`flare.http.response`

HTTP response type.

Structs

`Status`

struct Status

Common HTTP status code constants (RFC 7231 §6).

Implements Movable

comptime OK = Int(200)

comptime CREATED = Int(201)

comptime ACCEPTED = Int(202)

comptime NO_CONTENT = Int(204)

comptime MOVED_PERMANENTLY = Int(301)

comptime FOUND = Int(302)

comptime NOT_MODIFIED = Int(304)

comptime TEMPORARY_REDIRECT = Int(307)

comptime PERMANENT_REDIRECT = Int(308)

comptime BAD_REQUEST = Int(400)

comptime UNAUTHORIZED = Int(401)

comptime FORBIDDEN = Int(403)

comptime NOT_FOUND = Int(404)

comptime METHOD_NOT_ALLOWED = Int(405)

comptime REQUEST_TIMEOUT = Int(408)

comptime CONTENT_TOO_LARGE = Int(413)

comptime URI_TOO_LONG = Int(414)

comptime HEADER_FIELDS_TOO_LARGE = Int(431)

comptime INTERNAL_SERVER_ERROR = Int(500)

comptime BAD_GATEWAY = Int(502)

comptime SERVICE_UNAVAILABLE = Int(503)

comptime GATEWAY_TIMEOUT = Int(504)

`ResponseImpl`

struct ResponseImpl[B: Body = InlineBody]

An HTTP/1.1 response, parameterised by its authoring body type B.

B is a phantom type parameter: it records the Body impl a handler authored the response with (for the typed Handler.BodyType UX) but does not change the runtime layout. The body is always carried by the erased carrier fields body (buffered bytes) or body_stream (a boxed streaming source), which is the single representation every wire driver consumes. Because a bare defaulted struct name is not itself concrete, the ergonomic public spelling is the comptime Response = ResponseImpl[InlineBody] alias below; all existing call sites keep working unchanged through it. Typed authoring builds ResponseImpl[SomeBody] and calls :meth:lower at the wire boundary to obtain the erased Response.

Fields: status: HTTP status code (see Status.* constants). reason: Status reason phrase (e.g. "OK"). headers: Response headers (owned HeaderMap). body: Response body bytes. version: HTTP version string (default "HTTP/1.1"). trailers: Response trailer fields (RFC 7230 §4.1.2). Empty for non-chunked responses; populated by the client when decoding a chunked response that carries trailer fields after the final chunk. Server-side trailer emission uses :class:StreamingResponse[B].trailers instead -- buffered :class:Response always frames with Content-Length so it never carries trailers outbound.

This type is Movable (owns headers and body) but not Copyable.

Example:

var resp = client.get("http://example.com")
if resp.ok():
    print(resp.text())
# Trailers (gRPC-style status, etc) are populated when the
# peer sent ``Transfer-Encoding: chunked`` with trailing
# fields after the zero chunk:
var grpc_status = resp.trailers.get("grpc-status")

Implements Movable

Fields: status: Int; reason: String; headers: HeaderMap; body: List[UInt8]; version: String; trailers: HeaderMap; body_stream: Optional[ChunkSourceBox]: Optional streaming body source (K1). None for the ordinary buffered response (the body field carries the bytes); Some when a handler returns a streaming response, in which case the reactor emits Transfer-Encoding: chunked headers and pulls this source a bounded batch of chunks at a time per writable edge instead of sending body. Move-only, so Response stays move-only.

`init`

def __init__(out self, status: Int, var reason: String = "", var body: List[UInt8] = List(), var version: String = "HTTP/1.1")

`reset`

def reset(mut self, status: Int = Int(200), var reason: String = "")

Recycle this Response in place for the next request on a keep-alive connection.

Clears the body and header maps without releasing their backing capacity — the next response can refill the same List[UInt8] body and the same HeaderMap arrays without re-allocating, as long as the new payload fits in the prior capacity.

The version is left at "HTTP/1.1"; callers that need a non-default version can set self.version directly.

Args: status: New status code (default 200).; reason: New reason phrase (default empty — _status_reason will fill from the status code at serialise time).

`ok`

def ok(self) -> Bool

Return True if the status code is 2xx.

