batch_api 0.0.1 → 0.0.8

data/changelog.md

@@ -1,2 +1,29 @@
+v0.0.8
+* Return the results wrapped in a hash, rather than a raw array
+* Add process_start timestamp option
+
+v0.0.7
+* Return more specific error codes to alert clients to param errors
+
+v0.0.6
+* Refactor Rack middleware to be Sinatra-compatible
+
+v0.0.5
+* Add setting to decode JSON responses before sending batch results
+
+v0.0.4
+* Switch from Rails-based process to a Rack middleware
+* Improve tests
+
+v0.0.3
+* Encapsulate processing into a Processor module
+* Prepare for parallel processing in the future
+* Add specific errors
+* Allow controlling the routing target
+
+v0.0.2
+* Add config module
+* Add options for operation limit, endpoint, and verb
+
 v0.0.1
 * Initial build

data/lib/batch_api.rb

@@ -1,6 +1,11 @@
-require 'batch_api/routing_helper'
-require 'batch_api/engine'
+require 'batch_api/configuration'
 require 'batch_api/version'
+require 'batch_api/utils'
+require 'batch_api/processor'
+require 'batch_api/middleware'
 
 module BatchApi
+  def self.config
+    @config ||= Configuration.new
+  end
 end

data/lib/batch_api/configuration.rb

@@ -0,0 +1,29 @@
+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
+
+    # Default values for configuration variables
+    def initialize
+      @verb = :post
+      @endpoint = "/batch"
+      @limit = 50
+      @decode_json_responses = true
+      @add_timestamp = true
+    end
+  end
+end
+
+

data/lib/batch_api/error.rb

@@ -1,32 +1,3 @@
-module BatchApi
-  # Public: 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 Error
-    # Public: create a new BatchError from a Rails error.
-    def initialize(error)
-      @message = error.message
-      @backtrace = error.backtrace
-    end
+require 'batch_api/errors/request'
+require 'batch_api/errors/operation'
 
-    # Public: here for compatibility with BatchResponse interface.
-    attr_reader :cookies
-
-    # Public: the error details as a hash, which can be returned
-    # to clients as JSON.
-    def body
-      if expose_backtrace?
-        {
-          message: @message,
-          backtrace: @backtrace
-        }
-      else
-        { message: @message }
-      end
-    end
-
-    def expose_backtrace?
-      Rails.env.production?
-    end
-  end
-end

data/lib/batch_api/errors/base.rb

@@ -0,0 +1,45 @@
+module BatchApi
+  # Public: 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.
+  module Errors
+    class Base
+      # Public: create a new BatchError from a Rails error.
+      def initialize(error)
+        @error = error
+      end
+
+      # Public: the error details as a hash, which can be returned
+      # to clients as JSON.
+      def body
+        message = if 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, Middleware.content_type, [MultiJson.dump(body)]]
+      end
+
+      # Public: the status code to return for the given error.
+      def 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 expose_backtrace?
+        !Rails.env.production?
+      end
+    end
+  end
+end

data/lib/batch_api/errors/operation.rb

@@ -0,0 +1,7 @@
+require 'batch_api/errors/base'
+
+module BatchApi
+  module Errors
+    class Operation < Base; end
+  end
+end

data/lib/batch_api/errors/request.rb

@@ -0,0 +1,26 @@
+require 'batch_api/errors/base'
+
+module BatchApi
+  module Errors
+    # Public: This class encapsulates errors that occur at a request level.
+    # For instance, it returns proper error codes for BadOptionErrors or other
+    # identifiable problems.  (For actual code errors, it returns a 500
+    # response.)
+    class Request < BatchApi::Errors::Base
+      # Public: return the appropriate status code for the error.  For
+      # errors from bad Batch API input, raise a 422, otherwise, a 500.
+      def status_code
+        case @error
+        when BatchApi::Processor::BadOptionError,
+             BatchApi::Processor::OperationLimitExceeded,
+             BatchApi::Processor::NoOperationsError,
+             BatchApi::Operation::MalformedOperationError
+          422
+        else
+          500
+        end
+      end
+    end
+  end
+end
+

