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§

Descubrimiento — lo que todo server publica§

Un server Synsema se describe solo. Todo lo de abajo se deriva de lo que realmente está cableado — la tabla de rutas, expect, requires auth, rate_limit, describe y las capacidades que declara el código de las rutas. Nada se escribe dos veces, y lo que no se puede derivar con verdad (el schema de la respuesta) se omite, no se inventa.

URLQuéNotas
/llms.txtÍndice Markdown para agentes: título, intent, cada endpoint con las capacidades que puede usar (- POST /pay [net:api.stripe.com, llm]), la lista describe api: y una sección ## Machine-readable que apunta a los documentos de abajoencendido por defecto
/robots.txtAllow: / + Sitemap: <base>/sitemap.xml — Disallow: / con private
/sitemap.xmlLas páginas que un crawler puede visitar sin contexto: rutas GET sin params de path, sin requires auth, ni stream ni proxylas rutas paramétricas (/blog/:slug) no se expanden — el runtime no sabe qué slugs existen. Sin lastmod (no hay verdad para darle)
/openapi.jsonOpenAPI 3.1 de la tabla de rutas (mapeo abajo)determinista: paths ascendentes, métodos en orden GET/POST/PUT/PATCH/DELETE — diffeable, anclable en tests
/docsLa API navegable: cada operación con su schema, un formulario por parámetro de path y body, y Try it (un campo de bearer token que vive en el sessionStorage de la pestaña; las cookies viajan solas). Sin CDN, sin scripts de terceros. Con Accept: text/markdown vuelve la misma referencia en Markdown para agentesdocs off apaga solo esta página
/.well-known/synsema-authCómo autenticarse acá — Identidad de agentes

Base URL (los links absolutos de sitemap/robots y el servers de OpenAPI): el domain "…" del serve block si está declarado; si no, el Host del request, con https cuando hay TLS o un proxy adelante manda X-Forwarded-Proto: https.

Detrás de un proxy, declará domain. El proxy reescribe Host con la authority del backend (el $proxy_host por defecto de nginx, y también el proxy to propio), así que sin domain el sitemap diría https://127.0.0.1:8090/.... X-Forwarded-Host se ignora a propósito: cualquier cliente lo puede inyectar y un proxy genérico lo deja pasar — eso es host header injection, y envenenaría el sitemap, el robots.txt y el servers de OpenAPI. Misma postura que con X-Forwarded-For para rate limiting: el motor solo confía en lo que declaraste.

Forma y opt-outs:

serve on 8080
    describe
        about: "Bookshop API"            -- el título: /llms.txt, info.title de OpenAPI, /docs
        api: ["GET /books/:id -- un libro", "POST /orders -- hacer un pedido"]
        version: "1.4.0"                 -- info.version de OpenAPI (default "0.0.0")
    -- private                           -- server interno: /llms.txt, /openapi.json, /sitemap.xml, /docs → 404; robots Disallow: /
    -- docs off                          -- sin página /docs; /openapi.json sigue publicado
    route "POST /orders" requires auth
        expect body {book: text, qty: number}
        give {"ok": true}

Cómo se deriva /openapi.json:

OpenAPIDe
info.title / info.description / info.versiondescribe about: → intent: → "Synsema service" / intent: / describe version:
serversla base URL de arriba (ninguno cuando no se puede saber)
paths./a/{id} + parametersroute "GET /a/:id" — :id y *rest pasan a {id} / {rest}, in: path, requeridos, string
requestBodyel expect body {…} de nivel superior de la ruta → un JSON schema con todos los campos requeridos (text→string, number→number, bool→boolean, list→array, map→object). Un expect dentro de un when es una rama, no un contrato: no se publica
responses.200application/json; text/event-stream en una ruta stream; text/html cuando el último give es html()/render()/page(); los tres tipos negociados para content(); 302 para redirect(). Se infiere del código, sin schema de respuesta — ese es el límite honesto
400 / 401 / 429un expect / requires auth / un rate limit
security + components.securitySchemesrutas con requires auth cuando el bloque tiene auth with: bearer, cookie, httpsig (RFC 9421) — los mismos tres que anuncia /.well-known/synsema-auth
operationIdget_books_id (método + segmentos del path)
x-synsema-rate-limit{count, window} (window en segundos; una ruta hereda el del bloque) o "unlimited"
x-synsema-streaming / x-synsema-proxyrutas stream / rutas proxy to
x-synsema-capabilitieslo que la ruta puede tocar, estáticamente: las líneas require de cada task que el código de la ruta invoca (transitivo, también a través de módulos) más lo que implican los builtins que llama (fetch → net, sql → db, read_file → file.read, reason/decide → llm, remember → memory, …). Es el contrato, no una traza de lo que corrió — el runtime sigue gateando cada llamada. Siempre presente; [] cuando no hay nada

Los grupos montados (mount m.api at "/v1") se publican con su prefijo. Cada bloque host "…" publica su propia tabla bajo su Host.

En CI, sin server: synsema openapi app.syn --out openapi.json [--base-url https://api.example] escribe el mismo documento desde el fuente — solo parse, nada corre, no se abre ningún puerto; exit 2 cuando el archivo no tiene serve. Ver CLI.

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