atom-tools 1.0.0 → 2.0.0

data/lib/atom/http.rb

@@ -2,6 +2,8 @@ require "net/http"
 require "net/https"
 require "uri"
 
+require "atom/cache"
+
 require "sha1"
 require "digest/md5"
 
@@ -14,7 +16,7 @@ class String # :nodoc:
 end
 
 module Atom
-  UA = "atom-tools 1.0.0"
+  UA = "atom-tools 2.0.0"
 
   module DigestAuth
     CNONCE = Digest::MD5.hexdigest("%x" % (Time.now.to_i + rand(65535)))
@@ -66,8 +68,8 @@ module Atom
         response = kd(h(a1), params[:nonce] + ":" + h(a2))
       else
         @@nonce_count += 1
-        nc = ('%08x' % @@nonce_count) 
-   
+        nc = ('%08x' % @@nonce_count)
+
         # XXX auth-int
         data = "#{params[:nonce]}:#{nc}:#{CNONCE}:#{"auth"}:#{h(a2)}"
 
@@ -75,7 +77,7 @@ module Atom
       end
 
       header = %Q<Digest username="#{user}", uri="#{req.path}", realm="#{params[:realm]}", response="#{response}", nonce="#{params[:nonce]}">
-   
+
       if params[:opaque]
         header += %Q<, opaque="#{params[:opaque]}">
       end
@@ -105,7 +107,7 @@ module Atom
   #
   # This object can be used on its own, or passed to an Atom::Service,
   # Atom::Collection or Atom::Feed, where it will be used for requests.
-  # 
+  #
   # All its HTTP methods return a Net::HTTPResponse
   class HTTP
     include DigestAuth
@@ -116,14 +118,14 @@ module Atom
     # the token used for Google's AuthSub authentication
     attr_accessor :token
 
-    # when set to :basic, :wsse or :authsub, this will send an 
-    # Authentication header with every request instead of waiting for a 
-    # challenge from the server. 
-    # 
+    # when set to :basic, :wsse or :authsub, this will send an
+    # Authentication header with every request instead of waiting for a
+    # challenge from the server.
+    #
     # be careful; always_auth :basic will send your username and
     # password in plain text to every URL this object requests.
     #
-    # :digest won't work, since Digest authentication requires an 
+    # :digest won't work, since Digest authentication requires an
     # initial challenge to generate a response
     #
     # defaults to nil
@@ -136,7 +138,18 @@ module Atom
     # indicates to redirect a POST/PUT/DELETE
     attr_accessor :allow_all_redirects
 
-    def initialize # :nodoc:
+    # if set, 'cache' should be a directory for a disk cache, or an object
+    # with the same interface as Atom::FileCache
+    def initialize cache = nil
+      if cache.is_a? String
+        @cache = FileCache.new(cache)
+      elsif cache
+        @cache = cache
+      else
+        @cache = NilCache.new
+      end
+
+      # initialize default #when_auth
       @get_auth_details = lambda do |abs_url, realm|
         if @user and @pass
           [@user, @pass]
@@ -150,7 +163,7 @@ module Atom
     def get url, headers = {}
       http_request(url, Net::HTTP::Get, nil, headers)
     end
-  
+
     # POSTs body to an url
     def post url, body, headers = {}
       http_request(url, Net::HTTP::Post, body, headers)
@@ -236,7 +249,7 @@ module Atom
       now = Time.now.gmtime.iso8601
 
       digest = [Digest::SHA1.digest(nonce + now + pass)].pack("m").chomp
-      
+
       req['X-WSSE'] = %Q<UsernameToken Username="#{user}", PasswordDigest="#{digest}", Nonce="#{nonce_enc}", Created="#{now}">
       req["Authorization"] = 'WSSE profile="UsernameToken"'
     end
@@ -257,22 +270,46 @@ module Atom
     end
 
     # performs a generic HTTP request.