`is_redirect`

def is_redirect(self) -> Bool

Return True if the status code is a redirect (3xx).

`text`

def text(self) -> String

Decode the body as a UTF-8 string.

Interprets the body bytes as UTF-8. Invalid UTF-8 sequences are replaced with the Unicode replacement character (best-effort).

`json`

def json(self) -> Value

Parse the body as JSON and return a json.Value.

Uses the pure-Mojo backend from json <https://github.com/ehsanmok/json>_.

Example:

var resp = client.get("https://httpbin.org/json")
var data = resp.json()
print(data["slideshow"]["title"].string_value())

Raises Error: If the response body is not valid JSON.

`raise_for_status`

def raise_for_status(self)

Raise HttpError if the status code is not 2xx.

A no-op for responses with 200 <= status < 300.

Example:

var resp = client.get("https://httpbin.org/status/404")
resp.raise_for_status() # raises HttpError: 404 Not Found

Raises HttpError: If the status code indicates an error (< 200 or >= 300).

`set_cookie`

def set_cookie(mut self, var cookie: Cookie)

Append a Set-Cookie response header for cookie.

Multiple cookies are emitted as separate Set-Cookie lines per RFC 6265 paragraph 3, never folded into a single header.

Args: cookie: The cookie to set (ownership taken).

`cookies`

def cookies(self) -> CookieJar

Parse all Set-Cookie headers into a CookieJar.

Each Set-Cookie header is parsed independently with parse_set_cookie_header (attributes preserved). Returns an empty jar when no Set-Cookie headers are present.

`iter_bytes`

def iter_bytes(self, chunk_size: Int = Int(8192)) -> _BytesIter

Return an iterator that yields the body in chunks.

The entire body is already buffered in memory, so this does not perform additional I/O. Useful for streaming-style processing.

Example:

for chunk in resp.iter_bytes(1024):
    process(chunk[])

Args: chunk_size: Maximum bytes per chunk (default 8192).

`lower`

def lower(deinit self) -> ResponseImpl

Erase the phantom body type, yielding the concrete Response (ResponseImpl[InlineBody]) that every wire driver consumes.

B never affected the layout, so this moves every field across unchanged -- no copy of the body bytes or the stream box. Typed handlers that author a ResponseImpl[SomeBody] call this at the wire boundary to hand the reactor the single erased representation.

Uses the deinit self convention so the fields can be moved out and repacked into the InlineBody binding without a copy.

Functions

`stream_response`

def stream_response[S: ChunkSource](var source: S, status: Int = Int(200)) -> Response

Build a streaming Response backed by source (K1).

The reactor serves this with Transfer-Encoding: chunked, pulling source.next(cancel) in bounded batches per writable edge until it returns None (end-of-stream), so an open-ended or large body never has to materialise in memory. A source with nothing ready returns an empty chunk to end the batch. Set response headers (e.g. Content-Type: text/event-stream for SSE) on the returned value before returning it from a handler.

Args: source: The chunk source; ownership transfers in.; status: HTTP status code (default 200).

`response_from_body`

def response_from_body[B: Body](var body: B, status: Int = Int(200), var reason: String = "") -> Response

Build a concrete Response from any Body impl (opt-in Response[B] ergonomics).

Known-length bodies (content_length() is Some) are drained into the buffered Response.body -- byte-identical to the ordinary Response path. Open-ended bodies (None) are attached to body_stream so the reactor emits Transfer-Encoding: chunked and pulls chunks on writable edges. Set headers on the returned value before returning it from a Handler.

Args: body: The body source; ownership transfers in.; status: HTTP status code (default 200).; reason: Status reason phrase (default empty -> filled at serialise).

Aliases

comptime Response = ResponseImpl

The concrete, body-type-erased HTTP response every wire driver consumes.

This is the ergonomic public spelling of :struct:ResponseImpl bound to :struct:InlineBody. Because a bare defaulted struct name (ResponseImpl) is not itself concrete, Response is provided as a comptime alias -- all existing Response(...) / -> Response / Optional[Response] sites resolve through it unchanged. Handlers that want the typed authoring surface build a ResponseImpl[SomeBody] and call .lower() to obtain this type.