commute 0.2.0.rc.2 → 0.3.0.pre

data/lib/commute/core/sequence.rb

@@ -1,16 +1,29 @@
-require 'commute/core/commuter'
+require 'commute/core/layer'
 
 module Commute
 
-  # Internal: A Sequence is an ordered list of processors, that all
-  # work together to incrementally process a Commuter.
+  # Internal: A Sequence is an ordered list of Layers.
+  # It is a thin layer around an Array that enables it to
+  # add/remove/replace Layers more easily.
   #
-  class Sequence
+  # Examples
+  #
+  # Sequence.new do
+  #   append Commute::Common::Auth::Basic, as: :auth
+  #   append Commute::Common::Json::Render, before: :auth
+  #   replace :auth, Commute::Common::Auth::OAuth
+  # end
+  #
+  class Sequence < Array
 
-    # Public: Initializes a sequence without processors.
-    def initialize &alter
-      @processors = []
-      @index = {}
+    # Internal: Name of this Sequence.
+    attr_reader :name
+
+    # Public: Initializes a sequence without layers.
+    # Alters the Sequence if a block is given.
+    def initialize name, &alter
+      super()
+      @name = name
       self.alter &alter if block_given?
     end
 
@@ -30,151 +43,89 @@ module Commute
       return self
     end
 
-    # Returns an duplicate collection of processors.
-    def processors
-      @processors.clone
-    end
+    # Alias Array#insert.
+    alias :index_insert :insert
 
-    # Internal: Processes a commuter with al processors in the sequence.
+    # Public: Appends a layer to a the list of layers.
     #
-    # When a commuter provides parameters for a processor through the
-    # parameters method, given the processor id. Then those parameters
-    # are passed as an argument to the call method of the processor (if applicable).
+    # options - Optional parameters for layer naming and placement (default: {}):
+    #           :as    - The name of the layer in the sequence (optional).
+    #           :after - A reference layer id after which the processor needs to be appended.
     #
-    # Returns Nothing.
-    def call commuter, options = {}
-      call_one 0, commuter
-    end
-
-    def call_one index, commuter
-      # Get the processor using the index.
-      processor = @processors[index]
-      # Immediately return if no processor is found.
-      return nil unless processor
-      # Identify the processor.
-      # TODO: not very performant
-      processor_id = @index.key processor
-      # Immediately jumpt to the next processor if this one is disabled.
-      if commuter.enabled? processor_id
-        # Get the parameters.
-        parameters = commuter.parameters(processor_id) if processor_id
-        # Calling the processor.
-        if parameters
-          processor.call commuter, parameters
-        else
-          processor.call commuter
-        end
-      end
-      # Call self for the next processor.
-      call_next = Proc.new { call_one index + 1, commuter }
-      if commuter.delayed?
-        commuter.wait &call_next
-      else
-        call_next.call
-      end
+    # Returns the appended processor.
+    def append callable, options = {}
+      # Create a layer.
+      layer = Layer.new(callable, options[:as])
+      # Index to insert at.
+      index = (options[:after] && layer_index(options[:after])+1) || -1
+      # Append the layer.
+      index_insert index, layer
+      # Return the appended layer.
+      layer
     end
 
-    # Public: Appends a processor to a the list of processors.
+    # Public: Inserts a layer to a the list of layers.
     #
-    # options - Optional parameters for processor naming and placement (default: {}):
-    #           :as    - The name of the processor in the sequence (optional).
-    #           :after - A reference processor id after which the processor needs to be appended.
+    # options - Optional parameters for layer naming and placement (default: {}):
+    #           :as    - The name of the layer in the sequence (optional).
+    #           :after - A reference layer id before which the processor needs to be inserted.
     #
     # Returns the appended processor.
