manveru-makura 2009.02.18

data/COPYING

@@ -0,0 +1,18 @@
+Copyright (c) 2008 Michael Fellinger <m.fellinger@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,41 @@
+# Makura
+
+Makura is a Ruby wrapper around the CouchDB REST API.
+
+It doesn't provide a lot of bells and whistles, but aims to be as close to the
+original API as possible, while taking advantage of Ruby's expressive power.
+
+Most ideas for this have been gathered while trying other libraries such as
+CouchObject, CouchRest, and RelaxDB.
+
+It does so with almost no modification of ruby libraries and makes it simple
+to switch the HTTP library used by changing one method.
+Eventually Makura will be using an evented http library to provide better
+performance.
+
+We are using the json library, which adds following methods:
+To Kernel: #j, #jj, #JSON
+To Object and most core classes: #to_json
+To String: #to_json_raw_object, #to_json, #to_json_raw
+
+## Dependencies
+
+* CouchDB - 0.9 trunk (rev 725909 and higher)
+* rest-client
+* rack
+* json
+
+## Features
+
+* Simple Models, the CouchDB way and without magic.
+* Free choice of inheritance, just include the Makura::Model module.
+* Smart interpretation of returned JSON.
+* Direct mapping of javascript files to map/reduce functions for views.
+* CouchDB specific error reporting, no meaningless HTTP status code.
+* Live update of views during runtime.
+* Easy configuration, possibility to use different servers and databases each
+  model.
+
+## Usage
+
+See the /example/blog.rb

data/bin/makura

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'makura'
+
+Makura::Model.database = ARGV.shift
+DB = Makura::Model.database
+
+puts "Your database is assigned to DB"
+
+require 'irb'
+IRB.start

data/example/blog.rb

@@ -0,0 +1,53 @@
+require 'makura'
+
+# Setting up everything
+
+# Makura::Model.server = 'http://localhost:5984'
+Makura::Model.database = 'mydb'
+
+class Post
+  include Makura::Model
+
+  properties :title, :text, :tags
+  belongs_to :author
+
+  layout :all
+
+  validates(:title){ presence and length :within => (3..100) }
+  validates(:text){ presence }
+
+  save # submit design docs to CouchDB
+end
+
+class Author
+  include Makura::Model
+
+  property :name
+
+  layout :posts, :reduce => :sum_length
+  layout :all
+
+  save
+end
+
+class Comment
+  include Makura::Model
+
+  property :text
+end
+
+# And here it goes.
+
+author = Author.new('name' => 'Michael Fellinger')
+author.save
+
+post = Post.new(
+  :title => 'Hello, World!',
+  :text => 'This is my first post',
+  :author => author)
+post.save
+
+Post.view(:all).each do |post|
+  p post
+  p post.author
+end

data/example/couch/map/author_all.js

@@ -0,0 +1,5 @@
+function(doc){
+  if(doc.type == 'Author'){
+    emit(doc._id, doc);
+  }
+}

data/example/couch/map/author_posts.js

@@ -0,0 +1,5 @@
+function(doc){
+  if(doc.type == 'Post' && doc.user){
+    emit(doc.user, doc);
+  }
+}

data/example/couch/map/post_all.js

@@ -0,0 +1,5 @@
+function(doc){
+  if(doc.type == 'Post'){
+    emit(doc._id, doc);
+  }
+}

data/example/couch/map/post_comments.js

@@ -0,0 +1,5 @@
+function(doc){
+  if(doc.type == 'Comment'){
+    emit(doc._id, doc);
+  }
+}

data/example/couch/reduce/sum_length.js

@@ -0,0 +1,7 @@
+function(keys, values, rereduce){
+  if(rereduce){
+    return sum(values);
+  } else {
+    return values.length;
+  }
+}

data/lib/makura/database.rb

