server

HTTP and WebSocket server backed by Rust axum on tokio. Pair it with network for local round-trip tests.

global setup(){
    import("server");
    import("network");
}

Built from the Rust crate rust/server; no Boost or Crow dependency.

API

Register routes while the server is stopped, then start(port) / stop().

Paths must start with /. The listener binds to 127.0.0.1 only.

HTML is supplied as a normal Lynxer string and is returned unchanged. For example:

global main(){
    global.server.get("/", "<!doctype html><html><body><h1>Hello</h1></body></html>");
    println(global.server.start(8080));
    while (global.server.running()) {}
}

Routes

Register routes while the server is stopped. Paths must start with /, and a duplicate of the same verb and path is rejected.

HEAD is served by the matching GET route.

Callback handlers take no parameters. They run for each request under the interpreter lock; use the request readers below and then call respond. A callback that omits respond returns 204; a callback error returns 500. Fixed-string route registration and responses remain unchanged.

global greetRequest(){
    str name = global.server.getArg("name");
    global.server.respond(200, "text/plain", "Hello " + name);
}

global setup(){
    import("server");
    global.server.routeGetCallback("/greet", "greetRequest");
}

Templates

dataJson is a JSON object whose keys become template variables, addressed as {{ key }} and {{ nested.key }}. A Jinja-compatible subset is implemented:

• {{ expression }} — output, with filters ({{ name | upper }})
• {% if %} / {% elif %} / {% else %} / {% endif %}
• {% for x in items %} / {% endfor %} — with loop.index, loop.index0, loop.first, loop.last and loop.length; items may be an array, an object (its keys), a string (its characters) or range(n)
• {% set name = expression %}
• {# comment #}

Expressions cover literals, dotted paths, or/and/not, ==/!=/</ <=/>/>=, in, +/-/*///%, ~ (concatenation), grouping and range(), plus the filters upper, lower, trim, capitalize, title, length, first, last, reverse, join, default, int, float, round, replace and string. Templates support {% include "file" %}, {% extends "base" %} with named {% block %} sections, and {% macro name(args) %} definitions called as {{ name(args) }}. Output expressions are HTML-escaped by default; {{ value | safe }} opts out for trusted markup. Dynamic values inside on*, style, srcdoc and srcset attributes are omitted, and dangerous URL schemes in URL attributes are replaced with #. Unknown variables return a descriptive 500 template error instead of silently rendering as empty; use default for intentionally optional values. setTemplateFolder(folder) sets the directory used to resolve templates and included/extended files; those paths cannot escape the configured folder.

A template renders inside the request, so it can read the request through the request object:

The query-string arguments also overlay the root context, so ?name=Ada makes {{ name }} render Ada even without the prefix.

global.server.templateString(
    "/greet",
    "<h1>Hello, {{ name | upper }}!</h1>"
    "{% if request.args.n | default(\"\") %}<p>n={{ request.args.n }}</p>{% endif %}",
    "{\"name\":\"World\"}");

Middleware and error bodies

With CORS enabled, an OPTIONS preflight is answered 204 with Access-Control-Allow-Methods and -Headers.

Request context

Inside callback handlers, these read that handler's current request. Outside a callback they retain compatibility by describing the most recently handled request. Each returns "" when no request has been handled yet.

Lifecycle

run() blocks, matching the original, and releases the interpreter lock while waiting so callback routes continue to run. With start() + stop(), a long-lived Lynxer loop should yield periodically (for example with nativeThreadYield(0.01)) to let request callbacks acquire the interpreter.

TLS

runHTTPS(certPath, keyPath) and runSSLAdhoc() start an HTTPS listener with the same routes, on the host and port recorded by init(host, port) — call that first, or the op answers ERROR: call init(host, port) before …. Unlike run() they do not block: they return "ok" once the socket is listening, and stop() shuts the listener down. Both bound the port before returning, so a port clash is reported by the call.

runHTTPS reads the PEM files and rejects one it cannot use before binding: a missing file reports ERROR: cannot read '<path>': …, a file with no certificate reports ERROR: the certificate file contains no PEM certificate, and a key file with no key reports ERROR: the key file contains no PEM private key. A certificate/key mismatch is rejected before binding with ERROR: the certificate and private key do not match.

runSSLAdhoc() mints a self-signed certificate for localhost and 127.0.0.1 with rcgen, so it needs no files at all — it is the quickest way to stand up HTTPS, and a client must skip verification (the certificate is not signed by any authority it trusts).

TLS is rustls with the ring provider behind axum-server — pure Rust, no system OpenSSL — with rustls-pemfile for the PEM files and rcgen for the self-signed certificate. docs/stdlib_server_tls.lynx is the fixture: it mints a certificate, serves over HTTPS and completes a real handshake.

See also

• stdlib-contracts — the contract this module implements, including the error sentinel family it uses.
• builtins — the functions the interpreter implements itself.
• limitations — the full divergence register.