batch_api2 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5555904a32bd830b6afdb63a282135a2a33cd995
+  data.tar.gz: 81cd01446df080d2ce53b865eaa8e24ceedeff71
+SHA512:
+  metadata.gz: ebdd0d77a56b9d44b1e3872d95fc017c72fbaa8ec3b4daaee9bfbcdb1a6ea78e88ed98c6989c7a5c57c9446ad6637c1386c8f8487e97e258bf6e37c295dae0ae
+  data.tar.gz: a74c28e3dc240b0c1ed2baa01fa274a86fef87100ca0793d5357135f09b5f6ef40345c9c5da9ba805a2ebe29a63328337a8656636eb8b0e48afc9478b5511a49

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,30 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'BatchApi'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["--color", '--format doc', '--order rand']
+end
+
+task :default => :spec

data/changelog.md

@@ -0,0 +1,74 @@
+v0.3.0
+
+New features:
+
+* guard against nil REQUEST_URI (thanks, pbendersky and dlackty!)
+* don't parse empty bodies as JSON (thanks, trungpham and dlackty!)
+
+Testing improvements:
+
+* modernize test infrastructure and test against newer Ruby versions (thanks, dwaller, pmq20 and dlackty!)
+* update test Rails app version to 4.2
+* modernize RSpec syntax using transpec
+
+
+v0.2.2
+* Update documentation to remove old options and add installation section
+* Update gems
+
+v0.2.1
+* Default the method to GET if no method is specified
+
+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
+
+v0.1.0
+* Add direct support for Rails for path params
+* Fix spec bugs
+
+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

@@ -0,0 +1,28 @@
+require 'batch_api/configuration'
+require 'batch_api/version'
+require 'batch_api/utils'
+require 'batch_api/processor'
+
+require 'batch_api/internal_middleware'
+require 'batch_api/rack_middleware'
+
+require 'batch_api/error_wrapper'
+require 'batch_api/batch_error'
+
+module BatchApi
+
+  # Public: access the main Batch API configuration object.
+  #
+  # Returns a BatchApi::Configuration instance
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # Public: are we in Rails?  This partly exists just so that you
+  # can stub it in the tests.
+  #
+  # Returns true if Rails is a defined constant, false otherwise.
+  def self.rails?
+    defined?(Rails)
+  end
+end

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

@@ -0,0 +1,36 @@
+require 'batch_api/internal_middleware'
+
+module BatchApi
+  # 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)
+  #
+  # 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
+  }
+
+  # Batch API Configuration
+  class Configuration < Struct.new(*CONFIGURATION_OPTIONS.keys)
+    # Public: initialize a new configuration option and apply the defaults.
+    def initialize
+      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, [body.to_json]]
+    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,28 @@
+module BatchApi
+  module InternalMiddleware
+    # Public: a middleware that decodes the body of any individual batch
+    # operation if it's JSON.
+    class DecodeJsonBody
+      # Public: initialize the middleware.
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env).tap do |result|
+          if should_decode?(result)
+            result.body = MultiJson.load(result.body)
+          end
+        end
+      end
+
+      private
+
+      def should_decode?(result)
+        result.headers["Content-Type"] =~ /^application\/json/ &&
+          # don't try to decode an empty response
+          result.body.present?
+      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.rb

@@ -0,0 +1,2 @@
+require 'batch_api/operation/rack'
+require 'batch_api/operation/rails' if defined?(Rails)

data/lib/batch_api/operation/rack.rb

@@ -0,0 +1,76 @@
+require 'batch_api/response'
+
+module BatchApi
+  # Public: an individual batch operation.
+  module Operation
+    class Rack
+      attr_accessor :method, :url, :params, :headers
+      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
+      # batch request.
+      def initialize(op, base_env, app)
+        @op = op
+
+        @method = op["method"] || "get"
+        @url = op["url"]
+        @params = op["params"] || {}
+        @headers = op["headers"] || {}
+        @options = op
+
+        raise Errors::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 = 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
+          response = @app.call(@env)
+        rescue => err
+          response = BatchApi::ErrorWrapper.new(err).render
+        end
+        BatchApi::Response.new(response)
+      end
+
+      # Internal: customize the request environment.  This is currently done
+      # manually and feels clunky and brittle, but is mostly likely fine, though
+      # there are one or two environment parameters not yet adjusted.
+      def process_env
+        path, qs = @url.split("?")
+
+        # Headers
+        headrs = (@headers || {}).inject({}) do |heads, (k, v)|
+          heads.tap {|h| h["HTTP_" + k.gsub(/\-/, "_").upcase] = v}
+        end
+        # preserve original headers unless explicitly overridden
+        @env.merge!(headrs)
+
+        # method
+        @env["REQUEST_METHOD"] = @method.upcase
+
+        # path and query string
+        if @env["REQUEST_URI"]
+          # not all servers provide REQUEST_URI -- Pow, for instance, doesn't
+          @env["REQUEST_URI"] = @env["REQUEST_URI"].gsub(/#{BatchApi.config.endpoint}.*/, @url)
+        end
+        @env["REQUEST_PATH"] = path
+        @env["ORIGINAL_FULLPATH"] = @env["PATH_INFO"] = @url
+
+        @env["rack.request.query_string"] = qs
+        @env["QUERY_STRING"] = qs
+
+        # parameters
+        @env["rack.request.form_hash"] = @params
+        @env["rack.request.query_hash"] = @method == "get" ? @params : nil
+      end
+    end
+  end
+end