thehack-atom-tools 2.0.3

data/lib/atom/entry.rb

@@ -0,0 +1,134 @@
+require "rexml/document"
+
+require "atom/element"
+require "atom/text"
+
+module Atom
+  class Control < Atom::Element
+    attr_accessor :draft
+
+    is_element PP_NS, :control
+
+    on_parse [PP_NS, 'draft'] do |e,x|
+      e.set(:draft, x.text == 'yes')
+    end
+
+    on_build do |e,x|
+      unless (v = e.get(:draft)).nil?
+        el = e.append_elem(x, ['app', PP_NS], 'draft')
+        el.text = (v ? 'yes' : 'no')
+      end
+    end
+  end
+
+  module HasCategories
+    def HasCategories.included(klass)
+      klass.atom_elements :category, :categories, Atom::Category
+    end
+
+    # categorize the entry with each of an array or a space-separated
+    #   string
+    def tag_with(tags, delimiter = ' ')
+      return if not tags or tags.empty?
+
+      tag_list = unless tags.is_a?(String)
+                   tags
+                 else
+                   tags = tags.split(delimiter)
+                   tags.map! { |t| t.strip }
+                   tags.reject! { |t| t.empty? }
+                   tags.uniq
+                 end
+
+      tag_list.each do |tag|
+        unless categories.any? { |c| c.term == tag }
+          categories.new :term => tag
+        end
+      end
+    end
+  end
+
+  module HasLinks
+    def HasLinks.included(klass)
+      klass.atom_elements :link, :links, Atom::Link
+    end
+
+    def find_link(criteria)
+      self.links.find do |l|
+        criteria.all? { |k,v| l.send(k) == v }
+      end
+    end
+  end
+
+  # An individual entry in a feed. As an Atom::Element, it can be
+  # manipulated using accessors for each of its child elements. You
+  # should be able to set them using an instance of any class that
+  # makes sense
+  #
+  # Entries have the following children:
+  #
+  # id:: a universally unique IRI which permanently identifies the entry
+  # title:: a human-readable title (Atom::Text)
+  # content:: contains or links to the content of an entry (Atom::Content)
+  # rights:: information about rights held in and over an entry (Atom::Text)
+  # source:: the source feed's metadata (unimplemented)
+  # published:: a Time "early in the life cycle of an entry"
+  # updated:: the most recent Time an entry was modified in a way the publisher considers significant
+  # summary:: a summary, abstract or excerpt of an entry (Atom::Text)
+  #
+  # There are also +categories+, +links+, +authors+ and +contributors+,
+  # each of which is an Array of its respective type and can be used
+  # thusly:
+  #
+  #   author = entry.authors.new :name => "Captain Kangaroo", :email => "kanga@example.net"
+  #
+  class Entry < Atom::Element
+    is_atom_element :entry
+
+    # the master list of standard children and the types they map to
+    atom_string :id
+
+    atom_element :title, Atom::Title
+    atom_element :summary, Atom::Summary
+    atom_element :content, Atom::Content
+
+    atom_element :rights, Atom::Rights
+
+    # element :source, Atom::Feed  # XXX complicated, eg. serialization
+
+    atom_time :published
+    atom_time :updated
+    time ['app', PP_NS], :edited
+
+    atom_elements :author, :authors, Atom::Author
+    atom_elements :contributor, :contributors, Atom::Contributor
+
+    element ['app', PP_NS], :control, Atom::Control
+
+    include HasCategories
+    include HasLinks
+
+    atom_link :edit_url, :rel => 'edit'
+
+    def inspect # :nodoc:
+      "#<Atom::Entry id:'#{self.id}'>"
+    end
+
+    def draft
+      control and control.draft
+    end
+
+    alias :draft? :draft
+
+    def draft!
+      self.draft = true
+    end
+
+    def draft= is_draft
+      unless control
+        instance_variable_set '@control', Atom::Control.new
+      end
+      control.draft = is_draft
+    end
+  end
+end

data/lib/atom/feed.rb

