commute 0.2.0.rc.2 → 0.3.0.pre

data/lib/commute/core/builder.rb

@@ -54,7 +54,7 @@ module Commute
     end
 
     # Public: Adds logical parameters to the context.
-    # Logocal parameters whose names match the id of a
+    # Logical parameters whose names match the id of a
     # layer, get passed to that layer as options.
     #
     # When a parameter is set to nil, it is excluded
@@ -188,7 +188,7 @@ module Commute
     end
 
     # Same as `transform` but removes all existing transformations for these dependencies.
-    def transform! *dependencies, &transformation
+    def transform! name, *dependencies, &transformation
     end
 
     # Public: Used to alter the stack or one of its sequences.
@@ -233,19 +233,8 @@ module Commute
       end
     end
 
-    # TODO
-    def limit max
-      with limit: max
-    end
-
-    # TODO
-    def offset index
-      with offset: index
-    end
-
-    # TODO
-    def order field, direction = :asc
-      with order: { field: field, direction: direction }
+    def body body
+      with! body: body
     end
 
     private

data/lib/commute/core/context.rb

@@ -2,14 +2,61 @@ require 'forwardable'
 
 require 'commute/core/builder'
 require 'commute/core/stack'
-require 'commute/core/builder'
+require 'commute/core/http'
 
+# A context is a snapshot of a builder. It holds partial
+# information on how to build and execute a request.
+#
+# This is:
+#   * A stack
+#   * Logical parameters
+#   * Transformation that transform logical parameters into request parameters
+#   * Disables (for skipping layers)
+#
+# When a context holds enough information to execute a request, you
+# can execute it in 6 different ways (depending on your adapter):
+#
+# 1) Run Synchronously.
+#   paste, status[, response] = pastes.find(1).run
+#   pasted, status[, response] = api.create.run("Some paste")
+#   # OR
+#   pasted, status[, response] = api.put.one.run("Some paste")
+#
+# 2) Run Synchronously unsafe
+#   paste = pasted.find(1).run!
+#
+# 3) Run Asynchronously.
+#   pastes.find(1).run { |paste[, status[, response]]| ... }
+#
+# 4) Stream (down)
+#   pastes.all.stream { |response, status|
+#     # Received a response.
+#     response.on(:data) { |paste| ... }
+#     response.on(:end) { ... }
+#   }
+#
+# 5) Stream unsafe (down)
+#   pastes.all.stream! { |paste|
+#   }
+#
+# 6) The full treatment (up and downstreaming)
+#   request = pastes.all.request { |response, status|
+#   }
+#   request.write ...
+#   request.end
+#
 module Commute
   class Context
     include Buildable
 
+    # Public: All information needed to build and execute a request.
     attr_reader :stack, :parameters, :transformations, :disables
 
+    # Internal: Creates a new context. A developer never has to call
+    # this method manually.
+    #
+    # It sets up a snapshot of a builder and freezes all information.
+    #
     def initialize stack = nil, parameters = {}, transformations = [], \
        disables = [], builder_class = Builder
       @stack = stack.freeze
@@ -19,32 +66,111 @@ module Commute
       @builder_class = builder_class
     end
 
+    # Public: Get a logical parameter.
+    #
+    # key - The key of the logical parameter.
+    #
+    # Returns the value of the logical parameter.
     def [] key
       @parameters[key]
     end
 
-    # Public: Creates a new context, resetting all transformations.
+    # Public: Check if a layer is enabled.
     #
+    # name - The name of the layer in question.
+    #
+    # Returns `true` if the layer is enabled in the current context.
+    def enabled? name
+      !disables.include?(name)
+    end
+
+    # Internal: Creates a new context, resetting all transformations.
     def reset
+      self.class.new stack, parameters, [], disables, builder_class
     end
 
-    # Returns the
-    def run &on_complete
-      context = on_complete ? with(on_complete: on_complete) : self
-      commuter = Commuter.new context
-      @stack.call commuter
-      commuter.get
+    # Public: Down and Upstream any content (safely).
+    # The Full Treatment.
+    #
+    # Yields Layer Response and a status.
+    # Returns a Layer Request.
+    #
+    def request &on_response
+      @stack.call self.build, &on_response
     end
 
-    def run! *args, &block
-      result = self.run(*args, &block)
-      if result.kind_of?(Array)
-        result.first
-      else
-        result
+    # Public: Downstream any remote content (safely).
+    #
+    # body - Optional body to send with the request.
+    #
+    # Yields a Layer Response and a status.
+    # Returns Nothing.
+    #
+    def stream body = self[:body], &on_response
+      self.request(&on_response).tap do |request|
+        request.write body if body
+        request.end
       end
+      # Return Nothing.
+      nil
     end
 
