described_routes 0.8.0 → 0.8.1

data/History.txt

@@ -1,3 +1,8 @@
+== 0.8.1 2009-08-03
+
+* Link headers on the described_routes ResourceTemplate(s) metadata served by the middleware
+* Fix gem manifest
+
 == 0.8.0 2009-08-01
 
 * Rails integration via Rack middleware!

data/Manifest.txt

@@ -6,6 +6,8 @@ README.rdoc
 Rakefile
 lib/described_routes.rb
 lib/described_routes/helpers/described_routes_helper.rb
+lib/described_routes/middleware/base.rb
+lib/described_routes/middleware/rails.rb
 lib/described_routes/rails_controller.rb
 lib/described_routes/rails_routes.rb
 lib/described_routes/rake_task_methods.rb
@@ -33,10 +35,6 @@ test_rails_app/config/initializers/described_routes.rb
 test_rails_app/config/initializers/new_rails_defaults.rb
 test_rails_app/config/initializers/session_store.rb
 test_rails_app/config/routes.rb
-test_rails_app/log/development.log
-test_rails_app/log/production.log
-test_rails_app/log/server.log
-test_rails_app/log/test.log
 test_rails_app/script/server
 test_rails_app/test/fixtures/build_time/described_routes.json
 test_rails_app/test/fixtures/build_time/described_routes.text

data/README.rdoc

@@ -176,7 +176,7 @@ JSON example (after pretty printing):
 
 A discovery protocol based on link headers is added automatically by the middleware (controller changes are no longer required).  This protocol is understood by <code>path-to</code> (enabling client APIs to be bootstrapped easily) and the link headers can be regarded as adding useful type information to resources.
 
-Regular resources are given a link header that points to that resource's <code>ResourceTemplate</code> metadata.  That in turn is given a link header that points to the </code>ResourceTemplates</code> metadata for the entire application.  The root resource has a link header that points to the  </code>ResourceTemplates</code> metadata directly.
+Regular resources are given a link header that points to that resource's <code>ResourceTemplate</code> metadata.  That in turn is given a link header that points to the <code>ResourceTemplates</code> metadata for the entire application.  The root resource has a link header that points to the  <code>ResourceTemplates</code> metadata directly.
 
 For further information on link headers, see the draft spec http://tools.ietf.org/id/draft-nottingham-http-link-header-06.txt and the <code>link_header</code> gem.
 

data/lib/described_routes.rb

@@ -2,5 +2,5 @@ require 'resource_template'
 
 module DescribedRoutes
   # rubygem version
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

data/lib/described_routes/middleware/base.rb

