rdropbox 1.0.0

data/lib/dropbox/event.rb

@@ -0,0 +1,109 @@
+# Defines the Dropbox::Event class.
+
+nil # doc fix
+
+module Dropbox
+  
+  # The Dropbox::Event class stores information about which entries were
+  # modified during a pingback event. You initialize this class from the JSON
+  # string given to you by Dropbox during a pingback:
+  #
+  #  event = Dropbox::Event.new(params[:target_events])
+  #
+  # Once this is complete, the Dropbox::Event instance contains references for
+  # each of the entries, with the basic information included in the pingback:
+  #
+  #  event.user_ids #=> [ 1, 2, 3 ]
+  #  event.entries(1).first #=> #<Dropbox::Revision 1:10:100>
+  #
+  # For any of these entries, you can load its content and metadata:
+  #
+  #  event.entries(1).first.load(dropbox_session)
+  #  event.entries(1).first.content #=> "Content of file..."
+  #  event.entries(1).first.size #=> 2245
+  #
+  # You can also load only the metadata for all of a user's entries:
+  #
+  #  event.load_metadata(first_users_dropbox_session)
+  #  event.entries(1).first.size #=> 154365
+  
+  class Event
+    def initialize(json_pingback) # :nodoc:
+      @json_pingback = json_pingback
+      begin
+        @metadata = JSON.parse(json_pingback).stringify_keys_recursively
+      rescue JSON::ParserError
+        raise Dropbox::ParseError, "Invalid pingback event data"
+      end
+
+      process_pingback
+    end
+    
+    # Returns an array of Dropbox user ID's involved in this pingback.
+    
+    def user_ids
+      @entries_by_user_id.keys
+    end
+
+    # When given no arguments, returns an array of all entries (as
+    # Dropbox::Revision instances). When given a user ID, filters the list
+    # to only entries belonging to that Dropbox user.
+
+    def entries(user_id=nil)
+      user_id ? (@entries_by_user_id[user_id.to_i] || []).dup : @entries.dup
+    end
+
+    # Loads the metadata for all entries belonging to a given Dropbox session.
+    # Does not load data for files that do not belong to the user owning the
+    # given Dropbox session.
+    #
+    # Future calls to this method will result in additional network requests,
+    # though the Dropbox::Revision instances do cache their metadata values.
+    #
+    # Options:
+    #
+    # +mode+:: Temporarily changes the API mode. See the Dropbox::API::MODES
+    #          array.
+
+    def load_metadata(session, options={})
+      process_metadata session.event_metadata(@json_pingback, options).stringify_keys_recursively
+    end
+    
+    def inspect # :nodoc:
+      "#<#{self.class.to_s} (#{@entries.size} entries)>"
+    end
+    
+    private
+
+    def process_pingback
+      @entries = Array.new
+      @entries_by_user_id = Hash.new
+      @entries_hashed = Hash.new
+
+      @metadata.each do |user_id, namespaces|
+        @entries_hashed[user_id.to_i] = Hash.new
+        @entries_by_user_id[user_id.to_i] = Array.new
+        namespaces.each do |namespace_id, journals|
+          @entries_hashed[user_id.to_i][namespace_id.to_i] = Hash.new
+          journals.each do |journal_id|
+            entry = Dropbox::Revision.new(user_id.to_i, namespace_id.to_i, journal_id.to_i)
+            @entries << entry
+            @entries_by_user_id[user_id.to_i] << entry
+            @entries_hashed[user_id.to_i][namespace_id.to_i][journal_id.to_i] = entry
+          end
+        end
+      end
+    end
+
+    def process_metadata(metadata)
+      p metadata
+      metadata.each do |user_id, namespaces|
+        namespaces.each do |namespace_id, journals|
+          journals.each do |journal_id, attributes|
+            @entries_hashed[user_id.to_i][namespace_id.to_i][journal_id.to_i].process_metadata(attributes.symbolize_keys)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dropbox/memoization.rb