+    # Public: Downstream any remote content (unsafely).
+    #
+    # body - Optional body to send with the request.
+    #
+    # Yields for every chunk of body/result streamed.
+    # Returns Nothing.
+    #
+    def stream! body = self[:body], &on_data
+      self.stream do |response, status|
+        response.on :end, &on_data
+      end
+      # Return Nothing.
+      nil
+    end
+
+    # Public: Run (a)synchronously, only returns if data is fully
+    # received. Direct return only possible with synchronous adapter.
+    #
+    # body - Optional body to send with the request.
+    #
+    # Yields the buffered data, status and response. (sync)
+    # Returns the buffered data, status and response. (sync/async)
+    #
+    def run body = self[:body], &on_result
+      # Temprary result variable in this scope.
+      result, status, response = nil, nil, nil
+      # Stream the response.
+      self.stream(body) do |_response, _status|
+        # Set status.
+        status, response = _status, _response
+        # Buffer all data in result.
+        response.once(:data) { |_result| result = _result }
+        # Call on_result in the end.
+        response.on(:end) do
+          on_result.call result, status, response if on_result
+        end
+      end
+      # Also just return the result.
+      return result, status, response
+    end
+
+    # Public: Run synchronously unsafe.
+    # Only returns data when fully buffered, without a status.
+    #
+    # body - Optional body to send with the request.
+    #
+    # Returns the buffered data.
+    #
+    def run! body = self[:body]
+      return self.run(body).first
+    end
+
+    # Internal: Methods not defined on Context trigger
+    # the creation of a builder.
+    #
+    # The method is then forwarded to the builder.
     def method_missing method, *args, &block
       b = builder
       if b.respond_to?(method)
@@ -54,8 +180,23 @@ module Commute
       end
     end
 
-    private
+    protected
 
+    # Internal: Build a Http Request using context transformations.
+    #
+    def build
+      # Create a new request.
+      http_request = Http::Request.new(self)
+      # Build the request using context transformations.
+      @transformations.each do |t|
+        t.call http_request, self
+      end
+      # Return the http request.
+      http_request
+    end
+
+    # Internal: Creates a new Builder for this context.
+    #
     def builder
       @builder_class.new self
     end

data/lib/commute/core/http.rb

@@ -0,0 +1,124 @@
+require 'uri'
+
+require 'commute/core/status'
+
+module Commute
+
+  # Collection of model classes associated with Http.
+  module Http
+
+    # Public: Status that derives its ok status from a given
+    # Http status code.
+    #
+    class Status < Commute::Status
+      attr_reader :code
+
+      # Public: Creates a new Http Status.
+      #
+      # code  - Http Status code.
+      # error - Optional error details (Can be anything).
+      #
+      def initialize code, error = nil
+        super !(400..599).include?(code)
+        @code = code
+      end
+
+      def not_modified?
+        @code == 304
+      end
+    end
+
+    # Public: A Http connection to a host/port with a certain protocol.
+    class Connection
+
+      # Public: Uri of the host (containing scheme, host and port).
+      attr_reader :uri
+    end
+
+    # Public: A Http Request.
+    class Request
+
+      # Public: The context in which the Http Request is made.
+      attr_reader :context
+
+      # Public: Uri of EATS (Everything after the slash).
+      attr_accessor :uri
+
+      # Public: Url parameters (Hash).
+      attr_accessor :query
+      alias :params :query
+      alias :params= :query=
+
+      # Public: The HTTP Method of the request (Symbol).
+      # Mostly :get, :post, :put, :patch, :delete
+      attr_accessor :method
+
+      # Public: Request headers.
+      attr_accessor :headers
+
+      # Public: Optional connection associated with this request.
+      attr_reader :connection
+
+      # Public: Initializes a new Http Request with some default values.
+      #
+      # context - The context in which the Http Request is made.
+      #
+      def initialize context
+        @context = context
+        @uri = URI::Generic.build path: '/'
+        @headers = {}
+        @query = {}
+        @method = :get
+      end
+
+      # Public: Getting the Http method.
+      #
+      # Overload the default reader method for overloading
+      # of Object#method.
+      #
+      def method name = nil
+        name.nil? ? @method : super(name)
+      end
+
+      # Public: Get the URI of the Request.
+      #
+      # Override the default reader method for consistency
+      # with the query setter method on Request.
+      # We first merge the query string into the URI before
+      # returning it.
+      #
+      def uri
+        @uri.query = URI.encode_www_form_component( \
+          URI.encode_www_form(self.query)
+        ) if !self.query.empty?
+        @uri
+      end
+    end
+
+    # Public: An Http Response.
+    class Response
+
+      # Public: The request responsible for this response.
+      attr_accessor :request
+
+      # Public: Http Response code.
+      attr_accessor :code
+
+      # Public: Request headers.
+      attr_accessor :headers
+
+      # Public: Initializes a new Http Response with a reference Request.
+      #
+      # request - The request responsible for this response.
+      #
+      def initialize request
+        @request = request
+        @headers = {}
+      end
+
+      def etag
+        headers['ETag']
+      end
+    end
+  end
+end

data/lib/commute/core/layer.rb

