sinatra-rabbit 1.0.5 → 1.0.6

data/README.md

@@ -5,12 +5,15 @@ Sinatra::Rabbit
 
 Sinatra::Rabbit is a [Sinatra](http://www.sinatrarb.com) extensions that
 makes designing a [REST API](http://en.wikipedia.org/wiki/Representational_State_Transfer)
-much easier.
+much easier and more fun.
 
-Rabbit treats REST resource as 'collection'. Every collection then
-could have multiple operations. This simple DSL is then transformed into
-a proper modular [Sinatra::Base](http://www.sinatrarb.com/intro#Serving%20a%20Modular%20Application) 
-application that can be launched within any [Rack](http://rack.rubyforge.org/) container (including Rails).
+Rabbit maps REST resources to 'collections'. Every collection then could define
+CRUD and other operations to manipulate with resource. Rabbit will handle
+parameter validation and capability checks for you, so you can focus on the
+structure and design of your REST API.
+
+Once your REST API is designed, Rabbit will make it available as modular Sinatra
+application thus mountable to any Rack compatible container (Rails, Padrino...)
 
 Original Rabbit idea has been taken from the [Deltacloud API](http://deltacloud.org)
 project. However this is an complete rewrite of the original Deltacloud Rabbit.
@@ -25,54 +28,59 @@ An example application (modular Deltacloud API) can be found here:
 Features
 -------
 
-* Automatically generate proper path and use right HTTP method for all CRUD operations:
+* Automatically generate proper path and use the right HTTP method for all CRUD operations:
   * `operation :create` is being mapped as 'POST /:collection'
   * `operation :index` is being mapped as 'GET /:collection'
   * `operation :show` is being mapped as 'GET /:collection/:id'
-  * `operation :update` is being mapped as 'PUT /:collection/:id'
+  * `operation :update` is being mapped as 'PATCH /:collection/:id'
   * `operation :destroy` is being mapped as 'DELETE /:collection/:id'
-* Use of Sinatra route conditions
+  * `action :reboot` is being mapped as 'POST /:collection/:id/reboot'
+* Automatically set the :id parameter for routes like :show or :destroy
+* Automatically validates the request parameter values
+* Allow to change the HTTP method (`action :reboot, :http_method => :post`)
+* Allow to check if operation is supported by the current resource
 <pre>
   <code>
-    operation :stop, :if => driver.support_stop_operation? do
-     description "Stop virtual machine"
-     param :id, :string, :required, "Virtual Machine ID"
-     control do
-      # ...
-     end
+    check_capability :for => lambda { |m| driver.respond_to? m }
+
+    collection :vms do
+      action :stop, :with_capability => :stop do
+        control do
+          # ...
+        end
+      end
     end
   </code>
 </pre>
-* Support operation specific features
-* Support REST subcollections
+* Allow to define groups of parameters as features and make them available if
+  the current resource support them
+* Support the 'sub-collections' that might be defined on resouce
 <pre>
   <code>
     collection :buckets do
       collection :blobs, :with_id => :bucket_id do
-        description "Blobs are binary objects stored in buckets"
-        
+
         # GET /buckets/:bucket_id/blobs/:id
         operation :show do
-          description "Show content of blob"
-          param :id, :string, :required
           control { #... }
         end
       end
 
       # GET /buckets/:id
       operation :show do
-        description "Show content of bucket"
-        param :id, :string, :required
         control { #... }
       end
     end
   </code>
 </pre>
-* Generate HEAD routes for all operations and collections
+* Generate HEAD routes for all operations and collections to check if the route
+  is available
 * Generate OPTIONS routes for all operations and collections
   * `OPTIONS /:collection` will return list of all operations (using 'Allow' header)
   * `OPTIONS /:collection/:operation` will return list of parameters defined for given operation (using 'Allow' header)
-* Include bunch of tests to prove it work correctly
+* Allow to manipulate with the REST structure programmatically, to generate
+  documentation or collect statistics
+* Include bunch of tests to prove it all works correctly
 
 Configuration
 -------

data/Rakefile

@@ -0,0 +1,44 @@
+require 'rake/testtask'
+
+namespace :test do
+
+  desc 'Run all tests suites'
+  task :all do
+    Rake::Task['test:app'].invoke
+    Rake::Task['test:dsl'].invoke
+    Rake::Task['test:docs'].invoke
+    Rake::Task['test:param'].invoke
+  end
+
+  Rake::TestTask.new(:app) do |t|
+    t.test_files = FileList['tests/app_test.rb']
+    t.verbose = false
+    t.options = "-v"
+  end
+
+  Rake::TestTask.new(:dsl) do |t|
+    t.test_files = FileList['tests/dsl_test.rb']
+    t.verbose = false
+    #t.options = "-v"
+  end
+
+  Rake::TestTask.new(:docs) do |t|
+    t.test_files = FileList['tests/docs_test.rb']
+    t.verbose = false
+  end
+
+end
+
+desc "Run RSpec with code coverage"
+task :coverage do
+  ENV["COVERAGE"] = "true"
+  Rake::Task["test:all"].execute
+end
+
+desc "Reinstall gem"
+task :reinstall do
+  puts %x{rm -rf sinatra-rabbit-*.gem}
+  puts %x{gem uninstall sinatra-rabbit --all -I -x}
+  puts %x{gem build sinatra-rabbit.gemspec}
+  puts %x{gem install sinatra-rabbit-*.gem --local}
+end

data/lib/sinatra/docs/api.haml

@@ -0,0 +1,8 @@
+%html
+  %head
+  %body
+    %h1=self.class.name
+    %ul
+      - self.class.collections.each do |c|
+        %li
+          %a{:href => c.docs_url }=c.name

data/lib/sinatra/docs/collection.haml

@@ -0,0 +1,24 @@
+%html
+  %head
+  %body
+    %h1=@collection.name.gsub('Sinatra::Rabbit::', '')
+    %blockquote=@collection.description
+    .url=@collection.full_path
+    .features
+      - @collection.features.each do |f|
+        %p.feature=f.name
+    %table.operations
+      %thead
+        %tr
+          %th Name
+          %th Type
+          %th Valid values
+          %th Description
+      %tbody
+        - @collection.operations.each do |o|
+          %tr
+            %td.name
+              %a{:href => o.docs_url }
+            %td.method=o.http_method.to_s.upcase
+            %td.url
+              %a{:href=>o.full_path}=o.full_path

data/lib/sinatra/docs/operation.haml

@@ -0,0 +1,26 @@
+%html
+  %head
+  %body
+    %h1=@operation.name.gsub('Sinatra::Rabbit::', '')
+    %blockquote=@operation.description
+    .url=@operation.full_path
+    - if @operation.required_capability
+      %p{:class => :requires}=@operation.required_capability
+    - @operation.features.each do |f|
+      .feature
+        .name=f.name
+        %blockquote=f.description
+    %table.parameters
+      %thead
+        %tr
+          %th Name
+          %th Type
+          %th Valid values
+          %th Description
+      %tbody
+        - (@operation.params + @operation.features_params).each do |p|
+          %tr
+            %td{ :class => p.required? && 'required'}=p.name
+            %td=p.klass
+            %td=p.values
+            %td=p.description

data/lib/sinatra/rabbit/base.rb

@@ -14,14 +14,6 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
-unless Kernel.respond_to?(:require_relative)
-  module Kernel
-    def require_relative(path)
-      require File.join(File.dirname(caller[0]), path.to_str)
-    end
-  end
-end
-
 require_relative './dsl'
 require_relative './param'
 require_relative './base_collection'
@@ -98,7 +90,10 @@ module Sinatra
     #
     def self.included(base)
       configuration[:root_path] = '/'
-      base.register(DSL)
+      base.register(DSL) if base.respond_to? :register
+      base.get '/docs' do
+        haml File.read(File.join(File.dirname(__FILE__), '..', 'docs', 'api.haml'))
+      end
     end
 
     class Collection < BaseCollection
@@ -107,31 +102,57 @@ module Sinatra
 
       def self.generate(name, parent_collection=nil, &block)
         @collection_name = name.to_sym
-        @collections ||= []
         @parent_collection = parent_collection
         class_eval(&block)
-        send(:head, full_path, {}) { status 200 } unless Rabbit.disabled? :head_routes
-        send(:options, full_path, {}) do
-          [200, { 'Allow' => operations.map { |o| o.operation_name }.join(',') }, '']
-        end unless Rabbit.disabled? :options_routes
+        generate_head_route unless Rabbit.disabled? :head_routes
+        generate_option_route unless Rabbit.disabled? :options_routes
+        generate_docs_route unless Rabbit.disabled? :docs
         self
       end
 
+      def self.generate_option_route
+        base_class.options '/docs' + full_path do
+          header 'Allow' => operations.map { |o| o.operation_name }.join(',')
+          status 200
+        end
+      end
+
+      def self.generate_head_route
+        base_class.head full_path do
+          status 200
+        end
+      end
+
+      def self.docs_url
+        (root_path || '/') + 'docs/' + route_for(path)
+      end
+
+      def self.generate_docs_route
+        collection = self
+        base_class.get docs_url do
+          @collection = collection
+          haml File.read(File.join(File.dirname(__FILE__), '..', 'docs', 'collection.haml'))
+        end
+      end
+
+      # Define new collection using the name
+      #
+      # opts[:with_id]  Define :id used if the collection is a subcollection
+      #
       def self.collection(name, opts={}, &block)
-        unless block_given?
-          return @collections.find { |c| c.collection_name == name }
+        return collections.find { |c| c.collection_name == name } if not block_given?
+        new_collection = BaseCollection.collection_class(name, self) do |c|
+          c.base_class = self.base_class
+          c.with_id!(opts.delete(:with_id)) if opts.has_key?(:with_id)
+          c.no_member! if opts.has_key?(:no_member)
+          c.generate(name, self, &block)
         end
-        current_collection = BaseCollection.collection_class(name, self)
-        current_collection.set_base_class(self.base_class)
-        current_collection.with_id!(opts.delete(:with_id)) if opts.has_key? :with_id
-        current_collection.no_member! if opts.has_key? :no_member
-        current_collection.generate(name, self, &block)
-        @collections << current_collection
+        collections << new_collection
       end
 
       def self.parent_routes
         return '' if @parent_collection.nil?
-        route = ["#{@parent_collection.collection_name}"]
+        route = [ @parent_collection.collection_name.to_s ]
         current_parent = @parent_collection
         while current_parent = current_parent.parent_collection
           route << current_parent.collection_name
@@ -139,7 +160,7 @@ module Sinatra
         route.reverse.join('/')+'/'
       end
 
-      def self.set_base_class(klass)
+      def self.base_class=(klass)
         @klass = klass
       end
 
@@ -169,26 +190,37 @@ module Sinatra
         parent_routes + with_id_param + ((@no_member) ? '' :  collection_name.to_s)
       end
 
-      def self.base_class;@klass;end
-      def self.full_path;root_path + route_for(path);end
+      def self.base_class
+        @klass
+      end
+
       def self.collection_name; @collection_name; end
       def self.parent_collection; @parent_collection; end
-      def self.collections; @collections; end
+
+      def self.subcollection?
+        !parent_collection.nil?
+      end
+
+      def self.collections
+        @collections ||= []
+      end
+
+      def self.full_path
+        (root_path || '') + route_for(path)
+      end
 
       def self.description(text=nil)
         return @description if text.nil?
         @description = text
       end
 
-      def self.documentation
-        Rabbit::Documentation.for_collection(self, operations)
+      def self.[](obj_id)
+        collections.find { |c| c.collection_name == obj_id } || operation(obj_id)
       end
 
-
       def self.operation(operation_name, opts={}, &block)
-        @operations ||= []
         # Return operation when no block is given
-        return @operations.find { |o| o.operation_name == operation_name } unless block_given?
+        return operations.find { |o| o.operation_name == operation_name } unless block_given?
 
         # Check if current operation is not already registred
         if operation_registred?(operation_name)
@@ -196,13 +228,8 @@ module Sinatra
         end
 
         # Create operation class
-        operation = operation_class(self, operation_name).generate(self, operation_name, opts, &block)
-        @operations << operation
-
-        # Generate HEAD routes
-        unless Rabbit.disabled? :head_routes
-          send(:head, root_path + route_for(path, operation_name, {})) { status 200 }
-        end
+        new_operation = operation_class(self, operation_name).generate(self, operation_name, opts, &block)
+        operations << new_operation
 
         # Add route conditions if defined
         if opts.has_key? :if
@@ -215,24 +242,21 @@ module Sinatra
         end
 
         # Make the full_path method on operation return currect operation path
-        operation.set_route(root_path + route_for(path, operation_name, :id_name => @with_id || ':id'))
+        new_operation.route = root_path + route_for(path, operation_name, :id_name => @with_id || ':id')
 
         # Change the HTTP method to POST automatically for 'action' operations
-        if opts[:http_method]
-          operation.http_method(opts.delete(:http_method))
-        end
+        new_operation.http_method = opts.delete(:http_method) if opts[:http_method]
 
-        # Define Sinatra::Base route
+        # Remove :with_capability from Sinatra route options
         route_options = opts.clone
         route_options.delete :with_capability
-        base_class.send(operation.http_method || http_method_for(operation_name), operation.full_path, route_options, &operation.control)
 
-        # Generate OPTIONS routes
-        unless Rabbit.disabled? :options_routes
-          send(:options, root_path + route_for(path, operation_name, :member), {}) do
-            [200, { 'Allow' => operation.params.map { |p| p.to_s }.join(',') }, '']
-          end
-        end
+        # Define Sinatra route and generate OPTIONS route if enabled
+        base_class.send(new_operation.http_method || http_method_for(operation_name), new_operation.full_path, route_options, &new_operation.control)
+
+        new_operation.generate_option_route(root_path + route_for(path, operation_name, :no_id_and_member)) unless Rabbit.disabled?(:options_routes)
+        new_operation.generate_head_route(root_path + route_for(path, operation_name, :member)) unless Rabbit.disabled?(:head_routes)
+        new_operation.generate_docs_route(new_operation.docs_url) unless Rabbit.disabled?(:doc_routes)
         self
       end
 
@@ -241,23 +265,71 @@ module Sinatra
         operation(action_name, opts, &block)
       end
 
-      def self.operations; @operations; end
+      def self.operations
+        @operations ||= []
+      end
+
+      def self.features_for(operation_name)
+        features.select { |f| f.operations.map { |o| o.name}.include?(operation_name) }
+      end
 
-      class Operation
+      class Operation < BaseCollection
 
-        def self.set_route(path)
+        def self.docs_url
+          @collection.root_path + ['docs', @collection.collection_name, operation_name].join('/')
+        end
+
+        def self.route=(path)
           @operation_path = path
         end
 
-        def self.http_method(method=nil)
-          @method ||= method || BaseCollection.http_method_for(@name)
+        def self.http_method
+          @method ||= BaseCollection.http_method_for(@name)
+        end
+
+        def self.http_method=(method)
+          @method = method
+        end
+
+        def self.generate_head_route(path)
+          @collection.base_class.head path do
+            status 200
+          end
+        end
+
+        def self.generate_docs_route(path)
+          operation = self
+          @collection.base_class.get path do
+            @operation = operation
+            haml File.read(File.join(File.dirname(__FILE__), '..', 'docs', 'operation.haml'))
+          end
+        end
+
+        def self.generate_option_route(path)
+          operation_params = params.map { |p| p.to_s }.join(',')
+          @collection.base_class.options path do
+            headers 'Allow' => operation_params
+            status 200
+          end
+        end
+
+        def self.features
+          @collection.features_for(operation_name)
+        end
+
+        def self.features_params
+          features.map { |f| f.operations.map { |o| o.params_array } }.flatten
         end
 
         def self.generate(collection, name, opts={}, &block)
           @name, @params, @collection = name, [], collection
           @options = opts
-          http_method(@options.delete(:http_method)) if @options.has_key? :http_method
-          @collection.features.select { |f| f.operations.map { |o| o.name}.include?(@name) }.each do |feature|
+
+          if @options.has_key?(:http_method)
+            @method = @options.delete(:http_method)
+          end
+
+          features.each do |feature|
             if Sinatra::Rabbit.configuration[:check_features]
               next unless Sinatra::Rabbit.configuration[:check_features].call(collection.collection_name, feature.name)
             end
@@ -265,6 +337,7 @@ module Sinatra
               instance_eval(&o.params)
             end
           end
+
           if Sinatra::Rabbit::STANDARD_OPERATIONS.has_key? name
             required_params = Sinatra::Rabbit::STANDARD_OPERATIONS[name][:required_params]
             required_params.each do |p|
@@ -279,24 +352,27 @@ module Sinatra
         def self.full_path; @operation_path; end
         def self.operation_name; @name; end
 
+        def self.required_capability
+          @options[:with_capability]
+        end
+
         def self.has_capability?
           @capability ||= Sinatra::Rabbit.configuration[:check_capability]
-          if @capability and @options.has_key?(:with_capability)
-            @capability.call(@options[:with_capability])
+          if @capability and required_capability
+            @capability.call(required_capability)
           else
             true
           end
         end
 
         def self.description(text=nil)
-          return @description if text.nil?
-          @description = text
+          @description ||= text
         end
 
         def self.control(&block)
           params_def = @params
           if not has_capability?
-            @control = Proc.new { [412, {}, "The required capability to execute this operation is missing"] }
+            @control = Proc.new { [412, { 'Expect' => @options[:with_capability]}, "The required capability to execute this operation is missing"] }
           else
             @control ||= Proc.new do
               begin
@@ -324,7 +400,7 @@ module Sinatra
       private
 
       def self.operation_registred?(name)
-        @operations.any? { |o| o.name == name }
+        operations.any? { |o| o.name == name }
       end
 
       # Create an unique class name for all operations within Collection class

data/lib/sinatra/rabbit/base_collection.rb

@@ -22,19 +22,21 @@ module Sinatra
       enable :method_overide
 
       def self.route_for(collection, operation_name=nil, member=:member)
-        if operation_name
+        unless operation_name.nil?
           o = Sinatra::Rabbit::STANDARD_OPERATIONS[operation_name]
           if o
+            o = o.clone
             o[:member] = false if member == :no_member
             o[:collection] = true if member == :no_id
-            if member == :no_id_and_member
+            if member == :no_id_and_member or member == :docs
               o[:collection] = true
               o[:member] = true
             end
           end
           operation_path = (o && o[:member]) ? operation_name.to_s : nil
           operation_path = operation_name.to_s unless o
-          id_param = (o && o[:collection]) ? nil : (member.kind_of?(Hash) ? member[:id_name] : ':id')
+          id_param = (o && o[:collection]) ? nil : (member.kind_of?(Hash) ? member[:id_name] : ":id")
+          id_param.gsub!(':', '') if id_param and member  == :docs
           [route_for(collection), id_param, operation_path].compact.join('/')
         else
           collection.to_s
@@ -49,10 +51,11 @@ module Sinatra
       def self.collection_class(name, parent_class=nil)
         klass = parent_class || Sinatra::Rabbit
         begin
-          klass.const_get(name.to_s.camelize + 'Collection')
+          yield k = klass.const_get(name.to_s.camelize + 'Collection')
         rescue NameError
-          klass.const_set(name.to_s.camelize + 'Collection', Class.new(Collection))
+          yield k = klass.const_set(name.to_s.camelize + 'Collection', Class.new(Collection))
         end
+        return k
       end
 
       def self.root_path

data/lib/sinatra/rabbit/dsl.rb

@@ -30,20 +30,20 @@ module Sinatra
       #       end
       #     end
       def collection(name, &block)
-        return @collections.find { |c| c.collection_name == name } unless block_given?
-        @collections ||= []
-        current_collection = BaseCollection.collection_class(name)
-        current_collection.set_base_class(self)
-        current_collection.generate(name, &block)
-        @collections << current_collection
-        Sinatra::Rabbit::DSL.register_collection(current_collection)
+        return self[name] unless block_given?
+        current_collection = BaseCollection.collection_class(name) do |c|
+          c.base_class = self
+          c.generate(name, &block)
+        end
+        collections << current_collection
+        DSL << current_collection
         use current_collection
       end
 
       # Return all defined collections
       #
       def collections
-        @collections
+        @collections ||= []
       end
 
       def self.register_collection(c, &block)
@@ -51,6 +51,14 @@ module Sinatra
         @collections << c
       end
 
+      def self.<<(c)
+        register_collection(c)
+      end
+
+      def [](collection)
+        collections.find { |c| c.collection_name == collection }
+      end
+
     end
   end
 end

data/lib/sinatra/rabbit.rb

@@ -22,11 +22,18 @@ unless "".respond_to? :camelize
   end
 end
 
+unless Kernel.respond_to?(:require_relative)
+  module Kernel
+    def require_relative(path)
+      require File.join(File.dirname(caller[0]), path.to_str)
+    end
+  end
+end
+
 class << Sinatra::Base
   def options(path, opts={}, &bk)
     route 'OPTIONS', path, opts, &bk
   end
 end
 
-$:.unshift File.join(File::dirname(__FILE__), '.')
-require 'rabbit/base'
+require_relative './rabbit/base'

data/sinatra-rabbit.gemspec

@@ -29,12 +29,15 @@ Gem::Specification.new do |s|
     a simple REST API using easy to undestand DSL.
   EOF
 
-  s.version = '1.0.5'
+  s.version = '1.0.6'
   s.date = Time.now
   s.summary = %q{Sinatra REST API DSL}
   s.files = FileList[
     'lib/sinatra/*.rb',
     'lib/sinatra/rabbit/*.rb',
+    'lib/sinatra/docs/*.haml',
+    'tests/*.rb',
+    'Rakefile',
     'LICENSE',
     'README.md',
     'sinatra-rabbit.gemspec',