-    def append processor, options = {}
-      # When a reference is given, append after it.
-      if options[:after]
-        @processors.insert id_index(options[:after]) + 1, processor
-      else
-        @processors << processor
-      end
-      # Identify the processor using different methods.
-      id = identify processor, options[:as]
-      # Add the processor to the index for direct access purposes.
-      @index[id] = processor if id
-      # Return the appended processor.
-      processor
-    end
-
-    # TODO
-    def insert processor, options = {}
-      # When a reference is given, insert before it.
-      if options[:before]
-        @processors.insert id_index(options[:before]) - 1, processor
-      else
-        @processors.unshift processor
-      end
-      # Identify the processor using different methods.
-      id = identify processor, options[:as]
-      # Add the processor to the index for direct access purposes.
-      @index[id] = processor if id
-      # Return the appended processor.
-      processor
+    def insert callable, options = {}
+      # Create a layer.
+      layer = Layer.new(callable, options[:as])
+      # Index to insert at.
+      index = (options[:before] && layer_index(options[:before])) || 0
+      # Append the layer.
+      index_insert index, layer
+      # Return the appended layer.
+      layer
     end
 
-    # TODO TEST
-    def replace processor_id
-      processor = at processor_id
-      raise "processor does not exist #{processor_id}" unless processor
-      replacement = yield processor
-      @processors[@processors.index processor] = replacement
-      @index[processor_id] = replacement
-    end
-
-    # Public: Removes a processor from the sequence.
+    # Public: Removes a layer from the sequence.
     #
-    # When a processor object is given, the processor is removed. When its
-    # Symbol identifier is given, the associated processor is removed.
+    # name - The name of the layer to be removed.
     #
-    # Returns the removed processor.
-    def remove processor
-      if processor.is_a?(Symbol)
-        processor_id = processor
-        processor = at(processor)
-        @processors.delete processor
-        @index.delete processor_id
-      else
-        # Remove from list of processors.
-        @processors.delete processor
-        # Remove from index (if necessary).
-        @index.delete_if { |id, pr| pr == processor}
-      end
-      # Return the deleted processor.
-      processor
+    # Returns the removed layer.
+    def remove name
+      # Remove the layer.
+      delete_at layer_index(name)
     end
 
-    # Public
-    # Returns the processor with the given id.
+    # Public: Replaces a layer in the sequence.
     #
-    # id - The Symbol identifier of a processor.
-    def at id
-      @index[id]
+    # name  - The name of the layer to be replaced.
+    # layer - The callable to replace it with.
+    #
+    # Returns the new layer.
+    def replace name, callable
+      self[layer_index name] = Layer.new callable, name
     end
 
-    # Internal: Clones the sequence.
-    def dup
-      Sequence.new.tap do |sequence|
-        sequence.processors = @processors.clone
-        sequence.index = @index.clone
-      end
+    # Internal: Lazily adds the sequence (as a Layer)
+    # with this name to the router path.
+    #
+    # Lazily here means that when this sequence is added as a Layer
+    # it is not necessarely complete yet. Layers could be appended or
+    # removed later on. Therefor, the sequence is fetched from
+    # the current context.
+    #
+    def call router, request, options = {}
+      context = request.http.context
+      router << context.stack.sequence(name).reject { |layer|
+        !layer.callable?(context)
+      }.each
+      router.succ.call router, request
     end
 
     private
 
-    def identify processor, override = nil
-      if override
-        override
-      else
-        processor.class.instance_variable_get :@id
-      end
-    end
-
-    def id_index id
-      @processors.index at(id)
+    # Internal: Returns the index of a layer.
+    #
+    # name - The name of the layer.
+    #
+    def layer_index name
+      index { |layer| layer.name == name }
     end
-
-    protected
-
-    attr_writer :processors, :index
   end
 end

data/lib/commute/core/stack.rb

@@ -1,76 +1,61 @@
 require 'commute/core/sequence'
+require 'commute/core/util/path'
 
 module Commute
 
   # Internal: A stack is a collection of sequences with
   # A main sequence uses as a starting point for processing.
   #
-  # When the stack is called with a processable, it gets
+  # When the stack is called with a request, it gets
   # processed by the main sequence. That main sequence
   # can easily "embed" other sequences by adding them as
-  # a processer (a sequence is also a processor).
+  # a layer (a sequence is also a layer (composite)).
   #
   # Example:
   #
