analysand 1.0.1

data/lib/analysand/errors.rb

@@ -0,0 +1,26 @@
+module Analysand
+  class InvalidURIError < StandardError
+  end
+
+  class DatabaseError < StandardError
+    attr_accessor :response
+  end
+
+  class DocumentNotSaved < DatabaseError
+  end
+
+  class DocumentNotDeleted < DatabaseError
+  end
+
+  class CannotAccessDocument < DatabaseError
+  end
+
+  class CannotAccessView < DatabaseError
+  end
+
+  class CannotDropDatabase < DatabaseError
+  end
+
+  class BulkOperationFailed < DatabaseError
+  end
+end

data/lib/analysand/instance.rb

@@ -0,0 +1,156 @@
+require 'analysand/errors'
+require 'base64'
+require 'json/ext'
+require 'net/http/persistent'
+require 'uri'
+
+module Analysand
+  ##
+  # Wraps a CouchDB instance.
+  #
+  # This class is meant to be used for interacting with parts of CouchDB that
+  # aren't associated with any particular database: session management, for
+  # example.  If you're looking to do database operations,
+  # Analysand::Database is where you want to be.
+  #
+  # Instances MUST be identified by an absolute URI; instantiating this class
+  # with a relative URI will raise an exception.
+  #
+  # Common tasks
+  # ============
+  #
+  # Opening an instance
+  # -------------------
+  #
+  #     instance = Analysand::Instance(URI('http://localhost:5984'))
+  #
+  #
+  # Pinging an instance
+  # -------------------
+  #
+  #     instance.ping  # => #<Response code=200 ...>
+  #
+  #
+  # Establishing a session
+  # ----------------------
+  #
+  #     session, resp = instance.establish_session('username', 'password')
+  #     # for correct credentials:
+  #     # => [ {
+  #     #         :issued_at => (a UNIX timestamp),
+  #     #         :roles => [...roles...],
+  #     #         :token => 'AuthSession ...',
+  #     #         :username => (the supplied username)
+  #     #      },
+  #     #      the response
+  #     #    ]
+  #     #
+  #     # for incorrect credentials:
+  #     # => [nil, the response]
+  #
+  # The value in :token should be supplied as a cookie on subsequent requests,
+  # and can be passed as a credential when using Analysand::Database
+  # methods, e.g.
+  #
+  #     db = Analysand::Database.new(...)
+  #     session, resp = instance.establish_session(username, password)
+  #
+  #     db.put(doc, session[:token])
+  #
+  #
+  # Renewing a session
+  # ------------------
+  #
+  #     auth, _ = instance.establish_session('username', 'password')
+  #     # ...time passes...
+  #     session, resp = instance.renew_session(auth)
+  #
+  # Note: CouchDB doesn't always renew a session when asked; see the
+  # documentation for #renew_session for more details.
+  #
+  class Instance
+    attr_reader :http
+    attr_reader :uri
+
+    def initialize(uri)
+      raise InvalidURIError, 'You must supply an absolute URI' unless uri.absolute?
+
+      @http = Net::HTTP::Persistent.new('catalog_database')
+      @uri = uri
+    end
+
+    def establish_session(username, password)
+      path = uri + "/_session"
+
+      req = Net::HTTP::Post.new(path.to_s)
+      req.add_field('Content-Type', 'application/x-www-form-urlencoded')
+      req.body =
+        "name=#{URI.encode(username)}&password=#{URI.encode(password)}"
+
+      resp = http.request path, req
+
+      if Net::HTTPSuccess === resp
+        [session(resp), resp]
+      else
+        [nil, resp]
+      end
+    end
+
+    ##
+    # Attempts to renew a session.
+    #
+    # If the session was renewed, returns a session information hash identical
+    # in form to the hash returned by #establish_session.  If the session was
+    # not renewed, returns the passed-in hash.
+    #
+    #
+    # Renewal behavior
+    # ================
+    #
+    # CouchDB will only send a new session cookie if the current time is
+    # close enough to the session timeout.  For CouchDB, that means that the
+    # current time must be within a 10% timeout window (i.e. time left before
+    # timeout < timeout * 0.9).
+    def renew_session(old_session)
+      path = uri + "/_session"
+
+      req = Net::HTTP::Get.new(path.to_s)
+      req.add_field('Cookie', old_session[:token])
+
+      resp = http.request path, req
+
+      if Net::HTTPSuccess === resp
+        if !resp.get_fields('Set-Cookie')
+          [old_session, resp]
+        else
+          [session(resp), resp]
+        end
+      else
+        [nil, resp]
+      end
+    end
+
+    private
+
+    def session(resp)
+      token = resp.get_fields('Set-Cookie').
+        detect { |c| c =~ /^AuthSession=([^;]+)/i }
+
+      fields = Base64.decode64($1).split(':')
+      username = fields[0]
+      time = fields[1].to_i(16)
+
+      body = JSON.parse(resp.body)
+      roles = body.has_key?('userCtx') ?
+        body['userCtx']['roles'] : body['roles']
+
+      { :issued_at => time,
+        :roles => roles,
+        :token => token,
+        :username => username
+      }
+    end
+  end
+end
+
+# vim:ts=2:sw=2:et:tw=78