-    def http_request(url_s, method, body = nil, init_headers = {}, www_authenticate = nil, redirect_limit = 5)
-      req, url = new_request(url_s, method, init_headers)
-   
+    def http_request(url_s, method, body = nil, headers = {}, www_authenticate = nil, redirect_limit = 5)
+      cachekey = url_s.to_s
+
+      cached_value = @cache[cachekey]
+      if cached_value
+        sock = Net::BufferedIO.new(StringIO.new(cached_value))
+        info = Net::HTTPResponse.read_new(sock)
+        info.reading_body(sock, true) {}
+
+        if method == Net::HTTP::Put and info.key? 'etag' and not headers['If-Match']
+          headers['If-Match'] = info['etag']
+        end
+      end
+
+      if cached_value and not [Net::HTTP::Get, Net::HTTP::Head].member? method
+        @cache.delete(cachekey)
+      elsif cached_value
+        entry_disposition = _entry_disposition(info, headers)
+
+        if entry_disposition == :FRESH
+          info.extend Atom::HTTPResponse
+
+          return info
+        elsif entry_disposition == :STALE
+          if info.key? 'etag' and not headers['If-None-Match']
+            headers['If-None-Match'] = info['etag']
+          end
+          if info.key? 'last-modified' and not headers['Last-Modified']
+            headers['If-Modified-Since'] = info['last-modified']
+          end
+        end
+      end
+
+      req, url = new_request(url_s, method, headers)
+
       # two reasons to authenticate;
       if @always_auth
         self.send("#{@always_auth}_authenticate", req, url)
       elsif www_authenticate
-        # XXX multiple challenges, multiple headers
-        param_string = www_authenticate.sub!(/^(\w+) /, "")
-        auth_method = ($~[1].downcase + "_authenticate").to_sym
-
-        if self.respond_to? auth_method, true # includes private methods
-          self.send(auth_method, req, url, param_string)
-        else
-          raise "No support for #{$~[1]} authentication"
-        end
+        dispatch_authorization www_authenticate, req, url
       end
 
       http_obj = Net::HTTP.new(url.host, url.port)
@@ -282,47 +319,82 @@ module Atom
         h.request(req, body)
       end
 
+      # a bit of added convenience
+      res.extend Atom::HTTPResponse
+
       case res
       when Net::HTTPUnauthorized
-        if @always_auth or www_authenticate or not res["WWW-Authenticate"] # XXX and not stale (Digest only) 
+        if @always_auth or www_authenticate or not res["WWW-Authenticate"] # XXX and not stale (Digest only)
           # we've tried the credentials you gave us once
           # and failed, or the server gave us no way to fix it
           raise Unauthorized, "Your authorization was rejected"
         else
           # once more, with authentication
-          res = http_request(url_s, method, body, init_headers, res["WWW-Authenticate"])
+          res = http_request(url_s, method, body, headers, res["WWW-Authenticate"])
 
           if res.kind_of? Net::HTTPUnauthorized
             raise Unauthorized, "Your authorization was rejected"
           end
         end
       when Net::HTTPRedirection
-        if res["Location"] and (allow_all_redirects or [Net::HTTP::Get, Net::HTTP::Head].member? method)
+        if res.code == "304" and method == Net::HTTP::Get
+          res.end2end_headers.each { |k| info[k] = res[k] }
+
+          res = info
+
+          res["Content-Length"] = res.body.length
+
+          res.extend Atom::HTTPResponse
+
+          _updateCache(headers, res, @cache, cachekey)
+        elsif res["Location"] and (allow_all_redirects or [Net::HTTP::Get, Net::HTTP::Head].member? method)
           raise HTTPException, "Too many redirects" if redirect_limit.zero?
 
-          res = http_request res["Location"], method, body, init_headers, nil, (redirect_limit - 1)
+          res = http_request res["Location"], method, body, headers, nil, (redirect_limit - 1)
         end
+      when Net::HTTPOK, Net::HTTPNonAuthoritativeInformation
+        unless res.key? 'Content-Location'
+          res['Content-Location'] = url_s
+        end
+        _updateCache(headers, res, @cache, cachekey)
       end
 
-      # a bit of added convenience
-      res.extend Atom::HTTPResponse
-
       res
     end
-    
+
     def new_request(url_string, method, init_headers = {})
       headers = { "User-Agent" => UA }.merge(init_headers)
