dpla-analysand 3.0.2

data/lib/analysand/http.rb

@@ -0,0 +1,90 @@
+require 'forwardable'
+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
+    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)
+      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

@@ -0,0 +1,255 @@
+require 'analysand/config_response'
+require 'analysand/errors'
+require 'analysand/http'
+require 'analysand/response'
+require 'analysand/session_response'
+require 'base64'
+require 'net/http/persistent'
+require 'rack/utils'
+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
+  # ----------------------
+  #
+  #     resp, = instance.post_session('username', 'password')
+  #     cookie = resp.session_cookie
+  #
+  # For harmony, the same credentials hash accepted by database methods is
+  # also supported:
+  #
+  #     resp = instance.post_session(:username => 'username',
+  #                                  :password => 'password')
+  #
+  #
+  # resp.success? will be true if the session cookie is not empty, false
+  # otherwise.
+  #
+  #
+  # Testing a session cookie for validity
+  # -------------------------------------
+  #
+  #     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.
+  #
+  #
+  # 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
+  # ------------------------------------------
+  #
+  #     v = instance.get_config('couchdb_httpd_auth/allow_persistent_cookies',
+  #       credentials)
+  #     v.value # => false
+  #
+  #     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"'
+  #
+  #     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 #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.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.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
+    include Rack::Utils
+
+    def initialize(uri)
+      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
+                           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', body, headers)
+    end
+
+    def get_session(cookie)
+      headers = { 'Cookie' => cookie }
+
+      SessionResponse.new get('_session', headers)
+    end
+
+    def get_config(key, credentials = nil)
+      ConfigResponse.new get("_config/#{key}", {}, credentials)
+    end
+
+    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 delete_config(key, credentials = nil)
+      ConfigResponse.new delete("_config/#{key}", {}, credentials)
+    end
+
+    def delete_config!(key, credentials = nil)
+      raise_delete_error { delete_config(key, credentials) }
+    end
+
+    private
+
+    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
+
+# vim:ts=2:sw=2:et:tw=78

data/lib/analysand/reading.rb

@@ -0,0 +1,26 @@
+require 'analysand/errors'
+require 'analysand/response'
+
+module Analysand
+  module Reading
+    def get(doc_id, credentials = nil)
+      Response.new(_get(doc_id, credentials))
+    end
+
+    def get!(doc_id, credentials = nil)
+      get(doc_id, credentials).tap do |resp|
+        raise ex(CannotAccessDocument, resp) unless resp.success?
+      end
+    end
+
+    def head(doc_id, credentials = nil)
+      Response.new(_head(doc_id, credentials))
+    end
+
+    def get_attachment(loc, credentials = nil)
+      _get(loc, credentials)
+    end
+  end
+end
+
+# vim:ts=2:sw=2:et:tw=78

data/lib/analysand/response.rb

@@ -0,0 +1,35 @@
+require 'analysand/response_headers'
+require 'analysand/status_code_predicates'
+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, which checks if 200 <= response code <= 299.
+  # 2. A #conflict method, which checks if response code == 409.
+  # 3. Automatic JSON deserialization of all response bodies.
+  # 4. Delegates the [] property accessor to the body.
+  class Response
+    extend Forwardable
+    include ResponseHeaders
+    include StatusCodePredicates
+
+    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
+  end
+end
+
+# vim:ts=2:sw=2:et:tw=78

data/lib/analysand/response_headers.rb

@@ -0,0 +1,18 @@
+module Analysand
+  module ResponseHeaders
+    def etag
+      response.get_fields('ETag').first.gsub('"', '')
+    end
+
+    def cookies
+      response.get_fields('Set-Cookie')
+    end
+
+    def session_cookie
+      return unless (cs = cookies)
+
+      cs.detect { |c| c =~ /^(AuthSession=[^;]+)/i }
+      $1
+    end
+  end
+end

data/lib/analysand/session_response.rb

@@ -0,0 +1,16 @@
+require 'analysand/response'
+
+module Analysand
+  # Public: Wraps the response from GET /_session.
+  #
+  # GET /_session can be a bit surprising.  A 200 OK response from _session
+  # indicates that the session cookie was well-formed; it doesn't indicate that
+  # the session is _valid_.
+  #
+  # Hence, this class adds a #valid? predicate.
+  class SessionResponse < Response
+    def valid?
+      (uc = body['userCtx']) && uc['name']
+    end
+  end
+end

data/lib/analysand/status_code_predicates.rb

@@ -0,0 +1,25 @@
+module Analysand
+  module StatusCodePredicates
+    def code
+      response.code
+    end
+
+    def success?
+      c = code.to_i
+
+      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
+  end
+end