roadrunner_resp (roadrunner v0.8.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. The generic body/3,4 builder backs
the typed text, html, json, and ndjson helpers and is the
escape hatch for any other media type. Every content builder also
has a variant that takes a Headers list, added after the
content-type and content-length (which stay authoritative). 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.
Generic buffered response — set Status, the Content-Type header,
a Content-Length computed from Body, plus any caller Headers.
Generic buffered response with caller-supplied Headers.
Empty 403 Forbidden response.
HTML response with text/html; charset=utf-8.
HTML response with text/html; charset=utf-8 and caller-supplied
Headers, added after the content-type and content-length (which
stay authoritative).
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.
JSON response with caller-supplied Headers, added after the
content-type and content-length (which stay authoritative).
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.
NDJSON response with caller-supplied Headers, added after the
content-type and content-length (which stay authoritative).
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).
Redirect response with caller-supplied Headers, added after the
Location and content-length (which stay authoritative).
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).
Empty-body response with an arbitrary status code and caller-supplied
Headers, added after the content-length (which stays authoritative).
This is the headers path for the fixed-status helpers.
Plain-text response with text/plain; charset=utf-8.
Plain-text response with text/plain; charset=utf-8 and
caller-supplied Headers, added after the content-type and
content-length (which stay authoritative).
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 body(StatusCode :: roadrunner_http:status(), ContentType :: binary(), Body :: iodata()) -> buffered_response().
Generic buffered response — set Status, the Content-Type header,
a Content-Length computed from Body, plus any caller Headers.
The shared builder behind text/3, html/3, json/3, and
ndjson/3, and the escape hatch for any other media type. The
content-type and content-length come first and stay authoritative;
Headers are additive.
-spec body(StatusCode :: roadrunner_http:status(), ContentType :: binary(), Headers :: roadrunner_http:headers(), Body :: iodata()) -> buffered_response().
Generic buffered response with caller-supplied Headers.
Like body/3 with an extra Headers list added after the
content-type and content-length, which stay authoritative.
-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 html(StatusCode :: roadrunner_http:status(), Headers :: roadrunner_http:headers(), Body :: iodata()) -> buffered_response().
HTML response with text/html; charset=utf-8 and caller-supplied
Headers, added after the content-type and content-length (which
stay authoritative).
-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 json(StatusCode :: roadrunner_http:status(), Headers :: roadrunner_http:headers(), Term :: term()) -> buffered_response().
JSON response with caller-supplied Headers, added after the
content-type and content-length (which stay authoritative).
-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 ndjson(StatusCode :: roadrunner_http:status(), Headers :: roadrunner_http:headers(), Items :: [term()]) -> buffered_response().
NDJSON response with caller-supplied Headers, added after the
content-type and content-length (which stay authoritative).
-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 redirect(StatusCode :: roadrunner_http:redirect_status(), Headers :: roadrunner_http:headers(), Location :: binary()) -> buffered_response().
Redirect response with caller-supplied Headers, added after the
Location and content-length (which stay authoritative).
-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 status(roadrunner_http:status(), roadrunner_http:headers()) -> buffered_response().
Empty-body response with an arbitrary status code and caller-supplied
Headers, added after the content-length (which stays authoritative).
This is the headers path for the fixed-status helpers.
-spec text(StatusCode :: roadrunner_http:status(), Body :: iodata()) -> buffered_response().
Plain-text response with text/plain; charset=utf-8.
-spec text(StatusCode :: roadrunner_http:status(), Headers :: roadrunner_http:headers(), Body :: iodata()) -> buffered_response().
Plain-text response with text/plain; charset=utf-8 and
caller-supplied Headers, added after the content-type and
content-length (which stay authoritative).
-spec unauthorized() -> buffered_response().
Empty 401 Unauthorized response.