analysand 2.0.0 → 3.0.0

data/.gitignore

@@ -16,3 +16,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.ruby-version

data/CHANGELOG

@@ -1,8 +1,42 @@
 Issue numbers refer to issues on Analysand's Github tracker:
 https://github.com/yipdw/analysand/issues
 
+3.0.0 (2013-07-08)
+------------------
+
+* Change Celluloid dependency to 0.14.
+
+3.0.0.pre2 (2013-04-15)
+-----------------------
+
+* Change Celluloid dependency to 0.13.
+  Please note: Analysand does not require celluloid/autostart.  It's up to you
+  to decide whether or not you need that for your application.
+
+3.0.0.pre (2013-02-26)
+----------------------
+
+* Instance#set_config renamed to Instance#put_config
+* Instance#put_admin, Instance#delete_admin for db admin setup
+* JSON encoding/decoding removed from Instance#*_config methods: all values are
+  sent to/received from CouchDB verbatim.  This means that you'll have to quote all values,
+  e.g.
+
+     instance.set_config("stats/rate", 1200)
+
+  becomes
+
+     instance.put_config("stats/rate", '"1200"')
+
+
+x.y.z (2012-12-31)
+------------------
+
+* Analysand::Writing#bulk_docs! now raises BulkOperationFailed on 401 responses
+
 2.0.0 (2012-11-29)
 ------------------
+
 * Instance#establish_session and Instance#renew_session now return a (session,
   Analysand::Response pair)
 * Share HTTP code between Database and Instance

data/README

@@ -1,18 +1,20 @@
-Analysand - a terrible burden for a couch
------------------------------------------
+1. Analysand
 
 Analysand is a CouchDB client library of dubious worth.  It was extracted from
-https://github.com/amvorg-underground/catalog.
+the a-m-v.org catalog application:
+https://code.ninjawedding.org/git/amvorg-underground/catalog.git.
 
 Analysand was written for Ruby 1.9.  It is known to work on Ruby 1.9.3-p194 and
 Rubinius 2.0.0.
 
-Features:
+2. Features
 
 * GET, PUT, DELETE on databases
 * GET, PUT, DELETE, HEAD, COPY on documents
 * GET, PUT on document attachments
 * GET, POST on views
+* GET, PUT on server configuration
+* GET, PUT, POST on arbitrary service handlers
 * POST /_session
 * POST /_bulk_docs
 * View streaming
@@ -20,8 +22,7 @@ Features:
 * Cookie and HTTP Basic authentication for all of the above
 * Database objects can be safely shared across threads
 
-Developing Analysand
---------------------
+3. Development
 
 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
@@ -36,7 +37,12 @@ Naturally, we hang with all the cool kids:
 * Code Climate: https://codeclimate.com/github/yipdw/analysand
 * Gemnasium: https://gemnasium.com/yipdw/analysand
 
-License
--------
+4. License
 
 Copyright 2012 David Yip; made available under the MIT license.
+
+5. Special thanks
+
+Fear of Tigers, 3LAU, Ellie Goulding, TeddyLoid, Susumu Hirasawa.
+
+# vim:ts=2:sw=2:et:tw=78

data/analysand.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |gem|
 
   gem.required_ruby_version = '>= 1.9'
 
-  gem.add_dependency 'celluloid', '>= 0.12'
+  gem.add_dependency 'celluloid', '~> 0.14.0'
   gem.add_dependency 'celluloid-io'
   gem.add_dependency 'http_parser.rb'
   gem.add_dependency 'json'

data/lib/analysand/bulk_response.rb

@@ -6,7 +6,7 @@ module Analysand
   # records.
   class BulkResponse < Response
     def success?
-      body.none? { |r| r.has_key?('error') }
+      super && body.none? { |r| r.has_key?('error') }
     end
   end
 end

data/lib/analysand/change_watcher.rb

@@ -163,12 +163,6 @@ module Analysand
       @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:
@@ -267,6 +261,14 @@ module Analysand
       @socket.write("\r\n\r\n")
     end
 
+    ##
+    # @private
+    def disconnect
+      @socket.close if @socket && !@socket.closed?
+    end
+
+    finalizer :disconnect
+
     ##
     # @private
     def prepare_request

data/lib/analysand/config_response.rb

@@ -3,22 +3,23 @@ require 'analysand/response'
 module Analysand
   # Public: Wraps responses from /_config.
   #
-  # Not all responses from sub-resources of _config return valid JSON objects,
-  # but JSON.parse expects to see a full JSON object.  This object implements a
-  # bit of a hacky workaround if the body does not start with a '{' and end
-  # with a '}', then it is not run through the JSON parser.
-  class ConfigResponse < Response
+  # GET/PUT/DELETE /_config does not return a valid JSON object in all cases.
+  # This response object therefore does The Simplest Possible Thing and just
+  # gives you back the response body as a string.
+  class ConfigResponse
+    include ResponseHeaders
+    include StatusCodePredicates
+
+    attr_reader :response
+    attr_reader :body
+
     alias_method :value, :body
 
     def initialize(response)
