coach 0.0.0

data/coach.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'coach/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'coach'
+  spec.version       = Coach::VERSION
+  spec.date          = '2015-06-12'
+  spec.summary       = 'coach middleware'
+  spec.description   = 'Controller framework'
+  spec.authors       = %w(GoCardless)
+  spec.homepage      = "https://github.com/gocardless/coach"
+  spec.email         = %w(developers@gocardless.com)
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^spec/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'actionpack', '~> 4.2'
+  spec.add_dependency 'activesupport', '~> 4.2'
+
+  spec.add_development_dependency 'rspec', '~> 3.2.0'
+  spec.add_development_dependency 'rspec-its', '~> 1.2.0'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rubocop'
+end

data/lib/coach.rb

@@ -0,0 +1,16 @@
+require 'active_support'
+require 'action_dispatch'
+
+require_relative 'coach/errors'
+require_relative 'coach/handler'
+require_relative 'coach/middleware'
+require_relative 'coach/middleware_item'
+require_relative 'coach/middleware_validator'
+require_relative 'coach/notifications'
+require_relative 'coach/request_benchmark'
+require_relative 'coach/request_serializer'
+require_relative 'coach/router'
+require_relative 'coach/version'
+
+module Coach
+end

data/lib/coach/errors.rb

@@ -0,0 +1,16 @@
+module Coach
+  module Errors
+    class MiddlewareDependencyNotMet < StandardError
+      def initialize(middleware, keys)
+        super("#{middleware.name} requires keys [#{keys.join(',')}] that are not " \
+              "provided by the middleware chain")
+      end
+    end
+
+    class RouterUnknownDefaultAction < StandardError
+      def initialize(action)
+        super("Coach::Router does not know how to build action :#{action}")
+      end
+    end
+  end
+end

data/lib/coach/handler.rb

@@ -0,0 +1,82 @@
+require "coach/errors"
+
+module Coach
+  class Handler
+    def initialize(middleware)
+      @root_item = MiddlewareItem.new(middleware)
+      validate!
+    end
+
+    # Run validation on the root of the middleware chain
+    delegate :validate!, to: :@root_item
+
+    # The Rack interface to handler - builds a middleware chain based on
+    # the current request, and invokes it.
+    def call(env)
+      context = { request: ActionDispatch::Request.new(env) }
+      sequence = build_sequence(@root_item, context)
+      chain = build_request_chain(sequence, context)
+
+      start_event = start_event(context)
+      start = Time.now
+
+      publish('coach.handler.start', start_event.dup)
+      response = chain.instrument.call
+
+      finish = Time.now
+      publish('coach.handler.finish',
+              start, finish, nil, start_event.merge(response: { status: response[0] }))
+
+      response
+    end
+
+    # Traverse the middlware tree to build a linear middleware sequence,
+    # containing only middlewares that apply to this request.
+    def build_sequence(item, context)
+      sub_sequence = item.middleware.middleware_dependencies
+      filtered_sub_sequence = filter_sequence(sub_sequence, context)
+      flattened_sub_sequence = filtered_sub_sequence.flat_map do |child_item|
+        build_sequence(child_item, context)
+      end
+
+      dedup_sequence(flattened_sub_sequence + [item])
+    end
+
+    # Given a middleware sequence, filter out items not applicable to the
+    # current request, and set up a chain of instantiated middleware objects,
+    # ready to serve a request.
+    def build_request_chain(sequence, context)
+      chain_items = filter_sequence(sequence, context)
+      chain_items.reverse.reduce(nil) do |successor, item|
+        item.build_middleware(context, successor)
+      end
+    end
+
+    private
+
+    # Trigger ActiveSupport::Notification
+    def publish(name, *args)
+      ActiveSupport::Notifications.publish(name, *args)
+    end
+
+    # Remove middleware that have been included multiple times with the same
+    # config, leaving only the first instance
+    def dedup_sequence(sequence)
+      sequence.uniq { |item| [item.class, item.middleware, item.config] }
+    end
+
+    # Filter out middleware items that don't apply to this request - i.e. those
+    # that have defined an `if` condition that doesn't match this context.
+    def filter_sequence(sequence, context)
+      sequence.select { |item| item.use_with_context?(context) }
+    end
+
+    # Event to send for start of handler
+    def start_event(context)
+      {
+        middleware: @root_item.middleware.name,
+        request: context[:request]
+      }
+    end
+  end
+end

data/lib/coach/middleware.rb