@@ -0,0 +1,216 @@
+module Makura
+  class Database
+    include HTTPMethods
+    attr_accessor :server, :name
+
+    # Initialize instance of Database and create if it doesn't exist yet.
+    # To prevent automatic creation, pass false as 3rd parameter
+    #
+    # Usage:
+    #   server = Makura::Server.new
+    #   # #<URI::HTTP:0xb7788234 URL:http://localhost:5984>
+    #   database = Makura::Database.new(server, 'foo')
+    #   # #<Makura::Database 'http://localhost:5984/foo'>
+
+    def initialize(server, name, auto_create = true)
+      @server, @name = server, name
+      create if auto_create
+    end
+
+    # Create the database if it doesn't exist already.
+    #
+    # Usage:
+    #   server = Makura::Server.new
+    #   # #<URI::HTTP:0xb76a4a98 URL:http://localhost:5984>
+    #
+    #   database = Makura::Database.new(server, 'foo', false)
+    #   # #<Makura::Database 'http://localhost:5984/foo'>
+    #
+    #   database.create
+    #   # {"update_seq"=>0, "doc_count"=>0, "purge_seq"=>0, "disk_size"=>4096,
+    #   #  "compact_running"=>false, "db_name"=>"foo", "doc_del_count"=>0}
+
+    def create
+      info
+    rescue Error::ResourceNotFound
+      put("/", :payload => '')
+    end
+
+    # Will delete document in the CouchDB corresponding to given +doc+.
+    # Use #destroy to delete the database itself.
+    # Use #delete! to automatically rescue exceptions on conflicts.
+    #
+    # Possible variations (User is a Makura::Model) are:
+    #
+    #   # deleting based on explicit _id and :rev option.
+    #   database.delete('manveru', :rev => 123134)
+    #
+    #   # deleting based on a Hash
+    #   database.delete('_id' => 'manveru', '_rev' => 123134)
+    #
+    #   user = User.new(:name => 'manveru')
+    #   user.save
+    #   database.delete(user)
+    #
+    # Usage when deleting document:
+    #   doc = database.save('name' => 'manveru', 'time' => Time.now)
+    #   # {"rev"=>"484030692", "id"=>"67e086087d5b7e7196b5c99174b0b66c", "ok"=>true}
+    #
+    #   database[doc['id']]
+    #   # {"name"=>"manveru", "_rev"=>"484030692",
+    #      "time"=>"Sat Nov 22 16:37:50 +0900 2008",
+    #      "_id"=>"67e086087d5b7e7196b5c99174b0b66c"}
+    #
+    #   database.delete(doc['id'], :rev => doc['rev'])
+    #   # {"rev"=>"2034883605", "id"=>"67e086087d5b7e7196b5c99174b0b66c", "ok"=>true}
+    #
+    #   database[doc['id']]
+    #   RestClient::ResourceNotFound: RestClient::ResourceNotFound
+    #
+    #   database.delete(doc['id'], :rev => doc['rev'])
+    #   Makura::RequestFailed: {"reason"=>"Document update conflict.", "error"=>"conflict"}
+
+    def delete(doc, opts = {})
+      case doc
+      when Makura::Model
+        doc_id, doc_rev = doc._id, doc._rev
+      when Hash
+        doc_id  = doc['_id']  || doc['id']  || doc[:_id]  || doc[:id]
+        doc_rev = doc['_rev'] || doc['rev'] || doc[:_rev] || doc[:rev]
+      else
+        doc_id = doc
+      end
+
+      raise(ArgumentError, "document _id wasn't passed") unless doc_id
+
+      doc_id = Makura.escape(doc_id)
+      opts[:rev] ||= doc_rev if doc_rev
+
+      request(:delete, doc_id.to_s, opts)
+    end
+
+    def delete!(doc, opts = {})
+      delete(doc, opts)
+    rescue Error::Conflict, Error::ResourceNotFound
+    end
+
+    # Delete the database itself.
+    #
+    # Usage:
+    #   database.destroy
+    #   # {"ok"=>true}
+    #   database.info
+    #   # RestClient::ResourceNotFound: RestClient::ResourceNotFound
+
+    def destroy(opts = {})
+      request(:delete, '/', opts)
+    end
+
+    def destroy!(opts = {})
+      destroy(opts)
+    rescue Error::ResourceNotFound
+    end
+
+    def info
+      get('/')
+    end
+
+    def all_docs(params = {})
+      get('_all_docs')
+    end
+    alias documents all_docs
+
+    def [](id, rev = nil)
+      id = Makura.escape(id)
+      if rev
+        get(id, :rev => rev)
+      else
+        get(id)
+      end
+    end
+
+    def []=(id, doc)
+      id = Makura.escape(id)
+      put(id, :payload => prepare_doc(doc))
+    end
+
+    def temp_view(params = {})
+      params[:payload] = functions = {}
+      functions[:map] = params.delete(:map) if params[:map]
+      functions[:reduce] = params.delete(:reduce) if params[:reduce]
+      params['Content-Type'] = 'application/json'
+
+      post('_temp_view', params)
+    end
+
+    def view(layout, params = {})
+      get("_view/#{layout}", params)
+    end
+
+    def save(doc)
+      if id = doc['_id']
+        id = Makura.escape(id)
+        put(id, :payload => prepare_doc(doc))
+      else
+        id = doc['_id'] = @server.next_uuid
+        id = Makura.escape(id)
+        put(id, :payload => prepare_doc(doc))
+      end
+    end
+
+    # NOTE:
+    #   * Seems like we don't even need to check _id, CouchDB will assign it.
+    #     But in order to use our own uuids we still do it.
+    def bulk_docs(docs)
+      docs.each{|doc| doc['_id'] ||= @server.next_uuid }
+      post("_bulk_docs", :payload => {:docs => docs})
+    end
+    alias bulk_save bulk_docs
+
+    def get_attachment(doc, file_id)
+      doc_id = doc.respond_to?(:_id) ? doc._id : doc.to_str
+      file_id, doc_id = Makura.escape(file_id), Makura.escape(doc_id)
+
+      get("#{doc_id}/#{file_id}", :raw => true)
+    end
+
+    # PUT an attachment directly to CouchDB
+    def put_attachment(doc, file_id, file, options = {})
+      doc_id, file_id = Makura.escape(doc._id), Makura.escape(file_id)
+
+      options[:payload] = file
+      options[:raw] = true
+      options[:rev] = doc._rev if doc._rev
+
+      put("#{doc_id}/#{file_id}", options)
+    end
+
+    def prepare_doc(doc)
+      if attachments = doc['_attachments']
+        doc['_attachments'] = encode_attachments(attachments)
+      end
+
+      return doc
+    end
+
+    def request(method, path, params = {})
+      @server.send(:request, method, "/#{name}/#{path}", params)
+    end
+
+    def encode_attachments(attachments)
+      attachments.each do |key, value|
+        next if value['stub']
+        value['data'] = base64(value['data'])
+      end
+      attachments
+    end
+
+    def base64(data)
+      [data.to_s].pack('m').delete("\n")
+    end
+
+    def inspect
+      "#<Makura::Database '#{@server.uri(name)}'>"
+    end
+  end
+end