-      body = response.body.chomp
-
-      if body.start_with?('{') && body.end_with?('}')
-        super
-      else
-        @response = response
-        @body = body
-      end
+      @response = response
+      @body = response.body.chomp
     end
   end
 end
+
+# vim:ts=2:sw=2:et:tw=78

data/lib/analysand/errors.rb

@@ -22,6 +22,9 @@ module Analysand
   class ConfigurationNotSaved < DatabaseError
   end
 
+  class ConfigurationNotDeleted < DatabaseError
+  end
+
   class DocumentNotSaved < DatabaseError
   end
 

data/lib/analysand/http.rb

@@ -1,3 +1,4 @@
+require 'forwardable'
 require 'net/http/persistent'
 require 'rack/utils'
 require 'uri'
@@ -9,11 +10,20 @@ module Analysand
   # SHOULD be a Net::HTTP::Persistent instance, and @uri SHOULD be a URI
   # instance.
   module Http
+    extend Forwardable
+
     include Rack::Utils
 
     attr_reader :http
     attr_reader :uri
 
+    SSL_METHODS = %w(
+      certificate ca_file cert_store private_key
+      reuse_ssl_sessions ssl_version verify_callback verify_mode
+    ).map { |m| [m, "#{m}="] }.flatten
+
+    def_delegators :http, *SSL_METHODS
+
     def init_http_client(uri)
       unless uri.respond_to?(:path) && uri.respond_to?(:absolute?)
         uri = URI(uri)

data/lib/analysand/instance.rb

@@ -78,6 +78,24 @@ module Analysand
   # resp.valid? will be true if userCtx['name'] is non-null, false otherwise.
   #
   #
+  # Adding and removing admins
+  # --------------------------
+  #
+  #     instance.put_admin('admin', 'password', credentials)
+  #     # => #<ConfigResponse code=200 ...>
+  #     instance.delete_admin('admin', credentials)
+  #     # => #<ConfigResponse code=200 ...>
+  #
+  # Obviously, you'll need admin credentials to manage the admin list.
+  #
+  # There also exist bang-method variants:
+  #
+  #     instance.put_admin!('admin', 'password', bad_creds)
+  #     # => raises ConfigurationNotSaved on failure
+  #     instance.delete_admin!('admin', bad_creds)
+  #     # => raises ConfigurationNotDeleted on failure
+  #
+  #
   # Getting and setting instance configuration
   # ------------------------------------------
   #
@@ -85,33 +103,58 @@ module Analysand
   #       credentials)
   #     v.value # => false
   #
-  #     instance.set_config('couchdb_httpd_auth/allow_persistent_cookies',
-  #       true, credentials)
+  #     instance.put_config('couchdb_httpd_auth/allow_persistent_cookies',
+  #       '"true"', credentials)
   #     # => #<Response code=200 ...>
   #
   #     v = instance.get_config('couchdb_httpd_auth/allow_persistent_cookies',
   #       credentials)
-  #     v.value #=> true
+  #     v.value #=> '"true"'
+  #
+  #     instance.delete_config('couchdb_httpd_auth/allow_persistent_cookies',
+  #       credentials)
   #
   # You can get configuration at any level:
   #
   #     v = instance.get_config('', credentials)
   #     v.body['stats']['rate']  # => "1000", or whatever you have it set to
   #
-  # #get_config and #set_config both return Response-like objects.  You can
+  # #get_config and #put_config both return Response-like objects.  You can
   # check for failure or success that way:
   #
   #     v = instance.get_config('couchdb_httpd_auth/allow_persistent_cookies')
   #     v.code # => '403'
   #
-  #     instance.set_config('couchdb_httpd_auth/allow_persistent_cookies', false)
+  #     instance.put_config('couchdb_httpd_auth/allow_persistent_cookies', '"false"')
   #     # => #<Response code=403 ...>
   #
   # If you want to set configuration and just want to let errors bubble
   # up the stack, you can use the bang-variants:
   #
-  #     instance.set_config!('stats/rate', 1000)
+  #     instance.put_config!('stats/rate', '"1000"')
   #     # => on non-2xx response, raises ConfigurationNotSaved
+  #
+  #     instance.delete_config!('stats/rate')
+  #     # => on non-2xx response, raises ConfigurationNotDeleted
+  #
+  #
+  # Other instance-level services
+  # -----------------------------
+  #
+  # CouchDB can be extended with additional service handlers; authentication
+  # handlers are a popular example.
+  #
+  # Instance exposes #get, #put, and #post methods to access arbitrary
+  # endpoints.
+  #
+  # Examples:
+  #
+  #     instance.get('_log', {}, admin_credentials)
+  #     instance.post('_browserid', { 'assertion' => assertion },
+  #       { 'Content-Type' => 'application/json' })
+  #     instance.put('_config/httpd/bind_address', '192.168.0.1', {},
+  #       admin_credentials)
+  #
   class Instance
     include Errors
     include Http
