Synsemadocsv0.6.xENES

Servidor HTTP

Servidor HTTP

Un servidor HTTP de producción nativo — sin framework que agregar (async hyper/tokio). Todo es deny-by-default, así que un servidor necesita require serve(port).

serve.syn
-- Doc example: the serve response contract. Helpers return {status, value}; the
-- runtime renders them. (A real `serve on` block doesn't terminate, so the doctest
-- asserts the response shapes the handlers give — see the prose for a full server.)
intent: "doc example: serve response contract"

print("ok → " + text(status of ok({"a": 1})) + ",  fail(400) → " + text(status of fail(400, "bad")))

test "uniform response helpers carry a status + value"
    assert_eq(status of ok({"a": 1}), 200)
    assert_eq(status of created({"id": 1}), 201)
    assert_eq(status of fail(400, "bad input"), 400)
    assert_eq(status of not_found("missing"), 404)
    assert_eq((value of fail(400, "bad input"))["error"], "bad input")

Rutas y params§

require serve(8080)

serve on 8080
    route "GET /products"
        give sql("SELECT id, name, price FROM products")
    route "GET /products/:id"
        give sql("SELECT * FROM products WHERE id = ?", [params.id])
    route "GET /files/*path"            -- catch-all (profundidad variable)
        give read_file(params.path)

Las rutas matchean por especificidad (exacto > :param > *catchall), no por orden de declaración.

Auth y validación§

serve on 8080
    auth with check_token
    route "POST /products" requires auth
        expect body {name: text, price: number}    -- 400 si no coincide
        give created(json of request)

El auth task recibe el bearer token; declaralo con 2 parámetros (task check(token, request)) y recibe también el map del request — eso es lo que destraba las sesiones por cookie (Login y sesiones).

El request y las respuestas§

request tiene .method .path .body .json .form .headers .cookies .query .params .user .ip .body_file (.cookies — engine v0.5.5+; .form — engine > v0.5.9). form of request es el body de formulario parseado: urlencoded → {campo: texto}; multipart → campos de texto más archivos subidos como {filename, content_type, data} (bytes exactos); sin form body → map vacío — un <form method="post"> clásico no necesita fetch ni JSON. .headers, .query y .params son maps — se indexan por clave (request.headers["authorization"]; los nombres de header van en minúscula). Indexar una clave ausente es error, así que protegé las opcionales con contains(request.headers, "x"). query y params también quedan como locales sueltas, por eso params.id funciona directo. Cuando un body grande se derrama a disco (más de ~1 MiB), .body queda vacío y .body_file es la ruta a un archivo temporal — se lee con read_body() / read_body_bytes().

Alcance del handler: request, query y params viven solo en el scope del propio handler — una task que el handler llama no las ve. Pasale a la task lo que necesita como argumento (p. ej. lookup_user(request)), nunca un request pelado referenciado dentro de esa task.

Las respuestas usan los helpers uniformes — ok(x), created(x), fail(code, msg), not_found(msg), respond(text, content_type), redirect(url) — o give de un valor directo. Cualquiera puede llevar headers o cookies extra: with_header(resp, name, value) / set_cookie(resp, name, value, opts?) — ver Login y sesiones.

Estado compartido entre requests (state_*)§

Un set sobre un global dentro de un handler no persiste al request siguiente — cada request corre sobre su propio snapshot de los globales. El estado compartido entre requests/handlers vive en un store en memoria con la vida del server: state_set(key, value), state_get(key, default?), state_incr(key, delta?), state_delete(key), state_all() (un mapa-snapshot de todas las claves — {"a": 1, "hits": 2}). Se pierde al reiniciar; para estado durable, una base de datos o la memoria declarada (Memoria y estado).

Incluido§

Ver Frontend para páginas HTML y Construí un sitio web para el recorrido completo.