-  #   stack = Stack.new do |stack, sequence|
-  #     stack.sequence(:calculation) do
-  #       append Proc.new { |n| n.data += 1 }
-  #       append Proc.new { |n| n.data *= 2 }
+  #   stack = Stack.new do
+  #     sequence(:request_body) do
+  #       append Commute::Common::Json::Render
+  #       append Commute::Common::Auth::Basic
   #     end
   #
-  #     sequence.append stack.sequencer(:calculation)
-  #     sequence.append Proc.new { |p| p.process { |n| "The result is #{n}" }}
+  #     sequence.append sequence(:request_body)
   #  end
   #
-  #  stack.call Processable.new(context, 1)
-  #  # => "The result is 4"
+  #  request = stack.call Request.new(context) do |response, status|
+  #    # Process the response.
+  #  end
+  #  request.write data
+  #  request.end
   #
   class Stack
 
-    # Public: Constructs a stack with a main sequence.
-    #
-    # sequence - Sequence used as main sequence.
-    #
-    # Yields
-    #   1. The Stack itself. (If the arity of the block is 2)
-    #   2. a new sequence to use a main sequence when no
-    #      sequence is explicitely given.
+    # Internal: A Router that routes http request to the next layer.
     #
-    # Raises an error if neither is given.
+    # The router wraps the Http Request in a Layer Request and
+    # attaches the correct handler to the response event.
     #
-    # Returns a Stack with a main sequence.
-    def initialize sequence = nil, &main
-      @sequences = {}
-      @main = if sequence
-        sequence
-      else
-        if main.arity == 1
-          Sequence.new &main
-        else
-          sequence = Sequence.new
-          yield self, sequence
-          sequence
+    class Router < Path
+
+      # Public: Call the next layer.
+      #
+      # http - Http Request to send to the next layer on the Path.
+      #
+      # Yields a response and a status.
+      # Returns the Layer Request.
+      def call http, &on_response
+        Layer::Request.new(http).tap do |request|
+          request.on :response, &on_response
+          succ.call self, request
         end
       end
     end
 
-    # Public: Adds a sequence to the stack.
-    #
-    # sequence - The Sequence to be added.
-    # name     - The name of the sequence.
-    #
-    # Returns the Sequence that was added.
-    def add sequence, name
-      @sequences[name] = sequence
-    end
-
-    # Public: Get a sequence from the stack.
-    #
-    # name - The name of the wanted Sequence.
-    #
-    # Returns the asked sequence.
-    def get name
-      @sequences[name]
+    # Public: Constructs a stack with a main sequence.
+    # Akter the Stack if a block is given.
+    def initialize &alter
+      @sequences = {}
+      self.alter &alter if block_given?
     end
 
     # Public: Manipulate an either existing or new sequence.
@@ -84,25 +69,10 @@ module Commute
     #
     # Returns the Sequence.
     def sequence name = nil, &alter
-      if name
-        @sequences[name] || add(Sequence.new(&alter), name)
-      else
-        @main
-      end
-    end
-
-    # Public: Creates a processor that lazily fetches a named sequence
-    # on a call.
-    #
-    # name - The name of the sequence this sequencer stands in for.
-    #
-    # Returns a Sequencer
-    def sequencer name = nil
-      if name
-        Sequencer.new.here(name)
-      else
-        Sequencer.new
-      end
+      name ||= :main
+      sequence = @sequences[name] || add(Sequence.new name)
+      sequence.alter &alter if block_given?
+      sequence
     end
 
     # Internal: Calls the stack aka call the main sequence.
@@ -110,8 +80,9 @@ module Commute
     # processable - The thing to process.
     #
     # Returns the processable
-    def call processable
-      @main.call processable
+    def call request, &on_response
+      router = Router.new([sequence].each)
+      router.call request, &on_response
     end
 
     # Public: Alters the stack.
@@ -124,19 +95,39 @@ module Commute
       if alter.arity == 0
         instance_eval &alter
       else
-        yield self, @main
+        yield self
       end
       # Return the Stack.
       return self
     end
 
-    # Internal: Clones the sequence.
+    # Internal: Duplicates the stack.
     def dup
