reststop 0.1.0 → 0.2.0

data/lib/restr.rb

@@ -0,0 +1,126 @@
+require 'net/http'
+require 'net/https'
+require 'uri'
+require 'cgi'
+
+begin
+  require 'xml_simple'
+rescue LoadError
+  require 'rubygems'
+  require 'active_support'
+  begin
+  require 'xml_simple'
+  rescue LoadError
+    require 'xmlsimple'
+  end
+end
+
+
+# A very simple REST client, best explained by example:
+#
+#   # Retrieve a Kitten and print its name and colour
+#   kitten = Restr.get('http://example.com/kittens/1.xml')
+#   puts kitten['name']
+#   puts kitten['colour']
+#
+#   # Create a Kitten
+#   kitten = Restr.post('http://example.com/kittens.xml', 
+#     :name => 'batman', :colour => 'black')
+#
+#   # Update a Kitten
+#   kitten = Restr.put('http://example.com/kittens/1.xml', 
+#     :age => '6 months')
+#
+#   # Delete a Kitten :(
+#   kitten = Restr.delete('http://example.com/kittens/1.xml')
+#
+#   # Retrieve a list of Kittens
+#   kittens = Restr.get('http://example.com/kittens.xml')
+#
+# When the response to a Restr request has content type 'text/xml', the
+# response body will be parsed from XML into a nested Hash (using XmlSimple 
+# -- see http://xml-simple.rubyforge.org/). Otherwise the response is  
+# returned untouched, as a String.
+#
+# If the remote REST resource requires authentication (Restr only supports
+# HTTP Basic authentication, for now):
+#
+#   Restr.get('http://example.com/kittens/1.xml, {}, 
+#     {:username => 'foo', :password => 'bar'})
+#
+class Restr
+  @@log = nil
+  
+  def self.logger=(logger)
+    @@log = logger.dup
+    @@log.progname = self.name
+  end
+  
+  def self.method_missing(method, *args)
+    self.do(method, args[0], args[1] || {}, args[2])
+  end
+  
+  def self.do(method, url, params = {}, auth = nil)
+    uri = URI.parse(url)
+    params = {} unless params
+      
+    method_mod = method.to_s.downcase.capitalize
+    unless Net::HTTP.const_defined?(method_mod)
+      raise InvalidRequestMethod, 
+        "Callback method #{method.inspect} is not a valid HTTP request method."
+    end
+    
+    if method_mod == 'Get'
+      q = params.collect{|k,v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}"}.join("&")
+      if uri.query
+        uri.query += "&#{q}"
+      else
+        uri.query = q
+      end
+    end
+    
+    req = Net::HTTP.const_get(method_mod).new(uri.request_uri)
+    
+    
+    if auth
+      raise ArgumentError, 
+        "The `auth` parameter must be a Hash with a :username and :password value." unless 
+        auth.kind_of? Hash
+      req.basic_auth auth[:username] || auth['username'], auth[:password] || auth['password']
+    end
+    
+    unless method_mod == 'Get'
+      req.set_form_data(params, ';')
+    end
+    
+    @@log.debug("Sending #{method.inspect} request to #{url.inspect} with data #{params.inspect}"+
+        (auth ? " with authentication" : "")+".") if @@log
+ 
+    client = Net::HTTP.new(uri.host, uri.port)
+    client.use_ssl = (uri.scheme == 'https')
+    res = client.start do |http|
+      http.request(req)
+    end
+    
+    case res
+    when Net::HTTPSuccess
+      if res.content_type == 'text/xml'
+        @@log.debug("Got XML response.") if @@log
+        return XmlSimple.xml_in_string(res.body,
+          'forcearray'   => false,
+          'keeproot'     => false
+        )
+      else
+        @@log.debug("Got #{res.content_type.inspect} response.") if @@log
+        return res.body
+      end
+    else
+      $LAST_ERROR_BODY = res.body # FIXME: this is dumb
+      @@log.error("Got error resposne '#{res.message}(#{res.code})': #{$LAST_ERROR_BODY}") if @@log
+      res.error!      
+    end
+  end
+  
+  class InvalidRequestMethod < Exception
+  end
+end

data/lib/reststop.rb

