RubyGems - path-to - Versions diffs - 0.5.1 → 0.6.0 - Mend

path-to 0.5.1 → 0.6.0

Files changed (9) hide show

data/History.txt +4 -0
data/README.rdoc +29 -26
data/Rakefile +19 -14
data/lib/path-to.rb +1 -1
data/lib/path-to/application.rb +1 -1
data/lib/path-to/described_routes.rb +55 -0
data/lib/path-to/http_client.rb +19 -0
data/test/path-to/test_described_routes.rb +18 -0
metadata +21 -12

data/History.txt CHANGED

@@ -1,3 +1,7 @@
+== 0.6.0 2009-05-25
+* Application discovery via link headers
 == 0.5.1 2009-05-25
 * More ResourceTemplate refactoring

data/README.rdoc CHANGED

@@ -1,45 +1,48 @@
 = path-to README
-Model web apps easily and access them via nice app-specific Ruby APIs.
-Note to reader: You are invited to comment on the roadmap at http://positiveincline.com/?p=213
-== Description
-path-to allows web applications to be modelled via URI templates and then accessed through an application-specific Ruby API.  It is designed to be extended easily to support discovery mechanisms; included is an implementation based on the resource templates of described_routes.
+Model web apps easily and access them via nice app-specific Ruby APIs on the client side.  For suitably-configured servers (e.g. those using described_routes), path-to applications can bootstrap themselves from the address of any resource in the target application.
 == Synopsis
 === Automatic configuration with described_routes
-Create a client application configured from a server that supports described_routes:
+Create a client application for a web app that supports the described_routes discovery protocol:
   require 'path-to/described_routes'
+  app = PathTo::DescribedRoutes::Application.discover('http://example.com')
-  app = PathTo::DescribedRoutes::Application.new(:json => Net::HTTP.get(URI.parse("http://example.com/described_routes.json")))
+Or create one from a <code>ResourceTemplate</code> description in JSON or YAML found at some known place, preferable on the server.  This could be generated and served by the Rails controller provided by <code>described_routes</code> or perhaps hand-crafted and configured statically:
+  require 'path-to/described_routes'
+  app = PathTo::DescribedRoutes::Application.new(:json => Net::HTTP.get(URI.parse('http://example.com/described_routes.json')))
-  app.users["dojo"].articles.recent
+The <code>app</code> object then automatically supports an API that reflects the structure of the web application, for example:
+  app.users['dojo'].articles.recent
   #=> http://example.com/users/dojo/articles/recent
-  app.users["dojo"].articles.recent.get
-  #=> "<html>...</html>"
+  app.users['dojo'].articles.recent.get
+  #=> '<html>...</html>'
-  app.users["dojo"].articles.recent["format" => "json"]
+  app.users['dojo'].articles.recent['format' => 'json']
   #=> http://example.com/users/dojo/articles/recent.json
-  app.users["dojo"].articles.recent.get
+  app.users['dojo'].articles.recent.get
   #=> [...]
