@spec active_tasks(t()) :: {:error, any()} | {:ok, t(), [String.t()]}

Get _active_tasks. Only available to admin users.

@spec all_dbs(t()) :: {:error, any()} | {:ok, t(), [String.t()]}

List all databases. Only available to admin users.

@spec auth_info(nil | String.t()) :: %{} | %{user: String.t(), password: String.t()}

Returns user & password credentials extracted from a typical %URI{} userinfo field, as a Tesla-compatible authorization header. Currently only supports BasicAuth user:password combination.

Examples

iex> Sofa.auth_info("admin:password")
%{username: "admin", password: "password"}

iex> Sofa.auth_info("blank:")
%{username: "blank", password: ""}

iex> Sofa.auth_info("garbage")
%{}

@spec client(t()) :: t()

Builds Telsa runtime client, with appropriate middleware header credentials, from supplied %Sofa{} struct.

@spec connect(String.t() | t()) :: {:ok, t()} | {:error, any()}

Given an existing %Sofa{} struct, or a prepared URI, attempts to connect to the CouchDB instance, and returns an updated %Sofa{} to use in future connections to this server, using the same HTTP credentials.

Returns an updated {:ok, %Sofa{}} on success, or {:error, reason}, if for example, the URL is unreachable, times out, supplied credentials are rejected by CouchDB, or returns unexpected HTTP status codes.

@spec connect!(String.t() | t()) :: t()

Bang! wrapper around Sofa.connect/1; raises exceptions on error.

@spec init(uri :: String.t() | URI.t()) :: t()

Takes an optional parameter, the CouchDB uri, and returns a struct containing the usual CouchDB server properties. The URI may be given as a string or as a %URI struct.

This should be piped into Sofa.client/1 to create the HTTP client, which is stored inside the struct with correct authentication information.

Examples

iex> Sofa.init("https://very:Secure@foreignho.st:6984/")

%Sofa{
  auth: "very:Secure",
  features: nil,
  uri: %URI{
    authority: "very:Secure@foreignho.st:6984",
    fragment: nil,
    host: "foreignho.st",
    path: "/",
    port: 6984,
    query: nil,
    scheme: "https",
    userinfo: "very:Secure"
  },
  uuid: nil,
  vendor: nil,
  version: nil
}

@spec raw(
  t(),
  Tesla.Env.url(),
  Tesla.Env.method(),
  Tesla.Env.opts(),
  Tesla.Env.body(),
  Tesla.Env.headers()
) :: {:error, any()} | {:ok, t(), Sofa.Response.t()}

Minimal wrapper around native CouchDB HTTP API, allowing an escape hatch for raw functionality, and as the core abstraction layer for Sofa itself.

@spec raw!(
  t(),
  Tesla.Env.url(),
  Tesla.Env.method(),
  Tesla.Env.opts(),
  Tesla.Env.body()
) :: Sofa.Response.t()

Bang! wrapper around Sofa.raw/1; raises exceptions on error.