aqua 0.1.6

data/lib/aqua/store/couch_db/attachments.rb

@@ -0,0 +1,183 @@
+module Aqua
+  module Store
+    module CouchDB 
+      # Attachments is a Hash-like container with keys that are attacment names and values that are file-type
+      # objects. Initializing and adding to the collection assures the types of both keys and values. The 
+      # collection implements a lazy-loading scheme, such that when an attachment is requested and not found,
+      # it will try to load it from CouchDB.
+      class Attachments < Mash
+        attr_reader :document
+        attr_reader :stubs
+        
+        # Creates a new attachment collection with keys that are attachment names and values that are
+        # file-type objects. The collection manages both the key and the value types.
+        # 
+        # @param [String] Document uri; used to save and retrieve attachments directly
+        # @param [Hash] Initialization values
+        #
+        # @api public 
+        def initialize( doc, hash={} )
+          raise ArgumentError, "must be initialized with a document" unless doc.respond_to?( :retrieve ) 
+          @document = doc
+          self.class.validate_hash( hash ) unless hash.empty?
+          super( hash )
+        end  
+        
+        # Adds an attachment to the collection, checking for type. Does not add directly to the database.
+        #
+        # @param [String, Symbol] Name of the attachment as a string or symbol
+        # @param [File] The attachment
+        #
+        # @api public
+        def add( name, file )
+          self.class.validate_hash( name => file )
+          self[name] = file
+        end 
+        
+        # Adds an attachment to the collection and to the database. Document doesn't have to be saved, 
+        # but it does need to have an id.
+        #
+        # @param [String, Symbol] Name of the attachment as a string or symbol
+        # @param [File] The attachment
+        #
+        # @api public
+        def add!( name, file )
+          add( name, file )
+          content_type = MIME::Types.type_for(file.path).first 
+          content_type = content_type.nil? ? "text\/plain" : content_type.simplified
+          data = {
+            'content_type' => content_type,
+            'data'         => Base64.encode64( file.read ).gsub(/\s/,'') 
+          }
+          file.rewind 
+          response = CouchDB.put( uri_for( name ), data )
+          update_doc_rev( response )
+          file
+        end  
+        
+        # Deletes an attachment from the collection, and from the database. Use #delete (from Hash) to just
+        # delete the attachment from the collection.
+        # 
+        # @param [String, Symbol] Name of the attachment as a string or symbol
+        # @return [File, nil] File at that location or nil if no file found
+        # 
+        # @api public
+        def delete!( name )
+          if self[name]
+            file = delete( name ) 
+            unless document.new?
+              CouchDB.delete( uri_for( name ) )
+            end 
+            file 
+          end  
+        end
+        
+        # Gets an attachment from the collection first. If not found, it will be requested from the database.
+        #
+        # @param [String, Symbol] Name of the attachment
+        # @return [File, nil] File for that name, or nil if not found in hash or in database
+        #
+        # @api public
+        def get( name, stream=false )
+          file = self[name] 
+          unless file
+            file = get!( name, stream )
+          end
+          file.rewind if file # just in case of previous streaming
+          file  
+        end  
+        
+        # Gets an attachment from the database. Stores it in the hash.
+        #
+        # @param [String, Symbol] Name of the attachment
+        # @param [true, false] Stream boolean flag indicating whether the data should be converted to 
+        #   a file or kept as a stream
+        # @return [File, nil] File for that name, or nil if not found in the database 
+        # @raise Any error encountered on retrieval of the attachment, json, http_client, Aqua etc
+        # 
+        # @todo make this more memory favorable, maybe streaming/saving in a max number of bytes
+        # @api public
+        def get!( name, stream=false ) 
+          file = nil
+          response = CouchDB.get( uri_for( name, false ), true ) rescue nil
+          data = response && response.respond_to?(:keys) ? Base64.decode64( response['data'] ) : nil
+          if data || response
+            file = Tempfile.new( CGI.escape( name.to_s ) ) 
+            file.binmode if file.respond_to?( :binmode )
+            data ? file.write( data ) : file.write( response )
+            file.rewind 
+            self[name] = file
+          end  
+          stream ? file.read : file
+        end  
+        
+        # Constructs the standalone attachment uri for PUT and DELETE actions.
+        # 
+        # @param [String] Name of the attachment as a string or symbol
+        # 
+        # @api private
+        def uri_for( name, include_rev = true )
+          raise ArgumentError, 'Document must have id in order to save an attachment' if document.id.nil? || document.id.empty?
+          document.uri + "/#{CGI.escape( name.to_s )}" + ( document.rev && include_rev ? "?rev=#{document.rev}" : "" )
+        end
+        
+        
+        # Validates and throws an error on a hash, insisting that the key is a string or symbol, 
+        # and the value is a file. 
+        #
+        # @param [Hash]
+        #
+        # @api private
+        def self.validate_hash( hash )
+          hash.each do |name, file|
+            raise ArgumentError, "Attachment name, #{name.inspect}, must be a Symbol or a String" unless [Symbol, String ].include?( name.class )
+            raise ArgumentError, "Attachment file, #{file.inspect}, must be a File-like object"  unless file.respond_to?( :read ) 
+          end  
+        end 
+        
+        # Goes into the document and updates it's rev to match the returned rev. That way #new? will return false
+        # when an attachment is created before the document is saved. It also means that future attempts to save 
+        # the doc won't fail with a conflict.
+        #
+        # @param [Hash] response from the put request
+        # @api private
+        def update_doc_rev( response )
+          document[:_rev] = response['rev']
+        end
+        
+        # Creates a hash for the CouchDB _attachments key.
+        # @example 
+        #   "_attachments":
+        #   {
+        #     "foo.txt":
+        #     {
+        #       "content_type":"text\/plain",
+        #       "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
+        #     },
+        # 
+        #    "bar.txt":
+        #     {
+        #       "content_type":"text\/plain",
+        #       "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
+        #     }
+        #   }
+        def pack
+          pack_hash = {} 
+          self.keys.each do |key| 
+            file = self[key]
+            content_type = MIME::Types.type_for(file.path).first 
+            content_type = content_type.nil? ? "text\/plain" : content_type.simplified
+            data = {
+              'content_type' => content_type,
+              'data'         => Base64.encode64( file.read ).gsub(/\s/,'') 
+            }
+            file.rewind 
+            pack_hash[key.to_s] = data
+          end
+          pack_hash  
+        end    
+         
+      end # Attachments
+    end # CouchDB
+  end # Store
+end # Aqua        

