analysand 1.1.0 → 2.0.0

data/CHANGELOG

@@ -1,6 +1,14 @@
 Issue numbers refer to issues on Analysand's Github tracker:
 https://github.com/yipdw/analysand/issues
 
+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
+* Session handling on Instance rewritten: #post_session, #get_session
+* New response methods: #cookies, #session_cookie
+
 1.1.0 (2012-11-03)
 ------------------
 
@@ -9,7 +17,6 @@ https://github.com/yipdw/analysand/issues
 * Some code organization cleanups
 * require "analysand" now loads the Database and Instance classes
 
-
 1.0.1 (2012-10-01)
 ------------------
 

data/Rakefile

@@ -5,4 +5,18 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new
 
+namespace :git do
+  desc 'Strip trailing whitespace from tracked source files'
+  task :strip_spaces do
+    `git ls-files`.split("\n").each do |file|
+      puts file
+
+      if `file '#{file}'` =~ /text/
+        sh "git stripspace < '#{file}' > '#{file}.out'"
+        mv "#{file}.out", file
+      end
+    end
+  end
+end
+
 task :default => :spec

data/lib/analysand/change_watcher.rb

@@ -81,7 +81,7 @@ module Analysand
     def initialize(database)
       @db = database
       @waiting = {}
-      @http_parser = Http::Parser.new(self)
+      @http_parser = ::Http::Parser.new(self)
       @json_parser = Yajl::Parser.new
       @json_parser.on_parse_complete = lambda { |doc| process(doc) }
 

data/lib/analysand/config_response.rb

@@ -0,0 +1,24 @@
+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
+    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
+    end
+  end
+end

data/lib/analysand/database.rb

@@ -1,11 +1,9 @@
 require 'analysand/errors'
+require 'analysand/http'
 require 'analysand/reading'
 require 'analysand/response'
 require 'analysand/viewing'
 require 'analysand/writing'
-require 'net/http/persistent'
-require 'rack/utils'
-require 'uri'
 
 module Analysand
   ##
@@ -249,7 +247,13 @@ module Analysand
   #    as a cookie from CouchDB's Session API.  The string is used as the
   #    value of a Cookie header.
   #
-  # To get a token, use a CouchDB::Instance (ahem) instance.
+  # There are two ways to retrieve a token:
+  #
+  # 1. Establishing a session.  You can use
+  #    Analysand::Instance#establish_sesssion for this.
+  # 2. CouchDB may also issue updated session cookies as part of a response.
+  #    You can access such cookies using #session_cookie on the response
+  #    object.
   #
   # Omitting the credentials argument, or providing a form of credentials not
   # listed here, will result in no credentials being passed in the request.
@@ -263,13 +267,15 @@ module Analysand
   # connection per (uri.host, uri.port, thread) tuple, so connection pooling
   # is also done.
   class Database
-    include Rack::Utils
+    include Errors
+    include Http
     include Reading
     include Viewing
     include Writing
 
-    attr_reader :http
-    attr_reader :uri
+    def initialize(uri)
+      init_http_client(uri)
+    end
 
     def self.create!(uri, credentials = nil)
       new(uri).tap { |db| db.create!(credentials) }
@@ -279,19 +285,6 @@ module Analysand
       new(uri).drop(credentials)
     end
 
-    def initialize(uri)
-      raise InvalidURIError, 'You must supply an absolute URI' unless uri.absolute?
-
-      @http = Net::HTTP::Persistent.new('analysand_database')
-      @uri = uri
-
-      # Document IDs and other database bits are appended to the URI path,
-      # so we need to make sure that it ends in a /.
-      unless uri.path.end_with?('/')
-        uri.path += '/'
-      end
-    end
-
     def ping(credentials = nil)
       Response.new _get('', credentials)
     end
@@ -300,10 +293,6 @@ module Analysand
       ping(credentials).body
     end
 
-    def close
-      http.shutdown
-    end
-
     def create(credentials = nil)
       Response.new _put('', credentials)
     end
@@ -324,59 +313,9 @@ module Analysand
       end
     end
 
