analysand 1.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.sw?
+.rbx
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - rbx-19mode
+  - 1.9.3
+before_script:
+  - "./script/setup_database.rb"
+services:
+  - couchdb

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in analysand.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 David Yip
+
+MIT License
+
+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 OR COPYRIGHT HOLDERS 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

@@ -0,0 +1,41 @@
+Analysand - a terrible burden for a couch
+-----------------------------------------
+
+Analysand is a CouchDB client library of dubious worth.  It was extracted from
+https://github.com/amvorg-underground/catalog.
+
+Analysand was written for Ruby 1.9.  It is known to work on Ruby 1.9.3-p194 and
+Rubinius 2.0.0.
+
+Features:
+
+* GET, PUT, DELETE on databases
+* GET, PUT, DELETE, HEAD, COPY on documents
+* GET, PUT on document attachments
+* GET on views
+* POST /_session
+* POST /_bulk_docs
+* Celluloid::IO-based change feed watchers
+* Cookie and HTTP Basic authentication for all of the above
+* Database objects can be safely shared across threads
+
+Developing Analysand
+--------------------
+
+You'll need a CouchDB >= 1.1.0 instance.  I recommend not using a CouchDB
+instance that you're using for anything else; Analysand requires the presence
+of specific admin and non-admin users for its test suite.
+
+See spec/support/test_parameters.rb for usernames, passwords, and connection
+information.
+
+Naturally, we hang with all the cool kids:
+
+* Travis CI: http://travis-ci.org/#!/yipdw/analysand
+* Code Climate: https://codeclimate.com/github/yipdw/analysand
+* Gemnasium: https://gemnasium.com/yipdw/analysand
+
+License
+-------
+
+Copyright 2012 David Yip; made available under the MIT license.

data/Rakefile

@@ -0,0 +1,8 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/analysand.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/analysand/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["David Yip"]
+  gem.email         = ["yipdw@member.fsf.org"]
+  gem.description   = %q{A terrible burden for a couch}
+  gem.summary       = %q{A CouchDB client of dubious worth}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "analysand"
+  gem.require_paths = ["lib"]
+  gem.version       = Analysand::VERSION
+
+  gem.add_dependency 'celluloid', '>= 0.12'
+  gem.add_dependency 'celluloid-io'
+  gem.add_dependency 'http_parser.rb'
+  gem.add_dependency 'json'
+  gem.add_dependency 'net-http-persistent'
+  gem.add_dependency 'rack'
+  gem.add_dependency 'yajl-ruby'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'vcr'
+  gem.add_development_dependency 'webmock'
+end

data/bin/analysand

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+require 'analysand/database'
+require 'irb'
+require 'uri'
+
+$URI = URI('http://localhost:5984/analysand_test')
+
+
+def make_db(uri = $URI)
+  Analysand::Database.new(uri)
+end
+
+puts <<-END
+------------------------------------------------------------------------------
+Type make_db to make an Analysand::Database object.  The default URI is
+
+    #{$URI}
+
+To point at different databases, supply a URI object to make_db, e.g.
+
+    make_db(URI('https://couchdb.example.org:6984/supersekrit'))"
+------------------------------------------------------------------------------
+END
+
+IRB.start

data/lib/analysand.rb

@@ -0,0 +1,5 @@
+require "analysand/version"
+
+module Analysand
+  # Your code goes here...
+end

data/lib/analysand/bulk_response.rb

@@ -0,0 +1,14 @@
+require 'analysand/response'
+
+module Analysand
+  ##
+  # A subclass of Response that adjusts success? to check for individual error
+  # records.
+  class BulkResponse < Response
+    def success?
+      body.none? { |r| r.has_key?('error') }
+    end
+  end
+end
+
+# vim:ts=2:sw=2:et:tw=78

data/lib/analysand/change_watcher.rb