@@ -0,0 +1,98 @@
+# Defines the Dropbox::Memoization module.
+
+nil # doc fix
+
+module Dropbox
+
+  # Adds methods to the Dropbox::Session class to support the temporary local
+  # storage of API results to reduce the number of network calls and simplify
+  # code.
+  #
+  # Memoization is <b>opt-in</b>; you must explicitly indicate that you want
+  # this functionality by calling the enable_memoization method on your
+  # Scribd::Session instance. Once memoization is enabled, subsequent calls to
+  # memoized methods will hit an in-memory cache as opposed to making identical
+  # network calls.
+  #
+  # If you would like to use your own caching strategy (for instance, your own
+  # memcache instance), set the +cache_proc+ and +cache_clear_proc+ attributes.
+  #
+  # Enabling memoization makes removes an instance's thread-safety.
+  #
+  # Example:
+  #
+  #  session.metadata('file1') # network
+  #
+  #  session.enable_memoization
+  #  session.metadata('file1') # network
+  #  session.metadata('file1') # cache
+  #
+  #  session.metadata('file2') # network
+  #  session.metadata('file2') # cache
+  #
+  #  session.disable_memoization
+  #  session.metadata('file2') # network
+
+  module Memoization
+    def self.included(base) # :nodoc:
+      base.extend ClassMethods
+    end
+
+    # The cache_proc is a proc with two arguments, the cache identifier and the
+    # proc to call and store in the event of a cache miss:
+    #
+    #  instance.cache_proc = Proc.new do |identifier, calculate_proc|
+    #    Rails.cache.fetch(identifier) { calculate_proc.call }
+    #  end
+    #
+    # The Cache identifier will always be 64 lowercase hexadecimal characters.
+    # The second argument is a curried proc including all arguments to the
+    # original method call.
+
+    def cache_proc=(prc)
+      @_memo_cache_proc = prc
+    end
+
+    # The cache_clear_proc takes an identifier and should invalidate it from the
+    # cache:
+    #
+    #  instance.cache_clear_proc = Proc.new { |identifier| Rails.cache.delete identifier }
+
+    def cache_clear_proc=(prc)
+      @_memo_cache_clear_proc = prc
+    end
+
+    # Begins memoizing the results of API calls. Memoization is off by default
+    # for new instances.
+
+    def enable_memoization
+      @_memoize = true
+      @_memo_identifiers ||= Set.new
+    end
+
+    # Halts memoization of API calls and clears the memoization cache.
+
+    def disable_memoization
+      @_memoize = false
+      @_memo_identifiers.each { |identifier| (@_memo_cache_clear_proc || Proc.new { |ident| eval "@_memo_#{ident} = nil" }).call(identifier) }
+      @_memo_identifiers.clear
+    end
+
+    module ClassMethods # :nodoc:
+      def memoize(*method_names) # :nodoc:
+        method_names.each do |meth|
+          define_method :"#{meth}_with_memo" do |*args|
+            if @_memoize then
+              identifier = Digest::SHA1.hexdigest(meth.to_s + ":" + args.to_yaml)
+              @_memo_identifiers << identifier
+              (@_memo_cache_proc || Proc.new { |ident, calculate_proc| eval "@_memo_#{ident} ||= calculate_proc.call" }).call identifier, Proc.new { send :"#{meth}_without_memo", *args }
+            else
+              send :"#{meth}_without_memo", *args
+            end
+          end
+          alias_method_chain meth, :memo
+        end
+      end
+    end
+  end
+end

data/lib/dropbox/revision.rb

