sinatra-rest-addons 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Cyril Rohr
+
+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.rdoc

@@ -0,0 +1,8 @@
+= sinatra-rest-addons
+
+A set of helpers and extensions for sinatra apps that expose REST resources.
+
+== Copyright
+
+Copyright (c) 2009 Cyril Rohr. See LICENSE for details.
+Copyright (c) 2009 INRIA Rennes - Bretagne Atlantique. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sinatra-rest-addons"
+    gem.summary = %Q{A set of helpers and extensions for sinatra apps that expose REST resources.}
+    gem.description = %Q{A set of helpers and extensions for sinatra apps that expose REST resources.}
+    gem.email = "cyril.rohr@gmail.com"
+    gem.homepage = "http://github.com/crohr/sinatra-rest-addons"
+    gem.authors = ["Cyril Rohr"]
+    gem.add_development_dependency "contest", ">= 0"
+    gem.add_dependency "sinatra", ">= 0.9.0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "sinatra-rest-addons #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/sinatra/rest/helpers.rb

@@ -0,0 +1,16 @@
+require 'digest/sha1'
+
+module Sinatra
+  module REST
+    # Include it with:
+    #   class App < Sinatra::Base
+    #     helpers Sinatra::REST::Helpers
+    #   end
+    module Helpers    
+      def compute_etag(*args)
+        raise ArgumentError, "You must provide at least one parameter for the ETag computation" if args.empty?
+        Digest::SHA1.hexdigest(args.join("."))
+      end
+    end # module Helpers
+  end # module REST
+end # module Sinatra

data/lib/sinatra/rest/routes.rb

@@ -0,0 +1,116 @@
+require 'sinatra/base'
+
+module Sinatra
+  module REST
+    # Include it with:
+    #   class App < Sinatra::Base
+    #     register Sinatra::REST::Routes
+    #   end
+    module Routes
+      INFINITY = 1/0.0
+      
+      # Allow the definition of OPTIONS routes
+      def options(path, opts={}, &bk);   route 'OPTIONS',   path, opts, &bk end
+      
+      # e.g.
+      #   get '/', :provides => [:xml, "text/html;level=5"] { "hello" }
+      # will accept requests with Accept header =
+      # * application/xml
+      # * application/*
+      # * text/html
+      # * text/html;level=5
+      # * text/html;level=6
+      def provides(*formats)
+        generate_type_hash = Proc.new{ |header| 
+          type, *params = header.split(/;\s*/)
+          Hash[*params.map{|p| p.split(/\s*=\s*/)}.flatten].merge("type" => type)
+        }
+        condition {
+          supported_formats = formats.map do |f| 
+            # selects the correct mime type if a symbol is given
+            f.is_a?(Symbol) ? ::Rack::Mime::MIME_TYPES[".#{f.to_s}"] : f
+          end.compact.map do |f|
+            generate_type_hash.call(f)
+          end
+          # request.accept is an Array
+          accepted_formats = request.accept.map do |f| 
+            generate_type_hash.call(f)
+          end
+          selected_format = supported_formats.detect{ |supported_format| 
+            !accepted_formats.detect{ |accepted_format| 
+              Regexp.new(Regexp.escape(accepted_format["type"]).gsub("\\*", ".*?"), Regexp::IGNORECASE) =~ supported_format["type"] &&
+                (accepted_format["level"] || INFINITY).to_f >= (supported_format["level"] || 0).to_f
+            }.nil?
+          }      
+          if selected_format.nil?
+            content_type :txt
+            halt 406, supported_formats.map{|f| 
+              output = f["type"]
+              output.concat(";level=#{f["level"]}") if f.has_key?("level")
+              output
+            }.join(",")
+          else
+            response.headers['Content-Type'] = "#{selected_format["type"]}#{selected_format["level"].nil? ? "" : ";level=#{selected_format["level"]}"}"
+          end
+        }
+      end # def provides
+    
+      # Allow access to the route based on the result of the given proc, whose argument is a <tt>credentials</tt> object.
+      # You MUST declare a helper function named <tt>credentials</tt> that will return an object (of your choice) containing the client's credentials, 
+      # that will be passed as an argument to the given Proc.
+      # Halts the response process with a 403 status code if the given proc returns false (you may then process the error with a <tt>error 403 {}</tt> block).
+      # e.g.
+      #   helpers do
+      #     def credentials; [params["user"], params["password"]]; end
+      #   end
+      #   get  '/', :allow => Proc.new{ |credentials| credentials.first == "someone" && credentials.last == "password" } do 
+      #     "allowed"
+      #   end
+      def allow(proc)
+        raise ArgumentError, "You must provide a Proc that returns true or false when given the result of a call to the 'credentials' helper" unless proc.kind_of?(Proc)
+        condition {
+          unless proc.call(credentials)
+            halt 403, "You cannot access this resource"
+          end
+        }
+      end # def allow
+    
+      # Automatically decode the input data (coming from a POST or PUT request) based on the request's content-type.
+      # First argument must be a parsing procedure that will be used to parse the input data according to its content type.
+      # The decoded input will be available in request.env['sinatra.decoded_input']
+      # e.g.
+      #   post  '/', 
+      #         :decode => Proc.new{ |content_type, content| 
+      #           content_type =~ /^application\/.*json$/i ? JSON.parse(content) : throw(:halt, [400, "Don't know how to parse '#{content_type}' content."])
+      #         } do 
+      #     "#{request.env['sinatra.decoded_input']}"
+      #   end
+      def decode(*args)
+        args = [args] unless args.kind_of? Array
+        parsing_proc  = args.shift
+        raise ArgumentError, "You must provide a proc to parse the input data" unless parsing_proc.kind_of?(Proc)
+        size_range    = args.shift || (1..(1024**3))
+        condition {
+          begin
+            case (mime_type = request.env['CONTENT_TYPE'])
+            when /^application\/x-www-form-urlencoded/i
+              request.env['sinatra.decoded_input'] = request.env['rack.request.form_hash']
+            else
+              if not size_range.include?(request.env['rack.input'].size)
+                content_type :txt
+                halt 400, "Input data size must be between #{size_range.begin} and #{size_range.end} bytes."
+              else
+                content = request.env['rack.input'].read
+                request.env['sinatra.decoded_input'] = parsing_proc.call(mime_type, content)
+              end
+            end
+          rescue StandardError => e  
+            content_type :txt
+            halt 400, "#{e.class.name}: #{e.message}"
+          end
+        }
+      end # def decode
+      
+    end # module Routes
+  end # module REST
+end # module Sinatra