data/lib/aqua/store/couch_db/couch_db.rb

@@ -0,0 +1,151 @@
+require File.dirname(__FILE__) + '/http_client/rest_api'
+require File.dirname(__FILE__) + '/server'
+require File.dirname(__FILE__) + '/database'
+require File.dirname(__FILE__) + '/attachments'
+require File.dirname(__FILE__) + '/storage_methods'
+require File.dirname(__FILE__) + '/design_document'
+
+module Aqua
+  module Store
+    module CouchDB  
+      
+      class ResourceNotFound      < IOError; end
+      class RequestFailed         < IOError; end
+      class RequestTimeout        < IOError; end
+      class ServerBrokeConnection < IOError; end
+      class Conflict              < ArgumentError; end  
+      
+      # Returns a string describing the http adapter in use, or loads the default and returns a similar string
+      # @return [String] A string identifier for the HTTP adapter in use
+      def self.http_adapter
+        @adapter ||= set_http_adapter
+      end  
+  
+      # Sets a class variable with the library name that will be loaded.
+      # Then attempts to load said library from the adapter directory.
+      # It is extended into the HttpAbstraction module. Then the RestAPI which 
+      # references the HttpAbstraction module is loaded/extended into Aqua
+      # this makes available Aqua.get 'http:://someaddress.com' and other requests 
+      
+      # Loads an http_adapter from the internal http_client libraries. Right now there is only the 
+      # RestClient Adapter. Other adapters will be added when people get motivated to write and submit them.
+      # By default the RestClientAdapter is used, and if the CouchDB module is used without prior configuration
+      # it is automatically loaded.
+      #
+      # @param [optional, String] Maps to the HTTP Client Adapter module name, file name is inferred by removing the 'Adapter' suffix and underscoring the string 
+      # @return [String] Name of HTTP Client Adapter module
+      # @see Aqua::Store::CouchDB::RestAPI Has detail about the required interface
+      # @api public
+      def self.set_http_adapter( mod_string='RestClientAdapter' )
+    
+        # what is happening here:
+        # strips the Adapter portion of the module name to get at the client name
+        # convention over configurationing to get the file name as it relates to files in http_client/adapter
+        # require the hopefully found file
+        # modify the RestAPI class to extend the Rest methods from the adapter
+        # add the RestAPI to Aqua for easy access throughout the library
+        
+        @adapter = mod_string
+        mod = @adapter.gsub(/Adapter/, '')
+        file = mod.underscore
+        require File.dirname(__FILE__) + "/http_client/adapter/#{file}"
+        RestAPI.adapter = "#{mod_string}".constantize
+        extend(::RestAPI)
+        @adapter  # return the adapter 
+      end
+      
+      # Cache of CouchDB Servers used by Aqua. Each is identified by its namespace.
+      #
+      # @api private
+      def self.servers
+        @servers ||= {}
+      end
+      
+      # Reader for getting or initializtion and getting a server by namespace. Used by various parts of store
+      # to define storage strategies. Also conserves memory so that there is only one instance of a Server per
+      # namespace. 
+      #
+      # @param [String] Server Namespace
+      # @api private
+      def self.server( namespace=nil )
+        namespace ||= :aqua
+        namespace = namespace.to_sym unless namespace.class == Symbol
+        s = servers[ namespace ] 
+        s = servers[namespace.to_sym] = Server.new( :namespace => namespace ) unless s 
+        s  
+      end
+      
+      # Clears the cached servers. So far this is most useful for testing. 
+      # API will depend on usefulness outside this. 
+      #
+      # @api private
+      def self.clear_servers
+        @servers = {}
+      end 
+      
+      
+      # TEXT HELPERS ================================================
+      
+      # This comes from the CouchRest Library and its licence applies. 
+      # It is included in this library as LICENCE_COUCHREST.
+      # The method breaks the parameters into a url query string.
+      # 
+      # @param [String] The base url upon which to attach query params
+      # @param [optional Hash] A series of key value pairs that define the url query params 
+      # @api semi-public
+      def self.paramify_url( url, params = {} )
+        if params && !params.empty?
+          query = params.collect do |k,v|
+            v = v.to_json if %w{key startkey endkey}.include?(k.to_s)
+            "#{k}=#{CGI.escape(v.to_s)}"
+          end.join("&")
+          url = "#{url}?#{query}"
+        end
+        url
+      end 
+      
+      # A convenience method for escaping a string,
+      # namespaced classes with :: notation will be converted to __ 
+      # all other non-alpha numeric characters besides hyphens and underscores are removed 
+      #
+      # @param [String] to be converted
+      # @return [String] converted
+      #
+      # @api private
+      def self.escape( str )
+        str.gsub!('::', '__')
+        str.gsub!(/[^a-z0-9\-_]/, '')
+        str
+      end  
+      
+      # DATABASE STRATEGIES ----------------------------------
+      # This library was built with to be flexible but have some sensible defaults. Database strategies is 
+      # one of those areas. You can configure the CouchDB module to use one of three ways of managing data
+      # into databases: 
+      #   * :single - This is the default. It uses the CouchDB.server(:aqua) to build a single database where
+      #         all the documents are stored. 
+      #   * :per_class - This strategy is the opposite of the single strategy in that each class has it's own
+      #         database. This will make complex cross class lookups more difficult.
+      #   * :configured - Each class configures its own database and server namespace. Any server not 
+      #         configured will default to the CouchDB.server. Any database not configured will default to the
+      #         default database ... that set by the server namespace.
+      # TODO: store these strategies; give feedback to documents about the appropriate database. 
+      
+      
+      # AUTOLOADING ---------
+      # auto loads the default http_adapter if Aqua gets used without configuring it first
+        
+      class << self     
+        def method_missing( method, *args )
+          if @adapter.nil?
+            set_http_adapter # loads up the adapter related stuff
+            send( method.to_sym, eval(args.map{|value| "'#{value}'"}.join(', ')) )
+          else
+            raise NoMethodError
+          end    
+        end
+      end         
+    
+    end # CouchDB
+  end # Store
+end # Aqua     