@@ -0,0 +1,197 @@
+# Defines the Dropbox::Revision class.
+
+nil # doc fix
+
+module Dropbox
+
+  # A file or folder at a point in time as referenced by a Dropbox::Event
+  # pingback event. Instances start out as "shells" only storing enough
+  # information to uniquely identify a file/folder belonging to a user at a
+  # certain revision.
+  #
+  # Instances of this class only appear in a Dropbox::Event object. To load the
+  # metadata for a revision, use the Dropbox::Event#load_metadata method.
+  # To load the content of the file at this revision, use the load_content
+  # method on this class.
+  #
+  # Once the metadata has been loaded, you can access it directly:
+  #
+  #  revision.size #=> 2962
+  #
+  # The +mtime+ attribute will be a Time instance.  The +mtime+ and +size+
+  # attributes will be +nil+ (not -1) if the file was deleted. All other
+  # attributes are as defined in
+  # http://developers.getdropbox.com/base.html#event-metadata
+  #
+  # If the metadata could not be read for whatever reason, the HTTP error code
+  # will be stored in the +error+ attribute.
+
+  class Revision
+    # The ID of the Dropbox user that owns this file.
+    attr_reader :user_id
+    # The namespace ID of the file (Dropbox internal).
+    attr_reader :namespace_id
+    # The journal ID of the file (Dropbox internal).
+    attr_reader :journal_id
+    # The HTTP error code received when trying to load metadata, or +nil+ if no
+    # error has yet been received.
+    attr_reader :error
+
+    def initialize(uid, nid, jid) # :nodoc:
+      @user_id = uid
+      @namespace_id = nid
+      @journal_id = jid
+    end
+
+    # The unique identifier string used by some Dropbox event API methods.
+
+    def identifier
+      "#{user_id}:#{namespace_id}:#{journal_id}"
+    end
+
+    # Uses the given Dropbox::Session to load the content and metadata for a
+    # file at a specific revision.
+    #
+    # Options:
+    #
+    # +mode+:: Temporarily changes the API mode. See the Dropbox::API::MODES
+    #          array.
+
+    def load(session, options={})
+      @content, @metadata = session.event_content(identifier, options)
+      @metadata.symbolize_keys!
+
+      postprocess_metadata
+    end
+
+    # Returns true if the content for this revision has been previously loaded
+    # and is cached in this object.
+
+    def content_loaded?
+      @content.to_bool
+    end
+
+    # Returns true if the metadata for this revision has been previously loaded
+    # and is cached in this object.
+
+    def metadata_loaded?
+      @metadata.to_bool
+    end
+
+    # Sugar for the +latest+ attribute.
+
+    def latest?
+      raise NotLoadedError.new(:metadata) unless metadata_loaded?
+      self.latest
+    end
+
+    # Sugar for the +is_dir+ attribute.
+
+    def directory?
+      raise NotLoadedError.new(:metadata) unless metadata_loaded?
+      self.is_dir
+    end
+
+    # Synonym for the +mtime+ attribute, for "duck" compatibility with the
+    # Dropbox +metadata+ API.
+
+    def modified
+      raise NotLoadedError.new(:metadata) unless metadata_loaded?
+      self.mtime
+    end
+
+    # Returns true if an error occurred when trying to load metadata.
+
+    def error?
+      error.to_bool
+    end
+    
+    # Returns true if this change represents the file being deleted.
+    
+    def deleted?
+      raise NotLoadedError.new(:metadata) unless metadata_loaded?
+      self.mtime.nil? and self.size.nil?
+    end
+
+    # Returns the contents of the file as a string. Returns nil for directories.
+    # You must call load first to retrieve the content from the network.
+
+    def content
+      raise NotLoadedError.new(:content) unless content_loaded?
+      @content
+    end
+
+    def inspect # :nodoc:
+      "#<#{self.class.to_s} #{identifier}>"
+    end
+
+    # Allows you to access metadata attributes directly:
+    #
+    #  revision.size #=> 10526
+    #
+    # A NoMethodError will be raised if the metadata has not yet been loaded for
+    # this revision, so be sure to call metadata_loaded? beforehand.
+
+    def method_missing(meth, *args)
+      if args.empty? then
+        if @metadata and @metadata.include?(meth) then
+          return @metadata[meth]
+        else
+          super
+        end
+      else
+        super
+      end
+    end
+
+    # Loads the metadata for the latest revision of the entry and returns it as
+    # as <tt>Struct</tt> object. Uses the given session and calls
+    # Dropbox::API.metadata.
+    #
+    # If the metadata for this object has not yet been loaded, raises an error.
+    # Options are passed to Dropbox::API.metadata.
+
+    def metadata_for_latest_revision(session, options={})
+      raise NotLoadedError.new(:metadata) unless metadata_loaded?
+      session.metadata self.path, options
+    end
+
+    def process_metadata(metadata) # :nodoc:
+      if metadata[:error] then
+        @error = metadata[:error] unless @metadata
+        return
+      end
+
+      @error = nil
+      @metadata = Hash.new
+      metadata.each { |key, value| @metadata[key.to_sym] = value }
+
+      postprocess_metadata
+    end
+
+    private
+
+    def postprocess_metadata
+      @metadata[:size] = nil if @metadata[:size] == -1
+      @metadata[:mtime] = (@metadata[:mtime] == -1 ? nil : Time.at(@metadata[:mtime])) if @metadata[:mtime]
+      @metadata[:ts] = Time.parse(@metadata[:ts]) if @metadata[:ts]
+    end
+  end
+
+  # Raised when trying to access content metadata before it has been loaded.
+
+  class NotLoadedError < StandardError
+    
+    # What data did you attempt to access before it was loaded? Either
+    # <tt>:content</tt> or <tt>:metadata</tt>.
+    attr_reader :data
+
+    def initialize(data) # :nodoc:
+      @data = data
+    end
+
+    def to_s # :nodoc:
+      "#{data.capitalize} not yet loaded -- call #load on the Dropbox::Revision instance beforehand"
+    end
+  end
+end