@@ -0,0 +1,218 @@
+require 'rack'
+require 'rack/request'
+require 'rack/respond_to'
+require 'link_header'
+
+module DescribedRoutes
+  module Middleware
+    #
+    # Abstract Rack middleware for described_routes.  It serves ResourceTemplate data at the configured descrbed_routes path and
+    # adds link headers to regular requests whose routing matches a ResourceTemplate.
+    #
+    # It must be customised to the web framework in use - override #get_resource_templates and #get_resource_routing.
+    #
+    class Base
+      include Rack::RespondTo
+      
+      # The default options parameter to #link_headers; controls which links appear in html link elements 
+      DEFAULT_OPTIONS = {
+        :describedby           => true,
+        :self                  => false,
+        :up                    => false,
+        :related               => false,
+        :registered_rels       => {'edit' => 'edit', 'up' => 'up'},
+        :described_routes_path => '/described_routes'
+      }
+      
+      def initialize(app, options={})
+        @app = app
+
+        @options = DEFAULT_OPTIONS.merge(options)
+        DEFAULT_OPTIONS.keys.each do |option|
+          instance_variable_set("@option_#{option}", @options[option])
+        end
+        
+        @inited = false
+      end
+      
+      #
+      # From the first request, initialize @root, @described_routes_uri and @resource_templates
+      #
+      def init_from_first_req(req)
+        raise "no request host" unless req.host
+        
+        @root = "http://#{req.host}"
+        @root += ":#{req.port}" if req.port && req.port != 80
+        @root += "#{script_name}" if req.script_name && !req.script_name.empty?
+      
+        @described_routes_uri = @root + @option_described_routes_path
+
+        @resource_templates = get_resource_templates(@root)
+        raise "get_resource_templates(#{@root.inspect}) failed; no resource templates!" unless @resource_templates
+
+        @inited = true
+      end
+
+      #
+      # Does nothing - override in framework-specific middleware to return the top level ResourceTemplates object
+      #
+      def get_resource_templates
+        nil
+      end
+      
+      #
+      # Does nothing - override in framwork-specific middleware to return the ResourceTemplate and params hash matching the
+      # request, otherwise a pair of nils
+      #
+      def get_resource_routing(req)
+        [nil, nil]
+      end
+
+      #
+      # Process a Rack request, either returning ResourceTemplate data fif the request matches the described_routes path,
+      # otherwise passing on the request the application and adding a link header to the response.
+      #
+      def call(env)
+        # puts "\n", "-" * 80, "\n", env.map{|k, v| "#{k} => #{v.inspect}"}
+
+        req = Rack::Request.new(env)
+        
+        init_from_first_req(req) unless @inited
+
+        if req.path =~ %r(^#{@option_described_routes_path}(/([^/.]+)?)?(\.([a-z]+))?)
+          serve_resource_template_data(req, $2, $3)
+        else
+          call_with_link_header(req)
+        end
+      end
+      
+      #
+      # Handles requests for ResourceTemplate data
+      #
+      def serve_resource_template_data(req, route_name, format)
+        if route_name   # /described_routes/{route_name}
+          resource_template = @resource_templates.all_by_name[route_name]
+          unless resource_template
+            return [404, {'Content-Type' => 'text/plain'}, ["No ResourceTemplate named #{route_name.inspect}"]]
+          end
+          target = resource_template
+          rel = "index" # link header will point to the site ResourceTemplates description
+        else
+          rel = "self"  # this is the site ResourceTemplates description
+          target = @resource_templates
+        end        
+        expanded = target.partial_expand(req.GET)
+        Rack::RespondTo.env = req.env
+        if format
+          # Format extension overrides any accept header
+          Rack::RespondTo.media_types = [Rack::Mime::MIME_TYPES[format]]
+        else
+          # Supported formats, .text preferred.  No html yet!
+          Rack::RespondTo.media_types = %w(.text .json .yaml .xml).map{|format| Rack::Mime::MIME_TYPES[format]}
+        end
+
+        body = respond_to do |format|
+          format.text {expanded.to_text}
+          format.json {expanded.to_json}
+          format.yaml {expanded.to_yaml}
+          format.xml  {expanded.to_xml(Builder::XmlMarkup.new(:indent => 2)).target!}
+        end
+
+        headers = {
+          'Link' => %Q(<#{@described_routes_uri}>; rel="#{rel}"; meta="ResourceTemplates"),
+          'Content-Type' => Rack::RespondTo.selected_media_type
+        }
+        
+        [200, headers, [body]]
+      end
+      
+      #
+      # Passes on a request to the application and adds a link header to the response
+      #
+      def call_with_link_header(req)
+        status, headers, body = @app.call(req.env)
+        
+        resource_template, params = get_resource_routing(req)
+        if resource_template
+          headers = headers.merge("Link" => make_link_header(resource_template, params, @root + req.fullpath).to_s)
+        end
+        
+        [status, headers, body]
+      end
+            
+      # Returns a LinkHeader object that represents the required links.
+      #
+      # Link relation types ("rel" attributes) will contain a standard type ('self', 'up', 'describedby') &/or an extension type
+      # in the form "described_route_url(name)#rel", using the name and rel of the resource template.
+      #
+      # The output is filtered by the options hash, with members :self, :describedby, :up, :related.
+      #
+      # TODO move this to ResourceTemplate
+      #
+      def make_link_header(resource_template, params, request_uri)
+        links = []
+
+        type_prefix = @described_routes_uri + '#'
+        #
+        # For the application's root, the link with rel="describedby" has meta="ResourceTemplates" and it refers to a list of all
+        # top level resource templates. Otherwise, rel="describedby" has meta="ResourceTemplate" and it refers to a single resource
+        # template (together with any descendants).
+        #
+        if resource_template.name == 'root'
+          described_by = @described_routes_uri
+          related = @resource_templates
+          meta = "ResourceTemplates"
+        else
+          described_by = @described_routes_uri + "/" + resource_template.name
+          related = resource_template.resource_templates
+          meta = "ResourceTemplate"
+        end
+
+        #
+        # Add any query parameters to the rel="describedby" link
+        #
+        if params.empty?
+          described_by_with_params = described_by
+        else
+          described_by_with_params = described_by + '?' + params.to_query
+        end
+
+        # data for rel="self"
+        links << LinkHeader::Link.new(request_uri, [['rel', 'self'], ['role', type_prefix + resource_template.name]]) if @option_self
+
+        # data for rel="described_by"
+        links << LinkHeader::Link.new(described_by_with_params, [['rel', 'describedby'], ['meta', meta]]) if @option_describedby
+
+        # data for rel="up"
+        # TODO move this to ResourceTemplate
+        if @option_up
+          if resource_template.parent
+            links << LinkHeader::Link.new(
+                        resource_template.parent.uri_for(params),
+                        [['rel', 'up'], ['role', type_prefix + resource_template.parent.name]])
+          elsif resource_template.name != 'root'
+            links << LinkHeader::Link.new(@root + '/', [['rel', 'up'], ['role', type_prefix + 'root']])
+          end
+        end
+
+        # data for rel="related"
+        if @option_related
+          related.expand_links(params).each do |l|
+            if l.name != resource_template.name
+              rel = l.rel || l.name
+              rels = [['rel', described_by + '#' + rel]]
+              if l.rel
+                registered_rel = @option_registered_rels[rel]
+                if registered_rel
+                  rels.unshift(['rel', registered_rel])
+                end
+              end
+              links << LinkHeader::Link.new(l.uri, rels + [['role', type_prefix + l.name]])
+            end
+          end
+        end
+        LinkHeader.new(links)
+      end
+    end
+  end
+end

data/lib/described_routes/middleware/rails.rb

@@ -0,0 +1,50 @@
+require 'described_routes/middleware/base'
+require 'described_routes/rails_routes'
+
+module DescribedRoutes
+  module Middleware
+    #
+    # Rack middleware that integrates described_routes with Rails.
+    #
+    # In your environment.rb, add
+    #   require "described_routes/middleware/rails"
+    # and include
+    #   config.middleware.use DescribedRoutes::Middleware::Rails
+    # inside your <code>Rails::Initializer.run do...end block</code>
+    #
+    # Your Rails application will then serve ResourceTemplate data at the configured descrbed_routes path (/described_routes by
+    # default and adds link headers to regular requests whose routing matches a ResourceTemplate.
+    #
+    class Rails < Base
+      #
+      # Get a ResourceTemplates object from Rails.  Override to suppress sensitive routes.
+      #
+      def get_resource_templates(root)
+        RailsRoutes.get_resource_templates(root)
+      end
+
+      #
+      # Returns a ResourceTemplate matching the request and its parameter hash, otherwise a pair of nils.  The parameter hash
+      # is normalized by removing 'controller' and 'action' members and renaming 'id' (when present) to something resource-specific. 
+      #
+      def get_resource_routing(req)
+        path_parameters  = req.env["action_controller.request.path_parameters"]
+        query_parameters = req.env["action_controller.request.query_parameters"]
+        
+        # Guess the route from the controller and action
+        controller_name, action_name = path_parameters["controller"], path_parameters["action"]
+        resource_template, id_name = @resource_templates.routing[[controller_name, action_name]]
+        
+        if resource_template
+          params = path_parameters.merge(query_parameters).except("action", "controller")
+          if id_name && params[:id]
+            params[id_name] = params.delete(:id)
+          end
+          [resource_template, params]
+        else
+          [nil, nil]
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: described_routes
 version: !ruby/object:Gem::Version 
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors: 
 - Mike Burrows
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-02 00:00:00 +01:00
+date: 2009-08-03 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -79,6 +79,8 @@ files:
 - Rakefile
 - lib/described_routes.rb
 - lib/described_routes/helpers/described_routes_helper.rb
+- lib/described_routes/middleware/base.rb
+- lib/described_routes/middleware/rails.rb
 - lib/described_routes/rails_controller.rb
 - lib/described_routes/rails_routes.rb
 - lib/described_routes/rake_task_methods.rb
@@ -106,10 +108,6 @@ files:
 - test_rails_app/config/initializers/new_rails_defaults.rb
 - test_rails_app/config/initializers/session_store.rb
 - test_rails_app/config/routes.rb
-- test_rails_app/log/development.log
-- test_rails_app/log/production.log
-- test_rails_app/log/server.log
-- test_rails_app/log/test.log
 - test_rails_app/script/server
 - test_rails_app/test/fixtures/build_time/described_routes.json
 - test_rails_app/test/fixtures/build_time/described_routes.text