data/lib/batch_api/middleware.rb

@@ -0,0 +1,37 @@
+module BatchApi
+  class Middleware
+    def initialize(app, &block)
+      @app = app
+      yield BatchApi.config if block
+    end
+
+    def call(env)
+      if batch_request?(env)
+        begin
+          request = request_klass.new(env)
+          result = BatchApi::Processor.new(request, @app).execute!
+          [200, self.class.content_type, [MultiJson.dump(result)]]
+        rescue => err
+          BatchApi::Errors::Request.new(err).render
+        end
+      else
+        @app.call(env)
+      end
+    end
+
+    def self.content_type
+      {"Content-Type" => "application/json"}
+    end
+
+    private
+
+    def batch_request?(env)
+      env["PATH_INFO"] == BatchApi.config.endpoint &&
+        env["REQUEST_METHOD"] == BatchApi.config.verb.to_s.upcase
+    end
+
+    def request_klass
+      defined?(ActionDispatch) ? ActionDispatch::Request : Rack::Request
+    end
+  end
+end

data/lib/batch_api/operation.rb

@@ -3,46 +3,41 @@ require 'batch_api/response'
 module BatchApi
   # Public: an individual batch operation.
   class Operation
+    class MalformedOperationError < ArgumentError; end
+
     attr_accessor :method, :url, :params, :headers
-    attr_accessor :env, :result
+    attr_accessor :env, :app, :result
 
     # Public: create a new Batch Operation given the specifications for a batch
     # operation (as defined above) and the request environment for the main
     # batch request.
-    def initialize(op, base_env)
+    def initialize(op, base_env, app)
       @op = op
 
-      @method = op[:method]
-      @url = op[:url]
-      @params = op[:params]
-      @headers = op[:headers]
+      @method = op["method"]
+      @url = op["url"]
+      @params = op["params"] || {}
+      @headers = op["headers"] || {}
+
+      raise MalformedOperationError,
+        "BatchAPI operation must include method (received #{@method.inspect}) " +
+        "and url (received #{@url.inspect})" unless @method && @url
 
+      @app = app
       # deep_dup to avoid unwanted changes across requests
-      @env = base_env.deep_dup
+      @env = BatchApi::Utils.deep_dup(base_env)
     end
 
     # Execute a batch request, returning a BatchResponse object.  If an error
     # occurs, it returns the same results as Rails would.
     def execute
+      process_env
       begin
-        action = identify_routing
-        process_env
-        BatchApi::Response.new(action.call(@env))
+        response = @app.call(@env)
       rescue => err
-        error_response(err)
+        response = BatchApi::Errors::Operation.new(err).render
       end
-    end
-
-    # Internal: given a URL and other operation details as specified above,
-    # identify the appropriate controller and action to execute the action.
-    #
-    # Raises a routing error if the route doesn't exist.
-    #
-    # Returns the action object, which can be called with the environment.
-    def identify_routing
-      @path_params = Rails.application.routes.recognize_path(@url, @op)
-      @controller = ActionDispatch::Routing::RouteSet::Dispatcher.new.controller(@path_params)
-      @controller.action(@path_params[:action])
+      BatchApi::Response.new(response)
     end
 
     # Internal: customize the request environment.  This is currently done
@@ -51,12 +46,6 @@ module BatchApi
     def process_env
       path, qs = @url.split("?")
 
-      # rails routing
-      @env["action_dispatch.request.path_parameters"] = @path_params
-      # this isn't quite right, but hopefully it'll work
-      # since we're not executing any middleware
-      @env["action_controller.instance"] = @controller.new
-
       # Headers
       headrs = (@headers || {}).inject({}) do |heads, (k, v)|
         heads.tap {|h| h["HTTP_" + k.gsub(/\-/, "_").upcase] = v}
@@ -72,23 +61,14 @@ module BatchApi
       @env["REQUEST_PATH"] = path
       @env["ORIGINAL_FULLPATH"] = @env["PATH_INFO"] = @url
 
