akdubya-cushion 0.5.1

data/lib/cushion.rb

@@ -0,0 +1,97 @@
+require 'json'
+require 'restclient'
+require 'uri'
+
+dir = File.dirname(__FILE__) + '/cushion/'
+
+require dir + 'core_ext'
+require dir + 'server'
+require dir + 'database'
+require dir + 'document'
+require dir + 'design'
+
+DEFAULT_COUCH_HOST = "http://127.0.0.1:5984"
+
+module Cushion
+  VERSION = '0.5.1'
+
+  class << self
+
+    # Returns a Cushion::Server instance.
+    def server(*args)
+      Server.new(*args)
+    end
+    alias_method :new, :server
+
+    # Returns a Cushion::Database instance rooted at +url+. Does not attempt
+    # to create the database on the server.
+    def db(url)
+      parsed = parse(url)
+      server = Cushion.new(parsed[:host])
+      server.db(parsed[:db])
+    end
+    alias_method :database, :db
+
+    # Creates a database at +url+ if it does not exist. Returns a Cushion::Database
+    # instance.
+    def db!(url)
+      parsed = parse(url)
+      server = Cushion.new(parsed[:host])
+      server.db!(parsed[:db])
+    end
+    alias_method :database!, :db!
+
+    # Drops and recreates a database at +url+, returning a Cushion::Database
+    # instance.
+    def recreate(url)
+      parsed = parse(url)
+      server = Cushion.new(parsed[:host])
+      server.recreate(parsed[:db])
+    end
+
+    # Utility method for converting parameters into url query strings.
+    def 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
+
+    # Handles document id escaping.
+    def escape_docid(id)
+      /^_design\/(.*)/ =~ id ? "_design/#{CGI.escape($1)}" : CGI.escape(id)
+    end
+
+    # Base64 encodes inline attachments.
+    def encode_attachments(attachments)
+      attachments.each do |k,v|
+        next if v['stub']
+        v['data'] = base64(v['data'])
+      end
+      attachments
+    end
+
+    def base64(data)
+      Base64.encode64(data).gsub(/\s/,'')
+    end
+    
+    # Sets the RestClient proxy.
+    def proxy(url)
+      RestClient.proxy = url
+    end
+
+    private
+
+    def parse(url)
+      parsed = URI.parse(url)
+      {
+        :host => "#{parsed.scheme}://#{parsed.host}:#{parsed.port}",
+        :db => parsed.path[1, parsed.path.length] # strip off the leading slash
+      }
+    end
+  end # class << self
+end

data/lib/cushion/core_ext.rb

@@ -0,0 +1,27 @@
+# This file must be loaded after the JSON gem and any other library that beats up the Time class.
+class Time
+  # This date format sorts lexicographically
+  # and is compatible with Javascript's <tt>new Date(time_string)</tt> constructor.
+  # Note this this format stores all dates in UTC so that collation
+  # order is preserved. (There's no longer a need to set <tt>ENV['TZ'] = 'UTC'</tt>
+  # in your application.)
+
+  def to_json(options = nil)
+    u = self.utc
+    %("#{u.strftime("%Y/%m/%d %H:%M:%S +0000")}")
+  end
+end
+
+module RestClient
+  def self.copy(url, headers={})
+    Request.execute(:method => :copy,
+      :url => url,
+      :headers => headers)
+  end
+
+  def self.move(url, headers={})
+    Request.execute(:method => :move,
+    :url => url,
+    :headers => headers)
+  end
+end

data/lib/cushion/database.rb

