sinatra-api 1.0.2 → 1.1.2

data/.yardopts

@@ -1 +1 @@
---protected --private -m markdown -r README.md
+--protected -m markdown -r README.md

data/lib/sinatra/api.rb

@@ -27,11 +27,17 @@ require 'sinatra/base'
 require 'active_support/core_ext/hash'
 require 'active_support/core_ext/string'
 require 'sinatra/api/version'
+require 'sinatra/api/config'
 require 'sinatra/api/callbacks'
 require 'sinatra/api/helpers'
+require 'sinatra/api/error_handler'
 require 'sinatra/api/resource_aliases'
 require 'sinatra/api/resources'
 require 'sinatra/api/parameters'
+require 'sinatra/api/parameter_validator'
+require 'sinatra/api/parameter_validators/string_validator'
+require 'sinatra/api/parameter_validators/integer_validator'
+require 'sinatra/api/parameter_validators/float_validator'
 
 module Sinatra
   module API
@@ -49,6 +55,16 @@ module Sinatra
       #   The Sinatra instance that is evaluating the current request.
       attr_accessor :instance
 
+      # @!attribute instance
+      #   @return [Sinatra::Base]
+      #   The Sinatra application.
+      attr_accessor :app
+
+      # @!attribute config
+      #   @return [Sinatra::API::Config]
+      #   Runtime configuration options.
+      attr_accessor :config
+
       # Parse a JSON construct from a string stream.
       #
       # Override this to use a custom JSON parser, if necessary.
@@ -59,45 +75,52 @@ module Sinatra
       def parse_json(stream)
         ::JSON.parse(stream)
       end
+
+      def configure(options = {})
+        self.config = Config.new(options)
+      end
+
+      def process!(params, request)
+        request.body.rewind
+        raw_json = request.body.read.to_s || ''
+
+        unless raw_json.empty?
+          begin
+            params.merge!(parse_json(raw_json))
+          rescue ::JSON::ParserError => e
+            logger.warn e.message
+            logger.warn e.backtrace
+
+            instance.halt 400, "Malformed JSON content"
+          end
+        end
+      end
     end
 
     ResourcePrefix = '::'
 
     def self.registered(app)
-      base = self
+      api = self
+      self.app = app
       self.logger = ActiveSupport::Logger.new(STDOUT)
-
+      self.logger.level = 100
       app.helpers Helpers, Parameters, Resources
-      app.before do
-        base.instance = self
-
-        @api = { required: {}, optional: {} }
-        @parent_resource = nil
 
-        if api_call?
-          request.body.rewind
-          raw_json = request.body.read.to_s || ''
+      ParameterValidator.install(api)
 
-          unless raw_json.empty?
-            begin
-              params.merge!(base.parse_json(raw_json))
-            rescue ::JSON::ParserError => e
-              logger.warn e.message
-              logger.warn e.backtrace
+      on :with_errors_setting do |setting|
+        app.helpers ErrorHandler if setting
+      end
 
-              halt 400, "Malformed JSON content"
-            end
-          end
-        end
+      on :verbose_setting do |setting|
+        logger.level = setting ? 0 : 100
       end
 
-      app.set(:requires) do |*resources|
-        condition do
-          @required = resources.collect { |r| r.to_s }
-          @required.each do |r|
-            @parent_resource = api_locate_resource(r, @parent_resource)
-          end
-        end
+      app.before do
+        api.instance = self
+        api.trigger :request, self
+
+        api.process!(params, request) if api_call?
       end
     end
   end

data/lib/sinatra/api/callbacks.rb

@@ -21,6 +21,7 @@
 
 module Sinatra
   module API
+    # An event pub/sub interface.
     module Callbacks
       attr_accessor :callbacks
 
@@ -28,10 +29,38 @@ module Sinatra
         base.callbacks = {}
       end
 
