ICouch v0.6.2 ICouch.Server View Source

Holds information about CouchDB server connections and encapsulates API calls.

Link to this section Summary

Types

An endpoint can be given as plain path, as 2-tuple of a path and (query) options or as URI.t. The path cannot contain a query string; if you need to specify a custom query string, convert the path including the query string with URI.parse/1.

t()

Functions

Returns a tuple of username and password which has been set in the server struct (or nil if not given).

Returns a server struct without credentials.

Encodes CouchDB style query options together with an endpoint and returns the resulting relative URI.

Helper function to determine if an enumerable header contains Content-Encoding (case insensitive) that is set to gzip (case sensitive).

Returns and removes the credentials in the given server struct.

Invokes an arbitrary CouchDB API call which may or may not be implementation specific.

Invokes an arbitrary CouchDB API call which may or may not be implementation specific.

Link to this section Types

Link to this type

body()

View Source
body() ::
  nil
  | binary()
  | (() -> {:ok, binary()} | :eof)
  | (state :: term() -> {:ok, binary(), new_state :: term()} | :eof)
Link to this type

endpoint()

View Source
endpoint() ::
  String.t()
  | URI.t()
  | {String.t() | URI.t(),
     options :: Keyword.t() | %{optional(atom()) => term()}}

An endpoint can be given as plain path, as 2-tuple of a path and (query) options or as URI.t. The path cannot contain a query string; if you need to specify a custom query string, convert the path including the query string with URI.parse/1.

Link to this type

method()

View Source
method() ::
  :get
  | :post
  | :head
  | :options
  | :put
  | :patch
  | :delete
  | :trace
  | :mkcol
  | :propfind
  | :proppatch
  | :lock
  | :unlock
  | :move
  | :copy
Link to this type

option()

View Source
option() ::
  {:max_sessions, integer()}
  | {:max_pipeline_size, integer()}
  | {:ssl_options, [any()]}
  | {:pool_name, atom()}
  | {:proxy_host, String.t()}
  | {:proxy_port, integer()}
  | {:proxy_user, String.t()}
  | {:proxy_password, String.t()}
  | {:basic_auth, {username :: String.t(), password :: String.t()}}
  | {:cookie, String.t()}
  | {:http_vsn, {major :: integer(), minor :: integer()}}
  | {:host_header, String.t()}
  | {:timeout, integer()}
  | {:inactivity_timeout, integer()}
  | {:connect_timeout, integer()}
  | {:max_attempts, integer()}
  | {:socket_options, [any()]}
  | {:worker_process_options, [any()]}
  | {:direct_conn_pid, pid()}
Link to this type

t()

View Source
t() :: %ICouch.Server{direct: nil, ib_options: [], timeout: nil, uri: URI.t()}

Link to this section Functions

Link to this function

credentials(server)

View Source
credentials(server :: t()) ::
  {username :: String.t(), password :: String.t()} | nil

Returns a tuple of username and password which has been set in the server struct (or nil if not given).

Link to this function

delete_credentials(server)

View Source
delete_credentials(server :: t()) :: t()

Returns a server struct without credentials.

Link to this function

endpoint_with_options(endpoint, options \\ [])

View Source

Encodes CouchDB style query options together with an endpoint and returns the resulting relative URI.

This function is applied to the entrypoint parameter of send_raw_req/6 and indirectly to send_req/4.

To be specific, the following option values are converted to a plain string: rev, filter, view, since, startkey_docid, endkey_docid

These options are deleted: multipart, stream_to

The batch option is either converted to :ok on true, or removed on false.

Options with values that are atoms are also converted to a plain string.

Options with nil values are removed.

Options given through query_params are also kept as-is but cannot override an option given normally.

Any other option value is converted to its JSON representation.

Link to this function

has_gzip_encoding?(headers)

View Source

Helper function to determine if an enumerable header contains Content-Encoding (case insensitive) that is set to gzip (case sensitive).

Link to this function

new(uri, options)

View Source
new(uri :: String.t() | URI.t(), options :: [option()]) :: t()

See ICouch.server_connection/2.

Link to this function

pop_credentials(server)

View Source
pop_credentials(server :: t()) ::
  {{username :: String.t(), password :: String.t()} | nil, t()}

Returns and removes the credentials in the given server struct.

If credentials are present, {{username, password}, new_server} is returned where new_server is the result of removing the credentials from server. If no credentials are present, {nil, server} is returned.

Link to this function

send_raw_req(server, endpoint, method \\ :get, body \\ nil, headers \\ [], ib_options \\ [])

View Source
send_raw_req(
  server :: t(),
  endpoint(),
  method(),
  body(),
  headers :: [{binary(), binary()}],
  ib_options :: Keyword.t()
) ::
  {:ok, {response_headers :: [{binary(), binary()}], response_body :: binary()}}
  | {:ibrowse_req_id, id :: term()}
  | {:error, ICouch.RequestError.well_known_error() | term()}

Invokes an arbitrary CouchDB API call which may or may not be implementation specific.

This expects the request body to be sent as binary (or function yielding binary chunks) and returns the raw response headers and the body as binary. There are no checks made if the request method actually allows a request body.

To use transparent JSON encoding and decoding for the requests use send_req/4.

Link to this function

send_req(server, endpoint, method \\ :get, body_term \\ nil)

View Source
send_req(server :: t(), endpoint(), method(), body_term :: term()) ::
  {:ok, body :: term()}
  | {:error, ICouch.RequestError.well_known_error() | term()}

Invokes an arbitrary CouchDB API call which may or may not be implementation specific.

Many functions of the main module make use of this function. It is exposed publicly so you can call arbitrary API functions yourself.

Note that there is transparent JSON encoding and decoding for the requests and the response headers are discarded; if you need raw data or the headers, use send_raw_req/6. Also checks are made if the request method actually allows a request body and discards it if needed.