@@ -0,0 +1,223 @@
+require "atom/element"
+require "atom/text"
+require "atom/entry"
+
+require "atom/http"
+
+module Atom
+  class FeedGone < RuntimeError # :nodoc:
+  end
+
+  # A feed of entries. As an Atom::Element, it can be manipulated using
+  # accessors for each of its child elements. You can set them with any
+  # object that makes sense; they will be returned in the types listed.
+  #
+  # Feeds have the following children:
+  #
+  # id:: a universally unique IRI which permanently identifies the feed
+  # title:: a human-readable title (Atom::Text)
+  # subtitle:: a human-readable description or subtitle (Atom::Text)
+  # updated:: the most recent Time the feed was modified in a way the publisher considers significant
+  # generator:: the agent used to generate a feed
+  # icon:: an IRI identifying an icon which visually identifies a feed (1:1 aspect ratio, looks OK small)
+  # logo:: an IRI identifying an image which visually identifies a feed (2:1 aspect ratio)
+  # rights:: rights held in and over a feed (Atom::Text)
+  #
+  # There are also +links+, +categories+, +authors+, +contributors+
+  # and +entries+, each of which is an Array of its respective type and
+  # can be used thusly:
+  #
+  #   entry = feed.entries.new
+  #   entry.title = "blah blah blah"
+  #
+  class Feed < Atom::Element
+    is_atom_element :feed
+
+    attr_reader :uri
+
+    # the Atom::Feed pointed to by link[@rel='previous']
+    attr_reader :prev
+    # the Atom::Feed pointed to by link[@rel='next']
+    attr_reader :next
+
+    # conditional get information from the last fetch
+    attr_reader :etag, :last_modified
+
+    atom_string :id
+    atom_element :title, Atom::Title
+    atom_element :subtitle, Atom::Subtitle
+
+    atom_time :updated
+
+    include HasLinks
+    include HasCategories
+
+    atom_elements :author, :authors, Atom::Author
+    atom_elements :contributor, :contributors, Atom::Contributor
+
+    atom_string :generator # XXX with uri and version attributes!
+    atom_string :icon
+    atom_string :logo
+
+    atom_element :rights, Atom::Rights
+
+    atom_elements :entry, :entries, Atom::Entry
+
+    include Enumerable
+
+    def inspect # :nodoc:
+      "<#{@uri} entries: #{entries.length} title='#{title}'>"
+    end
+
+    # Create a new Feed that can be found at feed_uri and retrieved
+    # using an Atom::HTTP object http
+    def initialize feed_uri = nil, http = Atom::HTTP.new
+      @entries = []
+      @http = http
+
+      if feed_uri
+        @uri = feed_uri.to_uri
+        self.base = feed_uri
+      end
+
+      super()
+    end
+
+    # iterates over a feed's entries
+    def each &block
+      @entries.each &block
+    end
+
+    def empty?
+      @entries.empty?
+    end
+
+    # gets everything in the logical feed (could be a lot of stuff)
+    # (see RFC 5005)
+    def get_everything!
+      self.update!
+
+      prev = @prev
+      while prev
+        prev.update!
+
+        self.merge_entries! prev
+        prev = prev.prev
+      end
+
+      nxt = @next
+      while nxt
+        nxt.update!
+
+        self.merge_entries! nxt
+        nxt = nxt.next
+      end
+
+      self
+    end
+
+    # merges the entries from another feed into this one
+    def merge_entries! other_feed
+      other_feed.each do |entry|
+        # TODO: add atom:source elements
+        self << entry
+      end
+    end
+
+    # like #merge, but in place
+    def merge! other_feed
+      [:id, :title, :subtitle, :updated, :rights, :logo, :icon].each do |p|
+        if (v = other_feed.get(p))
+          set p, v
+        end
+      end
+
+      [:links, :categories, :authors, :contributors].each do |p|
+        other_feed.get(p).each do |e|
+          get(p) << e
+        end
+      end
+
+      @extensions = other_feed.extensions
+
+      merge_entries! other_feed
+    end
+
+    # merges "important" properties of this feed with another one,
+    # returning a new feed
+    def merge other_feed
+      feed = self.clone
+
+      feed.merge! other_feed
+
+      feed
+    end
+
+    # fetches this feed's URL, parses the result and #merge!s
+    # changes, new entries, &c.
+    #
+    # (note that this is different from Atom::Entry#updated!
+    def update!
+      raise(RuntimeError, "can't fetch without a uri.") unless @uri
+
+      res = @http.get(@uri, "Accept" => "application/atom+xml")
+
+      if @etag and res['etag'] == @etag
+        # we're already all up to date
+        return self
+      elsif res.code == "410"
+        raise Atom::FeedGone, "410 Gone (#{@uri})"
+      elsif res.code != "200"
+        raise Atom::HTTPException, "Unexpected HTTP response code: #{res.code}"
+      end
+
+      # we'll be forgiving about feed content types.
+      res.validate_content_type(["application/atom+xml",
+                                  "application/xml",
+                                  "text/xml"])
+
+      @etag = res["ETag"] if res["ETag"]
+
+      xml = res.body
+
+      coll = REXML::Document.new(xml)
+
+      update_el = REXML::XPath.first(coll, "/atom:feed/atom:updated", { "atom" => Atom::NS } )
+
+      # the feed hasn't been updated, don't do anything.
+      if update_el and self.updated and self.updated >= Time.parse(update_el.text)
+        return self
+      end
+
+      coll = self.class.parse(coll.root, self.base.to_s)
+      merge! coll
+
+      if abs_uri = next_link
+        @next = self.class.new(abs_uri.to_s, @http)
+      end
+
+      if abs_uri = previous_link
+        @prev = self.class.new(abs_uri.to_s, @http)
+      end
+
+      self
+    end
+
+    atom_link :previous_link, :rel => 'previous'
+    atom_link :next_link, :rel => 'next'
+
+    # adds an entry to this feed. if this feed already contains an
+    # entry with the same id, the newest one is used.
+    def << entry
+      existing = entries.find do |e|
+        e.id == entry.id
+      end
+
+      if not existing
+        @entries << entry
+      elsif not existing.updated or (existing.updated and entry.updated and entry.updated >= existing.updated)
+        @entries[@entries.index(existing)] = entry
+      end
+    end
+  end
+end