data/lib/analysand/response.rb

@@ -0,0 +1,45 @@
+require 'forwardable'
+require 'json/ext'
+
+module Analysand
+  ##
+  # The response object is a wrapper around Net::HTTPResponse that provides a
+  # few amenities:
+  #
+  # 1. A #success? method.  It returns true if the response code is between
+  #    (200..299) and false otherwise.
+  # 2. Automatic JSON deserialization of all response bodies.
+  # 3. Delegates the [] property accessor to the body.
+  class Response
+    extend Forwardable
+
+    attr_reader :response
+    attr_reader :body
+
+    def_delegators :body, :[]
+
+    def initialize(response)
+      @response = response
+
+      if !@response.body.nil? && !@response.body.empty?
+        @body = JSON.parse(@response.body)
+      end
+    end
+
+    def etag
+      response.get_fields('ETag').first.gsub('"', '')
+    end
+
+    def success?
+      c = code.to_i
+
+      c >= 200 && c <= 299
+    end
+
+    def code
+      response.code
+    end
+  end
+end
+
+# vim:ts=2:sw=2:et:tw=78

data/lib/analysand/version.rb

@@ -0,0 +1,3 @@
+module Analysand
+  VERSION = "1.0.1"
+end

data/lib/analysand/view_response.rb

@@ -0,0 +1,24 @@
+require 'analysand/response'
+
+module Analysand
+  ##
+  # A subclass of Response with additional view-specific accessors: total_rows,
+  # offset, and rows.
+  class ViewResponse < Response
+    def total_rows
+      body['total_rows']
+    end
+
+    def offset
+      body['offset']
+    end
+
+    def rows
+      body['rows']
+    end
+
+    def docs
+      rows.map { |r| r['doc'] }.compact
+    end
+  end
+end

data/script/setup_database.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+
+require File.expand_path('../../spec/support/test_parameters', __FILE__)
+require 'digest'
+require 'json'
+
+include TestParameters
+
+admin_command = ['curl',
+                 '-X PUT',
+                 %Q{--data-binary '"#{admin_password}"'},
+                 "#{instance_uri}/_config/admins/#{admin_username}"
+].join(' ')
+
+salt = "ff518dabd59b04b527de7c55179059a46ac54976"
+
+member_doc = {
+  "name" => member1_username,
+  "salt" => salt,
+  "password_sha" => Digest::SHA1.hexdigest("#{member1_password}#{salt}"),
+  "type" => "user",
+  "roles" => []
+}
+
+member_command = ['curl',
+                  '-X PUT',
+                  "--data-binary '#{member_doc.to_json}'",
+                  "-u #{admin_username}:#{admin_password}",
+                  "#{instance_uri}/_users/org.couchdb.user:#{member1_username}"
+].join(' ')
+
+db_command = ['curl',
+             '-X PUT',
+             "-u #{admin_username}:#{admin_password}",
+             database_uri.to_s
+].join(' ')
+
+[ admin_command,
+  member_command,
+  db_command
+].each do |cmd|
+  puts cmd
+  system cmd
+  puts
+end

data/spec/analysand/a_session_grantor.rb

