resource_full 0.7.6

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Brian Guthrie
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,100 @@
+= ResourceFull 0.7.5
+
+* http://github.com/bguthrie/resource_full/
+
+== DESCRIPTION
+
+ResourceFull integrated with ActionController to provide a comprehensive 
+RESTful resource modeling and querying framework.  It provides parameter 
+queryability, paging, sorting, separation of controller concerns, multiple 
+formats (HTML, XML, JSON), CRUD access permissions, and API metadata 
+surrounding the resource itself. It's opinionated but is intended to provide 
+you with as much as possible without limiting your ability to customize its
+behavior.
+
+== GOALS
+
+The major distinguishing features of ResourceFull are:
+
+* Queryability: the ability to designate certain parameters as queryable,
+  and map them to columns and SQL queries in the underlying model.
+  These queries chain together multiple named or unnamed scopes and can be
+  used either for a SQL SELECT or SELECT COUNT.
+  This functionality may be moved into a separate plugin in the future.
+* Pagination and orderability: it automatically responds to requests for
+  limit, offset, order_by, and order_dir.
+* Implementation: Default implementations for HTML, XML, and JSON controller requests.
+* API documentation: ResourceFull-enabled Rails apps are able to provide automatic
+  documentation of the resources they expose, up to a point.  (This is enabled
+  in large part by the queryability functionality and other resource-level
+  descriptors.)  It's my hope that this can eventually be consumed by a Rails
+  resource registrar that acts as the single source of record for multiple REST
+  engines within an organization.
+
+== EXAMPLE
+
+  class UsersController < ResourceFull::Base
+    identified_by :username, :unless => lambda { |id| id =~ /^[0-9]+$/ }
+    
+    queryable_with :city, :state, :from => :address
+    queryable_with :name, :columns => [:first_name, :last_name]
+    queryable_with :email_address, :fuzzy => true
+    queryable_with :is_active, :scope => :active
+
+    orderable_by :city, :from => :address
+    
+    responds_to :html
+    responds_to :xml, :only => [:read, :update]
+  end
+  
+  class AddressesController < ResourceFull::Base
+    nests_within :users
+    queryable_with :city, :state
+  end
+
+This allows for the following:
+
+  /users/bguthrie.xml
+  /users?name=Guthrie
+  /users?email_address=gmail
+  /users.xml?city=Chicago&name=Brian,Paul,Alicia&order_by=city&order_dir=asc
+  /users.xml?limit=10&offset=30
+  /users/bguthrie/addresses
+
+  >> UsersController.to_xml
+  => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<resource>\n  <parameters type=\"array\"/>..."
+
+== API DOCUMENTATION
+
+To enable ResourceFull to document your resources at /resources.xml and /resources/<name>/routes.xml, 
+add +map.api+ to your +routes.rb+ file.
+
+== CONTRIBUTORS
+
+* {Vijay Aravamudhan}[http://github.com/vraravam]
+* {Dirk Elmendorf}[http://github.com/economysizegeek]
+
+== LICENSE
+
+(The MIT License)
+
+Copyright (c) 2009 Brian Guthrie
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,19 @@
+require File.dirname(__FILE__) + '/../../../config/environment'
+
+require 'rake'
+require 'spec/rake/spectask'
+require 'rcov/rcovtask'
+
+task :default => :spec
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', 'spec/spec.opts']
+end
+
+require 'rcov/version'
+
+Rcov::RcovTask.new do |t|
+  t.pattern = "spec/**/_spec.rb"
+  t.rcov_opts = [ "--spec-only" ]
+  t.output_dir = "coverage"
+end

data/lib/resource_full/base.rb

@@ -0,0 +1,140 @@
+module ResourceFull
+  class ResourceNotFound < Exception; end
+  
+  class Base < ActionController::Base
+    if ActionPack::VERSION::STRING < "2.3.0"
+      session :off, :if => lambda { |request| request.format.xml? || request.format.json? }
+    end
+
+    def model_name; self.class.model_name; end
+    def model_class; self.class.model_class; end
+
+    class << self
+      # Returns the list of all resources handled by ResourceFull.
+      def all_resources
+        ActionController::Routing.possible_controllers.map do |possible_controller|
+          controller_for(possible_controller)
+        end.select do |controller_class|
+          controller_class.ancestors.include?(self)
+        end
+      end
+      
+      # Returns the controller for the given resource.
+      def controller_for(resource)
+        return resource if resource.is_a?(Class) && resource.ancestors.include?(ActionController::Base)
+        "#{resource.to_s.underscore}_controller".classify.constantize
+      rescue NameError
+        raise ResourceFull::ResourceNotFound, "not found: #{resource}"
+      end
+      
+      private
+      
+        def inherited(controller)
+          super(controller)
+          controller.send :extend, ClassMethods
+          controller.send :include, 
+            ResourceFull::Retrieve, 
+            ResourceFull::Query, 
+            ResourceFull::Dispatch, 
+            ResourceFull::Render
+          controller.send :alias_retrieval_methods!
+        end
+    end
+  end
+
+  module ClassMethods
+    attr_accessor_with_default :paginatable, true
+    attr_accessor_with_default :resource_identifier, :id
+    
+    # Returns true if this resource is paginatable, which is to say, it recognizes and honors
+    # the :limit and :offset parameters if present in a query.  True by default.
+    def paginatable?; paginatable; end
+    
+    # The name of the model exposed by this resource.  Derived from the name of the controller
+    # by default.  See +exposes+.
+    def model_name
+      @model_class ? @model_class.name.demodulize.underscore : self.controller_name.singularize
+    end
+    
+    # Indicates that this resource is identified by a database column other than the default
+    # :id.  
+    # TODO This should honor the model's primary key column but needn't be bound by it.
+    # TODO Refactor this.
+    # TODO Improve the documentation.
+    def identified_by(*args, &block)
+      opts = args.extract_options!
+      column = args.first
+      if !block.nil?
+        self.resource_identifier = block
+      elsif !column.nil?
+        if !opts.empty? && ( opts.has_key?(:if) || opts.has_key?(:unless) )
+          if opts[:unless] == :id_numeric
+            opts[:unless] = lambda { |id| id =~ /^[0-9]+$/ }
+          end
+          
+          # Negate the condition to generate an :if from an :unless.
+          condition = opts[:if] || lambda { |id| not opts[:unless].call(id) }
+          
+          self.resource_identifier = lambda do |id|
+            if condition.call(id)
+              column
+            else :id end
+          end
+        else
+          self.resource_identifier = column
+        end
+      else
+        raise ArgumentError, "identified_by expects either a block or a column name and some options"
+      end
+    end
+    
+    # The class of the model exposed by this resource.  Derived from the model name.  See +exposes+.
+    def model_class
+      @model_class ||= model_name.camelize.constantize
+    end
+
+    # Indicates that the CRUD methods should be called on the given class.  Accepts
+    # either a class object or the name of the desired model.
+    def exposes(model_class)
+      remove_retrieval_methods!
+      @model_class = model_class.to_s.singularize.camelize.constantize
+      alias_retrieval_methods!
+    end
+        
+    # Renders the resource as XML.
+    def to_xml(opts={})
+      { :name       => self.controller_name,
+        :parameters => self.queryable_params,
+        :identifier => self.xml_identifier
+      }.to_xml(opts.merge(:root => "resource"))
+    end
+    
+    protected
+    
+      def xml_identifier
+        (self.resource_identifier.is_a?(Proc) ? self.resource_identifier.call(nil) : self.resource_identifier).to_s
+      end
+        
+    private
+        
+      def alias_retrieval_methods!
+        define_method("new_#{model_name}")                 { new_model_object }
+        define_method("find_#{model_name}")                { find_model_object }
+        define_method("create_#{model_name}")              { create_model_object }
+        define_method("update_#{model_name}")              { update_model_object }
+        define_method("destroy_#{model_name}")             { destroy_model_object }
+        define_method("find_all_#{model_name.pluralize}")  { find_all_model_objects }
+        define_method("count_all_#{model_name.pluralize}") { count_all_model_objects }
+      end
+      
+      def remove_retrieval_methods!
+        remove_method "new_#{model_name}" if method_defined? "new_#{model_name}"
+        remove_method "find_#{model_name}" if method_defined? "find_#{model_name}"
+        remove_method "create_#{model_name}" if method_defined? "create_#{model_name}"
+        remove_method "update_#{model_name}" if method_defined? "update_#{model_name}"
+        remove_method "destroy_#{model_name}" if method_defined? "destroy_#{model_name}"
+        remove_method "find_all_#{model_name.pluralize}" if method_defined? "find_all_#{model_name.pluralize}"
+        remove_method "count_all_#{model_name.pluralize}" if method_defined? "count_all_#{model_name.pluralize}"
+      end
+  end
+end

data/lib/resource_full/controllers/resources.rb

@@ -0,0 +1,16 @@
+module ResourceFull
+  module Controllers
+    class ResourcesController < ResourceFull::Base
+      responds_to :xml
+
+      protected
+        def find_all_resources
+          ResourceFull::Base.all_resources
+        end
+
+        def find_resource
+          ResourceFull::Base.controller_for(params[:id].pluralize)
+        end
+    end
+  end
+end

data/lib/resource_full/controllers/resources_controller.rb

@@ -0,0 +1,26 @@
+module ResourceFull
+  module Controllers
+    class ResourcesController < ResourceFull::Base
+      responds_to :xml, :only => [ :read ]
+      
+      def index_xml
+        render :xml => find_all_resources.to_xml(:root => "resources")
+      end
+      
+      def show_xml
+        render :xml => find_resource.to_xml
+      rescue ResourceFull::ResourceNotFound => e
+        render :xml => e.to_xml, :status => :not_found
+      end
+
+      protected
+        def find_all_resources
+          ResourceFull::Base.all_resources
+        end
+
+        def find_resource
+          ResourceFull::Base.controller_for(params[:id])
+        end
+    end
+  end
+end

data/lib/resource_full/controllers/routes_controller.rb

@@ -0,0 +1,16 @@
+module ResourceFull
+  module Controllers
+    class RoutesController < ResourceFull::Base
+      exposes ResourceFull::Models::ResourcedRoute
+      responds_to :xml, :only => [ :read ]
+      
+      def index_xml
+        render :xml => find_all_routes.to_xml(:root => "routes")
+      end
+      
+      def find_all_routes
+        ResourceFull::Models::ResourcedRoute.find :all, params
+      end
+    end
+  end
+end

data/lib/resource_full/core_extensions/api.rb

@@ -0,0 +1,26 @@
+module ResourceFull
+  module CoreExtensions
+    module API
+      
+      # Generate ActionController routes for RESTful services documentation.
+      def api
+        with_options :format => 'xml', :conditions => { :method => :get } do |map|
+          map.named_route 'resource',         '/resources/:id.xml', 
+            :action => 'show',  :controller => 'resource_full/controllers/resources'
+          map.named_route 'resources',        '/resources.xml', 
+            :action => 'index', :controller => 'resource_full/controllers/resources'
+          map.named_route 'resources_route',  '/resources/:resource_id/routes/:id.xml', 
+            :action => 'show',  :controller => 'resource_full/controllers/routes'
+          map.named_route 'resources_routes', '/resources/:resource_id/routes.xml', 
+            :action => 'index', :controller => 'resource_full/controllers/routes'
+          map.named_route 'routes', '/routes.xml',
+            :action => 'index', :controller => 'resource_full/controllers/routes'
+        end
+      end
+    end
+  end
+end
+
+class ActionController::Routing::RouteSet::Mapper
+  include ResourceFull::CoreExtensions::API
+end

data/lib/resource_full/core_extensions/exception.rb

@@ -0,0 +1,25 @@
+module ResourceFull
+  module CoreExtensions
+    module Exception
+      def to_xml(options = {})
+        options[:indent] ||= 2
+        options[:builder] ||= Builder::XmlMarkup.new(:indent => options[:indent])
+        options[:builder].instruct! unless options[:skip_instruct]
+
+        options[:builder].errors {
+          options[:builder].error self.to_s
+          options[:builder].error self.backtrace if options[:include_backtrace] == true
+        }
+      end
+
+      def to_json(options = {})
+        {"error" => {:text => self.to_s,
+                     :backtrace => self.backtrace}}.to_json
+      end
+    end
+  end
+end
+
+class Exception
+  include ResourceFull::CoreExtensions::Exception
+end

data/lib/resource_full/core_extensions/from_json.rb

@@ -0,0 +1,13 @@
+module ResourceFull
+  module CoreExtensions
+    module Hash
+      def from_json(json)
+        ActiveSupport::JSON.decode json
+      end
+    end
+  end
+end
+
+class Hash
+  extend ResourceFull::CoreExtensions::Hash
+end

data/lib/resource_full/core_extensions/module.rb

@@ -0,0 +1,13 @@
+module ResourceFull
+  module CoreExtensions
+    module Module
+      def simple_name
+        name.split("::").last
+      end
+    end
+  end
+end
+
+class Module
+  include ResourceFull::CoreExtensions::Module
+end

data/lib/resource_full/dispatch.rb

@@ -0,0 +1,196 @@
+module ResourceFull
+  module Dispatch
+    class << self
+      def included(controller)
+        super(controller)
+        controller.send :extend, ClassMethods
+        controller.before_filter :ensure_sets_format_when_ie7
+        controller.before_filter :ensure_responds_to_format
+        controller.before_filter :ensure_responds_to_method
+      end
+    end
+    
+    module ClassMethods
+      DEFAULT_FORMATS = [ :xml, :html, :json ]
+      
+      CRUD_METHODS_TO_ACTIONS = {
+        :create => [ :create, :new ],
+        :read   => [ :show, :index, :count ],
+        :update => [ :update, :edit ],
+        :delete => [ :destroy ]
+      }
+      
+      # Indicates that the controller responds to one of the requested CRUD (create, read,
+      # update, delete) methods.  These correspond to controller methods in the following
+      # manner:
+      #
+      # * Create: create, new
+      # * Read: show, index, count
+      # * Update: update, edit
+      # * Delete: destroy
+      #
+      # By default, a format supports all of the above methods, unless you specify otherwise.
+      # Override these defaults by using the :only or :except options.  For example,
+      #
+      #   responds_to :xml, :only => [:create, :delete]
+      #
+      # A controller may be reset back to default responds (xml, html, all CRUD methods) by
+      # specifying responds_to :defaults.
+      def responds_to(*formats)
+        if formats.first == :defaults
+          @renderable_formats = default_responds
+          @renderable_formats_overridden = false
+          return
+        end
+        
+        opts = formats.extract_options!
+        
+        supported_crud_methods = if opts[:only]
+          [ opts[:only] ].flatten
+        elsif opts[:except]
+          possible_crud_methods - [ opts[:except] ].flatten
+        else
+          possible_crud_methods
+        end
+        
+        unless renderable_formats_already_overridden?
+          @renderable_formats = {}
+          @renderable_formats_overridden = true
+        end
+        
+        formats.each do |format|
+          renderable_formats[format] = supported_crud_methods
+        end
+      end
+      
+      # A list of symbols of all allowed formats (e.g. :xml, :html)
+      def allowed_formats
+        renderable_formats.keys
+      end
+      
+      # A list of symbols of all allowed CRUD methods (e.g. :create, :delete)
+      def allowed_methods(format=:html)
+        renderable_formats[format] || []
+      end
+      
+      # A list of symbols of all allowed controller actions (e.g. :show, :destroy) derived from
+      # the allowed CRUD actions.
+      def allowed_actions(format=:html)
+        renderable_formats[format].sum {|crud_action| CRUD_METHODS_TO_ACTIONS[crud_action]}
+      end
+      
+      # A list of all possible CRUD actions that this framework understands, which is to say,
+      # the core Rails actions plus +count+ (and perhaps others eventually).
+      def possible_actions
+        CRUD_METHODS_TO_ACTIONS.values.sum([])
+      end
+      
+      # Returns true if the request format is an allowed format.
+      def responds_to_request_format?(request)
+        allowed_formats.include? extract_request_format(request)
+      end
+      
+      # Returns true if the request action is an allowed action as defined by the allowed CRUD methods.
+      def responds_to_request_action?(request, action)
+        # TODO Consider using ActionController's +verify+ method in preference to this.
+        # TODO We don't verify custom methods yet, so ignore them.
+        return true unless possible_actions.include?(action.to_sym)
+        allowed_actions(extract_request_format(request)).include? action.to_sym
+      end
+      
+      protected
+      
+        def renderable_formats
+          @renderable_formats ||= default_responds
+        end
+      
+      private
+      
+        def possible_crud_methods
+          CRUD_METHODS_TO_ACTIONS.keys
+        end
+      
+        def extract_request_format(request)
+          request.format.html? ? :html : request.format.to_sym
+        end
+      
+        def renderable_formats_already_overridden?
+          @renderable_formats_overridden
+        end
+        
+        def default_responds
+          returning({}) do |responses|
+            DEFAULT_FORMATS.each do |format|
+              responses[format] = CRUD_METHODS_TO_ACTIONS.keys.dup
+            end
+          end
+        end
+    end
+    
+    [:index, :count, :show, :new, :create, :edit, :update, :destroy].each do |name|
+      define_method(name) { dispatch_to name }
+    end
+
+    protected
+    
+    def model_object=(object)
+      instance_variable_set "@#{model_name}", object
+    end
+    
+    def model_object
+      instance_variable_get "@#{model_name}"
+    end
+    
+    def model_objects=(objects)
+      instance_variable_set "@#{model_name.pluralize}", objects
+    end
+    
+    def model_objects
+      instance_variable_get "@#{model_name.pluralize}"
+    end
+    
+    private
+        
+    def ensure_sets_format_when_ie7
+      if user_agent_ie7?
+        if request_looks_like?('json', 'javascript')
+          request.format = 'json'
+        elsif request_looks_like?('xml')
+          request.format = 'xml'
+        else
+          request.format = 'html'
+        end
+      end
+    end
+    
+    def user_agent_ie7?
+      request.headers["HTTP_USER_AGENT"] =~ /MSIE 7.0/
+    end
+    
+    def request_looks_like?(*formats)
+      formats.any? do |format|
+        request.format.to_s =~ /#{format}/ || request.headers['REQUEST_URI'] =~ /\.#{format}[?]/
+      end
+    end
+        
+    def ensure_responds_to_format
+      unless self.class.responds_to_request_format?(request)
+        render :text => "Resource does not have a representation in #{request.format.to_str} format", :status => :not_acceptable
+      end
+    end
+    
+    def ensure_responds_to_method
+      unless self.class.responds_to_request_action?(request, params[:action])
+        render :text => "Resource does not allow #{params[:action]} action", :status => :method_not_allowed
+      end
+    end
+    
+    def dispatch_to(method)      
+      respond_to do |requested_format|
+        self.class.allowed_formats.each do |renderable_format|
+          requested_format.send(renderable_format) { send("#{method}_#{renderable_format}") }
+        end
+      end
+    end    
+  end
+end