sinatra-api-helpers 1.0.0

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format doc
+--require spec_helper

data/.yardopts

@@ -0,0 +1 @@
+--protected -m markdown -r README.md

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2013 Algol Labs, LLC. <dev@algollabs.com>
+
+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/README.md

@@ -0,0 +1,7 @@
+# Sinatra::API
+
+API parameter enforcing, coercion, and parameter-resource automatic resolution.
+
+## License
+
+This gem is licensed under the MIT license. Copyright Algol Labs, LLC. 2013

data/lib/sinatra-api-helpers.rb

@@ -0,0 +1,32 @@
+# Copyright (c) 2013 Algol Labs, LLC. <dev@algollabs.com>
+#
+# 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.
+#
+
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__)))
+
+require 'json'
+require 'sinatra/base'
+require 'sinatra/api/ext/hash'
+require 'sinatra/api/version'
+require 'sinatra/api/helpers'
+
+module Sinatra
+  register API
+end

data/lib/sinatra/api/ext/hash.rb

@@ -0,0 +1,24 @@
+class Hash
+  unless Hash.instance_methods.include?(:deep_merge)
+    # Merges self with another hash, recursively.
+    #
+    # This code was lovingly stolen from some random gem:
+    # http://gemjack.com/gems/tartan-0.1.1/classes/Hash.html
+    #
+    # Thanks to whoever made it.
+    def deep_merge(hash)
+      target = dup
+
+      hash.keys.each do |key|
+        if hash[key].is_a? Hash and self[key].is_a? Hash
+          target[key] = target[key].deep_merge(hash[key])
+          next
+        end
+
+        target[key] = hash[key]
+      end
+
+      target
+    end
+  end
+end

data/lib/sinatra/api/helpers.rb

@@ -0,0 +1,256 @@
+# Copyright (c) 2013 Algol Labs, LLC. <dev@algollabs.com>
+#
+# 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.
+#
+
+module Sinatra
+  # TODO: accept nested parameters
+  module API
+    module Helpers
+      def api_call?
+        (request.accept || '').to_s.include?('json') ||
+        (request.content_type||'').to_s.include?('json')
+      end
+
+      # Define the required API arguments map. Any item defined
+      # not found in the supplied parameters of the API call will
+      # result in a 400 RC with a proper message marking the missing
+      # field.
+      #
+      # The map is a Hash of parameter keys and optional validator blocks.
+      #
+      # @example A map of required API call arguments
+      #   api_required!({ title: nil, user_id: nil })
+      #
+      # Each entry can be optionally mapped to a validation proc that will
+      # be invoked *if* the field was supplied. The proc will be passed
+      # the value of the field.
+      #
+      # If the value is invalid and you need to suspend the request, you
+      # must return a String object with an appropriate error message.
+      #
+      # @example Rejecting a title if it's rude
+      #   api_required!({
+      #     :title => lambda { |t| return "Don't be rude" if t && t =~ /rude/ }
+      #   })
+      #
+      # @note
+      #   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.each_pair { |name, cnd|
+          if cnd.is_a?(Hash)
+            api_required!(cnd, h[name])
+            next
+          end
+
+          parse_api_argument(h, name, cnd, :required)
+        }
+      end
+
+      # Same as #api_required! except that fields defined in this map
+      # are optional and will be used only if they're supplied.
+      #
+      # @see #api_required!
+      def api_optional!(args, h = params)
+        args.each_pair { |name, cnd|
+          if cnd.is_a?(Hash)
+            api_optional!(cnd, h[name])
+            next
+          end
+
+          parse_api_argument(h, name, cnd, :optional)
+        }
+      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
+      #
+      def api_consume!(keys)
+        out  = nil
+
+        keys = [ keys ] unless keys.is_a?(Array)
+        keys.each do |k|
+          if val = @api[:required].delete(k.to_sym)
+            out = val
+            out = yield(val) if block_given?
+          end
+
+          if val = @api[:optional].delete(k.to_sym)
+            out = val
+            out = yield(val) if block_given?
+          end
+        end
+
+        out
+      end
+
+      def api_transform!(key, &handler)
+        if val = @api[:required][key.to_sym]
+          @api[:required][key.to_sym] = yield(val) if block_given?
+        end
+
+        if val = @api[:optional][key.to_sym]
+          @api[:optional][key.to_sym] = yield(val) if block_given?
+        end
+      end
+
+      def api_has_param?(key)
+        @api[:optional].has_key?(key)
+      end
+
+      def api_param(key)
+        @api[:optional][key.to_sym] || @api[:required][key.to_sym]
+      end
+
+      # Returns a Hash of the *supplied* request parameters. Rejects
+      # any parameter that was not defined in the REQUIRED or OPTIONAL
+      # maps (or was consumed).
+      #
+      # @param Hash q A Hash of attributes to merge with the parameters,
+      #               useful for defining defaults
+      def api_params(q = {})
+        @api[:optional].deep_merge(@api[:required]).deep_merge(q)
+      end
+
+      def api_clear!()
+        @api = { required: {}, optional: {} }
+      end
+
+      alias_method :api_reset!, :api_clear!
+
+      # Attempt to locate a resource based on an ID supplied in a request parameter.
+      #
+      # If the param map contains a resource id (ie, :folder_id),
+      # we attempt to locate and expose it to the route.
+      #
+      # A 404 is raised if:
+      #   1. the scope is missing (@space for folder, @space or @folder for page)
+      #   2. the resource couldn't be identified in its scope (@space or @folder)
+      #
+      # If the resources were located, they're accessible using @folder or @page.
+      #
+      # The route can be halted using the :requires => [] condition when it expects
+      # a resource.
+      #
+      # @example using :requires to reject a request with an invalid @page
+      #   get '/folders/:folder_id/pages/:page_id', :requires => [ :page ] do
+      #     @page.show    # page is good
+      #     @folder.show  # so is its folder
+      #   end
+      #
+      def __api_locate_resource(r, container = nil)
+
+        resource_id = params[r + '_id'].to_i
+        rklass      = r.capitalize
+
+        collection = case
+        when container.nil?;  eval "#{rklass}"
+        else;                 container.send("#{r.to_plural}")
+        end
+
+        puts "locating resource #{r} with id #{resource_id} from #{collection} [#{container}]"
+
+        resource = collection.get(resource_id)
+
+        if !resource
+          m = "No such resource: #{rklass}##{resource_id}"
+          if container
+            m << " in #{container.class.name.to_s}##{container.id}"
+          end
+
+          halt 404, m
+        end
+
+        if respond_to?(:can?)
+          unless can? :access, resource
+            halt 403, "You do not have access to this #{rklass} resource."
+          end
+        end
+
+        instance_variable_set('@'+r, resource)
+
+        resource
+      end
+
+      private
+
+      def parse_api_argument(h = params, name, cnd, type)
+        cnd ||= lambda { |*_| true }
+        name = name.to_s
+
+        unless [:required, :optional].include?(type)
+          raise ArgumentError, 'API Argument type must be either :required or :optional'
+        end
+
+        if !h.has_key?(name)
+          if type == :required
+            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
+
+          @api[type][name.to_sym] = h[name]
+        end
+      end
+    end
+
+    def self.registered(app)
+      app.helpers Helpers
+      app.before do
+        @api = { required: {}, optional: {} }
+        @parent_resource = nil
+
+        if api_call?
+          request.body.rewind
+          body = request.body.read.to_s || ''
+          unless body.empty?
+            begin;
+              params.merge!(::JSON.parse(body))
+              # puts params.inspect
+              # puts request.path
+            rescue ::JSON::ParserError => e
+              puts e.message
+              puts e.backtrace
+              halt 400, "Malformed JSON content"
+            end
+          end
+        end
+      end
+
+      app.set(:requires) do |*resources|
+        condition do
+          @required = resources.collect { |r| r.to_s }
+          @required.each { |r| @parent_resource = __api_locate_resource(r, @parent_resource) }
+        end
+      end
+
+    end
+  end
+end

