Behaviour for an outbound HTTP transport, the client-side dual of livery_adapter.

An adapter owns the wire: it takes a livery_client:request() and produces a livery_client:response() (or an error). The composable layers (timeout, retry, concurrency, circuit breaker) sit above it and do not care which transport runs underneath. The default adapter is livery_client_hackney (HTTP/1.1, HTTP/2, and HTTP/3 via hackney); write your own to front a different client.

Callbacks

• request(Request, Opts) -> {ok, Response} | {error, term()} - send one request. The adapter owns its connections and pooling.

• read(Reader, Timeout) -> {ok, Data, Reader} | {done, Reader} | {error, term()} - optional; pull the next chunk of a streamed response body. Only adapters that return a {stream, Reader} response body implement it.

• stream(Request, Opts, StreamOpts) -> {ok, Ref} | {error, term()} - optional; drive the request in a background process owned by the adapter and deliver the response to StreamOpts's stream_to pid as ordered {livery_response, Ref, _} messages ({status, Status, Headers}, {chunk, Binary}, done, {error, Reason}). StreamOpts carries stream_to (the recipient) and flow (auto to push as fast as the wire allows, manual to send one chunk per stream_next/1). Ref is opaque and identifies the stream for stream_next/1 and stop_stream/1.

• stream_next(Ref) -> ok | {error, term()} - optional; under flow => manual, ask for one more body chunk.

• stop_stream(Ref) -> ok - optional; cancel a push stream and release its connection.

• adopt(Reader, Owner) -> ok | {error, term()} - optional; hand the live connection behind a {stream, Reader} response body to Owner. A layer that runs the request in a short-lived worker (e.g. livery_client_timeout) calls this to reparent the connection to the process that will read it, before the worker exits. Only adapters whose streamed reader is tied to its owning process need it.