@@ -0,0 +1,40 @@
+require 'base64'
+
+shared_examples_for 'a session grantor' do
+  let(:result) { instance.establish_session(credentials[:username], credentials[:password]) }
+  let(:role_locator) do
+    lambda { |resp| resp['roles'] }
+  end
+
+  before do
+    @session, @resp = result
+  end
+
+  it 'returns a session and the original response' do
+    @session.should_not be_nil
+    @resp.should_not be_nil
+  end
+
+  describe 'the session object' do
+    it 'has the username' do
+      @session[:username].should == credentials[:username]
+    end
+
+    it 'has the token issuance time' do
+      @session[:token] =~ /AuthSession=([^;]+)/
+
+      time_as_hex = Base64.decode64($1).split(':')[1]
+      issuance_time = time_as_hex.to_i(16)
+
+      @session[:issued_at].should == issuance_time
+    end
+
+    it 'has the user roles' do
+      @session[:roles].should == role_locator[JSON.parse(@resp.body)]
+    end
+
+    it 'has a session token' do
+      @session[:token].should =~ /AuthSession.+/
+    end
+  end
+end

data/spec/analysand/change_watcher_spec.rb

@@ -0,0 +1,84 @@
+require 'spec_helper'
+
+require 'analysand/change_watcher'
+require 'analysand/database'
+require 'celluloid'
+
+module Analysand
+  describe ChangeWatcher do
+    class TestWatcher < Analysand::ChangeWatcher
+      attr_accessor :changes
+
+      def initialize(database, credentials)
+        super(database)
+
+        self.changes = []
+
+        @credentials = credentials
+      end
+
+      def customize_request(req)
+        req.basic_auth(@credentials[:username], @credentials[:password])
+      end
+
+      def process(change)
+        changes << change
+        change_processed(change)
+      end
+    end
+
+    let(:db) { Database.new(database_uri) }
+
+    before do
+      create_databases!
+    end
+
+    after do
+      Celluloid.shutdown
+
+      drop_databases!
+    end
+
+    describe '#changes_feed_uri' do
+      let!(:watcher) { TestWatcher.new(db, admin_credentials) }
+
+      describe 'when invoked multiple times' do
+        it 'returns what it returned the first time' do
+          uri1 = watcher.changes_feed_uri
+          uri2 = watcher.changes_feed_uri
+
+          uri1.should == uri2
+        end
+      end
+    end
+
+    describe '#waiter_for' do
+      let!(:watcher) { TestWatcher.new(db, admin_credentials) }
+
+      describe 'if the given document has not been processed' do
+        it 'blocks until the document has been processed' do
+          waiter = watcher.waiter_for('bar')
+
+          Thread.new do
+            db.put('foo', { 'foo' => 'bar' }, admin_credentials)
+            db.put('bar', { 'foo' => 'bar' }, admin_credentials)
+          end
+
+          waiter.wait
+
+          watcher.changes.detect { |r| r['id'] == 'foo' }.should_not be_nil
+        end
+      end
+    end
+
+    it 'receives changes' do
+      watcher = TestWatcher.new(db, admin_credentials)
+
+      waiter = watcher.waiter_for('foo')
+      db.put('foo', { 'foo' => 'bar' }, admin_credentials)
+      waiter.wait
+
+      watcher.changes.select { |r| r['id'] == 'foo' }.length.should == 1
+    end
+  end
+end

data/spec/analysand/database_spec.rb

