use http

HTTP module. Provides HTTP client and server functionality. Error codes: Ok=1 (success), specific errors start at 2

Constants

Functions

fn abort

Abort request processing and send error response. Prevents further middleware/handlers from running.

Signature: (c:Ctx status:i64 body:str -- )

Example:

c 401 "Unauthorized" http::abort

fn ANY

Register handler for any HTTP method.

Signature: (engine:ptr path:str handler:ptr -- )

fn body

Set request body.

Signature: (req:ptr body:str -- )

Example:

req "{\"key\":\"value\"}" http::body

fn cert

Set client certificate for mTLS (mutual TLS).

Signature: (req:ptr cert_path:str key_path:str -- )

Example:

req "/path/client.crt" "/path/client.key" http::cert

fn close

Close and free response.

Signature: (resp:Response -- )

Example:

resp http::close

fn DELETE

Register DELETE route.

Signature: (engine:ptr path:str handler:ptr -- )

fn engine

Create new HTTP engine.

Signature: ( -- engine:ptr)

Example:

http::engine  // e

fn free_engine

Free engine resources.

Signature: (engine:ptr -- )

Example:

e http::free_engine

fn free_request

Free request object (call after send).

Signature: (req:ptr -- )

Example:

req http::free_request

fn GET

Register GET route. - :param for path parameters (e.g., "/users/:id") - / for wildcard suffix (e.g., "/static/" matches /static/anything)

Signature: (engine:ptr path:str handler:ptr -- )

Example:

e "/" fn(c:Ctx -- ) { c 200 "Hello" http::string } http::GET

fn get_header

Get header value by name.

Signature: (c:Ctx name:str -- value:str)

Example:

c "Content-Type" http::get_header  // ct

fn group_DELETE

Register DELETE on group.

Signature: (group:ptr path:str handler:ptr -- )

fn group

Create route group with prefix.

Signature: (engine:ptr prefix:str -- group:ptr)

Example:

e "/api" http::group  // api

fn group_GET

Register GET on group.

Signature: (group:ptr path:str handler:ptr -- )

Example:

api "/users" fn(c:Ctx -- ) { ... } http::group_GET

fn group_POST

Register POST on group.

Signature: (group:ptr path:str handler:ptr -- )

fn group_PUT

Register PUT on group.

Signature: (group:ptr path:str handler:ptr -- )

fn group_use

Add middleware to group.

Signature: (group:ptr middleware:ptr -- )

Example:

api fn(c:Ctx -- ) { ... } http::group_use

fn handle_one

Handle a single request (non-blocking alternative to run). Returns 0 if no request pending, 1 if request handled.

Signature: (engine:ptr -- handled:i64)

Example:

e http::handle_one  // handled

fn header

Add request header.

Signature: (req:ptr name:str value:str -- )

Example:

req "Content-Type" "application/json" http::header

fn html

Send HTML response (sets Content-Type: text/html).

Signature: (c:Ctx status:i64 body:str -- )

Example:

c 200 "<h1>Hello</h1>" http::html

fn is_responded

Check if response has already been sent.

Signature: (c:Ctx -- sent:i64)

Example:

c http::is_responded  // sent

fn json

Send JSON response (sets Content-Type: application/json).

Signature: (c:Ctx status:i64 body:str -- )

Example:

c 200 "{\"ok\":true}" http::json

fn method

Set request HTTP method.

Signature: (req:ptr method:str -- )

Example:

req "POST" http::method

fn new

Create new HTTP request builder.

Signature: (url:str -- req:ptr)

Example:

"https://example.com" http::new  // req

fn param

Get path parameter by name.

Signature: (c:Ctx name:str -- value:str)

Example:

c "id" http::param  // id

fn POST

Register POST route.

Signature: (engine:ptr path:str handler:ptr -- )

Example:

e "/api/users" fn(c:Ctx -- ) { ... } http::POST

fn PUT

Register PUT route.

Signature: (engine:ptr path:str handler:ptr -- )

fn query_param

Get query parameter by name.

Signature: (c:Ctx name:str -- value:str)

Example:

c "page" http::query_param  // page

fn request_body

Get the raw request body as a string. Useful for reading JSON payloads in POST/PUT handlers.

Signature: (c:Ctx -- body:str)

Example:

c http::request_body  // json_payload

fn run

Start server (blocking).

Signature: (engine:ptr addr:str -- )!

Example:

e ":8080" http::run!

fn set_header

Set response header. Must be called before sending response body.

Signature: (c:Ctx name:str value:str -- )

Example:

c "X-Custom" "value" http::set_header

fn sse_end

End the SSE stream. Marks the stream as complete. The connection will be closed after the handler returns.

Signature: (c:Ctx -- )

Example:

c http::sse_end

fn sse_event

Send a named SSE event. The event is sent as "event: \ndata: \n\n". Clients can listen for specific event types with addEventListener.

Signature: (c:Ctx name:str data:str -- )

Example:

c "progress" "{\"percent\": 50}" http::sse_event

fn sse_send

Send a data-only SSE event. The data is sent as "data: \n\n".

Signature: (c:Ctx data:str -- )

Example:

c "{\"count\": 1}" http::sse_send

fn sse_start

Start an SSE (Server-Sent Events) stream. Sends SSE headers and keeps the connection open for streaming events. Must be called before sse_send or sse_event.

Signature: (c:Ctx -- )

Example:

c http::sse_start

fn static

Serve files from a directory. Maps URL paths to filesystem paths. Use with a wildcard route (/). Automatically serves index.html for directory requests. Returns 404 if file not found, 403 for path traversal attempts. // Serve files from ./public at /static/ fn handle_static(c:ptr -- ) { -> c c "/static" "./public" http::static } e "/static/*" &handle_static http::GET

Signature: (c:Ctx prefix:str fs_path:str -- )

fn static_file

Serve a single file from the filesystem. Automatically detects MIME type from file extension. Returns 404 if file not found, 403 for path traversal attempts.

Signature: (c:Ctx filepath:str -- )

Example:

c "/var/www/index.html" http::static_file

fn stop

Stop the server.

Signature: (engine:ptr -- )

Example:

e http::stop

fn string

Send plain text response.

Signature: (c:Ctx status:i64 body:str -- )

Example:

c 200 "Hello, World!" http::string

fn use

Add middleware to engine. Middleware runs before route handlers on every request.

Signature: (engine:ptr middleware:ptr -- )

Example:

e fn(c:Ctx -- ) { c "X-Server" "Quadrate" http::set_header } http::use

Ctx

HTTP Context structure (for server handlers). Passed to route handlers, contains request data and response methods. Fields: method - GET, POST, PUT, DELETE, etc. path - /users/123 (path without query string) query - Raw query string (foo=bar&baz=qux) headers - Request headers body - Request body params - Path parameters as "key=val\nkey2=val2" _socket - Internal: client socket _responded - Internal: response sent flag

Struct

Response

HTTP Response structure (for client)

Struct

Constructors

fn get

Simple GET request.

Signature: (url:str -- resp:Response)!

Example:

"https://example.com" http::get!  // resp

fn send

Execute HTTP request.

Signature: (req:ptr -- resp:Response)!

Example:

req http::send!  // resp  resp <<status print