batch_api 0.1.1 → 0.2.0

data/changelog.md

@@ -1,3 +1,20 @@
+v0.2.0
+* Refactor app to use internal middlewares for handling operations
+* Refactor JSON decoding to a middleware
+* Remove timestamp option
+
+v0.1.4
+* Refactor errors into ErrorWrapper/BatchError
+* Allow specification of custom status codes raised for errors
+
+v0.1.3
+* Refactor config to use a struct
+* Update readme to cover HTTP pipelining
+
+v0.1.2
+* Rewrite the readme
+* Add travis icon
+
 v0.1.1
 * Fix dumb error
 

data/lib/batch_api.rb

@@ -2,7 +2,12 @@ require 'batch_api/configuration'
 require 'batch_api/version'
 require 'batch_api/utils'
 require 'batch_api/processor'
-require 'batch_api/middleware'
+
+require 'batch_api/internal_middleware'
+require 'batch_api/rack_middleware'
+
+require 'batch_api/error_wrapper'
+require 'batch_api/batch_error'
 
 module BatchApi
 

data/lib/batch_api/batch_error.rb

@@ -0,0 +1,41 @@
+module BatchApi
+  module Errors
+    # Public: a module that tags Batch API errors and provides a default
+    # status.
+    module BatchError
+      # Public: the status code for this type of error.
+      # Subclasses can change this as desired.
+      def status_code; 500; end
+    end
+
+    # Public: an error thrown if an invalid option is
+    # specificed.
+    class BadOptionError < ArgumentError
+      include BatchError
+      # Public: the status code for this error.
+      def status_code; 422; end
+    end
+
+    # Public: an error thrown if too many operations are provided.
+    class OperationLimitExceeded < ArgumentError
+      include BatchError
+      # Public: the status code for this error.
+      def status_code; 422; end
+    end
+
+    # Public: an error thrown if no operations are provided.
+    class NoOperationsError < ArgumentError
+      include BatchError
+      # Public: the status code for this error.
+      def status_code; 422; end
+    end
+
+    # Public: an error thrown if one of the batch operations
+    # is somehow invalid (missing key parameters, etc.).
+    class MalformedOperationError < ArgumentError
+      include BatchError
+      # Public: the status code for this error.
+      def status_code; 422; end
+    end
+  end
+end

data/lib/batch_api/configuration.rb

@@ -1,27 +1,37 @@
+require 'batch_api/internal_middleware'
+
 module BatchApi
-  # Batch API Configuration
-  class Configuration
-    # Public: configuration options.
-    # Currently, you can set:
-    # - endpoint: (URL) through which the Batch API will be exposed (default
-    # "/batch)
-    # - verb: through which it's accessed (default "POST")
-    # - limit: how many requests can be processed in a single request
-    # (default 50)
-    # decode_json_responses - automatically decode JSON response bodies,
-    # so they don't get double-decoded (e.g. when you decode the batch
-    # response, the bodies are already objects).
-    attr_accessor :verb, :endpoint, :limit
-    attr_accessor :decode_json_responses
-    attr_accessor :add_timestamp
+  # Public: configuration options.
+  # Currently, you can set:
+  # - endpoint: (URL) through which the Batch API will be exposed (default
+  # "/batch)
+  # - verb: through which it's accessed (default "POST")
+  # - limit: how many requests can be processed in a single request
+  # (default 50)
+  # - decode_json_responses: automatically decode JSON response bodies,
+  # so they don't get double-decoded (e.g. when you decode the batch
+  # response, the bodies are already objects).
+  #
+  # There are also two middleware-related options -- check out middleware.rb
+  # for more information.
+  # - global_middleware: any middlewares to use round the entire batch request
+  # (such as authentication, etc.)
+  # - per_op_middleware: any middlewares to run around each individual request
+  # (adding headers, decoding JSON, etc.)
+  CONFIGURATION_OPTIONS = {
+    verb: :post,
+    endpoint: "/batch",
+    limit: 50,
+    batch_middleware: InternalMiddleware::DEFAULT_BATCH_MIDDLEWARE,
+    operation_middleware: InternalMiddleware::DEFAULT_OPERATION_MIDDLEWARE
+  }
 