@@ -121,6 +164,38 @@ module Analysand
       init_http_client(uri)
     end
 
+    def get(path, headers = {}, credentials = nil)
+      _get(path, credentials, {}, headers)
+    end
+
+    def post(path, body = nil, headers = {}, credentials = nil)
+      _post(path, credentials, {}, headers, body)
+    end
+
+    def put(path, body = nil, headers = {}, credentials = nil)
+      _put(path, credentials, {}, headers, body)
+    end
+
+    def delete(path, headers = {}, credentials = nil)
+      _delete(path, credentials, {}, headers)
+    end
+
+    def put_admin(username, password, credentials = nil)
+      put_config("admins/#{username}", %Q{"#{password}"}, credentials)
+    end
+
+    def put_admin!(username, password, credentials = nil)
+      raise_put_error { put_admin(username, password, credentials) }
+    end
+
+    def delete_admin(username, credentials = nil)
+      delete_config("admins/#{username}", credentials)
+    end
+
+    def delete_admin!(username, credentials = nil)
+      raise_delete_error { delete_admin(username, credentials) }
+    end
+
     def post_session(*args)
       username, password = if args.length == 2
                              args
@@ -132,68 +207,47 @@ module Analysand
       headers = { 'Content-Type' => 'application/x-www-form-urlencoded' }
       body = build_query('name' => username, 'password' => password)
 
-      Response.new _post('_session', nil, {}, headers, body)
+      Response.new post('_session', body, headers)
     end
 
     def get_session(cookie)
       headers = { 'Cookie' => cookie }
 
-      SessionResponse.new _get('_session', nil, {}, headers, nil)
+      SessionResponse.new get('_session', headers)
     end
 
     def get_config(key, credentials = nil)
-      ConfigResponse.new _get("_config/#{key}", credentials)
-    end
-
-    def set_config(key, value, credentials = nil)
-      # This is a bizarre transformation that deserves some explanation.
-      #
-      # CouchDB configuration is made available as strings containing JSON
-      # data.  GET /_config/stats, for example, will return something like
-      # this:
-      #
-      #     {"rate":"1000","samples":"[0, 60, 300, 900]"}
-      #
-      # However, I'd really like to write
-      #
-      #     instance.set_config('stats/samples', [0, 60, 300, 900])
-      #
-      # and I'd also like to be able to use values from get_config directly,
-      # just for symmetry:
-      #
-      #     v = instance1.get_config('stats/samples')
-      #     instance2.set_config('stats/samples', v)
-      #
-      # To accomplish this, we convert non-string values to JSON twice.
-      # Strings are passed through.
-      body = (String === value) ? value : value.to_json.to_json
-
-      ConfigResponse.new _put("_config/#{key}", credentials, {}, {}, body)
-    end
-
-    def set_config!(key, value, credentials = nil)
-      set_config(key, value, credentials).tap do |resp|
-        raise ex(ConfigurationNotSaved, resp) unless resp.success?
-      end
+      ConfigResponse.new get("_config/#{key}", {}, credentials)
     end
 
-    private
+    def put_config(key, value, credentials = nil)
+      ConfigResponse.new put("_config/#{key}", value, {}, credentials)
+    end
+
+    def put_config!(key, value, credentials = nil)
+      raise_put_error { put_config(key, value, credentials) }
+    end
 
-    def session(cookie, resp)
-      token = cookie.split('=', 2).last
-      fields = Base64.decode64(token).split(':')
+    def delete_config(key, credentials = nil)
+      ConfigResponse.new delete("_config/#{key}", {}, credentials)
+    end
 
-      username = fields[0]
-      time = fields[1].to_i(16)
+    def delete_config!(key, credentials = nil)
+      raise_delete_error { delete_config(key, credentials) }
+    end
 
-      roles = resp.body.has_key?('userCtx') ?
-        resp.body['userCtx']['roles'] : resp.body['roles']
+    private
 
-      { :issued_at => time,
-        :roles => roles,
-        :token => cookie,
-        :username => username
-      }
+    def raise_put_error
+      yield.tap do |resp|
+        raise ex(ConfigurationNotSaved, resp) unless resp.success?
+      end
+    end
+
+    def raise_delete_error
+      yield.tap do |resp|
+        raise ex(ConfigurationNotDeleted, resp) unless resp.success?
+      end
     end
   end
 end

data/lib/analysand/status_code_predicates.rb

@@ -10,6 +10,14 @@ module Analysand
       c >= 200 && c <= 299
     end
 
+    def unauthorized?
+      code.to_i == 401
+    end
+
+    def not_found?
+      code.to_i == 404
+    end
+
     def conflict?
       code.to_i == 409
     end