+The API objects include the <code>#get</code>, <code>#put</code>, <code>#post</code> and <code>#delete</code> of HTTParty (or other HTTP client provided at initialization). Alternatively you can use their <code>#uri</code> or <code>#path</code> methods with an un-integrated HTTP client:
+  your_favourite_http_client.get app.users['dojo'].articles.recent.uri
+  #=> '<html>...</html>'
-See examples/delicious.rb for an example based on a partial YAML-based description of the Delicious API.
-=== Local configuration
+=== Local configuration - using path-to without described_routes
-   require "path-to"
+   require 'path-to'
    class Users    < PathTo::Path ; end
    class Articles < PathTo::Path ; end
    app = Application.new(
-       :users    => "http://example.com/users/{user}",
-       :articles => "http://example.com/users/{user}/articles/{slug}") do |app|
+       :users    => 'http://example.com/users/{user}',
+       :articles => 'http://example.com/users/{user}/articles/{slug}') do |app|
      def app.child_class_for(instance, method, params)
        {
          :users    => Users,
@@ -56,19 +59,19 @@ app.articles cause objects of the appropriate class to be generated.  These in t
 params, like this:
    app.users                                                   #=> http://example.com/users/ <Users>
-   app.users(:user => "dojo")                                  #=> http://example.com/users/dojo <Users>
-   app.users[:user => "dojo"]                                  #=> http://example.com/users/dojo <Users>
-   app.articles(:user => "dojo", :slug => "my-article")        #=> http://example.com/users/dojo/articles/my-article <Articles>
-   app.users[:user => "dojo"].articles[:slug => "my-article"]  #=> http://example.com/users/dojo/articles/my-article <Articles>
+   app.users(:user => 'dojo')                                  #=> http://example.com/users/dojo <Users>
+   app.users[:user => 'dojo']                                  #=> http://example.com/users/dojo <Users>
+   app.articles(:user => 'dojo', :slug => 'my-article')        #=> http://example.com/users/dojo/articles/my-article <Articles>
+   app.users[:user => 'dojo'].articles[:slug => 'my-article']  #=> http://example.com/users/dojo/articles/my-article <Articles>
 With a little more work (overriding Users#[] and Articles#[] - as described in the documentation for the Path class), the last example
 becomes simply:
-  app.users["dojo"].articles["my-article"]                     #=> http://example.com/users/dojo/articles/my-article <Articles>
+  app.users['dojo'].articles['my-article']                     #=> http://example.com/users/dojo/articles/my-article <Articles>
 HTTP support comes courtesy of HTTParty (the Path class includes it).  To GET an article in the above example, just invoke the get method on the path object:
-  app.users["dojo"].articles["my-article"].get                 #=> "<html>...</html>"
+  app.users['dojo'].articles['my-article'].get                 #=> '<html>...</html>'
 == Installation

data/Rakefile CHANGED

@@ -1,28 +1,33 @@
-%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+%w[rubygems rake rake/clean fileutils newgem rubigen hoe].each { |f| require f }
 $:.push File.dirname(__FILE__) + '/lib'
 require 'path-to'
 # Generate all the Rake tasks
 # Run 'rake -T' to see list of generated tasks (from gem root directory)
-$hoe = Hoe.new('path-to', PathTo::VERSION) do |p|
-  p.developer('Mike Burrows (asplake)', 'mjb@asplake.co.uk')
-  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
-  p.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
-  p.rubyforge_name       = p.name
-  p.url = 'http://positiveincline.com/?p=213'
-  p.extra_deps         = [
+$hoe = Hoe.spec 'path-to' do
+  developer('Mike Burrows', 'mjb@asplake.co.uk')
+  self.version = PathTo::VERSION
+  self.readme_file          = "README.rdoc"
+  self.summary = self.description              = paragraphs_of(self.readme_file, 1..1).join("\n\n")
+  self.changes              = paragraphs_of("History.txt", 0..1).join("\n\n")
+  self.rubyforge_name       = 'path-to'
+  self.url = 'http://github.com/asplake/path-to/tree'
+  self.extra_deps         = [
+  ]
+  self.extra_deps         = [
     ['httparty','>= 0.4.2'],
     ['addressable','>= 2.1.0'],
-    ['described_routes','>= 0.5.0']
+    ['described_routes','>= 0.6.0'],
+    ['link_header','>= 0.0.4']
   ]
-  p.extra_dev_deps = [
+  self.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'
+  self.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (rubyforge_name == name) ? rubyforge_name : "\#{rubyforge_name}/\#{name}"
+  self.remote_rdoc_dir = File.join(path.gsub(/^#{rubyforge_name}\/?/,''), 'rdoc')
+  self.rsync_args = '-av --delete --ignore-errors'
 end
 task :info do

data/lib/path-to.rb CHANGED

@@ -1,5 +1,5 @@
 module PathTo
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end
 $:.push File.dirname(__FILE__)

data/lib/path-to/application.rb CHANGED

@@ -1,6 +1,7 @@
 require "path-to/path"
 require "path-to/http_client"
 require "addressable/template"
+require "net/http"
 module PathTo
   #
@@ -115,7 +116,6 @@ module PathTo
     # TODO Consider taking an instance as the first parameter, as #child_class_for does
     #
     def uri_for(method, params = {})
-      # TODO it's a 1-line fix to Addressable to permit symbols (etc) as keys
       if (t = uri_template_for(method, params))
         string_keyed_params = params.keys.inject({}){|hash, key| hash[key.to_s] = params[key]; hash}
         Addressable::Template.new(t).expand(string_keyed_params).to_s

data/lib/path-to/described_routes.rb CHANGED

@@ -1,11 +1,19 @@
 require "path-to"
 require "described_routes"
+require "link_header"
 module PathTo
   #
   # Application and Path implementations for DescribedRoutes, each resource described by a ResourceTemplate
   #
   module DescribedRoutes
+    #
+    # Raised in the event of discovery protocol errors, e.g. responses other than 200 OK or missing headers.
+    # Low-level exceptions are NOT swallowed.
+    #
+    class ProtocolError < Exception
+    end
     #
     # Implements PathTo::Path, represents a resource described by a ResourceTemplate
     #
@@ -132,6 +140,53 @@ module PathTo
       # Hash of options to be included in HTTP method calls
       attr_reader :http_options
+      def self.discover(url, options={})
+        http_options = options[:http_options] || nil
+        default_type = options[:default_type] || Path
+        http_client  = options[:http_client]  || HTTPClient
+        metadata_link = self.discover_metadata_link(url, http_client)
+        unless metadata_link
+          raise ProtocolError.new("no metadata link found")
+        end
+        json = http_client.get(metadata_link.href, :format => :text, :headers => {"Accept" => "application/json"})
+        unless json
+          raise ProtocolError.new("no json found")
+        end
+        self.new(options.merge(:json => json))
+      end
+      def self.discover_metadata_link(url, http_client)
+        response = http_client.head(url, {"Accept" => "application/json"})
+        unless response.kind_of?(Net::HTTPOK)
+          raise ProtocolError.new("got response #{response.inspect} from #{url}")
+        end
+        link_header = LinkHeader.parse(response["Link"])
+        app_templates_link = link_header.find_link(["rel", "describedby"], ["meta", "ResourceTemplates"])
+        unless app_templates_link
+          resource_template_link = link_header.find_link(["rel", "describedby"], ["meta", "ResourceTemplate"])
+          if resource_template_link
+            response = http_client.head(resource_template_link.href, {"Accept" => "application/json"})
+            unless response.kind_of?(Net::HTTPOK)
+              raise ProtocolError.new("got response #{response.inspect} from #{url}")
+            end
+            link_header = LinkHeader.parse(response["Link"])
+            app_templates_link = link_header.find_link(["rel", "index"], ["meta", "ResourceTemplates"])
+            unless app_templates_link
+              raise ProtocolError.new("(2) couldn't find link with rel=\"index\" and meta=\"ResourceTemplates\" at #{resource_template_link.href}")
+            end
+          else
+            unless app_templates_link
+              raise ProtocolError.new("(1) couldn't find link with rel=\"described_by\" and meta=\"ResourceTemplates\" or meta=\"ResourceTemplate\" at #{url}")
+            end
+          end
+        end
+        app_templates_link
+      end
       def initialize(options)
         super(options[:parent], options[:service], options[:params])

data/lib/path-to/http_client.rb CHANGED

@@ -1,4 +1,5 @@
 require "httparty"
+require "uri"
 module PathTo
   #
@@ -10,5 +11,23 @@ module PathTo
   #
   class HTTPClient
     include HTTParty
+    Request::SupportedHTTPMethods.push(Net::HTTP::Head)
+    #
+    # HEAD request, returns some sort of NET::HTTPResponse
+    #
+    # A bit ugly and out of place this, but HTTParty doesn's support HEAD yet.
+    # (@jnunemaker@asplake there is a patch for head requests I need to pull in)
+    #
+    def self.head(uri_string, headers={})
+      uri = URI.parse(uri_string)
+      raise URI::InvalidURIError.new("#{uri_string.inspect} is not a valid http URI") unless uri.kind_of?(URI::HTTP) && uri.host
+      Net::HTTP.new(uri.host, uri.port).start do |http|
+        return http.request(Net::HTTP::Head.new(uri.request_uri, headers))
+      end
+    end
   end
 end

data/test/path-to/test_described_routes.rb CHANGED

@@ -127,4 +127,22 @@ class TestDescribedRoutes < Test::Unit::TestCase
     assert_equal(app, app_json.parent)
     assert_equal("http://localhost:3000/users.json", users_json.uri)
   end
+  def test_discover_with_empty_uri
+    assert_raise(URI::InvalidURIError) do
+      PathTo::DescribedRoutes::Application.discover("")
+    end
+  end
+  def test_discover_with_invalid_uri
+    assert_raise(URI::InvalidURIError) do
+      PathTo::DescribedRoutes::Application.discover("foo bar")
+    end
+  end
+  def test_discover_with_nonexistent_uri
+    assert_raise(PathTo::DescribedRoutes::ProtocolError) do
+      PathTo::DescribedRoutes::Application.discover("http://localhost/NONEXISTENT")
+    end
+  end
 end

metadata CHANGED

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: path-to
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
-- Mike Burrows (asplake)
+- Mike Burrows
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2009-05-25 00:00:00 +01:00
+date: 2009-07-27 00:00:00 +01:00
 default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
@@ -40,7 +40,17 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.5.0
+        version: 0.6.0
+    version:
+- !ruby/object:Gem::Dependency
+  name: link_header
+  type: :runtime
+  version_requirement:
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.4
     version:
 - !ruby/object:Gem::Dependency
   name: newgem
@@ -50,7 +60,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.4.1
+        version: 1.5.1
     version:
 - !ruby/object:Gem::Dependency
   name: hoe
@@ -60,9 +70,9 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.8.0
+        version: 2.3.2
     version:
-description: path-to allows web applications to be modelled via URI templates and then accessed through an application-specific Ruby API.  It is designed to be extended easily to support discovery mechanisms; included is an implementation based on the resource templates of described_routes.
+description: Model web apps easily and access them via nice app-specific Ruby APIs on the client side.  For suitably-configured servers (e.g. those using described_routes), path-to applications can bootstrap themselves from the address of any resource in the target application.
 email:
 - mjb@asplake.co.uk
 executables: []
@@ -73,7 +83,6 @@ extra_rdoc_files:
 - History.txt
 - Manifest.txt
 - PostInstall.txt
-- README.rdoc
 files:
 - History.txt
 - LICENSE
@@ -99,10 +108,10 @@ files:
 - test/path-to/test_with_params.rb
 - test/test_helper.rb
 has_rdoc: true
-homepage: http://positiveincline.com/?p=213
+homepage: http://github.com/asplake/path-to/tree
 licenses: []
-post_install_message: PostInstall.txt
+post_install_message:
 rdoc_options:
 - --main
 - README.rdoc
@@ -123,10 +132,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubyforge_project: path-to
-rubygems_version: 1.3.3
+rubygems_version: 1.3.5
 signing_key:
 specification_version: 3
-summary: path-to allows web applications to be modelled via URI templates and then accessed through an application-specific Ruby API
+summary: Model web apps easily and access them via nice app-specific Ruby APIs on the client side.  For suitably-configured servers (e.g. those using described_routes), path-to applications can bootstrap themselves from the address of any resource in the target application.
 test_files:
 - test/path-to/test_application.rb
 - test/path-to/test_described_routes.rb