@@ -1,34 +1,24 @@
+require 'camping'
+require 'reststop/version'
+
 #--
 # This file is part of Reststop.
 #
 # Reststop is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
+# it under the terms of the GNU Lesser General Public License as 
+# published by the Free Software Foundation; either version 3 of 
+# the License, or (at your option) any later version.
 #
 # Reststop is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 #
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# You should have received a copy of the GNU Lesser General Public 
+# License along with this program.  If not, see 
+# <http://www.gnu.org/licenses/>.
 #--
 
-
-module Reststop
-  unless const_defined? 'VERSION'
-  	module VERSION #:nodoc:
-      MAJOR = 0
-      MINOR = 1
-      TINY  = 0
-  
-      STRING = [MAJOR, MINOR, TINY].join('.')
-    end
-  end
-end
-
-
 # Extends and overrides Camping for convenient RESTfulness.
 #
 # Have a look at:
@@ -38,21 +28,55 @@ end
 #
 module Camping
   
-  # Override Camping's goes() mechanism so that we can add our stuff.
-  # ... there must be a saner way to do this >:|
+  # Overrides Camping's goes() mechanism so that we can add our stuff.
+  # ... there must be a saner way to do this? >:|
+  #
+  # Also modifies Camping's qsp() method to allow parsing of XML input data.
   #
   # FIXME: looks like this breaks auto-reloading when using the camping
   #        server for launching apps :(
   S2 = IO.read(__FILE__).gsub(/^  S2 = I.+$/,'') # :nodoc:
   class << self
-    alias_method :camping_goes, :goes 
+    # alias_method call is conditional only to make `rake package` happy
+    alias_method :camping_goes, :goes
     def goes(m) # :nodoc:
       camping_goes m
       eval S2.gsub('Camping', m.to_s), TOPLEVEL_BINDING
     end
   end