data/lib/dropbox/session.rb

@@ -0,0 +1,160 @@
+# Defines the Dropbox::Session class.
+
+require 'oauth'
+
+module Dropbox
+
+  # This class is a portal to the Dropbox API and a façade over the Ruby OAuth
+  # gem allowing developers to authenticate their user's Dropbox accounts.
+  #
+  # == Authenticating a user
+  #
+  # You start by creating a new instance and providing your OAuth consumer key
+  # and secret. You then call the authorize_url method on your new instance to
+  # receive the authorization URL.
+  #
+  # Once your user visits the URL, it will complete the authorization process on
+  # the server side. You should call the authorize method:
+  #
+  #  session = Dropbox::Session.new(my_key, my_secret)
+  #  puts "Now visit #{session.authorize_url}. Hit enter when you have completed authorization."
+  #  gets
+  #  session.authorize
+  #
+  # The authorize method must be called on the same instance of Dropbox::Session
+  # that gave you the URL. If this is unfeasible (for instance, you are doing
+  # this in a stateless Rails application), you can serialize the Session for
+  # storage (e.g., in your Rails session):
+  #
+  #  def authorize
+  #    if params[:oauth_token] then
+  #      dropbox_session = Dropbox::Session.deserialize(session[:dropbox_session])
+  #      dropbox_session.authorize(params)
+  #      session[:dropbox_session] = dropbox_session.serialize # re-serialize the authenticated session
+  #
+  #      redirect_to :action => 'upload'
+  #    else
+  #      dropbox_session = Dropbox::Session.new('your_consumer_key', 'your_consumer_secret')
+  #      session[:dropbox_session] = dropbox_session.serialize
+  #      redirect_to dropbox_session.authorize_url(:oauth_callback => root_url)
+  #    end
+  #  end
+  #
+  # == Working with the API
+  #
+  # This class includes the methods of the Dropbox::API module. See that module
+  # to learn how to continue using the API.
+
+  class Session
+    include API
+
+    # Begins the authorization process. Provide the OAuth key and secret of your
+    # API account, assigned by Dropbox. This is the first step in the
+    # authorization process.
+    #
+    # Options:
+    #
+    # +ssl+:: If true, uses SSL to connect to the Dropbox API server.
+
+    def initialize(oauth_key, oauth_secret, options={})
+      @ssl = options[:ssl].to_bool
+      @consumer = OAuth::Consumer.new(oauth_key, oauth_secret,
+                                      :site => (@ssl ? Dropbox::SSL_HOST : Dropbox::HOST),
+                                      :request_token_path => "/#{Dropbox::VERSION}/oauth/request_token",
+                                      :authorize_path => "/#{Dropbox::VERSION}/oauth/authorize",
+                                      :access_token_path => "/#{Dropbox::VERSION}/oauth/access_token")
+      @request_token = @consumer.get_request_token
+    end
+
+    # Returns a URL that is used to complete the authorization process. Visiting
+    # this URL is the second step in the authorization process, after creating
+    # the Session instance.
+
+    def authorize_url(*args)
+      if authorized? then
+        raise AlreadyAuthorizedError, "You have already been authorized; no need to get an authorization URL."
+      else
+        return @request_token.authorize_url(*args)
+      end
+    end
+
+    # Authorizes a user from the information returned by Dropbox. This is the
+    # third step in the authorization process, after sending the user to the
+    # authorize_url.
+    #
+    # You can pass to this method a hash containing the keys and values of the
+    # OAuth parameters returned by Dropbox. An example in Rails:
+    #
+    #  session.authorize :oauth_verifier => params[:oauth_verifier]
+    #
+    # Returns a boolean indicating if authentication was successful.
+
+    def authorize(options={})
+      @access_token = @request_token.get_access_token(options)
+      @request_token = nil if @access_token
+      return @access_token.to_bool
+    end
+
+    # Returns true if this session has been authorized.
+
+    def authorized?
+      @access_token.to_bool
+    end
+
+    # Serializes this object into a string that can then be recreated with the
+    # Dropbox::Session.deserialize method.
+
+    def serialize
+      if authorized? then
+        [ @consumer.key, @consumer.secret, authorized?, @access_token.token, @access_token.secret ].to_yaml
+      else
+        [ @consumer.key, @consumer.secret, authorized?, @request_token.token, @request_token.secret ].to_yaml
+      end
+    end
+    
+    # Deserializes an instance from a string created from the serialize method.
+    # Returns the recreated instance.
+
+    def self.deserialize(data)
+      consumer_key, consumer_secret, authorized, token, token_secret = YAML.load(StringIO.new(data))
+      raise ArgumentError, "Must provide a properly serialized #{self.to_s} instance" unless [ consumer_key, consumer_secret, token, token_secret ].all? and authorized == true or authorized == false
+
+      session = self.new(consumer_key, consumer_secret)
+      if authorized then
+        session.instance_variable_set :@access_token, OAuth::AccessToken.new(session.instance_variable_get(:@consumer), token, token_secret)
+      else
+        session.instance_variable_set :@request_token, OAuth::RequestToken.new(session.instance_variable_get(:@consumer), token, token_secret)
+      end
+      
+      return session
+    end
+
+    def inspect # :nodoc:
+      "#<#{self.class.to_s} #{@consumer.key} (#{'un' unless authorized?}authorized)>"
+    end
+
+    private
+
+    def access_token
+      @access_token || raise(UnauthorizedError, "You need to authorize the Dropbox user before you can call API methods")
+    end
+
+    def clone_with_host(host)
+      session = dup
+      consumer = OAuth::Consumer.new(@consumer.key, @consumer.secret, :site => host)
+      session.instance_variable_set :@consumer, consumer
+      session.instance_variable_set :@access_token, OAuth::AccessToken.new(consumer, @access_token.token, @access_token.secret)
+      return session
+    end
+  end
+
+  # Raised when trying to call Dropbox API methods without yet having completed
+  # the OAuth process.
+
+  class UnauthorizedError < StandardError; end
+
+  # Raised when trying to call Dropbox::Session#authorize_url on an already
+  # authorized session.
+
+  class AlreadyAuthorizedError < StandardError; end
+end

