marlowe 2.1 → 3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 942139256c91a7b04a4549271e176b8dab519dd566df088dc818198e8d285065
-  data.tar.gz: 00a699c0d9ce21ada8c453ea638a0f972f64307e7572be8aa3dca7629922f598
+  metadata.gz: 5a38beee250c02c545fa9a16e99a7e32702f4e027e2d9b87bfee4911210d6f7e
+  data.tar.gz: 3c4b0d3dddec1f5706076a36036fe1b1fcc26a4a662a7ce134fc4e7df7fa5579
 SHA512:
-  metadata.gz: 6dfa8bd46ddc990b643db1d01925da2a694fba37466c4dfacaab2dd36c776aa8f6f26e8fa64b5e35f5e52d91095e8ad1cf368a382f5c2188defc62596be1a63d
-  data.tar.gz: ee94d6e57c9dc02ae7690977281dc9a62051465ef45330474aac3e2284f68d438099409736a32806ecff61da2f9191d8eaf9869300f48e6464c943ee6caf608a
+  metadata.gz: 1adb8585c41f04ae645af9080f97ae115d2977ed1e0fa0d2bace7b6b896b6dc3e9c10fca4938a40dcd7727a98a552312be9a514e883d48a0dd9058986b7b85ac
+  data.tar.gz: 80bfa345158bcf410251861067b071bbef0362cccac7866c50febbf6b9db557498a6b561aed47b1e62ea0de5988d15a510c896ceca017cc8193c386b1f0a5cdd

data/.github/workflows/ruby.yml

@@ -0,0 +1,55 @@
+name: Ruby CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+jobs:
+  ruby-ci:
+    name: Ruby ${{ matrix.ruby }} - ${{ matrix.os }}
+
+    strategy:
+      fail-fast: true
+      matrix:
+        os:
+          - ubuntu-20.04
+        ruby:
+          - '2.7'
+          - '3.0'
+          - '3.1'
+          - head
+          - jruby
+          - jruby-head
+          - truffleruby
+          - truffleruby-head
+          - 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@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - 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

data/.standard.yml

@@ -0,0 +1,4 @@
+parallel: true
+ruby_version: 2.7
+ignore:
+  - 'marlowe.gemspec'

data/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.

data/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.

data/Manifest.txt

@@ -1,3 +1,5 @@
+.github/workflows/ruby.yml
+.standard.yml
 Contributing.md
 History.md
 Licence.md
@@ -5,9 +7,12 @@ 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

data/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
 

data/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:

data/lib/marlowe/config.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Configuration object for Marlowe.
+class Marlowe::Config
+  # The name of the default header to look for and put the correlation id in.
+  CORRELATION_HEADER = "X-Request-Id" # :nodoc:
+
+  class << self
+    # The global Marlowe configuration.
+    def global
+      @global ||= new
+    end
+
+    # Override the global Marlowe configuration.
+    def override(opts)
+      new(global, opts)
+    end
+
+    def configure(&block) # :nodoc:
+      @global = new(global, &block)
+    end
+
+    private
+
+    def clear_global!
+      @global = nil
+    end
+  end
+
+  # The name of the header to inspect. Defaults to 'X-Request-Id'.
+  attr_accessor :header
+  # The HTTP formatted version of the header name to inspect. Defaults to
+  # 'HTTP_X_REQUEST_ID'.
+  attr_reader :http_header
+  # The handler for request correlation IDs. Defaults to sanitizing provided
+  # request IDs or generating a UUID. If <tt>:simple</tt> is provided, provided
+  # request IDs will not be sanitized. A callable (expecting a single input of
+  # any possible existing request ID) may be provided to introduce more complex
+  # request ID handling.
+  attr_accessor :handler
+  # If +true+ (the default), the request correlation ID will be returned as
+  # part of the response headers. Only affects Marlowe::Middleware.
+  attr_accessor :return
+  # If +true+, Marlowe will add code to behave like
+  # <tt>ActionDispatch::RequestId</tt>. Depends on
+  # <tt>ActionDispatch::Request</tt>. Only affects Marlowe::Middleware.
+  attr_accessor :action_dispatch
+
+  # === Option Values
+  #
+  # <tt>:header</tt>:: The name of the header to inspect. Defaults to
+  #                    'X-Request-Id'. Also available as
+  #                    <tt>:correlation_header</tt>.
+  # <tt>:handler</tt>:: The handler for request correlation IDs. Defaults to
+  #                     sanitizing provided request IDs or generating a UUID.
+  #                     If <tt>:simple</tt> is provided, provided request IDs
+  #                     will not be sanitized. A callable (expecting a single
+  #                     input of any possible existing request ID) may be
+  #                     provided to introduce more complex request ID
+  #                     handling.
+  # <tt>:return</tt>:: If +true+ (the default), the request correlation ID
+  #                    will be returned as part of the response headers.
+  # <tt>:action_dispatch</tt>:: If +true+, Marlowe will add code to behave
+  #                             like <tt>ActionDispatch::RequestId</tt>.
+  #                             Depends on <tt>ActionDispatch::Request</tt>.
+  def initialize(base = nil, opts = nil) # :yields: self
+    opts =
+      if base.nil? && opts.nil?
+        {}
+      elsif base.nil? && opts.is_a?(Hash)
+        opts
+      elsif base.is_a?(Hash) && opts.nil?
+        base
+      elsif base.is_a?(self.class) && opts.nil?
+        base.to_hash
+      elsif (base.is_a?(Hash) || base.is_a?(self.class)) && opts.is_a?(Hash)
+        hash =
+          if base.is_a?(self.class)
+            base.to_hash
+          else
+            base
+          end
+        hash.update(opts)
+      end
+
+    @header, @http_header = format_header_name(
+      opts[:header] || opts[:correlation_header] || CORRELATION_HEADER
+    )
+
+    @handler = opts.fetch(:handler, :clean)
+    @return = opts.fetch(:return, true)
+    @action_dispatch = opts.fetch(:action_dispatch, false)
+
+    yield self if block_given?
+
+    freeze
+  end
+
+  def to_hash
+    {
+      header: header,
+      handler: handler,
+      return: self.return,
+      action_dispatch: action_dispatch
+    }
+  end
+
+  private
+
+  def format_header_name(header)
+    [
+      header.to_s.tr("_", "-").freeze,
+      "HTTP_#{header.to_s.tr("-", "_").upcase}"
+    ]
+  end
+end

data/lib/marlowe/faraday.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "marlowe"
+
+# Marlowe correlation ID middleware for Faraday. Including this into your
+# request middleware stack will use the captured correlation ID.
+class Marlowe::Faraday < Faraday::Middleware
+  def initialize(app, opts = {})
+    super(app)
+    @config = Marlowe::Config.override(opts)
+  end
+
+  def call(env)
+    env[:request_headers][@config.header] =
+      Marlowe.make_request_id(RequestStore[:correlation_id], @config)
+    @app.call(env)
+  end
+end
+
+Faraday::Request.register_middleware marlowe: -> { Marlowe::Faraday }

data/lib/marlowe/middleware.rb

@@ -6,11 +6,11 @@ require "securerandom"
 
 module Marlowe
   # Marlowe correlation id middleware. Including this into your middleware
-  # stack will add a correlation id header as an incoming request, and save
-  # that id in a request session variable.
+  # stack will capture or add a correlation id header on an incoming request,
+  # and save that id in a request session variable.
   class Middleware
     # The name of the default header to look for and put the correlation id in.
-    CORRELATION_HEADER = "X-Request-Id" #:nodoc:
+    CORRELATION_HEADER = Marlowe::Config::CORRELATION_HEADER # :nodoc:
 
     # Configure the Marlowe middleware to call +app+ with options +opts+.
     #