@@ -0,0 +1,310 @@
+require 'cgi'
+require 'base64'
+
+module Cushion
+  class Database
+    attr_reader :server, :name
+
+    def initialize(server, name)
+      raise ArgumentError, "server must be an a Cushion::Server" unless server.kind_of?(Cushion::Server)
+      # TODO: CouchDB has strict db naming requirements. Should validate.
+      @name = CGI.escape(name.to_s)
+      @server = server
+    end
+
+    # Retrieves information about this database.
+    def info(headers = {})
+      server.get(@name, headers)
+    end
+
+    # Compacts this database.
+    def compact(headers = {})
+      server.post("#{@name}/_compact", nil, headers)
+    end
+
+    # Creates this database on the server.
+    def create(headers = {})
+      server.put(@name, nil, headers)
+    end
+
+    # Deletes this database from the server.
+    def delete(headers = {})
+      server.delete(@name, headers)
+    end
+
+    # Query the default +all_docs+ view. Set the +keys+ option to perform a
+    # key-based multi-document fetch. Set the +headers+ option to pass
+    # custom request headers.
+    #
+    def all_docs(params = {})
+      keys = params.delete(:keys)
+      opts = params.delete(:headers) || {}
+      path = Cushion.paramify_url("#{@name}/_all_docs", params)
+      if keys
+        server.post(path, {:keys => keys}, opts)
+      else
+        server.get(path, opts)
+      end
+    end
+
+    # Retrieves a single document by +id+. Set the +headers+ option to pass
+    # custom request headers.
+    def open_doc(id, params = {})
+      opts = params.delete(:headers) || {}
+      slug = Cushion.escape_docid(id)
+      path = Cushion.paramify_url("#{@name}/#{slug}", params)
+      server.get(path, opts)
+    end
+
+    # Retrieves a single document by +id+ and returns a <tt>Cushion::Document</tt>
+    # linked to this database.
+    #
+    def doc(id, params = {})
+      result = open_doc(id, params)
+      ndoc = Cushion::Document.new(result)
+      ndoc.database = self
+      ndoc
+    end
+    alias_method :document, :doc
+
+    # Saves the params hash to the database as a document, encoding inline
+    # attachments and generating a UUID if no +_id+ is supplied. A +_rev+ attribute
+    # must be supplied to update an existing document. Set the +headers+ option
+    # to pass custom request headers.
+    #
+    def save_doc(params = {})
+      opts = params.delete(:headers) || {}
+      if params['_attachments']
+        params['_attachments'] = Cushion.encode_attachments(params['_attachments'])
+      end
+      if params['_id']
+        slug = Cushion.escape_docid(params['_id'])
+        server.put("#{@name}/#{slug}", params, opts)
+      else
+        slug = params['_id'] = server.next_uuid
+        server.put("#{@name}/#{slug}", params, opts)
+      end
+    end
+
+    # Deletes a single document by +id+ and +rev+.
+    def delete_doc(id, rev, headers = {})
+      slug = Cushion.escape_docid(id)
+      server.delete("#{@name}/#{slug}?rev=#{rev}", headers)
+    end
+
+    # Creates, updates and deletes multiple documents in this database according
+    # to the supplied +docs+ array. Set the +_deleted+ attribute to true to delete
+    # an individual doc. Set the +_rev+ attribute to update an individual doc. Leave
+    # out the +_rev+ attribute to create a new doc. Example:
+    #
+    #   docs = [
+    #     { "_id" => "0", "_rev" => "123456", "_deleted" => true }, #=> Delete this doc
+    #     { "_id" => "1", "_rev" => "32486671", "foo" => "bar" },   #=> Update this doc
+    #     { "_id" => "2", "baz" => "bat" }                          #=> Create this doc
+    #   ]
+    #   
+    #   db.bulk_docs(docs)
+    #
+    # +bulk_docs+ returns a hash of updated doc ids and revs, as follows:
+    #
+    #   {
+    #     "ok" => true,
+    #     "new_revs" => [
+    #       { "id" => "0", "rev" => "3682408536" },
+    #       { "id" => "1", "rev" => "3206753266" },
+    #       { "id" => "2", "rev" => "426742535" }
+    #     ]
+    #   }
+    #
+    # Set the +use_uuids+ option to generate UUIDs from the server cache before
+    # saveing. Set the +headers+ option to pass custom request headers.
+    #
+    def bulk_docs(docs, params = {})
+      headers = params.delete(:headers) || {}
+      opts = { :use_uuids => true }.merge(params)
+      if (opts[:use_uuids])
+        ids, noids = docs.partition{|d|d['_id']}
+        uuid_count = [noids.length, server.uuid_batch_count].max
+        noids.each do |doc|
+          nextid = server.next_uuid(uuid_count) rescue nil
+          doc['_id'] = nextid if nextid
+        end
+      end
+      server.post("#{@name}/_bulk_docs", {:docs => docs}, headers)
+    end
+
+    # A convenience method for deleting multiple documents at once. Just pass in
+    # an array of saved +docs+ and the correct deletion params are
+    # automatically set. (See #bulk_docs)
+    #
+    def bulk_delete(docs, params = {})
+      deletions = docs.map { |doc| { '_id' => doc['_id'], '_rev' => doc['_rev'], '_deleted' => true } }
+      bulk_docs(deletions, params.merge(:use_uuids => false))
+    end
+
+    # Completely purges the supplied document revisions from the database.
+    # +doc_revs+ is a hash of document ids, each containing an array of revisions
+    # to be deleted. Example:
+    # 
+    #   doc_revs = {
+    #     "1" => ["12345", "42836"],
+    #     "2" => ["572654"],
+    #     "3" => ["34462"]
+    #   }
+    #
+    #  db.purge(doc_revs)
+    #
+    def purge(doc_revs, headers = {})
+      server.post("#{@name}/_purge", doc_revs, headers)
+    end
+
+    # Copies the document identified by +source_id+ to a new or existing document
+    # at +destination_id+. Set the +dest_rev+ option to overwrite an existing doc.
+    # Set the +headers+ option to pass custom request headers.
+    #
+    def copy_doc(source_id, dest_id, params = {})
+      headers = params.delete(:headers) || {}
+      dest_rev = params[:dest_rev]
+      slug = Cushion.escape_docid(source_id)
+      destination = if dest_rev
+        "#{dest_id}?rev=#{dest_rev}"
+      else
+        dest_id
+      end
+      server.copy("#{@name}/#{slug}", destination, headers)
+    end
+
+    # Moves the document identified by +source_id+ and +src_rev+ to a new or
+    # existing document at +destination_id+. Set the +dest_rev+ option to
+    # overwrite an existing doc. Set the +headers+ option to pass custom
+    # request headers.
+    #
+    def move_doc(source_id, dest_id, src_rev, params = {})
+      headers = params.delete(:headers) || {}
+      dest_rev = params[:dest_rev]
+      slug = Cushion.escape_docid(source_id)
+      destination = if dest_rev
+        "#{dest_id}?rev=#{dest_rev}"
+      else
+        dest_id
+      end
+      server.move("#{@name}/#{slug}?rev=#{src_rev}", destination, headers)
+    end
+
+    # Supply +funcs+ to create a temporary view and run a query against it. Set
+    # the +keys+ option to perform a key-based multi-document fetch against the
+    # temp view. Example:
+    #
+    #   temp_view = { :map => "function(doc){emit(doc.status,null)}" }
+    #   db.temp_view(temp_view, :key => "verified")
+    #
+    # Set the +headers+ option to pass custom request headers.
+    #
+    # Temp view queries are slow, so they should only be used as a convenience
+    # during development.
+    #
+    def temp_view(funcs, params = {})
+      keys = params.delete(:keys)
+      headers = params.delete(:headers) || {}
+      funcs = funcs.merge({:keys => keys}) if keys
+      path = Cushion.paramify_url("#{@name}/_temp_view", params)
+      server.post(path, funcs, headers)
+    end
+
+    # Query a saved view identified by +view+. Set the +keys+ param to perform a
+    # key-based multi-document fetch. Example:
+    #
+    #   db.view("people/by_first_name", :key => "gomer")
+    #
+    # Set the +headers+ option to pass custom request headers.
+    #
+    def view(view, params = {})
+      keys = params.delete(:keys)
+      headers = params.delete(:headers) || {}
+      path = Cushion.paramify_url("#{@name}/_view/#{view}", params)
+      if keys
+        server.post(path, {:keys => keys}, headers)
+      else
+        server.get(path, headers)
+      end
+    end
+
+    # Query the show template identified by +design+, +show_template+ and +id+.
+    # The results are not parsed by default. Set the +headers+ option to pass
+    # custom request headers.
+    #
+    def show(design, show_template, id, params = {})
+      defaults = { :accept => "text/html;text/plain;*/*" }
+      headers = params.delete(:headers) || {}
+      slug = Cushion.escape_docid(id)
+      path = Cushion.paramify_url("#{@name}/_show/#{design}/#{show_template}/#{slug}", params)
+      server.get(path, defaults.merge(headers))
+    end
+
+    # Query the list template identified by +design+, +list_template+ and +view+.
+    # The results are not parsed by default. Set the +headers+ option to pass
+    # custom request headers.
+    #
+    def list(design, list_template, view, params = {})
+      defaults = { :accept => "text/html;text/plain;*/*" }
+      headers = params.delete(:headers) || {}
+      path = Cushion.paramify_url("#{@name}/_list/#{design}/#{list_template}/#{view}", params)
+      server.get(path, defaults.merge(headers))
+    end
+
+    # Issues a request to the CouchDB external server identified by +process+.
+    # Calls to external must include a request +verb+. Set the +headers+ option
+    # to pass custom request headers.
+    #
+    def external(verb, process_path, params = {})
+      path = Cushion.paramify_url("_#{process_path}", params[:query])
+      server.request(verb, path, :body => params[:body], :headers => params[:headers])
+    end
+
+    # Uses open-uri to open the attachment identified by +id+ and +filename+.
+    # Returns a Tempfile.
+    #
+    def open_attachment(id, filename, params = {})
+      slug = Cushion.escape_docid(id)
+      fname = CGI.escape(filename)
+      path = Cushion.paramify_url("#{@name}/#{slug}/#{fname}", params)
+      server.open_attachment(path)
+    end
+
+    # Saves an attachment under the document identified by +id+ and +rev+ with
+    # the supplied +filename+ and +data+. Content type defaults to
+    # 'application/octet-stream'. Change it by passing <code>:content_type => "foo/bar"</code>
+    # as the last param.
+    #
+    def save_attachment(id, rev, filename, data, headers = {})
+      defaults = { :content_type => "application/octet-stream" }
+      slug = Cushion.escape_docid(id)
+      fname = CGI.escape(filename)
+      server.put("#{@name}/#{slug}/#{fname}?rev=#{rev}", data, defaults.merge(headers))
+    end
+
+    # Deletes an attachment under the document identified by +id+ and +rev+ with
+    # the supplied +filename+.
+    #
+    def delete_attachment(id, rev, filename, headers = {})
+      slug = Cushion.escape_docid(id)
+      fname = CGI.escape(filename)
+      server.delete("#{@name}/#{slug}/#{fname}?rev=#{rev}", headers)
+    end
+
+    # Renames an attachment under the document identified by +id+ and +rev+.
+    # +oldname+ is the name of the existing attachment and +newname+ is the
+    # desired name.
+    #
+    def rename_attachment(id, rev, oldname, newname)
+      temp = open_attachment(id, oldname)
+      res = save_attachment(id, rev, newname, temp.read, :content_type => temp.content_type)
+      if res["ok"] == true
+        res = delete_attachment(id, res["rev"], oldname)
+      else
+        res
+      end
+    end
+
+  end
+end

data/lib/cushion/design.rb

@@ -0,0 +1,33 @@
+module Cushion  
+  class Design < Document
+    def view(view_name, query={})
+      view_name = view_name.to_s
+      view_slug = "#{name}/#{view_name}"
+      defaults = (self['views'][view_name] && self['views'][view_name]["couchrest-defaults"]) || {}
+      database.view(view_slug, defaults.merge(query))
+    end
+
+    def name
+      id.sub('_design/','') if id
+    end
+
+    def name=(newname)
+      self['_id'] = "_design/#{newname}"
+    end
+
+    def language
+      self['language']
+    end
+
+    # Sets this design document's language.
+    def language=(lang)
+      self['language'] = lang
+    end
+
+    def save
+      raise ArgumentError, "_design docs require a name" unless name && name.length > 0
+      self.language = "javascript" unless language
+      super
+    end
+  end
+end