-      
+
       url = url_string.to_uri
-       
+
       rel = url.path
       rel += "?" + url.query if url.query
 
       [method.new(rel, headers), url]
     end
+
+    def dispatch_authorization www_authenticate, req, url
+      param_string = www_authenticate.sub(/^(\w+) /, "")
+      auth_method = ($~[1].downcase + "_authenticate").to_sym
+
+      if self.respond_to? auth_method, true # includes private methods
+        self.send(auth_method, req, url, param_string)
+      else
+        # didn't support the first offered, find the next header
+        next_to_try = www_authenticate.sub(/.* ([\w]+ )/, '\1')
+        if next_to_try == www_authenticate
+          # this was the last WWW-Authenticate header
+          raise Atom::Unauthorized, "No support for offered authentication types"
+        else
+          dispatch_authorization next_to_try, req, url
+        end
+      end
+    end
   end
 
   module HTTPResponse
+    HOP_BY_HOP = ['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailers', 'transfer-encoding', 'upgrade']
+
     # this should probably support ranges (eg. text/*)
     def validate_content_type( valid )
       raise Atom::HTTPException, "HTTP response contains no Content-Type!" if not self.content_type or self.content_type.empty?
@@ -333,5 +405,13 @@ module Atom
         raise Atom::WrongMimetype, "unexpected response Content-Type: #{media_type.inspect}. should be one of: #{valid.inspect}"
       end
     end
+
+    def end2end_headers
+      hopbyhop = HOP_BY_HOP
+      if self['connection']
+        hopbyhop += self['connection'].split(',').map { |x| x.strip }
+      end
+      @header.keys.reject { |x| hopbyhop.member? x.downcase }
+    end
   end
 end

data/lib/atom/service.rb

@@ -5,98 +5,28 @@ require "atom/element"
 require "atom/collection"
 
 module Atom
+  class AutodiscoveryFailure < RuntimeError; end
+
   # an Atom::Workspace has a #title (Atom::Text) and #collections, an Array of Atom::Collection s
   class Workspace < Atom::Element
-    element :collections, Atom::Multiple(Atom::Collection)
-    element :title, Atom::Text
-
-    def self.parse(xml, base = "", http = Atom::HTTP.new) # :nodoc:
-      ws = Atom::Workspace.new("workspace")
-
-      rxml = if xml.is_a? REXML::Document
-        xml.root
-      elsif xml.is_a? REXML::Element
-        xml
-      else 
-        begin
-          REXML::Document.new(xml)
-        rescue REXML::ParseException
-          raise Atom::ParseError
-        end
-      end
-
-      xml.fill_text_construct(ws, "title")
-
-      REXML::XPath.match( rxml, 
-                          "./app:collection",
-                          {"app" => Atom::PP_NS} ).each do |col_el|
-        # absolutize relative URLs
-        url = base.to_uri + col_el.attributes["href"].to_uri
-       
-        coll = Atom::Collection.new(url, http)
-
-        col_el.fill_text_construct(coll, "title")
-
-        accepts = REXML::XPath.first( col_el,
-                                      "./app:accept",
-                                      {"app" => Atom::PP_NS} )
-
-        accepts = []
-        REXML::XPath.each(col_el, "./app:accept", {"app" => Atom::PP_NS}) do |a|
-          accepts << a.texts.join
-        end
-
-        coll.accepts = (accepts.empty? ? ["application/atom+xml;type=entry"] : accepts)
-        
-        ws.collections << coll
-      end
-
-      ws
-    end
-
-    def to_element # :nodoc:
-      root = REXML::Element.new "workspace" 
-
-      if self.title
-        title = self.title.to_element
-        title.name = "atom:title"
-        root << title
-      end
-
-      self.collections.each do |coll|
-        el = REXML::Element.new "collection"
-
-        el.attributes["href"] = coll.uri.to_s
-
-        title = coll.title.to_element
-        title.name = "atom:title"
-        el << title
-       
-        unless coll.accepts.nil?
-          coll.accepts.each do |acc|
-            accept = REXML::Element.new "accept"
-            accept.text = acc
-            el << accept
-          end
-        end
-
-        root << el
-      end
+    is_element PP_NS, :workspace
 
