benhoskings-hammock 0.2.4

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2008 Ben Hoskings <ben@hoskings.net>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of Ben Hoskings nor the names of any of the software's
+      contributors may be used to endorse or promote products derived from
+      this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Manifest.txt

@@ -0,0 +1,42 @@
+History.txt
+LICENSE
+Manifest.txt
+README.rdoc
+Rakefile
+lib/hammock.rb
+lib/hammock/ajaxinate.rb
+lib/hammock/callbacks.rb
+lib/hammock/canned_scopes.rb
+lib/hammock/constants.rb
+lib/hammock/controller_attributes.rb
+lib/hammock/export_scope.rb
+lib/hammock/hamlink_to.rb
+lib/hammock/javascript_buffer.rb
+lib/hammock/logging.rb
+lib/hammock/model_attributes.rb
+lib/hammock/model_logging.rb
+lib/hammock/monkey_patches/action_pack.rb
+lib/hammock/monkey_patches/active_record.rb
+lib/hammock/monkey_patches/array.rb
+lib/hammock/monkey_patches/hash.rb
+lib/hammock/monkey_patches/logger.rb
+lib/hammock/monkey_patches/module.rb
+lib/hammock/monkey_patches/numeric.rb
+lib/hammock/monkey_patches/object.rb
+lib/hammock/monkey_patches/route_set.rb
+lib/hammock/monkey_patches/string.rb
+lib/hammock/overrides.rb
+lib/hammock/resource_mapping_hooks.rb
+lib/hammock/resource_retrieval.rb
+lib/hammock/restful_actions.rb
+lib/hammock/restful_rendering.rb
+lib/hammock/restful_support.rb
+lib/hammock/route_drawing_hooks.rb
+lib/hammock/route_for.rb
+lib/hammock/scope.rb
+lib/hammock/suggest.rb
+lib/hammock/utils.rb
+misc/scaffold.txt
+misc/template.rb
+tasks/hammock_tasks.rake
+test/hammock_test.rb

data/README.rdoc

