HTTP Server

Basic Server

Declare a server with serve on <port>. Routes are nested inside the declaration using indentation, keeping the entire server definition in one readable block.

require serve(8080)

serve on 8080
    route "GET /hello"
        give {"message": "Hello, world!"}

The require serve(8080) declaration tells the runtime to reserve the port at startup, making permission explicit and auditable. The server blocks the process until interrupted; no extra runner is needed.

Routes

Routes are matched top-to-bottom within each method. Three segment kinds are supported: literal, named parameter, and catch-all.

Named parameters

A colon prefix captures a single path segment and exposes it on the params map.

route "GET /products/:id"
    give fetch_product(params.id)

Catch-all segments

A star prefix captures everything from that position to the end of the path, including slashes.

route "GET /files/*path"
    give read_file(params.path)

Matching precedence

When multiple routes could match a request, Syntecnia applies this order:

1. Exact literal match
2. Named parameter (:param)
3. Catch-all (*catchall)

Automatic method handling

If the request path matches a known route but the method does not, Syntecnia returns 405 Method Not Allowed and sets the Allow header to the list of accepted methods — no boilerplate needed.

OPTIONS and HEAD are handled automatically for every defined route: OPTIONS replies with the correct Allow header, and HEAD mirrors the GET handler with the body stripped.

The Request Object

Inside any route handler the name request is a map pre-populated by the runtime. All fields are read-only.

Query parameters

Query string values are available as the query map. All values are text; parse them explicitly when a number is needed.

route "GET /search"
    let term = query.q
    give search(term)

Path parameters

Captured route segments are available as the params map. Like query values, all entries are text.

Reading the full body

For streaming uploads or large payloads that spilled to disk, use read_body() to retrieve the complete content regardless of where it is stored.

route "POST /upload"
    let data = read_body()
    give {"size": len(data)}

Response Contract

Syntecnia serialises whatever the route handler gives into an HTTP response automatically. The mapping is:

Response helpers

Use these built-ins when you need a specific status code or content type:

route "POST /items"
    let item = create_item(request.json)
    give created(item)

route "GET /items/:id"
    let item = find_item(params.id)
    when item is nothing
        give not_found({"error": "item not found"})
    give item

Pagination

When a route gives a list, Syntecnia automatically paginates it. The default page size is 100 items; the maximum is 1 000 items. Clients control pagination with query parameters:

• ?limit=N — number of items per page
• ?cursor=N — opaque cursor for the next page (returned in the previous response's "cursor" field)

The envelope returned for every paginated list is:

{
  "items":  [ /* …page contents… */ ],
  "count":  25,       /* items on this page */
  "total":  412,      /* total matching rows */
  "cursor": 100       /* next-page cursor; absent on last page */
}

SQL push-down with paged()

For database queries use paged() so that the database applies LIMIT/OFFSET and an exact COUNT(*) is computed in a single round-trip instead of fetching the full result set into memory.

route "GET /products"
    give paged(query("SELECT * FROM products ORDER BY id"))

Authentication

Declare an auth task with auth with <task>. The runtime extracts the Authorization: Bearer <token> header and calls your task with the raw token string. The task should return either the user data (any map) or nothing to signal an invalid token.

auth with check_token

route "GET /me" requires auth
    give user of request

task check_token(token)
    let row = query_one("SELECT * FROM sessions WHERE token = ?", token)
    give row

• Routes marked requires auth automatically return 401 Unauthorized when the auth task returns nothing.
• The authenticated user map is available inside the handler as request.user.
• Routes without requires auth can still read request.user — it will be nothing for unauthenticated requests.

Input Validation

Use expect body { … } to declare required fields and their types. Syntecnia validates the request JSON before the handler body runs.

route "POST /products"
    expect body {name: text, price: number}
    give create_product(request.json)

Supported types:

• A missing field or a type mismatch returns 400 Bad Request with the offending field name in the error body.
• Malformed JSON (not parseable at all) is also a 400 before expect body is even evaluated.

Static Files

Serve files from the filesystem with a single declaration. No separate file() capability is needed — the static declaration itself is the permission grant.

# Serve everything in ./public at the root URL
static "./public"

# Serve ./assets under /assets prefix
static "/assets" from "./assets"

• Route precedence: a defined route always wins over a static file at the same path.
• Path traversal: requests containing .. segments are blocked with 400 before any filesystem access occurs.
• Appropriate Content-Type headers are set automatically based on the file extension.

CORS

Enable Cross-Origin Resource Sharing with a single declaration. Place it at the top of the serve block to apply server-wide, or inside a route to limit its scope.

# Allow all origins (no credentials)
cors "*"

# Restrict to a specific origin
cors "https://app.example.com"

• Syntecnia handles preflight OPTIONS requests automatically when CORS is enabled.
• Standard CORS headers (Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers) are added to every matching response.

SSE Streaming

Use the stream block to push Server-Sent Events to the client. The response is sent as Content-Type: text/event-stream and the connection stays open until the block exits.

route "GET /events"
    stream
        each tick in range(10)
            send {"count": tick}
            send token as "token"    # named event type

• send <value> emits a data: event line. Maps and lists are JSON-encoded.
• send <value> as "<type>" emits an event: <type> line before the data line.
• stream and give are mutually exclusive in the same route handler.
• Concurrent open streams are capped by max_streams N (default 100). Requests beyond the cap receive 503 Service Unavailable.

serve on 8080
    max_streams 500    # raise the cap server-wide

    route "GET /events"
        stream
            each msg in subscribe("channel")
                send msg

Rate Limiting

Syntecnia uses a token bucket algorithm keyed by the real peer IP address (proxy headers are respected). Limits can be set globally or per route.

# Global limit: 100 requests per minute
rate_limit 100 per minute

serve on 8080
    rate_limit 100 per minute    # server-wide default

    route "POST /login"
        rate_limit 5 per minute   # tighter per-route limit
        give authenticate(request.json)

    route "GET /public"
        rate_limit none           # disable for this route
        give {"status": "ok"}

Supported time windows:

• Requests exceeding the limit receive 429 Too Many Requests with a Retry-After header indicating when the bucket refills.
• Rate limiting is checked before authentication — an attacker cannot bypass it by probing auth endpoints.
• rate_limit none disables the limit for a specific route, regardless of the server-wide setting.

Request Body Limits

Syntecnia enforces a 1 MB default body limit to protect against memory exhaustion from large uploads. Change it with max_body.

serve on 8080
    max_body "10mb"     # raise limit to 10 MiB

    route "POST /upload"
        max_body "100mb"   # per-route override
        give handle_upload()

• Requests whose body exceeds the limit receive 413 Content Too Large before the handler runs.
• Bodies larger than an internal threshold (currently 256 KB) that are within the limit are spilled to a temporary file on disk; request.body_file holds the path and read_body() reads it transparently.

Templates (Server-Side Rendering)

Render HTML templates server-side with the render() built-in. Templates are plain .html files using Syntecnia's minimal, injection-safe syntax.

route "GET /welcome"
    let t = "Welcome"
    give render("page.html", {
        "title": t,
        "items": ["a", "b"]
    })

Template syntax

Template expressions use single curly braces. All values are HTML-escaped by default.

Semantic Content

The content() system lets you build structured documents from semantic nodes rather than raw HTML. Syntecnia negotiates the output format based on the client's Accept header or URL suffix.

route "GET /article/:slug"
    let doc = fetch_article(params.slug)
    give content(
        page([
            heading(1, doc.title),
            prose(doc.body),
            link("Back", "/")
        ], {"title": doc.title})
    )

Content nodes

Content negotiation

Agent Discoverability

Syntecnia auto-generates machine-readable discovery files so that LLM agents and crawlers can understand your API without manual documentation.

Automatic files

• /llms.txt — generated from your intent declaration, route annotations, and describe block. Lists every public route with its method, path, and purpose.
• /robots.txt — served automatically. Allows crawlers by default.

Enriching /llms.txt with describe

serve on 8080
    describe
        intent  "Product catalogue API"
        contact "api@example.com"
        version "2.1.0"

Disabling discoverability

Add the private keyword to the server declaration to opt out entirely:

serve on 8080 private
    # /llms.txt → 404
    # /robots.txt → Disallow: /

Request Isolation

Every inbound request executes in its own interpreter scope. Variables, intermediate values, and any state created during one request are invisible to concurrent requests and discarded when the handler returns.

• No shared mutable state between handlers. There is no global variable that one request can corrupt for another.
• Shared persistence is intentional and explicit: use the blackboard for ephemeral cross-request state, or the database for durable storage.
• Always use parameterised SQL. Syntecnia's query built-ins require parameters to be passed as a separate argument, making accidental string interpolation in SQL structurally impossible.

# Safe: parameter is separate from the query string
let user = query_one("SELECT * FROM users WHERE id = ?", params.id)

# Unsafe: never build SQL by concatenation
# query("SELECT * FROM users WHERE id = " + params.id)  ← SQL injection risk

Error Handling

Syntecnia's HTTP layer is designed to never crash the server. Every error path maps to a deterministic HTTP response.

Handling errors in handlers

You can intercept errors within a handler using attempt / catch:

route "GET /risky"
    attempt
        give do_something_risky()
    catch err
        give fail(500, err.message)