toast 0.1.0

data/README.md

@@ -0,0 +1,154 @@
+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.
+
+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.
+
+Toast is a Rails engine that runs one generic controller and a sets up
+the routing to it according to the definition in the models, which is
+denoted using a block oriented DSL.
+
+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 Ain't reST**
+
+*Be careful*: This version is experimental and probably not bullet
+proof. As soon as the gem is installed 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.
+
+Example
+=======
+
+Let the table `bananas` have the following schema:
+
+     create_table "bananas", :force => true do |t|
+       t.string   "name"
+       t.integer  "number"
+       t.string   "color"
+       t.integer  "apple_id"
+     end
+
+and let a corresponding model class have a *resourceful_model* annotation:
+
+     class Banana < ActiveRecord::Base
+       belongs_to :apple
+       has_many :coconuts
+       scope :find_some, where("number < 100")
+
+       resourceful_model do
+         # attributes or association names
+         fields :name, :number, :coconuts, :apple
+
+         # class methods of Banana returning an Array of Banana records
+         collections :find_some, :all
+       end
+     end
+
+The above definition inside the `resourceful_model` 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.
+
+### Get a collection
+    GET /bananas
+    --> 200,  '[{"uri":"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",
+                  ... }, ... ]
+### Get a customized collection (filtered, paging, etc.)
+
+    GET /bananas/find_some
+    --> 200, '[SOME BANANAS]'
+
+### Get a single resource representation:
+    GET /bananas/23
+    --> 200,  '{"uri":"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" }'
+
+### Get a 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",
+                       "number": 44}'
+    --> 200,  '{"uri":"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"}'
+
+### Create a new record
+    "POST" /bananas,  '{"name": "Johnny",
+                        "number": 888}'
+    --> 201,  {"uri":"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 }
+
+### Create an associated record
+    "POST" /bananas/23/coconuts, '{COCONUT}'
+    --> 201,  {"uri":"http://www.example.com/coconuts/432,
+               ...}
+
+### Delete records
+    DELETE /bananas/23
+    --> 200
+
+More details and configuration options are documented in the manual... (_comming soon_)
+
+Installation
+============
+
+    git clone git@github.com:robokopp/toast.git
+    gem install jeweler
+    cd toast
+    rake install
+
+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
+
+        rake
+
+   Or you may call `rake test` from the root directory of the working
+   copy. This will reinstall the toast gem before running tests
+   automatically.

data/app/controller/toast_controller.rb

@@ -0,0 +1,47 @@
+class ToastController < ApplicationController
+
+  def catch_all
+
+    begin
+      resource = Toast::Resource.build( params, request )
+      render resource.apply(request.method, request.body.read)
+
+    rescue Toast::ResourceNotFound => e
+      return head(:not_found)
+
+    rescue Toast::PayloadInvalid => e
+      return head(:unprocessable_entity)
+
+    rescue Toast::PayloadFormatError => e
+      return head(:bad_request)
+
+    rescue Toast::MethodNotAllowed => e
+      return head(:method_not_allowed)
+
+    rescue Toast::UnsupportedMediaType => e
+      return head(:unsupported_media_type)
+
+    rescue Exception => e
+      log_exception e
+      raise e if Rails.env == "test"
+      return head(:internal_server_error)
+    end
+
+  end
+
+  def not_found
+    return head(:not_found)
+  end
+
+
+  if Rails.env == "test"
+    def log_exception e
+      puts "#{e.class}: '#{e.message}'\n\n#{e.backtrace[0..14].join("\n")}\n\n"
+    end
+  else
+    def log_exception e
+      logger.error("#{e.class}: '#{e.message}'\n\n#{e.backtrace.join("\n")}")
+    end
+  end
+
+end

data/config/routes.rb

@@ -0,0 +1,17 @@
+Rails.application.routes.draw do
+
+  ActiveRecord::Base.descendants.each do |model|
+    next unless model.is_resourceful_model?
+
+    resource_name = model.to_s.pluralize.underscore
+
+    match "#{model.toast_config.namespace}/#{resource_name}(/:id(/:subresource))" => 'toast#catch_all', :constraints => { :id => /\d+/ }, :resource => resource_name
+    match "#{model.toast_config.namespace}/#{resource_name}/:subresource" => 'toast#catch_all', :resource => resource_name
+  end
+
+  match ":resource(/:id(/:subresource))" => 'toast#not_found', :constraints => { :id => /\d+/ }
+  match ":resource/:subresource" => 'toast#not_found'
+
+end
+
+

data/lib/toast.rb

@@ -0,0 +1 @@
+require 'toast/engine' if defined?(Rails) && Rails::VERSION::MAJOR == 3

data/lib/toast/active_record_extensions.rb

@@ -0,0 +1,76 @@
+require 'blockenspiel'
+require 'toast/config_dsl'
+
+module Toast
+  module ActiveRecordExtensions
+
+    # Configuration DSL
+    def resourceful_model &block
+      @toast_config = Toast::ConfigDSL::Base.new(self)
+      Blockenspiel.invoke( block, @toast_config)
+
+      # add class methods
+      self.instance_eval do
+
+        cattr_accessor :uri_base
+
+        def is_resourceful_model?
+          true
+        end
+
+        def toast_config
+          @toast_config
+        end
+      end
+
+      # add instance methods
+      self.class_eval do
+        # Return toast's standard uri for a record
+        def uri
+          "#{self.class.uri_base}/#{self.class.to_s.pluralize.underscore}/#{self.id}"
+        end
+
+        # Returns a Hash with all exposed attributes
+        def exposed_attributes options = {}
+          options.reverse_merge! :in_collection => false,
+                                 :with_uri => true
+
+          # attributes
+          exposed_attr =
+            options[:in_collection] ? self.class.toast_config.in_collection.exposed_attributes :
+                                      self.class.toast_config.exposed_attributes
+
+          out = exposed_attr.inject({}) do |acc, attr|
+            acc[attr] = self[attr]
+            acc
+          end
+
+          # association URIs
+          exposed_assoc =
+            options[:in_collection] ? self.class.toast_config.in_collection.exposed_associations :
+                                      self.class.toast_config.exposed_associations
+
+          exposed_assoc.each do |assoc|
+            out[assoc] = self.uri + "/" + assoc
+          end
+
+          out["uri"] = self.uri if options[:with_uri]
+
+          out
+        end
+      end
+    end
+
+    # defaults for non resourceful-models
+    def is_resourceful_model?
+      false
+    end
+    def resourceful_model_options
+      nil
+    end
+    def resource_names
+      @@all_resourceful_resource_names
+    end
+  end
+
+end

data/lib/toast/associate_collection.rb

@@ -0,0 +1,58 @@
+module Toast
+  class AssociateCollection < Resource
+    
+    def initialize model, id, subresource_name
+      unless model.toast_config.exposed_associations.include? subresource_name
+        raise ResourceNotFound
+      end
+
+      @model = model
+      @record = model.find(id) rescue raise(ResourceNotFound)
+      @collection = subresource_name
+
+      @associate_model = Resource.get_class_by_resource_name subresource_name
+      @associate_model.uri_base = @model.uri_base
+      
+    end
+
+    def get
+      records = @record.send(@collection)
+      {
+        :json => records.map{|r| r.exposed_attributes(:in_collection => true)},
+        :status => :ok
+      }
+    end
+
+    def put
+      raise MethodNotAllowed
+    end
+
+    def post payload
+
+
+      if self.media_type != @associate_model.toast_config.media_type
+        raise UnsupportedMediaType
+      end
+
+      if payload.keys.to_set != @associate_model.toast_config.exposed_attributes.to_set
+        raise PayloadInvalid
+      end
+
+      unless payload.is_a? Hash
+        raise PayloadFormatError
+      end 
+      #debugger  
+      record = @record.send(@collection).create payload
+      
+      {
+        :json => record.exposed_attributes,
+        :location => record.uri,
+        :status => :created
+      }
+    end
+
+    def delete
+      raise MethodNotAllowed
+    end
+  end
+end

data/lib/toast/attribute.rb

@@ -0,0 +1,38 @@
+module Toast
+  class Attribute < Resource
+
+    def initialize model, id, attribute_name
+      unless model.toast_config.exposed_attributes.include? attribute_name
+        raise ResourceNotFound 
+      end
+
+      @model = model
+      @record = model.find(id) rescue raise(ResourceNotFound)
+      @attribute_name = attribute_name
+    end
+    
+    def get
+      {
+        :json => @record[@attribute_name],
+        :status => :ok
+      }
+    end
+
+    def put payload
+      @record.update_attribute(@attribute_name, payload)
+      { 
+        :json => @record[@attribute_name],
+        :stauts => :ok,
+        :loaction => @record.uri
+      }
+    end
+
+    def post payload
+      raise MethodNotAllowed
+    end
+    
+    def delete
+      raise MethodNotAllowed
+    end
+  end
+end

data/lib/toast/config_dsl.rb

@@ -0,0 +1,112 @@
+module Toast
+  module ConfigDSL
+
+    class Base
+      include Blockenspiel::DSL
+      dsl_attr_accessor :media_type, :has_many, :namespace
+
+      def initialize model
+        @model = model
+        @fields = []
+        @collections = []
+        @media_type = "application/json"
+        @exposed_attributes = []
+        @exposed_associations = []
+        @in_collection = ConfigDSL::InCollection.new model, self
+      end
+
+      def fields= *fields
+        @fields.push *ConfigDSL.sanitize(fields,"fields")
+        @fields.each do |attr_or_assoc|
+          if @model.new.attributes.keys.include? attr_or_assoc
+            @exposed_attributes << attr_or_assoc
+          else
+            @exposed_associations << attr_or_assoc
+          end
+        end
+
+      end
+
+      def fields *arg
+        return(@fields) if arg.empty?
+        self.fields = *arg
+      end
+
+      attr_reader :exposed_attributes, :exposed_associations
+
+      def collections= collections=[]
+        @collections = ConfigDSL.sanitize(collections, "collections")
+      end
+
+      def collections *arg
+        return(@collections) if arg.empty?
+        self.collections = *arg
+      end
+
+      def in_collection &block
+        if block_given?
+          Blockenspiel.invoke( block, @in_collection)
+        else
+          @in_collection
+        end
+      end
+
+      # non DSL methods
+      dsl_methods false
+    end
+
+    class InCollection
+      include Blockenspiel::DSL
+
+      def initialize model, base_config
+        @model = model
+        @fields = base_config.fields
+        @exposed_attributes = base_config.exposed_attributes
+        @exposed_associations = base_config.exposed_associations
+        @media_type = "application/json"
+      end
+
+      def fields= *fields
+        @fields = ConfigDSL.sanitize(fields,"fields")
+
+        @exposed_attributes = []
+        @exposed_associations = []
+
+        @fields.each do |attr_or_assoc|
+          if @model.new.attributes.keys.include? attr_or_assoc
+            @exposed_attributes << attr_or_assoc
+          else
+            @exposed_associations << attr_or_assoc
+          end
+        end
+      end
+
+      def fields *arg
+        return(@fields) if arg.empty?
+        self.fields = *arg
+      end
+
+      attr_reader :exposed_attributes, :exposed_associations
+    end
+
+
+    # Helper
+
+    # checks if list is made of symbols and strings
+    # converts a single value to an Array
+    # converts all symbols to strings
+    def self.sanitize list, name
+      list = [list].flatten
+
+      list.map do |x|
+        if (!x.is_a?(Symbol) && !x.is_a?(String))
+          raise "Toast Config Error: '#{name}' should be a list of Symbols or Strings"
+        else
+          x.to_s
+        end
+      end
+    end
+
+
+  end
+end

data/lib/toast/engine.rb

@@ -0,0 +1,28 @@
+require 'toast/active_record_extensions.rb'
+require 'toast/resource.rb'
+require 'toast/root_collection'
+require 'toast/associate_collection'
+require 'toast/attribute'
+require 'toast/record'
+require 'action_dispatch/http/request'
+
+module Toast
+  class Engine < Rails::Engine
+
+    # configure our plugin on boot. other extension points such
+    # as configuration, rake tasks, etc, are also available
+    initializer "toast.initialize" do |app|
+      # Add 'restful_model' declaration to ActiveRecord::Base
+      ActiveRecord::Base.extend Toast::ActiveRecordExtensions
+
+      # Load all models in app/models early to setup routing
+      begin
+        Dir["#{Rails.root}/app/models/**/*.rb"].each{|m| require m }
+
+      rescue ActiveRecord::StatementInvalid
+        # raised when DB is not setup yet. (rake db:schema:load)
+      end
+
+    end
+  end
+end

data/lib/toast/record.rb

@@ -0,0 +1,51 @@
+module Toast
+  class Record < Resource
+    
+    def initialize model, id
+      @model = model      
+      @record = model.find(id) rescue raise(ResourceNotFound.new)
+    end
+
+    def post payload
+      raise MethodNotAllowed
+    end
+
+    # get, put, delete, post return a Hash that can be used as
+    # argument for ActionController#render
+
+    def put payload       
+      if self.media_type != @model.toast_config.media_type
+        raise UnsupportedMediaType
+      end
+
+      unless payload.is_a? Hash
+        raise PayloadFormatError
+      end
+
+      if payload.keys.to_set != @model.toast_config.exposed_attributes.to_set
+        raise PayloadInvalid
+      end
+      
+      @record.update_attributes payload
+      {
+        :json => @record.exposed_attributes,
+        :status => :ok,
+        :location => @record.uri
+      }
+    end
+
+    def get 
+      {
+        :json => @record.exposed_attributes,
+        :status => :ok
+      }
+    end
+
+    def delete
+      @record.destroy
+      {
+        :status => :ok
+      }
+    end
+  end
+end

data/lib/toast/resource.rb

@@ -0,0 +1,86 @@
+module Toast
+
+  class ResourceNotFound < Exception; end
+  class MethodNotAllowed < Exception; end
+  class PayloadInvalid < Exception; end
+  class PayloadFormatError < Exception; end
+  class UnsupportedMediaType < Exception; end
+
+  # Represents a resource. There are following resource types as sub classes:
+  # Record, RootCollection, AssociateCollection, Attribute
+  class Resource
+
+    attr_accessor :media_type
+
+    def initialize
+      raise 'ToastResource#new: use #build to create an instance'
+    end
+
+    def self.build params, request
+
+      resource_name = params[:resource]
+      id = params[:id]
+      subresource_name = params[:subresource]
+
+      uri_base = "#{request.protocol}#{request.host}"
+      unless (request.protocol == "http://" and request.port == 80) or
+             (request.protocol == "https://" and request.port == 443)
+        uri_base += ":#{request.port}"
+      end
+
+      begin
+
+        model = get_class_by_resource_name resource_name
+
+        model.uri_base = uri_base
+        model.uri_base += "/#{model.toast_config.namespace}" if model.toast_config.namespace
+
+        # decide which sub type
+        rsc = if id.nil?
+                Toast::RootCollection.new(model, subresource_name)
+              elsif subresource_name.nil?
+                Toast::Record.new(model, id)
+              elsif model.toast_config.exposed_associations.include? subresource_name
+                Toast::AssociateCollection.new(model, id, subresource_name)
+              elsif model.toast_config.exposed_attributes.include? subresource_name
+                Toast::Attribute.new(model, id, subresource_name)
+              else
+                raise ResourceNotFound
+              end
+
+        rsc.media_type = request.media_type
+
+        rsc
+      rescue NameError
+        raise ResourceNotFound
+      end
+    end
+
+    def self.get_class_by_resource_name name
+      begin
+        model = name.singularize.classify.constantize # raises NameError
+
+        unless ((model.superclass == ActiveRecord::Base) and model.is_resourceful_model?)
+          raise ResourceNotFound
+        end
+
+        model
+
+      rescue NameError
+        raise ResourceNotFound
+      end
+    end
+
+    def apply method, payload
+      case method
+      when "PUT","POST"
+        self.send(method.downcase, ActiveSupport::JSON.decode(payload))
+      when "DELETE","GET"
+        self.send(method.downcase)
+      else
+        raise MethodNotAllowed
+      end
+    end
+  end
+end
+

data/lib/toast/root_collection.rb

@@ -0,0 +1,58 @@
+module Toast
+  class RootCollection < Resource
+    
+    def initialize model, subresource_name
+      
+      subresource_name ||= "all"
+      
+      unless model.toast_config.collections.include? subresource_name
+        raise ResourceNotFound
+      end
+
+      @model = model
+      @collection = subresource_name
+    end
+
+    def get
+      records = @model.send(@collection)
+      {
+        :json => records.map{|r| r.exposed_attributes(:in_collection => true)},
+        :status => :ok
+      }
+    end
+
+    def put
+      raise MethodNotAllowed
+    end
+
+    def post payload
+      if @collection != "all"
+        raise MethodNotAllowed
+      end
+
+      if self.media_type != @model.toast_config.media_type
+        raise UnsupportedMediaType
+      end
+
+      unless payload.is_a? Hash
+        raise PayloadFormatError
+      end
+
+      if payload.keys.to_set != @model.toast_config.exposed_attributes.to_set
+        raise PayloadInvalid
+      end
+      
+      record = @model.create payload
+      
+      {
+        :json => record,
+        :location => record.uri,
+        :status => :created
+      }
+    end
+
+    def delete
+      raise MethodNotAllowed
+    end
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: toast
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Robert Annies
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-06-28 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: blockenspiel
+  requirement: &1015970 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+  type: :runtime
+  prerelease: false
+  version_requirements: *1015970
+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.'
+email: robokopp@fernwerk.net
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- app/controller/toast_controller.rb
+- config/routes.rb
+- lib/toast.rb
+- lib/toast/active_record_extensions.rb
+- lib/toast/associate_collection.rb
+- lib/toast/attribute.rb
+- lib/toast/config_dsl.rb
+- lib/toast/engine.rb
+- lib/toast/record.rb
+- lib/toast/resource.rb
+- lib/toast/root_collection.rb
+- README.md
+homepage: https://github.com/robokopp/toast
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: Toast adds a RESTful interface to ActiveRecord models in Ruby on Rails.
+test_files: []