-    %w(Head Get Put Post Delete Copy).each do |m|
-      str = <<-END
-        def _#{m.downcase}(doc_id, credentials, query = {}, headers = {}, body = nil, block = nil)
-          _req(Net::HTTP::#{m}, doc_id, credentials, query, headers, body, block)
-        end
-      END
-
-      class_eval str, __FILE__, __LINE__
-    end
-
-    ##
-    # @private
-    def _req(klass, doc_id, credentials, query, headers, body, block)
-      uri = self.uri.dup
-      uri.path += URI.escape(doc_id)
-      uri.query = build_query(query) unless query.empty?
-
-      req = klass.new(uri.request_uri)
-
-      headers.each { |k, v| req.add_field(k, v) }
-      req.body = body if body && req.request_body_permitted?
-      set_credentials(req, credentials)
-
-      http.request(uri, req, &block)
-    end
-
-    ##
-    # Sets credentials on a request object.
-    #
-    # If creds is a hash containing :username and :password keys, HTTP basic
-    # authorization is used.  If creds is a string, the string is added as a
-    # cookie.
-    def set_credentials(req, creds)
-      return unless creds
-
-      if String === creds
-        req.add_field('Cookie', creds)
-      elsif creds[:username] && creds[:password]
-        req.basic_auth(creds[:username], creds[:password])
-      end
-    end
-
     def json_headers
       { 'Content-Type' => 'application/json' }
     end
-
-    ##
-    # @private
-    def ex(klass, response)
-      klass.new("Expected response to have code 2xx, got #{response.code} instead").tap do |ex|
-        ex.response = response
-      end
-    end
   end
 end
 

data/lib/analysand/errors.rb

@@ -1,4 +1,17 @@
 module Analysand
+  # Private: Methods to generate exceptions.
+  module Errors
+    # Instantiates an exception and fills in a response.
+    #
+    # klass    - the exception class
+    # response - the response object that caused the error
+    def ex(klass, response)
+      klass.new("Expected response to have code 2xx, got #{response.code} instead").tap do |ex|
+        ex.response = response
+      end
+    end
+  end
+
   class InvalidURIError < StandardError
   end
 
@@ -6,6 +19,9 @@ module Analysand
     attr_accessor :response
   end
 
+  class ConfigurationNotSaved < DatabaseError
+  end
+
   class DocumentNotSaved < DatabaseError
   end
 

data/lib/analysand/http.rb

@@ -0,0 +1,80 @@
+require 'net/http/persistent'
+require 'rack/utils'
+require 'uri'
+
+module Analysand
+  # Private: HTTP client methods for Database and Instance.
+  #
+  # Users of this module MUST set @http and @uri in their initializer.  @http
+  # SHOULD be a Net::HTTP::Persistent instance, and @uri SHOULD be a URI
+  # instance.
+  module Http
+    include Rack::Utils
+
+    attr_reader :http
+    attr_reader :uri
+
+    def init_http_client(uri)
+      unless uri.respond_to?(:path) && uri.respond_to?(:absolute?)
+        uri = URI(uri)
+      end
+
+      raise InvalidURIError, 'You must supply an absolute URI' unless uri.absolute?
+
+      @http = Net::HTTP::Persistent.new('analysand')
+      @uri = uri
+
+      # Document IDs and other database bits are appended to the URI path,
+      # so we need to make sure that it ends in a /.
+      unless uri.path.end_with?('/')
+        uri.path += '/'
+      end
+    end
+
+    def close
+      http.shutdown
+    end
+
+    %w(Head Get Put Post Delete Copy).each do |m|
+      str = <<-END
+        def _#{m.downcase}(doc_id, credentials, query = {}, headers = {}, body = nil, block = nil)
+          _req(Net::HTTP::#{m}, doc_id, credentials, query, headers, body, block)
+        end
+      END
+
+      module_eval str, __FILE__, __LINE__
+    end
+
+    ##
+    # @private
+    def _req(klass, doc_id, credentials, query, headers, body, block)
+      uri = self.uri.dup
+      uri.path += URI.escape(doc_id)
+      uri.query = build_query(query) unless query.empty?
+
+      req = klass.new(uri.request_uri)
+
+      headers.each { |k, v| req.add_field(k, v) }
+      req.body = body if body && req.request_body_permitted?
+      set_credentials(req, credentials)
+
+      http.request(uri, req, &block)
+    end
+
+    ##
+    # Sets credentials on a request object.
+    #
+    # If creds is a hash containing :username and :password keys, HTTP basic
+    # authorization is used.  If creds is a string, the string is added as a
+    # cookie.
+    def set_credentials(req, creds)
+      return unless creds
+
+      if String === creds
+        req.add_field('Cookie', creds)
+      elsif creds[:username] && creds[:password]
+        req.basic_auth(creds[:username], creds[:password])
+      end
+    end
+  end
+end

data/lib/analysand/instance.rb

@@ -1,7 +1,11 @@
+require 'analysand/config_response'
 require 'analysand/errors'
+require 'analysand/http'
+require 'analysand/response'
+require 'analysand/session_response'
 require 'base64'
-require 'json/ext'
 require 'net/http/persistent'
+require 'rack/utils'
 require 'uri'
 
 module Analysand
@@ -34,119 +38,160 @@ module Analysand
   # 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]
+  #     resp, = instance.post_session('username', 'password')
+  #     cookie = resp.session_cookie
   #
-  # 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.
+  # For harmony, the same credentials hash accepted by database methods is
+  # also supported:
   #
-  #     db = Analysand::Database.new(...)
-  #     session, resp = instance.establish_session(username, password)
+  #     resp = instance.post_session(:username => 'username',
+  #                                  :password => 'password')
   #
-  #     db.put(doc, session[:token])
   #
+  # resp.success? will be true if the session cookie is not empty, false
+  # otherwise.
   #
-  # Renewing a session
-  # ------------------
   #
-  #     auth, _ = instance.establish_session('username', 'password')
-  #     # ...time passes...
-  #     session, resp = instance.renew_session(auth)
+  # Testing a session cookie for validity
+  # -------------------------------------
   #
-  # Note: CouchDB doesn't always renew a session when asked; see the
-  # documentation for #renew_session for more details.
+  #     resp = instance.get_session(cookie)
   #
+  # In CouchDB 1.2.0, the response body is a JSON object that looks like
+  #
+  #       {
+  #           "info": {
+  #               "authentication_db": "_users",
+  #               "authentication_handlers": [
+  #                   "oauth",
+  #                   "cookie",
+  #                   "default"
+  #               ]
+  #           },
+  #           "ok": true,
+  #           "userCtx": {
+  #               "name": "username",
+  #               "roles": ["member"]
+  #           }
+  #       }
+  #
+  # resp.valid? will be true if userCtx['name'] is non-null, false otherwise.
+  #
+  #
+  # Getting and setting instance configuration
+  # ------------------------------------------
+  #
+  #     v = instance.get_config('couchdb_httpd_auth/allow_persistent_cookies',
+  #       credentials)
+  #     v.value # => false
+  #
+  #     instance.set_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
+  #
+  # 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
+  # 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)
+  #     # => #<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)
+  #     # => on non-2xx response, raises ConfigurationNotSaved
   class Instance
-    attr_reader :http
-    attr_reader :uri
+    include Errors
+    include Http
+    include Rack::Utils
 
     def initialize(uri)
-      raise InvalidURIError, 'You must supply an absolute URI' unless uri.absolute?
+      init_http_client(uri)
+    end
 
-      @http = Net::HTTP::Persistent.new('catalog_database')
-      @uri = uri
+    def post_session(*args)
+      username, password = if args.length == 2
+                             args
+                           else
+                             h = args.first
+                             [h[:username], h[:password]]
+                           end
+
+      headers = { 'Content-Type' => 'application/x-www-form-urlencoded' }
+      body = build_query('name' => username, 'password' => password)
+
+      Response.new _post('_session', nil, {}, headers, body)
     end
 
-    def establish_session(username, password)
-      path = uri + "/_session"
+    def get_session(cookie)
+      headers = { 'Cookie' => cookie }
 
-      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)}"
+      SessionResponse.new _get('_session', nil, {}, headers, nil)
+    end
 
-      resp = http.request path, req
+    def get_config(key, credentials = nil)
+      ConfigResponse.new _get("_config/#{key}", credentials)
+    end
 
-      if Net::HTTPSuccess === resp
-        [session(resp), resp]
-      else
-        [nil, resp]
-      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
 
-    ##
-    # 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]
+    def set_config!(key, value, credentials = nil)
+      set_config(key, value, credentials).tap do |resp|
+        raise ex(ConfigurationNotSaved, resp) unless resp.success?
       end
     end
 
     private
 
-    def session(resp)
-      token = resp.get_fields('Set-Cookie').
-        detect { |c| c =~ /^AuthSession=([^;]+)/i }
+    def session(cookie, resp)
+      token = cookie.split('=', 2).last
+      fields = Base64.decode64(token).split(':')
 
-      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']
+      roles = resp.body.has_key?('userCtx') ?
+        resp.body['userCtx']['roles'] : resp.body['roles']
 
       { :issued_at => time,
         :roles => roles,
-        :token => token,
+        :token => cookie,
         :username => username
       }
     end