coach 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5b238b46a6cc3ceb9bd972eb675ab185e9782314
+  data.tar.gz: 65d9e3c36df29228fa740e1b745a4888b6e7942c
+SHA512:
+  metadata.gz: 68a7271f6e510864ed92949c9b4e9d6edb1ed0212138792717d0ed357c0afd2ff95b35ab42a3915e69cc3b37d9653cba9d9c1bdd3d8c9202473dab482abb35be
+  data.tar.gz: e4ec8fac9cbcbccd75cef7162604f7b521be4a9b902fe41c5625fb47717aff18a55bbc3c9fe28d37eedd94dcf74bd023edf92f52fd1badcab9182fc8bf846c23

data/.rspec

@@ -0,0 +1 @@
+--color

data/.rubocop.yml

@@ -0,0 +1,123 @@
+# For all options see https://github.com/bbatsov/rubocop/tree/master/config
+
+# Limit lines to 90 characters.
+LineLength:
+  Max: 90
+
+ClassLength:
+  Enabled: false
+
+ModuleLength:
+  Enabled: false
+
+# Avoid methods longer than 30 lines of code
+MethodLength:
+  CountComments: false  # count full line comments?
+  Max: 87
+
+# Avoid single-line methods.
+SingleLineMethods:
+  AllowIfMethodIsEmpty: true
+
+StringLiterals:
+  Enabled: false
+
+GlobalVars:
+  Enabled: false # We use them Redis + StatsD (though maybe we shouldn't?)
+
+# Wants underscores in all large numbers. Pain in the ass for things like
+# unix timestamps.
+NumericLiterals:
+  Enabled: false
+
+# Wants you to use the same argument names for every reduce. This seems kinda
+# naff compared to naming them semantically
+SingleLineBlockParams:
+  Enabled: false
+
+Style/SignalException:
+  EnforcedStyle: 'only_raise'
+
+# Use trailing rather than leading dots on multi-line call chains
+Style/DotPosition:
+  EnforcedStyle: trailing
+
+Lint/NestedMethodDefinition:
+  Enabled: false
+
+Lint/UnusedBlockArgument:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 61
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Style/AccessorMethodName:
+  Enabled: false
+
+# Allow non-ASCII characters (e.g. £) in comments
+Style/AsciiComments:
+  Enabled: false
+
+# Configuration parameters: EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle, SupportedLastArgumentHashStyles.
+Style/AlignHash:
+  Enabled: false
+
+# Configuration parameters: EnforcedStyle, SupportedStyles, ProceduralMethods, FunctionalMethods, IgnoredMethods.
+Style/BlockDelimiters:
+  Enabled: false
+
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/ClosingParenthesisIndentation:
+  Enabled: false
+
+# Configuration parameters: Keywords.
+Style/CommentAnnotation:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+# Configuration parameters: MinBodyLength.
+Style/GuardClause:
+  Enabled: false
+
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/IndentHash:
+  Enabled: false
+
+Style/Lambda:
+  Enabled: false
+
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/MultilineOperationIndentation:
+  Enabled: false
+
+# Configuration parameters: NamePrefix, NamePrefixBlacklist.
+Style/PredicateName:
+  Enabled: false
+
+Style/RedundantSelf:
+  Enabled: false
+
+Style/SingleSpaceBeforeFirstArg:
+  Enabled: false
+
+# Configuration parameters: MultiSpaceAllowedForOperators.
+Style/SpaceAroundOperators:
+  Enabled: false
+
+# Configuration parameters: ExactNameMatch, AllowPredicates, AllowDSLWriters, IgnoreClassMethods, Whitelist.
+Style/TrivialAccessors:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,104 @@
+PATH
+  remote: .
+  specs:
+    coach (0.0.0)
+      actionpack (~> 4.2)
+      activesupport (~> 4.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (4.2.1)
+      actionview (= 4.2.1)
+      activesupport (= 4.2.1)
+      rack (~> 1.6)
+      rack-test (~> 0.6.2)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.1)
+    actionview (4.2.1)
+      activesupport (= 4.2.1)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.1)
+    activesupport (4.2.1)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    ast (2.0.0)
+    astrolabe (1.3.0)
+      parser (>= 2.2.0.pre.3, < 3.0)
+    builder (3.2.2)
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    erubis (2.7.0)
+    i18n (0.7.0)
+    json (1.8.3)
+    loofah (2.0.2)
+      nokogiri (>= 1.5.9)
+    method_source (0.8.2)
+    mini_portile (0.6.2)
+    minitest (5.7.0)
+    nokogiri (1.6.6.2)
+      mini_portile (~> 0.6.0)
+    parser (2.2.2.5)
+      ast (>= 1.1, < 3.0)
+    powerpack (0.1.1)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rack (1.6.1)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rails-deprecated_sanitizer (1.0.3)
+      activesupport (>= 4.2.0.alpha)
+    rails-dom-testing (1.0.6)
+      activesupport (>= 4.2.0.beta, < 5.0)
+      nokogiri (~> 1.6.0)
+      rails-deprecated_sanitizer (>= 1.0.1)
+    rails-html-sanitizer (1.0.2)
+      loofah (~> 2.0)
+    rainbow (2.0.0)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.3)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-its (1.2.0)
+      rspec-core (>= 3.0.0)
+      rspec-expectations (>= 3.0.0)
+    rspec-mocks (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.2)
+    rubocop (0.32.0)
+      astrolabe (~> 1.3)
+      parser (>= 2.2.2.5, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.4)
+    ruby-progressbar (1.7.5)
+    slop (3.6.0)
+    thread_safe (0.3.5)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  coach!
+  pry
+  rspec (~> 3.2.0)
+  rspec-its (~> 1.2.0)
+  rubocop
+
+BUNDLED WITH
+   1.10.3

