roadrunner_resp (roadrunner v0.7.0)
View SourceConvenience builders for the buffered {Status, Headers, Body}
triple — one of the five shapes a roadrunner handler can return.
Each helper sets Content-Type and Content-Length so handlers
don't repeat the boilerplate. Body framing (Connection: close,
Transfer-Encoding, etc.) is still the connection layer's job —
these helpers only fill in what the handler can know.
These helpers only construct the buffered form
(buffered_response/0). Streaming, loop, sendfile, and
WebSocket-upgrade handlers build their own tuple directly; see
roadrunner_handler:response/0 for the full union.
Summary
Functions
Prepend a header to an existing response triple.
Empty 400 Bad Request response.
Empty 403 Forbidden response.
HTML response with text/html; charset=utf-8.
Empty 500 Internal Server Error response.
JSON response — the term is encoded via the stdlib json module
(OTP 27+) and Content-Type is set to application/json.
Empty 405 Method Not Allowed response with an Allow header listing
the permitted methods, comma-separated (RFC 9110 requires Allow on a
405). Pass the uppercase method binaries the resource accepts.
NDJSON response — each item in Items is framed as one compact JSON
document on its own line via roadrunner_ndjson:item/1, and
Content-Type is set to application/x-ndjson. The buffered companion
to a {stream, ...} handler that pushes roadrunner_ndjson:item/1 per
line; reach for this when the whole list fits in memory.
Empty 204 No Content response.
Empty 404 Not Found response.
Redirect response — sets the Location header and an empty body.
Use a 3xx status (typically 301, 302, 303, 307, or 308).
Add a Set-Cookie header to a response — wraps roadrunner_cookie:serialize/3
so handlers don't have to.
Empty-body response with an arbitrary status code — handy for statuses outside the named shortcut set (e.g., 418, 503).
Plain-text response with text/plain; charset=utf-8.
Empty 401 Unauthorized response.
Types
-type buffered_response() :: {roadrunner_http:status(), roadrunner_http:headers(), iodata()}.
Functions
-spec add_header(buffered_response(), Name :: binary(), Value :: iodata()) -> buffered_response().
Prepend a header to an existing response triple.
The header is added to the front of the list — last-write-wins for
any subsequent lookup. Value may be iodata; it is flattened into a
binary so the wire encoder doesn't have to.
-spec bad_request() -> buffered_response().
Empty 400 Bad Request response.
-spec forbidden() -> buffered_response().
Empty 403 Forbidden response.
-spec html(StatusCode :: roadrunner_http:status(), Body :: iodata()) -> buffered_response().
HTML response with text/html; charset=utf-8.
The charset suffix is intentional — modern browsers default to
ISO-8859-1 absent an explicit charset in the response header,
which is wrong for ~all current content. To match a server that
emits bare text/html (e.g. cowboy's default), override after the
build:
roadrunner_resp:add_header(
roadrunner_resp:html(200, Body), ~"content-type", ~"text/html"
).add_header/3 prepends, so the bare value wins on header lookup.
-spec internal_error() -> buffered_response().
Empty 500 Internal Server Error response.
-spec json(StatusCode :: roadrunner_http:status(), Term :: term()) -> buffered_response().
JSON response — the term is encoded via the stdlib json module
(OTP 27+) and Content-Type is set to application/json.
-spec method_not_allowed([binary()]) -> buffered_response().
Empty 405 Method Not Allowed response with an Allow header listing
the permitted methods, comma-separated (RFC 9110 requires Allow on a
405). Pass the uppercase method binaries the resource accepts.
-spec ndjson(StatusCode :: roadrunner_http:status(), Items :: [term()]) -> buffered_response().
NDJSON response — each item in Items is framed as one compact JSON
document on its own line via roadrunner_ndjson:item/1, and
Content-Type is set to application/x-ndjson. The buffered companion
to a {stream, ...} handler that pushes roadrunner_ndjson:item/1 per
line; reach for this when the whole list fits in memory.
-spec no_content() -> buffered_response().
Empty 204 No Content response.
-spec not_found() -> buffered_response().
Empty 404 Not Found response.
-spec redirect(StatusCode :: roadrunner_http:redirect_status(), Location :: binary()) -> buffered_response().
Redirect response — sets the Location header and an empty body.
Use a 3xx status (typically 301, 302, 303, 307, or 308).
-spec set_cookie(buffered_response(), Name :: binary(), Value :: binary(), roadrunner_cookie:serialize_opts()) -> buffered_response().
Add a Set-Cookie header to a response — wraps roadrunner_cookie:serialize/3
so handlers don't have to.
-spec status(roadrunner_http:status()) -> buffered_response().
Empty-body response with an arbitrary status code — handy for statuses outside the named shortcut set (e.g., 418, 503).
-spec text(StatusCode :: roadrunner_http:status(), Body :: iodata()) -> buffered_response().
Plain-text response with text/plain; charset=utf-8.
-spec unauthorized() -> buffered_response().
Empty 401 Unauthorized response.