Route kinds and compute classes

Every file in src/api/ has two independent concerns:

• kind describes handler behavior (task versus an HTTP endpoint). The legacy serverless and hot values remain compatible for one migration window.
• compute.class describes execution: function or dedicated.

New HTTP endpoints and tasks default to function with 1gb of memory.

Canonical compute contract

export const route = {
  kind: 'task',
  compute: {
    class: 'function',
    memory: '4gb', // 1gb | 4gb | 6gb | 8gb | 12gb
  },
  timeout: 60_000,
};

On managed Vura, server and hybrid pages currently use the persistent Dedicated project runtime because their request-time SSR handler needs the full server build context. They are not placed in an individual Function endpoint.

Dedicated manifests also carry the legacy machine.memoryMb / machine.cpus shape so current platform hot-task sizing honors canonical memory and CPU requests during the compatibility window.

Use vura routes inspect --json or vura runtime advise --json to see the effective class, memory, CPU, timeout, provider recommendation, confidence, and reasons before deployment.

Deployment-relevant route config is a static literal contract. Strings, finite numbers, numeric separators, booleans, null, arrays, nested objects, and as const are supported. Calls, referenced identifiers, spreads, computed properties, and template literals are rejected with a line/column error; scanning never imports or evaluates application code. Deployment-affecting page fields such as mode, revalidate, and tags must use static literals, and modes must be quoted strings. Explicit presentation references such as styles: [baseStyles] are omitted from the manifest and evaluated later by the renderer.

Annotation

// shorthand — kind only
export const kind = 'hot';

// route object — kind + config fields
export const route = {
  kind: 'task',
  compute: { class: 'function', memory: '1gb' },
  retries: 2,
  timeout: 60_000,
};

When both kind and route are exported from the same file, route wins. Use the shorthand when you have no additional config.

serverless (default)

Stateless, per-request. Runs inside the unified Node server (persistent hosts) or as an individual Lambda/Worker function (serverless adapters). No state persists between requests. No timeout beyond the adapter limit.

Exports recognized:

Any subset of these. req is the Celsian request object; reply has .json(), .text(), .html(), .status(), .redirect().

Lifecycle: request comes in → handler runs → response sent → handler scope is discarded.

hot

Persistent process. The server holds a WebSocket open for each connection. In-memory state (sets, maps, objects) lives for the lifetime of the server process, not the request. There is no timeout.

Exports recognized:

websocket(peer, req) contract:

peer — HotPeer:

• peer.id — unique connection id (string)
• peer.send(data) — send string or ArrayBuffer; no-op after close
• peer.close(code?, reason?) — close this connection
• peer.on('message' | 'close', cb) — subscribe to events
• peer.broadcast(data, excludeSelf = true) — send to all peers on the same concrete URL path. Broadcast is path-keyed (e.g. /api/rooms/7), not pattern-keyed (/api/rooms/:id), so it delivers only to peers in the same "room".

req — HotRequest:

• req.url — full URL string of the upgrade request
• req.headers — Headers object from the upgrade request
• req.query — URLSearchParams from the upgrade URL
• req.params — path params extracted from the route pattern (e.g. { room: '7' } for /api/rooms/:room)

route config fields:

export const route = { kind: 'hot', origins: ['https://app.example.com'] };

Known limitation — backpressure: peer.send() is fire-and-forget with no bufferedAmount cap. A slow consumer can buffer unbounded data in the socket write queue. Implement your own flow-control in the message handler for high-throughput binary streams.

Lifecycle: server boots → per-connection websocket(peer, req) called on upgrade → peer.on('message', ...) fires per frame → peer.on('close', ...) fires on disconnect. State in module scope persists across all connections for the lifetime of the process.

task

Off the request path. Not exposed as a regular HTTP endpoint — calls go through /__tasks. The handler is the POST export and receives a context object.

Exports recognized:

route config fields:

/__tasks admin interface:

vura tasks CLI:

vura tasks list                       # list task routes and their schedules
vura tasks run <name>                 # trigger immediately
vura tasks run <name> --input '{"k":1}' # with input

Lifecycle: POST to /__tasks/<name> → handler runs → retried up to retries times on throw → result returned as JSON. Scheduled tasks fire via the cron engine inside the running server.

Per-adapter support matrix

Hot routes require a persistent process that can hold a WebSocket open. Cloudflare Workers and Lambda terminate the process between invocations and cannot fulfill this contract. vura build emits a warning at build time when a hot route is detected and the selected adapter cannot support it:

[vura] N hot route(s) cannot run on <adapter> and were not bundled: /api/live/room — deploy them to a persistent host (see /self-host/)

The hot routes are not silently omitted — they are excluded with an explicit named warning.

See the Deploy rung and Adapters reference for the full per-adapter picture.