-  
-  # This override is stolen and slightly modified from the Camping mailing list;
+
+  # Overrides Camping's query parsing method so that XML input is parsed
+  # into @input as an object usable more or less in the same manner as
+  # a standard Hash input. 
+  #
+  # This is necessary for dealing with ActiveResource calls, since ActiveResource
+  # submits its POST and PUT data as XML instead of the standard CGI query
+  # string.
+  #
+  # The method automatically determines whether input is XML or standard
+  # CGI query and parses it accordingly.
+  def self.qsp(qs, d='&;', y=nil, z=H[])
+    if qs.kind_of?(String) && !qs.nil? && !qs.empty? && qs =~ /^<\?xml/
+      qxp(qs)
+    else  
+      m = proc {|_,o,n|o.u(n,&m)rescue([*o]<<n)}
+      (qs||'').
+          split(/[#{d}] */n).
+          inject((b,z=z,H[])[0]) { |h,p| k, v=un(p).split('=',2)
+              h.u(k.split(/[\]\[]+/).reverse.
+                  inject(y||v) { |x,i| H[i,x] },&m)
+          }
+    end
+  end
+
+  # Parse an XML query (input) into a Hash usable more or less
+  # the same way as a Camping's standard Hash input.
+  def self.qxp(qxml)
+    #xml = XmlSimple.xml_in_string(qxml, 'forcearray' => false)
+    H.new Hash.from_xml(qxml)
+  end
+
+  # This override is taken and slightly modified from the Camping mailing list;
   # it fakes PUT/DELETE HTTP methods, since many browsers don't support them.
   #
   # In your forms you will have to add:
@@ -73,12 +97,15 @@ module Camping
   # Overrides Camping's render method to add the ability to specify a format 
   # module when rendering a view.
   #
-  # Format is specified in one of three ways (in this order of precedence):
+  # The format can also be specified in other ways (shown in this order 
+  # of precedence):
   #
   #   # By providing a second parameter to render()
   #     (eg: <tt>render(:foo, :HTML)</tt>)
   #   # By setting the @format variable
   #   # By providing a 'format' parameter in the request (i.e. @input[:format])
+  #   # By adding a file-format extension to the url (e.g. /items.xml or 
+  #     /items/2.html).
   #
   # For example, you could have:
   #
@@ -116,6 +143,11 @@ module Camping
   #   # url is /foobar/1?format=RSS
   #   render(:foo) # render the RSS version of foo
   #
+  # or 
+  #
+  #   # url is /foobar/1.rss
+  #   render(:foo) # render the RSS version of foo
+  #
   # If no format is specified, render() will behave like it normally does in 
   # Camping, by looking for a matching view method directly
   # in the Views module.
@@ -128,18 +160,33 @@ module Camping
   #     module HTML
   #       # ... etc.
   #     end
-  #     default_format :XML
+  #     default_format :HTML
   #   end
   #
   def render(action, format = nil)
-    format ||= @format || @input[:format]
+    format ||= @format
     
     if format.nil?
+      begin
+        ct = CONTENT_TYPE
+      rescue NameError
+        ct = 'text/html'
+      end
+      @headers['Content-Type'] ||= ct
+      
       super(action)
     else
       m = Mab.new({}, self)
       mod = "Camping::Views::#{format.to_s}".constantize
       m.extend mod
+      
+      begin
+        ct = mod::CONTENT_TYPE
+      rescue NameError
+        ct = "text/#{format.to_s.downcase}"
+      end
+      @headers['Content-Type'] = ct
+      
       s = m.capture{m.send(action)}
       s = m.capture{send(:layout){s}} if /^_/!~a[0].to_s and m.respond_to?(:layout)
       s
@@ -166,8 +213,16 @@ module Camping
     end
   end
   
-  module Controllers
+  module Controllers 
     class << self
+      def read_format(input, env) #:nodoc:
+        if input[:format] && !input[:format].empty?
+          input[:format].upcase.intern
+        elsif env['PATH_INFO'] =~ /\.([a-z]+)$/
+          $~[1].upcase.intern
+        end
+      end
+      
       # Calling <tt>REST "<resource name>"</tt> creates a controller with the
       # appropriate routes and maps your REST methods to standard
       # Camping controller mehods. This is meant to be used in your Controllers
@@ -223,35 +278,167 @@ module Camping
       #       # ...
       #     end
       #   end
+      #
+      # Additionally, format-based routing is possible. For example to get 
+      # a list of kittens in XML format, place a GET call to /kittens.xml.
+      # See the documentation for the render() method for more info.
+      #
       def REST(r, options = {})
-        crud = R "#{options[:prefix]}/#{r}/(.+)", "#{options[:prefix]}/#{r}"
+        crud = R "#{options[:prefix]}/#{r}/([0-9a-zA-Z]+)/([a-z_]+)(?:\.[a-z]+)?",
+          "#{options[:prefix]}/#{r}/([0-9a-zA-Z]+)(?:\.[a-z]+)?",
+          "#{options[:prefix]}/#{r}/([a-z_]+)(?:\.[a-z]+)?",
+          "#{options[:prefix]}/#{r}(?:\.[a-z]+)?"
+          
         crud.module_eval do
+          meta_def(:restful?){true}
           
-          def get(id = nil) # :nodoc:
-            if id.nil? && @input[:id].nil?
-               list
+          $LOG.debug("Creating RESTful controller for #{r.inspect} using Reststop #{::Reststop::VERSION::STRING}") if $LOG
+          
+          def get(id_or_custom_action = nil, custom_action =  nil) # :nodoc:
+            id = @input[:id] if @input[:id]
+            
+            custom_action = @input[:action] if @input[:action]
+            
+            if self.methods.include? id_or_custom_action
+              custom_action ||= id_or_custom_action
+              id ||= nil
             else
-              read(id || @input[:id])
+              id ||= id_or_custom_action
+            end
+            
+            id = id.to_i if id && id =~ /^[0-9]+$/
+            
+            @format = Controllers.read_format(@input, @env)
+            
+            begin
+              if id.nil? && @input[:id].nil?
+                custom_action ? send(custom_action) : list
+              else
+                custom_action ? send(custom_action, id || @input[:id]) : read(id || @input[:id])
+              end
+            rescue NoMethodError => e
+              # FIXME: this is probably not a good way to do this, but we need to somehow differentiate
+              #        between 'no such route' vs. other NoMethodErrors
+              if e.message =~ /no such method/
+                return no_method(e)
+              else
+                raise e
+              end
+            rescue ActiveRecord::RecordNotFound => e
+              return not_found(e)
             end
           end
           
           
-          def post # :nodoc:
-            create
+          def post(custom_action = nil) # :nodoc:
+            @format = Controllers.read_format(@input, @env)
+            custom_action ? send(custom_action) : create
+          end
+          
+          
+          def put(id, custom_action = nil) # :nodoc:
+            id = id.to_i if id =~ /^[0-9]+$/
+            @format = Controllers.read_format(@input, @env)
+            custom_action ? send(custom_action, id || @input[:id]) : update(id || @input[:id])
           end
           
           
-          def put(id = nil) # :nodoc:
-            update(id || @input[:id])
+          def delete(id, custom_action = nil) # :nodoc:
+            id = id.to_i if id =~ /^[0-9]+$/
+            @format = Controllers.read_format(@input, @env)
+            custom_action ? send(custom_action, id || @input[:id]) : destroy(id || @input[:id])
+          end
+          
+          private
+          def _error(message, status_code = 500, e = nil)
+            @status = status_code
+            @message = message
+            begin
+              render "error_#{status_code}".intern
+            rescue NoMethodError
+              if @format.to_s == 'XML'
+                "<error code='#{status_code}'>#{@message}</error>"
+              else
+                out  = "<strong>#{@message}</strong>"
+                out += "<pre style='color: #bbb'><strong>#{e.class}: #{e}</strong>\n#{e.backtrace.join("\n")}</pre>" if e
+                out
+              end
+            end
           end
           
+          def no_method(e)
+            _error("No controller method responds to this route!", 501, e)
+          end
           
-          def delete(id = nil) # :nodoc:
-            destroy(id || @input[:id])
+          def not_found(e)
+            _error("Record not found!", 404, e)
           end
         end
         crud
       end
     end
   end
+
+  module Helpers
+    alias_method :_R, :R
+    
+    # Overrides Camping's routing helper to make it possible to route RESTful resources.
+    #
+    # Some usage examples:
+    #
+    #   R(Kittens)            # /kittens
+    #   R(Kittens, 'new')     # /kittens/new
+    #   R(Kittens, 1, 'meow') # /kittens/1/meow
+    #   R(@kitten)            # /kittens/1
+    #   R(@kitten, 'meow')    # /kittens/1/meow
+    #
+    # The current output format is retained, so if the current <tt>@format</tt> is <tt>:XML</tt>, 
+    # the URL will be /kittens/1.xml rather than /kittens/1.
+    #
+    # Note that your controller names might not be loaded if you're calling <tt>R</tt> inside a
+    # view module. In that case you should use the fully qualified name (i.e. Myapp::Controllers::Kittens)
+    # or include the Controllers module into your view module. 
+    def R(c, *g)
+      if Controllers.constants.include?(cl = c.class.name.split("::").last.pluralize)
+        path = "/#{cl.underscore}/#{c.id}"
+        path << ".#{@format.to_s.downcase}" if @format
+        path << "?#{g}" unless g.empty? # FIXME: undefined behaviour if there are multiple arguments left
+        self / path
+      elsif c.respond_to?(:restful?) && c.restful?
+        base = c.name.split("::").last.underscore
+        id = g.shift
+        action = g.shift
+        path = "/#{base}"
+        path << "/#{id}" if id
+        path << "/#{action}" if action
+        path << ".#{@format.to_s.downcase}" if @format 
+        path << "?#{g}" unless g.empty? # FIXME: undefined behaviour if there are multiple arguments left
+        self / path
+      else
+        _R(c, *g)
+      end
+    end
+  end
+
+end
+
+module Markaby
+  class Builder
+    # Modifies Markaby's 'form' generator so that if a 'method' parameter
+    # is supplied, a hidden '_method' input is automatically added. 
+    def form(*args, &block)
+      options = args[0] if args && args[0] && args[0].kind_of?(Hash)
+      inside = capture &block
+      
+      if options && options.has_key?(:method)
+        inside = input(:type => 'hidden', :name => '_method', :value => options[:method]) +
+          inside
+        if options[:method].to_s === 'put' || options[:method].to_s == 'delete'
+          options[:method] = 'post'
+        end
+      end
+      
+      tag!(:form, options || args[0]) {inside}
+    end
+  end
 end