Standardbibliothek

Antra::Net::HTTP

import Antra::Net::HTTP

Small HTTP server helpers built on the phase-1 TCP socket surface.

Antra::Net::HTTP is a deliberately small server-side MVP package. It currently focuses on one-shot request/response flows and keeps the public API narrow:

read_request(...) parses one HTTP/1.x request line plus headers and optionally a simple Content-Length body
response(...) / text(...) build %HttpResponse{...} values
sse(...) builds a small %HttpSSE{...} streaming response for text/event-stream
serve(...) keeps one listener open for multiple requests and supports small concurrency modes like :sequential and :fork_per_client
serve_once(...) binds one listener, accepts one client, answers once
fork(...) runs the same server loop in a child via System.fork
fork_once(...) runs the same one-shot server in a child via System.fork

Current request shape:

%HttpRequest{method, target, path, version, headers, body, meta}
%HttpRequestMeta{request_index, local_addr} via request.meta

Current response shape:

%HttpResponse{status, headers, body}
%HttpSSE{status, headers, run} for small SSE streams
optional %HttpControl{response, stop} for loop control in serve(...)

Example:

import Antra::Net::HTTP as HTTP

val %Ok[_] = HTTP.serve("127.0.0.1", 4040, |request| -> {
    if (request.method == "GET" && request.path == "/") {
        HTTP.ok("hello from antra\n")
    } else {
        HTTP.not_found()
    }
}, [max_requests: 10])

Typen#

Concurrency

Concurrencytype</>

typedef Concurrency = :sequential | :fork_per_client | :multiplex

How serve handles clients.

Funktionen#

anyfn</>

fn any(handler)

Declares a catch-all fallback route for router([...]).

Returns %HttpRouteAny{handler}.

bad_jsonfn</>

fn bad_json()
fn bad_json(body)

Convenience constructor for invalid JSON request bodies.

Returns %HttpResponse{status, headers, body}.

bad_requestfn</>

fn bad_request()
fn bad_request(body)

Convenience constructor for 400 Bad Request.

Returns %HttpResponse{status, headers, body}.

body_jsonfn</>

fn body_json(request)
fn body_json(request, opts)

Parses the request body as JSON.

Returns %Ok[value] or %Err[%Error{...}].

body_textfn</>

fn body_text(request)

Returns the raw request body text.

Expects %HttpRequest{...} and returns its current in-memory body as string.

controlfn</>

fn control(http_response)
fn control(http_response, [stop: stop = false, ..])

Wraps a response with explicit loop control metadata.

Expects %HttpResponse{...} and returns %HttpControl{response, stop}.

deletefn</>

fn delete(path, handler)

Declares a DELETE route for router([...]).

Returns %HttpRoute{method, path, handler}.

forkfn</>

fn fork(host, port, handler)
fn fork(host, port, handler, [max_requests: max_requests = undef, concurrency: concurrency = :sequential, ..])

Forks a child process that runs serve_once(...) and exits afterwards.