data/lib/makura/design.rb

@@ -0,0 +1,37 @@
+module Makura
+  class Design
+    attr_accessor :database, :name, :language
+    attr_reader :layouts
+
+    def initialize(name, database = nil)
+      @name, @database = name, database
+      @language = 'javascript'
+      @layouts = {}
+    end
+
+    def save
+      hash = to_hash
+      doc = @database[hash['_id']]
+      doc['views'] = hash['views']
+      @database.save(doc)
+    rescue Makura::Error::ResourceNotFound
+      @database.save(to_hash)
+    end
+
+    def [](layout_name)
+      @layouts[layout_name.to_s]
+    end
+
+    def []=(layout_name, layout)
+      @layouts[layout_name.to_s] = layout
+    end
+
+    def to_hash
+      views = {}
+      @layouts.each{|name, layout| views[name] = layout.to_hash }
+      views.delete_if{|k,v| !(v[:map] || v['map']) }
+
+      {'language' => @language, '_id' => "_design/#{@name}", 'views' => views}
+    end
+  end
+end

data/lib/makura/error.rb

@@ -0,0 +1,14 @@
+module Makura
+  # Mother and namespace of all exceptions
+  class Error < ::RuntimeError
+    class ConnectionRefused < Error; end
+    class RequestFailed < Error; end
+    class ResourceNotFound < RequestFailed; end
+    class Conflict < RequestFailed; end
+    class MissingRevision < RequestFailed; end
+    class BadRequest < RequestFailed; end
+    class Authorization < RequestFailed; end
+    class NotFound < RequestFailed; end
+    class FileExists < RequestFailed; end
+  end
+end

data/lib/makura/http_methods.rb

@@ -0,0 +1,19 @@
+module Makura
+  module HTTPMethods
+    def delete(path, params = {})
+      request(:delete, path, params)
+    end
+
+    def get(path, params = {})
+      request(:get, path, params)
+    end
+
+    def post(path, params = {})
+      request(:post, path, params)
+    end
+
+    def put(path, params = {})
+      request(:put, path, params)
+    end
+  end
+end

data/lib/makura/layout.rb

@@ -0,0 +1,62 @@
+module Makura
+  class Layout
+    attr_accessor :design, :name, :map, :reduce
+
+    PATH = [
+      './couch',
+      File.join(Makura::ROOT, '../couch')
+    ]
+
+    def initialize(name, design = nil)
+      @name, @design = name, design
+      @design[name] = self
+      @map = @reduce = nil
+      @options = {}
+    end
+
+    def load_proto_map(file_or_function, replace = {})
+      return unless common_load(:proto_map, file_or_function)
+      replace.each{|from, to| @proto_map.gsub!(/"\{\{#{from}\}\}"/, to) }
+      @map = @proto_map
+    end
+
+    def load_proto_reduce(file_or_function, replace = {})
+      return unless common_load(:proto_reduce, file_or_function)
+      replace.each{|from, to| @proto_reduce.gsub!(/"\{\{#{from}\}\}"/, to) }
+      @reduce = @proto_reduce
+    end
+
+    def load_map(file_or_function)
+      common_load(:map, file_or_function)
+    end
+
+    def load_reduce(file_or_function)
+      common_load(:reduce, file_or_function)
+    end
+
+    def common_load(root, file_or_function)
+      return unless file_or_function
+
+      if file_or_function =~ /function\(.*\)/
+        function = file_or_function
+      else
+        filename = "#{root}/#{file_or_function}.js"
+
+        if pathname = PATH.find{|pa| File.file?(File.join(pa, filename)) }
+          function = File.read(File.join(pathname, filename))
+        end
+      end
+
+      instance_variable_set("@#{root}", function) if function
+    end
+
+    def save
+      @design[@name] = self.to_hash
+      @design.save
+    end
+
+    def to_hash
+      {:map => @map, :reduce => @reduce, :makura_options => @options}
+    end
+  end
+end