data/lib/dropbox.rb

@@ -0,0 +1,43 @@
+# Defines the Dropbox module.
+
+require 'cgi'
+require 'yaml'
+require 'digest/sha1'
+require 'thread'
+require 'set'
+require 'time'
+require 'tempfile'
+
+Dir.glob("#{File.expand_path File.dirname(__FILE__)}/extensions/*.rb") { |file| require file }
+Dir.glob("#{File.expand_path File.dirname(__FILE__)}/dropbox/*.rb") { |file| require file }
+
+# Container module for the all Dropbox API classes.
+
+module Dropbox
+  # The API version this client works with.
+  VERSION = "0"
+  # The host serving API requests.
+  HOST = "http://api.dropbox.com"
+  # The SSL host serving API requests.
+  SSL_HOST = "https://api.dropbox.com"
+  # Alternate hosts for other API requests.
+  ALTERNATE_HOSTS = { 'event_content' => 'http://api-content.dropbox.com', 'files' => "http://api-content.dropbox.com" }
+  # Alternate SSL hosts for other API requests.
+  ALTERNATE_SSL_HOSTS = { 'event_content' => 'https://api-content.dropbox.com', 'files' => "https://api-content.dropbox.com" }
+
+  def self.api_url(*paths_and_options) # :nodoc:
+    params = paths_and_options.extract_options!
+    ssl = params.delete(:ssl)
+    host = (ssl ? ALTERNATE_SSL_HOSTS[paths_and_options.first] : ALTERNATE_HOSTS[paths_and_options.first]) || (ssl ? SSL_HOST : HOST)
+    url = "#{host}/#{VERSION}/#{paths_and_options.map { |path_elem| CGI.escape path_elem.to_s }.join('/')}"
+    url.gsub! '+', '%20' # dropbox doesn't really like plusses
+    url << "?#{params.map { |k,v| CGI.escape(k.to_s) + "=" + CGI.escape(v.to_s) }.join('&')}" unless params.empty?
+    return url
+  end
+
+  def self.check_path(path) # :nodoc:
+    raise ArgumentError, "Backslashes are not allowed in Dropbox paths" if path.include?('\\')
+    raise ArgumentError, "Dropbox paths are limited to 256 characters in length" if path.size > 256
+    return path
+  end
+end