+      # Add a callback to a given event.
+      #
+      # @example Listening to :resource_located events
+      #
+      #     Sinatra::API.on :resource_located do |resource, name|
+      #       if resource.is_a?(Monkey)
+      #         resource.eat_banana
+      #       end
+      #     end
+      #
+      # @example A callback with an instance method
+      #
+      #   class Monkey
+      #     def initialize
+      #       # This means that the monkey will eat a banana everytime a resource
+      #       # is located.
+      #       Sinatra::API.on :resource_located, &method(:eat_banana)
+      #     end
+      #
+      #     def eat_banana(*args)
+      #     end
+      #   end
       def on(event, &callback)
         (self.callbacks[event.to_sym] ||= []) << callback
       end
 
+      # Broadcast an event to subscribed callbacks.
+      #
+      # @example Triggering an event with an argument
+      #
+      #     Sinatra::API.trigger :special_event, 'Special Argument'
+      #
       def trigger(event, *args)
         callbacks = self.callbacks[event.to_sym] || []
         callbacks.each do |callback|

data/lib/sinatra/api/config.rb

@@ -0,0 +1,42 @@
+module Sinatra::API
+  class Config
+    attr_accessor :with_errors
+    attr_accessor :verbose
+
+    Defaults = {
+      with_errors: true,
+      verbose: false
+    }
+
+    def initialize(options = {})
+      api = Sinatra::API
+
+      options = {}.merge(Config::Defaults).merge(options)
+      options.each_pair do |key, setting|
+        unless self.respond_to?(key)
+          api.logger.warn "Unknown option #{key} => #{setting}"
+          next
+        end
+
+        self[key] = setting if changed?(key, setting)
+      end
+
+      super()
+    end
+
+    def [](key)
+      self.send key rescue nil
+    end
+
+    def []=(key, value)
+      self.send("#{key}=", value)
+      Sinatra::API.trigger "#{key}_setting", value
+    end
+
+    private
+
+    def changed?(key, value)
+      self[key] != value
+    end
+  end
+end

data/lib/sinatra/api/error_handler.rb

@@ -0,0 +1,54 @@
+module Sinatra::API
+  module ErrorHandler
+    def format_api_error(message)
+      field_errors = {}
+
+      message = case
+      when message.is_a?(String)
+        [ message ]
+      when message.is_a?(Array)
+        message
+      when message.is_a?(Hash)
+        field_errors = message
+        message.collect { |k,v| v }
+      when message.is_a?(DataMapper::Validations::ValidationErrors)
+        field_errors = message.to_hash
+        message.to_hash.collect { |k,v| v }.flatten
+      else
+        [ "unexpected response: #{message.class} -> #{message}" ]
+      end
+
+      [ field_errors, message ]
+    end
+
+    def handle_api_error(message = response.body)
+      # Support for CORS pre-flight requests
+      if request.request_method == 'OPTIONS'
+        content_type :text
+        halt response.status
+      end
+
+      status response.status
+      content_type :json
+
+      field_errors, message = *format_api_error(message)
+
+      {
+        code: response.status,
+        status: 'error',
+        messages: message,
+        field_errors: field_errors
+      }.to_json
+    end
+
+    def self.included(base)
+      base.error 400 do
+        handle_api_error if api_call?
+      end
+
+      base.error 404 do
+        handle_api_error if api_call?
+      end
+    end
+  end
+end

data/lib/sinatra/api/helpers.rb

@@ -21,6 +21,7 @@
 
 module Sinatra::API
   module Helpers
+    # Determine if this is a JSON API request.
     def api_call?
       (request.accept || '').to_s.include?('json') ||
       (request.content_type||'').to_s.include?('json')

data/lib/sinatra/api/parameter_validator.rb

