coach 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f233d889ec89e57f76bae7dda4b2177c83be182d
-  data.tar.gz: 4c9c7a69abc07cbaa151d0bea475b71613fda6af
+  metadata.gz: 3258a468d749d86884a028d51d035966dfa925a2
+  data.tar.gz: c04518e139d26372ee97a8450967d4aa32756989
 SHA512:
-  metadata.gz: 10d9020086eda5deadf442818a34835340705a303378aba76f85fe2044e5f51c29fed30300f5702ba2a575ccd33712ff735561d806429f0508385fc2499a4f7a
-  data.tar.gz: 4f5620ed998bab8ee0549dc7da81149171f694fa9d3f0bcef2f26e1561b9d4cbeb9765f5418e0c90e1a3a1e1b8059be6679374c0fdf916600f85d4b54aaf8906
+  metadata.gz: 439c250dce80d2ed7f50a69d8c06aaf4d47e01ba3b25f4c368debfc0ab4431c45c8cf470f0f3377cbdb6043e1604c3c731b116e0134903d986865b06f53f9fc2
+  data.tar.gz: 01963b88c9e4886cfd523d0da278958a5db70e08e1f1fb96d2c97ba987c30392fe2581a450a613c9ee0f6427390664ba44f1c4b4b90be10efbb092b360eeb017

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    coach (0.2.0)
+    coach (0.2.1)
       actionpack (~> 4.2)
       activesupport (~> 4.2)
 
@@ -101,4 +101,4 @@ DEPENDENCIES
   rubocop
 
 BUNDLED WITH
-   1.10.3
+   1.10.4

data/README.md

