Update to Marlowe 3.0 (#8)

.github/workflows/ruby.yml

@@ -1,76 +1,55 @@
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
-# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
-
-name: Ruby
+name: Ruby CI
 
 on:
-  push:
-    branches: [master]
   pull_request:
-    branches: [master]
+  push:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
 
 jobs:
-  test:
+  ruby-ci:
+    name: Ruby ${{ matrix.ruby }} - ${{ matrix.os }}
+
     strategy:
+      fail-fast: true
       matrix:
         os:
-          - ubuntu
-          - macos
-          - windows
+          - ubuntu-20.04
         ruby:
-          - '2.6'
           - '2.7'
           - '3.0'
+          - '3.1'
           - head
-          - debug
-          - mingw
-          - mswin
           - jruby
           - jruby-head
           - truffleruby
           - truffleruby-head
-        exclude:
-          - os: macos
-            ruby: mingw
-          - os: macos
-            ruby: mswin
-          - os: ubuntu
-            ruby: mingw
-          - os: ubuntu
-            ruby: mswin
-          - os: windows
-            ruby: debug
-          - os: windows
-            ruby: jruby
-          - os: windows
-            ruby: jruby-head
-          - os: windows
-            ruby: truffleruby
-          - os: windows
-            ruby: truffleruby-head
-    runs-on: ${{ matrix.os }}-latest
-    continue-on-error: ${{
-      startsWith(matrix.ruby, 'truffle') ||
-      matrix.ruby == 'debug' ||
-      endsWith(matrix.ruby, 'head') ||
-      (startsWith(matrix.ruby, 'jruby') && matrix.os == 'windows')
-      }}
+          - truffleruby+graalvm
+          - truffleruby+graalvm-head
+        include:
+          - ruby: head
+            continue-on-error: true
+          - ruby: jruby-head
+            continue-on-error: true
+          - os: ubuntu-22.04
+            ruby: head
+          - os: ubuntu-22.04
+            ruby: '3.1'
+
+    runs-on: ${{ matrix.os }}
+
+    continue-on-error: ${{ matrix.continue-on-error || false }}
+
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
-      - name: Install dependencies
-        run: bundle install
-      - name: Install appraisals
-        run: bundle exec ruby -S appraisal install
-      - name: Run tests
-        run: bundle exec ruby -S rake test
-      - name: Run appraisals
-        run: bundle exec ruby -S appraisal rake test
+
+      - run: bundle exec ruby -S rake test --trace
+      - run: bundle exec ruby -S appraisal install
+      - run: bundle exec ruby -S appraisal rake test
+      - run: bundle exec standardrb

Appraisals

@@ -1,7 +1,15 @@
-appraise "rack-1.6" do
+# frozen_string_literal: true
+
+appraise "rack-1" do
   gem "rack", "~> 1.6"
+  gem "rack-test", "~> 1.0"
 end
 
 appraise "rack-2" do
   gem "rack", "~> 2.0"
+  gem "rack-test", "~> 1.0"
+end
+
+appraise "rack-3" do
+  gem "rack", "~> 3.0"
 end

Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # -*- ruby -*-
 
 # NOTE: This file is present to keep Travis CI happy. Edits to it will not

History.md

@@ -1,3 +1,10 @@
+### 3.0 / 2022-09-11
+
+- Added a Faraday request middleware.
+- Replaced Hurley example with examples for the use of the Faraday
+  middleware.
+- Added global Marlowe configuration.
+
 ### 2.1 / 2021-09-08
 
 - Allow the use of Ruby 3.

Licence.md

@@ -2,26 +2,24 @@
 
 This software is available under an MIT-style licence.
 
-*   Copyright 2015–2016 Kinetic Cafe
+- Copyright 2015–2022 Kinetic Cafe
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in
 the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
-of the Software, and to permit persons to whom the Software is furnished to do
-so, subject to the following conditions:
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
 
-*   The names of its contributors may not be used to endorse or promote
-    products derived from this software without specific prior written
-    permission.
+- The names of its contributors may not be used to endorse or promote products
+  derived from this software without specific prior written permission.
 
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Manifest.txt

@@ -1,13 +1,18 @@
+.github/workflows/ruby.yml
+.standard.yml
 Contributing.md
 History.md
 Licence.md
 Manifest.txt
 README.rdoc
 Rakefile
 lib/marlowe.rb
+lib/marlowe/config.rb
+lib/marlowe/faraday.rb
 lib/marlowe/formatter.rb
 lib/marlowe/middleware.rb
 lib/marlowe/rails.rb
 lib/marlowe/simple_formatter.rb
 test/minitest_config.rb
 test/test_marlowe.rb
+test/test_marlowe_config.rb

README.rdoc

@@ -14,7 +14,41 @@ correlation across multiple services.
 When using Rails, Marlowe automatically adds itself to the middleware before
 <tt>Rails::Rack::Logger</tt>.
 
-=== Upgrading from Marlowe 1.x
+As of Marlowe 3.0, a Faraday middleware is provided (<tt>require 'marlowe/faraday'</tt>).
+
+=== Upgrading
+
+==== from Marlowe 2.0
+
+In Marlowe 2.0, configuration was entirely specified in Rails configuration or
+in the Rack +use+ clause. With the addition of a Faraday middleware for use with
+Marlowe, centralization of the configuration is advisable.
+
+The existing configuration mechanisms will work (and create instance
+configurations if provided), but it is instead recommended to use the global
+configuration:
+
+  # Compatibility with Marlowe 1.0
+  Marlowe.configure do |config|
+    config.header = 'Correlation-ID'
+    config.handler = :simple
+    config.return = false
+  end
+
+Configuration is static for Marlowe::Middleware or Marlowe::Faraday instances
+and changes to Marlowe configuration only affect *new* instances. If the
+configuration options are provided in the middleware +use+ clause, they will
+override the configured values.
+
+  Marlowe.configure do |config|
+    config.header = 'Correlation-ID'
+    config.handler = :simple
+    config.return = false
+  end
+  use Marlowe::Middleware, handler: :clean
+  # The handler will be the :clean handler for the used middleware.
+
+==== from Marlowe 1.x
 
 In Marlowe 1.0, the correlation header was called <tt>Correlation-Id</tt>;
 since then, Rails 5 and other tools and frameworks (such as Phoenix) have
@@ -109,7 +143,7 @@ The correlation id can be accessed throughout the application by accessing the
 
 For a Rails application, you simply need to change the log formatter to one of
 the provided ones. Correlated versions of both the SimpleFormatter and
-Formatter are included. 
+Formatter are included.
 
   # config/environments/development.rb
   Rails.application.configure do
@@ -134,7 +168,7 @@ As {lograge}[https://github.com/roidrage/lograge] supplies its own formatter,
 you will need to do something a little different:
 
   # config/application.rb
-  
+
   class Application < Rails::Application
     config.before_initialize do
       ...
@@ -146,47 +180,39 @@ you will need to do something a little different:
     end
   end
 
-== Clients
-
-Catching and creating the correlation ID is a great all on its own, but to
-really take advantage of the correlation in a service based architecture you'll
-need to pass the request ID to the next service in the change.
-
-Here's an example of a {Hurley}[https://github.com/lostisland/hurley] client:
+=== SemanticLogger
 
-  # lib/correlated_client.rb
+As {semantic_logger}[https://github.com/rocketjob/semantic_logger] provides its
+own formatters this should be added as a tag. The best way that I can see to do
+this is to capture the +correlation_id+ in an +on_log+ event:
 
-  require 'hurley'
-  require 'request_store'
+  # config/initializers/semantic_logger.rb
 
-  class Hurley::CorrelatedClient < Hurley::Client
-    def initialize(*args, &block)
-      super
-      header['X-Request-Id'] = ::RequestStore.store[:correlation_id]
+  SemanticLogger.on_log do |log|
+    if RequestStore[:correlation_id]
+      log.named_tags[:correlation_id] = RequestStore[:correlation_id]
     end
   end
 
-If you have long-lived Hurley clients, it is also possible to use the Hurley
-{callback machanism}[https://github.com/lostisland/hurley#client-callbacks] to
-add the outgoing headers:
+== Clients
 
-  client.before_call do |request|
-    request.header['X-Request-Id'] = ::RequestStore.store[:correlation_id]
-  end
+Catching and creating the correlation ID is a great all on its own, but to
+really take advantage of the correlation in a service based architecture you'll
+need to pass the request ID to the next service in the change.
 
-or 
-
-  class Correlator
-    def name
-      :correlator
-    end
+Here's an example with {Faraday}[https://github.com/lostisland/faraday]:
 
-    def call(request)
-      request.header['X-Request-Id'] = ::RequestStore.store[:correlation_id]
-    end
-  end
+    require 'faraday'
+    require 'faraday_middleware'
+    require 'marlowe/faraday'
+
+    conn = Faraday.new(url: 'https://example.org/') do |conn|
+      conn.request :marlowe
+      conn.request :json
 
-  client.before_call(Correlator.new)
+      conn.response :json
+      conn.adapter Faraday.default_adapter
+    end
 
 == Install
 

Rakefile

@@ -23,7 +23,7 @@ spec = Hoe.spec "marlowe" do
   require_ruby_version ">= 2.0", "< 4"
 
   extra_deps << ["request_store", "~> 1.2"]
-  extra_deps << ["rack", ">= 0.9", "< 3"]
+  extra_deps << ["rack", ">= 1", "< 4"]
 
   extra_dev_deps << ["appraisal", "~> 2.1"]
   extra_dev_deps << ["hoe-doofus", "~> 1.0"]
@@ -35,7 +35,7 @@ spec = Hoe.spec "marlowe" do
   extra_dev_deps << ["minitest-bonus-assertions", "~> 3.0"]
   extra_dev_deps << ["minitest-focus", "~> 1.1"]
   extra_dev_deps << ["minitest-moar", "~> 0.0"]
-  extra_dev_deps << ["rack-test", "~> 1.0"]
+  extra_dev_deps << ["rack-test", "~> 2.0"]
   extra_dev_deps << ["rake", ">= 10.0", "< 14"]
   extra_dev_deps << ["rdoc", ">= 4.2"]
   extra_dev_deps << ["standard", "~> 1.0"]
@@ -45,7 +45,7 @@ end
 
 ENV["RUBYOPT"] = "-W0"
 
-module Hoe::Publish #:nodoc:
+module Hoe::Publish # :nodoc:
   alias_method :__make_rdoc_cmd__marlowe__, :make_rdoc_cmd
 
   def make_rdoc_cmd(*extra_args) # :nodoc:

gemfiles/rack_1.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org/"
+
+gem "rack", "~> 1.6"
+gem "rack-test", "~> 1.0"
+
+gemspec path: "../"

gemfiles/rack_2.gemfile

@@ -3,5 +3,6 @@
 source "https://rubygems.org/"
 
 gem "rack", "~> 2.0"
+gem "rack-test", "~> 1.0"
 
 gemspec path: "../"

gemfiles/rack_1.6.gemfile → gemfiles/rack_3.gemfile

@@ -2,6 +2,6 @@
 
 source "https://rubygems.org/"
 
-gem "rack", "~> 1.6"
+gem "rack", "~> 3.0"
 
 gemspec path: "../"