-    # Default values for configuration variables
+  # Batch API Configuration
+  class Configuration < Struct.new(*CONFIGURATION_OPTIONS.keys)
+    # Public: initialize a new configuration option and apply the defaults.
     def initialize
-      @verb = :post
-      @endpoint = "/batch"
-      @limit = 50
-      @decode_json_responses = true
-      @add_timestamp = true
+      super
+      CONFIGURATION_OPTIONS.each {|k, v| self[k] = v}
     end
   end
 end

data/lib/batch_api/error_wrapper.rb

@@ -0,0 +1,44 @@
+module BatchApi
+  # Public: wrap an error thrown during a batch operation.
+  # This has a body class and a cookies accessor and can
+  # function in place of a regular BatchResponse object.
+  class ErrorWrapper
+    # Public: create a new ErrorWrapper from an error object.
+    def initialize(error)
+      @error = error
+      @status_code = error.status_code if error.respond_to?(:status_code)
+    end
+
+    # Public: the error details as a hash, which can be returned
+    # to clients as JSON.
+    def body
+      message = if self.class.expose_backtrace?
+        {
+          message: @error.message,
+          backtrace: @error.backtrace
+        }
+      else
+        { message: @error.message }
+      end
+      { error: message }
+    end
+
+    # Public: turn the error body into a Rack-compatible body component.
+    #
+    # Returns: an Array with the error body represented as JSON.
+    def render
+      [status_code, RackMiddleware.content_type, [MultiJson.dump(body)]]
+    end
+
+    # Public: the status code to return for the given error.
+    def status_code
+      @status_code || 500
+    end
+
+    # Internal: whether the backtrace should be exposed in the response.
+    # Currently Rails-specific, needs to be generalized (to ENV["RACK_ENV"])?
+    def self.expose_backtrace?
+      !Rails.env.production?
+    end
+  end
+end

data/lib/batch_api/internal_middleware.rb

@@ -0,0 +1,87 @@
+require 'middleware'
+require 'batch_api/processor/sequential'
+require 'batch_api/processor/executor'
+require 'batch_api/internal_middleware/decode_json_body'
+require 'batch_api/internal_middleware/response_filter'
+
+module BatchApi
+  # Public: the internal middleware system used to process batch requests.
+  # (Not to be confused with RackMiddleware, which handles incoming Rack
+  # request.)  Based on Mitchel Hashimoto's middleware gem.
+  #
+  # There are actually two internal middleware stacks, one run around the
+  # entire request and the other run around each individual operation.
+  #
+  # The batch_middleware stack consists of two parts:
+  #   1) Custom middlewares - these middlewares will be run around the entire
+  #   sequence of batch requests.  Useful for global processing on a batch
+  #   request; for instance, the timestamp middleware adds a timestamp based on
+  #   when the original request was started.  This should return an array of
+  #   BatchApi::Response objects.
+  #
+  #   2) Processor - this automatically-provided middleware will execute all
+  #   batch requests either sequentially (currently the only option) or in
+  #   parallel (in the future).  This will return an array of
+  #   BatchApi::Response objects.
+  #
+  # The operation_middleware stack also consists of two parts:
+  #   1) Operation - these middlewares will run once per each operation, giving
+  #   you a chance to alter the results or details of an op -- for instance,
+  #   decoding the body if it's JSON.  This should return an individual
+  #   BatchApi::Response object.
+  #
+  #   2) Executor - this automatically-provided middleware actually executes
+  #   the individual Rack request, and returns a BatchApi::Response object.
+  #
+  # Symetry, right?
+  #
+  # All middlewares#call will receive the following as an env hash:
+  #   {
+  #     # for batch middlewares
+  #     ops: [], # the total set of operations
+  #     # for operation middlewares
+  #     op: obj, # the specific operation being executed
+  #     # all middlewares get the following:
+  #     rack_env: {}, # the Rack environment
+  #     rack_app: app # the Rack application
+  #   }
+  #
+  # All middlewares should return the result of their individual operation or
+  # the array of operation results, depending on where they are in the chain.
+  # (See above.)
+  module InternalMiddleware
+    # Public: the default internal middlewares to be run around the entire
+    # operation.
+    DEFAULT_BATCH_MIDDLEWARE = Proc.new {}
+
+    # Public: the default internal middlewares to be run around each batch
+    # operation.
+    DEFAULT_OPERATION_MIDDLEWARE = Proc.new do
+      # Decode JSON response bodies, so they're not double-encoded.
+      use InternalMiddleware::ResponseFilter
+      use InternalMiddleware::DecodeJsonBody
+    end
+
+    # Public: the middleware stack to use for processing the batch request as a
+    # whole..
+    def self.batch_stack(processor)
+      Middleware::Builder.new do
+        # evaluate these in the context of the middleware stack
+        self.instance_eval &BatchApi.config.batch_middleware
+        # for now, everything's sequential, but that will change
+        use processor.strategy
+      end
+    end
+    #
+    # Public: the middleware stack to use for processing each batch operation.
+    def self.operation_stack
+      Middleware::Builder.new do
+        # evaluate the operation middleware in the context of the middleware
+        # stack
+        self.instance_eval &BatchApi.config.operation_middleware
+        # and end with actually executing the batch request
+        use Processor::Executor
+      end
+    end
+  end
+end

