coach 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d5d8146dab264d6d7e2f1177101b9f7f5c62f44840964fb9672b7de7d01fe20
-  data.tar.gz: '058153f00f46e7eac0d26eb7039af4624e9636954fd59999f9bcf419fe559abf'
+  metadata.gz: c085b582900931acb9b56a21ee03e9b8b1695e8b9e36c23b5286acb8cc949868
+  data.tar.gz: ab1dd0c12bfcbad8b93832649f96fa3699cc036d392129f4b6e1e8aca36bb72e
 SHA512:
-  metadata.gz: 04204eb3b4029928a706b5d9894984462698ee337ccdb3d96e224da1bfc8debf4970b1eb5ba0b8b8cd14960171b8e926d5369f12eea66fcd42ded4bad5de1738
-  data.tar.gz: a3db075dddeff6e111cdac3bdef7236e8d461fb86c9aa7b696dd15ffd2b8cb5db2b755c07f2465e51eeee5963461a5ae72985aa924e4d9a1340a18987f428391
+  metadata.gz: 94525ce01d5c1b0dc75314c47f2901bdd33946fbe63ae847bf0ce6f1a1099e57c1db72f1c146199d0f77462eca826f47d0784aa21eeab41fb8b30aee3aa3dc0c
+  data.tar.gz: ccd13d3dcb3623c01f6650ce6efb842c892663afaaffa30db8e8781380a8ffcdbc9be809b0d171c224d7c494448cabf7b38d9dae989af1a0c5256bee1a949758

data/.rubocop.yml

@@ -9,11 +9,16 @@ AllCops:
 Metrics/MethodLength:
   Max: 15
 
+# Even after some serious refactoring, the default of 15 can be hard to meet
+# if you favour saving intermediate state into well-named variables
+Metrics/AbcSize:
+  Max: 20
+
 Style/RescueStandardError:
   Exclude:
     - "*/**/*_spec.rb"
 
-Naming/UncommunicativeMethodParamName:
+Naming/MethodParameterName:
   AllowedNames:
     # These are the default allowed names, set by Rubocop
     - io

data/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 No unreleased changes.
 