@@ -0,0 +1,105 @@
+= hammock
+
+http://github.com/benhoskings/hammock
+
+
+== DESCRIPTION:
+
+Hammock is a Rails plugin that eliminates redundant code in a very RESTful manner. It does this in lots in lots of different places, but in one manner: it encourages specification in place of implementation.
+
+
+Hammock enforces RESTful resource access by abstracting actions away from the controller in favour of a clean, model-like callback system.
+
+Hammock tackles the hard and soft sides of security at once with a scoping security system on your models. Specify who can verb what resources under what conditions once, and everything else - the actual security, link generation, index filtering - just happens.
+
+Hammock inspects your routes and resources to generate a routing tree for each resource. Parent resources in a nested route are handled transparently at every point - record retrieval, creation, and linking.
+
+It makes more sense when you see how it works though, so check out the screencast!
+
+
+== REQUIREMENTS:
+
+benhoskings-ambition
+benhoskings-ambitious-activerecord
+
+
+== INSTALL:
+
+sudo gem install benhoskings-hammock --source http://gems.github.com
+
+class ApplicationController
+  include Hammock
+  ...
+
+
+== LICENSE:
+
+Hammock is licensed under the BSD license, which can be found in full in the LICENSE file.
+
+
+== SYNOPSIS
+
+At the moment, you can do this with Hammock:
+
+  class ApplicationController < ActionController::Base
+    include Hammock
+  end
+
+  class BeersController < ApplicationController
+  end
+
+  class Person < ActiveRecord::Base
+  end
+
+  class Beer < ActiveRecord::Base
+    belongs_to :creator, :class_name => 'Person'
+    belongs_to :recipient, :class_name => 'Person'
+
+    def read_scope_for account
+      proc {|beer| beer.creator_id == account.id || beer.recipient_id == account.id }
+    end
+    export_scope :read
+    export_scope :read, :as => :index
+    
+    def write_scope_for account
+      proc {|beer| record.creator_id == account.id }
+    end
+    export_scope :write
+  end
+
+  <% @beers.each do |beer| %>
+    From <%= beer.creator.name %> to <%= beer.recipient.name %>, <%= beer.reason %>, rated <%= beer.rating %>
+    <%= hamlink_to :edit, beer %>
+  <% end %>
+
+The scope methods above require just one thing -- a context-free proc object that takes an ActiveRecord record as its argument, and returns true iff that record is within the scope for the specified account. Hammock uses the method (e.g. Beer.read_scope_for) to define resource and record scopes for the model:
+
+  Beer.readable_by(account): the set of Beer records whose existence can be known by account
+  Beer#readable_by?(account): returns true if the existence of this Beer instance can be known by account
+
+You define the logic for read, index and write scopes in Beer.[read,index,write]_scope_for, and the rest just works.
+
+These scope definitions are exploited extensively, to provide index selection, scoping for record selection, and post-selection object checks.
+
+- They provide the conditions that should be applied to retrieve the index of each resource. The scope is used transperently by Hammock on /beers -> BeersController#index, and is available for use through Beer.indexable_by(account).
+
+- They provide a scope within which records are searched for on single-record actions. For example, given the request /beers/5 -> BeersController#show{:id => 5}, Rails would generate the following SQL:
+
+  SELECT * FROM "beers" WHERE (beers."id" = 5) LIMIT 1
+
+Hammock uses the conditions specified in Beer.read_scope_for to generate (assuming an account_id of 3):
+
+  SELECT * FROM "beers" WHERE ((beers.creator_id = 3 OR beers.recipient_id = 3) AND beers."id" = 5) LIMIT 1
+
+Hammock uses Beer.read_scope_for on #show, and write_scope_for on #edit, #update and #destroy. These scopes can be accessed as above through Beer.readable_by(account) and Beer.writeable_by(account). This eliminates authorization checks from the action, because if the ID of a Beer is provided that the user doesn't have access to it will fall outside the scope and will not be found in the DB at all.
+
+- They are used to discover credentials for already-queried ActiveRecord objects, without touching the database again. Just as Beer.readable_by(account) returns the set of Beer records whose existence can be known by account, @beer.readable_by?(account) returns true iff @beer's existence can be known by account. This is employed by hamlink_to.
+
+These three uses of the scope, plus another as-yet unimplemented bit, provide the entire security model of the application.
+
+== THE MASTER PLAN
+
+Lots of functionality is planned that will take this much further.
+
+
+

data/Rakefile

@@ -0,0 +1,27 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/hammock'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('hammock', Hammock::VERSION) do |p|
+  p.developer('Ben Hoskings', 'ben@hoskings.net')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.rubyforge_name       = p.name
+  p.extra_deps         = [
+    ['benhoskings-ambitious-activerecord','>= 0.1.3.4'],
+  ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]

data/lib/hammock.rb

@@ -0,0 +1,25 @@
+gem 'benhoskings-ambition'
+gem 'benhoskings-ambitious-activerecord'
+require 'ambition'
+require 'ambition/adapters/active_record'
+
+Dir.glob("#{File.dirname __FILE__}/hammock/**/*.rb").each {|dep|
+  require dep
+} if defined?(RAILS_ROOT) # Loading Hammock components under 'rake package' fails.
+
+module Hammock
+  VERSION = '0.2.4'
+
+  def self.included base # :nodoc:
+    Hammock.constants.map {|constant_name|
+      Hammock.const_get constant_name
+    }.select {|constant|
+      constant.is_a? Module
+    }.partition {|mod|
+      mod.constants.include?('LoadFirst') && mod::LoadFirst
+    }.flatten.each {|mod|
+      target = mod.constants.include?('MixInto') ? mod::MixInto : base
+      target.send :include, mod
+    }
+  end
+end

data/lib/hammock/ajaxinate.rb