@@ -0,0 +1,96 @@
+require "coach/middleware_item"
+
+module Coach
+  class Middleware
+    def self.uses(middleware, config = {})
+      middleware_dependencies << MiddlewareItem.new(middleware, config)
+    end
+
+    def self.middleware_dependencies
+      @middleware_dependencies ||= []
+    end
+
+    def self.provided
+      @provided ||= []
+    end
+
+    def self.provides(*new_provided)
+      provided.concat(new_provided)
+      provided.uniq!
+    end
+
+    def self.provides?(requirement)
+      provided.include?(requirement)
+    end
+
+    def self.requirements
+      @requirements ||= []
+    end
+
+    def self.requires(*new_requirements)
+      requirements.concat(new_requirements)
+      requirements.uniq!
+
+      new_requirements.each do |requirement|
+        define_method(requirement) { @_context[requirement] }
+      end
+    end
+
+    attr_reader :next_middleware, :config
+
+    # Middleware gets access to a shared context, which is populated by other
+    # middleware futher up the stack, a reference to the next middleware in
+    # the stack, and a config object.
+    def initialize(context, next_middleware = nil, config = {})
+      @_context = context
+      @next_middleware = next_middleware
+      @config = config
+    end
+
+    # `request` is always present in context, and we want to give every
+    # middleware access to it by default as it's always present and often used!
+    def request
+      @_context[:request]
+    end
+
+    # Make values available to middleware further down the stack. Accepts a
+    # hash of name => value pairs. Names must have been declared by calling
+    # `provides` on the class.
+    def provide(args)
+      args.each do |name, value|
+        unless self.class.provides?(name)
+          raise NameError, "#{self.class} does not provide #{name}"
+        end
+
+        @_context[name] = value
+      end
+    end
+
+    # Use ActiveSupport to instrument the execution of the subsequent chain.
+    def instrument
+      proc do
+        ActiveSupport::Notifications.
+          publish('coach.middleware.start', middleware_event)
+        ActiveSupport::Notifications.
+          instrument('coach.middleware.finish', middleware_event) { call }
+      end
+    end
+
+    # Helper to access request params from within middleware
+    delegate :params, to: :request
+
+    # Most of the time this will be overridden, but by default we just call
+    # the next middleware in the chain.
+    delegate :call, to: :next_middleware
+
+    private
+
+    # Event for ActiveSupport
+    def middleware_event
+      {
+        middleware: self.class.name,
+        request: request
+      }
+    end
+  end
+end

data/lib/coach/middleware_item.rb

@@ -0,0 +1,31 @@
+require "coach/errors"
+require "coach/middleware_validator"
+
+module Coach
+  class MiddlewareItem
+    attr_accessor :middleware, :config
+
+    def initialize(middleware, config = {})
+      @middleware = middleware
+      @config = config
+    end
+
+    def build_middleware(context, successor)
+      @middleware.new(context, successor && successor.instrument, @config)
+    end
+
+    # Requires tweaking to make it run methods by symbol on the class from which the
+    # `uses` call is made.
+    def use_with_context?(context)
+      return true if @config[:if].nil?
+      return @config[:if].call(context) if @config[:if].respond_to?(:call)
+      middleware.send(@config[:if], context)
+    end
+
+    # Runs validation against the middleware chain, raising if any unmet dependencies are
+    # discovered.
+    def validate!
+      MiddlewareValidator.new(middleware).validated_provides!
+    end
+  end
+end

data/lib/coach/middleware_validator.rb

@@ -0,0 +1,39 @@
+require "coach/errors"
+
+module Coach
+  class MiddlewareValidator
+    def initialize(middleware, already_provided = [])
+      @middleware = middleware
+      @already_provided = already_provided
+    end
+
+    # Aggregates provided keys from the given middleware, and all the middleware it uses.
+    # Can raise at any level assuming a used middleware is missing a required dependency.
+    def validated_provides!
+      if missing_requirements.any?
+        raise Coach::Errors::MiddlewareDependencyNotMet.new(
+          @middleware, missing_requirements
+        )
+      end
+
+      @middleware.provided + provided_by_chain
+    end
+
+    private
+
+    def missing_requirements
+      @middleware.requirements - provided_by_chain
+    end
+
+    def provided_by_chain
+      @provided_by_chain ||=
+        middleware_dependencies.reduce(@already_provided) do |provided, middleware|
+          provided + self.class.new(middleware, provided).validated_provides!
+        end.flatten.uniq
+    end
+
+    def middleware_dependencies
+      @middleware_dependencies ||= @middleware.middleware_dependencies.map(&:middleware)
+    end
+  end
+end

