couch-client 0.0.1

data/lib/couch-client/connection_handler.rb

@@ -0,0 +1,70 @@
+require 'cgi'
+
+module CouchClient
+  class InvalidPathObject < Exception; end
+  class InvalidQueryObject < Exception; end
+  class InvalidDatabaseName < Exception; end
+  
+  # The ConnectionHandler creates properly formed URIs and paths, while also
+  # specifying sensible defaults for CouchDB.  Once initialized, parameters
+  # can be wrote and read using getter and setter syntax.
+  class ConnectionHandler
+    attr_accessor :scheme, :username, :password, :host, :port
+    attr_reader :database
+    
+    # ConnectionHandler is constructed without any parameters, and with defaults
+    # for scheme, host and port.  Other settings are set via the accessors above.
+    def initialize
+      @scheme = "http"
+      @host = "localhost"
+      @port = 5984
+    end
+    
+    # Sets the database and ensures that it follows proper naming conventions.
+    def database=(database)
+      if database.match(/^[a-z0-9_$()+-\/]+$/)
+        @database = database
+      else
+        raise InvalidDatabaseName.new("only lowercase characters (a-z), digits (0-9), or _, $, (, ), +, - and / are allowed.")
+      end
+    end
+    
+    # Creates a properly formed URI that can be used by a HTTP library.
+    def uri(path_obj = nil, query_obj = nil)
+      str  = "#{@scheme}://#{@host}:#{@port}"
+      str += path(path_obj, query_obj)
+      str
+    end
+    
+    # Creates a properly formed path that can be used by a HTTP library.
+    # `path_obj` can be an Array or NilClass, `query_obj` can be Hash or NilClass.
+    def path(path_obj = nil, query_obj = nil)
+      path_obj  ||= []
+      query_obj ||= {}
+      
+      path_str = if path_obj.is_a?(Array)
+        # If an Array, stringify and escape (unless it is a design document) each object and join with a "/"
+        ([@database] + path_obj).map{|p| p.to_s.match(/_design\//) ? p.to_s : CGI.escape(p.to_s)}.join("/")
+      else
+        # Else, raise an error
+        raise InvalidPathObject.new("path must be of type 'Array' not of type '#{path_obj.class}'")
+      end
+      
+      query_str = if query_obj.is_a?(Hash)
+        # If a Hash, stringify and escape each object, join each key/value with a "=" and each pair with a "&"
+        query_obj.to_a.map{|q| q.map{|r| CGI.escape(r.to_s)}.join("=")}.join("&")
+      else
+        # Else, raise an error
+        raise InvalidQueryObject.new("path must be of type 'Hash' or 'NilClass' not of type '#{query_obj.class}'")
+      end
+      
+      str  = "/" + path_str
+      str += "?" + query_str unless query_str.empty?
+      str
+    end
+
+    def inspect
+      "#<#{self.class}>"
+    end
+  end
+end

data/lib/couch-client/consistent_hash.rb

@@ -0,0 +1,98 @@
+module CouchClient
+  # ConsistentHash allows indifferent access with either with symbols or strings
+  # while also converting symbol values in Arrays or Hashes into strings values.
+  #
+  # ConsistentHash only overides methods that already exist in the Hash class;
+  # see the documentation in the Ruby core API for clarification and examples.
+  #
+  # This code was is heavily influenced by ActiveSupport::HashWithIndifferentAccess.
+  class ConsistentHash < Hash
+    # ConsistentHash is constructed with either a Hash or a default value.  When
+    # a Hash is given, a new ConsistentHash is constructed with the same default
+    # value.  When any other value is given it will be set as the default value.
+    def initialize(hash = {})
+      if hash.is_a?(Hash)
+        super()
+        update(hash).tap do |new_hash|
+          new_hash.default = hash.default
+        end
+      else
+        super(hash)
+      end
+    end
+
+    def default(key = nil)
+      if key.is_a?(Symbol) && include?(key = key.to_s)
+        self[key]
+      else
+        super
+      end
+    end
+
+    alias_method :regular_writer, :[]= unless method_defined?(:regular_writer)
+    alias_method :regular_update, :update unless method_defined?(:regular_update)
+
+    def []=(key, value)
+      regular_writer(convert_key(key), convert_value(value))
+    end
+
+    def update(other_hash)
+      other_hash.each_pair do |key, value| 
+        regular_writer(convert_key(key), convert_value(value))
+      end
+      self
+    end
+
+    alias_method :merge!, :update
+
+    def key?(key)
+      super(convert_key(key))
+    end
+
+    alias_method :include?, :key?
+    alias_method :has_key?, :key?
+    alias_method :member?, :key?
+
+    def fetch(key, *extras)
+      super(convert_key(key), *extras)
+    end
+
+    def values_at(*indices)
+      indices.collect {|key| self[convert_key(key)]}
+    end
+
+    def dup
+      ConsistentHash.new(self)
+    end
+
+    def merge(hash)
+      dup.update(hash)
+    end
+
+    def delete(key)
+      super(convert_key(key))
+    end
+
+    def to_hash
+      Hash.new(default).merge!(self)
+    end
+
+    protected
+
+    def convert_key(key)
+      key.is_a?(Symbol) ? key.to_s : key
+    end
+
+    def convert_value(value)
+      if value.instance_of?(Hash)
+        ConsistentHash.new(value)
+      elsif value.instance_of?(Symbol)
+        value.to_s
+      elsif value.instance_of?(Array)
+        value.collect{|e| convert_value(e)}
+      else
+        value
+      end
+    end
+  end
+end

data/lib/couch-client/database.rb

@@ -0,0 +1,39 @@
+module CouchClient
+  # The Database is just a organized collection of functions that interact with the
+  # CouchDB database such as stats, creation, compaction, replication and deletion.
+  class Database
+    # Database is constructed with a connection that is used to make HTTP requests to the server.
+    def initialize(connection)
+      @connection = connection
+    end
+    
+    def stats
+      @connection.hookup.get.last
+    end
+    
+    def exists?
+      @connection.hookup.get.first == 200
+    end
+    
+    def create
+      @connection.hookup.put.last
+    end
+    
+    def delete!
+      @connection.hookup.delete.last
+    end
+    
+    def compact!
+      @connection.hookup.post(["_compact"]).last
+    end
+    
+    # TODO: add replicate method
+    def replicate
+      raise "pending"
+    end
+    
+    def inspect
+      "#<#{self.class}>"
+    end
+  end
+end

data/lib/couch-client/design.rb

@@ -0,0 +1,79 @@
+module CouchClient
+  class ViewNotFound < Exception; end
+  class ShowNotFound < Exception; end
+  class ListNotFound < Exception; end
+  class FullTextNotFound < Exception; end
+  
+  # The Design is the interface used to interact with design documents
+  # in order make view, show, list and fulltext requests.
+  class Design
+    attr_accessor :id
+    
+    # Design is constructed with an id of the design documemnt and
+    # a connection that is used to make HTTP requests to the server.
+    def initialize(id, connection)
+      @id = id
+      @connection = connection
+    end
+
+    # Makes requests to the server that return mappped/reduced view collections.
+    def view(name, options = {})
+      # key, startkey and endkey must be JSON encoded
+      ["key", "startkey", "endkey"].each do |key|
+        options[key] &&= options[key].to_json
+      end
+
+      code, body = @connection.hookup.get(["_design", id, "_view", name], options)
+
+      case code
+      when 200
+        # Return a Collection if results were found
+        Collection.new(code, body, @connection)
+      when 404
+        # Raise an error if nothing was found
+        raise ViewNotFound.new("could not find view field '#{name}' for design '#{id}'")
+      else
+        # Also raise an error if something else happens
+        raise Error.new("code: #{code}, error: #{body["error"]}, reason: #{body["reason"]}")
+      end
+    end
+
+    # TODO: add show method
+    def show(name, options = {})
+      raise "pending"
+    end
+
+    # TODO: add list method
+    def list(name, options = {})
+      raise "pending"
+    end
+    
+    # Makes requests to the server that return lucene search results.
+    def fulltext(name, options = {})
+      code, body = @connection.hookup.get(["_fti", "_design", id, name], options)
+
+      case code
+      when 200
+        if body["rows"]
+          # Return a serch result if a query was provided
+          Collection.new(code, body, self)
+        else
+          # Return a status hash if a query was not provided
+          body
+        end
+      else
+        if body["reason"] == "no_such_view"
+          # Raise an error if a fulltext function was not found
+          raise FullTextNotFound.new("could not find fulltext field '#{name}' for design '#{id}'")
+        else
+          # Also raise an error if something else happens 
+          raise Error.new("code: #{code}, error: #{body["error"]}, reason: #{body["reason"]}")
+        end
+      end
+    end
+
+    def inspect
+      "#<#{self.class}: id: #{@id}>"
+    end
+  end
+end

data/lib/couch-client/document.rb

@@ -0,0 +1,151 @@
+module CouchClient
+  class InvalidId < Exception; end
+  class AttachmentError < Exception; end
+  class DocumentNotAvailable < Exception; end
+  
+  # The Document is an extended Hash that provides additional methods to
+  # save, update (with attachments), and delete documents on the CouchDB.
+  class Document < ConsistentHash
+    attr_reader :code, :error
+
+    # Document is constructed with a status code, response body,
+    # connection object and a flag stating if the document has been deleted.
+    def initialize(code, body, connection, deleted = false)
+      self.merge!(body)
+
+      @code = code
+      @error = {}
+      @connection = connection
+      @deleted = deleted
+
+      if self.attachments
+        self.attachments = AttachmentList.new(attachments)
+        
+        self.attachments.keys.each do |key|
+          self.attachments[key] = Attachment.new(id, key, attachments[key], @connection)
+        end
+      end
+    end
+
+    # Hookup#(id|id=|rev|rev=|attachments|attachments=) are convenience methods
+    # that correspond to ["_id"], ["_rev"] and ["_attachments"] document fields.
+    ["id", "rev", "attachments"].each do |method|
+      define_method(method) do
+        self["_#{method}"]
+      end
+
+      define_method("#{method}=") do |value|
+        self["_#{method}"] = value
+      end
+    end
+    
+    # Returns a copy of the same document that is currently saved on the server.
+    def saved_doc(query = {})
+      if new?
+        raise DocumentNotAvailable.new('this document is new and therefore has not been saved yet')
+      else
+        @connection[self.id, query]
+      end
+    end
+
+    # Tries to save the document to the server.  If it us unable to,
+    # it will save the error and make it available with via #error.
+    def save
+      # Ensure that "_id" is a String if it is defined.
+      if self.key?("_id") && !self["_id"].is_a?(String)
+        raise InvalidId.new("document _id must be a String")
+      end
+      
+      # Documents without an id must use post, with an id must use put
+      @code, body = if self.id
+        @connection.hookup.put([self.id], nil, self)
+      else
+        @connection.hookup.post(nil, nil, self)
+      end
+      
+      # If the document was saved
+      if body["ok"]
+        # Update id and rev, ensure the deleted flag is set to `false` and return `true`
+        self.id ||= body["id"]
+        self.rev  = body["rev"]
+        @deleted  = false
+        true
+      else
+        # Save error message and return `false`.
+        @error = {body["error"] => body["reason"]}
+        false
+      end
+    end
+
+    # Tries to attach a file to the document.  If it us unable to,
+    # it will save the error and make it available with via #error.
+    def attach(name, content, content_type)
+      # The document must already be saved to the server before a file can be attached.
+      if self.rev
+        @code, body = @connection.hookup.put([self.id, name], {"rev" => self.rev}, content, content_type)
+        
+        # If the document was saved
+        if body["ok"]
+          # Update rev and return `true`
+          self.rev = body["rev"]
+          true
+        else
+          # Save error message and return `false`.
+          @error = {body["error"] => body["reason"]}
+          false
+        end
+      else
+        # Raise an error if the document is new before trying to attach a file.
+        raise AttachmentError.new("a document must exist before an attachment can be uploaded to it")
+      end
+    end
+    
+    # Tries to delete a file from the server.  If it us unable to,
+    # it will save the error and make it available with via #error.
+    def delete!
+      @code, body = @connection.hookup.delete([id], {"rev" => rev})
+      
+      # If the document was deleted
+      if body["ok"]
+        # Update the rev, set the deleted flag to `true` and return `true`
+        self.rev = body["rev"]
+        @deleted = true
+        true
+      else
+        # Save error message and return `false`.
+        @error = {body["error"] => body["reason"]}
+        false
+      end
+    end
+
+    # Identifies the document as a design document
+    def design?
+      !!self.id.match(/_design\//) # Design documents start with "_design/"
+    end
+    
+    # Identifies the document as not yet being saved to the server
+    def new?
+      !rev
+    end
+
+    # Identifies that there are currently errors that must be resolved
+    def error?
+      !@error.empty?
+    end
+    
+    # Identifies that the document does not yet pass a `validate_on_update` function
+    def invalid?
+      @code == 403 && @error["forbidden"]
+    end
+    
+    # Identifies that the document cannot be saved due to conflicts
+    def conflict?
+      !!@error["conflict"]
+    end
+
+    # Identifies that the document has been deleted
+    def deleted?
+      @deleted
+    end
+  end
+end

data/lib/couch-client/hookup.rb

@@ -0,0 +1,107 @@
+require 'curb'
+require 'json'
+
+module CouchClient
+  class InvalidHTTPVerb < Exception; end
+  class InvalidJSONData < Exception; end
+  class SymbolUsedInField < Exception; end
+
+  # The Hookup is the basic HTTP interface that connects CouchClient to CouchDB.
+  # Hookup can use any HTTP library if the conventions listed below are followed.
+  #
+  # If modified, Hookup must have head, get, post, put and delete instance methods.
+  class Hookup
+    attr_reader :handler
+    
+    # Hookup is constructed with a connection handler, which formats the 
+    # proper URIs with a domain, authentication, path and query string.
+    def initialize(handler)
+      @handler = handler
+    end
+    
+    # Hookup#(head|get|delete) has the following method signature
+    #   hookup.verb(["path", "name"], {"query_key" => "query_value"}, "content/type")
+    #
+    # And has the following response
+    #   [code, {"data_key" => "data_value"}]
+    #
+    # Except, if the verb is `head`, which has the following response
+    #   [code, nil]
+    #
+    # Or, if the verb is `get` and content_type is not "application/json", which has the following response
+    #   [code, "string containing file data"]
+    #
+    # By default path is nil, query is nil, and content_type is "application/json"
+    [:head, :get, :delete].each do |verb|
+      define_method(verb) do |*args|
+        # These methods do not have a body parameter. As such, the following
+        # prevents setting content_type to nil instead not setting it at all.
+        params = [verb, args.shift, args.shift, nil]
+        params << args.shift unless args.empty?
+        curl(*params)
+      end
+    end
+    
+    # Hookup#(post|put) has the following method signature
+    #   hookup.verb(["path", "name"], {"query_key" => "query_value"}, {"data_key" => "data_value"}, "content/type")
+    #
+    # And has the following response
+    #   [code, {"data_key" => "data_value"}]
+    #
+    # By default path is nil, query is nil, data is {} and content_type is "application/json"
+    [:post, :put].each do |verb|
+      define_method(verb) do |*args|
+        curl(verb, *args)
+      end
+    end
+
+    def inspect
+      "#<#{self.class}>"
+    end
+    
+    private
+    
+    # This is the method that actually makes curl request for each verb method listed above.
+    def curl(verb, path = nil, query = nil, data = {}, content_type = "application/json")
+      # Setup curb options block
+      options = lambda do |easy|
+        easy.headers["User-Agent"] = "couch-client v#{VERSION}"
+        easy.headers["Content-Type"] = content_type if content_type
+        easy.headers["Accepts"] = content_type if content_type
+        easy.username = handler.username
+        easy.userpwd  = handler.password
+      end
+      
+      easy = case verb
+      when :head, :get, :delete
+        # head, get and delete http methods only take a uri string and options block
+        Curl::Easy.send("http_#{verb}", handler.uri(path, query), &options)
+      when :post, :put
+        # post and put http methods take a uri string, data string and options block
+        # also convert the hash into json if the content_type of the request is json
+        data = data.to_json if content_type == "application/json"
+        Curl::Easy.send("http_#{verb}", handler.uri(path, query), data, &options)
+      else
+        raise InvalidHTTPVerb.new("only `head`, `get`, `post`, `put` and `delete` are supported")
+      end
+      
+      # code is the http code (e.g. 200 or 404)
+      code = easy.response_code
+      
+      # body is either a nil, a hash or a string containing attachment data
+      body = if easy.body_str == "" || easy.body_str.nil?
+        nil
+      elsif content_type == "application/json" || [:post, :put, :delete].include?(verb)
+        begin
+          JSON.parse(easy.body_str)
+        rescue
+          raise InvalidJSONData.new("document received is not valid JSON")
+        end
+      else
+        easy.body_str
+      end
+      
+      [code, body]
+    end
+  end
+end