@@ -0,0 +1,276 @@
+require 'celluloid'
+require 'celluloid/io'
+require 'analysand/connection_testing'
+require 'http/parser'
+require 'net/http'
+require 'rack/utils'
+require 'uri'
+require 'yajl'
+
+module Analysand
+  ##
+  # A Celluloid::IO actor that watches the changes feed of a CouchDB database.
+  # When a change is received, it passes the change to a #process method.
+  #
+  # ChangeWatchers monitor changes using continuous mode and set up a heartbeat
+  # to fire approximately every 10 seconds.
+  #
+  # ChangeWatchers begin watching for changes as soon as they are initialized.
+  # To send a shutdown message:
+  #
+  #     a.stop
+  #
+  # The watcher will terminate on the next heartbeat.
+  #
+  #
+  # Failure modes
+  # =============
+  #
+  # ChangeWatcher deals with the following failures in the following ways:
+  #
+  # * If Errno::ECONNREFUSED is raised whilst connecting to CouchDB, it will
+  #   retry the connection in 30 seconds.
+  # * If the connection to CouchDB's changes feed is abruptly terminated, it
+  #   dies.
+  # * If an exception is raised during HTTP or JSON parsing, it dies.
+  #
+  # Situations where the actor dies should be handled by a supervisor.
+  #
+  #
+  # Example usage
+  # =============
+  #
+  #     class Accumulator < Analysand::ChangeWatcher
+  #       attr_accessor :results
+  #
+  #       def initialize(database)
+  #         super(database)
+  #
+  #         self.results = []
+  #       end
+  #
+  #       def process(change)
+  #         results << change
+  #
+  #         # Once a ChangeWatcher has successfully processed a change, it
+  #         # SHOULD invoke #change_processed.
+  #         change_processed(change)
+  #       end
+  #     end
+  #
+  #     a = Accumulator.new('http://localhost:5984/mydb')
+  #
+  #     # or with supervision:
+  #     a = Accumulator.supervise('http://localhost:5984/mydb')
+  class ChangeWatcher
+    include Celluloid::IO
+    include Celluloid::Logger
+    include ConnectionTesting
+    include Rack::Utils
+
+    # Read at most this many bytes off the socket at a time.
+    QUANTUM = 4096
+
+    ##
+    # Checks services.  If all services pass muster, enters a read loop.
+    #
+    # The database parameter may be either a URL-as-string or a
+    # Analysand::Database.
+    #
+    # If overriding the initializer, you MUST call super.
+    def initialize(database)
+      @db = database
+      @waiting = {}
+      @http_parser = Http::Parser.new(self)
+      @json_parser = Yajl::Parser.new
+      @json_parser.on_parse_complete = lambda { |doc| process(doc) }
+
+      async.start
+    end
+
+    # The URI of the changes feed.  This URI incorporates any changes
+    # made by customize_query.
+    def changes_feed_uri
+      query = {
+        'feed' => 'continuous',
+        'heartbeat' => '10000'
+      }
+
+      customize_query(query)
+
+      uri = (@db.respond_to?(:uri) ? @db.uri : URI(@db)).dup
+      uri.path += '/_changes'
+      uri.query = build_query(query)
+      uri
+    end
+
+    # The connection_ok method is called before connecting to the changes feed.
+    # By default, it checks that there's an HTTP service listening on the
+    # changes feed.
+    #
+    # If the method returns true, then we connect to the changes feed and begin
+    # processing.  If it returns false, a warning message is logged and the
+    # connection check will be retried in 30 seconds.
+    #
+    # This method can be overridden if you need to check additional services.
+    # When you override the method, make sure that you don't discard the return
+    # value of the original definition:
+    #
+    #     # Wrong
+    #     def connection_ok
+    #       super
+    #       ...
+    #     end
+    #
+    #     # Right
+    #     def connection_ok
+    #       ok = super
+    #
+    #       ok && my_other_test
+    #     end
+    def connection_ok
+      test_http_connection(changes_feed_uri)
+    end
+
+    def start
+      return if @started
+
+      @started = true
+
+      while !connection_ok
+        error "Some services used by #{self.class.name} did not check out ok; will retry in 30 seconds"
+        sleep 30
+      end
+
+      connect
+
+      info "#{self.class} entering read loop"
+
+      @running = true
+
+      while @running
+        @http_parser << @socket.readpartial(QUANTUM)
+      end
+
+      # Once we're done, close things up.
+      @started = false
+      @socket.close
+    end
+
+    def stop
+      @running = false
+    end
+
+    ##
+    # Called by Celluloid::IO's actor shutdown code.
+    def finalize
+      @socket.close if @socket && !@socket.closed?
+    end
+
+    ##
+    # Can be used to set query parameters.  query is a Hash.  The query hash
+    # has two default parameters:
+    #
+    # | Key       | Value      |
+    # | feed      | continuous |
+    # | heartbeat | 10000      |
+    #
+    # It is NOT RECOMMENDED that they be changed.
+    #
+    # By default, this does nothing.  Provide behavior in a subclass.
+    def customize_query(query)
+    end
+
+    ##
+    # Can be used to add headers.  req is a Net::HTTP::Get instance.
+    #
+    # By default, this does nothing.  Provide behavior in a subclass.
+    def customize_request(req)
+    end
+
+    ##
+    # This method should implement your change-processing logic.
+    #
+    # change is a Hash containing keys id, seq, and changes.  See [0] for
+    # more information.
+    #
+    # By default, this does nothing.  Provide behavior in a subclass.
+    #
+    # [0]: http://guide.couchdb.org/draft/notifications.html#continuous
+    def process(change)
+    end
+
+    class Waiter < Celluloid::Future
+      alias_method :wait, :value
+    end
+
+    ##
+    # Returns an object that can be used to block a thread until a document
+    # with the given ID has been processed.
+    #
+    # Intended for testing.
+    def waiter_for(id)
+      @waiting[id] = true
+
+      Waiter.new do
+        loop do
+          break true if !@waiting[id]
+          sleep 0.1
+        end
+      end
+    end
+
+    ##
+    # Notify waiters.
+    def change_processed(change)
+      @waiting.delete(change['id'])
+    end
+
+    ##
+    # Http::Parser callback.
+    #
+    # @private
+    def on_headers_complete(parser)
+      status = @http_parser.status_code.to_i
+
+      raise "Request failed: expected status 200, got #{status}" unless status == 200
+    end
+
+    ##
+    # Http::Parser callback.
+    #
+    # @private
+    def on_body(chunk)
+      @json_parser << chunk
+    end
+
+    ##
+    # @private
+    def connect
+      req = prepare_request
+      uri = changes_feed_uri
+
+      info "#{self.class} connecting to #{req.path}"
+
+      @socket = TCPSocket.new(uri.host, uri.port)
+
+      # Make the request.
+      data = [
+        "GET #{req.path} HTTP/1.1"
+      ]
+
+      req.each_header { |k, v| data << "#{k}: #{v}" }
+
+      @socket.write(data.join("\r\n"))
+      @socket.write("\r\n\r\n")
+    end
+
+    ##
+    # @private
+    def prepare_request
+      Net::HTTP::Get.new(changes_feed_uri.to_s).tap do |req|
+        customize_request(req)
+      end
+    end
+  end
+end