http.md

http

HTTP client and server. import http, effect.

http.serve(port: Int, f: Fn[Unknown] -> Unknown) -> Unit

Start an HTTP server on the given port with a request handler

http.serve(3000, (req) => http.response(200, "ok"))

http.response(status: Int, body: String) -> Response

Create a plain text HTTP response with status code

http.response(200, "Hello!")

http.json(status: Int, body: String) -> Response

Create a JSON HTTP response with status code

http.json(200, json.stringify(data))

http.with_headers(status: Int, body: String, headers: Map[String, String]) -> Response

Create a response with custom headers

http.with_headers(200, body, {"Content-Type": "text/html"})

http.redirect(url: String) -> Response

Create a 302 temporary redirect response

http.redirect("/new-path")

http.status(resp: Response, code: Int) -> Response

Set the status code on a response

http.status(resp, 201)

http.body(resp: Response) -> String

Get the body string from a response

let text = http.body(resp)

http.set_header(resp: Response, key: String, value: String) -> Response

Set a header on a response

http.set_header(resp, "X-Custom", "value")

http.get_header(resp: Response, key: String) -> Option[String]

Get a header value from a response

let ct = http.get_header(resp, "Content-Type")

http.req_method(req: Request) -> String

Get the HTTP method of a request (GET, POST, etc.)

let method = http.req_method(req)

http.req_path(req: Request) -> String

Get the URL path of a request

let path = http.req_path(req)

http.req_body(req: Request) -> String

Get the body string of a request

let body = http.req_body(req)

http.req_header(req: Request, key: String) -> Option[String]

Get a header value from a request

let auth = http.req_header(req, "Authorization")

http.query_params(req: Request) -> Map[String, String]

Get all query parameters from a request as a map. Values are percent-decoded (%XX → byte, + → space), so ?q=%E7%8C%AB yields {"q": "猫"}.

let params = http.query_params(req) // {"page": "1", "q": "test"}

http.url_decode(s: String) -> String

Percent-decode a URL component (%XX → byte, + → space). query_params already decodes its values; use this for manually-extracted query/form text.

let q = http.url_decode("%E7%8C%AB") // "猫"

http.get(url: String) -> Result[String, String]

Send an HTTP GET request and return the response body

let html = http.get("https://example.com")

http.post(url: String, body: String) -> Result[String, String]

Send an HTTP POST request with a body string

let resp = http.post("https://api.example.com", body)

http.put(url: String, body: String) -> Result[String, String]

Send an HTTP PUT request

let resp = http.put(url, body)

http.patch(url: String, body: String) -> Result[String, String]

Send an HTTP PATCH request

let resp = http.patch(url, body)

http.delete(url: String) -> Result[String, String]

Send an HTTP DELETE request

let resp = http.delete(url)

http.request(method: String, url: String, body: String, headers: Map[String, String]) -> Result[String, String]

Send a custom HTTP request with method, URL, body, and headers

let resp = http.request("PUT", url, body, headers)

http.get_bytes(url: String) -> Result[Bytes, String]

Send an HTTP GET and return the raw response body as Bytes (no UTF-8 conversion), so binary payloads such as images or TTS audio survive intact. The String client corrupts non-UTF-8 bodies.

let audio = http.get_bytes("https://tts.example.com/say.mp3")!
fs.write_bytes_raw("say.mp3", audio)!

http.request_bytes(method: String, url: String, body: String, headers: Map[String, String]) -> Result[Bytes, String]

Like http.request but returns the raw response body as Bytes.

let blob = http.request_bytes("POST", url, body, headers)!