+# 2.2.0 / 2019-01-08
+
+* [#68](https://github.com/gocardless/coach/pull/68) Add `coach` CLI and add
+  documentation to README
+
 # 2.1.0 / 2019-11-14
 
 * [#79](https://github.com/gocardless/coach/pull/79) RequestSerializer will now

data/README.md

@@ -334,6 +334,77 @@ class Tracking < Coach::Middleware
 end
 ```
 
+# Coach CLI
+
+As well as the library, the Coach gem comes with a command line tool - `coach`.
+
+When working in a large codebase that uses Coach, one of the challenges you may run into
+is understanding the `provide`/`require` graph made up of all the middleware chains you've
+built. While the library enforces the correctness of those chains at boot time, it doesn't
+help you understand those dependencies. That's where the `coach` CLI comes in!
+
+Currently, the `coach` CLI supports two commands.
+
+## `find-provider`
+
+`find-provider` is the simpler of the two commands. Given the name of a Coach middleware
+and a value that it requires, it outputs the name of the middleware that provides it.
+
+```bash
+$ bundle exec coach find-provider HelloUser user
+Value `user` is provided to `HelloUser` by:
+
+Authentication
+```
+
+If there are multiple middlewares in the chain that provide the same value, all of them
+will be listed.
+
+## `find-chain`
+
+`find-chain` is the more advanced of the two commands, and is most useful in larger
+codebases. Given the name of a Coach middleware and a value it requires, it outputs the
+chains of middleware between the specified middleware and the one that provides the
+required value.
+
+```bash
+# Note that we've assumed an intermediate middleware - `UserDecorator` exists in this
+# example to make the functionality of the command clearer.
+$ bundle exec coach find-chain HelloUser user
+Value `user` is provided to `HelloUser` by:
+
+HelloUser -> UserDecorator -> Authentication
+```
+
+If there are multiple paths to a middleware that provides that value, all of them will be
+listed. Similarly, if multiple middlewares provide the same value, all of them will be
+listed.
+
+## Spring integration
+
+Given that the Coach CLI is mostly aimed at large Rails apps using Coach, it would be an
+oversight for us not to integrate it with [Spring](https://github.com/rails/spring/).
+
+To enable the use of Spring with the Coach CLI, add the following to `config/spring.rb` or
+an equivalent Rails config file.
+
+```ruby
+require "spring/commands/coach"
+```
+
+On GoCardless' main Rails app, using Spring reduces the time to run `coach` commands from
+around 15s to 1s.
+
+## Future work
+
+While we think the commands we've already built are useful, we do have some ideas to go
+further, including:
+
+  - Better formatting of provider chains
+  - Outputting DOT format files to visualise with Graphviz
+  - Editor integrations (e.g. showing the provider chains when hovering a `requires`
+    statement)
+
 # License & Contributing
 
 * Coach is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/bin/coach

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+
+require "slop"
+require "coach/cli/provider_finder"
+
+begin
+  require File.join(Dir.pwd, "config/environment")
+rescue LoadError
+  puts <<~EOS
+    Could not load your Rails app
+    =============================
+
+    Currently the coach CLI assumes you have a config/environment.rb file that
+    we can load. We believe this is true of Rails apps in general.
+
+    Please raise an issue if that's not the case!
+
+    https://github.com/gocardless/coach/issues
+  EOS
+  exit 1
+end
+
+Slop.parse do
+  command "find-provider" do
+    run do |_, args|
+      middleware_name, value_name = *args
+      raise ArgumentError, "middleware_name and value_name required" unless middleware_name && value_name
+
+      result = Coach::Cli::ProviderFinder.new(args[0], args[1]).find_provider
+
+      puts "Value `#{value_name}` is provided to `#{middleware_name}` by:\n\n"
+      puts result.to_a.join("\n")
+    end
+  end
+
+  command "find-chain" do
+    run do |_, args|
+      middleware_name, value_name = *args
+      raise ArgumentError, "middleware_name and value_name required" unless middleware_name && value_name
+
+      chains = Coach::Cli::ProviderFinder.new(middleware_name, value_name).find_chain
+
+      if chains.size > 1
+        puts "Value `#{value_name}` is provided to `#{middleware_name}` " \
+          "by multiple middleware chains:\n\n"
+      else
+        puts "Value `#{value_name}` is provided to `#{middleware_name}` by:\n\n"
+      end
+
+      formatted_chains = chains.map do |chain|
+        chain.join(" -> ")
+      end.join("\n---\n")
+
+      puts formatted_chains
+    end
+  end
+end

data/coach.gemspec

@@ -17,11 +17,15 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z`.split("\x0")
   spec.test_files    = spec.files.grep(%r{^spec/})
   spec.require_paths = ["lib"]
+  spec.executables   = ["coach"]
 
   spec.add_dependency "actionpack", ">= 4.2"
   spec.add_dependency "activesupport", ">= 4.2"
+  # TODO: Find another CLI parser that supports subcommands
+  # Slop v4 got rid of them :(
+  spec.add_dependency "slop", "~> 3.6"
 
-  spec.add_development_dependency "gc_ruboconfig", "= 2.6.1"
+  spec.add_development_dependency "gc_ruboconfig", "= 2.9.0"
   spec.add_development_dependency "pry", "~> 0.10"
   spec.add_development_dependency "rspec", "~> 3.2"
   spec.add_development_dependency "rspec-its", "~> 1.2"

data/lib/coach/cli/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Coach
+  module Cli
+    class Error < StandardError; end
+
+    module Errors
+      class MiddlewareNotFoundError < Error
+        attr_reader :middleware_name
+
+        def initialize(middleware_name)
+          @middleware_name = middleware_name
+
+          super("Middleware #{@middleware_name} not found")
+        end
+      end
+
+      class ValueNotRequiredError < Error
+        attr_reader :value_name
+
+        def initialize(middleware_name, value_name)
+          @middleware_name = middleware_name
+          @value_name = value_name
+
+          super("Middleware #{@middleware_name} doesn't require value #{value_name}")
+        end
+      end
+
+      class ValueNotProvidedError < Error
+        attr_reader :value_name
+
+        def initialize(middleware_name, value_name)
+          @middleware_name = middleware_name
+          @value_name = value_name
+
+          super("Middleware #{@middleware_name} isn't provided with value #{value_name}")
+        end
+      end
+    end
+  end
+end

data/lib/coach/cli/provider_finder.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "coach/cli/errors"
+require "set"
+
+module Coach
+  module Cli
+    class ProviderFinder
+      def initialize(middleware_name, value_name)
+        @middleware_name = middleware_name
+        @value_name = value_name
+      end
+
+      def find_provider
+        enforce_middleware_exists!
+        middleware = Module.const_get(@middleware_name)
+
+        enforce_middleware_requires_value!(middleware)
+
+        provider_mapping = build_provider_mapping(middleware, Hash.new { Set.new })
+
+        if provider_mapping.key?(@value_name.to_sym)
+          providers = provider_mapping[@value_name.to_sym]
+        else
+          err = Errors::ValueNotProvidedError.new(@middleware_name, @value_name)
+          raise err
+        end
+
+        providers.to_a.map(&:to_s)
+      end
+
+      def find_chain
+        enforce_middleware_exists!
+        middleware = Module.const_get(@middleware_name)
+
+        enforce_middleware_requires_value!(middleware)
+
+        provider_chain = build_provider_chain(middleware, Hash.new { Set.new }, [])
+
+        if provider_chain.key?(@value_name.to_sym)
+          chains = provider_chain[@value_name.to_sym]
+        else
+          err = Errors::ValueNotProvidedError.new(@middleware_name, @value_name)
+          raise err
+        end
+
+        chains.map { |chain| chain.map(&:to_s).reverse }.to_set
+      end
+
+      private
+
+      def enforce_middleware_exists!
+        unless Module.const_defined?(@middleware_name)
+          err = Errors::MiddlewareNotFoundError.new(@middleware_name)
+          raise err
+        end
+      end
+
+      def enforce_middleware_requires_value!(middleware)
+        unless middleware.requires?(@value_name.to_sym)
+          err = Errors::ValueNotRequiredError.new(@middleware_name, @value_name)
+          raise err
+        end
+      end
+
+      def build_provider_mapping(middleware, mapping)
+        middleware.provided.each do |p|
+          mapping[p] = mapping[p].add(middleware)
+        end
+
+        middleware.middleware_dependencies.each do |dep|
+          build_provider_mapping(dep.middleware, mapping)
+        end
+
+        mapping
+      end
+
+      def build_provider_chain(middleware, mapping, chain)
+        new_chain = chain + [middleware]
+
+        middleware.provided.each do |p|
+          mapping[p] = mapping[p].add(new_chain)
+        end
+
+        middleware.middleware_dependencies.each do |dep|
+          build_provider_chain(dep.middleware, mapping, new_chain)
+        end
+
+        mapping
+      end
+    end
+  end
+end

data/lib/coach/request_serializer.rb

@@ -64,7 +64,7 @@ module Coach
       header_value_pairs = @request.filtered_env.map do |key, value|
         key = if RACK_UNPREFIXED_HEADERS.include?(key)
                 "http_#{key.downcase}"
-              elsif key =~ /^HTTP_/
+              elsif key.match?(/^HTTP_/)
                 key.downcase
               end
 

data/lib/coach/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coach
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 end

data/lib/spring/commands/coach.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Spring
+  module Commands
+    class Coach
+      def env(*)
+        "development"
+      end
+
+      def exec_name
+        "coach"
+      end
+
+      Spring.register_command "coach", Coach.new
+    end
+  end
+end

data/spec/lib/coach/cli/provider_finder_spec.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+require "coach/cli/provider_finder"
+
+describe Coach::Cli::ProviderFinder do
+  subject(:provider_finder) { described_class.new(middleware_name, value_name) }
+
+  let(:middleware_name) { "" }
+  let(:value_name) { "" }
+
+  describe "#find_provider" do
+    context "when there is a single provider" do
+      let(:middleware_name) { "RequiringMiddleware" }
+      let(:value_name) { "provided_value" }
+
+      before do
+        stub_const("ProvidingMiddleware", Class.new(Coach::Middleware) do
+          provides :provided_value
+        end)
+        stub_const(middleware_name, Class.new(Coach::Middleware) do
+          uses ProvidingMiddleware
+
+          requires :provided_value
+        end)
+      end
+
+      it "returns the providing middleware" do
+        expect(provider_finder.find_provider).to eq %w[ProvidingMiddleware]
+      end
+    end
+
+    context "when there are multiple providers" do
+      let(:middleware_name) { "RequiringMiddleware" }
+      let(:value_name) { "provided_value" }
+
+      before do
+        stub_const("FirstProvidingMiddleware", Class.new(Coach::Middleware) do
+          provides :provided_value
+        end)
+        stub_const("SecondProvidingMiddleware", Class.new(Coach::Middleware) do
+          provides :provided_value
+        end)
+        stub_const(middleware_name, Class.new(Coach::Middleware) do
+          uses FirstProvidingMiddleware
+          uses SecondProvidingMiddleware
+
+          requires :provided_value
+        end)
+      end
+
+      it "returns the providing middleware" do
+        expect(provider_finder.find_provider).
+          to eq %w[FirstProvidingMiddleware SecondProvidingMiddleware]
+      end
+    end
+
+    context "when there's an intermediate middleware after the provider" do
+      let(:middleware_name) { "RequiringMiddleware" }
+      let(:value_name) { "provided_value" }
+
+      before do
+        stub_const("ProvidingMiddleware", Class.new(Coach::Middleware) do
+          provides :provided_value
+        end)
+        stub_const("IntermediateMiddleware", Class.new(Coach::Middleware) do
+          uses ProvidingMiddleware
+        end)
+        stub_const(middleware_name, Class.new(Coach::Middleware) do
+          uses IntermediateMiddleware
+
+          requires :provided_value
+        end)
+      end
+
+      it "returns the providing middleware" do
+        expect(provider_finder.find_provider).to eq %w[ProvidingMiddleware]
+      end
+    end
+
+    context "when the middleware can't be found" do
+      let(:middleware_name) { "MiddlewareThatDoesntExist" }
+
+      it "raises a MiddlewareNotFoundError" do
+        expect { provider_finder.find_provider }.
+          to raise_error(Coach::Cli::Errors::MiddlewareNotFoundError)
+      end
+    end
+
+    context "when the middleware doesn't require the specified value" do
+      let(:middleware_name) { "MiddlewareWithoutRequires" }
+      let(:value_name) { "value_that_doesnt_exist" }
+
+      before do
+        stub_const(middleware_name, Class.new(Coach::Middleware))
+      end
+
+      it "raises a ValueNotRequiredError" do
+        expect { provider_finder.find_provider }.
+          to raise_error(Coach::Cli::Errors::ValueNotRequiredError)
+      end
+    end
+
+    context "when the middleware isn't provided with a value it requires" do
+      let(:middleware_name) { "MiddlewareWithMissingProvide" }
+      let(:value_name) { "value_that_isnt_provided" }
+
+      before do
+        stub_const(middleware_name, Class.new(Coach::Middleware) do
+          requires :value_that_isnt_provided
+        end)
+      end
+
+      it "raises a ValueNotProvidedError" do
+        expect { provider_finder.find_provider }.
+          to raise_error(Coach::Cli::Errors::ValueNotProvidedError)
+      end
+    end
+  end
+
+  describe "#find_chain" do
+    context "when there is a single provider" do
+      let(:middleware_name) { "RequiringMiddleware" }
+      let(:value_name) { "provided_value" }
+
+      before do
+        stub_const("ProvidingMiddleware", Class.new(Coach::Middleware) do
+          provides :provided_value
+        end)
+        stub_const(middleware_name, Class.new(Coach::Middleware) do
+          uses ProvidingMiddleware
+
+          requires :provided_value
+        end)
+      end
+
+      it "returns the providing middleware" do
+        expect(provider_finder.find_chain).
+          to eq [%w[ProvidingMiddleware RequiringMiddleware]].to_set
+      end
+    end
+
+    context "when there are multiple paths to a single provider" do
+      let(:middleware_name) { "RequiringMiddleware" }
+      let(:value_name) { "provided_value" }
+
+      before do
+        stub_const("ProvidingMiddleware", Class.new(Coach::Middleware) do
+          provides :provided_value
+        end)
+        stub_const("FirstIntermediateMiddleware", Class.new(Coach::Middleware) do
+          uses ProvidingMiddleware
+        end)
+        stub_const("SecondIntermediateMiddleware", Class.new(Coach::Middleware) do
+          uses ProvidingMiddleware
+        end)
+        stub_const(middleware_name, Class.new(Coach::Middleware) do
+          uses FirstIntermediateMiddleware
+          uses SecondIntermediateMiddleware
+
+          requires :provided_value
+        end)
+      end
+
+      it "returns multiple middleware chains" do
+        expect(provider_finder.find_chain).
+          to eq [
+            %w[ProvidingMiddleware FirstIntermediateMiddleware RequiringMiddleware],
+            %w[ProvidingMiddleware SecondIntermediateMiddleware RequiringMiddleware],
+          ].to_set
+      end
+    end
+
+    context "when there are multiple paths to multiple providers" do
+      let(:middleware_name) { "RequiringMiddleware" }
+      let(:value_name) { "provided_value" }
+
+      before do
+        stub_const("FirstProvidingMiddleware", Class.new(Coach::Middleware) do
+          provides :provided_value
+        end)
+        stub_const("SecondProvidingMiddleware", Class.new(Coach::Middleware) do
+          provides :provided_value
+        end)
+        stub_const("FirstIntermediateMiddleware", Class.new(Coach::Middleware) do
+          uses FirstProvidingMiddleware
+        end)
+        stub_const("SecondIntermediateMiddleware", Class.new(Coach::Middleware) do
+          uses SecondProvidingMiddleware
+        end)
+        stub_const(middleware_name, Class.new(Coach::Middleware) do
+          uses FirstIntermediateMiddleware
+          uses SecondIntermediateMiddleware
+
+          requires :provided_value
+        end)
+      end
+
+      it "returns multiple middleware chains" do
+        expect(provider_finder.find_chain).
+          to eq([
+            %w[FirstProvidingMiddleware FirstIntermediateMiddleware RequiringMiddleware],
+            %w[SecondProvidingMiddleware SecondIntermediateMiddleware RequiringMiddleware], # rubocop:disable Metrics/LineLength
+          ].to_set)
+      end
+    end
+
+    context "when the middleware can't be found" do
+      let(:middleware_name) { "MiddlewareThatDoesntExist" }
+
+      it "raises a MiddlewareNotFoundError" do
+        expect { provider_finder.find_chain }.
+          to raise_error(Coach::Cli::Errors::MiddlewareNotFoundError)
+      end
+    end
+
+    context "when the middleware doesn't require the specified value" do
+      let(:middleware_name) { "MiddlewareWithoutRequires" }
+      let(:value_name) { "value_that_doesnt_exist" }
+
+      before do
+        stub_const(middleware_name, Class.new(Coach::Middleware))
+      end
+
+      it "raises a ValueNotRequiredError" do
+        expect { provider_finder.find_chain }.
+          to raise_error(Coach::Cli::Errors::ValueNotRequiredError)
+      end
+    end
+
+    context "when the middleware isn't provided with a value it requires" do
+      let(:middleware_name) { "MiddlewareWithMissingProvide" }
+      let(:value_name) { "value_that_isnt_provided" }
+
+      before do
+        stub_const(middleware_name, Class.new(Coach::Middleware) do
+          requires :value_that_isnt_provided
+        end)
+      end
+
+      it "raises a ValueNotProvidedError" do
+        expect { provider_finder.find_chain }.
+          to raise_error(Coach::Cli::Errors::ValueNotProvidedError)
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: coach
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - GoCardless
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-14 00:00:00.000000000 Z
+date: 2020-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -38,20 +38,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: slop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
 - !ruby/object:Gem::Dependency
   name: gc_ruboconfig
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.6.1
+        version: 2.9.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.6.1
+        version: 2.9.0
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -111,7 +125,8 @@ dependencies:
 description: 
 email:
 - developers@gocardless.com
-executables: []
+executables:
+- coach
 extensions: []
 extra_rdoc_files: []
 files:
@@ -124,9 +139,12 @@ files:
 - Gemfile
 - LICENSE.txt
 - README.md
+- bin/coach
 - coach.gemspec
 - docs/COMPATIBILITY.md
 - lib/coach.rb
+- lib/coach/cli/errors.rb
+- lib/coach/cli/provider_finder.rb
 - lib/coach/errors.rb
 - lib/coach/handler.rb
 - lib/coach/middleware.rb
@@ -138,6 +156,8 @@ files:
 - lib/coach/router.rb
 - lib/coach/rspec.rb
 - lib/coach/version.rb
+- lib/spring/commands/coach.rb
+- spec/lib/coach/cli/provider_finder_spec.rb
 - spec/lib/coach/handler_spec.rb
 - spec/lib/coach/middleware_spec.rb
 - spec/lib/coach/middleware_validator_spec.rb
@@ -165,12 +185,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Alternative controllers built with middleware
 test_files:
+- spec/lib/coach/cli/provider_finder_spec.rb
 - spec/lib/coach/handler_spec.rb
 - spec/lib/coach/middleware_spec.rb
 - spec/lib/coach/middleware_validator_spec.rb