-      @env["rack.request.query_string"] = @env["QUERY_STRING"] = qs
+      @env["rack.request.query_string"] = qs
+      @env["QUERY_STRING"] = qs
 
       # parameters
+      @env["rack.request.form_hash"] = @params
       @env["action_dispatch.request.parameters"] = @params
       @env["action_dispatch.request.request_parameters"] = @params
       @env["rack.request.query_hash"] = @method == "get" ? @params : nil
     end
-
-    # Internal: create a BatchResponse for an exception thrown during batch
-    # processing.
-    def error_response(err)
-      wrapper = ActionDispatch::ExceptionWrapper.new(@env, err)
-      BatchApi::Response.new([
-        wrapper.status_code,
-        {},
-        BatchApi::Error.new(err)
-      ])
-    end
   end
 end

data/lib/batch_api/processor.rb

@@ -0,0 +1,104 @@
+require 'batch_api/processor/strategies/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.
+    #
+    # env - a Rack environment hash
+    # app - a Rack application
+    #
+    # Raises OperationLimitExceeded if more operations are requested than
+    # allowed by the BatchApi configuration.
+    # Raises BadOptionError if other provided options are invalid.
+    # Raises ArgumentError if no operations are provided (nil or []).
+    #
+    # Returns the new Processor instance.
+    def initialize(request, app)
+      @app = app
+      @request = request
+      @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
+    end
+
+    # Public: run the batch operations according to the appropriate strategy.
+    #
+    # Returns a set of BatchResponses
+    def execute!
+      format_response(strategy.execute!(@ops, @options))
+    end
+
+    protected
+
+    # Internal: format the result of the operations, and include
+    # any other appropriate information (such as timestamp).
+    #
+    # result - the array of batch operations
+    #
+    # Returns a hash ready to go to the user
+    def format_response(operation_results)
+      {
+        "results" => operation_results,
+        "timestamp" => @start_time.to_s
+      }
+    end
+
+    # Internal: Validate that an allowable number of operations have been
+    # provided, and turn them into BatchApi::Operation objects.
+    #
+    # ops - a series of operations
+    #
+    # Raises OperationLimitExceeded if more operations are requested than
+    # allowed by the BatchApi configuration.
+    #
+    # Returns an array of BatchApi::Operation objects
+    def process_ops
+      ops = @request.params.delete("ops")
+      if !ops || ops.empty?
+        raise NoOperationsError, "No operations provided"
+      elsif ops.length > BatchApi.config.limit
+        raise OperationLimitExceeded,
+          "Only #{BatchApi.config.limit} operations can be submitted at once, " +
+          "#{ops.length} were provided"
+      else
+        ops.map do |op|
+          BatchApi::Operation.new(op, @env, @app)
+        end
+      end
+    end
+
+    # Internal: Processes any other provided options for validity.
+    # Currently, the :sequential option is REQUIRED (until parallel
+    # implementation is created).
+    #
+    # options - an options hash
+    #
+    # Returns the valid options hash.
+    def process_options
+      unless @request.params["sequential"]
+        raise BadOptionError, "Sequential flag is currently required"
+      end
+      @request.params
+    end
+  end
+end

data/lib/batch_api/processor/strategies/sequential.rb

@@ -0,0 +1,18 @@
+module BatchApi
+  class Processor
+    module Strategies
+      module Sequential
+        # Public: execute all operations sequentially.
+        #
+        # ops - a set of BatchApi::Operations
+        # options - a set of options
+        #
+        # Returns an array of BatchApi::Response objects.
+        def self.execute!(ops, options = {})
+          ops.map(&:execute)
+        end
+      end
+    end
+  end
+end
+

data/lib/batch_api/response.rb

@@ -6,17 +6,30 @@ module BatchApi
   # outcome.
   class Response
     # Public: the attributes of the HTTP response.
-    attr_accessor :status, :body, :headers, :cookies
+    attr_accessor :status, :body, :headers
 
     # Public: create a new response representation from a Rack-compatible
     # response (e.g. [status, headers, response_object]).
     def initialize(response)