data/lib/makura/model.rb

@@ -0,0 +1,372 @@
+module Makura
+  module Model
+    KEY = 'makura_type'
+
+    class << self
+      attr_reader :server, :database
+
+      def database=(name)
+        @database = server.database(name)
+      end
+
+      def server=(obj)
+        case obj
+        when Makura::Server
+          @server = obj
+        when String, URI
+          @server = Makura::Server.new(obj)
+        else
+          raise ArgumentError
+        end
+      end
+
+      def server
+        return @server if @server
+        self.server = Makura::Server.new
+      end
+
+      def included(into)
+        into.extend(SingletonMethods)
+        into.send(:include, InstanceMethods)
+        into.makura_relation = {:belongs_to => {}, :has_many => {}}
+        into.property_type = {}
+        into.defaults = {'type' => into.name}
+        into.properties(:_id, :_rev, :type)
+      end
+    end
+
+    module InstanceMethods
+      def initialize(hash = {})
+        @_hash = self.class.defaults.dup
+        merge!(hash)
+      end
+
+      def merge!(hash)
+        case hash
+        when Makura::Model
+          merge!(hash.to_hash)
+        when Hash
+          hash.each{|key, value|
+            meth = "#{key}="
+
+            if respond_to?(meth)
+              self.send("#{key}=", value)
+            else
+              self[key.to_s] = value
+            end
+          }
+        else
+          raise ArgumentError, "This is neither relation data nor an Hash"
+        end
+      end
+
+      def [](key)
+        @_hash[key.to_s]
+      end
+
+      def []=(key, value)
+        @_hash[key.to_s] = value
+      end
+
+      def to_hash
+        @_hash.dup
+      end
+
+      def to_json
+        @_hash.to_json
+      end
+
+      def inspect
+        "#<#{self.class} #{@_hash.inspect}>"
+      end
+
+      def pretty_print(o)
+        ["#<#{self.class} ", @_hash, ">"].each{|e| e.pretty_print(o) }
+      end
+
+      def saved?
+        self['_rev']
+      end
+
+      def save
+        return if not valid? if respond_to?(:valid)
+        return if saved?
+        save!
+      end
+
+      def save!
+        hash = self.to_hash
+
+        self.class.makura_relation.each do |kind, relation_hash|
+          relation_hash.each do |key, value|
+            hash[key.to_s] = hash[key.to_s] #._id
+          end
+        end
+
+        response = self.class.database.save(hash)
+        self._rev = response['rev']
+        self._id = response['id']
+
+        return self
+      end
+
+      # path, file, args = {})
+      def attach(*args)
+        self.class.database.put_attachment(self, *args)
+      end
+
+      # delete attachment by name.
+      # we make sure the parameter is given and a nonempty string to avoid
+      # destroying the document itself
+      def detach(name)
+        name.strip!
+        return if name.empty?
+        self.class.database.request(:delete, "#{_id}/#{name}", :rev => _rev)
+      rescue Makura::Error::Conflict
+        self['_rev'] = self.class[self._id]['_rev']
+        retry
+      end
+
+      def destroy
+        self.class.database.delete(_id, :rev => _rev)
+      end
+
+      def ==(obj)
+        self.class == obj.class and self._id == obj._id
+      end
+
+      def hash
+        @_hash.hash
+      end
+
+      def eql?(other)
+        other == self && other.hash == self.hash
+      end
+
+      def clone
+        hash = @_hash.dup
+        hash.delete('_id')
+        hash.delete('_rev')
+        self.class.new(hash)
+      end
+    end
+
+    module SingletonMethods
+      attr_accessor :defaults, :makura_relation, :property_type
+
+      def plugin(name)
+        require "makura/plugin/#{name}".downcase
+
+        name = name.to_s.capitalize
+        mod = Makura::Plugin.const_get(name)
+
+        include(mod::InstanceMethods) if defined?(mod::InstanceMethods)
+        extend(mod::SingletonMethods) if defined?(mod::SingletonMethods)
+      end
+
+      def database=(name)
+        @database = Makura::Model.server.database(name)
+      end
+
+      def database
+        @database || Makura::Model.database
+      end
+
+      def properties(*names)
+        names.each{|name| property(name) }
+      end
+
+      def property(name, opts = {})
+        name = name.to_s
+        defaults[name] = default = opts.delete(:default) if opts[:default]
+        property_type[name] = type = opts.delete(:type) if opts[:type]
+
+        if type == Time
+          code = "
+            def #{name}()
+              Time.at(@_hash[#{name.dump}].to_i)
+            end
+            def #{name}=(obj)
+              @_hash[#{name.dump}] = obj.to_i
+            end"
+          class_eval(code)
+        else
+          code = "
+            def #{name}() @_hash[#{name.dump}] end
+            def #{name}=(obj) @_hash[#{name.dump}] = obj end"
+        end
+
+        class_eval(code)
+      end
+
+      def id(name)
+        @id = name
+        class_eval("
+          alias #{name} _id
+          alias #{name}= _id=")
+      end
+
+      def belongs_to(name, model = nil)
+        name = name.to_s
+        klass = (model || name.capitalize).to_s
+        @makura_relation[:belongs_to][name] = klass
+
+        class_eval("
+          def #{name}()
+            @#{name} ||= #{klass}[self[#{name.dump}]]
+          end
+          def #{name}=(obj)
+            if obj.respond_to?(:_id)
+              @_hash[#{name.dump}] = obj._id
+            else
+              @_hash[#{name.dump}] = obj
+            end
+          end")
+      end
+
+      def has_many(name, model = nil)
+        name = name.to_s
+        klass = (model || name.capitalize).to_s
+        @makura_relation[:has_many][name] = klass
+
+        class_eval("
+          def #{name}()
+            @#{name} ||= #{klass}[self[#{name.dump}]]
+          end
+          def #{name}=(obj)
+            return unless obj
+            raise RuntimeError, 'You many not assign here'
+          end")
+      end
+
+      def [](id, rev = nil)
+        new(database[id, rev])
+      rescue Error::ResourceNotFound
+        nil
+      end
+
+      def design
+        @design ||= Design.new(name.to_s, database)
+      end
+
+      def layout(name, opts = {})
+        design[name] = layout = Layout.new(name, design)
+
+        map_name    = opts[:map]    || "#{self.name}_#{name}".downcase
+        reduce_name = opts[:reduce] || "#{self.name}_#{name}".downcase
+
+        layout.load_map(map_name)
+        layout.load_reduce(reduce_name)
+
+        return layout
+      end
+
+      def proto_layout(common, name, opts = {})
+        design[name] = layout = Layout.new(name, design)
+
+        map_name    = opts.delete(:map)    || "#{self.name}_#{common}".downcase
+        reduce_name = opts.delete(:reduce) || "#{self.name}_#{common}".downcase
+
+        layout.load_proto_map(map_name, opts)
+        layout.load_proto_reduce(reduce_name, opts)
+
+        return layout
+      end
+
+      def save
+        design.save
+      end
+
+      # +opts+ must include a :keys or 'keys' key with something that responds
+      # to #to_a as value
+      #
+      # Usage given a map named `Post/by_tags' that does something like:
+      #
+      #     for(t in doc.tags){ emit([doc.tags[t]], null); }
+      #
+      # You can use this like:
+      #
+      #     keys = ['ruby', 'couchdb']
+      #     Post.multi_fetch(:by_tags, :keys => keys)
+      #
+      # And it will return all docs with the tags 'ruby' OR 'couchdb'
+      # This can be extended to match even more complex things
+      #
+      #   for(t in doc.tags){ emit([doc.author, doc.tags[t]], null); }
+      #
+      # Now we do
+      #
+      #     keys = [['manveru', 'ruby'], ['mika', 'couchdb']]
+      #     Post.multi_fetch(:by_tags, :keys => keys)
+      #
+      # This will return all docs match following:
+      #     ((author == 'manveru' && tags.include?('ruby')) ||
+      #      (author == 'mika' && tags.include?('couchdb')))
+      #
+      # Of course you can add as many keys as you like:
+      #
+      #     keys = [['manveru', 'ruby'],
+      #             ['manveru', 'couchdb'],
+      #             ['mika', 'design']]
+      #             ['mika', 'couchdb']]
+      #     Post.multi_fetch(:by_tags, :keys => keys)
+      #
+      #
+      # From http://wiki.apache.org/couchdb/HTTP_view_API
+      #   A JSON structure of {"keys": ["key1", "key2", ...]} can be posted to
+      #   any user defined view or _all_docs to retrieve just the view rows
+      #   matching that set of keys. Rows are returned in the order of the keys
+      #   specified. Combining this feature with include_docs=true results in
+      #   the so-called multi-document-fetch feature.
+
+      def multi_fetch(name, opts = {})
+        keys = opts.delete(:keys) || opts.delete('keys')
+        opts.merge!(:payload => {'keys' => keys.to_a})
+        hash = database.post("_view/#{self}/#{name}", opts)
+        convert_raw(hash['rows'])
+      end
+
+      def multi_fetch_with_docs(name, opts = {})
+        opts.merge!(:include_docs => true, :reduce => false)
+        multi_fetch(name, opts)
+      end
+      alias multi_document_fetch multi_fetch_with_docs
+
+      # It is generally recommended not to include the doc in the emit of the
+      # map function but to use include_docs=true.
+      # To make using this approach more convenient use this method.
+
+      def view_with_docs(name, opts = {})
+        opts.merge!(:include_docs => true, :reduce => false)
+        view(name, opts)
+      end
+
+      alias view_docs view_with_docs
+
+      def view(name, opts = {})
+        flat = opts.delete(:flat)
+        hash = database.view("#{self}/#{name}", opts)
+
+        convert_raw(hash['rows'], flat)
+      end
+
+      def convert_raw(rows, flat = false)
+        rows.map do |row|
+          value = row['doc'] || row['value']
+
+          if value.respond_to?(:to_hash)
+            if type = value['type'] and not flat
+              const_get(type).new(value)
+            else
+              row
+            end
+          elsif not row['key']
+            value
+          else
+            row
+          end
+        end
+      end
+    end
+  end
+end

data/lib/makura/plugin/pager.rb

@@ -0,0 +1,56 @@
+module Makura
+  module Plugin
+    module Pager
+      module SingletonMethods
+        def pager(page, limit)
+          Makura::Plugin::Pager::Pagination.new(self, :pager, page, limit)
+        end
+      end
+
+      class Pagination
+        def initialize(model, view, page, limit)
+          @model, @view, @page, @limit = model, view, page, limit
+        end
+
+        # /pager/_all_docs?count=10&group=true
+        # /pager/_all_docs?startkey=%224f9dca1c66121f9320a69553546db07a%22&startkey_docid=4f9dca1c66121f9320a69553546db07a&skip=1&descending=false&count=10&group=true
+        # /pager/_all_docs?startkey=%22_design%2FUser%22&startkey_docid=_design%2FUser&skip=1&descending=false&count=10&group=true
+        # /pager/_all_docs?startkey=%22d850f0801686b85035680bb6f38d5c5c%22&startkey_docid=d850f0801686b85035680bb6f38d5c5c&skip=1&descending=false&count=10&group=true
+
+        # NOTE:
+        #   * descending should be true if you page backwards
+
+        include Enumerable
+
+        def each(start_id = nil, descending = false, &block)
+          opts = {
+            :count => @limit,
+            :group => true,
+            :descending => descending,
+            # :include_docs => true,
+          }
+
+          if start_id
+            opts[:skip] = 1
+            opts[:startkey_docid] = start_id
+            opts[:startkey] = start_id
+          end
+
+          @model.view(@view, opts).each(&block)
+        end
+
+        def count
+        end
+
+        def first_page?
+        end
+
+        def last_page?
+        end
+
+        def empty?
+        end
+      end
+    end
+  end
+end

data/lib/makura/server.rb

@@ -0,0 +1,203 @@
+module Makura
+  class Server
+    include HTTPMethods
+    attr_accessor :uri, :cache_ttl, :cache_tries
+
+    COUCHDB_URI = 'http://localhost:5984'
+    CACHE_TTL = 5
+    CACHE_TRIES = 2
+
+    # Usage:
+    #   server = Makura::Server.new
+    #   #<URI::HTTP:0xb778ce38 URL:http://localhost:5984>
+    #   server.info
+    #   {"couchdb"=>"Welcome", "version"=>"0.9.0a718650-incubating"}
+
+    def initialize(uri = COUCHDB_URI, cache_ttl = CACHE_TTL, cache_tries = CACHE_TRIES)
+      @uri = URI(uri.to_s)
+      @cache_ttl = cache_ttl
+      @cache_tries = cache_tries
+      @uuids = UUIDCache.new(self)
+    end
+
+    def inspect
+      @uri.inspect
+    end
+
+    # General queries
+
+    # Answers with general couchdb info, looks like:
+    #
+    # Usage:
+    #   server.info
+    #   # {'couchdb' => 'Welcome', 'version' => '0.9.0a718650-incubating'}
+    def info
+      get('/')
+    end
+
+    # Answers with configuration info.
+    #
+    # Usage:
+    #   server.config
+    #
+    def config
+      get('/_config')
+    end
+
+    # Issue restart of the CouchDB daemon.
+    #
+    # Usage:
+    #   server.restart
+    #   # {'ok' => true}
+    def restart
+      post('/_restart')
+    end
+
+    # Array of names of databases on the server
+    #
+    # Usage:
+    #   server.databases
+    #   # ["another", "blog", "makura-spec"]
+    def databases
+      get('/_all_dbs')
+    end
+
+    # Return new database instance using this server instance.
+    #
+    # Usage:
+    #   foo = server.database('foo')
+    #   # #<Makura::Database 'http://localhost:5984/foo'>
+    #   server.databases
+    #   # ["another", "blog", "foo", "makura-spec"]
+
+    def database(name)
+      Database.new(self, name)
+    end
+
+    # Answers with an uuid from the UUIDCache.
+    #
+    # Usage:
+    #   server.next_uuid
+    #   # "55fdca746fa5a5b56f5270875477a2cc"
+
+    def next_uuid
+      @uuids.next
+    end
+
+    def start_cache(namespace = 'makura', *servers)
+      servers << 'localhost:11211' if servers.empty?
+      @cache = MemCache.new(servers, :namespace => namespace, :multithread => true)
+    end
+
+    def stop_cache
+      @cache = nil
+    end
+
+    def cached(request, ttl = cache_ttl, tries = cache_tries)
+      key = request[:url]
+
+      unless response = @cache.get(key)
+        response = execute(request)
+        @cache.add(key, response, ttl)
+      end
+
+      return response
+    rescue MemCache::MemCacheError => error
+      servers = @cache.servers.map{|s| "#{s.host}:#{s.port}"}
+      start_cache(@cache.namespace, *servers)
+      tries -= 1
+      retry if tries > 0
+      warn "[makura caching disabled] #{error.message}"
+      @cache = nil
+      execute(request)
+    end
+
+    # Helpers
+
+    def request(method, path, params = {})
+      keep_raw = params.delete(:raw)
+      payload = params.delete(:payload)
+      payload = payload.to_json if payload and not keep_raw
+      headers = {}
+
+      if content_type = params.delete('Content-Type')
+        headers['Content-Type'] = content_type
+      end
+
+      params.delete_if{|k,v| v.nil? }
+      uri = uri(path, params).to_s
+
+      request = {
+        :method => method,
+        :url => uri,
+        :payload => payload,
+        :headers => headers}
+
+      if @cache and request[:method] == :get
+        raw = cached(request)
+      else
+        raw = execute(request)
+      end
+
+      return raw if keep_raw
+      json = JSON.parse(raw)
+    rescue JSON::ParserError
+      return raw
+    rescue RestClient::RequestFailed => ex
+      raise appropriate_error(ex)
+    rescue RestClient::ResourceNotFound => ex
+      raise Error::ResourceNotFound, request[:url], ex.backtrace
+    rescue Errno::ECONNREFUSED
+      raise Error::ConnectionRefused, "Is CouchDB running at #{@uri}?"
+    end
+
+    def execute(request)
+      RestClient::Request.execute(request)
+    end
+
+    def appropriate_error(exception)
+      body = exception.response.body if exception.respond_to?(:response)
+      backtrace = exception.backtrace
+
+      raise(Error::RequestFailed, exception.message, backtrace) unless body
+      raise(Error::RequestFailed, exception.message, backtrace) if body.empty?
+
+      json = JSON.parse(body)
+      error, reason = json['error'], json['reason']
+
+      case error
+      when 'bad_request'
+        raise(Error::BadRequest, reason, backtrace)
+      when 'authorization'
+        raise(Error::Authorization, reason, backtrace)
+      when 'not_found'
+        raise(Error::NotFound, reason, backtrace)
+      when 'file_exists'
+        raise(Error::FileExists, reason, backtrace)
+      when 'missing_rev'
+        raise(Error::MissingRevision, reason, backtrace)
+      when 'conflict'
+        raise(Error::Conflict, reason, backtrace)
+      else
+        raise(Error::RequestFailed, json.inspect, backtrace)
+      end
+    end
+
+    JSON_PARAMS = %w[key startkey endkey]
+
+    def paramify(hash)
+      hash.map{|k,v|
+        k = k.to_s
+        v = v.to_json if JSON_PARAMS.include?(k)
+        "#{Makura.escape(k)}=#{Makura.escape(v)}"
+      }.join('&')
+    end
+
+    def uri(path = '/', params = {})
+      uri = @uri.dup
+      uri.path = (path[0,1] == '/' ? path : "/#{path}").squeeze('/')
+      uri.query = paramify(params) unless params.empty?
+      uri
+    end
+  end
+end

data/lib/makura/uuid_cache.rb

@@ -0,0 +1,23 @@
+module Makura
+  class UUIDCache
+    attr_accessor :min, :max, :server, :pretty
+
+    def initialize(server, min = 500, max = 1500, pretty = true)
+      @server, @min, @max, @pretty = server, min, max, pretty
+      @uuids = []
+    end
+
+    def next
+      fetch if @uuids.size < min
+      @uuids.shift
+    end
+
+    def fetch(count = 0)
+      todo = max - @uuids.size
+      count = [min, todo, max].sort[1]
+      uuids = @server.get('/_uuids', :count => count)['uuids']
+      uuids.map!{|u| Makura.pretty_from_md5(u) } if pretty
+      @uuids.concat(uuids)
+    end
+  end
+end

data/lib/makura.rb

@@ -0,0 +1,62 @@
+require 'pp'
+require 'uri'
+
+begin
+  require 'rubygems'
+rescue LoadError
+end
+
+require 'rest_client'
+require 'json'
+
+module Makura
+  VERSION = '2008.01.15'
+  ROOT = File.expand_path(File.dirname(__FILE__))
+end
+
+unless $LOAD_PATH.any?{|lp| File.expand_path(lp) == Makura::ROOT }
+  $LOAD_PATH.unshift(Makura::ROOT)
+end
+
+require 'makura/error'
+require 'makura/http_methods'
+require 'makura/server'
+require 'makura/database'
+require 'makura/uuid_cache'
+require 'makura/model'
+require 'makura/design'
+require 'makura/layout'
+
+module Makura
+  CHARS = (48..128).map{|c| c.chr}.grep(/[[:alnum:]]/)
+  MOD = CHARS.size
+
+  module_function
+
+  # From Rack
+  def escape(s)
+    s.to_s.gsub(/([^ a-zA-Z0-9_.-]+)/n) {
+      '%'+$1.unpack('H2'*$1.size).join('%').upcase
+    }.tr(' ', '+')
+  end
+
+  def pretty_from_md5(md5)
+    id = md5.to_i(16)
+    o = []
+    while id > 0
+      id, r = id.divmod(MOD)
+      o.unshift CHARS[r]
+    end
+    o.join
+  end
+
+  def pretty_to_md5(id)
+    i = 0
+    id.scan(/./) do |c|
+      i = i * MOD + CHARS.index(c)
+    end
+    i.to_s(16)
+  end
+end
+
+Sofa = Makura # be backwards compatible

data/makura.gemspec

@@ -0,0 +1,41 @@
+Gem::Specification.new do |s|
+  s.name = "makura"
+  s.version = "2009.02.18"
+
+  s.summary = "Ruby wrapper around the CouchDB REST API."
+  s.description = "Ruby wrapper around the CouchDB REST API."
+  s.platform = "ruby"
+  s.has_rdoc = true
+  s.author = "Michael 'manveru' Fellinger"
+  s.email = "m.fellinger@gmail.com"
+  s.homepage = "http://github.com/manveru/makura"
+  s.executables = ['makura']
+  s.bindir = "bin"
+  s.require_path = "lib"
+
+  s.add_dependency('rest-client', '>= 0.8.1')
+  s.add_dependency('json', '>= 1.1.3')
+
+  s.files = [
+    "COPYING",
+    "README.md",
+    "bin/makura",
+    "example/blog.rb",
+    "example/couch/map/author_all.js",
+    "example/couch/map/author_posts.js",
+    "example/couch/map/post_all.js",
+    "example/couch/map/post_comments.js",
+    "example/couch/reduce/sum_length.js",
+    "lib/makura/database.rb",
+    "lib/makura/design.rb",
+    "lib/makura/error.rb",
+    "lib/makura/http_methods.rb",
+    "lib/makura/layout.rb",
+    "lib/makura/model.rb",
+    "lib/makura/plugin/pager.rb",
+    "lib/makura/server.rb",
+    "lib/makura/uuid_cache.rb",
+    "lib/makura.rb",
+    "makura.gemspec"
+  ]
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: manveru-makura
+version: !ruby/object:Gem::Version 
+  version: 2009.02.18
+platform: ruby
+authors: 
+- Michael 'manveru' Fellinger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-13 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.8.1
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.3
+    version: 
+description: Ruby wrapper around the CouchDB REST API.
+email: m.fellinger@gmail.com
+executables: 
+- makura
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- COPYING
+- README.md
+- bin/makura
+- example/blog.rb
+- example/couch/map/author_all.js
+- example/couch/map/author_posts.js
+- example/couch/map/post_all.js
+- example/couch/map/post_comments.js
+- example/couch/reduce/sum_length.js
+- lib/makura/database.rb
+- lib/makura/design.rb
+- lib/makura/error.rb
+- lib/makura/http_methods.rb
+- lib/makura/layout.rb
+- lib/makura/model.rb
+- lib/makura/plugin/pager.rb
+- lib/makura/server.rb
+- lib/makura/uuid_cache.rb
+- lib/makura.rb
+- makura.gemspec
+has_rdoc: true
+homepage: http://github.com/manveru/makura
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Ruby wrapper around the CouchDB REST API.
+test_files: []
+