@@ -0,0 +1,152 @@
+module Hammock
+  module Ajaxinate
+    MixInto = ActionView::Base
+    
+    def self.included base # :nodoc:
+      base.send :include, InstanceMethods
+      base.send :extend, ClassMethods
+    end
+
+    module ClassMethods
+    end
+
+    module InstanceMethods
+
+      def ajax_button verb, record, opts = {}
+        ajax_link verb, record, opts.merge(:class => [opts[:class], 'button'].squash.join(' '))
+      end
+
+      def ajax_link verb, record, opts = {}
+        if can_verb_entity?(verb, record)
+          route = ajaxinate verb, record, opts
+
+          content_tag :a,
+            opts[:text] || route.verb.to_s.capitalize,
+            :class => [opts[:class], link_class_for(route.verb, record)].squash.join(' '),
+            :href => route.path,
+            :onclick => 'return false;',
+            :style => opts[:style]
+        end
+      end
+
+      def ajaxinate verb, record, opts = {}
+        record_attributes = {record.base_model => record.unsaved_attributes}
+        link_params = {record.base_model => (opts.delete(:record) || {}) }.merge(opts[:params] || {})
+        route = route_for verb, record
+        attribute = link_params[:attribute]
+        link_class = link_class_for route.verb, record, attribute
+
+        link_params[:_method] = route.http_method
+        link_params[:format] = opts[:format].to_s
+
+        form_elements_hash = if route.get?
+          '{ }'
+        elsif attribute.blank?
+          "jQuery('form').serializeHash()"
+        else
+          "{ '#{record.base_model}[#{attribute}]': $('.#{link_class}').val() }"
+        end
+
+        response_action = case link_params[:format].to_s
+        when 'js'
+          "eval(response)"
+        else
+          "jQuery('.#{opts[:target] || link_class + '_target'}').before(response).remove()"
+        end
+
+        # TODO check the response code in the callback, and replace :after with :success and :failure.
+        js = %Q{
+          jQuery('.#{link_class}').#{opts[:on] || 'click'}(function() {
+            /*if (#{attribute.blank? ? 'false' : 'true'} && (jQuery('.#{link_class}_target .original_value').html() == jQuery('.#{link_class}_target .modify input').val())) {
+              eval("#{clean_snippet opts[:skipped]}");
+            } else*/ if (false == eval("#{clean_snippet opts[:before]}")) {
+              // before callback failed
+            } else { // fire the request
+              jQuery.#{route.fake_http_method}(
+                '#{route.path}',
+                jQuery.extend(
+                  #{record_attributes.to_flattened_json},
+                  #{form_elements_hash},
+                  #{link_params.to_flattened_json},
+                  #{forgery_key_json(route.http_method)}
+                ),
+                function(response) {
+                  #{response_action};
+                  eval("#{clean_snippet opts[:after]}");
+                }
+              );
+            }
+          });
+        }
+
+        append_javascript js
+        route
+      end
+      
+      def status_callback
+        %Q{
+          if ('success' == textStatus) {
+            jQuery('.success', jQuery('#' + jQuery(data).attr("id"))).show().fadeOut(4000);
+          } else {
+            jQuery('.statuses .failure', obj).hide();
+            jQuery('.statuses .failure', obj).show().parents('obj').BlindUp();
+          }
+        }
+      end
+
+      def jquery_xhr verb, record, opts = {}
+        route = route_for verb, record
+        params = if opts[:params].is_a?(String)
+          opts[:params].chomp(',').start_with('{').end_with('}')
+        else
+          (opts[:params] || {}).merge(record.base_model => (opts[:record] || {})).to_flattened_json
+        end
+
+        response_action = case opts[:format].to_s
+        when 'js'
+          "eval(data);"
+        else
+          "obj.replaceWith(data);"
+        end
+
+        %Q{
+          jQuery('.spinner', obj).show();
+
+          jQuery.#{route.fake_http_method}(
+            '#{route.path}',
+            jQuery.extend(
+              #{params},
+              {format: '#{opts[:format] || 'html'}', _method: '#{route.http_method}'},
+              #{forgery_key_json(route.http_method)}
+            ),
+            function(data, textStatus) {
+              #{response_action}
+              #{status_callback}
+              #{(opts[:callback] || '').end_with(';')}
+            }
+          );
+        }
+      end
+
+      private
+
+      def link_class_for verb, record, attribute = nil
+        [verb, record.base_model, record.id, attribute].compact.join('_')
+      end
+
+      def clean_snippet snippet
+        report "Double quote detected in snippet '#{snippet}'" if snippet['"'] unless snippet.nil?
+        (snippet || '').gsub("\n", '\n').end_with(';')
+      end
+
+      def forgery_key_json request_method = nil
+        if !protect_against_forgery? || (:get == (request_method || request.method))
+          '{ }'
+        else
+          "{ '#{request_forgery_protection_token}': encodeURIComponent('#{escape_javascript(form_authenticity_token)}') }"
+        end
+      end
+
+    end
+  end
+end