@@ -31,67 +31,36 @@ module Marlowe
     # <tt>:action_dispatch</tt>:: If +true+, Marlowe will add code to behave
     #                             like <tt>ActionDispatch::RequestId</tt>.
     #                             Depends on <tt>ActionDispatch::Request</tt>.
-    def initialize(app, opts = {})
+    def initialize(app, opts = nil)
       @app = app
-      @header, @http_header = format_header_name(
-        opts[:header] || opts[:correlation_header] || CORRELATION_HEADER
-      )
-      @handler = opts.fetch(:handler, :clean)
-      @return = opts.fetch(:return, true)
-      @action_dispatch = opts.fetch(:action_dispatch, false)
+      @config = Marlowe::Config.override(opts)
     end
 
     # Stores the incoming correlation id from the +env+ hash. If the correlation
     # id has not been sent, a new UUID is generated and the +env+ is modified.
     def call(env)
-      req_id = make_request_id(env[@http_header])
-      RequestStore.store[:correlation_id] = env[@http_header] = req_id
+      req_id = Marlowe.make_request_id(env[config.http_header], config)
+      RequestStore.store[:correlation_id] = env[config.http_header] = req_id
 
-      if @action_dispatch
+      if config.action_dispatch
         req = ActionDispatch::Request.new(env)
         req.request_id = req_id
       end
 
