Filo.Client.Transport behaviour (Filo v0.2.0)

Copy Markdown View Source

The HTTP transport a Filo.Client drives — a behaviour, so Filo ships the Hrana protocol without pinning a concrete HTTP client on hosts (the same posture the server keeps with Plug/WebSock).

Filo provides Filo.Client.Transport.Mint as the default, behind the optional :mint dependency. A host that already runs Finch, Req, or :gun can implement this behaviour over it and pass it as Filo.Client.connect(url, transport: MyTransport).

An implementation owns one connection and issues requests on it serially (a Hrana stream is sequential — one baton-threaded round-trip at a time), so it does not need its own pool or concurrency.

Summary

Types

response()

A decoded HTTP response.

state()

Opaque per-connection state carried between calls by the client.

Callbacks

close(state)

Closes the connection. Always returns :ok.

connect(t, keyword)

Opens a connection to uri. opts carries at least :timeout (ms).

request(state, method, path, headers, body)

Sends one request on the held connection and reads the full response.

Types

response()

@type response() :: %{
  status: non_neg_integer(),
  headers: [{String.t(), String.t()}],
  body: binary()
}

A decoded HTTP response.

state()

@type state() :: term()

Opaque per-connection state carried between calls by the client.

Callbacks

close(state)

@callback close(state()) :: :ok

Closes the connection. Always returns :ok.

connect(t, keyword)

@callback connect(
  URI.t(),
  keyword()
) :: {:ok, state()} | {:error, term()}

Opens a connection to uri. opts carries at least :timeout (ms).

request(state, method, path, headers, body)

@callback request(
  state(),
  method :: String.t(),
  path :: String.t(),
  headers :: [{String.t(), String.t()}],
  body :: iodata()
) :: {:ok, response(), state()} | {:error, term(), state()}

Sends one request on the held connection and reads the full response.

Returns the advanced state either way so a transport error still hands the client a connection to close/1.

Report a dropped connection (the peer or a load balancer closed the socket) as the reason :closed — that is the sentinel Filo.Client treats as retryable, reconnecting and resuming the stream by baton. Any other reason is returned to the caller unretried.