Class: CouchRest::Connection
- Inherits:
-
Object
- Object
- CouchRest::Connection
- 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
-
.proxy ⇒ Object
Default proxy URL to use in all connections.
Instance Attribute Summary collapse
-
#http ⇒ Object
readonly
Returns the value of attribute http.
-
#last_response ⇒ Object
readonly
Returns the value of attribute last_response.
-
#options ⇒ Object
readonly
Returns the value of attribute options.
-
#uri ⇒ Object
readonly
Returns the value of attribute uri.
Instance Method Summary collapse
-
#copy(path, destination, options = {}) ⇒ Object
Send a COPY request to the URI provided.
-
#delete(path, options = {}) ⇒ Object
Send a DELETE request.
-
#get(path, options = {}, &block) ⇒ Object
Send a GET request.
-
#head(path, options = {}) ⇒ Object
Send a HEAD request.
-
#initialize(uri, options = {}) ⇒ Connection
constructor
A new instance of Connection.
-
#post(path, doc = nil, options = {}, &block) ⇒ Object
Send a POST request.
-
#put(path, doc = nil, options = {}) ⇒ Object
Send a PUT request.
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, = {}) raise "CouchRest::Connection.new requires URI::HTTP(S) parameter" unless uri.is_a?(URI::HTTP) @uri = clean_uri(uri) @options = .dup @http = prepare_http_connection end |
Class Attribute Details
.proxy ⇒ Object
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
#http ⇒ Object (readonly)
Returns the value of attribute http.
56 57 58 |
# File 'lib/couchrest/connection.rb', line 56 def http @http end |
#last_response ⇒ Object (readonly)
Returns the value of attribute last_response.
56 57 58 |
# File 'lib/couchrest/connection.rb', line 56 def last_response @last_response end |
#options ⇒ Object (readonly)
Returns the value of attribute options.
56 57 58 |
# File 'lib/couchrest/connection.rb', line 56 def @options end |
#uri ⇒ Object (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, = {}) opts = .nil? ? {} : .dup opts[:headers] = [:headers].nil? ? {} : [: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, = {}) execute('DELETE', path, ) end |
#get(path, options = {}, &block) ⇒ Object
Send a GET request.
66 67 68 |
# File 'lib/couchrest/connection.rb', line 66 def get(path, = {}, &block) execute('GET', path, , 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, = {}) = .merge(:head => true) # No parsing! execute('HEAD', path, ) 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, = {}, &block) execute('POST', path, , 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, = {}) execute('PUT', path, , doc) end |