map_restfully 0.5.0

data/Gemfile

@@ -0,0 +1,9 @@
+source 'http://rubygems.org'
+
+gem 'rails', '~> 3.0.10'
+gem 'rack-test'
+
+group :development do
+  gem 'bundler', '~> 1.0.0'
+  gem 'jeweler', '~> 1.6.4'
+end

data/README.rdoc

@@ -0,0 +1,135 @@
+= map_restfully
+
+The map_restfully plugin creates a more RESTful controller than the default in Rails. This facilitates 
+applications that are much closer to the architectural style REST, which leads to performance and convention 
+advantages.
+
+== Example
+
+In your routes.rb file, simply add:
+
+  map_restfully :chair
+
+where 'chair' is the name of your resource.
+
+This will automatically provide routes and named path helpers for GETS, POSTS, PUTS, DELETES, GET, POST, PUT, DELETE. 
+The grammatical number corresponds to the url generated and the path helpers.
+
+Using the above example, we have the following.
+*convenience helper*                     \*example paths*                                      \*controller method*
+chair_path(@chair)                       \chair, chair.html, chair/1, chair/1.html             \ChairsController#get
+chair_path(@chair, :method => :post)     \chair, chair.xml, chair/1, chair/1.xml               \ChairsController#post
+chair_path(@chair, :method => :put)      \chair, chair.js, chair/1, chair/1.js                 \ChairsController#put
+chair_path(@chair, :method => :delete)   \chair, chair.html, chair/1, chair/1.html             \ChairsController#delete
+chairs_path(@chairs)                     \chairs, chairs.html, chairs/1,2,3, chairs/1,2,3.html \ChairsController#gets
+chairs_path(@chairs, :method => :post)   \chairs, chairs.xml, chairs/1,2,3, chairs/1,2,3.xml   \ChairsController#posts
+chairs_path(@chairs, :method => :put)    \chairs, chairs.js, chairs/1,2,3, chairs/1,2,3.js     \ChairsController#puts
+chairs_path(@chairs, :method => :delete) \chairs, chairs.html, chairs/1,2,3, chairs/1,2,3.html \ChairsController#deletes
+Note the ‘s’ on the end of the controller method names in the plural case. The above are only examples. The paths take 
+the usual formats .xml, .js, etc. The id number in the singular case and the ids in the plural case are optional. 
+
+
+== Rationale
+
+When Rails began flirting with ‘RESTful’ resources, there wasn’t much RESTful about Rails’ implementation other than 
+an added conversion layer between REST verbs and the default Rails actions. Those actions are Index (formerly List), 
+Show, New, Edit, Create, Update, and Destroy. We take the position that this added conversion layer is both 
+unnecessary and counter-productive.
+
+We have demonstrated that this conversion layer, the current implementation of map.resource, is unnecessary 
+in this plugin. We suggest that the current implementation in Rails is counter-productive, for the reasons elaborated below.
+
+== Breaking the Origin Barrier
+
+RESTful architecture provides scalability and fault-tolerance in a network application. A default Rails 
+implementation overrides this with the response header “Cach-Control: private, max-age=0, must-revalidate.” 
+This tells every node between the server and the client that every request requires the entire page 
+to be sent on each request.
+
+Imagine a situation where the index page to your site fairly static. Rather than sending the header above, 
+the server responds to the root request with “Cach-Control: max-age=28800.” Boom. What was that sound? 
+That was sound of your index page being served so fast that it moved faster than your server can spit 
+the bits out. Let’s call it ‘Breaking the Origin Barrier.’
+
+Your Rails web site now responds much faster, because the client web browser knows not to bother the 
+origin server if 8 hours haven’t passed since the last time you looked at the index page. Client-side 
+caching is the best possible performance solution in applications that transfer state representations 
+across a network.
+
+The next-best performance solution is if an intermediate server caches the web page. You now have that 
+advantage as well. Any caching servers set up between the origin server and the clients requesting that 
+resource (the index page) won’t bother passing the request along and waiting for a response. Instead, 
+they will simply and quickly reply with the cached page.
+
+As you can see, this could drastically decrease your server load and bandwidth needs. This is how HTTP 
+was designed to work. This is one benefit of using a RESTful approach.
+
+To get this caching benefit, you could add ‘expires_in’ to the example above:
+
+  class ChairsController < ApplicationController
+    def gets
+      …code…
+      expires_in 8.hours, :private => false
+    end
+  end
+
+(Gets is the method that corresponds to the Index action in traditional Rails apps.) 
+
+== Tips
+
+Rails typically treated Show, New, and Edit actions as get requests. In our experience, we found that 
+the edit view was always redundant with either the Show or the New view, so we discard it. In many cases, 
+we find that a properly scoped controller would have a form behind HTTP_AUTH (the RESTful alternative to 
+sessions). We also found that the form helpers obviate the New view, since we can just call 
+@record.new_record? in the view if we need to distinguish. So rather than maintain show(), edit(), 
+and new(), we recommend combining edit() and new() into one get.html.* form.
+
+You can distinguish the editable representation of a resource either by the subject of the RESTful 
+sentence (normally the logged-in user), or by another parameter (like appending ?edit=true to the url). 
+In the former case we recommend putting the logged-in views and controllers under a separate namespace 
+in order to make it convenient to disable the caching for those GET requests. In the latter case you 
+can render a different template based on the presence of the edit parameter.
+
+In typical ActiveRecord implementations, the id starts with the integer 1 and increments with each 
+record created. We use the id number 0 to represent a new ActiveRecord instance. Using that convention, 
+we can obviate the separate view and controller method for New.
+
+== Contributing to map_restfully
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Turn Off Session
+
+If you adhere to strick RESTful principles, you can separate your application controller by the subject 
+of the request: “I get the book…” or “Anonymous gets the book…” In this example, you can see that the 
+former case has the subject “I,” which is sometimes stored in the session cookie. You will get a 
+significant performance boost by turning sessions off. If you cannot identify the subject via a URL 
+parameter, then you are probably dealing with an issue of authentication. Consider using HTTP 
+authentication. This will populate your parameters with a ‘user’ and ‘password’ on every request, 
+which is automatically handled by the client web browser.
+
+To turn off sessions, change the following default line in config/environment.rb from:
+
+  config.action_controller.session = {
+    :session_key => '_dummy_session',
+    :secret      => 'someveryveryverylooooooooongrandomstring'
+  }
+
+to:
+
+  config.action_controller.session = false
+
+And remove the following line in ‘app/controllers/application.rb’:
+
+  protect_from_forgery #:secret => 'somerandomstring
+
+== Copyright
+
+Copyright (c) 2011 CLR. See LICENSE.txt for
+further details.