data/lib/sinatra/api/version.rb

@@ -0,0 +1,26 @@
+# Copyright (c) 2013 Algol Labs, LLC. <dev@algollabs.com>
+#
+# 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.
+#
+
+module Sinatra
+  module API
+    VERSION = "1.0.0"
+  end
+end

data/sinatra-api-helpers.gemspec

@@ -0,0 +1,24 @@
+require File.join(%W[#{File.dirname(__FILE__)} lib sinatra api version])
+
+Gem::Specification.new do |s|
+  s.name        = 'sinatra-api-helpers'
+  s.summary     = 'Handy helpers for writing RESTful APIs in Sinatra.'
+  s.version     = Sinatra::API::VERSION
+  s.date        = Time.now.strftime('%Y-%m-%d')
+  s.authors     = [ 'Ahmad Amireh' ]
+  s.email       = 'ahmad@algollabs.com'
+  s.homepage    = 'https://github.com/amireh/sinatra-api-helpers'
+  s.files       = Dir.glob("{lib,spec}/**/*.rb") +
+                  [ 'LICENSE', 'README.md', '.rspec', '.yardopts', __FILE__ ]
+  s.has_rdoc    = 'yard'
+  s.license     = 'MIT'
+
+  s.required_ruby_version = '>= 1.9.3'
+
+  s.add_dependency 'json'
+  s.add_dependency 'sinatra'
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rack-test'
+  s.add_development_dependency 'yard', '>= 0.8.0'
+end

data/spec/helpers/router.rb

@@ -0,0 +1,60 @@
+module Router
+  class << self
+    def puts(*args)
+      super(*args) if $VERBOSE
+    end
+
+    # Locates routes defined for any verb containing the provided token.
+    #
+    # @param [String] token the token the route should contain
+    # @return [Array<Hash, Fixnum>] a map of all the verb routes, and the count of located routes
+    def routes_for(token)
+      all_routes = {}
+      count  = 0
+      Sinatra::Application.routes.each do |verb_routes|
+        verb, routes = verb_routes[0], verb_routes[1]
+        all_routes[verb] ||= []
+        routes.each_with_index do |route, i|
+          route_regex = route.first.source
+          if route_regex.to_s.include?(token)
+            all_routes[verb] << route
+            count += 1
+
+            puts "Route located: #{verb} -> #{route_regex.to_s}"
+          end
+        end
+        all_routes[verb].uniq!
+      end
+      [ all_routes, count ]
+    end
+
+    def purge(token)
+      routes, nr_routes = *routes_for(token)
+
+      # puts "cleaning up #{nr_routes} routes"
+
+      routes.each_pair do |verb, vroutes|
+        vroutes.each do |r| delete_route(verb, r) end
+      end
+
+      yield(nr_routes) if block_given?
+
+      nr_routes
+    end
+
+    protected
+
+    def delete_route(verb, r)
+      verb_routes = Sinatra::Application.routes.select { |v| v == verb }.first
+
+      unless verb_routes
+        raise "Couldn't find routes for verb #{verb}, that's impossible"
+      end
+
+      unless verb_routes[1].delete(r)
+        raise "Route '#{r}' not found for verb #{verb}"
+      end
+    end
+
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,40 @@
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..')
+
+ENV['RACK_ENV'] = 'test'
+
+
+require 'lib/sinatra-api-helpers'
+require 'rspec'
+require 'rack/test'
+
+class SinatraAPITestApp < Sinatra::Base
+  register Sinatra::API
+end
+
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  Thread.abort_on_exception = true
+
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus => true
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+
+  include Rack::Test::Methods
+
+  def app
+    Sinatra::Application
+  end
+end
+
+Dir["./spec/helpers/**/*.rb"].sort.each { |f| require f }

data/spec/unit/helpers_spec.rb

@@ -0,0 +1,123 @@
+describe "Helpers" do
+  before :each do
+    Router.purge('/')
+  end
+
+  class ModelAdapter
+  end
+
+  class CollectionAdapter
+    def initialize(model)
+      @model = model
+    end
+
+    def self.get(key)
+      return @model.new
+    end
+  end
+
+  class Item
+    def self.get(id)
+      return {} if id == 1
+    end
+
+    def sub_items
+      CollectionAdapter.new(SubItem)
+    end
+  end
+
+  class SubItem < ModelAdapter
+    def item
+      Item.new
+    end
+  end
+
+  it "should reject a request missing a required parameter" do
+    app.get '/' do
+      api_required!({
+        id: nil
+      })
+    end
+
+    get '/'
+    last_response.status.should == 400
+    last_response.body.should match(/Missing required parameter :id/)
+  end
+
+  it "should accept a request satisfying required parameters" do
+    app.get '/' do
+      api_required!({
+        id: nil
+      })
+    end
+
+    get '/', { id: 5 }
+    last_response.status.should == 200
+  end
+
+  it "should accept a request not satisfying optional parameters" do
+    app.get '/' do
+      api_required!({
+        id: nil
+      })
+      api_optional!({
+        name: nil
+      })
+    end
+
+    get '/', { id: 5 }
+    last_response.status.should == 200
+  end
+
+  it "should apply parameter conditions" do
+    app.get '/' do
+      api_optional!({
+        name: lambda { |v|
+          unless (v || '').match /ahmad/
+            "Unexpected name."
+          end
+        }
+      })
+    end
+
+    get '/', { name: 'foobar' }
+    last_response.status.should == 400
+    last_response.body.should match(/Unexpected name/)
+
+    get '/', { name: 'ahmad' }
+    last_response.status.should == 200
+  end
+
+  it "should pick parameters" do
+    app.get '/' do
+      api_optional!({
+        name: nil
+      })
+
+      api_params.to_json
+    end
+
+    get '/', {
+      name: 'foobar',
+      some: 'thing'
+    }
+
+    last_response.body.should == {
+      name: 'foobar'
+    }.to_json
+  end
+
+  it "should locate a resource" do
+    app.get '/items/:item_id', requires: [ :item ] do
+      @item.to_json
+    end
+
+    get '/items/1'
+    last_response.status.should == 200
+    last_response.body.should == {}.to_json
+
+    get '/items/2'
+    last_response.status.should == 404
+    last_response.body.should match /No such resource/
+  end
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: sinatra-api-helpers
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Ahmad Amireh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-09-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  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
+    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: rack-test
+  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: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+description: 
+email: ahmad@algollabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/sinatra-api-helpers.rb
+- lib/sinatra/api/helpers.rb
+- lib/sinatra/api/version.rb
+- lib/sinatra/api/ext/hash.rb
+- spec/unit/helpers_spec.rb
+- spec/helpers/router.rb
+- spec/spec_helper.rb
+- LICENSE
+- README.md
+- .rspec
+- .yardopts
+- sinatra-api-helpers.gemspec
+homepage: https://github.com/amireh/sinatra-api-helpers
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Handy helpers for writing RESTful APIs in Sinatra.
+test_files: []
+has_rdoc: yard