toast 0.6.0 → 0.7.0

data/README.md

@@ -1,32 +1,31 @@
 Summary
 =======
 
-Toast is an extension to Ruby on Rails that lets you expose any
-ActiveRecord model as a resource according to the REST paradigm. The
-representation format is JSON.
+Toast is an extension to Ruby on Rails to build web services with low
+programming effort in a coherent way.  Toast exends ActiveRecord such
+that each model can be declared to be a web resource, exposing defined
+attributes for reading and writing using HTTP.
 
-In contrast to other plugins, gems and Rails' inbuilt REST features
-toast takes a data centric approach: Tell the model to be a resource
-and what attributes and associations are to be exposed. That's it. No
-controller boiler plate code for every model, no routing setup.
+Its main features are:
 
-Toast is a Rails engine that runs one generic controller and a sets up
-the routing according to the definition in the models, which is
-denoted using a block oriented DSL.
+  * declaration of web resources based on ActiveRecord models
+  * generic controller handles all actions
+  * automated routing
+  * exposing data values with JSON maps 
+  * exposing associations by links (URLs)
 
-REST is more than some pretty URIs, the use of the HTTP verbs and
-response codes. It's on the toast user to invent media types that
-control the application's state and introduce semantics. With toast you
-can build REST services or tightly coupled server-client applications,
-which ever suits the task best. That's why TOAST stands for:
+Toast works with Ruby on Rails >= 3.1.0 (currently tested up to 3.2.6)
 
->  **TOast Ain't reST**
+WARNING
+=======
+
+This version is experimental and probably not bullet
+proof. As soon as the gem is loaded a controller with ready routing is
+enabled serving the annotated model's data records.
 
-*Be careful*: This version is experimental and probably not bullet
-proof. As soon as the gem is loaded a controller with ready routing
-is enabled serving the annotated model's data records for reading,
-updating and deleting. There are no measures to prevent XSS and CSFR
-attacks.
+Version 1.0.0 of Toast is planned to be a production-ready implementation,
+which will be finished within 2012. Until then API/DSL changes must
+be expected with each minor update. 
 
 Example
 =======
@@ -40,89 +39,89 @@ Let the table `bananas` have the following schema:
        t.integer  "apple_id"
      end
 
-and let a corresponding model class have a *resourceful_model* annotation:
+and let a corresponding model class have a *acts_as_resource* annotation:
 
      class Banana < ActiveRecord::Base
        belongs_to :apple
        has_many :coconuts
-       scope :find_some, where("number < 100")
+       
+       scope :less_than_100, where("number < 100")
 
-       resourceful_model do
-         # attributes or association names
+       acts_as_resource do
+         # exposed attributes or association names
          readables :coconuts, :apple
-	 writables :name, :number	 
+         writables :name, :number	 
 	 
-         # class methods of Banana returning an Array of Banana records
-         collections :find_some, :all
+         # exposed class methods of Banana returning an Array of Banana records
+         collections :less_than_100, :all
        end
      end
 
-The above definition inside the `resourceful_model` block exposes the
+The above definition inside the `acts_as_resource` block exposes the
 records of the model Banana automatically via a generic controller to
 the outside world, accepting and delivering JSON representations of
 the records. Let the associated models Apple and Coconut be
-exposed as a resource, too.
+exposed as a resource, too:
 
 ### Get a collection
     GET /bananas
-    --> 200,  '[{"uri":"http://www.example.com/bananas/23",
-                 "name": "Fred",
-                 "number": 33,
+    --> 200,  '[{"self":     "http://www.example.com/bananas/23",
+                 "name":     "Fred",
+                 "number":   33,
                  "coconuts": "http://www.example.com/bananas/23/coconuts",
-                 "apple":"http://www.example.com/bananas/23/apple,
-                {"uri":"http://www.example.com/bananas/24",
+                 "apple":    "http://www.example.com/bananas/23/apple,
+                {"self":     "http://www.example.com/bananas/24",
                   ... }, ... ]
 ### Get a customized collection (filtered, paging, etc.)
-
-    GET /bananas/find_some
-    --> 200, '[SOME BANANAS]'
+    GET /bananas/less_than_100
+    --> 200, '[{BANANA}, {BANANA}, ...]'
 
 ### Get a single resource representation:
     GET /bananas/23