@@ -0,0 +1,90 @@
+module Sinatra::API
+  class ParameterValidator
+    attr_accessor :typenames
+
+    def initialize(*typenames)
+      self.typenames = typenames.flatten
+      super()
+    end
+
+    # Validate a given parameter value.
+    #
+    # @param [Any] value
+    #   The parameter value to validate.
+    #
+    # @param [Hash] options
+    #   Custom validator options defined by the user.
+    #
+    # @return [String] Error message if the parameter value is invalid.
+    # @return [Any] Any other value means the parameter is valid.
+    def validate(value, options = {})
+      raise NotImplementedError
+    end
+
+    class << self
+      attr_accessor :validators, :api
+
+      def install(api)
+        self.api = api
+        self.api.on :parameter_parsed, &method(:run_validators!)
+
+        install_validators
+      end
+
+      private
+
+      def run_validators!(key, hash, definition)
+        value = hash[key]
+        typename = definition[:type]
+        validator = definition[:validator]
+        validator ||= self.validators[typename]
+        definition[:coerce] = true unless definition.has_key?(:coerce)
+
+        if validator
+          # Backwards compatibility:
+          #
+          # validators were plain procs that received the value to validate.
+          if validator.respond_to?(:call)
+            rc = validator.call(value)
+          # Strongly-defined ParameterValidator objects
+          elsif validator.respond_to?(:validate)
+            rc = validator.validate(value, definition)
+          # ?
+          else
+            raise 'Invalid ParameterValidator, must respond to #call or #validate'
+          end
+
+          if rc.is_a?(String)
+            self.api.instance.halt 400, { :"#{key}" => rc }
+          end
+
+          # coerce the value, if viable
+          if validator.respond_to?(:coerce) && definition[:coerce].present?
+            hash[key] = validator.coerce(value, definition)
+          end
+        end
+      end
+
+      # Insantiate an instance of every Sinatra::API::SomethingValidator
+      # class defined and register them with the typenames they cover.
+      def install_validators
+        self.validators = {}
+
+        validator_klasses = self.api.constants.select { |k| k =~ /Validator$/ }
+        validator_klasses.each do |klass_id|
+          klass = self.api.const_get(klass_id)
+          validator = klass.new
+
+          unless validator.respond_to?(:validate)
+            raise "Invalid ParameterValidator #{klass_id}, must respond to #validate"
+          end
+
+          validator.typenames.each do |typename|
+            api.logger.debug "Validator defined: #{typename}"
+            validators[typename.to_s.downcase.to_sym] = validator
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sinatra/api/parameter_validators/float_validator.rb

@@ -0,0 +1,17 @@
+module Sinatra::API
+  class FloatValidator < ParameterValidator
+    def initialize
+      super(:float)
+    end
+
+    def validate(value, options)
+      Float(value)
+    rescue
+      "Not a valid float."
+    end
+
+    def coerce(value, options)
+      Float(value)
+    end
+  end
+end

data/lib/sinatra/api/parameter_validators/integer_validator.rb

@@ -0,0 +1,17 @@
+module Sinatra::API
+  class IntegerValidator < ParameterValidator
+    def initialize
+      super(:integer)
+    end
+
+    def validate(value, options)
+      Integer(value)
+    rescue
+      "Not a valid integer."
+    end
+
+    def coerce(value, options)
+      Integer(value)
+    end
+  end
+end

data/lib/sinatra/api/parameter_validators/string_validator.rb

@@ -0,0 +1,17 @@
+module Sinatra::API
+  class StringValidator < ParameterValidator
+    def initialize
+      super(:string, String)
+    end
+
+    def validate(value, options)
+      unless value.is_a?(String)
+        return "Expected value to be of type String, got #{value.class.name}"
+      end
+
+      if options[:format] && !value =~ options[:format]
+        return "Invalid format."
+      end
+    end
+  end
+end

data/lib/sinatra/api/parameters.rb

@@ -51,13 +51,15 @@ module Sinatra::API
     #   The supplied value passed to validation blocks is not pre-processed,
     #   so you must make sure that you check for nils or bad values in validator blocks!
     def api_required!(args, h = params)
+      args = api_parameters_to_hash(args) if args.is_a?(Array)
+
       args.each_pair do |name, cnd|
         if cnd.is_a?(Hash)
           api_required!(cnd, h[name])
           next
         end
 
-        parse_api_argument(h, name, cnd, :required)
+        parse_api_parameter(name, cnd, :required, h)
       end
     end
 
@@ -66,26 +68,33 @@ module Sinatra::API
     #
     # @see #api_required!
     def api_optional!(args, h = params)
+      args = api_parameters_to_hash(args) if args.is_a?(Array)
+
       args.each_pair { |name, cnd|
         if cnd.is_a?(Hash)
           api_optional!(cnd, h[name])
           next
         end
 
-        parse_api_argument(h, name, cnd, :optional)
+        parse_api_parameter(name, cnd, :optional, h)
       }
     end
 
