marlowe 1.0.3 → 3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e8fe217abd7b34e70a4816265d375e11a9200421
-  data.tar.gz: 036330895f4d6518ebcccfc63eaee3b806a0556a
+SHA256:
+  metadata.gz: 5a38beee250c02c545fa9a16e99a7e32702f4e027e2d9b87bfee4911210d6f7e
+  data.tar.gz: 3c4b0d3dddec1f5706076a36036fe1b1fcc26a4a662a7ce134fc4e7df7fa5579
 SHA512:
-  metadata.gz: 9c17b2a005ef985a3c8303911c921ffb32f898595855ad74ea90c1c182b658f86e352876c5f92f95da82294898789cc92e1bc04064616e7d2130d597c3f222ef
-  data.tar.gz: c748d8e49920eef7aa26e74ab90d824c43d2c258392dcb58e17a6a54afae500f29ac9922fd100f92dbea45b9fbbde84be0813c3dffec7a0a92f2c6f19461e738
+  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/Contributing.md

@@ -0,0 +1,71 @@
+## Contributing
+
+We value any contribution to Marlowe you can provide: a bug report,
+a feature request, or code contributions. Marlowe is reasonably complex
+code, so there are a few contribution guidelines:
+
+*   Changes *will not* be accepted without tests. The test suite is written
+    with [Minitest][].
+*   Match our coding style.
+*   Use a thoughtfully-named topic branch that contains your change. Rebase
+    your commits into logical chunks as necessary.
+*   Use [quality commit messages][].
+*   Do not change the version number; when your patch is accepted and a release
+    is made, the version will be updated at that point.
+*   Submit a GitHub pull request with your changes.
+
+### Test Dependencies
+
+Marlowe uses Ryan Davis’s [Hoe][] to manage the release process, which
+adds a number of rake tasks. You will mostly be interested in:
+
+    $ rake
+
+which runs the tests the same way that:
+
+    $ rake test
+    $ rake travis
+
+will do.
+
+To assist with the installation of the development dependencies for
+Marlowe, I have provided the simplest possible Gemfile pointing to the
+(generated) `marlowe.gemspec` file. This will permit you to do:
+
+    $ bundle install
+
+to get the development dependencies. If you aleady have `hoe` installed, you
+can accomplish the same thing with:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs, and
+generate the RDoc.
+
+### Workflow
+
+Here's the most direct way to get your work merged into the project:
+
+*   Fork the project.
+*   Clone down your fork (`git clone
+    git://github.com/KineticCafe/marlowe.git`).
+*   Create a topic branch to contain your change (`git checkout -b
+    my_awesome_feature`).
+*   Hack away, add tests. Not necessarily in that order.
+*   Make sure everything still passes by running `rake`.
+*   If necessary, rebase your commits into logical chunks, without errors.
+*   Push the branch up (`git push origin my_awesome_feature`).
+*   Create a pull request against KineticCafe/marlowe and describe
+    what your change does and the why you think it should be merged.
+
+### Contributors
+
+*   Trevor Oke [@thefury](https://github.com/thefury) created marlowe.
+*   Austin Ziegler [@halostatue](https://github.com/halostatue)
+*   Adam Solove [@asolove](https://github.com/asolove)
+*   Tim Morton [@tmorton](https://github.com/tmorton)
+
+[Minitest]: https://github.com/seattlerb/minitest
+[quality commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[Hoe]: https://github.com/seattlerb/hoe
+[kccoc]: https://github.com/KineticCafe/code-of-conduct

data/History.md

@@ -0,0 +1,43 @@
+### 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.
+- Switch to standardruby instead of rubocop.
+- Switch from Travis to Github Actions.
+
+### 2.0 / 2016-11-16
+
+- Breaking change: the correlation header defaults to `X-Request-Id` instead of
+  `Correlation-Id`.
+- Breaking change: by default, the `correlation_id` is sanitized in the same
+  way as `ActionDispatch::RequestId` when provided from an upstream source (only
+  alphanumerics with dashes up to 255 characters in length).
+- Breaking change: by default, the `correlation_id` is returned to the client as
+  part of the response.
+- Marlowe is more configurable now.
+
+### 1.0.3 / 2016-01-15
+
+- Update Readme example of using available formatted subclass.
+- Make the correlation header name configurable
+
+### 1.0.2 / 2015-11-24
+
+- Add documentation for using Marlowe with [lograge][].
+
+### 1.0.1 / 2015-10-20
+
+- Update gemspec with homepage
+- Update Rakefile
+
+### 1.0.0 / 2015-10-16
+
+- Initial Commit
+
+[lograge]: https://github.com/roidrage/lograge

data/Licence.md

@@ -0,0 +1,25 @@
+## Licence
+
+This software is available under an MIT-style licence.
+
+- 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:
+
+- 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.

data/Manifest.txt

@@ -1,14 +1,18 @@
-.autotest
-Gemfile
-History.rdoc
-Licence.rdoc
+.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

data/README.rdoc

@@ -1,37 +1,138 @@
-= marlowe
+= Marlowe, Your Request Sleuth
+
+code :: https://github.com/KineticCafe/marlowe/
+issues :: https://github.com/KineticCafe/marlowe/issues
+docs :: http://www.rubydoc.info/github/KineticCafe/marlowe/master
+continuous integration :: {<img src="https://travis-ci.org/KineticCafe/marlowe.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/KineticCafe/marlowe]
 
 == Description
 
-{marlowe}[https://github.com/KineticCafe/marlowe] provides a correlation id 
-header for Rails and Rack applications to correlate logs for a single request 
-across multiple services.
+{Marlowe}[https://github.com/KineticCafe/marlowe] is a Rack middleware that
+extracts or creates a request ID using a pre-defined header, permitting request
+correlation across multiple services.
 
-== Install
+When using Rails, Marlowe automatically adds itself to the middleware before
+<tt>Rails::Rack::Logger</tt>.
 
-You can install it as a gem:
+As of Marlowe 3.0, a Faraday middleware is provided (<tt>require 'marlowe/faraday'</tt>).
 
-  $ gem install marlowe
+=== 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
 
-or add it into a Gemfile:
+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
+standardized on the header <tt>X-Request-Id</tt>. Marlowe 2.0 changes to this
+header by default.
 
-  gem 'marlowe'
+To keep complete compatibility with Marlowe 1.0, the following should be used:
+
+  # Rails
+  config.marlowe_header = 'Correlation-Id'
+  config.marlowe_handler = :simple
+  config.marlowe_return = false
+
+  # Rack
+  use Marlowe::Middleware, header: 'Correlation-Id', handler: :simple, return: false
 
 == Configuration
 
-To configure the header where Marlowe looks for and puts the correlation id:
+Marlowe has three main configuration options: the request ID header, the
+request ID handler, and the request ID return. The options may be provided to
+the Rack +use+ command as a keyword option, or set in a corresponding
+<tt>marlowe_<em>option</em></tt> configuration variable in Rails.
+
+=== Request ID Header
+
+Specifies the header to be used for the request correlation ID. Defaults to
+<tt>X-Request-Id</tt>.
+
+    # Rails
+    config.marlowe_header = 'Correlation-Id'
+    # OR: config.marlowe_correlation_header = 'Correlation-Id'
+
+    # Rack
+    use Marlowe::Middleware, header: 'Correlation-Id'
+    # OR: use Marlowe::Middleware, correlation_header: 'Correlation-Id'
+
+Marlowe will convert this to an appropriate HTTP header (in the Rack +env+
+parameter, the above header would be represented as
+<tt>env['HTTP_CORRELATION_ID']</tt>).
+
+=== Request ID Handler
+
+Specifies the method for sanitizing or generating the request correlation ID.
+Values can be <tt>:clean</tt> (the default, which limits incoming correlation
+IDs to 255 alphanumeric-or-dash characters), <tt>:simple</tt> (does not limit
+incoming correlation IDs), or a proc to transform or generate a correlation ID.
+
+In all cases, if a correlation request ID is not handled, a UUID will be
+generated.
+
+    # Rails
+    config.marlowe_handler = :simple
+    config.marlowe_handler = ->(req_id) {
+      req_id.try(:reverse) || SecureRandom.uuid
+    }
 
-- In Rails, specify the header in your environment configuration:
+    # Rack
+    use Marlowe::Middleware, handler: :simple
+    use Marlowe::Middleware, handler: ->(req_id) {
+      req_id.try(:reverse) || SecureRandom.uuid
+    }
 
-  config.marlowe_correlation_header = "My-Correlation-Id"
+=== Request ID Return
 
-- If you are adding the middleware to a Rack application directly, pass it as an option:
+If +true+ (the default), the request correlation ID will be returned to the
+client in the same header that it was provided in.
 
-  use Marlowe::Middleware, correlation_header: "My-Correlation-Id"
+    # Rails
+    config.marlowe_return = false
 
-(Note that HTTP headers are case insensitive. In the Rack `env`, this header name is actually
-represented as `env['HTTP_MY_CORRELATION_ID']`.)
+    # Rack
+    use Marlowe::Middleware, return: false
 
-== Accesing the Correlation ID
+=== Using Marlowe with Rails 5
+
+Rails 5 includes the <tt>ActionDispatch::RequestId</tt> middleware, reducing
+the need for Marlowe. Marlowe is more configurable than the Rails 5 default, so
+set +marlowe_replace_action_dispatch_request_id+ to true to have
+<tt>Marlowe::Middleware</tt> will replace <tt>ActionDispatch::RequestId</tt>:
+
+  # Rails only
+  config.marlowe_replace_action_dispatch_request_id = true
+
+== Accessing the Correlation ID
 
 The correlation id can be accessed throughout the application by accessing the
 {RequestStore}[https://github.com/steveklabnik/request_store] storage.
@@ -40,16 +141,15 @@ The correlation id can be accessed throughout the application by accessing the
 
 == Logging
 
-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. 
+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.
 
   # config/environments/development.rb
   Rails.application.configure do
     config.log_formatter = Marlowe::SimpleFormatter.new
   end
 
-
 To create your own formatter, you'll need to access the RequestStore storage.
 You can use this pattern if you've rolled your own logger/formatter:
 
@@ -64,11 +164,11 @@ You can use this pattern if you've rolled your own logger/formatter:
 
 === Lograge
 
-As {lograge}[https://github.com/roidrage/lograge] supplies it's own formatter,
+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
       ...
@@ -80,46 +180,64 @@ you will need to do something a little different:
     end
   end
 
+=== SemanticLogger
+
+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:
+
+  # config/initializers/semantic_logger.rb
+
+  SemanticLogger.on_log do |log|
+    if RequestStore[:correlation_id]
+      log.named_tags[:correlation_id] = RequestStore[:correlation_id]
+    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 id to the next service in the change.
+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:
+Here's an example with {Faraday}[https://github.com/lostisland/faraday]:
 
-  # lib/correlated_client.rb
+    require 'faraday'
+    require 'faraday_middleware'
+    require 'marlowe/faraday'
 
-  require 'hurley'
-  require 'request_store'
+    conn = Faraday.new(url: 'https://example.org/') do |conn|
+      conn.request :marlowe
+      conn.request :json
 
-  class Hurley::CorrelatedClient < Hurley::Client
-    def initialize(*args, &block)
-      super
-      header['Correlation-Id'] = ::RequestStore.store[:correlation_id]
+      conn.response :json
+      conn.adapter Faraday.default_adapter
     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:
+== Install
 
-  client.before_call do |request|
-    request.header['Correlation-Id'] = ::RequestStore.store[:correlation_id]
-  end
+Add Marlowe to your Gemfile:
 
-or 
-  
-  class Correlator
-    def name
-      :correlator
-    end
+    gem 'marlowe', '~> 2.0'
 
-    def call(request)
-      request.header['Correlation-Id'] = ::RequestStore.store[:correlation_id]
-    end
-  end
+Or manually install:
+
+  $ gem install marlowe
+
+== Marlowe Semantic Versioning
+
+Marlowe uses a {Semantic Versioning}[http://semver.org/] scheme with one
+significant change:
+
+* When PATCH is zero (+0+), it will be omitted from version references.
 
-  client.before_call(Correlator.new)
+Additionally, the major version will generally be reserved for plug-in
+infrastructure changes.
 
+== Community and Contributing
 
+Marlowe welcomes your contributions as described in
+{Contributing.md}[https://github.com/KineticCafe/marlowe/blob/master/Contributing.md].
+This project, like all Kinetic Cafe {open source
+projects}[https://github.com/KineticCafe], is under the Kinetic Cafe Open
+Source {Code of Conduct}[https://github.com/KineticCafe/code-of-conduct].

data/Rakefile

@@ -1,61 +1,68 @@
-# -*- ruby -*-
+# frozen_string_literal: true
 
-require 'rubygems'
-require 'hoe'
+require "rubygems"
+require "hoe"
+require "rake/clean"
 
 Hoe.plugin :doofus
-Hoe.plugin :email unless ENV['CI'] or ENV['TRAVIS']
+Hoe.plugin :email unless ENV["CI"]
 Hoe.plugin :gemspec2
 Hoe.plugin :git
 Hoe.plugin :minitest
 Hoe.plugin :rubygems
-Hoe.plugin :travis
-
-Hoe.spec 'marlowe' do
-  developer('Trevor Oke', 'toke@kineticcafe.com')
-  developer('Kinetic Cafe', 'dev@kineticcafe.com')
-
-  self.history_file = 'History.rdoc'
-  self.readme_file = 'README.rdoc'
-
-  license 'MIT'
-
-  extra_deps << ['request_store', '~> 1.2']
-  extra_deps << ['rack',  '>= 0.9', '< 2']
-
-  extra_dev_deps << ['rack-test', '~> 0.6']
-  self.extra_dev_deps << ['rake', '~> 10.0']
-  self.extra_dev_deps << ['hoe-doofus', '~> 1.0']
-  self.extra_dev_deps << ['hoe-gemspec2', '~> 1.1']
-  self.extra_dev_deps << ['hoe-git', '~> 1.5']
-  self.extra_dev_deps << ['hoe-travis', '~> 1.2']
-  self.extra_dev_deps << ['minitest', '~> 5.4']
-  self.extra_dev_deps << ['minitest-autotest', '~> 1.0']
-  self.extra_dev_deps << ['minitest-bisect', '~> 1.2']
-  self.extra_dev_deps << ['minitest-focus', '~> 1.1']
-  self.extra_dev_deps << ['minitest-moar', '~> 0.0']
-  self.extra_dev_deps << ['simplecov', '~> 0.7']
+
+spec = Hoe.spec "marlowe" do
+  developer("Trevor Oke", "toke@kineticcafe.com")
+  developer("Kinetic Cafe", "dev@kineticcafe.com")
+
+  self.history_file = "History.md"
+  self.readme_file = "README.rdoc"
+
+  license "MIT"
+
+  require_ruby_version ">= 2.0", "< 4"
+
+  extra_deps << ["request_store", "~> 1.2"]
+  extra_deps << ["rack", ">= 1", "< 4"]
+
+  extra_dev_deps << ["appraisal", "~> 2.1"]
+  extra_dev_deps << ["hoe-doofus", "~> 1.0"]
+  extra_dev_deps << ["hoe-gemspec2", "~> 1.1"]
+  extra_dev_deps << ["hoe-git", "~> 1.6"]
+  extra_dev_deps << ["hoe-rubygems", "~> 1.0"]
+  extra_dev_deps << ["minitest", "~> 5.4"]
+  extra_dev_deps << ["minitest-autotest", "~> 1.0"]
+  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", "~> 2.0"]
+  extra_dev_deps << ["rake", ">= 10.0", "< 14"]
+  extra_dev_deps << ["rdoc", ">= 4.2"]
+  extra_dev_deps << ["standard", "~> 1.0"]
+  extra_dev_deps << ["simplecov", "~> 0.21"]
+  extra_dev_deps << ["psych", "~> 3.1"]
 end
 
-module Hoe::Publish
-  alias_method :original_make_rdoc_cmd, :make_rdoc_cmd
+ENV["RUBYOPT"] = "-W0"
+
+module Hoe::Publish # :nodoc:
+  alias_method :__make_rdoc_cmd__marlowe__, :make_rdoc_cmd
 
   def make_rdoc_cmd(*extra_args) # :nodoc:
-    spec.extra_rdoc_files.reject! { |f| f == 'Manifest.txt' }
-    original_make_rdoc_cmd(*extra_args)
+    spec.extra_rdoc_files.reject! { |f| f == "Manifest.txt" }
+    __make_rdoc_cmd__marlowe__(*extra_args)
   end
 end
 
-namespace :test do
-  task :coverage do
-    prelude = <<-EOS
-require 'simplecov'
-SimpleCov.start('test_frameworks') { command_name 'Minitest' }
-gem 'minitest'
-    EOS
-    spec.test_prelude = prelude.split($/).join('; ')
-    Rake::Task['test'].execute
+if File.exist?(".simplecov-prelude.rb")
+  namespace :test do
+    task :coverage do
+      spec.test_prelude = 'load ".simplecov-prelude.rb"'
+      Rake::Task["test"].execute
+    end
+
+    CLOBBER << "coverage"
   end
 end
 
-# vim: syntax=ruby
+CLOBBER << "tmp"