livery_h1 (livery v0.1.0)

View Source

HTTP/1.1 adapter on top of the h1 library.

Starts an h1 server bound to a Livery middleware stack and handler. For every inbound request the adapter:

  1. Builds a #livery_req{} from the method, path, and headers delivered by h1.
  2. Spawns a livery_req_proc worker under livery_req_sup.
  3. Spawns a small translator that turns {h1, Conn, _} body and trailer events into the {livery_body, Ref, _} shape the worker reads via livery_body.
  4. Registers the translator as the h1 stream handler so the engine never blocks on the worker.

Response emission goes through livery:emit/3 and lands on the adapter callbacks (send_headers/4, send_data/3, send_trailers/2, reset/2), which in turn call into h1:send_response/4, h1:send_data/3,4, and h1:send_trailers/3.

Summary

Types

listen_opts()
listener()
stream()

Functions

accept_ws/4

Hand the stream's socket to the ws library to run a WebSocket session.

capabilities(Listener)
peer_info/1
reset/2
send_data/3
send_headers/4
send_trailers/2
start(Opts)

Start a listener with the given options.

start(Name, Opts, StartOpts)
stop(Listener)

Types

listen_opts()

-type listen_opts() ::
          #{port => inet:port_number(),
            transport => tcp | ssl,
            cert => binary() | string(),
            key => binary() | string(),
            cacerts => [binary()],
            acceptors => pos_integer(),
            max_body => non_neg_integer() | infinity,
            idle_timeout => timeout(),
            request_timeout => timeout(),
            handshake_timeout => timeout(),
            max_keepalive_requests => pos_integer() | infinity,
            stack := livery_middleware:stack(),
            handler := livery_middleware:handler()}.

listener()

-type listener() :: h1:server_ref().

stream()

-type stream() :: {h1:connection(), h1:stream_id()}.

Functions

accept_ws/4

-spec accept_ws(stream(), livery_req:req(), module(), term()) -> {ok, pid()} | {error, term()}.

Hand the stream's socket to the ws library to run a WebSocket session.

Validates the RFC 6455 handshake headers, replies 101 via h1:accept_upgrade/3, takes ownership of the raw socket, and calls ws:accept/5 with the supplied handler module and opts.

Returns {ok, SessionPid} on success or {error, _} on a bad handshake or socket transfer failure.

capabilities(Listener)

-spec capabilities(listener()) -> livery_adapter:capabilities().

peer_info/1

-spec peer_info(stream()) -> livery_adapter:peer_info().

reset/2

-spec reset(stream(), term()) -> ok.

send_data/3

-spec send_data(stream(), iodata(), livery_adapter:send_opts()) -> livery_adapter:send_result().

send_headers/4

-spec send_headers(stream(), 100..599, [{binary(), binary()}], livery_adapter:send_opts()) ->
                      livery_adapter:send_result().

send_trailers/2

-spec send_trailers(stream(), [{binary(), binary()}]) -> livery_adapter:send_result().

start(Opts)

-spec start(listen_opts()) -> {ok, listener()} | {error, term()}.

Start a listener with the given options.

Opts must include stack and handler. port defaults to 0 (random port). transport defaults to tcp. Returns the same listener handle the h1 library does, suitable for passing to stop/1 or to h1:server_port/1.

start(Name, Opts, StartOpts)

-spec start(atom() | undefined, listen_opts(), map()) -> {ok, listener()} | {error, term()}.

stop(Listener)

-spec stop(listener()) -> ok.