data/Rakefile

@@ -0,0 +1,35 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "map_restfully"
+  gem.homepage = "http://github.com/clr/map_restfully"
+  gem.license = "MIT"
+  gem.summary = %Q{Provide HTTP-verb style routing to Rails.}
+  gem.description = %Q{Convenience method to provide controller actions that correspond to the HTTP verbs.}
+  gem.email = "clr@port49.com"
+  gem.authors = ["CLR"]
+  gem.add_dependency 'rails', '~> 3.0.10'
+  gem.add_dependency 'rack-test'
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+0.5.0

data/lib/map_restfully.rb

@@ -0,0 +1,17 @@
+module ActionDispatch
+  module Routing
+    class Mapper
+      module MapRestfully
+        def map_restfully(resource_name, options={})
+          singular = resource_name.to_s
+          plural = options[:plural] || singular.pluralize
+          %w(get post put delete).each do |verb|
+            match({"#{singular}(/:id(.:format))" => "#{plural}##{verb}", :via => verb, :as => singular}.merge(options))
+            match "#{plural}(/:ids(.:format))" => "#{plural}##{verb}s", :via => verb, :as => plural
+          end
+        end
+      end
+      include MapRestfully
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,69 @@
+require 'rubygems'
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
+require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE'])
+
+require "action_controller/railtie"
+require "rails/test_unit/railtie"
+require 'rails/test_help'
+require File.expand_path('../../lib/map_restfully', __FILE__)
+
+module Test
+  class Application < Rails::Application
+  end
+end
+Test::Application.config.secret_token = ("testingframework" * 2)
+
+def app
+  Test::Application.routes.draw do
+    map_restfully :chair
+    match("/url" => "controller#action", :as => :nothing)
+  end
+  Test::Application
+end
+
+# helper for a common assertion
+def assert_ok
+  assert last_response.ok?, "Response was not ok: #{last_response.status}"
+end
+
+# helper for looping through the HTTP verbs
+def each_http_verb(&block)
+  %w(GET POST PUT DELETE).each do |verb|
+    yield verb
+  end
+end
+
+class ChairsController < ActionController::Base
+  include Test::Application.routes.url_helpers
+
+  # singular actions
+  each_http_verb do |verb|
+    define_method verb.downcase.to_sym do
+      response = params[:id].nil? ? "new chair" : "chair number #{params[:id]}"
+      respond_to do |format|
+        format.html{render :text => "HTML #{verb} #{response}"}
+        format.js{  render :text => "JSON #{verb} #{response}"}
+      end
+    end
+  end
+  # plural actions
+  each_http_verb do |verb|
+    define_method "#{verb.downcase}s".to_sym do
+      response = params[:ids].nil? ? "all chairs" : "chairs numbered #{params[:ids].split(',').join(" and ")}"
+      respond_to do |format|
+        format.html{render :text => "HTML #{verb}S #{response}"}
+        format.js{  render :text => "JSON #{verb}S #{response}"}
+      end
+    end
+  end
+end
+
+class ActiveSupport::TestCase
+  # Setup all fixtures in test/fixtures/*.(yml|csv) for all tests in alphabetical order.
+  #
+  # Note: You'll currently still have to declare fixtures explicitly in integration tests
+  # -- they do not yet inherit this setting
+
+  # Add more helper methods to be used by all tests here...
+end

