sinatra-rabbit 0.9 → 0.9.1

data/README.md

@@ -5,7 +5,7 @@ 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.
 
-Rabbit threat REST resource as 'collection'. Every collection then
+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).
@@ -15,6 +15,129 @@ project. However this is an complete rewrite of the original Deltacloud Rabbit.
 The goal is to make Rabbit highly modular, so it can be used in other projects
 as well as in Deltacloud.
 
+Full documentation: [rubydoc.info/github/mifo/sinatra-rabbit](http://rubydoc.info/github/mifo/sinatra-rabbit/master)
+
+Features
+-------
+
+* Automatically generate proper path and use 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 :destroy` is being mapped as 'DELETE /:collection/:id'
+* Use of Sinatra route conditions
+<pre>
+  <code>
+    operation :stop, :if => driver.support_stop_operation? do
+     description "Stop virtual machine"
+     param :id, :string, :required, "Virtual Machine ID"
+     control do
+      # ...
+     end
+    end
+  </code>
+</pre>
+* Support operation specific features
+* Support REST subcollections
+<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 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
+
+Configuration
+-------
+
+Rabbit behavior can be customized using `configure` method:
+
+    Sinatra::Rabbit.configure do
+      disable :head_routes      # This will disable automatic generation of HEAD routes
+      disable :options_routes   # This will disable automatic generation of OPTIONS routes
+      disable :documentation    # This will disable automatic generation of documentation routes
+    end
+
+Operation specific 'features'
+--------
+
+In some specific use-cases, you would like to have different set of parameters
+for operation, based on some condition of your system.
+To give you and example, in Deltacloud API project, we have support for
+different drivers. The project aims to give user full cross-cloud abstraction
+layer, however for some cloud providers the full abstraction is not possible and
+in this case we need to handle this using 'features'. It mean that some
+particular operations can have 'feature' assigned. If this 'feature' is
+supported by underlaying driver, then we add new parameters to that operations.
+
+In sinatra-rabbit, you can define features for every model in this way:
+
+    class Sample < Sinatra::Base
+      include Sinatra::Rabbit
+      include Sinatra::Rabbit::Features
+
+      features do
+        feature :user_name, :for => :instances do
+          operation :create do
+            param :user_name, :string, :optional, "Allow to define user-defined name"
+          end
+        end
+      end
+    end
+
+You can also wrap features into 'if' block or put some conditions on top
+of this block to make it more flexible.
+
+Tests
+------
+
+Project include set of minitest files located under 'tests/' directory. You can
+launch them by typing:
+
+    $ rake test:all
+
+If you want to run just DSL tests:
+
+    $ rake test:dsl
+
+If you want to test if Sinatra::Base works on your system correctly with Rabbit:
+
+    $ rake test:app
+
+If you want to see code coverage, you must install the *simplecov* gem:
+
+    $ gem install simplecov
+    $ rake coverage
+
+NOTE: The coverage reports are supported only on Ruby 1.9
+
+TODO
+-------
+
+* Add documentation generation and routes for Rabbit based applications
+
 Installation
 -------
 
@@ -32,7 +155,18 @@ Usage
       collection :images do
         description "Images description"
 
-        operation :index do
+        collection :subcollection do
+          description "Images subcollection"
+
+          operation :index do
+            description "Hello world"
+            control do
+              status 200
+            end
+          end
+        end
+
+        operation :index, :if => lambda { 1 == 1} do
           description "Index operation description"
           control do
             status 200
@@ -50,6 +184,7 @@ Usage
             "Hey #{params[:id]}"
           end
         end
+      end
     end
 
     MySinatraApp.run!

data/lib/sinatra/rabbit.rb

@@ -22,5 +22,11 @@ unless "".respond_to? :camelize
   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'

data/lib/sinatra/rabbit/base.rb

@@ -14,25 +14,74 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
-require 'sinatra/rabbit/dsl'
-require 'sinatra/rabbit/param'
-require 'sinatra/rabbit/base_collection'
-require 'sinatra/rabbit/validator'
+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'
+require_relative './validator'
+require_relative './features'
 
 module Sinatra
   module Rabbit
 
     STANDARD_OPERATIONS = {
-      :create => { :member => false, :method => :post, :collection => true },
-      :show => { :member => false, :method => :get },
-      :destroy => { :member => false, :method => :delete },
-      :index => { :member => false, :method => :get, :collection => true }
+      :create => {
+        :member => false,
+        :method => :post,
+        :collection => true
+      },
+      :show => {
+        :member => false,
+        :method => :get,
+        :required_params => [ :id ]
+      },
+      :destroy => {
+        :member => false,
+        :method => :delete,
+        :required_params => [ :id ]
+      },
+      :index => {
+        :member => false,
+        :method => :get,
+        :collection => true
+      }
     }
 
     def self.configure(&block)
       instance_eval(&block)
     end
 
+    def self.configuration
+      @configuration || {}
+    end
+
+    def self.enable(property)
+      @configuration[property] = true
+    end
+
+    def self.enabled?(property)
+      !@configuration[property].nil? and @configuration[property] == true
+    end
+
+    def self.disabled?(property)
+      !@configuration[property].nil? and @configuration[property] == false
+    end
+
+    def self.disable(property)
+      @configuration[property] = false
+    end
+
+    def self.set(property, value)
+      @configuration[property] = value
+    end
+
     # Automatically register the DSL to Sinatra::Base if this
     # module is included:
     #
@@ -43,30 +92,126 @@ module Sinatra
     #     end
     #
     def self.included(base)
+      @configuration ||= {
+        :root_path => '/'
+      }
       base.register(DSL)
     end
 
     class Collection < BaseCollection
 
-      def self.generate(name, &block)
-        @name = name.to_sym
+      include DSL
+
+      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
         self
       end
 
-      def self.path; @name; end
+      def self.collection(name, opts={}, &block)
+        unless block_given?
+          return @collections.find { |c| c.collection_name == name }
+        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.generate(name, self, &block)
+        @collections << current_collection
+      end
+
+      def self.parent_routes
+        return '' if @parent_collection.nil?
+        route = ["#{@parent_collection.collection_name}"]
+        current_parent = @parent_collection
+        while current_parent = current_parent.parent_collection
+          route << current_parent.collection_name
+        end
+        route.reverse.join('/')+'/'
+      end
+
+      def self.set_base_class(klass)
+        @klass = klass
+      end
+
+      def self.control(*args)
+        raise "The 'control' statement must be used only within context of Operation"
+      end
+
+      def self.features
+        return [] unless base_class.respond_to? :features
+        base_class.features.select { |f| f.collection == collection_name }
+      end
+
+      def self.with_id!(id)
+        @with_id = ":#{id}"
+      end
+
+      def self.path
+        with_id_param = @with_id.nil? ? '' : ':id/' 
+        parent_routes + with_id_param + collection_name.to_s
+      end
 
-      def self.description(text)
+      def self.base_class;@klass;end
+      def self.full_path;root_path + route_for(path);end
+      def self.collection_name; @collection_name; end
+      def self.parent_collection; @parent_collection; end
+      def self.collections; @collections; end
+
+      def self.description(text=nil)
+        return @description if text.nil?
         @description = text
       end
 
-      def self.operation(operation_name, &block)
+      def self.documentation
+        Rabbit::Documentation.for_collection(self, operations)
+      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?
+
+        # Check if current operation is not already registred
         if operation_registred?(operation_name)
-          raise "Operation #{operation_name} already register in #{self.name} collection"
+          raise "Operation #{operation_name} already registered in #{self.name} collection"
+        end
+
+        # Create operation class
+        @operations << (operation = operation_class(self, operation_name).generate(self, operation_name, &block))
+
+        # Generate HEAD routes
+        unless Rabbit.disabled? :head_routes
+          send(:head, root_path + route_for(path, operation_name, {})) { status 200 }
+        end
+
+        # Add route conditions if defined
+        if opts.has_key? :if
+          base_class.send(:set, :if_true) do |value|
+            condition do
+              (value.kind_of?(Proc) ? value.call : value) == true
+            end
+          end
+          opts[:if_true] = opts.delete(:if)
+        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'))
+
+        # Define Sinatra::Base route
+        base_class.send(http_method_for(operation_name), operation.full_path, opts, &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
-        operation = operation_class(self, operation_name).generate(self, operation_name, &block)
-        send(http_method_for(operation_name), route_for(path, operation_name), {}, &operation.control)
         self
       end
 
@@ -74,13 +219,33 @@ module Sinatra
 
       class Operation
 
+        def self.set_route(path)
+          @operation_path = path
+        end
+
         def self.generate(collection, name, &block)
-          @name, @params = name, []
+          @name, @params, @collection = name, [], collection
+          @collection.features.select { |f| f.operations.map { |o| o.name}.include?(@name) }.each do |feature|
+            feature.operations.each do |o|
+              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|
+              param p, :required, :string, "The #{p} parameter"
+            end unless required_params.nil?
+          end
           class_eval(&block)
+          description "#{name.to_s.capitalize} operation on #{@collection.name} collection" if description.nil?
           self
         end
 
-        def self.description(text)
+        def self.full_path; @operation_path; end
+        def self.operation_name; @name; end
+
+        def self.description(text=nil)
+          return @description if text.nil?
           @description = text
         end
 
@@ -91,8 +256,7 @@ module Sinatra
               Rabbit::Validator.validate!(params, params_def)
             rescue => e
               if e.kind_of? Rabbit::Validator::ValidationError
-                status e.http_status_code
-                halt
+                halt e.http_status_code, e.message
               else
                 raise e
               end
@@ -102,8 +266,11 @@ module Sinatra
         end
 
         def self.param(*args)
+          return @params.find { |p| p.name == args[0] } if args.size == 1
           @params << Rabbit::Param.new(*args)
         end
+
+        def self.params; @params; end
       end
 
       private
@@ -114,7 +281,11 @@ module Sinatra
 
       # Create an unique class name for all operations within Collection class
       def self.operation_class(collection_klass, operation_name)
-        collection_klass.const_set(operation_name.to_s.camelize + 'Operation', Class.new(Operation))
+        begin
+          collection_klass.const_get(operation_name.to_s.camelize + 'Operation')
+        rescue NameError
+          collection_klass.const_set(operation_name.to_s.camelize + 'Operation', Class.new(Operation))
+        end
       end
 
     end

data/lib/sinatra/rabbit/base_collection.rb

@@ -18,20 +18,26 @@ module Sinatra
   module Rabbit
 
     class BaseCollection < Sinatra::Base
-      attr_accessor :name, :description
-      attr_accessor :operations
-
       set :views, Proc.new { File.join(File::dirname(__FILE__), "..", "..", "views") }
       enable :method_overide
 
-      def self.route_for(collection, operation_name=nil)
+      def self.route_for(collection, operation_name=nil, member=:member)
         if operation_name
           o = Sinatra::Rabbit::STANDARD_OPERATIONS[operation_name]
+          if o
+            o[:member] = false if member == :no_member
+            o[:collection] = true if member == :no_id
+            if member == :no_id_and_member
+              o[:collection] = true
+              o[:member] = true
+            end
+          end
           operation_path = (o && o[:member]) ? operation_name.to_s : nil
-          id_param = (o && o[:collection]) ? nil : ":id"
+          operation_path = operation_name.to_s unless o
+          id_param = (o && o[:collection]) ? nil : (member.kind_of?(Hash) ? member[:id_name] : ':id')
           [route_for(collection), id_param, operation_path].compact.join('/')
         else
-          "/#{collection}"
+          collection.to_s
         end
       end
 
@@ -40,8 +46,17 @@ module Sinatra
         (o && o[:method]) ? o[:method] : :get
       end
 
-      def self.collection_class(name)
-        Sinatra::Rabbit.const_set(name.to_s.camelize + 'Collection', Class.new(Collection))
+      def self.collection_class(name, parent_class=nil)
+        klass = parent_class || Sinatra::Rabbit
+        begin
+          klass.const_get(name.to_s.camelize + 'Collection')
+        rescue NameError
+          klass.const_set(name.to_s.camelize + 'Collection', Class.new(Collection))
+        end
+      end
+
+      def self.root_path
+        Sinatra::Rabbit.configuration[:root_path]
       end
 
     end

data/lib/sinatra/rabbit/dsl.rb

@@ -30,8 +30,13 @@ module Sinatra
       #       end
       #     end
       def collection(name, &block)
+        return @collections.find { |c| c.collection_name == name } unless block_given?
         @collections ||= []
-        @collections << (current_collection = BaseCollection.collection_class(name).generate(name, &block))
+        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)
         use current_collection
       end
 
@@ -41,6 +46,11 @@ module Sinatra
         @collections
       end
 
+      def self.register_collection(c, &block)
+        @collections ||= []
+        @collections << c
+      end
+
     end
   end
 end

data/lib/sinatra/rabbit/features.rb

@@ -0,0 +1,69 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+module Sinatra
+  module Rabbit
+    class Feature
+      attr_reader :name
+      attr_reader :collection
+      attr_reader :operations
+
+      def initialize(name, opts={}, &block)
+        @name = name
+        @operations = []
+        @collection = opts[:for]
+        raise "Each feature must define collection for which it will be valid using :for parameter" unless @collection
+        instance_eval(&block) if block_given?
+      end
+
+      def operation(name, &block)
+        @operations << Operation.new(name, &block) if block_given?
+        @operations.find { |o| o.name == name }
+      end
+
+      class Operation
+        attr_reader :name
+        attr_reader :params
+
+        def initialize(name, &block)
+          @name = name
+          @params = block
+        end
+
+      end
+    end
+
+    module Features
+
+      def features(&block)
+        @@features ||= []
+        instance_eval(&block) if block_given?
+        @@features
+      end
+
+      def feature(name, opts={}, &block)
+        @@features << Feature.new(name, opts, &block) if block_given?
+        @@features.find { |f| f.name == name }
+      end
+
+      def self.included(base)
+        base.register(Features)
+      end
+
+    end
+
+  end
+end

data/lib/sinatra/rabbit/param.rb

@@ -24,22 +24,24 @@ module Sinatra
         @name, @klass = args.pop, args.pop
         raise "DSL: You need to specify the name and param type (#{@name})" unless @name or @klass
         parse_params!(args)
+        @description ||= "Description not available"
       end
 
       def required?; @required == true; end
       def optional?; !required?; end
       def enum?; !@values.nil?; end
-      def number?; [:integer, :float].include?(@klass); end
+      def number?; [:integer, :float, :number].include?(@klass); end
+      def string?; @klass == :string; end
+
+      def to_s
+        "#{name}:#{klass}:#{required? ? 'required' : 'optional'}"
+      end
 
       private
 
       def parse_params!(args)
-        if args.pop == :required
-          @required = true
-        else
-          @required = false
-        end
         @values = args.pop if args.last.kind_of? Array
+        @required = args.pop == :required if [:required, :optional].include? args.last
         @description = args.pop
       end
 

data/sinatra-rabbit.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |s|
     a simple REST API using easy to undestand DSL.
   EOF
 
-  s.version = '0.9'
+  s.version = '0.9.1'
   s.date = Time.now
   s.summary = %q{Sinatra REST API DSL}
   s.files = FileList[

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-rabbit
 version: !ruby/object:Gem::Version
-  version: '0.9'
+  version: 0.9.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-13 00:00:00.000000000 Z
+date: 2012-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
-  requirement: &70240995322640 !ruby/object:Gem::Requirement
+  requirement: &70283050880100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: 1.3.0
   type: :runtime
   prerelease: false
-  version_requirements: *70240995322640
+  version_requirements: *70283050880100
 description: ! "    Rabbit is a Sinatra extension which can help you writing\n    a
   simple REST API using easy to undestand DSL.\n"
 email: dev@deltacloud.apache.org
@@ -34,6 +34,7 @@ files:
 - lib/sinatra/rabbit/base.rb
 - lib/sinatra/rabbit/base_collection.rb
 - lib/sinatra/rabbit/dsl.rb
+- lib/sinatra/rabbit/features.rb
 - lib/sinatra/rabbit/param.rb
 - lib/sinatra/rabbit/validator.rb
 - LICENSE
@@ -59,7 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: Sinatra REST API DSL