data/lib/batch_api/internal_middleware/decode_json_body.rb

@@ -0,0 +1,24 @@
+module BatchApi
+  module InternalMiddleware
+    # Public: a middleware that decodes the body of any individual batch
+    # operation if the it's JSON.
+    class DecodeJsonBody
+      # Public: initialize the middleware.
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env).tap do |result|
+          result.body = MultiJson.load(result.body) if should_decode?(result)
+        end
+      end
+
+      private
+
+      def should_decode?(result)
+        result.headers["Content-Type"] =~ /^application\/json/
+      end
+    end
+  end
+end

data/lib/batch_api/internal_middleware/response_filter.rb

@@ -0,0 +1,27 @@
+module BatchApi
+  module InternalMiddleware
+    # Public: a batch middleware which surpresses the response from a call.  If you
+    # know you don't need a response (for instance, for a POST or PUT), you can
+    # add silent: true (or any truthy value, like 1) to your operation to
+    # surpress all output for successful requests.  Failed requests (status !=
+    # 2xx) will still return information.
+    class ResponseFilter
+      # Public: init the middleware.
+      def initialize(app)
+        @app = app
+      end
+
+      # Public: execute the call.  If env[:op].options[:silent] is true, it'll
+      # remove any output for a successful response.
+      def call(env)
+        @app.call(env).tap do |result|
+          if env[:op].options["silent"] && (200...299).include?(result.status)
+            # we have success and a request for silence
+            # so remove all the content before proceeding
+            result.status = result.body = result.headers = nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/batch_api/operation/rack.rb

@@ -3,11 +3,9 @@ require 'batch_api/response'
 module BatchApi
   # Public: an individual batch operation.
   module Operation
-    class MalformedOperationError < ArgumentError; end
-
     class Rack
       attr_accessor :method, :url, :params, :headers
-      attr_accessor :env, :app, :result
+      attr_accessor :env, :app, :result, :options
 
       # Public: create a new Batch Operation given the specifications for a batch
       # operation (as defined above) and the request environment for the main
@@ -19,8 +17,9 @@ module BatchApi
         @url = op["url"]
         @params = op["params"] || {}
         @headers = op["headers"] || {}
+        @options = op
 
-        raise MalformedOperationError,
+        raise Errors::MalformedOperationError,
           "BatchAPI operation must include method (received #{@method.inspect}) " +
           "and url (received #{@url.inspect})" unless @method && @url
 