data/lib/atom/http.rb

@@ -0,0 +1,417 @@
+require "net/http"
+require "net/https"
+require "uri"
+
+require "atom/cache"
+
+require "sha1"
+require "digest/md5"
+
+module URI # :nodoc: all
+  class Generic; def to_uri; self; end; end
+end
+
+class String # :nodoc:
+  def to_uri; URI.parse(self); end
+end
+
+module Atom
+  UA = "atom-tools 2.0.1"
+
+  module DigestAuth
+    CNONCE = Digest::MD5.hexdigest("%x" % (Time.now.to_i + rand(65535)))
+
+    @@nonce_count = -1
+
+    # quoted-strings plus a few special cases for Digest
+    def parse_wwwauth_digest param_string
+      params = parse_quoted_wwwauth param_string
+      qop = params[:qop] ? params[:qop].split(",") : nil
+
+      param_string.gsub(/stale=([^,]*)/) do
+        params[:stale] = ($1.downcase == "true")
+      end
+
+      params[:algorithm] = "MD5"
+      param_string.gsub(/algorithm=([^,]*)/) { params[:algorithm] = $1 }
+
+      params
+    end
+
+    def h(data); Digest::MD5.hexdigest(data); end
+    def kd(secret, data); h(secret + ":" + data); end
+
+    # HTTP Digest authentication (RFC 2617)
+    def digest_authenticate(req, url, param_string = "")
+      raise "Digest authentication requires a WWW-Authenticate header" if param_string.empty?
+
+      params = parse_wwwauth_digest(param_string)
+      qop = params[:qop]
+
+      user, pass = username_and_password_for_realm(url, params[:realm])
+
+      if params[:algorithm] == "MD5"
+        a1 = user + ":" + params[:realm] + ":" + pass
+      else
+        # XXX MD5-sess
+        raise "I only support MD5 digest authentication (not #{params[:algorithm].inspect})"
+      end
+
+      if qop.nil? or qop.member? "auth"
+        a2 = req.method + ":" + req.path
+      else
+        # XXX auth-int
+        raise "only 'auth' qop supported (none of: #{qop.inspect})"
+      end
+
+      if qop.nil?
+        response = kd(h(a1), params[:nonce] + ":" + h(a2))
+      else
+        @@nonce_count += 1
+        nc = ('%08x' % @@nonce_count)
+
+        # XXX auth-int
+        data = "#{params[:nonce]}:#{nc}:#{CNONCE}:#{"auth"}:#{h(a2)}"
+
+        response = kd(h(a1), data)
+      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
+
+      if params[:algorithm] != "MD5"
+        header += ", algorithm=#{algo}"
+      end
+
+      if qop
+        # XXX auth-int
+        header += %Q<, nc=#{nc}, cnonce="#{CNONCE}", qop=auth>
+      end
+
+      req["Authorization"] = header
+    end
+  end
+
+  class HTTPException < RuntimeError # :nodoc:
+  end
+  class Unauthorized < Atom::HTTPException  # :nodoc:
+  end
+  class WrongMimetype < Atom::HTTPException # :nodoc:
+  end
+
+  # An object which handles the details of HTTP - particularly
+  # authentication and caching (neither of which are fully implemented).
+  #
+  # 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
+
+    # used by the default #when_auth
+    attr_accessor :user, :pass
+
+    # 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.
+    #
+    # 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
+    # initial challenge to generate a response
+    #
+    # defaults to nil
+    attr_accessor :always_auth
+
+    # automatically handle redirects, even for POST/PUT/DELETE requests?
+    #
+    # defaults to false, which will transparently redirect GET requests
+    # but return a Net::HTTPRedirection object when the server
+    # indicates to redirect a POST/PUT/DELETE
+    attr_accessor :allow_all_redirects
+
+    # 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]
+        else
+          nil
+        end
+      end
+    end
+
+    # GETs an url
+    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)
+    end
+
+    # PUTs body to an url
+    def put url, body, headers = {}
+      http_request(url, Net::HTTP::Put, body, headers)
+    end
+
+    # DELETEs to url
+    def delete url, body = nil, headers = {}
+      http_request(url, Net::HTTP::Delete, body, headers)
+    end
+
+    # a block that will be called when a remote server responds with
+    # 401 Unauthorized, so that your application can prompt for
+    # authentication details.
+    #
+    # the default is to use the values of @user and @pass.
+    #
+    # your block will be called with two parameters:
+    # abs_url:: the base URL of the request URL
+    # realm:: the realm used in the WWW-Authenticate header (maybe nil)
+    #
+    # your block should return [username, password], or nil
+    def when_auth &block # :yields: abs_url, realm
+      @get_auth_details = block
+    end
+
+    # GET a URL and turn it into an Atom::Entry
+    def get_atom_entry(url)
+      res = get(url, "Accept" => "application/atom+xml")
+
+      # XXX handle other HTTP codes
+      if res.code != "200"
+        raise Atom::HTTPException, "failed to fetch entry: expected 200 OK, got #{res.code}"
+      end
+
+      # be picky for atom:entrys
+      res.validate_content_type( [ "application/atom+xml" ] )
+
+      Atom::Entry.parse(res.body, url)
+    end
+
+    # PUT an Atom::Entry to a URL
+    def put_atom_entry(entry, url = entry.edit_url)
+      raise "Cowardly refusing to PUT a non-Atom::Entry (#{entry.class})" unless entry.is_a? Atom::Entry
+      headers = {"Content-Type" => "application/atom+xml" }
+
+      put(url, entry.to_s, headers)
+    end
+
+    private
+    # parses plain quoted-strings
+    def parse_quoted_wwwauth param_string
+      params = {}
+
+      param_string.gsub(/(\w+)="(.*?)"/) { params[$1.to_sym] = $2 }
+
+      params
+    end
+
+    # HTTP Basic authentication (RFC 2617)
+    def basic_authenticate(req, url, param_string = "")
+      params = parse_quoted_wwwauth(param_string)
+
+      user, pass = username_and_password_for_realm(url, params[:realm])
+
+      req.basic_auth user, pass
+    end
+
+    # is this the right way to do it? who knows, there's no
+    # spec!
+    #   <http://necronomicorp.com/lab/atom-authentication-sucks>
+    #
+    # thanks to H. Miyamoto for clearing things up.
+    def wsse_authenticate(req, url, params = {})
+      user, pass = username_and_password_for_realm(url, params["realm"])
+
+      nonce = rand(16**32).to_s(16)
+      nonce_enc = [nonce].pack('m').chomp
+      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
+
+    def authsub_authenticate req, url
+      req["Authorization"] = %{AuthSub token="#{@token}"}
+    end
+
+    def username_and_password_for_realm(url, realm)
+      abs_url = (url + "/").to_s
+      user, pass = @get_auth_details.call(abs_url, realm)
+
+      unless user and pass
+        raise Unauthorized, "You must provide a username and password"
+      end
+
+      [ user, pass ]
+    end
+
+    # performs a generic HTTP request.
+    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
+        dispatch_authorization www_authenticate, req, url
+      end
+
+      http_obj = Net::HTTP.new(url.host, url.port)
+      http_obj.use_ssl = true if url.scheme == "https"
+
+      res = http_obj.start do |h|
+        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)
+          # 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, headers, res["WWW-Authenticate"])
+
+          if res.kind_of? Net::HTTPUnauthorized
+            raise Unauthorized, "Your authorization was rejected"
+          end
+        end
+      when Net::HTTPRedirection
+        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, 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
+
+      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?
+
+      media_type = self.content_type.split(";").first
+
+      unless valid.member? media_type.downcase
+        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