adavidev_batch_api 0.2.1.pre.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7534a2af10be012a0af6a393d7db504bfed9b153
+  data.tar.gz: a13259fc6a2eaf65e1afc01c13862eae54762bf0
+SHA512:
+  metadata.gz: 3c6924ef94af17cb2310251ebab090a9098eaa525154348771aef0a67a7edf11c3b5d0361d8919daabe5147ca7a2d6e3fe454fb13a4ebfb141aba2dcb1c11bd6
+  data.tar.gz: c0d80c55b7a5560fc3be70cffd2174ef576a09deb9441eddec5ab229fb3f5fbb9a37fba26690964616dfb9fb9be2d5a17b51488983d2e9c75260ae957813a156

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,60 @@
+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/adavidev_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, [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/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/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/operation/rack.rb

@@ -0,0 +1,74 @@
+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 = @url.split("?")
+        qs = @params.to_json
+
+        # 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
+        @env["REQUEST_URI"] = @env["REQUEST_URI"].gsub(/#{BatchApi.config.endpoint}.*/, @url)
+        @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

data/lib/batch_api/operation/rails.rb

@@ -0,0 +1,42 @@
+require 'batch_api/operation/rack'
+
+module BatchApi
+  # Public: an individual batch operation.
+  module Operation
+    class Rails < Operation::Rack
+      # Public: create a new Rails Operation.  It does all that Rack does
+      # and also some additional Rails-specific processing.
+      def initialize(op, base_env, app)
+        super
+        @params = params_with_path_components
+      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
+        # parameters
+        super
+        @env["action_dispatch.request.parameters"] = @params
+        @env["action_dispatch.request.request_parameters"] = @params
+      end
+
+      private
+
+      # Internal: process the params the Rails way, merging in the
+      # path_parameters.  If the route can't be recognized, it will
+      # leave the params unchanged.
+      #
+      # Returns the updated params.
+      def params_with_path_components
+        begin
+          path_params = ::Rails.application.routes.recognize_path(@url, @op)
+          @params.merge(path_params)
+        rescue
+          @params
+        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/processor/executor.rb

@@ -0,0 +1,18 @@
+module BatchApi
+  class Processor
+    # Public: a simple middleware that lives at the end of the internal chain
+    # and simply executes each batch operation.
+    class Executor
+
+      # Public: initialize the middleware.
+      def initialize(app)
+        @app = app
+      end
+
+      # Public: execute the batch operation.
+      def call(env)
+        env[:op].execute
+      end
+    end
+  end
+end

data/lib/batch_api/processor/sequential.rb

@@ -0,0 +1,29 @@
+module BatchApi
+  class Processor
+    class Sequential
+      # Public: initialize with the app.
+      def initialize(app)
+        @app = app
+      end
+
+      # Public: execute all operations sequentially.
+      #
+      # ops - a set of BatchApi::Operations
+      # options - a set of options
+      #
+      # Returns an array of BatchApi::Response objects.
+      def call(env)
+        env[:ops].collect do |op|
+          # set the current op
+          env[:op] = op
+
+          # execute the individual request inside the operation-specific
+          # middeware, then clear out the current op afterward
+          middleware = InternalMiddleware.operation_stack
+          middleware.call(env).tap {|r| env.delete(:op) }
+        end
+      end
+    end
+  end
+end
+