-spec dispatch(livery_middleware:stack(), livery_middleware:handler(), livery_req:req()) ->
                  livery_resp:resp().

Run a middleware stack and handler against a request value.

Pure dispatch: returns the #livery_resp{} value produced by the pipeline. Adapters generally invoke this from a per-request process and then call emit/3 to write the response back to the wire.

-spec drain(pid()) -> ok | {error, timeout}.

Gracefully drain and stop a service. See livery_drain:drain/1.

-spec drain(pid(), livery_drain:opts()) -> ok | {error, timeout}.

Gracefully drain and stop a service: stop accepting new connections, wait up to the timeout for in-flight requests to finish, then stop. See livery_drain:drain/2.

-spec emit(module(), livery_adapter:stream(), livery_resp:resp()) -> ok | {error, term()}.

Walk a response body variant and drive the adapter callbacks.

Called once a handler has returned. The walker emits status and headers, then iterates the body variant (full, chunked, sse, file, empty, or upgrade) into Adapter:send_headers/4, Adapter:send_data/3, and Adapter:send_trailers/2. Errors from the adapter are propagated by stopping the walk and returning the error tuple.

A {file, Path, Range} body is streamed from the filesystem in 64 KiB chunks. Content-Length is set from the resolved segment (unless the handler already set it); a byte range adds a Content-Range header. A missing file emits 404, an unsatisfiable range emits 416.

-spec router_handler(livery_router:router()) -> fun((livery_req:req()) -> livery_resp:resp()).

Turn a compiled router into a request handler.

Returns a fun((livery_req:req()) -> livery_resp:resp()) that matches the request's method and path against Router, sets the captured path parameters as bindings, and invokes the matched route handler. Unmatched paths get 404; a path that exists for a different method gets 405 with an Allow header.

Pass the result as the handler for a listener, or give the router directly to start_service/1 (which calls this for you).

-spec router_handler(livery_router:router(), map()) -> fun((livery_req:req()) -> livery_resp:resp()).

router_handler/1 with fallbacks.

Opts may set not_found => fun((Req) -> Resp) and method_not_allowed => fun((Req, [Method]) -> Resp) to override the default 404/405 responses.

-spec start_listener(atom(), map()) -> {ok, term()} | {error, term()}.

Start a single-protocol listener. Useful for serving over just one wire; for multi-protocol services with Alt-Svc, use start_service/1.

Name selects the adapter (livery_h1, livery_h2, or livery_h3). Opts is the adapter's listen_opts() map.

-spec start_service(livery_service:service_opts()) -> {ok, pid()} | {error, term()}.

Start the full service: H3 on UDP, H2 on TLS, H1 on TCP, sharing one middleware stack and handler, optionally advertising Alt-Svc on H1 and H2 responses.

See livery_service:start_link/1 for the opts shape.

-spec stop_listener({livery_h1, livery_h1:listener()} |
                    {livery_h2, livery_h2:listener()} |
                    {livery_h3, livery_h3:listener()} |
                    term()) ->
                       ok | {error, term()}.

Stop a single-protocol listener by adapter and handle.

-spec stop_service(pid()) -> ok.

Stop a running service by pid (immediate; cuts off in-flight).

-spec which_listeners(pid()) -> #{h1 | h2 | h3 => inet:port_number()}.

List the bound ports of a running service, keyed by protocol.

Returns a map containing only the protocols that were configured.