class CouchRest::Connection

Handle connections to the CouchDB server and provide a set of HTTP based methods to perform requests.

All connections are persistent and thread safe. A connection cannot be re-used to connect to other servers once instantiated.

Six types of REST requests are supported: get, put, post, delete, copy and head.

Requests that do not have a payload like GET, DELETE and COPY, accept the URI and options parameters. PUT and POST both expect a document as the second parameter.

The API will share the options between the HTTP connection and JSON parser.

When initializing a connection, the following options are available:

* `:timeout` (or `:read_timeout`) and `:open_timeout` the time in miliseconds to wait for the request, see the [Net HTTP Persistent documentation](http://docs.seattlerb.org/net-http-persistent/Net/HTTP/Persistent.html#attribute-i-read_timeout) for more details.
* `:verify_ssl` verify ssl certificates (or not)
* `:ssl_client_cert`, `:ssl_client_key` parameters controlling ssl client certificate authentication
* `:ssl_ca_file` load additional CA certificates from a file (or directory)

The following request options are supported:

* `:content_type`, type of content to be sent, especially useful when sending files as this will set the file type. The default is :json.
* `:accept`, the content type to accept in the response. This should pretty much always be `:json`.
* `:payload` override the document or data sent in the message body (only PUT or POST).
* `:headers` any additional headers (overrides :content_type and :accept if provided).

When :raw is true in PUT and POST requests, no attempt will be made to convert the document payload to JSON. This is not normally necessary as IO and Tempfile objects will not be parsed anyway. The result of the request will always be parsed.

For all other requests, mainly GET, the :raw option will make no attempt to parse the result. This is useful for receiving files from the database.

Constants

DEFAULT_HEADERS
HEADER_CONTENT_SYMBOL_MAP
KNOWN_PARSER_OPTIONS
SUCCESS_RESPONSE_CODES

Attributes

http[R]

last_response[R]

options[R]

uri[R]

Public Class Methods

new(uri, options = {}) click to toggle source

# File lib/couchrest/connection.rb, line 58
def initialize(uri, options = {})
  raise "CouchRest::Connection.new requires URI::HTTP(S) parameter" unless uri.is_a?(URI::HTTP)
  @uri = clean_uri(uri)
  @options = options.dup
  @http = prepare_http_connection
end

Public Instance Methods

copy(path, destination, options = {}) click to toggle source

Send a COPY request to the URI provided.

# File lib/couchrest/connection.rb, line 86
def copy(path, destination, options = {})
  opts = options.nil? ? {} : options.dup
  opts[:headers] = options[:headers].nil? ? {} : options[:headers].dup
  opts[:headers]['Destination'] = destination
  execute('COPY', path, opts)
end

delete(path, options = {}) click to toggle source

Send a DELETE request.

# File lib/couchrest/connection.rb, line 81
def delete(path, options = {})
  execute('DELETE', path, options)
end

get(path, options = {}, &block) click to toggle source

Send a GET request.

# File lib/couchrest/connection.rb, line 66
def get(path, options = {}, &block)
  execute('GET', path, options, nil, &block)
end

head(path, options = {}) click to toggle source

Send a HEAD request.

# File lib/couchrest/connection.rb, line 94
def head(path, options = {})
  options = options.merge(:head => true) # No parsing!
  execute('HEAD', path, options)
end

post(path, doc = nil, options = {}, &block) click to toggle source

Send a POST request.

# File lib/couchrest/connection.rb, line 76
def post(path, doc = nil, options = {}, &block)
  execute('POST', path, options, doc, &block)
end

put(path, doc = nil, options = {}) click to toggle source

Send a PUT request.

# File lib/couchrest/connection.rb, line 71
def put(path, doc = nil, options = {})
  execute('PUT', path, options, doc)
end