roadrunner (roadrunner v0.1.0)
View SourcePublic API for the roadrunner HTTP server.
Listeners are supervised by roadrunner_sup: starting a listener adds a
roadrunner_listener child, stopping one terminates and forgets it. The
roadrunner application must be running (typically via
application:ensure_all_started(roadrunner)).
Configure listeners via the roadrunner_listener:opts/0 map; see
that type for the full set of available keys, defaults, and tuning
rationale.
Summary
Functions
Emit [roadrunner, drain, acknowledged] for the current request, signalling
to subscribers that a long-running handler ({loop, ...} or WebSocket)
has observed and is honoring an in-flight roadrunner_listener:drain/2
broadcast. Handlers should call this from their handle_info/3 (loop)
or handle_frame/2 (websocket) when they pattern-match on
{roadrunner_drain, _} and decide to wind down.
Same as acknowledge_drain/1 but threads the drain Deadline
(in milliseconds, the second element of the {roadrunner_drain, Deadline}
message a handler received) into the telemetry metadata so subscribers
can compute Deadline - erlang:monotonic_time(millisecond) for the
remaining grace period.
Return the list of currently registered listener names.
Start a listener as a supervised child of the roadrunner application.
Stop a previously started listener and remove it from the supervision tree.
Functions
-spec acknowledge_drain(roadrunner_req:request()) -> ok.
Emit [roadrunner, drain, acknowledged] for the current request, signalling
to subscribers that a long-running handler ({loop, ...} or WebSocket)
has observed and is honoring an in-flight roadrunner_listener:drain/2
broadcast. Handlers should call this from their handle_info/3 (loop)
or handle_frame/2 (websocket) when they pattern-match on
{roadrunner_drain, _} and decide to wind down.
Req is the request map the handler received. Returns ok. Calling
this when no drain is in flight is harmless — subscribers see a stray
event and ignore it — but the documented usage is post-drain-receipt.
For SREs computing "how much grace did the handler use," see
acknowledge_drain/2 which threads the Deadline from the
{roadrunner_drain, Deadline} message into the event metadata.
-spec acknowledge_drain(roadrunner_req:request(), integer()) -> ok.
Same as acknowledge_drain/1 but threads the drain Deadline
(in milliseconds, the second element of the {roadrunner_drain, Deadline}
message a handler received) into the telemetry metadata so subscribers
can compute Deadline - erlang:monotonic_time(millisecond) for the
remaining grace period.
-spec listeners() -> [atom()].
Return the list of currently registered listener names.
Order matches supervisor:which_children/1 — typically reverse
start-order. The roadrunner application must be running.
-spec start_listener(Name :: atom(), roadrunner_listener:opts()) -> {ok, pid()} | {error, term()}.
Start a listener as a supervised child of the roadrunner application.
Name becomes the listener's registered atom; pass the same name to
stop_listener/1 later. Returns {ok, Pid} on success or {error, _}
if a child with the same name already exists or the listen socket
cannot be opened.
Opts is a roadrunner_listener:opts/0 map — see that type for
the full set of keys, per-key defaults, and tuning rationale.
-spec stop_listener(Name :: atom()) -> ok | {error, not_found}.
Stop a previously started listener and remove it from the supervision tree.
Returns ok on success or {error, not_found} if no listener is
registered under Name.