data/sinatra-rest-addons.gemspec

@@ -0,0 +1,56 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{sinatra-rest-addons}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Cyril Rohr"]
+  s.date = %q{2009-11-13}
+  s.description = %q{A set of helpers and extensions for sinatra apps that expose REST resources.}
+  s.email = %q{cyril.rohr@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/sinatra/rest/helpers.rb",
+     "lib/sinatra/rest/routes.rb",
+     "sinatra-rest-addons.gemspec",
+     "test/helper.rb",
+     "test/test_routes.rb"
+  ]
+  s.homepage = %q{http://github.com/crohr/sinatra-rest-addons}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{A set of helpers and extensions for sinatra apps that expose REST resources.}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_routes.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<contest>, [">= 0"])
+      s.add_runtime_dependency(%q<sinatra>, [">= 0.9.0"])
+    else
+      s.add_dependency(%q<contest>, [">= 0"])
+      s.add_dependency(%q<sinatra>, [">= 0.9.0"])
+    end
+  else
+    s.add_dependency(%q<contest>, [">= 0"])
+    s.add_dependency(%q<sinatra>, [">= 0.9.0"])
+  end
+end
+

data/test/helper.rb

@@ -0,0 +1,38 @@
+#  Adapted from the Sinatra test suite
+ENV['RACK_ENV'] = 'test'
+
+begin
+  require 'rack'
+rescue LoadError
+  require 'rubygems'
+  require 'rack'
+end
+
+libdir = File.dirname(File.dirname(__FILE__)) + '/lib'
+$LOAD_PATH.unshift libdir unless $LOAD_PATH.include?(libdir)
+
+require 'contest'
+require 'rack/test'
+require 'sinatra/base'
+
+class Sinatra::Base
+  # Allow assertions in request context
+  include Test::Unit::Assertions
+end
+
+Sinatra::Base.set :environment, :test
+
+class Test::Unit::TestCase
+  include Rack::Test::Methods
+
+  # Sets up a Sinatra::Base subclass defined with the block
+  # given. Used in setup or individual spec methods to establish
+  # the application.
+  def mock_app(base=Sinatra::Base, &block)
+    @app = Sinatra.new(base, &block)
+  end
+
+  def app
+    Rack::Lint.new(@app)
+  end
+end

data/test/test_routes.rb

@@ -0,0 +1,240 @@
+require File.dirname(__FILE__) + '/helper'
+require 'sinatra/rest/routes'
+require 'json'
+
+class RoutesTest < Test::Unit::TestCase
+
+  test "defines OPTIONS request handlers with options" do
+    mock_app {
+      register Sinatra::REST::Routes
+      options '/hello' do
+        response['X-Hello'] = 'World!'
+        'remove me'
+      end
+    }
+  
+    request = Rack::MockRequest.new(@app)
+    response = request.request("OPTIONS", '/hello', {})
+    assert response.ok?
+    assert_equal 'World!', response.headers['X-Hello']
+    assert_equal 'remove me', response.body
+  end
+  
+  context "route option :provides" do
+
+  
+    test "should return 406 and the list of supported types, if the server does not support the types accepted by the client [simple matching]" do
+      mock_app {
+        register Sinatra::REST::Routes
+        get '/', :provides => ["application/xml", "application/vnd.x.y.z+xml"] do
+          request.env['HTTP_ACCEPT']
+        end
+      }
+      get '/', {}, { 'HTTP_ACCEPT' => 'application/json' }
+      assert_equal 406, last_response.status
+      assert_equal 'application/xml,application/vnd.x.y.z+xml', last_response.body
+      assert_equal 'text/plain', last_response.headers['Content-Type']
+    end
+    test "should return 406 if the accepted type has a level lower than what is supported" do
+      mock_app {
+        register Sinatra::REST::Routes
+        get '/', :provides => ["application/xml;level=5"] do
+          request.env['HTTP_ACCEPT']
+        end
+      }
+      get '/', {}, { 'HTTP_ACCEPT' => 'application/xml;level=4' }
+      assert_equal 406, last_response.status
+      assert_equal 'application/xml;level=5', last_response.body
+      assert_equal 'text/plain', last_response.headers['Content-Type']
+    end
+    test "should return the first matching type if the accepted type contains a *" do
+      mock_app {
+        register Sinatra::REST::Routes
+        get '/', :provides => ["application/xml", "application/vnd.x.y.z+xml"] do
+          request.env['HTTP_ACCEPT']
+        end
+      }
+      get '/', {}, { 'HTTP_ACCEPT' => 'application/*' }
+      assert_equal 200, last_response.status
+      assert_equal 'application/*', last_response.body
+      assert_equal 'application/xml', last_response.headers['Content-Type']
+    end
+    test "should be successful if the accepted type does not require a specific level" do
+      mock_app {
+        register Sinatra::REST::Routes
+        get '/', :provides => ["application/xml;level=5"] do
+          request.env['HTTP_ACCEPT']
+        end
+      }
+      get '/', {}, { 'HTTP_ACCEPT' => 'application/xml' }
+      assert last_response.ok?
+      assert_equal 'application/xml', last_response.body
+      assert_equal 'application/xml;level=5', last_response.headers['Content-Type']
+    end
+    test "should be successful if the accepted type level is greater than what is supported" do
+      mock_app {
+        register Sinatra::REST::Routes
+        get '/', :provides => ["application/xml;level=5"] do
+          request.env['HTTP_ACCEPT']
+        end
+      }
+      get '/', {}, { 'HTTP_ACCEPT' => 'application/xml;level=6' }
+      assert last_response.ok?
+      assert_equal 'application/xml;level=6', last_response.body
+      assert_equal 'application/xml;level=5', last_response.headers['Content-Type']
+    end
+  end
+  
+  context "route option :decode" do
+    setup do
+      PARSING_PROC = Proc.new{|content_type, content| content_type =~ /^application\/.*json$/i ? JSON.parse(content) : throw(:halt, [400, "Cannot parse"])} unless defined? PARSING_PROC
+    end
+    test "should return 400 if the input content is empty" do
+      mock_app {
+        register Sinatra::REST::Routes
+        post '/', :decode => PARSING_PROC do
+          request.env['sinatra.decoded_input'].inspect
+        end
+      }
+      post '/', "", {'CONTENT_TYPE' => "application/json"}
+      assert_equal 400, last_response.status
+      assert_equal 'Input data size must be between 1 and 1073741824 bytes.', last_response.body
+      assert_equal 'text/plain', last_response.headers['Content-Type']
+    end
+    test "should return 400 if the input content is too large" do
+      mock_app {
+        register Sinatra::REST::Routes
+        post '/', :decode => [PARSING_PROC, 2...30] do
+          request.env['sinatra.decoded_input'].inspect
+        end
+      }
+      post '/', '{"key1": ["value1", "value2"]}', {'CONTENT_TYPE' => "application/json"}
+      assert_equal 400, last_response.status
+      assert_equal 'Input data size must be between 2 and 30 bytes.', last_response.body
+      assert_equal 'text/plain', last_response.headers['Content-Type']
+    end
+    test "should return 400 if the input content can be parsed but is malformed" do
+      mock_app {
+        register Sinatra::REST::Routes
+        post '/', :decode => [PARSING_PROC, 2..30] do
+          request.env['sinatra.decoded_input'].inspect
+        end
+      }
+      post '/', '{"key1": ["value1", "value2"]', {'CONTENT_TYPE' => "application/json"}
+      assert_equal 400, last_response.status
+      assert_equal "JSON::ParserError: 618: unexpected token at '{\"key1\": [\"value1\", \"value2\"]'", last_response.body
+      assert_equal 'text/plain', last_response.headers['Content-Type']
+    end
+    test "should allow the parsing proc to throw an exception if needed (e.g. no parser can be found for the requested content type)" do
+      mock_app {
+        register Sinatra::REST::Routes
+        post '/', :decode => [PARSING_PROC, 2..30] do
+          request.env['sinatra.decoded_input'].inspect
+        end
+      }
+      post '/', '<item></item>', {'CONTENT_TYPE' => "application/xml"}
+      assert_equal 400, last_response.status
+      assert_equal "Cannot parse", last_response.body
+      assert_equal 'text/html', last_response.headers['Content-Type']
+    end
+    test "should correctly parse the input content if a parser can be found for the specified content type, and the decoded input must be made available in env['sinatra.decoded_input']" do
+      input = {"key1" => ["value1", "value2"]}
+      mock_app {
+        register Sinatra::REST::Routes
+        post '/', :decode => [PARSING_PROC, 2...30] do
+          content_type 'application/json'
+          JSON.dump request.env['sinatra.decoded_input']
+        end
+      }
+      post '/', JSON.dump(input), {'CONTENT_TYPE' => "application/json"}
+      assert_equal 200, last_response.status
+      assert_equal JSON.dump(input), last_response.body
+      assert_equal 'application/json', last_response.headers['Content-Type']
+    end
+    test "should set the decoded input to the params hash already decoded by Sinatra, if the request's content type is application/x-www-form-urlencoded" do
+      input = {"key1" => ["value1", "value2"]}
+      mock_app {
+        register Sinatra::REST::Routes
+        post '/', :decode => [PARSING_PROC, 2...30] do
+          content_type 'application/json'
+          JSON.dump request.env['sinatra.decoded_input']
+        end
+      }
+      post '/', input
+      assert_equal 200, last_response.status
+      assert_equal JSON.dump(input), last_response.body
+      assert_equal 'application/json', last_response.headers['Content-Type']
+    end
+    test "should return 400 if the parsing proc raises a StandardError" do
+      mock_app {
+        register Sinatra::REST::Routes
+        post '/', :decode => Proc.new{|content_type, content| raise(StandardError, "error message") } do
+          request.env['sinatra.decoded_input'].inspect
+        end
+      }
+      post '/', 'whatever content', {'CONTENT_TYPE' => "whatever type"}
+      assert_equal 400, last_response.status
+      assert_equal "StandardError: error message", last_response.body
+      assert_equal 'text/plain', last_response.headers['Content-Type']
+    end
+    test "should raise an error if the first argument is not a proc" do
+     assert_raise(ArgumentError){ mock_app {
+        register Sinatra::REST::Routes
+        disable :raise_errors, :show_exceptions
+        post '/', :decode => :whatever do
+          JSON.dump request.env['sinatra.decoded_input']
+        end
+      } }
+    end
+  end
+  
+  context "route option :allow" do
+    test "should return 403 if the proc returns false" do
+      mock_app {
+        register Sinatra::REST::Routes
+        helpers do
+          def credentials; ["nobody"]; end
+        end
+        get '/', :allow => lambda{|credentials| credentials.first == "crohr" } do
+          "allowed"
+        end
+      }
+      get '/'
+      assert_equal 403, last_response.status
+      assert_equal "You cannot access this resource", last_response.body
+    end
+    test "should return 200 if the proc returns true" do
+      mock_app {
+        register Sinatra::REST::Routes
+        helpers do
+          def credentials; ["crohr", "1234x"]; end
+        end
+        get '/', :allow => lambda{|credentials| credentials.first == "crohr" && credentials.last == "1234x" } do
+          "allowed"
+        end
+      }
+      get '/'
+      assert_equal 200, last_response.status
+      assert_equal "allowed", last_response.body
+    end
+    test "should raise an error if the argument is not a proc" do
+      assert_raise(ArgumentError) {
+        mock_app {
+          register Sinatra::REST::Routes
+          get '/', :allow => :whatever do
+            "allowed"
+          end
+        }
+      }
+    end
+    test "should raise a NoMethodError if 'credentials' helpers are not defined" do
+      mock_app {
+        register Sinatra::REST::Routes
+        get '/', :allow => lambda{} do
+          "allowed"
+        end
+      }
+      assert_raise(NameError) { get '/' }
+    end
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: sinatra-rest-addons
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Cyril Rohr
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-13 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: contest
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: sinatra
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.9.0
+    version: 
+description: A set of helpers and extensions for sinatra apps that expose REST resources.
+email: cyril.rohr@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/sinatra/rest/helpers.rb
+- lib/sinatra/rest/routes.rb
+- sinatra-rest-addons.gemspec
+- test/helper.rb
+- test/test_routes.rb
+has_rdoc: true
+homepage: http://github.com/crohr/sinatra-rest-addons
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A set of helpers and extensions for sinatra apps that expose REST resources.
+test_files: 
+- test/helper.rb
+- test/test_routes.rb