@@ -36,7 +35,7 @@ module BatchApi
         begin
           response = @app.call(@env)
         rescue => err
-          response = BatchApi::Errors::Operation.new(err).render
+          response = BatchApi::ErrorWrapper.new(err).render
         end
         BatchApi::Response.new(response)
       end

data/lib/batch_api/processor.rb

@@ -1,16 +1,8 @@
-require 'batch_api/processor/strategies/sequential'
+require 'batch_api/processor/sequential'
 require 'batch_api/operation'
 
 module BatchApi
   class Processor
-    # Public: Raised when a user provides more Batch API requests than a service
-    # allows.
-    class OperationLimitExceeded < StandardError; end
-    # Public: Raised if a provided option is invalid.
-    class BadOptionError < StandardError; end
-    # Public: Raised if no operations are provided.
-    class NoOperationsError < ArgumentError; end
-
     attr_reader :ops, :options, :app
 
     # Public: create a new Processor.
@@ -20,7 +12,7 @@ module BatchApi
     #
     # Raises OperationLimitExceeded if more operations are requested than
     # allowed by the BatchApi configuration.
-    # Raises BadOptionError if other provided options are invalid.
+    # Raises Errors::BadOptionError if other provided options are invalid.
     # Raises ArgumentError if no operations are provided (nil or []).
     #
     # Returns the new Processor instance.
@@ -30,26 +22,34 @@ module BatchApi
       @env = request.env
       @ops = self.process_ops
       @options = self.process_options
-
-      @start_time = Time.now.to_i
     end
 
     # Public: the processing strategy to use, based on the options
     # provided in BatchApi setup and the request.
     # Currently only Sequential is supported.
     def strategy
-      BatchApi::Processor::Strategies::Sequential
+      BatchApi::Processor::Sequential
     end
 
     # Public: run the batch operations according to the appropriate strategy.
     #
     # Returns a set of BatchResponses
     def execute!
-      format_response(strategy.execute!(@ops, @options))
+      stack = InternalMiddleware.batch_stack(self)
+      format_response(stack.call(middleware_env))
     end
 
     protected
 
+    def middleware_env
+      {
+        ops: @ops,
+        rack_env: @env,
+        rack_app: @app,
+        options: @options
+      }
+    end
+
     # Internal: format the result of the operations, and include
     # any other appropriate information (such as timestamp).
     #
@@ -58,8 +58,7 @@ module BatchApi
     # Returns a hash ready to go to the user
     def format_response(operation_results)
       {
-        "results" => operation_results,
-        "timestamp" => @start_time.to_s
+        "results" => operation_results
       }
     end
 
@@ -68,16 +67,17 @@ module BatchApi
     #
     # ops - a series of operations
     #
-    # Raises OperationLimitExceeded if more operations are requested than
+    # Raises Errors::OperationLimitExceeded if more operations are requested than
     # allowed by the BatchApi configuration.
+    # Raises Errors::NoOperationsError if no operations are provided.
     #
     # Returns an array of BatchApi::Operation objects
     def process_ops
       ops = @request.params.delete("ops")
       if !ops || ops.empty?
-        raise NoOperationsError, "No operations provided"
+        raise Errors::NoOperationsError, "No operations provided"
       elsif ops.length > BatchApi.config.limit
-        raise OperationLimitExceeded,
+        raise Errors::OperationLimitExceeded,
           "Only #{BatchApi.config.limit} operations can be submitted at once, " +
           "#{ops.length} were provided"
       else
@@ -100,10 +100,12 @@ module BatchApi
     #
     # options - an options hash
     #
+    # Raises Errors::BadOptionError if sequential is not provided.
+    #
     # Returns the valid options hash.
     def process_options
       unless @request.params["sequential"]
-        raise BadOptionError, "Sequential flag is currently required"
+        raise Errors::BadOptionError, "Sequential flag is currently required"
       end
       @request.params
     end