-    --> 200,  '{"uri":"http://www.example.com/bananas/23"
-                "name": "Fred",
-                "number": 33,
+    --> 200,  '{"self":     "http://www.example.com/bananas/23"
+                "name":     "Fred",
+                "number":   33,
                 "coconuts": "http://www.example.com/bananas/23/coconuts",
-                "apple": "http://www.example.com/bananas/23/apple" }'
+                "apple":    "http://www.example.com/bananas/23/apple" }'
 
-### Get a associated collection
+### Get an associated collection
     "GET" /bananas/23/coconuts
     --> 200, '[{COCNUT},{COCONUT},...]',
 
 ### Update a single resource:
-    PUT /bananas/23, '{"uri":"http://www.example.com/bananas/23"
-                       "name": "Barney",
+    PUT /bananas/23, '{"self":   "http://www.example.com/bananas/23"
+                       "name":   "Barney",
                        "number": 44}'
-    --> 200,  '{"uri":"http://www.example.com/bananas/23"
-                "name": "Barney",
-                "number": 44,
+    --> 200,  '{"self":     "http://www.example.com/bananas/23"
+                "name":     "Barney",
+                "number":   44,
                 "coconuts": "http://www.example.com/bananas/23/coconuts",
-                "apple": "http://www.example.com/bananas/23/apple"}'
+                "apple":    "http://www.example.com/bananas/23/apple"}'
 
 ### Create a new record
     "POST" /bananas,  '{"name": "Johnny",
                         "number": 888}'
