http.nu

http — the unified HTTP server interface library for NURL.

One include gives a consumer both:

• the complete stdlib HTTP surface (sockets + TLS, request parser,

response builder, keep-alive server with pools & DoS limits, router, static files, auth / jwt / multipart / middleware / websocket), via the http_full aggregator; and

• the ergonomic HttpApp facade (app.nu) that wires those pieces into

a running server in a few calls.

Usage from a dependent package:

$ deps/http/src/http.nu

@ main → i { : *HttpApp a ( http_app_new ) ( http_get a / \ HttpRequest req Params p → HttpResponse { ^ ( response_text 200 hello ) } ) ^ ( http_listen a 127.0.0.1 8080 ) }

The intent is that this package is THE dependency anything needing an HTTP server reaches for — complete enough to stand in for hand-wired servers such as the anomaly service or the nurlapi playground server.

---

app.nu

http/app.nu — the ergonomic App facade over the stdlib HTTP stack.

The stdlib already ships a complete HTTP toolkit (net sockets + TLS, request parser, response builder, keep-alive server with worker pools and DoS limits, router, static-file serving, middleware). What every server re-invents is the ~40 lines of glue that wire them together: bind → build a router → install a shutdown signal → wrap the handler in logging / CORS / panic-recovery → run the keep-alive loop.

HttpApp collapses that into one object:

: *HttpApp a ( http_app_new ) ( http_app_get a /health \ HttpRequest req Params p → HttpResponse { ^ ( response_text 200 ok ) } ) ( http_app_static_dir a ./static ) // fallback file serving ( http_app_cors a ) ( http_app_logging a ) : i rc ( http_app_listen a 127.0.0.1 8080 ) // blocks; returns exit code

Everything below the App is the untouched stdlib implementation, reached through the umbrella include in http.nu — so HttpRequest, HttpResponse, response_json, Router, Params, the auth/jwt/multipart helpers, etc. are all in scope for the handler bodies.

Memory model: http_app_new returns a heap *HttpApp (mutable across the registration calls); free it with http_app_free. The embedded Router holds a stable Vec handle, so route registrations through . a router accumulate correctly. http_app_listen MOVES the bound listener into the server and stops it on return.

API

: HttpApp

: HttpApp {
    Router router
    i idle_ms          // keep-alive idle timeout (ms) for server_new_with_timeout
    i workers          // 0 → single-threaded server_run; >0 → server_run_pool(n)
    b recover_panics   // wrap dispatch in `recover`, turning a panic into 500
    b log_requests     // access log (method/path/status) to stderr
    b cors             // permissive CORS + OPTIONS preflight
    b quiet            // suppress the "serving on host:port" banner
    b has_static       // static fallback enabled
    String webroot     // directory served for unmatched GET/HEAD when has_static
}

@ http_app_new → *HttpApp

@ http_app_free *HttpApp a → v

@ http_app_workers *HttpApp a i n → v

Serve on a worker pool of n threads (0 = single-threaded keep-alive).

@ http_app_idle_ms *HttpApp a i ms → v

Keep-alive idle timeout in milliseconds (0 = server default).

@ http_app_recover *HttpApp a b on → v

Toggle panic→500 recovery (on by default). A handler that panics then yields a 500 instead of tearing down the connection loop.

@ http_app_logging *HttpApp a → v

Log every request (method path → status) to stderr.

@ http_app_cors *HttpApp a → v

Permissive CORS: reflect *, answer OPTIONS preflight with 204.

@ http_app_quiet *HttpApp a → v

Suppress the startup banner on stderr.

@ http_app_static_dir *HttpApp a s dir → v

Serve files from dir for any GET/HEAD the router leaves unmatched (404). Path traversal is rejected by the underlying serve_static.

@ http_app_get *HttpApp a s pattern ( @ HttpResponse HttpRequest Params ) handler → v

@ http_app_post *HttpApp a s pattern ( @ HttpResponse HttpRequest Params ) handler → v

@ http_app_put *HttpApp a s pattern ( @ HttpResponse HttpRequest Params ) handler → v

@ http_app_patch *HttpApp a s pattern ( @ HttpResponse HttpRequest Params ) handler → v

@ http_app_delete *HttpApp a s pattern ( @ HttpResponse HttpRequest Params ) handler → v

@ http_app_route *HttpApp a s method s pattern ( @ HttpResponse HttpRequest Params ) handler → v

@ http_app_router *HttpApp a → Router

The embedded router, for advanced use (mounting sub-routers, tests).

@ http_app_use_router *HttpApp a Router r → v

Adopt a pre-built router as the app's router, freeing the default empty one. For servers that assemble their routes elsewhere (e.g. a *_service_router → Router that stays testable without a socket): build the router, hand it to the app, and let the facade own the serving glue.

@ http_app_listen *HttpApp a s host i port → i

Bind host:port and serve until the listener is closed (SIGINT/SIGTERM or error). Returns a process exit code (0 clean, 1 on bind/serve error).

@ http_app_listen_tls *HttpApp a s host i port s cert s key → i

Same, over TLS. cert/key are PEM paths (EC or RSA leaf; a fullchain PEM is accepted for cert).