-      @status = response.first
-      @headers = response[1]
+      @status, @headers = *response
+      @body = process_body(response[2])
+    end
+
+    private
+
+    def process_body(body_pieces)
+      # bodies have to respond to .each, but may otherwise
+      # not be suitable for JSON serialization
+      # (I'm looking at you, ActionDispatch::Response)
+      # so turn it into a string
+      base_body = ""
+      body_pieces.each {|str| base_body << str}
+      should_decode? ? MultiJson.load(base_body) : base_body
+    end
 
-      response_object = response[2]
-      @body = response_object.body
-      @cookies = response_object.cookies
+    def should_decode?
+      @headers["Content-Type"] =~ /^application\/json/ &&
+        BatchApi.config.decode_json_responses
     end
   end
 end

data/lib/batch_api/utils.rb

@@ -0,0 +1,17 @@
+module BatchApi
+  module Utils
+
+    def self.deep_dup(object)
+      if object.is_a?(Hash)
+        duplicate = object.dup
+        duplicate.each_pair do |k,v|
+          tv = duplicate[k]
+          duplicate[k] = tv.is_a?(Hash) && v.is_a?(Hash) ? deep_dup(tv) : v
+        end
+        duplicate
+      else
+        object
+      end
+    end
+  end
+end

data/lib/batch_api/version.rb

@@ -1,3 +1,3 @@
 module BatchApi
-  VERSION = "0.0.1"
+  VERSION = "0.0.8"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: batch_api
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.8
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-13 00:00:00.000000000 Z
+date: 2012-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -19,7 +19,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '3.2'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
@@ -27,6 +27,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -75,6 +91,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-contrib
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Batch API plugin that provides a RESTful syntax, allowing clients to
   make any number of REST calls with a single HTTP request.
 email:
@@ -83,12 +115,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- app/controllers/batch_api/batch_controller.rb
-- lib/batch_api/engine.rb
+- lib/batch_api/configuration.rb
 - lib/batch_api/error.rb
+- lib/batch_api/errors/base.rb
+- lib/batch_api/errors/operation.rb
+- lib/batch_api/errors/request.rb
+- lib/batch_api/middleware.rb
 - lib/batch_api/operation.rb
+- lib/batch_api/processor/strategies/sequential.rb
+- lib/batch_api/processor.rb
 - lib/batch_api/response.rb
-- lib/batch_api/routing_helper.rb
+- lib/batch_api/utils.rb
 - lib/batch_api/version.rb
 - lib/batch_api.rb
 - lib/tasks/batch_api_tasks.rake
@@ -110,7 +147,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1071837955116255101
+      hash: -456340693841676630
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -119,7 +156,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1071837955116255101
+      hash: -456340693841676630
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.21

data/app/controllers/batch_api/batch_controller.rb

@@ -1,10 +0,0 @@
-require 'batch_api/operation'
-
-module BatchApi
-  class BatchController < ::ApplicationController
-    def batch
-      ops = params[:ops].map {|o| BatchApi::Operation.new(o, request.env)}
-      render :json => ops.map(&:execute)
-    end
-  end
-end

data/lib/batch_api/engine.rb

@@ -1,8 +0,0 @@
-# CURRENT FILE :: lib/team_page/engine.rb
-module BatchApi
-  class Engine < Rails::Engine
-    initializer "batch_api.add_routing_helper" do |app|
-      ActionDispatch::Routing::Mapper.send(:include, BatchApi::RoutingHelper)
-    end
-  end
-end

data/lib/batch_api/routing_helper.rb

@@ -1,12 +0,0 @@
-module BatchApi
-  module RoutingHelper
-    DEFAULT_VERB = :post
-    DEFAULT_ENDPOINT = "/batch"
-
-    def batch_api(options = {})
-      endpoint = options.delete(:endpoint) || DEFAULT_ENDPOINT
-      verb = options.delete(:via) || DEFAULT_VERB
-      match({endpoint => "batch_api/batch#batch", via: verb}.merge(options))
-    end
-  end
-end