data/README.md

@@ -0,0 +1,260 @@
+# Coach
+For when Rails has you jumping on the tracks...
+
+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.
+- **Guarantees** - Work with a simple `provide`/`require` interface to guarantee that the
+  data you need in your endpoint is loaded before your app even boots.
+- **Testability** - Test each middleware in isolation, with effortless mocking of test
+  data and natural RSpec matchers.
+
+## Simple endpoint
+
+Lets start by creating a simple endpoint.
+
+```ruby
+module Routes
+  class Echo < Coach::Middleware
+    def call
+      # All middleware should return rack compliant responses
+      [ 200, {}, [params[:word]] ]
+    end
+  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`.
+
+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),
+        via: :get
+end
+```
+
+Once booting Rails locally, running `curl -XGET http://localhost:3000/echo/hello` should
+respond with `'hello'`.
+
+## Building chains
+
+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
+```
+
+The above will verify that a user can be found with the given params, and if it cannot
+then will respond with a `401`.
+
+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.
+
+```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
+    end
+  end
+end
+
+module Routes
+  class Secret < Coach::Middleware
+    uses Middleware::Authentication
+
+    def call
+      [ 200, {}, ['super-secretness'] ]
+    end
+  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.
+
+## 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...
+
+```ruby
+module Middleware
+  class AuthenticatedUser < Coach::Middleware
+    provides :authenticated_user
+
+    def call
+      user = User.find_by(token: request.headers['Authorization'])
+      return [ 401, {}, ['Access denied'] ] unless user.exists?
+
+      provide(authenticated_user: user)
+      next_middleware.call
+    end
+  end
+end
+
+module Routes
+  class Whoami < Coach::Middleware
+    uses AuthenticatedUser
+    requires :authenticated_user
+
+    def call
+      [ 200, {}, [authenticated_user.name] ]
+    end
+  end
+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
+promises will be verified. In the above, if our `Whoami` middleware had neglected to use
+`AuthenticatedUser`, then mounting would fail with the error...
+
+    Coach::Errors::MiddlewareDependencyNotMet: AuthenticatedUser requires keys [authenticated_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
+data you require has been loaded, and makes tracing the origin of that data as simple as
+looking up the chain.
+
+## Testing
+
+The basic strategy is to test each middleware in isolation, covering all the edge cases,
+and then create request specs that cover a happy code path, testing each of the
+middlewares while they work in sequence.
+
+Each middleware is encouraged to rely on data passed through the `provide`/`require`
+syntax exclusively, except in stateful operations (such as database queries). By sticking
+to this rule, testing becomes as simple as mocking a `context` hash.
+
+```ruby
+require 'spec_helper'
+
+describe "/whoami" do
+  let(:user) { FactoryGirl.create(:user, name: 'Clark Kent', token: 'Kryptonite') }
+
+  context "with correct auth details" do
+    it "responds with user name" do
+      get "/whoami", {}, { 'Authorization' => 'Kryptonite' }
+      expect(response.body).to match(/Clark Kent/)
+    end
+  end
+end
+
+describe Routes::Whoami do
+  subject(:instance) { described_class.new(context) }
+  let(:context) { { authenticated_user: double(name: "Clark Kent") } }
+
+  it { is_expected.to respond_with_body_that_matches(/Clark Kent/) }
+end
+
+describe Middleware::AuthenticatedUser do
+  subject(:instance) { described_class.new(context) }
+  let(:context) do
+    { request: instance_double(ActionDispatch::Request, headers: headers) }
+  end
+
+  let(:user) { FactoryGirl.create(:user, name: 'Clark Kent', token: 'Kryptonite') }
+
+  context "with valid token" do
+    it { is_expected.to call_next_middleware }
+    it { is_expected.to provide(authenticated_user: user) }
+  end
+
+  context "with invalid token" do
+    it { is_expected.to respond_with_status(401) }
+    it { is_expected.to respond_with_body_that_matches(/access denied/i) }
+  end
+end
+```
+
+## Routing
+
+For routes that represent resource actions, Coach provides some syntactic sugar to
+allow concise mapping of endpoint to handler.
+
+```ruby
+router = Coach::Router.new(Example::Application)
+
+router.draw(Routes::Users,
+            base: "/users",
+            actions: [
+              :index,
+              :show,
+              :create,
+              :update,
+              disable: { method: :post, url: "/:id/actions/disable" }
+            ])
+```
+
+Default actions that conform to standard REST principles can be easily loaded, with the
+users resource being mapped to...
+
+| Method | URL                          | Description                                    |
+|--------|------------------------------|------------------------------------------------|
+| `GET`  | `/users`                     | Index all users                                |
+| `GET`  | `/users/:id`                 | Get user by ID                                 |
+| `POST` | `/users`                     | Create new user                                |
+| `PUT`  | `/users/:id`                 | Update user details                            |
+| `POST` | `/users/:id/actions/disable` | Custom action routed to the given path suffix  |
+
+## Rendering
+
+By now you'll probably agree that the rack response format isn't the nicest way to render
+responses. Coach comes sans renderer, and for a good reason.
+
+We initially built a `Coach::Renderer` module, but soon realised that doing so would
+prevent us from open sourcing. Our `Renderer` was 90% logic specific to the way our APIs
+function, including handling/formatting of validation errors, logging of unusual events
+etc.
+
+What worked well for us is a standalone `Renderer` class that we could require in all our
+middleware that needed to format responses. This pattern also led to clearer code -
+consistent with our preference for explicit code, stating `Renderer.new_resource(...)` is
+instantly more debuggable than an inherited method on all middlewares.
+
+## Instrumentation
+
+Coach uses `ActiveSupport::Notifications` to issue events that can be used to profile
+middleware.
+
+Information for how to use `ActiveSupport`s notifications can be found
+[here](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html).
+
+
+| Event                         | Arguments                                              |
+|-------------------------------|------------------------------------------------------- |
+| `coach.handler.start`     | `event(:middleware, :request)`                         |
+| `coach.middleware.start`  | `event(:middleware, :request)`                         |
+| `coach.middleware.finish` | `start`, `finish`, `id`, `event(:middleware, :request)`|
+| `coach.handler.finish`    | `start`, `finish`, `id`, `event(:middleware, :request)`|
+| `coach.request`           | `event` containing request data and benchmarking       |
+
+Of special interest is `coach.request`, which publishes statistics on an entire
+middleware chain and request. This data is particularly useful for logging, and is our
+solution to Rails `process_action.action_controller` event emitted on controller requests.
+
+The benchmarking data includes information on how long each middleware took to process,
+along with the total duration of the chain.