http.response

An HTTP response built through immutable transformations.

Construct with a body, then chain.with_*()calls to set status, headers, and cookies. Each call returns a newResponse.

A compact JSON response serialized directly to bytes.

Use this for narrow progressive-enhancement endpoints such as typeahead data islands. Chirp's primary response model remains HTML return types; JSONResponseis not a parallel REST serialization layer.

A redirect response.

Build a redirect response for htmx and non-htmx clients.

Sets bothLocation and HX-Redirect. The negotiation layer strips the conflicting header per client: htmx requests receive200with HX-Redirect only (no Location, which XHR would follow first); non-htmx requests receive the HTTP redirect viaLocationonly.

For form POST success paths, preferFormAction orMutationResult, which apply the same negotiation automatically.

A file response served from disk with conditional-GET and Range support.

The body is streamed from disk by a dedicated ASGI sender (send_file_response()) rather than read fully into memory, so large files do not grow worker RSS unboundedly. The sender emits ETag, Last-Modified and Accept-Ranges: bytesand honours conditional requests (If-None-Match / If-Modified-Since-> 304) and a single byteRange (-> 206, 416when unsatisfiable).

content_type is auto-detected from the path via mimetypeswhen left asNone (defaulting to application/octet-stream).

The file isstat-ed at send time, not at construction, so the dataclass stays cheap and immutable.ETagis derived from size + mtime (not a content hash) — it is stable for a given file on disk but changes across rebuilds that rewrite mtimes; this is intentional given Chirp ships no asset pipeline.

LikeResponse, exposes the chainable .with_*() / .header() API so middleware can modify headers/status without special-casing the type.

conditionalcontrols whether the sender evaluates 304/206 (disabled for error bodies such as a custom 404 page, where caching a 304 would be wrong).

Injected static HTML. When an HTML-injection middleware (HTMLInject/ StreamingHTMLInject / AlpineInject) is active, a text/html FileResponse is materialized into a bufferedResponseso the snippet can be inserted; that path does not reachsend_file_response. The middleware rebuilds conditional-GET over the post-injection body (Last-Modified from mtime, a content-hash ETagonly when the snippet is nonce-free, 304 on match) but drops Range / Accept-Ranges — byte offsets shift once a snippet is inserted, so partial fetches against the file would return wrong bytes. Non-HTML files and HTML served without an inject middleware keep full Range here.

A streaming HTTP response that sends chunks progressively.

Used for chunked transfer encoding: headers are sent immediately, then each chunk is sent as an ASGI body message withmore_body=True.

Supports the same.with_*() chainable API as Response so middleware can modify headers/status without knowing the response is streamed.

render_intent mirrors Responseso HTML middleware (e.g. AlpineInject) can skip fragments.

Sentinel response for Server-Sent Events.

Wraps an EventStream and requires direct ASGI send/receive access (the handler bypasses the normal _send_response path).

Provides no-op.with_*()methods so middleware chains don't crash. SSE headers (text/event-stream, no-cache) are always sent by the SSE handler itself; any middleware header modifications are ignored.

A warning is logged the first time a no-op method is called, so middleware authors know their modifications are being silently dropped.