peterpunk-couchrest 0.23.1 → 0.33

data/README.md

@@ -1,7 +1,7 @@
 # CouchRest: CouchDB, close to the metal
 
 CouchRest is based on [CouchDB's couch.js test
-library](http://svn.apache.org/repos/asf/incubator/couchdb/trunk/share/www/script/couch.js),
+library](http://svn.apache.org/repos/asf/couchdb/trunk/share/www/script/couch.js),
 which I find to be concise, clear, and well designed. CouchRest lightly wraps
 CouchDB's HTTP API, managing JSON serialization, and remembering the URI-paths
 to CouchDB's API endpoints so you don't have to.
@@ -12,14 +12,17 @@ Note: CouchRest only support CouchDB 0.9.0 or newer.
 
 ## Easy Install
 
-Easy Install is moving to RubyForge, heads up for the gem.
+    $ sudo gem install couchrest
+   
+Alternatively, you can install from Github:
+    
+    $ gem sources -a http://gems.github.com (you only have to do this once)
+    $ sudo gem install couchrest-couchrest
 
 ### Relax, it's RESTful
 
-The core of Couchrest is Heroku’s excellent REST Client Ruby HTTP wrapper.
-REST Client takes all the nastyness of Net::HTTP and gives is a pretty face,
-while still giving you more control than Open-URI. I recommend it anytime
-you’re interfacing with a well-defined web service.
+CouchRest rests on top of a HTTP abstraction layer using by default Heroku’s excellent REST Client Ruby HTTP wrapper.
+Other adapters can be added to support more http libraries.
 
 ### Running the Specs
 
@@ -27,7 +30,7 @@ The most complete documentation is the spec/ directory. To validate your
 CouchRest install, from the project root directory run `rake`, or `autotest`
 (requires RSpec and optionally ZenTest for autotest support).
 
-## Examples
+## Examples (CouchRest Core)
 
 Quick Start:
 
@@ -59,12 +62,50 @@ Creating and Querying Views:
       })
     puts @db.view('first/test')['rows'].inspect 
 
-## CouchRest::Model
 
-CouchRest::Model has been deprecated and replaced by CouchRest::ExtendedDocument
+## CouchRest::ExtendedDocument  
+
+CouchRest::ExtendedDocument is a DSL/ORM for CouchDB. Basically, ExtendedDocument seats on top of CouchRest Core to add the concept of Model.
+ExtendedDocument offers a lot of the usual ORM tools such as optional yet defined schema, validation, callbacks, pagination, casting and much more.
+
+### Model example
+
+Check spec/couchrest/more and spec/fixtures/more for more examples
+
+    class Article < CouchRest::ExtendedDocument
+      use_database DB
+      unique_id :slug
 
+      view_by :date, :descending => true
+      view_by :user_id, :date
 
-## CouchRest::ExtendedDocument
+      view_by :tags,
+        :map => 
+          "function(doc) {
+            if (doc['couchrest-type'] == 'Article' && doc.tags) {
+              doc.tags.forEach(function(tag){
+                emit(tag, 1);
+              });
+            }
+          }",
+        :reduce => 
+          "function(keys, values, rereduce) {
+            return sum(values);
+          }"  
+
+      property :date
+      property :slug, :read_only => true
+      property :title
+      property :tags, :cast_as => ['String']
+
+      timestamps!
+
+      save_callback :before, :generate_slug_from_title
+
+      def generate_slug_from_title
+        self['slug'] = title.downcase.gsub(/[^a-z0-9]/,'-').squeeze('-').gsub(/^\-|\-$/,'') if new_document?
+      end
+    end
 
 ### Callbacks
 
@@ -93,3 +134,32 @@ you can define some casting rules.
 
 If you want to cast an array of instances from a specific Class, use the trick shown above ["ClassName"]
 