-    --> 201,  {"uri":"http://www.example.com/bananas/102"
-               "name": "Johnny",
-               "number": 888,
+    --> 201,  {"self":     "http://www.example.com/bananas/102"
+               "name":     "Johnny",
+               "number":   888,
                "coconuts": "http://www.example.com/bananas/102/coconuts" ,
-               "apple": "http://www.example.com/bananas/102/apple }
+               "apple":    "http://www.example.com/bananas/102/apple }
 
 ### Create an associated record
     "POST" /bananas/23/coconuts, '{COCONUT}'
-    --> 201,  {"uri":"http://www.example.com/coconuts/432,
+    --> 201,  {"self":"http://www.example.com/coconuts/432,
                ...}
 
 ### Delete records
     DELETE /bananas/23
     --> 200
 
-More details and configuration options are documented in the manual... (_comming soon_)
+More details and configuration options are documented in the manual.
 
 Installation
 ============
 
-With bundler
+With bundler from  (rubygems.org)
 
     gem "toast"
 
@@ -130,29 +129,14 @@ the latest Git:
 
     gem "toast", :git => "https://github.com/robokopp/toast.git"	
 
-Test Suite
-==========
-
-In `test/rails_app` you can find a rails application with tests. To run
-the tests you need to
-
-0. Install the *jeweler* gem:
-
-        gem install jeweler
-
-1. install the toast gem from this git clone:
-
-        rake install
-
-2. initialize the test application
-
-        cd test/rails_app
-        bundle install
-
-3. Now you can run the test suite from within the test application
+Remarks
+=======
 
-        rake
+REST is more than some pretty URIs, the use of the HTTP verbs and
+response codes. It's on the Toast user to invent meaningful media
+types that control the application's state and introduce
+semantics. With toast you can build REST services or tightly coupled
+server-client applications, which ever suits the task best. That's why
+TOAST stands for:
 
-   Or you may call `rake test` from the root directory of the working
-   copy. This will reinstall the toast gem before running tests
-   automatically.
+>  **TOast Ain't reST**

data/app/controller/toast_controller.rb

@@ -25,7 +25,7 @@ class ToastController < ApplicationController
 
     rescue Exception => e
       log_exception e
-      raise e if Rails.env == "test"
+      puts e if Rails.env == "test"
       return head(:internal_server_error)
     end
 

data/config/routes.rb

@@ -14,7 +14,7 @@ Rails.application.routes.draw do
         
       namespaces << tc.namespace
       
-      match("#{tc.namespace}/#{resource_name}(/:id(/:subresource))" => 'toast#catch_all',
+      match("#{tc.namespace}/#{resource_name}(/:id(/:subresource(/:scope)))" => 'toast#catch_all',
             :constraints => { :id => /\d+/ },
             :resource => resource_name,
             :as => resource_name,

data/lib/toast/active_record_extensions.rb

@@ -44,15 +44,28 @@ module Toast
         # Like ActiveRecord::Base.attributes, but result Hash includes
         # only attributes from the list _attr_names_ plus the
         # associations _assoc_names_ as links and the 'self' link
-        def represent attr_names, assoc_names, base_uri
+        def represent attr_names, assoc_names, base_uri, media_type
           props = {}
 
           attr_names.each do |name| 
+            unless self.respond_to?(name) && self.method(name).arity == 0
+              raise "Toast Error: Connot find instance method '#{self.class}##{name}' of arity 0"
+            end
             props[name] = self.send(name)
           end
           
           assoc_names.each do |name| 
             props[name] = "#{base_uri}#{self.uri_path}/#{name}"
+            
+            # collections (scopes) actiing on associacions:    
+            
+            reflect = self.class.reflect_on_association(name.to_sym)            
+            if reflect.collection?
+              reflect.klass.toast_config(media_type).collections.each do |collection_name|
+                next if collection_name == "all"
+                props[name+":"+collection_name] = "#{base_uri}#{self.uri_path}/#{name}/#{collection_name}"
+              end
+            end
           end
           
           props["self"] = base_uri + self.uri_path

data/lib/toast/association.rb

@@ -22,6 +22,11 @@ module Toast
     end
 
     def get
+
+      unless @record.class.reflect_on_all_associations.detect{|a| a.name.to_s == @assoc}
+        raise "Toast Error: Association '#{@assoc}' not found in model '#{@record.class}'"
+      end
+
       result = @record.send(@assoc)
 
       raise ResourceNotFound if result.nil?
@@ -31,7 +36,8 @@ module Toast
           :json => result.map{|r|
             r.represent( @associate_config_out.in_collection.exposed_attributes,
                          @associate_config_out.in_collection.exposed_associations,
-                         @base_uri )
+                         @base_uri,
+                         @associate_config_out.media_type )
           },
           :status => :ok,
           :content_type => @associate_config_out.in_collection.media_type
@@ -40,7 +46,8 @@ module Toast
         {
           :json =>  result.represent( @associate_config_out.exposed_attributes,
                                       @associate_config_out.exposed_associations,
-                                      @base_uri ),
+                                      @base_uri,
+                                      @associate_config_out.media_type),
           :status => :ok,
           :content_type => @associate_config_out.media_type
         }
@@ -81,7 +88,8 @@ module Toast
         {
           :json => record.represent( @associate_config_out.exposed_attributes,
                                      @associate_config_out.exposed_associations,
-                                     @base_uri ),
+                                     @base_uri,
+                                     @associate_config_out.media_type),
           :location => self.base_uri + record.uri_path,
           :status => :created,
           :content_type => @associate_config_out.media_type

data/lib/toast/collection.rb

@@ -3,7 +3,7 @@ module Toast
 
     attr_reader :model
 
-    def initialize model, subresource_name, params, config_in, config_out
+    def initialize model_or_relation, subresource_name, params, config_in, config_out
 
       subresource_name ||= "all"
 
@@ -11,7 +11,11 @@ module Toast
         raise ResourceNotFound
       end
 
-      @model = model
+      @target_model = (model_or_relation.klass rescue false) ? 
+                       model_or_relation.klass :
+                       model_or_relation
+ 
+      @model_or_relation = model_or_relation
       @collection = subresource_name
       @params = params
       @format = params[:format]
@@ -21,24 +25,43 @@ module Toast
 
     def get
 
-      records = if @config_out.pass_params_to.include?(@collection)
-                  @model.send(@collection, @params)
+      unless @model_or_relation.respond_to?(@collection)
+        raise "Toast Error: Cannot find class method '#{@collection}' of model '#{@model_or_relation}', which is configured in 'acts_as_resource > collections'."
+      end
+      
+      # FIXME: This is a lot of hallooballoo to check if the #send
+      #        will be successful, but if it's not checked the error
+      #        message is not helpful to find the error.
+
+      records = if @config_out.pass_params_to.include?(@collection)                                  
+                  if @target_model.method(@collection).arity != 1  
+                    raise "Toast Error: Class method '#{@collection}' of model '#{@target_model}' must accept one parameter, as configured by 'acts_as_resource > pass_params_to'."
+                  end
+                  # fetch results 
+                  @model_or_relation.send(@collection, @params)
+
                 else
-                  @model.send(@collection)
+
+                  if @target_model.method(@collection).arity > 0
+                    raise "Toast Error: Class method '#{@collection}' of model '#{@model_or_relation}' must not accept any parameter, as configured by 'acts_as_resource'"
+                  end
+                  # fetch results
+                  @model_or_relation.send(@collection)
                 end
 
       case @format
       when "html"
         {
-          :template => "resources/#{model.to_s.pluralize.underscore}",
-          :locals => { model.to_s.pluralize.underscore.to_sym => records }
+          :template => "resources/#{@target_model.to_s.pluralize.underscore}",
+          :locals => { @target_model.to_s.pluralize.underscore.to_sym => records }
         }
       when "json"
         {
           :json => records.map{|r|
             r.represent( @config_out.in_collection.exposed_attributes,
                          @config_out.in_collection.exposed_associations,
-                         @base_uri )
+                         self.base_uri,
+                         @config_out.media_type)
           },
           :status => :ok,
           :content_type => @config_out.in_collection.media_type
@@ -78,13 +101,14 @@ module Toast
       end
 
       begin
-        record = @model.create! payload
+        record = @model_or_relation.create! payload
 
         {
           :json => record.represent( @config_out.exposed_attributes,
                                      @config_out.exposed_associations,
-                                     @base_uri ),
-          :location => @base_uri + record.uri_path,
+                                     self.base_uri,
+                                     @config_out.media_type),
+          :location => self.base_uri + record.uri_path,
           :status => :created,
           :content_type => @config_out.media_type
         }

data/lib/toast/engine.rb

@@ -4,6 +4,7 @@ require 'toast/collection'
 require 'toast/association'
 require 'toast/record'
 require 'toast/single'
+require 'toast/scoped_association'
 
 require 'action_dispatch/http/request'
 require 'rack/accept_media_types'

data/lib/toast/record.rb

@@ -41,6 +41,11 @@ module Toast
       
       # set the virtual attributes
       (@config_in.writables - @record.attribute_names -  @config_in.exposed_associations).each do |vattr|
+
+        unless (@record.respond_to?("#{vattr}=") && @record.method("#{vattr}=").arity == 1)
+          raise "Toast Error: Connot find setter '#{@record.class}##{vattr}='"
+        end
+
         @record.send("#{vattr}=", payload.delete(vattr))
       end
       
@@ -49,7 +54,8 @@ module Toast
       {        
         :json => @record.represent( @config_out.exposed_attributes,
                                     @config_out.exposed_associations,
-                                    @base_uri ),
+                                    @base_uri,
+                                    @config_out.media_type ),
         :status => :ok,
         :location => self.base_uri + @record.uri_path,
         :content_type => @config_out.media_type
@@ -67,7 +73,8 @@ module Toast
         {
           :json => @record.represent( @config_out.exposed_attributes,
                                       @config_out.exposed_associations,
-                                      @base_uri ),
+                                      @base_uri,
+                                      @config_out.media_type),
           :status => :ok,
           :content_type => @config_out.media_type
         }

data/lib/toast/resource.rb

@@ -22,11 +22,7 @@ module Toast
       id = params[:id]
       subresource_name = params[:subresource]
       format = params[:format]
-
-      #### Debugging stop
-      # binding.pry if $halt
-      ###
-
+      scope = params[:scope]
       begin
         
         # determine model
@@ -39,7 +35,7 @@ module Toast
         config_in = model.toast_config request.media_type
 
         #  ... or in case of an association request
-        config_assoc_src = model.toast_config request.headers["Assoc-source-type"]
+        config_assoc_src = model.toast_config request.headers["Assoc-source-type"] # ?
         
         # base URI for returned object
         base_uri = request.base_url + request.script_name + 
@@ -53,9 +49,10 @@ module Toast
               elsif subresource_name.nil?
                 Toast::Record.new(model, id, format, config_in, config_out)
               elsif (config_assoc_src && config_assoc_src.exposed_associations.include?(subresource_name))
-                
+
                 # determine associated model
-                assoc_model = get_class_by_resource_name subresource_name
+                assoc_model = 
+                  model.reflect_on_all_associations.detect{|a| a.name.to_s == subresource_name}.klass
                 
                 # determine config for representation of assoc. model                
                 assoc_config_out = assoc_model.toast_config request.accept_media_types.prefered
@@ -65,8 +62,13 @@ module Toast
                 base_uri = request.base_url + request.script_name + 
                   (assoc_config_out.namespace ? "/" + assoc_config_out.namespace : "")
 
-                Toast::Association.new(model, id, subresource_name, format, config_assoc_src, 
-                                       assoc_model, assoc_config_in, assoc_config_out)
+                if scope.nil?
+                  Toast::Association.new(model, id, subresource_name, format, config_assoc_src, 
+                                         assoc_model, assoc_config_in, assoc_config_out)
+                else 
+                  Toast::ScopedAssociation.new(model, id, subresource_name, scope, params.clone,
+                                               assoc_config_in, assoc_config_out)                                               
+                end
               else
                 raise ResourceNotFound
               end
@@ -74,6 +76,8 @@ module Toast
         # set base to be prepended to URIs
         rsc.base_uri = base_uri
 
+        
+
         rsc
       rescue NameError
         raise ResourceNotFound

data/lib/toast/scoped_association.rb

@@ -0,0 +1,23 @@
+module Toast
+  class ScopedAssociation < Resource
+    # delegeates everything to Toast::Collection, where the model is replaced
+    # by the Relation this association creates 
+
+    def initialize(model, id, association_name, scope_name,  params, 
+                   config_in, config_out)
+                   
+      record = model.find(id)
+      assoc_model = record.class
+      
+      @collection = Toast::Collection.new(record.send(association_name), 
+                                          scope_name,
+                                          params,
+                                          config_in,
+                                          config_out)
+
+    end
+
+    delegate :get, :put, :post, :delete, :base_uri, :base_uri=, :to => :@collection
+
+  end
+end

data/lib/toast/single.rb

@@ -25,10 +25,20 @@ module Toast
       @params = params
       @format = params[:format]
 
+      unless @model.respond_to?(subresource_name)
+        raise "Toast Error: Cannot find class method '#{@model}.#{subresource_name}', which is configured in 'acts_as_resource > singles'."
+      end
 
       @record = if @config_out.pass_params_to.include?(subresource_name)
+                  if @model.method(subresource_name).arity != 1
+                    raise "Toast Error: Class method '#{@model}.#{subresource_name}' must accept one parameter, as configured by 'acts_as_resource > pass_params_to'."
+                  end
                   @model.send(subresource_name, @params)
                 else
+                  if(@model.method(subresource_name).arity < -1 or 
+                     @model.method(subresource_name).arity > 0)
+                    raise "Toast Error: Class method '#{@model}.#{subresource_name}' must be callable w/o parameters"
+                  end
                   @model.send(subresource_name)
                 end
       
@@ -46,7 +56,8 @@ module Toast
         {
           :json => @record.represent( @config_out.exposed_attributes,
                                       @config_out.exposed_associations,
-                                      @base_uri ),
+                                      @base_uri,
+                                      @config_out.media_type),
           :status => :ok
         }
       else

