(sigil http response)

HTTP Response Record

Test if a value is a http-response struct.

Get the status field of a http-response struct.

Get the headers field of a http-response struct.

Get the body field of a http-response struct.

Status code constants

Get the human-readable message for an HTTP status code.

(http-status-message 200)  ; => "OK"
(http-status-message 404)  ; => "Not Found"

Convenience constructors Create a plain text response.

(http-response/text 200 "Hello, world!")

Create an HTML response.

(http-response/html 200 "<h1>Hello</h1>")

Create a JSON response.

body is either a dict (encoded for you with json-encode) or an already-encoded JSON string (passed through untouched).

(http-response/json 200 #{ name: "Alice" })            ; dict, encoded for you
(http-response/json 200 (json-encode #{ name: "Alice" }))  ; string still works

Create a 404 Not Found response with a default HTML body.

Create a redirect response.

Defaults to 302 Found. Pass a status code to override.

(http-response/redirect "/login")
(http-response/redirect "/new-url" 301)

Create an error response with an HTML body.

(http-response/error 500 "Something went wrong")

Default minimum body size (bytes) below which compression isn't worth the header overhead.

#t when a content type generally benefits from gzip. Already-compressed media (images, video, fonts, zip/gz) is excluded.

Return a gzip-encoded copy of response when it is worth doing, otherwise return response unchanged.

accept-encoding is the request's Accept-Encoding header value (or #f); callers typically pass (http-request-header req "Accept-Encoding"). Compression is applied only when: the client accepts gzip, the body is a string or bytevector at least min-bytes long, the content type is compressible, and the response isn't already content-encoded. The result gains Content-Encoding: gzip and Vary: Accept-Encoding; Content-Length is derived from the compressed body by the serializer.

(http-response-gzip (http-request-header req "Accept-Encoding")
                    (http-response/json 200 payload))

Get body length for Content-Length header For strings, we need byte length (UTF-8), not character count

Check if body is a streaming producer

Build status line: "HTTP/1.1 200 OKrn"

Build headers string Converts keyword keys to HTTP header format

Ensure required headers are present

Write an HTTP response to a socket.

The write function should accept (socket data) and return bytes written or #f. Returns #t on success, #f on error.

Convert an HTTP response to a string (for debugging).

Parse an HTTP Range header value into (start . end). Returns #f if the header is absent or malformed.

(parse-range-header "bytes=0-499")    ; => (0 . 499)
(parse-range-header "bytes=500-")     ; => (500 . #f)
(parse-range-header #f)               ; => #f

Serve a file with automatic MIME type and optional Range support. Uses streaming I/O to send files in chunks without loading the entire file into memory.

(http-response/file "/path/to/video.mp4")
(http-response/file "/path/to/video.mp4" range-start: 0 range-end: 499)

Create a Server-Sent Events response.

The producer is called with two arguments:

• send: (lambda (event-type data) ...) - sends an event
• close: (lambda () ...) - closes the stream

Example:

(http-response/sse
  (lambda (send close)
    (send "message" (dict text: "Hello"))
    (send "update" (dict count: 42))
    ;; Keep connection open, send more events...
    ))

Create an SSE response that broadcasts from a channel.

Subscribes to a broadcast channel and sends events for each message. The handler transforms messages into SSE event strings; it is optional and defaults to the identity function, so a hub that already carries pre-formatted SSE strings (the common case) needs no handler.

Parameters: broadcast: The broadcast channel to subscribe to handler: Optional (lambda (msg) ...) -> string or #f. Returns SSE event string to send, or #f to skip. Defaults to identity (send each message as-is). buffer-size: Subscriber buffer size (default: 32) on-connect: Optional (lambda () ...) called on connect. Returns initial event string or #f.

Example:

;; Hub carries pre-formatted event strings — no handler needed:
(http-response/sse-broadcast hub on-connect: (lambda () (snapshot)))

;; Transform raw messages into SSE strings:
(http-response/sse-broadcast chat-broadcast
  (lambda (msg) (sse-event "message" (json-encode msg))))

Format a Server-Sent Event with event type and data.

Returns a string in SSE format: event: <type> data: <json>

The data is JSON-encoded if it's not already a string.

Format a simple data-only SSE event (no event type).

Returns a string in SSE format: data: <content>

Sentinel broadcast message indicating a heartbeat. Recognized by http-response/sse-broadcast, which writes the SSE comment sse-heartbeat-message in response. Treat as reserved: don't send this value as application data.

The SSE comment written for each heartbeat. Lines starting with : are ignored by the browser EventSource API but trigger write-chunk, so dead connections surface as write failures.

Spawn a background goroutine that sends sse-heartbeat-marker on the given broadcast(s) every interval seconds.

broadcasts is either a single broadcast channel or a list of broadcast channels. interval defaults to 30 seconds.

Returns a thunk that stops the heartbeat loop when invoked.

(define stop (start-sse-heartbeat! my-broadcast))
;; later ...
(stop)

Combined with http-response/sse-broadcast, this provides automatic dead-client cleanup for SSE endpoints — no changes required in user handlers.

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)

(No description)