+### Pagination
+
+Pagination is available in any ExtendedDocument classes. Here are some usage examples:
+
+basic usage:
+
+    Article.all.paginate(:page => 1, :per_page => 5)
+    
+note: the above query will look like: `GET /db/_design/Article/_view/all?include_docs=true&skip=0&limit=5&reduce=false` and only fetch 5 documents. 
+    
+Slightly more advance usage:
+  
+    Article.by_name(:startkey => 'a', :endkey => {}).paginate(:page => 1, :per_page => 5)
+    
+note: the above query will look like: `GET /db/_design/Article/_view/by_name?startkey=%22a%22&limit=5&skip=0&endkey=%7B%7D&include_docs=true`    
+Basically, you can paginate through the articles starting by the letter a, 5 articles at a time.
+
+
+Low level usage:        
+
+    Article.paginate(:design_doc => 'Article', :view_name => 'by_date',
+      :per_page => 3, :page => 2, :descending => true, :key => Date.today, :include_docs => true)
+      
+      
+## Ruby on Rails
+
+CouchRest is compatible with rails and can even be used a Rails plugin.
+However, you might be interested in the CouchRest companion rails project:
+[http://github.com/hpoydar/couchrest-rails](http://github.com/hpoydar/couchrest-rails)      

data/Rakefile

@@ -24,12 +24,11 @@ spec = Gem::Specification.new do |s|
   s.description = "CouchRest provides a simple interface on top of CouchDB's RESTful HTTP API, as well as including some utility scripts for managing views and attachments."
   s.has_rdoc = true
   s.authors = ["J. Chris Anderson", "Matt Aimonetti"]
-  s.files = %w( LICENSE README.md Rakefile THANKS.md ) + 
+  s.files = %w( LICENSE README.md Rakefile THANKS.md history.txt) + 
     Dir["{examples,lib,spec,utils}/**/*"] - 
     Dir["spec/tmp"]
   s.extra_rdoc_files = %w( README.md LICENSE THANKS.md )
   s.require_path = "lib"
-  s.add_dependency("json", ">= 1.1.2")
   s.add_dependency("rest-client", ">= 0.5")
   s.add_dependency("mime-types", ">= 1.15")
 end
@@ -54,6 +53,7 @@ end
 
 desc "Run all specs"
 Spec::Rake::SpecTask.new('spec') do |t|
+	t.spec_opts = ["--color"]
 	t.spec_files = FileList['spec/**/*_spec.rb']
 end
 

data/history.txt

@@ -0,0 +1,63 @@
+== 0.33
+
+* Major enhancements
+
+  * Added a new Rack logger middleware letting you log/save requests/queries (Matt Aimonetti)
+  
+* Minor enhancements 
+  
+  * Added #amount_pages to a paginated result array (Matt Aimonetti)
+  * Ruby 1.9.2 compatible (Matt Aimonetti)
+  * Added a property? method for property cast as :boolean (John Wood)
+  * Added an option to force the deletion of a attachments (bypass 409s) (Matt Aimonetti)
+  * Created a new abstraction layer for the REST API (Matt Aimonetti)
+  * Bug fix: made ExtendedDocument#all compatible with Couch 0.10 (tc)
+
+== 0.32
+  
+* Major enhancements
+
+  * ExtendedDocument.get doesn't raise an exception anymore. If no documents are found nil is returned.
+  * ExtendedDocument.get! works the say #get used to work and will raise an exception if a document isn't found.
+  
+* Minor enhancements  
+   
+  * Bug fix: Model.all(:keys => [1,2]) was not working (Matt Aimonetti)
+  * Added ValidationErrors#count in order to play nicely with Rails (Peter Wagenet)
+  * Bug fix: class proxy design doc refresh (Daniel Kirsh)
+  * Bug fix: the count method on the proxy collection was missing (Daniel Kirsch)
+  * Added #amount_pages to a paginated collection. (Matt Aimonetti)
+
+== 0.31
+
+* Major enhancements
+
+  * Created an abstraction HTTP layer to support different http adapters (Matt Aimonetti)
+  * Added ExtendedDocument.create({}) and #create!({}) so you don't have to do Model.new.create (Matt Aimonetti)
+  
+* Minor enhancements
+  
+  * Added an init.rb file for easy usage as a Rails plugin (Aaron Quint)
+  * Bug fix: pagination shouldn't die on empty results (Arnaud Berthomier)
+  * Optimized ExtendedDocument.count to run about 3x faster (Matt Aimonetti)
+  * Added Float casting (Ryan Felton & Matt Aimonetti)
+
+== 0.30
+ 
+* Major enhancements
+ 
+  * Added support for pagination (John Wood)
+  * Improved performance when initializing documents with timestamps (Matt Aimonetti)
+ 
+* Minor enhancements
+ 
+  * Extended the API to retrieve an attachment URI (Matt Aimonetti)
+  * Bug fix: default value should be able to be set as false (Alexander Uvarov)
+  * Bug fix: validates_is_numeric should be able to properly validate a Float instance (Rob Kaufman)
+  * Bug fix: fixed the Timeout implementation (Seth Falcon)
+  
+  
+---
+
+Unfortunately, before 0.30 we did not keep a track of the modifications made to CouchRest.
+You can see the full commit history on GitHub: http://github.com/couchrest/couchrest/commits/master/

data/lib/couchrest/core/adapters/restclient.rb

@@ -0,0 +1,35 @@
+module RestClientAdapter
+   
+  module API
+    def proxy=(url)
+      RestClient.proxy = url
+    end 
+    
+    def proxy
+      RestClient.proxy
+    end
+  
+    def get(uri, headers={})
+      RestClient.get(uri, headers)
+    end
+  
+    def post(uri, payload, headers={})
+      RestClient.post(uri, payload, headers)
+    end
+  
+    def put(uri, payload, headers={})
+      RestClient.put(uri, payload, headers)
+    end
+  
+    def delete(uri, headers={})
+      RestClient.delete(uri, headers)
+    end
+  
+    def copy(uri, headers)
+      RestClient::Request.execute(  :method   => :copy,
+                                    :url      => uri,
+                                    :headers  => headers) 
+    end
+  end 
+  
+end

data/lib/couchrest/core/database.rb

@@ -17,7 +17,8 @@ module CouchRest
       @name = name
       @server = server
       @host = server.uri
-      @uri = @root = "#{host}/#{name.gsub('/','%2F')}"
+      @uri  = "/#{name.gsub('/','%2F')}"
+      @root = host + uri
       @streamer = Streamer.new(self)
       @bulk_save_cache = []
       @bulk_save_cache_limit = 500  # must be smaller than the uuid count
@@ -25,18 +26,18 @@ module CouchRest
     
     # returns the database's uri
     def to_s
-      @uri
+      @root
     end
     
     # GET the database info from CouchDB
     def info
-      CouchRest.get @uri
+      CouchRest.get @root
     end
     
     # Query the <tt>_all_docs</tt> view. Accepts all the same arguments as view.
     def documents(params = {})
       keys = params.delete(:keys)
-      url = CouchRest.paramify_url "#{@uri}/_all_docs", params
+      url = CouchRest.paramify_url "#{@root}/_all_docs", params
       if keys
         CouchRest.post(url, {:keys => keys})
       else
@@ -48,6 +49,7 @@ module CouchRest
     def get_bulk(ids)
       documents(:keys => ids, :include_docs => true)
     end
+    alias :bulk_load :get_bulk
   
     # POST a temporary view function to CouchDB for querying. This is not
     # recommended, as you don't get any performance benefit from CouchDB's
@@ -55,8 +57,8 @@ module CouchRest
     def slow_view(funcs, params = {})
       keys = params.delete(:keys)
       funcs = funcs.merge({:keys => keys}) if keys
-      url = CouchRest.paramify_url "#{@uri}/_temp_view", params
-      JSON.parse(RestClient.post(url, funcs.to_json, {"Content-Type" => 'application/json'}))
+      url = CouchRest.paramify_url "#{@root}/_temp_view", params
+      JSON.parse(HttpAbstraction.post(url, funcs.to_json, {"Content-Type" => 'application/json'}))
     end
     
     # backwards compatibility is a plus
@@ -69,7 +71,7 @@ module CouchRest
       name = name.split('/') # I think this will always be length == 2, but maybe not...
       dname = name.shift
       vname = name.join('/')
-      url = CouchRest.paramify_url "#{@uri}/_design/#{dname}/_view/#{vname}", params
+      url = CouchRest.paramify_url "#{@root}/_design/#{dname}/_view/#{vname}", params
       if keys
         CouchRest.post(url, {:keys => keys})
       else
@@ -84,7 +86,7 @@ module CouchRest
     # GET a document from CouchDB, by id. Returns a Ruby Hash.
     def get(id, params = {})
       slug = escape_docid(id)
-      url = CouchRest.paramify_url("#{@uri}/#{slug}", params)
+      url = CouchRest.paramify_url("#{@root}/#{slug}", params)
       result = CouchRest.get(url)
       return result unless result.is_a?(Hash)
       doc = if /^_design/ =~ result["_id"]
@@ -98,26 +100,34 @@ module CouchRest
     
     # GET an attachment directly from CouchDB
     def fetch_attachment(doc, name)
-      # slug = escape_docid(docid)        
-      # name = CGI.escape(name)
-      uri = uri_for_attachment(doc, name)
-      RestClient.get uri
-      # "#{@uri}/#{slug}/#{name}"
+      uri = url_for_attachment(doc, name)
+      HttpAbstraction.get uri
     end
     
     # PUT an attachment directly to CouchDB
     def put_attachment(doc, name, file, options = {})
       docid = escape_docid(doc['_id'])
       name = CGI.escape(name)
-      uri = uri_for_attachment(doc, name)       
-      JSON.parse(RestClient.put(uri, file, options))
+      uri = url_for_attachment(doc, name)
+      JSON.parse(HttpAbstraction.put(uri, file, options))
     end
     
     # DELETE an attachment directly from CouchDB
-    def delete_attachment doc, name
-      uri = uri_for_attachment(doc, name)
+    def delete_attachment(doc, name, force=false)
+      uri = url_for_attachment(doc, name)
       # this needs a rev
-      JSON.parse(RestClient.delete(uri))
+      begin
+        JSON.parse(HttpAbstraction.delete(uri))
+      rescue Exception => error
+        if force
+          # get over a 409
+          doc = get(doc['_id'])
+          uri = url_for_attachment(doc, name)
+          JSON.parse(HttpAbstraction.delete(uri))
+        else
+          error
+        end
+      end
     end
     
     # Save a document to CouchDB. This will use the <tt>_id</tt> field from
@@ -141,14 +151,20 @@ module CouchRest
         bulk_save
       end
       result = if doc['_id']
-        slug = escape_docid(doc['_id'])        
-        CouchRest.put "#{@uri}/#{slug}", doc
+        slug = escape_docid(doc['_id'])
+        begin     
+          CouchRest.put "#{@root}/#{slug}", doc
+        rescue HttpAbstraction::ResourceNotFound
+          p "resource not found when saving even tho an id was passed"
+          slug = doc['_id'] = @server.next_uuid
+          CouchRest.put "#{@root}/#{slug}", doc
+        end
       else
         begin
           slug = doc['_id'] = @server.next_uuid
-          CouchRest.put "#{@uri}/#{slug}", doc
+          CouchRest.put "#{@root}/#{slug}", doc
         rescue #old version of couchdb
-          CouchRest.post @uri, doc
+          CouchRest.post @root, doc
         end
       end
       if result['ok']
@@ -183,7 +199,7 @@ module CouchRest
           doc['_id'] = nextid if nextid
         end
       end
-      CouchRest.post "#{@uri}/_bulk_docs", {:docs => docs}
+      CouchRest.post "#{@root}/_bulk_docs", {:docs => docs}
     end
     alias :bulk_delete :bulk_save
     
@@ -200,7 +216,7 @@ module CouchRest
         return { "ok" => true } # Mimic the non-deferred version
       end
       slug = escape_docid(doc['_id'])        
-      CouchRest.delete "#{@uri}/#{slug}?rev=#{doc['_rev']}"
+      CouchRest.delete "#{@root}/#{slug}?rev=#{doc['_rev']}"
     end
     
     ### DEPRECATION NOTICE
@@ -220,7 +236,7 @@ module CouchRest
       else
         dest
       end
-      CouchRest.copy "#{@uri}/#{slug}", destination
+      CouchRest.copy "#{@root}/#{slug}", destination
     end
     
     ### DEPRECATION NOTICE
@@ -231,7 +247,7 @@ module CouchRest
     
     # Compact the database, removing old document revisions and optimizing space use.
     def compact!
-      CouchRest.post "#{@uri}/_compact"
+      CouchRest.post "#{@root}/_compact"
     end
     
     # Create the database
@@ -244,7 +260,7 @@ module CouchRest
     def recreate!
       delete!
       create!
-    rescue RestClient::ResourceNotFound
+    rescue HttpAbstraction::ResourceNotFound
     ensure
       create!
     end
@@ -264,11 +280,16 @@ module CouchRest
     # DELETE the database itself. This is not undoable and could be rather
     # catastrophic. Use with care!
     def delete!
-      CouchRest.delete @uri
+      clear_extended_doc_fresh_cache
+      CouchRest.delete @root
     end
 
     private
     
+    def clear_extended_doc_fresh_cache
+      ::CouchRest::ExtendedDocument.subclasses.each{|klass| klass.design_doc_fresh = false if klass.respond_to?(:design_doc_fresh=) }
+    end
+
     def uri_for_attachment(doc, name)
       if doc.is_a?(String)
         puts "CouchRest::Database#fetch_attachment will eventually require a doc as the first argument, not a doc.id"
@@ -281,7 +302,11 @@ module CouchRest
       docid = escape_docid(docid)
       name = CGI.escape(name)
       rev = "?rev=#{doc['_rev']}" if rev
-      "#{@root}/#{docid}/#{name}#{rev}"
+      "/#{docid}/#{name}#{rev}"
+    end
+
+    def url_for_attachment(doc, name)
+      @root + uri_for_attachment(doc, name)
     end
     
     def escape_docid id      

data/lib/couchrest/core/document.rb

@@ -3,10 +3,6 @@ require 'delegate'
 module CouchRest  
   class Document < Response
     include CouchRest::Mixins::Attachments
-
-    # def self.inherited(subklass)
-    #   subklass.send(:extlib_inheritable_accessor, :database)
-    # end
     
     extlib_inheritable_accessor :database
     attr_accessor :database
@@ -68,7 +64,7 @@ module CouchRest
     # Returns the CouchDB uri for the document
     def uri(append_rev = false)
       return nil if new_document?
-      couch_uri = "http://#{database.uri}/#{CGI.escape(id)}"
+      couch_uri = "http://#{database.root}/#{CGI.escape(id)}"
       if append_rev == true
         couch_uri << "?rev=#{rev}"
       elsif append_rev.kind_of?(Integer)

data/lib/couchrest/core/http_abstraction.rb

@@ -0,0 +1,48 @@
+require 'couchrest/core/adapters/restclient'
+
+# Abstraction layet for HTTP communications.
+#                                           
+# By defining a basic API that CouchRest is relying on,
+# it allows for easy experimentations and implementations of various libraries.
+# 
+# Most of the API is based on the RestClient API that was used in the early version of CouchRest.
+#
+module HttpAbstraction
+  
+  # here is the list of exception expected by CouchRest
+  # please convert the underlying errors in this set of known
+  # exceptions.
+  class ResourceNotFound < StandardError; end
+  class RequestFailed < StandardError; end
+  class RequestTimeout < StandardError; end
+  class ServerBrokeConnection < StandardError; end
+  class Conflict < StandardError; end
+  
+  
+  # # Here is the API you need to implement if you want to write a new adapter
+  # # See adapters/restclient.rb for more information.
+  #
+  # def self.proxy=(url)
+  # end
+  #      
+  # def self.proxy
+  # end
+  #
+  # def self.get(uri, headers=nil)
+  # end
+  # 
+  # def self.post(uri, payload, headers=nil)
+  # end
+  # 
+  # def self.put(uri, payload, headers=nil)
+  # end
+  # 
+  # def self.delete(uri, headers=nil)
+  # end
+  # 
+  # def self.copy(uri, headers)
+  # end    
+ 
+end
+
+HttpAbstraction.extend(RestClientAdapter::API)

data/lib/couchrest/core/response.rb

@@ -3,11 +3,7 @@ module CouchRest
     def initialize(pkeys = {})
       pkeys ||= {}
       pkeys.each do |k,v|
-        if self.respond_to?("#{k}=")
-          self.send("#{k}=",v)
-        else
-          self[k.to_s] = v
-        end
+        self[k.to_s] = v
       end
     end
     def []=(key, value)

data/lib/couchrest/core/rest_api.rb

@@ -0,0 +1,49 @@
+module RestAPI
+
+  def put(uri, doc = nil)
+    payload = doc.to_json if doc
+    begin
+      JSON.parse(HttpAbstraction.put(uri, payload))
+    rescue Exception => e
+      if $DEBUG
+        raise "Error while sending a PUT request #{uri}\npayload: #{payload.inspect}\n#{e}"
+      else
+        raise e
+      end
+    end
+  end
+
+  def get(uri)
+    begin
+      JSON.parse(HttpAbstraction.get(uri), :max_nesting => false)
+    rescue => e
+      if $DEBUG
+        raise "Error while sending a GET request #{uri}\n: #{e}"
+      else
+        raise e
+      end
+    end
+  end
+
+  def post(uri, doc = nil)
+    payload = doc.to_json if doc
+    begin
+      JSON.parse(HttpAbstraction.post(uri, payload))
+    rescue Exception => e
+      if $DEBUG
+        raise "Error while sending a POST request #{uri}\npayload: #{payload.inspect}\n#{e}"
+      else
+        raise e
+      end
+    end
+  end
+
+  def delete(uri)
+    JSON.parse(HttpAbstraction.delete(uri))
+  end
+
+  def copy(uri, destination) 
+    JSON.parse(HttpAbstraction.copy(uri, {'Destination' => destination}))
+  end 
+
+end