@rank-lang/server-runtime

Helpers for loading and validating Rank server entrypoints.

Full documentation →

Install

npm install @rank-lang/server-runtime

API

loadRankServerApp(entry, cwd?, options?)

Loads a Rank entry module through @rank-lang/compiler, validates the server-specific exports, and returns either:

• { ok: true, app }
• { ok: false, diagnostic }

Validation rules:

• pub main must exist
• pub main must be a function value
• pub main must accept zero or one parameters
• when pub main accepts one parameter, it must be typed as std::Runtime::ExecutionContext<Routes>
• optional pub config must be an object literal or zero-argument function

The success result contains:

• entryPath: resolved absolute entry path
• moduleGraph: loaded compiler module graph configured for serve-time evaluation
• hasConfig: whether pub config was present
• mainDeclaration: validated pub main declaration
• configDeclaration: validated pub config declaration when present

prepareServeRuntime(options)

Normalizes host and port options, loads the server app, and returns either:

• { ok: true, runtime, note }
• { ok: false, diagnostic }

runtime exposes:

• app: the loaded RankServerApp
• host, port: resolved listener coordinates
• shutdownGracePeriodMs: resolved grace period (ms)
• defaultResponseFormat: resolved response format from pub config
• maxRequestBodyBytes: resolved body size limit from pub config
• requestTimeoutMs: resolved request deadline from pub config
• dispatch(request): dispatch a ServeRequestInput and get a ServeDispatchResult
• close(): shut down provider runtime state

ServeRequestInput shape:

• method: HTTP method string
• path: request path
• headers?: header map
• body?: raw request body string
• remoteAddress?: client IP
• requestId?: forwarded to req.ctx.request_id
• timeReceived?: forwarded to req.ctx.time_received

ServeDispatchResult shape: { status, headers, body }.

Options (ServeRuntimeOptions):

• entry: path to the .rank server entrypoint
• cwd?: working directory for resolving entry (default: process.cwd())
• host?: bind host (default: localhost)
• port?: bind port (default: 0, OS-assigned)
• shutdownGracePeriodMs?: drain timeout before force-close. Defaults to 30_000
• dev?: enable verbose error detail strings in runtime-generated responses
• frozenLockfile?: fail if provider lockfile would be updated
• offline?: disable network access during provider resolution
• providerCapabilities?: override allowed provider capabilities
• allowedHttpHosts?: override allowed outbound HTTP hosts
• allowedEnvPatterns?: override allowed env var patterns
• providerTimeoutMs?: override provider invocation timeout

startServeRuntime(options)

Accepts the same options as prepareServeRuntime. Starts a Node HTTP listener and returns either:

• { ok: true, runtime, note }
• { ok: false, diagnostic }

runtime extends PreparedServeRuntime with:

• server: the bound Node HTTP server
• url: the bound listener URL
• stop(): stops accepting new connections, closes idle keep-alives, waits up to shutdownGracePeriodMs, then force-closes remaining connections before shutting down provider runtime state

Current execution scope:

• exact method/path route matching plus match-prefixed path params
• synthesized 404 and 405 before handler execution
• HTTP::AppConfig.allowedOrigins / allowCredentials synthesize CORS preflight OPTIONS responses and attach matching CORS headers to ordinary responses for admitted origins; maxRequestBodyBytes caps request body size (default 1_048_576)
• route-local query, JSON body, header, and cookie validation before handler execution
• route-local API-key auth execution for named routes whose executable auth metadata is supplied inline on HTTP::ApiKeyAuth<T> { ... }; same-named value binding probing remains available as a compatibility fallback
• req.params, req.query, req.body, req.headers, req.cookies, and req.ctx.request_id / req.ctx.time_received materialization
• authenticated routes also materialize req.auth after successful verifier execution
• response serialization for json, yaml, and text
• compatible explicit content-type overrides are preserved; conflicting ones fail with a structured runtime error
• ordinary redirect responses work through status plus location headers with no special helper type
• manual set-cookie headers are rejected when typed cookies output is also present
• request deadlines are enforced through requestTimeoutMs
• options.dev === true adds verbose detail strings to runtime-generated validation and request-shape error responses while keeping opaque internal 500s unchanged
• graceful shutdown stops accepting new connections, closes idle keep-alives, rejects late-arriving requests with a structured 503 once draining begins, and force-closes remaining connections after shutdownGracePeriodMs
• the host exposes a reserved readiness endpoint at /.well-known/rank/ready, returning 200 { ok: true, state: "ready" } while serving and 503 RUNTIME_DRAINING once shutdown has begun
• zero-arg pub config Env<T> {} reads are filtered through the admitted allow-env view before listener startup
• undeclared incoming headers and cookies are ignored unless the route contract declares a rest field
• bare allow-env = ["*"] emits a visible startup warning before serving begins

Example

import { startServeRuntime } from "@rank-lang/server-runtime";

const started = await startServeRuntime({
  entry: "src/server.rank",
  port: 3000,
});

if (!started.ok) {
  throw new Error(started.diagnostic);
}

console.log(started.note);
await started.runtime.stop();

Development

npm run build -w @rank-lang/server-runtime
npm run test -w @rank-lang/server-runtime
npm run typecheck -w @rank-lang/server-runtime

Publishing

Build the package first, then publish from the workspace root:

npm run build -w @rank-lang/server-runtime
npm publish -w @rank-lang/server-runtime