data/lib/coach/notifications.rb

@@ -0,0 +1,88 @@
+require_relative 'request_benchmark'
+require_relative 'request_serializer'
+
+module Coach
+  # By default, Coach will trigger ActiveSupport::Notifications at specific times in a
+  # request lifecycle.
+  #
+  # Notifications is used to coordinate the listening and aggregation of these middleware
+  # notifications, while RequestEvent processes the published data.
+  #
+  # Once a request has completed, Notifications will emit a 'coach.request' with
+  # aggregated request data.
+  class Notifications
+    # Begin processing/emitting 'coach.request's
+    def self.subscribe!
+      instance.subscribe!
+    end
+
+    # Cease to emit 'coach.request's
+    def self.unsubscribe!
+      instance.unsubscribe!
+    end
+
+    def self.instance
+      @instance ||= new
+    end
+
+    def subscribe!
+      return if active?
+
+      @subscriptions << subscribe('handler.start') do |_, event|
+        @benchmarks[event[:request].uuid] = RequestBenchmark.new(event[:middleware])
+      end
+
+      @subscriptions << subscribe('middleware.finish') do |name, start, finish, _, event|
+        log_middleware_finish(event, start, finish)
+      end
+
+      @subscriptions << subscribe('handler.finish') do |name, start, finish, _, event|
+        log_handler_finish(event, start, finish)
+      end
+    end
+
+    def unsubscribe!
+      return unless active?
+      while @subscriptions.any?
+        ActiveSupport::Notifications.unsubscribe(@subscriptions.pop)
+      end
+      true
+    end
+
+    def active?
+      @subscriptions.any?
+    end
+
+    private_class_method :new
+
+    private
+
+    def initialize
+      @benchmarks = {}
+      @subscriptions = []
+    end
+
+    def subscribe(event, &block)
+      ActiveSupport::Notifications.subscribe("coach.#{event}", &block)
+    end
+
+    def log_middleware_finish(event, start, finish)
+      benchmark_for_request = @benchmarks[event[:request].uuid]
+      return unless benchmark_for_request.present?
+      benchmark_for_request.notify(event[:middleware], start, finish)
+    end
+
+    def log_handler_finish(event, start, finish)
+      benchmark = @benchmarks.delete(event[:request].uuid)
+      benchmark.complete(start, finish)
+      broadcast(event, benchmark)
+    end
+
+    def broadcast(event, benchmark)
+      serialized = RequestSerializer.new(event[:request]).serialize.
+        merge(benchmark.stats).
+        merge(event.slice(:response))
+      ActiveSupport::Notifications.publish('coach.request', serialized)
+    end
+  end
+end

data/lib/coach/request_benchmark.rb

@@ -0,0 +1,59 @@
+module Coach
+  # This class is built to aggregate data during the course of the request. It relies on
+  # 'coach.middleware.start' and 'coach.middleware.end' events to register the
+  # start/end of each middleware element, and thereby calculate running times for each.
+  #
+  # Coach::Notifications makes use of this class to produce benchmark data for
+  # requests.
+  class RequestBenchmark
+    def initialize(endpoint_name)
+      @endpoint_name = endpoint_name
+      @events = []
+    end
+
+    def notify(name, start, finish)
+      event =  { name: name, start: start, finish: finish }
+
+      duration_of_children = child_events_for(event).
+        inject(0) { |total, e| total + e[:duration] }
+      event[:duration] = (finish - start) - duration_of_children
+
+      @events.push(event)
+    end
+
+    def complete(start, finish)
+      @duration = finish - start
+    end
+
+    # Serialize the results of the benchmarking
+    def stats
+      {
+        endpoint_name: @endpoint_name,
+        duration: format_ms(@duration),
+        chain: sorted_chain.map do |event|
+          { name: event[:name], duration: format_ms(event[:duration]) }
+        end
+      }
+    end
+
+    private
+
+    def previous_event
+      @events.last
+    end
+
+    def child_events_for(parent)
+      @events.select do |child|
+        parent[:start] < child[:start] && child[:finish] < parent[:finish]
+      end
+    end
+
+    def sorted_chain
+      @events.sort_by { |event| event[:start] }
+    end
+
+    def format_ms(duration)
+      (1000 * duration).round
+    end
+  end
+end