@@ -4,7 +4,7 @@
 [![Build Status](https://travis-ci.org/gocardless/coach.png?branch=master)](https://travis-ci.org/gocardless/coach)
 [![Code Climate](https://codeclimate.com/github/gocardless/coach.png)](https://codeclimate.com/github/gocardless/coach)
 
-Coach improves your controller code by encouraging...
+Coach improves your controller code by encouraging:
 
 - **Modularity** - No more tangled `before_filter`'s and interdependent concerns. Build
   Middleware that does a single job, and does it well.
@@ -13,129 +13,129 @@ Coach improves your controller code by encouraging...
 - **Testability** - Test each middleware in isolation, with effortless mocking of test
   data and natural RSpec matchers.
 
-## Simple endpoint
+## Coach by example
 
-Lets start by creating a simple endpoint.
+The best way to see the benefits of Coach is with a demonstration.
+
+### Mounting an endpoint
 
 ```ruby
-module Routes
-  class Echo < Coach::Middleware
-    def call
-      # All middleware should return rack compliant responses
-      [ 200, {}, [params[:word]] ]
-    end
+class HelloWorld < Coach::Middleware
+  def call
+    # Middleware return a Rack response
+    [ 200, {}, ['hello world'] ]
   end
 end
 ```
 
-Any Middlewares have access to the `request` handle, which is an instance of
-`ActionDispatch::Request`. This also parses the request params, and these are made
-available inside Middlewares as `params`.
+So we've created ourselves a piece of middleware, `HelloWorld`. As you'd expect,
+`HelloWorld` simply outputs the string `'hello world'`.
 
 In an example Rails app, called `Example`, we can mount this route like so...
 
 ```ruby
 Example::Application.routes.draw do
-  match "/echo/:word",
-        to: Coach::Handler.new(Routes::Echo),
+  match "/hello_world",
+        to: Coach::Handler.new(HelloWorld),
         via: :get
 end
 ```
 
-Once booting Rails locally, running `curl -XGET http://localhost:3000/echo/hello` should
-respond with `'hello'`.
-
-## Building chains
+Once you've booted Rails locally, the following should return `'hello world'`:
 
-Lets try creating a route protected by authentication.
-
-```ruby
-module Routes
-  class Secret < Coach::Middleware
-    def call
-      unless User.exists?(id: params[:user_id], password: params[:user_password])
-        return [ 401, {}, ['Access denied'] ]
-      end
-
-      [ 200, {}, ['super-secretness'] ]
-    end
-  end
-end
+```sh
+$ curl -XGET http://localhost:3000/hello_world
 ```
 
-The above will verify that a user can be found with the given params, and if it cannot
-then will respond with a `401`.
+### Building chains
+
+Suppose we didn't want just anybody to see our `HelloWorld` endpoint. In fact, we'd like
+to lock it down behind some authentication.
 
-This does what we want it to do, but why should `Secret` know anything about
-authentication? This complicates `Secret`'s design and prevents reuse of authentication
-logic.
+Our request will now have two stages, one where we check authentication details and
+another where we respond with our secret greeting to the world. Let's split into two
+pieces, one for each of the two subtasks, allowing us to reuse this authentication flow in
+other middlewares.
 
 ```ruby
-module Middleware
-  class Authentication < Coach::Middleware
-    def call
-      unless User.exists?(id: params[:user_id], password: params[:user_password])
-        return [ 401, {}, ['Access denied'] ]
-      end
-
-      next_middleware.call
+class Authentication < Coach::Middleware
+  def call
+    unless User.exists?(login: params[:login])
+      return [ 401, {}, ['Access denied'] ]
     end
+
+    next_middleware.call
   end
 end
 
-module Routes
-  class Secret < Coach::Middleware
-    uses Middleware::Authentication
+class HelloWorld < Coach::Middleware
+  uses Authentication
 
-    def call
-      [ 200, {}, ['super-secretness'] ]
-    end
+  def call
+    [ 200, {}, ['hello world'] ]
   end
 end
 ```
 
-Here we detach the authentication logic into it's own middleware. `Secret` now `uses`
-`Middleware::Authentication`, and will only run if it has been called via
-`next_middleware.call` from authentication.
+Here we detach the authentication logic into its own middleware. `HelloWorld` now `uses`
+`Authentication`, and will only run if it has been called via `next_middleware.call` from
+authentication.
+
+Notice we also use `params` just like you would in a normal Rails controller. Every
+middleware class will have access to a `request` object, which is an instance of
+`ActionDispatch::Request`.
 
-## Passing data through middleware
+### Passing data through middleware
 
-Now what happens if you have an endpoint that returns the current auth'd users details? We
-can maintain the separation of authentication logic and endpoint as below...
+So far we've demonstrated how Coach can help you break your controller code into modular
+pieces. The big innovation with Coach, however, is the ability to explicitly pass your
+data through the middleware chain.
+
+An example usage here is to create a `HelloUser` endpoint. We want to protect the route by
+authentication, as we did before, but this time greet the user that is logged in. Making
+a small modification to the `Authentication` middleware we showed above...
 
 ```ruby
-module Middleware
-  class AuthenticatedUser < Coach::Middleware
-    provides :authenticated_user
+class Authentication < Coach::Middleware
+  provides :user  # declare that Authentication provides :user
 
-    def call
-      user = User.find_by(token: request.headers['Authorization'])
-      return [ 401, {}, ['Access denied'] ] unless user.exists?
+  def call
+    return [ 401, {}, ['Access denied'] ] unless user.present?
 
-      provide(authenticated_user: user)
-      next_middleware.call
-    end
+    provide(user: user)
+    next_middleware.call
+  end
+
+  def user
+    @user ||= User.find_by(login: params[:login])
   end
 end
 
-module Routes
-  class Whoami < Coach::Middleware
-    uses AuthenticatedUser
-    requires :authenticated_user
+class HelloUser < Coach::Middleware
+  uses Authentication
+  requires :user  # state that HelloUser requires this data
 
-    def call
-      [ 200, {}, [authenticated_user.name] ]
-    end
+  def call
+    # Can now access `user`, as it's been provided by Authentication
+    [ 200, {}, [ "hello #{user.name}" ] ]
   end
 end
+
+# Inside config/routes.rb
+Example::Application.routes.draw do
+  match "/hello_user",
+        to: Coach::Handler.new(HelloUser),
+        via: :get
+end
 ```
 
-Each middleware declares what it requires from those that have ran before it, and what it
-will provide to those that run after. Whenever a middleware chain is mounted, these
-requirements will be verified. In the above, if our `Whoami` middleware had neglected to use
-`AuthenticatedUser`, then mounting would fail with the error...
+Coach analyses your middleware chains whenever a new `Handler` is created. If any
+middleware `requires :x` when its chain does not provide `:x`, we'll error out before the
+app even starts with the error:
 
-    Coach::Errors::MiddlewareDependencyNotMet: AuthenticatedUser requires keys [authenticated_user] that are not provided by the middleware chain
+```ruby
+Coach::Errors::MiddlewareDependencyNotMet: HelloUser requires keys [user] that are not provided by the middleware chain
+```
 
 This static verification eradicates an entire category of errors that stem from implicitly
 running code before hitting controller methods. It allows you to be confident that the
@@ -213,7 +213,7 @@ router.draw(Routes::Users,
 ```
 
 Default actions that conform to standard REST principles can be easily loaded, with the
-users resource being mapped to...
+users resource being mapped to:
 
 | Method | URL                          | Description                                    |
 |--------|------------------------------|------------------------------------------------|

data/lib/coach/handler.rb

@@ -25,7 +25,10 @@ module Coach
 
       finish = Time.now
       publish('coach.handler.finish',
-              start, finish, nil, start_event.merge(response: { status: response[0] }))
+              start, finish, nil,
+              start_event.merge(
+                response: { status: response[0] },
+                metadata: context.fetch(:_metadata, {})))
 
       response
     end

data/lib/coach/middleware.rb

@@ -15,6 +15,10 @@ module Coach
     end
 
     def self.provides(*new_provided)
+      if new_provided.include?(:_metadata)
+        raise 'Cannot provide :_metadata, Coach uses this internally!'
+      end
+
       provided.concat(new_provided)
       provided.uniq!
     end
@@ -76,6 +80,12 @@ module Coach
       end
     end
 
+    # Adds key-values to metadata, to be published with coach events.
+    def log_metadata(**values)
+      @_context[:_metadata] ||= {}
+      @_context[:_metadata].merge!(values)
+    end
+
     # Helper to access request params from within middleware
     delegate :params, to: :request
 

data/lib/coach/notifications.rb

@@ -78,10 +78,12 @@ module Coach
       broadcast(event, benchmark)
     end
 
+    # Receives a handler.finish event, with processed benchmark. Publishes to
+    # coach.request notification.
     def broadcast(event, benchmark)
       serialized = RequestSerializer.new(event[:request]).serialize.
         merge(benchmark.stats).
-        merge(event.slice(:response))
+        merge(event.slice(:response, :metadata))
       ActiveSupport::Notifications.publish('coach.request', serialized)
     end
   end

data/lib/coach/version.rb

@@ -1,3 +1,3 @@
 module Coach
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/lib/spec/matchers.rb

@@ -12,6 +12,7 @@ def build_middleware(name)
 
     def call
       config[:callback].call if config.include?(:callback)
+      log_metadata(Hash[name.to_sym, true])
 
       # Build up a list of middleware called, in the order they were called
       if next_middleware

data/spec/lib/coach/middleware_spec.rb

@@ -5,6 +5,13 @@ describe Coach::Middleware do
   let(:context_) { {} }
   let(:middleware_obj) { middleware_class.new(context_, nil) }
 
+  describe ".provides" do
+    it "blows up if providing a reserved keyword" do
+      expect { middleware_class.provides(:_metadata) }.
+        to raise_exception(/cannot provide.* coach uses this/i)
+    end
+  end
+
   describe ".provides?" do
     context "given names it does provide" do
       before { middleware_class.provides(:foo, :bar) }

data/spec/lib/coach/notifications_spec.rb

@@ -48,10 +48,18 @@ describe Coach::Notifications do
       expect(middleware_event).not_to be_nil
     end
 
-    it "broadcasts event containing all middleware that have been run" do
-      handler.call({})
-      middleware_names = middleware_event[:chain].map { |item| item[:name] }
-      expect(middleware_names).to include(*%w(Terminal A B))
+    describe "coach.request event" do
+      before { handler.call({}) }
+
+      it "contains all middleware that have been run" do
+        middleware_names = middleware_event[:chain].map { |item| item[:name] }
+        expect(middleware_names).to include(*%w(Terminal A B))
+      end
+
+      it "includes all logged metadata" do
+        expect(middleware_event).
+          to include(metadata: { A: true, B: true, Terminal: true })
+      end
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coach
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - GoCardless
@@ -14,84 +14,84 @@ dependencies:
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '4.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '4.2'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '4.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '4.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 3.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 3.2.0
 - !ruby/object:Gem::Dependency
   name: rspec-its
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 1.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 1.2.0
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Controller framework
@@ -101,10 +101,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .rubocop.yml
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
 - Gemfile
 - Gemfile.lock
 - README.md
@@ -139,12 +139,12 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []