api_hammer 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 32321326726e5c0d8d195dfb62c59fbaeb6837ec
-  data.tar.gz: f770e32fc9bd8ee16d1f17d6c30b4dceeca03131
+  metadata.gz: a4967ef9a4193e2caca1f27035eb81f81e1ed918
+  data.tar.gz: 61f6a27ec7f13762954656f841666dddc37c9a8c
 SHA512:
-  metadata.gz: 843b147c0c7d60776834ffe0ea3d2c9e8c25e42558ea398df825478217969309af8700a2cbafe3ffc1f885a61adcbb183d80a495881a664b508850aa94a00cc5
-  data.tar.gz: 2202a0ebb1fbf519a37ecd5ab223418a3e38254616c7367d1dbb0da8b1c72fd1d860db831fa5031012949bc49a81284b224dfb22500f98d93bece4c010c84216
+  metadata.gz: ea757b0f6203e080b27eee87ba0094db03a71bfc517f0c33223d37049bd2972ad2db6cf48601668bb2c20625628194bc5eb2897bfeb95d9df097fd2dae345cc7
+  data.tar.gz: 141e9a7c5aae36bedd0f1293c4faddae6621f6fa0d8b956ee44309a44628fad1245d012d9d9ad6c52ba233fca74465eb3b47187f479ce0d37583ca8e5b83138c

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# v0.13.0
+- ApiHammer::Sinatra, with some useful sinatra methods
+  - #halt, #halt_error, #halt_unprocessable_entity and friends
+  - a more api-appropriate 404 for unknown routes
+  - parsing request bodies in accordance with content-type, with appropriate errors
+  - formatting response bodies, minding accept headers, with appropriate errors
+
 # v0.12.0
 - hc --input option
 - rails 4 support for unmunged_request_params

data/lib/api_hammer/{halt.rb → halt_methods.rb}

@@ -1,100 +1,56 @@
-# the contents of this file are to let you halt a controller in its processing without having to have a 
-# return in the actual action. this lets helper methods which do things like parameter validation halt.
-#
-# it is desgined to function similarly to Sinatra's handling of throw(:halt), but is based around exceptions 
-# because rails doesn't catch anything, just rescues. 
-
 module ApiHammer
-  # an exception raised to stop processing an action and render the body given as the 'body' argument 
-  # (which is expected to be a JSON-able object)
-  class Halt < StandardError
-    def initialize(message, body, render_options={})
-      super(message)
-      @body = body
-      @render_options = render_options
-    end
-
-    attr_reader :body, :render_options
-  end
-end
-
-module ApiHammer::Rails
-  unless instance_variables.any? { |iv| iv.to_s == '@halt_included' }
-    @halt_included = proc do |controller_class|
-      controller_class.send(:rescue_from, ApiHammer::Halt, :with => :handle_halt)
-    end
-    (@on_included ||= Set.new) << @halt_included
-  end
-
-  # handle a raised ApiHammer::Halt or subclass and render it
-  def handle_halt(halt)
-    render_options = halt.render_options ? halt.render_options.dup : {}
-    # rocket pants does not have a render method, just render_json 
-    if respond_to?(:render_json, true)
-      render_json(halt.body || {}, render_options)
-    else
-      render_options[:json] = halt.body || {}
-      render(render_options)
-    end
-  end
-
-  # halt and render the given body 
-  def halt(status, body, render_options = {})
-    raise(ApiHammer::Halt.new(body.inspect, body, render_options.merge(:status => status)))
-  end
-
-  # halt and render the given errors in the body on the 'errors' key 
-  def halt_error(status, errors, options = {})
-    errors_as_json = errors.respond_to?(:as_json) ? errors.as_json : errors
-    unless errors_as_json.is_a?(Hash)
-      raise ArgumentError, "errors be an object representable in JSON as a Hash; got errors = #{errors.inspect}"
-    end
-    unless errors_as_json.keys.all? { |k| k.is_a?(String) || k.is_a?(Symbol) }
-      raise ArgumentError, "errors keys must all be string or symbol; got errors = #{errors.inspect}"
-    end
-    unless errors_as_json.values.all? { |v| v.is_a?(Array) && v.all? { |e| e.is_a?(String) } }
-      raise ArgumentError, "errors values must all be arrays of strings; got errors = #{errors.inspect}"
-    end
-    render_options = options.dup.with_indifferent_access
-    body = {'errors' => errors}
-    error_message = render_options.delete('error_message') || begin
-      error_values = errors.values.inject([], &:+)
-      if error_values.size <= 1
-        error_values.first
-      else
-        # sentencify with periods 
-        error_values.map { |v| v =~ /\.\s*\z/ ? v : v + '.' }.join(' ')
+  module HaltMethods
+    # halt and render the given errors in the body on the 'errors' key 
+    def halt_error(status, errors, options = {})
+      errors_as_json = errors.respond_to?(:as_json) ? errors.as_json : errors
+      unless errors_as_json.is_a?(Hash)
+        raise ArgumentError, "errors be an object representable in JSON as a Hash; got errors = #{errors.inspect}"
+      end
+      unless errors_as_json.keys.all? { |k| k.is_a?(String) || k.is_a?(Symbol) }
+        raise ArgumentError, "errors keys must all be string or symbol; got errors = #{errors.inspect}"
+      end
+      unless errors_as_json.values.all? { |v| v.is_a?(Array) && v.all? { |e| e.is_a?(String) } }
+        raise ArgumentError, "errors values must all be arrays of strings; got errors = #{errors.inspect}"
+      end
+      halt_options = options.dup.with_indifferent_access
+      body = {'errors' => errors}
+      error_message = halt_options.delete('error_message') || begin
+        error_values = errors.values.inject([], &:+)
+        if error_values.size <= 1
+          error_values.first
+        else
+          # sentencify with periods 
+          error_values.map { |v| v =~ /\.\s*\z/ ? v : v + '.' }.join(' ')
+        end
       end
+      body['error_message'] = error_message if error_message
+      halt(status, body, halt_options)
+    end
+
+    # attempts to find and return the given model (an ActiveRecord::Base subclass) with the given attributes. 
+    # halts with 404 (does not return) if that fails. options[:status] may specify a different status if that 
+    # is required.
+    #
+    # e.g.:
+    #
+    #     find_or_halt(User, :email => 'user@example.com')
+    #
+    def find_or_halt(model, find_attrs, options={})
+      options = {:status => 404}.merge(options)
+      record = model.where(find_attrs).first
+      unless record
+        attributes = find_attrs.map { |attr, val| "#{attr}: #{val}" }.join(", ")
+        model_name = model.table_name
+        model_name = model_name.singularize if model_name.respond_to?(:singularize)
+        message = I18n.t(:"errors.unknown_record_with_attributes", :default => "Unknown %{model_name}! %{attributes}",
+          :model_name => model_name,
+          :attributes => attributes
+        )
+        halt_error(options[:status], {model_name => [message]})
+      end
+      record
     end
-    body['error_message'] = error_message if error_message
-    halt(status, body, render_options)
-  end
-
-  # attempts to find and return the given model (an ActiveRecord::Base subclass) with the given attributes. 
-  # halts with 404 (does not return) if that fails. options[:status] may specify a different status if that 
-  # is required.
-  #
-  # e.g.:
-  #
-  #     find_or_halt(User, :email => 'user@example.com')
-  #
-  def find_or_halt(model, find_attrs, options={})
-    options = {:status => 404}.merge(options)
-    record = model.where(find_attrs).first
-    unless record
-      attributes = find_attrs.map{|attr, val| "#{attr}: #{val}" }.join(", ")
-      model_name = model.table_name
-      model_name = model_name.singularize if model_name.respond_to?(:singularize)
-      message = I18n.t(:"errors.unknown_record_with_attributes", :default => "Unknown %{model_name}! %{attributes}",
-        :model_name => model_name,
-        :attributes => attributes
-      )
-      halt_error(options[:status], {model_name => [message]})
-    end
-    record
-  end
 
-  module HaltMethods
     # halt with status 200 OK, responding with the given body object 
     def halt_ok(body, render_options = {})
       halt(200, body, render_options)
@@ -444,6 +400,4 @@ end.compact.join)
 
 =end
   end
-
-  include HaltMethods
 end

data/lib/api_hammer/rails/halt.rb

@@ -0,0 +1,47 @@
+require 'api_hammer/halt_methods'
+
+# the contents of this file are to let you halt a controller in its processing without having to have a 
+# return in the actual action. this lets helper methods which do things like parameter validation halt.
+#
+# it is desgined to function similarly to Sinatra's handling of throw(:halt), but is based around exceptions 
+# because rails doesn't catch anything, just rescues. 
+
+module ApiHammer::Rails
+  # an exception raised to stop processing an action and render the body given as the 'body' argument 
+  # (which is expected to be a JSON-able object)
+  class Halt < StandardError
+    def initialize(message, body, render_options={})
+      super(message)
+      @body = body
+      @render_options = render_options
+    end
+
+    attr_reader :body, :render_options
+  end
+
+  unless instance_variables.any? { |iv| iv.to_s == '@halt_included' }
+    @halt_included = proc do |controller_class|
+      controller_class.send(:rescue_from, ApiHammer::Rails::Halt, :with => :handle_halt)
+    end
+    (@on_included ||= Set.new) << @halt_included
+  end
+
+  # handle a raised ApiHammer::Halt or subclass and render it
+  def handle_halt(halt)
+    render_options = halt.render_options ? halt.render_options.dup : {}
+    # rocket pants does not have a render method, just render_json 
+    if respond_to?(:render_json, true)
+      render_json(halt.body || {}, render_options)
+    else
+      render_options[:json] = halt.body || {}
+      render(render_options)
+    end
+  end
+
+  # halt and render the given body 
+  def halt(status, body, render_options = {})
+    raise(ApiHammer::Rails::Halt.new(body.inspect, body, render_options.merge(:status => status)))
+  end
+
+  include ApiHammer::HaltMethods
+end

data/lib/api_hammer/rails.rb

@@ -1,11 +1,13 @@
-require 'api_hammer/halt'
-require 'api_hammer/check_required_params'
-require 'api_hammer/unmunged_request_params'
+require 'api_hammer/rails/halt'
+require 'api_hammer/rails/check_required_params'
+require 'api_hammer/rails/unmunged_request_params'
 
-module ApiHammer::Rails
-  def self.included(klass)
-    (@on_included || []).each do |included_proc|
-      included_proc.call(klass)
+module ApiHammer
+  module Rails
+    def self.included(klass)
+      (@on_included || []).each do |included_proc|
+        included_proc.call(klass)
+      end
     end
   end
 end

data/lib/api_hammer/sinatra/halt.rb

@@ -0,0 +1,14 @@
+require 'api_hammer/halt_methods'
+
+module ApiHammer
+  module Sinatra
+    module Halt
+      # halt and render the given body 
+      def halt(status, body, render_options = {})
+        throw :halt, format_response(status, body, headers)
+      end
+
+      include HaltMethods
+    end
+  end
+end

data/lib/api_hammer/sinatra.rb

@@ -0,0 +1,157 @@
+require 'api_hammer/sinatra/halt'
+
+module ApiHammer
+  module Sinatra
+    def self.included(klass)
+      (@on_included || []).each do |included_proc|
+        included_proc.call(klass)
+      end
+    end
+
+    # override Sinatra::Base#route_missing
+    def route_missing
+      message = I18n.t('app.errors.request.route_404',
+        :default => "Not a known route: %{method} %{path}",
+        :method => env['REQUEST_METHOD'], :path => env['PATH_INFO']
+      )
+      halt_error(404, {'route' => [message]})
+    end
+
+    include ApiHammer::Sinatra::Halt
+
+    unless instance_variables.any? { |iv| iv.to_s == '@supported_media_types_included' }
+      @supported_media_types_included = proc do |klass|
+        klass.define_singleton_method(:supported_media_types=) do |supported_media_types|
+          @supported_media_types = supported_media_types
+        end
+        klass.define_singleton_method(:supported_media_types) do
+          @supported_media_types
+        end
+      end
+      (@on_included ||= Set.new) << @supported_media_types_included
+    end
+
+    def supported_media_types
+      self.class.supported_media_types
+    end
+
+    # finds the best match (highest q) for those supported_media_types indicated as acceptable by the Accept header. 
+    #
+    # If the Accept header is not present, assumes that any supported media type is acceptable, and returns the first 
+    # one.
+    #
+    # if the :halt_if_unacceptable option is true and no supported media type is acceptable, this halts with 406. 
+    #
+    # if the :halt_if_unacceptable option is false (or omitted) and no supported media type is acceptable, this 
+    # returns the first supported media type. 
+    def response_media_type(options={})
+      options = {:halt_if_unacceptable => false}.merge(options)
+      accept = env['HTTP_ACCEPT']
+      if accept =~ /\S/
+        begin
+          best_media_type = env['rack-accept.request'].best_media_type(supported_media_types)
+        rescue RuntimeError => e
+          # TODO: this is a crappy way to recognize this exception 
+          raise unless e.message =~ /Invalid header value/
+        end
+        if best_media_type
+          best_media_type
+        else
+          if options[:halt_if_unacceptable]
+            logger.error "received Accept header of #{accept.inspect}; halting with 406"
+            message = I18n.t('app.errors.request.accept',
+              :default => "The request indicated that no supported media type is acceptable. Supported media types are: %{supported_media_types}. The request specified Accept: %{accept}",
+              :accept => accept,
+              :supported_media_types => supported_media_types.join(', ')
+            )
+            halt_error(406, {'Accept' => [message]})
+          else
+            supported_media_types.first
+          end
+        end
+      else
+        supported_media_types.first
+      end
+    end
+
+    def check_accept
+      response_media_type(:halt_if_unacceptable => true)
+    end
+
+    # returns a rack response with the given object encoded in the appropriate format for the requests. 
+    #
+    # arguments are in the order of what tends to vary most frequently 
+    # rather than rack's way, so headers come last 
+    def format_response(status, body_object, headers={})
+      body = case response_media_type
+      when 'application/json'
+        JSON.pretty_generate(body_object)
+      else
+        # :nocov:
+        raise NotImplementedError, "unsupported response media type #{response_media_type}"
+        # :nocov:
+      end
+      [status, headers.merge({'Content-Type' => response_media_type}), [body]]
+    end
+
+    # reads the request body 
+    def request_body
+      # rewind in case anything in the past has left this un-rewound 
+      request.body.rewind
+      request.body.read.tap do
+        # rewind in case anything in the future expects this to have been left rewound 
+        request.body.rewind
+      end
+    end
+
+    # returns the parsed contents of the request body. 
+    #
+    # checks the Content-Type of the request, and unless it's supported (or omitted - in which case assumed to be the
+    # first supported media type), halts with 415. 
+    #
+    # if the body is not parseable, then halts with 400. 
+    def parsed_body
+      request_media_type = request.media_type
+      unless request_media_type =~ /\S/
+        fallback = true
+        request_media_type = supported_media_types.first
+      end
+      case request_media_type
+      when 'application/json'
+        begin
+          return JSON.parse(request_body)
+        rescue JSON::ParserError
+          if fallback
+            t_key = 'app.errors.request.body_parse_fallback_json'
+            default = "Error encountered attempting to parse the request body. No Content-Type was specified and parsing as JSON failed. Supported media types are %{supported_media_types}. JSON parser error: %{error_class}: %{error_message}"
+          else
+            t_key = 'app.errors.request.body_parse_indicated_json'
+            default = "Error encountered attempting to parse the JSON request body: %{error_class}: %{error_message}"
+          end
+          message = I18n.t(t_key,
+            :default => default,
+            :error_class => $!.class,
+            :error_message => $!.message,
+            :supported_media_types => supported_media_types.join(', ')
+          )
+          errors = {'json' => [message]}
+          halt_error(400, errors)
+        end
+      else
+        if supported_media_types.include?(request_media_type)
+          # :nocov:
+          raise NotImplementedError, "handling request body with media type #{request_media_type} not implemented"
+          # :nocov:
+        end
+        logger.error "received Content-Type of #{request.content_type.inspect}; halting with 415"
+        message = I18n.t('app.errors.request.content_type',
+          :default => "Unsupported Content-Type of %{content_type} given for the request body. Supported media types are %{supported_media_types}",
+          :content_type => request.content_type,
+          :supported_media_types => supported_media_types.join(', ')
+        )
+        errors = {'Content-Type' => [message]}
+        halt_error(415, errors)
+      end
+    end
+  end
+end

data/lib/api_hammer/version.rb

@@ -1,3 +1,3 @@
 module ApiHammer
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
 end

data/lib/api_hammer.rb

@@ -4,6 +4,7 @@ require 'api_hammer/version'
 
 module ApiHammer
   autoload :Rails, 'api_hammer/rails'
+  autoload :Sinatra, 'api_hammer/sinatra'
   autoload :RequestLogger, 'api_hammer/request_logger'
   autoload :ShowTextExceptions, 'api_hammer/show_text_exceptions'
   autoload :TrailingNewline, 'api_hammer/trailing_newline'

data/test/check_required_params_test.rb

@@ -24,43 +24,43 @@ describe 'ApiHammer::Rails#check_required_params' do
 
     it 'is missing id' do
       c = controller_with_params(:person => {:name => 'hammer', :height => '3'}, :lucky_numbers => ['2'])
-      err = assert_raises(ApiHammer::Halt) { c.check_required_params(checks) }
+      err = assert_raises(ApiHammer::Rails::Halt) { c.check_required_params(checks) }
       assert_equal({'error_message' => 'id is required but was not provided', 'errors' => {'id' => ['id is required but was not provided']}}, err.body)
     end
 
     it 'is missing person' do
       c = controller_with_params(:id => '99', :lucky_numbers => ['2'])
-      err = assert_raises(ApiHammer::Halt) { c.check_required_params(checks) }
+      err = assert_raises(ApiHammer::Rails::Halt) { c.check_required_params(checks) }
       assert_equal({'error_message' => 'person is required but was not provided', 'errors' => {'person' => ['person is required but was not provided']}}, err.body)
     end
 
     it 'is has the wrong type for person' do
       c = controller_with_params(:id => '99', :person => ['hammer', '3'], :lucky_numbers => ['2'])
-      err = assert_raises(ApiHammer::Halt) { c.check_required_params(checks) }
+      err = assert_raises(ApiHammer::Rails::Halt) { c.check_required_params(checks) }
       assert_equal({'error_message' => 'person must be a Hash', 'errors' => {'person' => ['person must be a Hash']}}, err.body)
     end
 
     it 'is missing person#name' do
       c = controller_with_params(:id => '99', :person => {:height => '3'}, :lucky_numbers => ['2'])
-      err = assert_raises(ApiHammer::Halt) { c.check_required_params(checks) }
+      err = assert_raises(ApiHammer::Rails::Halt) { c.check_required_params(checks) }
       assert_equal({'error_message' => 'person#name is required but was not provided', 'errors' => {'person#name' => ['person#name is required but was not provided']}}, err.body)
     end
 
     it 'is missing lucky_numbers' do
       c = controller_with_params(:id => '99', :person => {:name => 'hammer', :height => '3'})
-      err = assert_raises(ApiHammer::Halt) { c.check_required_params(checks) }
+      err = assert_raises(ApiHammer::Rails::Halt) { c.check_required_params(checks) }
       assert_equal({'error_message' => 'lucky_numbers is required but was not provided', 'errors' => {'lucky_numbers' => ['lucky_numbers is required but was not provided']}}, err.body)
     end
 
     it 'has the wrong type for lucky_numbers' do
       c = controller_with_params(:id => '99', :person => {:name => 'hammer', :height => '3'}, :lucky_numbers => '2')
-      err = assert_raises(ApiHammer::Halt) { c.check_required_params(checks) }
+      err = assert_raises(ApiHammer::Rails::Halt) { c.check_required_params(checks) }
       assert_equal({'error_message' => 'lucky_numbers must be a Array', 'errors' => {'lucky_numbers' => ['lucky_numbers must be a Array']}}, err.body)
     end
 
     it 'has multiple problems' do
       c = controller_with_params({})
-      err = assert_raises(ApiHammer::Halt) { c.check_required_params(checks) }
+      err = assert_raises(ApiHammer::Rails::Halt) { c.check_required_params(checks) }
       assert_equal({'error_message' => 'id is required but was not provided. person is required but was not provided. lucky_numbers is required but was not provided.', 'errors' => {'id' => ['id is required but was not provided'], 'person' => ['person is required but was not provided'], 'lucky_numbers' => ['lucky_numbers is required but was not provided']}}, err.body)
     end
   end

data/test/halt_test.rb

@@ -14,19 +14,19 @@ class FakeController
 end
 
 describe 'ApiHammer::Rails#halt' do
-  it 'raises ApiHammer::Halt' do
-    haltex = assert_raises(ApiHammer::Halt) { FakeController.new.halt(200, {}) }
+  it 'raises ApiHammer::Rails::Halt' do
+    haltex = assert_raises(ApiHammer::Rails::Halt) { FakeController.new.halt(200, {}) }
     assert_equal({}, haltex.body)
     assert_equal(200, haltex.render_options[:status])
   end
   describe 'status-specific halts' do
     it 'halts ok' do
-      haltex = assert_raises(ApiHammer::Halt) { FakeController.new.halt_ok({}) }
+      haltex = assert_raises(ApiHammer::Rails::Halt) { FakeController.new.halt_ok({}) }
       assert_equal({}, haltex.body)
       assert_equal(200, haltex.render_options[:status])
     end
     it 'halts unprocessable entity' do
-      haltex = assert_raises(ApiHammer::Halt) { FakeController.new.halt_unprocessable_entity({}) }
+      haltex = assert_raises(ApiHammer::Rails::Halt) { FakeController.new.halt_unprocessable_entity({}) }
       assert_equal({'errors' => {}}, haltex.body)
       assert_equal(422, haltex.render_options[:status])
     end
@@ -49,7 +49,7 @@ describe 'ApiHammer::Rails#halt' do
           define_method(:table_name) { 'record' }
         end
       end
-      haltex = assert_raises(ApiHammer::Halt) { FakeController.new.find_or_halt(model, {:id => 'anid'}) }
+      haltex = assert_raises(ApiHammer::Rails::Halt) { FakeController.new.find_or_halt(model, {:id => 'anid'}) }
       assert_equal({'error_message' => 'Unknown record! id: anid', 'errors' => {'record' => ['Unknown record! id: anid']}}, haltex.body)
       assert_equal(404, haltex.render_options[:status])
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api_hammer
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Ethan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-22 00:00:00.000000000 Z
+date: 2016-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -245,25 +245,28 @@ files:
 - lib/api_hammer.rb
 - lib/api_hammer/active_record_cache_find_by.rb
 - lib/api_hammer/body.rb
-- lib/api_hammer/check_required_params.rb
 - lib/api_hammer/content_type_attrs.rb
 - lib/api_hammer/faraday/outputter.rb
 - lib/api_hammer/faraday/request_logger.rb
 - lib/api_hammer/filtration/form_encoded.rb
 - lib/api_hammer/filtration/json.rb
-- lib/api_hammer/halt.rb
+- lib/api_hammer/halt_methods.rb
 - lib/api_hammer/json_script_escape_helper.rb
 - lib/api_hammer/public_instance_exec.rb
 - lib/api_hammer/rails.rb
+- lib/api_hammer/rails/check_required_params.rb
+- lib/api_hammer/rails/halt.rb
+- lib/api_hammer/rails/unmunged_request_params.rb
 - lib/api_hammer/rails_or_sidekiq_logger.rb
 - lib/api_hammer/rails_request_logging.rb
 - lib/api_hammer/request_logger.rb
 - lib/api_hammer/show_text_exceptions.rb
+- lib/api_hammer/sinatra.rb
+- lib/api_hammer/sinatra/halt.rb
 - lib/api_hammer/tasks.rb
 - lib/api_hammer/tasks/cucumber_pretty.rb
 - lib/api_hammer/tasks/gem_available_updates.rb
 - lib/api_hammer/trailing_newline.rb
-- lib/api_hammer/unmunged_request_params.rb
 - lib/api_hammer/version.rb
 - lib/api_hammer/weblink.rb
 - lib/logstash/filters/active_support_tags.rb