-      @app.call(env).tap { |_status, headers, _body|
-        if @return
-          headers[@header] = if @action_dispatch
-            req.request_id
-          else
-            RequestStore.store[:correlation_id]
-          end
+      app.call(env).tap { |_status, headers, _body|
+        if config.return
+          headers[config.header] =
+            if config.action_dispatch
+              req.request_id
+            else
+              RequestStore.store[:correlation_id]
+            end
         end
       }
     end
 
     private
 
-    def format_header_name(header)
-      [
-        header.to_s.tr("_", "-").freeze,
-        "HTTP_#{header.to_s.tr("-", "_").upcase}"
-      ]
-    end
-
-    def make_request_id(request_id)
-      if @handler == :simple
-        simple(request_id)
-      elsif @handler.is_a?(Proc)
-        simple(@handler.call(request_id))
-      else
-        clean(request_id)
-      end
-    end
-
-    def clean(request_id)
-      simple(request_id).gsub(/[^\w\-]/, "")[0, 255]
-    end
-
-    def simple(request_id)
-      if request_id && !request_id.empty? && request_id !~ /\A[[:space]]*\z/
-        request_id
-      else
-        SecureRandom.uuid
-      end
-    end
+    attr_reader :app, :config
   end
 end

data/lib/marlowe/rails.rb

@@ -6,23 +6,21 @@ module Marlowe
       config = app.config
 
       opts = {
-        header: config.try(:marlowe_header) || config.try(:marlowe_correlation_header),
-        handler: config.try(:marlowe_request_id_handler),
-        return: config.try(:marlowe_return_request_id),
-        action_dispatch: config.try(:marlowe_replace_action_dispatch_request_id)
+        header: config&.marlowe_header || config&.marlowe_correlation_header,
+        handler: config&.marlowe_request_id_handler,
+        return: config&.marlowe_return_request_id,
+        action_dispatch: config&.marlowe_replace_action_dispatch_request_id
       }.compact
 
       if opts[:action_dispatch]
-        app.middleware.insert_before ActionDispatch::RequestId,
-          Marlowe::Middleware, opts
+        app.middleware.insert_before ActionDispatch::RequestId, Marlowe::Middleware, opts
         app.middleware.delete ActionDispatch::RequestId
       else
-        app.middleware.insert_before Rails::Rack::Logger, Marlowe::Middleware,
-          opts
+        app.middleware.insert_before Rails::Rack::Logger, Marlowe::Middleware, opts
       end
     end
 
-    def app #:nodoc:
+    def app # :nodoc:
       Rails.application
     end
   end

data/lib/marlowe/simple_formatter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "request_store"
 
 module Marlowe

data/lib/marlowe.rb

@@ -2,11 +2,44 @@
 
 # Marlowe, a correlation id injector.
 module Marlowe
-  VERSION = "2.1" #:nodoc:
+  VERSION = "3.0" # :nodoc:
 
+  require "marlowe/config"
   require "marlowe/middleware"
   require "marlowe/rails" if defined? Rails::Railtie
 
   autoload :Formatter, "marlowe/formatter"
   autoload :SimpleFormatter, "marlowe/simple_formatter"
+
+  class << self
+    # Configure Marlowe
+    def configure(&block)
+      Marlowe::Config.configure(&block)
+    end
+
+    # Make a Marlowe request ID
+    def make_request_id(request_id, config = Marlowe::Config.global)
+      if config.handler == :simple
+        simple(request_id)
+      elsif config.handler.is_a?(Proc)
+        simple(config.handler.call(request_id))
+      else
+        clean(request_id)
+      end
+    end
+
+    private
+
+    def clean(request_id)
+      simple(request_id).gsub(/[^\w\-]/, "")[0, 255]
+    end
+
+    def simple(request_id)
+      if request_id && !request_id.empty? && request_id !~ /\A[[:space]]*\z/
+        request_id
+      else
+        SecureRandom.uuid
+      end
+    end
+  end
 end

data/test/test_marlowe.rb

@@ -9,6 +9,7 @@ class TestMarlowe < Minitest::Test
 
   def setup
     @marlowe_options = {}
+    Marlowe::Config.send(:clear_global!)
   end
 
   def app
@@ -85,7 +86,7 @@ class TestMarlowe < Minitest::Test
   end
 
   def test_handler_config_with_proc_handler_returning_nil
-    marlowe_options[:handler] = ->(item) {}
+    marlowe_options[:handler] = ->(_item) {}
     get "/", {}, {"HTTP_X_REQUEST_ID" => "test+value"}
     assert last_response.header.key?("X-Request-Id")
     refute_empty last_response.header["X-Request-Id"]

data/test/test_marlowe_config.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "minitest_config"
+
+class TestMarloweConfig < Minitest::Test
+  include Rack::Test::Methods
+
+  attr_reader :marlowe_options
+
+  def setup
+    @marlowe_options = {}
+    Marlowe::Config.send(:clear_global!)
+  end
+
+  def app
+    Marlowe.configure do |config|
+      marlowe_options.each do |k, v|
+        config.send(:"#{k}=", v) if config.respond_to?(:"#{k}=")
+      end
+    end
+
+    options = marlowe_options
+    Rack::Builder.new do
+      use Marlowe::Middleware, options
+
+      run lambda { |_env|
+        [
+          200,
+          {"Content-Type" => "text/plain"},
+          [RequestStore[:correlation_id]]
+        ]
+      }
+    end
+  end
+
+  def test_default_config_no_header_value
+    get "/"
+    assert last_response.header.key?("X-Request-Id")
+    refute_empty last_response.header["X-Request-Id"]
+    assert_equal last_response.header["X-Request-Id"], last_response.body
+  end
+
+  def test_default_config_with_header_value
+    get "/", {}, {"HTTP_X_REQUEST_ID" => "testvalue"}
+    assert last_response.header.key?("X-Request-Id")
+    refute_empty last_response.header["X-Request-Id"]
+    assert_equal last_response.header["X-Request-Id"], last_response.body
+    assert_equal "testvalue", last_response.header["X-Request-Id"]
+  end
+
+  def test_header_config_no_header_value
+    marlowe_options[:header] = "Correlation-Id"
+    get "/"
+    assert last_response.header.key?("Correlation-Id")
+    refute_empty last_response.header["Correlation-Id"]
+    assert_equal last_response.header["Correlation-Id"], last_response.body
+  end
+
+  def test_header_config_no_header_with_header_value
+    marlowe_options[:header] = "Correlation-Id"
+    get "/", {}, {"HTTP_CORRELATION_ID" => "testvalue"}
+    assert last_response.header.key?("Correlation-Id")
+    refute_empty last_response.header["Correlation-Id"]
+    assert_equal last_response.header["Correlation-Id"], last_response.body
+    assert_equal "testvalue", last_response.header["Correlation-Id"]
+  end
+
+  def test_handler_config_default_handler
+    get "/", {}, {"HTTP_X_REQUEST_ID" => "test+value"}
+    assert last_response.header.key?("X-Request-Id")
+    refute_empty last_response.header["X-Request-Id"]
+    assert_equal last_response.header["X-Request-Id"], last_response.body
+    assert_equal "testvalue", last_response.header["X-Request-Id"]
+  end
+
+  def test_handler_config_with_simple_handler
+    marlowe_options[:handler] = :simple
+    get "/", {}, {"HTTP_X_REQUEST_ID" => "test+value"}
+    assert last_response.header.key?("X-Request-Id")
+    refute_empty last_response.header["X-Request-Id"]
+    assert_equal last_response.header["X-Request-Id"], last_response.body
+    assert_equal "test+value", last_response.header["X-Request-Id"]
+  end
+
+  def test_handler_config_with_proc_handler
+    marlowe_options[:handler] = ->(item) { item && item.reverse || SecureRandom.uuid }
+    get "/", {}, {"HTTP_X_REQUEST_ID" => "test+value"}
+    assert last_response.header.key?("X-Request-Id")
+    refute_empty last_response.header["X-Request-Id"]
+    assert_equal last_response.header["X-Request-Id"], last_response.body
+    assert_equal "eulav+tset", last_response.header["X-Request-Id"]
+  end
+
+  def test_handler_config_with_proc_handler_returning_nil
+    marlowe_options[:handler] = ->(_item) {}
+    get "/", {}, {"HTTP_X_REQUEST_ID" => "test+value"}
+    assert last_response.header.key?("X-Request-Id")
+    refute_empty last_response.header["X-Request-Id"]
+    assert_equal last_response.header["X-Request-Id"], last_response.body
+    assert_match(/\A[-\w]+\z/, last_response.header["X-Request-Id"])
+  end
+
+  def test_return_config_false
+    marlowe_options[:return] = false
+    get "/"
+    refute last_response.header.key?("X-Request-Id")
+    assert_equal RequestStore[:correlation_id], last_response.body
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: marlowe
 version: !ruby/object:Gem::Version
-  version: '2.1'
+  version: '3.0'
 platform: ruby
 authors:
 - Trevor Oke
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-09-09 00:00:00.000000000 Z
+date: 2022-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: request_store
@@ -31,34 +31,34 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.14'
+        version: '5.16'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.14'
+        version: '5.16'
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -191,14 +191,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -281,14 +281,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.23'
+        version: '3.25'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.23'
+        version: '3.25'
 description: |-
   {Marlowe}[https://github.com/KineticCafe/marlowe] is a Rack middleware that
   extracts or creates a request ID using a pre-defined header, permitting request
@@ -296,6 +296,8 @@ description: |-
 
   When using Rails, Marlowe automatically adds itself to the middleware before
   <tt>Rails::Rack::Logger</tt>.
+
+  As of Marlowe 3.0, a Faraday middleware is provided (<tt>require 'marlowe/faraday'</tt>).
 email:
 - toke@kineticcafe.com
 - dev@kineticcafe.com
@@ -308,6 +310,8 @@ extra_rdoc_files:
 - Manifest.txt
 - README.rdoc
 files:
+- ".github/workflows/ruby.yml"
+- ".standard.yml"
 - Contributing.md
 - History.md
 - Licence.md
@@ -315,12 +319,15 @@ files:
 - 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
 homepage: https://github.com/KineticCafe/marlowe/
 licenses:
 - MIT
@@ -347,7 +354,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: "{Marlowe}[https://github.com/KineticCafe/marlowe] is a Rack middleware that