@@ -0,0 +1,228 @@
+require 'spec_helper'
+
+require 'analysand/database'
+require 'analysand/errors'
+require 'thread'
+require 'uri'
+
+module Analysand
+  describe Database do
+    let(:db) { Database.new(database_uri) }
+
+    describe '#initialize' do
+      it 'requires an absolute URI' do
+        lambda { Database.new(URI("/abc")) }.should raise_error(InvalidURIError)
+      end
+    end
+
+    describe '.create!' do
+      before do
+        drop_databases!
+      end
+
+      it 'creates the database at the given URI' do
+        db = Database.create!(database_uri, admin_credentials)
+
+        resp = db.ping
+        resp.body['db_name'].should == database_name
+      end
+
+      it 'raises an exception if the database cannot be created' do
+        Database.create!(database_uri, admin_credentials)
+
+        lambda { Database.create!(database_uri, admin_credentials) }.should raise_error(DatabaseError)
+      end
+    end
+
+    describe '.drop' do
+      before do
+        create_databases!
+      end
+
+      it 'drops the database at the given URI' do
+        resp = Database.drop(database_uri, admin_credentials)
+
+        resp.should be_success
+        Database.new(database_uri).ping.code.should == '404'
+      end
+    end
+
+    describe '#close' do
+      it "shuts down the current thread's connection" do
+        pending 'a good way to test this'
+      end
+    end
+
+    describe '#head' do
+      before do
+        clean_databases!
+
+        db.put!('foo', { 'foo' => 'bar' })
+      end
+
+      it 'retrieves the rev of a document' do
+        resp = db.head('foo')
+
+        resp.etag.should_not be_empty
+      end
+    end
+
+    describe '#get!' do
+      before do
+        clean_databases!
+
+        db.put!('foo', { 'foo' => 'bar' })
+      end
+
+      describe 'if the response code is 200' do
+        it 'returns the document' do
+          db.get!('foo').body['foo'].should == 'bar'
+        end
+      end
+
+      describe 'if the response code is 404' do
+        it 'raises Analysand::CannotAccessDocument' do
+          lambda { db.get!('bar') }.should raise_error(Analysand::CannotAccessDocument)
+        end
+
+        it 'includes the response in the exception' do
+          code = nil
+
+          begin
+            db.get!('bar')
+          rescue Analysand::CannotAccessDocument => e
+            code = e.response.code
+          end
+
+          code.should == '404'
+        end
+      end
+    end
+
+    describe '#get_attachment' do
+      let(:io) { StringIO.new('an attachment') }
+
+      before do
+        clean_databases!
+
+        db.put_attachment('doc_id/a', io, {}, admin_credentials)
+      end
+
+      xit 'permits streaming' do
+        resp = db.get_attachment('doc_id/a')
+
+        lambda { resp.read_body { } }.should_not raise_error
+      end
+    end
+
+    describe '#view' do
+      before do
+        clean_databases!
+
+        doc = {
+          'views' => {
+            'a_view' => {
+              'map' => %q{function (doc) { emit(doc['_id'], 1); }}
+            },
+            'composite_key' => {
+              'map' => %q{function (doc) { emit([1, doc['_id']], 1); }}
+            }
+          }
+        }
+
+        db.put('_design/doc', doc, admin_credentials)
+        db.put('abc123', {}, admin_credentials)
+        db.put('abc456', {}, admin_credentials)
+      end
+
+      it 'retrieves _all_docs' do
+        resp = db.view('_all_docs')
+
+        resp.code.should == '200'
+      end
+
+      it 'retrieves a view' do
+        resp = db.view('doc/a_view')
+
+        resp.code.should == '200'
+        resp.total_rows.should == resp.body['total_rows']
+        resp.offset.should == resp.body['offset']
+        resp.rows.should == resp.body['rows']
+      end
+
+      it 'passes through view parameters' do
+        resp = db.view('doc/a_view', :skip => 1)
+
+        resp.offset.should == 1
+        resp.rows.length.should == 1
+      end
+
+      it 'JSON-encodes the key parameter' do
+        resp = db.view('doc/composite_key', :key => [1, 'abc123'])
+
+        resp.code.should == '200'
+        resp.rows.length.should == 1
+      end
+
+      it 'JSON-encodes the keys parameter' do
+        resp = db.view('doc/composite_key', :keys => [[1, 'abc123'], [1, 'abc456']])
+
+        resp.code.should == '200'
+        resp.rows.length.should == 2
+      end
+
+      it 'JSON-encodes the startkey parameter' do
+        resp = db.view('doc/composite_key', :startkey => [1, 'abc123'])
+
+        resp.code.should == '200'
+        resp.rows.length.should == 2
+      end
+
+      it 'JSON-encodes the endkey parameter' do
+        resp = db.view('doc/composite_key', :endkey => [1, 'abc456'], :skip => 1)
+
+        resp.code.should == '200'
+        resp.rows.length.should == 1
+      end
+
+      it 'passes credentials' do
+        security = {
+          'members' => {
+            'names' => [member1_username],
+            'roles' => []
+          }
+        }
+
+        db.put!('_security', security, admin_credentials)
+
+        resp = db.view('doc/a_view', { :skip => 1 }, member1_credentials)
+
+        resp.code.should == '200'
+      end
+    end
+
+    describe '#view!' do
+      before do
+        clean_databases!
+      end
+
+      describe 'if the response code is 404' do
+        it 'raises Analysand::CannotAccessView' do
+          lambda { db.view!('unknown/view') }.should raise_error(Analysand::CannotAccessView)
+        end
+
+        it 'includes the response in the exception' do
+          code = nil
+
+          begin
+            db.view!('unknown/view')
+          rescue Analysand::CannotAccessView => e
+            code = e.response.code
+          end
+
+          code.should == '404'
+        end
+      end
+    end
+  end
+end