data/lib/toast/version.rb

@@ -0,0 +1,3 @@
+module Toast
+  VERSION = '0.7.0'
+end

metadata

@@ -4,23 +4,49 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 6
+  - 7
   - 0
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors: 
-- Robert Annies
+- "robokopp (Robert Anni\xC3\xA9s)"
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2012-05-31 00:00:00 +02:00
+date: 2012-07-10 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: blockenspiel
+  name: shoulda
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rails
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 1
+        - 0
+        version: 3.1.0
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: blockenspiel
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
@@ -30,11 +56,11 @@ dependencies:
         - 2
         version: 0.4.2
   type: :runtime
-  version_requirements: *id001
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: rack-accept-media-types
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &id004 !ruby/object:Gem::Requirement 
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
@@ -43,11 +69,23 @@ dependencies:
         - 9
         version: "0.9"
   type: :runtime
-  version_requirements: *id002
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: ffaker
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id005
 description: |-
   Toast is an extension to Ruby on Rails that lets you expose any
-  ActiveRecord model as a resource according to the REST paradigm. The
-  representation format is JSON.
+  ActiveRecord model as a resource according to the REST paradigm via a generic controller. The default
+  representation format is JSON or can be anything
 email: robokopp@fernwerk.net
 executables: []
 
@@ -59,6 +97,7 @@ files:
 - app/controller/toast_controller.rb
 - config/routes.rb
 - lib/toast.rb
+- lib/toast/version.rb
 - lib/toast/active_record_extensions.rb
 - lib/toast/association.rb
 - lib/toast/collection.rb
@@ -67,6 +106,7 @@ files:
 - lib/toast/record.rb
 - lib/toast/resource.rb
 - lib/toast/single.rb
+- lib/toast/scoped_association.rb
 - README.md
 has_rdoc: true
 homepage: https://github.com/robokopp/toast