@@ -0,0 +1,187 @@
+require 'commute/core/util/event_emitter'
+require 'commute/core/util/stream'
+
+module Commute
+
+  # Internal: A Layer is one processing piece in a commute stack.
+  #
+  # A layer acts as a mini in-process server that takes its own
+  # requests (Layer::Request) and issues its own requests (to the
+  # next layer in the stack). Therefor implementing a layer
+  # gives you alot of rope to work with.
+  #
+  # Think of layers as seperate network components that call
+  # each other in a russian-doll model with the adapter as
+  # the most inner doll.
+  #
+  # The Layer requests and response are only for communication
+  # between the layers, they carry the real http requests
+  # and responses (access at Request#http and Response#http).
+  #
+  # The Spec for a layer is documented hereafter.
+  #
+  # A layer implements a call method that takes a router, request
+  # and some options from the context of that request
+  # meant for the layer.
+  #
+  # The router is a the router that a connects all layers of
+  # stack needed for this request.
+  #
+  # Take a simple layer that does not call the next layer,
+  # but just echoes all that is sent to it.
+  #
+  #   def call router, request, options = {
+  #     # Respond to the request right away.
+  #     response = request.respond Response.new, Status.ok
+  #     # Echo all data.
+  #     request.on(:data) do |chunk|
+  #       response.write chunk
+  #     end
+  #     # When the request ends, we also have no use anymore.
+  #     request.on(:end) { response.end }
+  #  end
+  #
+  # Sidenote: We could also have written
+  #
+  #   def call router, request, options = {}
+  #     # Respond to the request right away.
+  #     response = request.respond Response.new
+  #     # Connect the incoming stream with the outgoing stream.
+  #     request.pipe response
+  #   end
+  #
+  # A bit more complex example that shows the entire spec
+  # is a layer does nothing but two-way forwarding (short with piping).
+  #
+  #   def call router, request, options = {}
+  #     # Forward the request to the next layer.
+  #     proxy_request = router.call request.http do |response, status|
+  #       proxy_response = request.respond response.http, status
+  #       response.pipe proxy_response
+  #     end
+  #
+  #     request.pipe proxy_request
+  #   end
+  #
+  class Layer
+
+    # Internal: Base class for Request and Response.
+    # Includes some modules by default.
+    class Communication
+      include EventEmitter
+      include Stream
+
+      attr_reader :http
+
+      # Internal: Creates a new Request/Response.
+      #
+      # http - Underlaying http Request/Response.
+      #
+      def initialize http
+        super()
+        @http = http
+      end
+    end
+
+    # Public: An inter-Layer Request.
+    #
+    # Includes EventEmitter to listen for responses, data and request end.
+    # Includes Stream for stream-uploading.
+    #
+    class Request < Communication
+
+      # Public: Respond to a Request using a Http Response.
+      # The http response the gets wrapped in a Layer Response.
+      #
+      # http   - Http Response for this Request.
+      # status - Any status indications for the Response.
+      #
+      # Yields the Layer response and ends the response thereafter
+      # if a block is given.
+      #
+      # Returns the Layer Response.
+      def respond http, status, &lifecycle
+        Response.new(http).tap do |response|
+          emit :response, response, status
+          if block_given?
+            lifecycle.call response
+            response.end
+          end
+        end
+      end
+
+      # Public: Returns a responder for this request.
+      #
+      # A Responder will automatically handle a response
+      # from a layer and use it to respond to this request.
+      #
+      # It will pipe all data from the response to the response
+      # for this request.
+      #
+      # Returns a block that responds to this request.
+      def responder
+        proc do |response, status|
+          response.pipe self.respond(response.http, status)
+        end
+      end
+    end
+
+    # Public: An inter-Layer Response.
+    #
+    # Includes EventEmitter to listen for data and response end.
+    # Includes Stream for downloading data in chunks.
+    #
+    class Response < Communication
+    end
+
+    # Internal: Name of the Layer.
+    attr_reader :name
+
+    # Internal: Creates a new Layer.
+    #
+    # callable - Object with Layer logics that responds to #call.
+    # name     - Name of the Layer (optional).
+    #
+    def initialize callable, name = nil
+      @name = name \
+        || callable.class.instance_variable_get(:@name) \
+        || (callable.respond_to?(:name) && callable.name)
+      @callable = callable
+    end
+
+    # Internal: Call the Layer with options fetched out of the context
+    # using the name of the Layer.
+    #
+    # For example, when you add a Layer to a sequence and name it auth.
+    # And when you then call `with auth: { key: 'secret'}` on your
+    # builder, `key: 'secret' will be passed as options to the Layer.
+    #
+    # router  - Path of connected Layers.
+    # request - Request issued for this Layer.
+    #
+    # Returns Nothing
+    def call router, request, options = {}
+      @callable.call router, request, request.http.context[@name]
+      nil
+    end
+
+    # Internal: Checks if this Layer has to be called in a certain context.
+    #
+    # context - The context the Layer is called in.
+    #
+    # Returns true if the Layer has to be called.
+    def callable? context
+      !@callable.nil? && context.enabled?(name)
+    end
+
+    # Internal: Two layers are equal if there callables are equal.
+    def == layer
+      self.callable == layer.callable
+    end
+
+    protected
+
+    # Internal: The #call object where the logic of this Layer resides.
+    attr_reader :callable
+  end
+end