data/lib/aqua/store/couch_db/database.rb

@@ -0,0 +1,186 @@
+require "base64"
+
+module Aqua 
+  module Store
+    module CouchDB
+      class Database
+        attr_reader :server, :name, :uri 
+        attr_accessor :bulk_cache
+     
+        # Create a CouchDB database representation from a name. Does not actually create a database on couchdb.
+        # It does not ensure that the database actually exists either. Just creates a ruby representation
+        # of a ruby database interface.
+        # 
+        # @param [optional String] Name of database. If not provided server namespace will be used as database name. 
+        # @param [optional Hash] Options for initialization. Currently the only option is :server which must be either a CouchDB server object or a symbol representing a server stored in the CouchDB module.
+        # @return [Database] The initialized object
+        # 
+        # @api public
+        def initialize( name=nil, opts={})
+          name = nil if name && name.empty?
+          opts = Mash.new( opts ) unless opts.empty?
+          @name = name if name
+          initialize_server( opts[:server] )
+          @uri = "#{server.uri}/#{namespaced( name )}" 
+          self.bulk_cache = []
+        end
+        
+        # Initializes the database server with the option provided. If not option is provided the default CouchDB
+        # server is used instead.
+        #
+        # @param [Symbol, Server]
+        #   If server_option argument is a Symbol then the CouchDB server stash will be queried for a matching 
+        #   server. CouchDB manages the creation of that server in the stash, if not found. 
+        #   If server_option argument is a Server object then then it is added directly to the database object.
+        #   No management of the server will be done with CouchDB's server stash.
+        # @raise [ArgumentError] Raised if a server_option is passed in and if that option is neither a Hash nor a Symbol.
+        # @return [Server]
+        #
+        # @api private
+        def initialize_server( server_option ) 
+          if server_option
+            if server_option.class == Symbol
+              @server = CouchDB.server( server_option )
+            elsif server_option.class == Aqua::Store::CouchDB::Server
+              @server = server_option # WARNING: this won't get stashed in CouchDB for use with other database.
+            else
+              raise ArgumentError, ":server option must be a symbol identifying a CouchDB server, or a Server object"
+            end
+          else        
+            @server = CouchDB.server
+          end 
+          @server  
+        end
+        
+        # Namespaces the database path for the given server. If no name is provided, then the database name is
+        # just the Server's namespace.
+        # 
+        # @param [String] Name that the database is initialized with, if any.
+        # @return [String] Namespaced database for use as a http path
+        # 
+        # @api private
+        def namespaced( name )
+          if name 
+            "#{server.namespace}_#{CouchDB.escape(@name)}"
+          else
+            server.namespace
+          end     
+        end  
+    
+        # Creates a database representation and PUTs it on the CouchDB server. 
+        # If successfull returns a database object. If not successful in creating
+        # the database on the CouchDB server then, false will be returned.
+        #
+        # @see Aqua::Store::CouchDB#initialize for option details
+        # @return [Database, false] Will return the database on success, and false if it did not succeed. 
+        #
+        # @api pubilc
+        def self.create( name=nil, opts={} )
+          db = new(name, opts)
+          begin
+            CouchDB.put( db.uri )
+          rescue Exception => e # catch database already exists errors ... 
+            unless e.message.match(/412/)
+              db = false
+            end   
+          end
+          db    
+        end 
+        
+        # Creates a database representation and PUTs it on the CouchDB server. 
+        # This version of the #create method raises an error if the PUT request fails. 
+        # The exception on this, is if the database already exists then the 412 HTTP code will be ignored.
+        #
+        # @see Aqua::Store::CouchDB#initialize for option details
+        # @return [Database] Will return the database on success. 
+        # @raise HttpAdapter Exceptions depending on the reason for failure.
+        #
+        # @api pubilc
+        def self.create!( name=nil, opts={} ) 
+          db = new( name, opts )
+          begin
+            CouchDB.put( db.uri )
+          rescue Exception => e # catch database already exists errors ... 
+            raise e unless e.class == RequestFailed && e.message.match(/412/) 
+          end 
+          db
+        end  
+    
+        # Checks to see if the database exists on the couchdb server.
+        #
+        # @return [true, false] depending on whether the database already exists in CouchDB land
+        #
+        # @api public
+        def exists?
+          begin 
+            info 
+            true
+          rescue CouchDB::ResourceNotFound  
+            false
+          end  
+        end  
+        
+        # GET the database info from CouchDB
+        def info
+          CouchDB.get( uri )
+        end
+     
+        # Deletes a database; use with caution as this isn't reversible.
+        # 
+        # @return A JSON response on success. nil if the resource is not found. And raises an error if another exception was raised
+        # @raise Exception related to request failure that is not a ResourceNotFound error.
+        def delete
+          begin 
+            CouchDB.delete( uri )
+          rescue CouchDB::ResourceNotFound
+            nil
+          end    
+        end  
+        
+        # Deletes a database; use with caution as this isn't reversible. Similar to #delete, 
+        # except that it will raise an error on failure to find the database.
+        # 
+        # @return A JSON response on success. 
+        # @raise Exception related to request failure or ResourceNotFound.
+        def delete!
+          CouchDB.delete( uri )
+        end  
+    
+        # # Query the <tt>documents</tt> view. Accepts all the same arguments as view.
+        def documents(params = {})
+          keys = params.delete(:keys)
+          url = CouchDB.paramify_url( "#{uri}/_all_docs", params )
+          if keys
+            CouchDB.post(url, {:keys => keys})
+          else
+            CouchDB.get url
+          end
+        end 
+        
+        # Deletes all the documents in a given database
+        def delete_all
+          documents['rows'].each do |doc|
+            CouchDB.delete( "#{uri}/#{CGI.escape( doc['id'])}?rev=#{doc['value']['rev']}" ) #rescue nil
+          end  
+        end    
+    
+        # BULK ACTIVITIES ------------------------------------------
+        def add_to_bulk_cache( doc ) 
+          if server.uuid_count/2.0 > bulk_cache.size
+            self.bulk_cache << doc 
+          else
+            bulk_save
+            self.bulk_cache << doc
+          end    
+        end
+    
+        def bulk_save
+          docs = bulk_cache
+          self.bulk_cache = []
+          CouchDB.post( "#{uri}/_bulk_docs", {:docs => docs} )
+        end
+          
+      end # Database       
+    end # CouchDB
+  end # Store  
+end # Aqua