Class: CouchRest::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/couchrest/connection.rb

Overview

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.

Constant Summary collapse

HEADER_CONTENT_SYMBOL_MAP =
{
  :content_type => 'Content-Type',
  :accept       => 'Accept'
}
DEFAULT_HEADERS =
{
  'Content-Type' => 'application/json',
  'Accept'       => 'application/json'
}
KNOWN_PARSER_OPTIONS =
[
  :max_nesting, :allow_nan, :quirks_mode, :create_additions
]
SUCCESS_RESPONSE_CODES =
[200, 201, 202, 204]

Class Attribute Summary collapse

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(uri, options = {}) ⇒ Connection

Returns a new instance of Connection.



58
59
60
61
62
63
# 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

Class Attribute Details

.proxyObject

Default proxy URL to use in all connections.



266
267
268
# File 'lib/couchrest/connection.rb', line 266

def proxy
  @proxy
end

Instance Attribute Details

#httpObject (readonly)

Returns the value of attribute http.



56
57
58
# File 'lib/couchrest/connection.rb', line 56

def http
  @http
end

#last_responseObject (readonly)

Returns the value of attribute last_response.



56
57
58
# File 'lib/couchrest/connection.rb', line 56

def last_response
  @last_response
end

#optionsObject (readonly)

Returns the value of attribute options.



56
57
58
# File 'lib/couchrest/connection.rb', line 56

def options
  @options
end

#uriObject (readonly)

Returns the value of attribute uri.



56
57
58
# File 'lib/couchrest/connection.rb', line 56

def uri
  @uri
end

Instance Method Details

#copy(path, destination, options = {}) ⇒ Object

Send a COPY request to the URI provided.



86
87
88
89
90
91
# 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 = {}) ⇒ Object

Send a DELETE request.



81
82
83
# File 'lib/couchrest/connection.rb', line 81

def delete(path, options = {})
  execute('DELETE', path, options)
end

#get(path, options = {}, &block) ⇒ Object

Send a GET request.



66
67
68
# File 'lib/couchrest/connection.rb', line 66

def get(path, options = {}, &block)
  execute('GET', path, options, nil, &block)
end

#head(path, options = {}) ⇒ Object

Send a HEAD request.



94
95
96
97
# 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) ⇒ Object

Send a POST request.



76
77
78
# 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 = {}) ⇒ Object

Send a PUT request.



71
72
73
# File 'lib/couchrest/connection.rb', line 71

def put(path, doc = nil, options = {})
  execute('PUT', path, options, doc)
end