+    def api_parameter!(id, options = {}, hash = params)
+      parameter_type = options[:required] ? :required : :optional
+      parameter_validator = options[:validator]
+
+      parse_api_parameter(id, parameter_validator, parameter_type, hash, options)
+    end
+
     # Consumes supplied parameters with the given keys from the API
     # parameter map, and yields the consumed values for processing by
     # the supplied block (if any).
     #
-    # This is useful if:
-    #  1. a certain parameter does not correspond to a model attribute
-    #     and needs to be renamed, or is used in a validation context
-    #  2. the data needs special treatment
-    #  3. the data needs to be (re)formatted
+    # This is useful when a certain parameter does not correspond to a model
+    # attribute and needs to be renamed, or is used only in a validation context.
     #
+    # Use #api_transform! if you only need to convert the value or process it.
     def api_consume!(keys)
       out  = nil
 
@@ -105,23 +114,38 @@ module Sinatra::API
       out
     end
 
+    # Transform the value for the given parameter in-place. Useful for
+    # post-processing or converting raw values.
+    #
+    # @param [String, Symbol] key
+    #   The key of the parameter defined earlier.
+    #
+    # @param [#call] handler
+    #   A callable construct that will receive the original value and should
+    #   return the transformed one.
     def api_transform!(key, &handler)
-      if val = @api[:required][key.to_sym]
-        @api[:required][key.to_sym] = yield(val) if block_given?
+      key = key.to_sym
+
+      if val = @api[:required][key]
+        @api[:required][key] = yield(val) if block_given?
       end
 
-      if val = @api[:optional][key.to_sym]
-        @api[:optional][key.to_sym] = yield(val) if block_given?
+      if val = @api[:optional][key]
+        @api[:optional][key] = yield(val) if block_given?
       end
     end
 
+    # Is the specified *optional* parameter supplied by the request?
     def api_has_param?(key)
       @api[:optional].has_key?(key)
     end
+    alias_method :has_api_parameter?, :api_has_param?
 
+    # Get the value of the given API parameter, if any.
     def api_param(key)
       @api[:optional][key.to_sym] || @api[:required][key.to_sym]
     end
+    alias_method :api_parameter, :api_param
 
     # Returns a Hash of the *supplied* request parameters. Rejects
     # any parameter that was not defined in the REQUIRED or OPTIONAL
@@ -135,18 +159,22 @@ module Sinatra::API
     end
 
     def api_clear!()
-      @api = { required: {}, optional: {} }
+      @api = {
+        required: {}.with_indifferent_access,
+        optional: {}.with_indifferent_access
+      }.with_indifferent_access
     end
-
     alias_method :api_reset!, :api_clear!
 
     private
 
-    def parse_api_argument(h = params, name, cnd, type)
-      cnd ||= lambda { |*_| true }
+    def parse_api_parameter(name, cnd, type, h = params, options = {})
+      # cnd ||= lambda { |*_| true }
       name = name.to_s
 
-      unless [:required, :optional].include?(type)
+      options[:validator] ||= cnd
+
+      unless [ :required, :optional ].include?(type)
         raise ArgumentError, 'API Argument type must be either :required or :optional'
       end
 
@@ -155,13 +183,27 @@ module Sinatra::API
           halt 400, "Missing required parameter :#{name}"
         end
       else
-        if cnd.respond_to?(:call)
-          errmsg = cnd.call(h[name])
-          halt 400, { :"#{name}" => errmsg } if errmsg && errmsg.is_a?(String)
-        end
+        Sinatra::API.trigger :parameter_parsed, name, h, options
+
+        # if cnd.respond_to?(:call)
+        #   errmsg = cnd.call(h[name])
+        #   halt 400, { :"#{name}" => errmsg } if errmsg && errmsg.is_a?(String)
+        # end
 
         @api[type][name.to_sym] = h[name]
       end
     end
+
+    def api_parameters_to_hash(args)
+      converted = {}
+      args.each { |name| converted[name] = nil }
+      converted
+    end
+
+    def self.included(app)
+      Sinatra::API.on :request do |request_scope|
+        request_scope.instance_eval &:api_reset!
+      end
+    end
   end
 end