Client behaviour for Arangox. Arangox uses client implementations to perform all its connection and execution operations.

To use a library other than :velocy or :mint, implement this behaviour in a module and pass that module to the :client start option.

One error contract

Every callback that can fail returns %Arangox.Error{} and nothing else — not a POSIX atom, not a library exception struct, not a bare binary:

{:ok, socket} | {:error, Arangox.Error.t()}                     # connect/2
{:ok, Response.t(), state} | {:error, Arangox.Error.t(), state} # request/3

Arangox.Connection no longer classifies whatever a client happened to return; it reads :reason off the struct. Populate :reason with the transport's own atom (:econnrefused, :closed, ...) so applications can match on it.

The socket-gone signal

A client that detects a lost connection must be able to force a disconnect. Before, that was the {:error, :noproc, state} sentinel; now it is a reason class, listed by connection_lost_reasons/0 and tested by connection_lost?/1. The connection's execute callback maps any error whose reason is in that set to {:disconnect, ...}, which retires the socket and reconnects.

Getting this wrong is not a cosmetic error: a dead socket returned to the pool as an ordinary {:error, ...} stays checked in and fails every later checkout that draws it.

The set covers the socket genuinely being gone (:closed, :econnreset, :epipe, ...) and also :timeout/:etimedout, because a request/response exchange that timed out leaves an unread reply on the socket: the next request on it would read the previous request's response. :noproc is in the set too, so a third-party client written against the old sentinel keeps forcing disconnects.

Credentials

A client is where authentication material is closest to the wire, so it is where redaction has to happen. Two rules:

• never put a header value in an error — :mint echoes the offending value in {:invalid_header_value, name, value}, which for an authorization header is the credential itself. request/3 refuses a header carrying a carriage return, line feed, or null before any client sees it, reporting the name alone;
• never put a configured endpoint binary in an error — it may carry userinfo. Clients receive an already-parsed Arangox.Endpoint.t/0, which never has any, and Arangox.Connection fills in the (redacted) endpoint on the way out.

Request timeouts

No client may wait on a socket indefinitely. The budget reaches a client as two keys in the per-request options:

• :deadline — DBConnection's own option: the absolute monotonic instant, in milliseconds, by which the caller expects to be done. Arangox stamps it when the caller enters the pool, before checkout can spend any of the budget.
• :request_timeout — a per-request override of the pool's :request_timeout. A ceiling on the derived wait, never a replacement for it.

A client derives its socket wait from those and from the :request_timeout in Arangox.Connection.t/0, and it derives it again before every receive — a bound applied per recv call is not a bound on the request, since a response arriving in N chunks would get N budgets:

deadline = Arangox.Client.deadline(opts, state)

case Arangox.Client.socket_timeout(deadline, opts, state) do
  {:ok, timeout} -> transport_recv(socket, timeout)
  :elapsed -> {:error, %Arangox.Error{reason: :timeout}, state}
end

deadline/2 falls back to a request-local deadline when the caller established none, so a client called outside arangox's own request path is bounded too.

The remaining budget, never a duration. The caller's clock starts when it asks for a connection, not when one comes free, so a caller that queued out most of its allowance must get the remainder. Reading opts[:timeout] inside a callback and using it as a socket wait restarts a clock that has already been running; see docs/solutions/architecture-patterns/dbconnection-timeout-is-a-deadline-not-a-duration.md.

A timeout disconnects. Report it with :reason :timeout, which is in connection_lost_reasons/0. A timed-out HTTP/1.1 connection has unread bytes and an open request reference on it; returned to the pool, the next checkout reads the previous response.

Optional callbacks

alive?/1 is optional. A client that does not export it is treated as alive; see alive?/1.