data/lib/extensions/array.rb

@@ -0,0 +1,9 @@
+class Array # :nodoc:
+  def extract_options! # :nodoc:
+    last.is_a?(::Hash) ? pop : {}
+  end unless method_defined?(:extract_options!)
+
+  def to_hash # :nodoc:
+    inject({}) { |hsh, (k,v)| hsh[k] = v  ; hsh }
+  end unless method_defined?(:to_hash)
+end

data/lib/extensions/hash.rb

@@ -0,0 +1,61 @@
+class Hash # :nodoc:
+  def slice(*keys) #:nodoc:
+    keys = keys.map! { |key| convert_key(key) } if respond_to?(:convert_key)
+    hash = self.class.new
+    keys.each { |k| hash[k] = self[k] if has_key?(k) }
+    hash
+  end unless method_defined?(:slice)
+
+  def symbolize_keys # :nodoc:
+    inject({}) do |options, (key, value)|
+      options[(key.to_sym rescue key) || key] = value
+      options
+    end
+  end unless method_defined?(:symbolize_keys)
+
+  def symbolize_keys! # :nodoc:
+    self.replace(self.symbolize_keys)
+  end unless method_defined?(:symbolize_keys!)
+
+  def symbolize_keys_recursively # :nodoc:
+    hsh = symbolize_keys
+    hsh.each { |k, v| hsh[k] = v.symbolize_keys_recursively if v.kind_of?(Hash) }
+    hsh.each { |k, v| hsh[k] = v.map { |i| i.kind_of?(Hash) ? i.symbolize_keys_recursively : i } if v.kind_of?(Array) }
+    return hsh
+  end
+
+  def stringify_keys # :nodoc:
+    inject({}) do |options, (key, value)|
+      options[(key.to_s rescue key) || key] = value
+      options
+    end
+  end unless method_defined?(:stringify_keys)
+
+  def stringify_keys! # :nodoc:
+    self.replace(self.stringify_keys)
+  end unless method_defined?(:stringify_keys!)
+
+  def stringify_keys_recursively # :nodoc:
+    hsh = stringify_keys
+    hsh.each { |k, v| hsh[k] = v.stringify_keys_recursively if v.kind_of?(Hash) }
+    hsh.each { |k, v| hsh[k] = v.map { |i| i.kind_of?(Hash) ? i.stringify_keys_recursively : i } if v.kind_of?(Array) }
+    return hsh
+  end
+
+  def to_struct # :nodoc:
+    struct = Struct.new(*keys).new(*values)
+    # attach methods for any predicate keys, since Struct.new doesn't seem to do that
+    pred_keys = slice(*(keys.select { |key| key.to_s.ends_with?('?') }))
+    pred_keys.each do |key, val|
+      struct.eigenclass.send(:define_method, key.to_sym) { return val }
+    end
+    return struct
+  end
+
+  def to_struct_recursively # :nodoc:
+    hsh = dup
+    hsh.each { |k, v| hsh[k] = v.to_struct_recursively if v.kind_of?(Hash) }
+    hsh.each { |k, v| hsh[k] = v.map { |i| i.kind_of?(Hash) ? i.to_struct_recursively : i } if v.kind_of?(Array) }
+    return hsh.to_struct
+  end
+end