data/test/test_rack.rb

@@ -0,0 +1,54 @@
+require File.expand_path('../helper', __FILE__)
+require 'rack/test'
+
+class TestRack < ActiveSupport::TestCase
+  include Rack::Test::Methods
+
+  each_http_verb do |verb|
+    test "#{verb} request to singular resource" do
+      self.send(verb.downcase.to_sym, "/chair")
+      assert_ok
+      assert_equal "HTML #{verb} new chair", last_response.body
+    end
+  end
+
+  each_http_verb do |verb|
+    test "#{verb} request to singular resource by resources ID" do
+      self.send(verb.downcase.to_sym, "/chair/42")
+      assert_ok
+      assert_equal "HTML #{verb} chair number 42", last_response.body
+    end
+  end
+
+  each_http_verb do |verb|
+    test "#{verb} request to singular resource by resources ID in another format" do
+      self.send(verb.downcase.to_sym, "/chair/42.js")
+      assert_ok
+      assert_equal "JSON #{verb} chair number 42", last_response.body
+    end
+  end
+
+  each_http_verb do |verb|
+    test "#{verb} request to plural resource" do
+      self.send(verb.downcase.to_sym, "/chairs")
+      assert_ok
+      assert_equal "HTML #{verb}S all chairs", last_response.body
+    end
+  end
+
+  each_http_verb do |verb|
+    test "#{verb} request to plural resource by resources IDs" do
+      self.send(verb.downcase.to_sym, "/chairs/42,37")
+      assert_ok
+      assert_equal "HTML #{verb}S chairs numbered 42 and 37", last_response.body
+    end
+  end
+
+  each_http_verb do |verb|
+    test "#{verb} request to plural resource by resources IDs in another format" do
+      self.send(verb.downcase.to_sym, "/chairs/42,37.js")
+      assert_ok
+      assert_equal "JSON #{verb}S chairs numbered 42 and 37", last_response.body
+    end
+  end
+end

data/test/test_routes.rb

@@ -0,0 +1,23 @@
+require File.expand_path('../helper', __FILE__)
+
+class TestRoutes < ActiveSupport::TestCase
+
+  test "that a named routes exist for singular and plural resource" do
+    assert app.routes.named_routes[:chair].is_a?(ActionDispatch::Routing::Route),  "Singular named route not found."
+    assert app.routes.named_routes[:chairs].is_a?(ActionDispatch::Routing::Route), "Plural named route not found."
+  end
+
+  each_http_verb do |verb|
+    test "that a map exists in the router for #{verb} resource singular" do
+      assert saved_route = app.routes.routes.detect{|r| r.verb == verb && r.path == "/chair(/:id(.:format))"}, "Route not found for #{verb} resource"
+      assert_equal({:controller => 'chairs', :action => verb.downcase}, saved_route.requirements)
+    end
+  end
+
+  each_http_verb do |verb|
+    test "that a map exists in the router for #{verb} resource plural" do
+      assert saved_route = app.routes.routes.detect{|r| r.verb == verb && r.path == "/chairs(/:ids(.:format))"}, "Route not found for #{verb} resource"
+      assert_equal({:controller => 'chairs', :action => "#{verb.downcase}s"}, saved_route.requirements)
+    end
+  end
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: map_restfully
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+  prerelease: 
+platform: ruby
+authors:
+- CLR
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-19 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: &18942540 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.10
+  type: :runtime
+  prerelease: false
+  version_requirements: *18942540
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: &18941980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *18941980
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &18941480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *18941480
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: &18940980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.6.4
+  type: :development
+  prerelease: false
+  version_requirements: *18940980
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: &18940480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.10
+  type: :runtime
+  prerelease: false
+  version_requirements: *18940480
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: &18939960 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *18939960
+description: Convenience method to provide controller actions that correspond to the
+  HTTP verbs.
+email: clr@port49.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+files:
+- Gemfile
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/map_restfully.rb
+- test/helper.rb
+- test/test_rack.rb
+- test/test_routes.rb
+homepage: http://github.com/clr/map_restfully
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4251634958389231380
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Provide HTTP-verb style routing to Rails.
+test_files: []