-      Stack.new(@main.dup).tap do |stack|
+      Stack.new.tap do |stack|
         stack.sequences = Hash[@sequences.map { |k,v| [k, v.dup] }]
       end
     end
 
+    private
+
+    # Internal: Adds a sequence to the stack.
+    #
+    # sequence - The Sequence to be added.
+    #
+    # Returns the Sequence that was added.
+    def add sequence
+      @sequences[sequence.name] = sequence
+    end
+
+    # Internal: Get a sequence from the stack.
+    #
+    # name - The name of the wanted Sequence.
+    #
+    # Returns the asked sequence.
+    def get name
+      @sequences[name]
+    end
+
     protected
 
     attr_writer :sequences

data/lib/commute/core/status.rb

@@ -0,0 +1,45 @@
+module Commute
+
+  # Public: A Generic status object that can represent
+  # either a positive or negative status.
+  #
+  # When the status is negative, an additional error
+  # detail can be provided.
+  #
+  # Examples
+  #
+  #   Status.new false, { reason: 'No access' }
+  #   Status.ok # Same as Status.new true
+  #
+  class Status
+
+    # Public: Creates a positive status.
+    #
+    def self.ok
+      self.new
+    end
+
+    # Public: Creates a new status object.
+    #
+    # success - Whether the status is positive or not (default: true).
+    # error   - Optional error detail (can be anything).
+    #
+    def initialize success = true, error = nil
+      @success = success
+    end
+
+    # Public: Check if a status is a success.
+    #
+    # Returns true if the status is positive.
+    def success?
+      @success
+    end
+
+    # Public: Check if a status is a fail.
+    #
+    # Returns true if the status is negative.
+    def fail?
+      !success?
+    end
+  end
+end

data/lib/commute/core/util/event_emitter.rb

@@ -0,0 +1,58 @@
+module Commute
+
+  # Internal: A Simple EventEmitter modelled after node.js' EventEmitter.
+  # More info: http://nodejs.org/api/events.html
+  #
+  # Include this module in any model that wants to send events to its listeners.
+  #
+  # Listen to events using `on(:event)`. In the model, notify listeners
+  # by calling `emit(:event, ...)` with some arguments.
+  module EventEmitter
+
+    # Internal: Initializes an empty handler hash.
+    def initialize *args
+      super *args
+      @handlers = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Internal: Subscribe a handler to an event.
+    #
+    # event   - The name of the event to listen for.
+    # handler - The proc to call when this event occurs.
+    #
+    # Returns Nothing.
+    def on event, &handler
+      @handlers[event] << handler
+      nil
+    end
+
+    # Internal: Subscribe a handler to an event and
+    # unsuscribe it when the event fired once.
+    #
+    def once event, &handler
+      on event do |*args, &block|
+        handler.call *args, &block
+        remove event, handler
+      end
+    end
+
+    # Internal: Remove an event handler.
+    def remove event, handler
+      @handlers[event].delete handler
+    end
+
+    protected
+
+    # Internal: Emit an event to all handlers.
+    #
+    # event - The name of the event.
+    # args  - Arguments to send to the listeners.
+    #
+    # Returns the notified handlers.
+    def emit event, *args
+      @handlers[event].each do |handler|
+        handler.call *args
+      end
+    end
+  end
+end

data/lib/commute/core/util/path.rb

@@ -0,0 +1,37 @@
+module Commute
+
+  # Internal: A Path is that wraps some enums and
+  # returns there values in the order that you added them.
+  #
+  class Path
+
+    # Internal: Initialize the path with a main route.
+    #
+    # main - An enumerable to start the path with.
+    #
+    def initialize main
+      @path = []
+      self << main
+    end
+
+    # Internal: Push a route on the path (detour).
+    #
+    # route - An enumerable to walk first before continuing.
+    def << route
+      @path << route
+    end
+
+    # Internal: Figures out the successor in the path.
+    #
+    # Returns the next stop on the path.
+    def succ
+      begin
+        return nil if @path.empty?
+        @path.last.next
+      rescue StopIteration
+        @path.pop
+        retry
+      end
+    end
+  end
+end