The parent receives %Ok[#Process<...>] or %Err[%Error{...}].

fork_oncefn</>

fn fork_once(host, port, handler)

Forks a child process that runs serve_once(...) and exits afterwards.

The parent receives %Ok[#Process<...>] or %Err[%Error{...}].

getfn</>

fn get(path, handler)

Declares a GET route for router([...]).

Returns %HttpRoute{method, path, handler}.

htmlfn</>

fn html(body)
fn html(status, body)

Builds a text/html response with UTF-8 charset.

Returns %HttpResponse{status, headers, body}.

jsonfn</>

fn json(value)
fn json(status, value)

Builds a JSON response from an Antra value.

Returns %HttpResponse{status, headers, body}.

method_not_allowedfn</>

fn method_not_allowed()
fn method_not_allowed(body)

Convenience constructor for 405 Method Not Allowed.

Returns %HttpResponse{status, headers, body}.

not_foundfn</>

fn not_found()
fn not_found(body)

Convenience constructor for 404 Not Found.

Returns %HttpResponse{status, headers, body}.

okfn</>

fn ok(body)

Convenience constructor for 200 OK text responses.

Returns %HttpResponse{status, headers, body}.

patchfn</>

fn patch(path, handler)

Declares a PATCH route for router([...]).

Returns %HttpRoute{method, path, handler}.

postfn</>

fn post(path, handler)

Declares a POST route for router([...]).

Returns %HttpRoute{method, path, handler}.

putfn</>

fn put(path, handler)

Declares a PUT route for router([...]).

Returns %HttpRoute{method, path, handler}.

query_paramfn</>

fn query_param(request, key)
fn query_param(request, key, default)

Reads one decoded query parameter or returns undef when absent.

query_paramsfn</>

fn query_params(request)

Parses the request query string into a decoded string-keyed map.

Returns %{...}. Repeated keys currently use the last value.

read_requestfn</>

fn read_request(socket)
fn read_request(socket, [request_index: request_index = undef, ..])

Parses one HTTP request from a connected socket.

Returns %Ok[%HttpRequest{method, target, path, version, headers, body, meta}] or %Err[message].

redirectfn</>

fn redirect(location)
fn redirect(status, location)

Builds a redirect response with Location header.

Returns %HttpResponse{status, headers, body}.

require_jsonfn</>

fn require_json(request, opts = [], on_error = bad_json())

Parses the request body as JSON and maps parse failures to a 400 response.

Returns %Ok[value] or %Err[%HttpResponse{status, headers, body}]. on_error should itself be a %HttpResponse{...} value.

responsefn</>

fn response(status, body)
fn response(status, body, headers)

Builds a plain %HttpResponse{...} value.

Returns %HttpResponse{status, headers, body}.

routerfn</>

fn router(route_defs)

Builds a small router from helper routes such as HTTP.get(...).

Returns a handler function request -> %HttpResponse{...}.

routesfn</>

fn routes(route_defs)
fn routes(route_defs, [fallback: fallback = _default_route_fallback, ..])

Builds a small exact-match router from [method, path, handler] entries.

Returns a handler function request -> %HttpResponse{...}.

send_responsefn</>

fn send_response(socket, http_response)

Renders and sends one %HttpResponse{...} or %HttpSSE{...} over a connected socket.

Returns %Ok[undef] or %Err[%Error{...}].

servefn</>

fn serve(host, port, handler)
fn serve(host, port, handler, [max_requests: max_requests = undef, concurrency :- Concurrency = :sequential, ..])

Opens one listener, accepts one client, parses one request and answers once.

The handler(request) callback may return %HttpResponse{...}, %HttpSSE{...} or %HttpControl{response, stop}.

Returns %Ok[undef] or %Err[%Error{...}] / %Err[message].

serve_oncefn</>

fn serve_once(host, port, handler)

Opens one listener, accepts one client, parses one request and answers once.

The handler(request) callback may return %HttpResponse{...}, %HttpSSE{...} or %HttpControl{response, stop}.

Returns %Ok[undef] or %Err[%Error{...}] / %Err[message].

ssefn</>

fn sse(run)
fn sse(run, [status: status = 200, headers: headers = %{}, ..])

Builds a small Server-Sent Events response.

Returns %HttpSSE{status, headers, run}.

sse_commentfn</>

fn sse_comment(writer, text)

Sends one SSE comment frame over an active SSE writer.

Returns %Ok[Number] from the underlying socket send or %Err[%Error{...}].

sse_eventfn</>

fn sse_event(writer, data)
fn sse_event(writer, data, [event: event = undef, id: id = undef, retry: retry = undef, ..])

Sends one SSE event frame over an active SSE writer.

Returns %Ok[Number] from the underlying socket send or %Err[%Error{...}].

sse_tickerfn</>

fn sse_ticker(state, tick)
fn sse_ticker(state, tick, [
        status: status = 200,
        headers: headers = %{},
        tick_ms: tick_ms = 250,
        keepalive_ms: keepalive_ms = undef,
        max_age_ms: max_age_ms = undef,
        ..
    ])

Builds a resumable Server-Sent Events response.

Unlike sse(...), whose callback runs until the stream ends, tick is called once per due round and must return immediately with one of %Emit[data, next_state], %Emit[data, next_state, opts], %Idle[next_state] or %Done[]. That is what lets :multiplex keep many streams open in one process; the blocking modes drive the same ticker in a loop, so one handler works in every mode.

opts takes the same event:, id: and retry: keys as sse_event. keepalive_ms: writes a comment when nothing was sent for that long, max_age_ms: closes the stream so the browser reconnects via retry.

Returns %HttpSSETicker{...}.

Example:

HTTP.sse_ticker(0, |seen| -> match latest() {
    %Some[n] when n > seen -> %Emit[str(n), n, [event: "tick", id: str(n)]]
    _                      -> %Idle[seen]
}, [tick_ms: 250, keepalive_ms: 15000])

stopfn</>

fn stop(http_response)

Signals that serve(...) / fork(...) should stop after this response.

Expects %HttpResponse{...} and returns %HttpControl{response, stop: true}.

textfn</>

fn text(status, body)

Builds a text/plain response with UTF-8 charset.

Returns %HttpResponse{status, headers, body}.

Quelle dieser Seite