data/lib/hammock/callbacks.rb

@@ -0,0 +1,107 @@
+module Hammock
+  module Callbacks
+    LoadFirst = true
+
+    def self.included base # :nodoc:
+      base.send :include, InstanceMethods
+      base.send :extend, ClassMethods
+
+      base.class_eval {
+        include ActiveSupport::Callbacks
+
+        define_hammock_callbacks *%w[
+          before_find      during_find     after_failed_find
+
+          before_index     before_show
+          before_modify    before_new      before_edit
+
+          before_save      after_save      after_failed_save
+          before_create    after_create    after_failed_create
+          before_update    after_update    after_failed_update
+          before_destroy   after_destroy
+          before_undestroy after_undestroy
+
+          before_suggest   after_suggest
+        ]
+      }
+    end
+
+    module ClassMethods
+
+      class HammockCallback < ActiveSupport::Callbacks::Callback
+        private
+
+        def evaluate_method method, *args, &block
+          if method.is_a? Proc
+            # puts "was a HammockCallback proc within #{args.first.class}."
+            method.bind(args.shift).call(*args, &block)
+          else
+            super
+          end
+        end
+      end
+
+      def define_hammock_callbacks *callbacks
+        callbacks.each do |callback|
+          class_eval <<-"end_eval"
+            def self.#{callback}(*methods, &block)
+              callbacks = if !block_given? || methods.length > 1
+                CallbackChain.build(:#{callback}, *methods, &block)
+              else # hammock-style callback
+                if methods.empty?
+                  log "<-- you should give this callback a description", :skip => 1
+                elsif !methods.first.is_a?(String)
+                  raise ArgumentError, "Inline callback definitions require a description as their sole argument."
+                else
+                  # logger.info "defining \#{methods.first} on \#{name} with method \#{block.inspect}."
+                  [HammockCallback.new(:#{callback}, block, :identifier => methods.first)]
+                end || []
+              end
+              # log callbacks
+              (@#{callback}_callbacks ||= CallbackChain.new).concat callbacks
+            end
+
+            def self.#{callback}_callback_chain
+              @#{callback}_callbacks ||= CallbackChain.new
+
+              if superclass.respond_to?(:#{callback}_callback_chain)
+                CallbackChain.new(superclass.#{callback}_callback_chain + @#{callback}_callbacks)
+              else
+                @#{callback}_callbacks
+              end
+            end
+          end_eval
+        end
+      end
+
+    end
+
+    module InstanceMethods
+      private
+
+      CallbackFail = false
+
+      def callback kind, *args
+        callback_chain_for(kind).all? {|cb|
+          # dlog "Calling #{kind} callback #{cb.method}"
+          result = cb.call(self, *args) != CallbackFail
+          log "#{self.class}.#{cb.kind} callback '#{cb.method}' failed." unless result
+          result
+        }
+      end
+
+      def required_callback kind, *args
+        callback(kind, *args) if has_callbacks_for?(kind)
+      end
+
+      def has_callbacks_for? kind
+        !callback_chain_for(kind).empty?
+      end
+
+      def callback_chain_for kind
+        self.class.send "#{kind}_callback_chain"
+      end
+
+    end
+  end
+end