-      root
-    end
+    elements ['app', PP_NS], :collection, :collections, Atom::Collection
+    atom_element :title, Atom::Title
   end
 
   # Atom::Service represents an Atom Publishing Protocol service
-  # document. Its only child is #workspaces, which is an Array of 
+  # document. Its only child is #workspaces, which is an Array of
   # Atom::Workspace s
   class Service < Atom::Element
-    element :workspaces, Atom::Multiple(Atom::Workspace)
+    is_element PP_NS, :service
+
+    elements ['app', PP_NS], :workspace, :workspaces, Atom::Workspace
 
     # retrieves and parses an Atom service document.
     def initialize(service_url = "", http = Atom::HTTP.new)
-      super("service")
-      
+      super()
+
       @http = http
 
       return if service_url.empty?
@@ -112,52 +42,65 @@ module Atom
         raise Atom::HTTPException, "Unexpected HTTP response code: #{res.code}"
       end
 
-      parse(res.body, base)
-    end
-
-    def self.parse xml, base = ""
-      Atom::Service.new.parse(xml, base)
+      self.class.parse(res.body, base, self)
     end
 
     def collections
       self.workspaces.map { |ws| ws.collections }.flatten
     end
 
-    # parse a service document, adding its workspaces to this object
-    def parse xml, base = ""
-      rxml = if xml.is_a? REXML::Document
-        xml.root
-      elsif xml.is_a? REXML::Element
-        xml
-      else 
-        REXML::Document.new(xml)
-      end
+    # given a URL, attempt to find a service document
+    def self.discover url, http = Atom::HTTP.new
+      res = http.get(url, 'Accept' => 'application/atomsvc+xml, text/html')
 
-      unless rxml.root.namespace == PP_NS
-        raise Atom::ParseError, "this isn't an atom service document! (wrong namespace: #{rxml.root.namespace})"
-      end
+      case res.content_type
+      when /application\/atomsvc\+xml/
+        Service.parse res.body, url
+      when /html/
+        begin
+          require 'hpricot'
+        rescue
+          raise 'autodiscovering from HTML requires Hpricot.'
+        end
 
-      REXML::XPath.match( rxml, "/app:service/app:workspace", {"app" => Atom::PP_NS} ).each do |ws_el|
-        self.workspaces << Atom::Workspace.parse(ws_el, base, @http)
-      end
+        h = Hpricot(res.body)
 
-      self
+        links = h.search('//link')
+
+        service_links = links.select { |l| (' ' + l['rel'] + ' ').match(/ service /i) }
+
+        unless service_links.empty?
+          url = url.to_uri + service_links.first['href']
+          return Service.new(url.to_s, http)
+        end
+
+        rsd_links = links.select { |l| (' ' + l['rel'] + ' ').match(/ EditURI /i) }
+
+        unless rsd_links.empty?
+          url = url.to_uri + rsd_links.first['href']
+          return Service.from_rsd(url, http)
+        end
+
+        raise AutodiscoveryFailure, "couldn't find any autodiscovery links in the HTML"
+      else
+        raise AutodiscoveryFailure, "can't autodiscover from a document of type #{res.content_type}"
+      end
     end
 
-    # serialize to a (namespaced) REXML::Document 
-    def to_xml
-      doc = REXML::Document.new
-      
-      root = REXML::Element.new "service"
-      root.add_namespace Atom::PP_NS
-      root.add_namespace "atom", Atom::NS
+    def self.from_rsd url, http = Atom::HTTP.new
+      rsd = http.get(url)
+
+      doc = REXML::Document.new(rsd.body)
 
-      self.workspaces.each do |ws|
-        root << ws.to_element
+      atom = REXML::XPath.first(doc, '/rsd/service/apis/api[@name="Atom"]')
+
+      unless atom
+        raise AutodiscoveryFailure, "couldn't find an Atom link in the RSD"
       end
 
-      doc << root
-      doc
+      url = url.to_uri + atom.attributes['apiLink']
+
+      Service.new(url.to_s, http)
     end
   end
 end