ArctonArcton
API Reference

Runtime Types

The RuntimeAdapter contract and the supporting types an adapter implements.

Overview

These types define what a RuntimeAdapter is and what it hands back — they're the contract bunAdapter and nodeAdapter (see Adapters) implement, and the shapes you'd need if you wrote your own. Most applications never touch these directly; they matter when you're passing adapter to app.listen() or authoring a new one.

import { nodeAdapter } from '@arcton/adapter-node'
import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/', () => 'Hello from Node')

app.listen({ adapter: nodeAdapter })

RuntimeAdapter

Purpose — the interface a runtime integration implements so @arcton/core can serve requests without importing Bun or Node APIs itself.

Signature

interface RuntimeAdapter {
  readonly name: string
  readonly version: string
  readonly capabilities: RuntimeCapabilities
  serve(options: RuntimeServeOptions): RuntimeServer
}

Behavior — name and version identify the runtime (used in the startup banner printed by listen(), see listen()). capabilities.websocket is checked once, inside listen(), against whatever ws() routes exist at that point (including ones added by mounting a module) — not at ws()-registration time.

Example — see Adapters for the two concrete, shipped values.

RuntimeCapabilities

Purpose — declares what an adapter supports.

Signature

interface RuntimeCapabilities {
  readonly websocket: boolean
}

Behavior — both shipped adapters set websocket: true. If websocket is false on the adapter passed to listen() and the app has registered ws() routes, listen() throws.

RuntimeHandler

Purpose — the function shape of the HTTP request handler an adapter's serve() is given.

Signature

type RuntimeHandler = (
  request: Request,
  context: RuntimeRequestContext
) => Response | undefined | Promise<Response | undefined>

Parameters

ParameterTypeDescription
requestRequestThe incoming request. A request that carries no body must have request.body === null, not an empty stream — that is how a route with an optional body tells the two apart.
contextRuntimeRequestContextRuntime-provided helpers, currently just the low-level WebSocket upgrade primitive.

Return type — a Response, or undefined when the handler has already completed the request another way (for example, a successful WebSocket upgrade).

RuntimeServeOptions

Purpose — what's passed into RuntimeAdapter.serve().

Signature

interface RuntimeServeOptions {
  fetch: RuntimeHandler
  port: number
  hostname?: string
  websocket?: RuntimeWebSocketRoute[]
}

Behavior — websocket lists every ws() route registered on the app (including ones grafted in by mounting a module); the adapter is expected to auto-upgrade requests that match one of these paths, ahead of calling fetch at all.

RuntimeRequestContext

Purpose — the low-level WebSocket upgrade primitive handed to a RuntimeHandler, for upgrades that can't be expressed as a static websocket route entry (for example, one gated on auth).

Signature

interface RuntimeRequestContext {
  upgrade(request: Request, options?: RuntimeUpgradeOptions): boolean
}

Parameters

ParameterTypeDescription
requestRequestThe request to upgrade.
optionsRuntimeUpgradeOptionsOptional upgrade payload/headers.

Return type — boolean: true if the upgrade succeeded, false otherwise.

Behavior — only usable when RuntimeAdapter.capabilities.websocket is true. On success, the handler must not also return a Response; on failure (false), the handler should return an error Response itself.

Example — a fragment showing the primitive, not a full adapter:

import type { RuntimeHandler } from '@arcton/contracts'

const fetchFallback: RuntimeHandler = (request, context) => {
  if (new URL(request.url).pathname === '/socket') {
    return context.upgrade(request)
      ? undefined
      : new Response('Upgrade failed', { status: 400 })
  }

  return new Response('not found', { status: 404 })
}

RuntimeUpgradeOptions

Purpose — optional data passed alongside a RuntimeRequestContext.upgrade() call.

Signature

interface RuntimeUpgradeOptions {
  data?: unknown
  headers?: Record<string, string>
}

Behavior — data becomes the WebSocket's RuntimeWebSocket.data once the connection is open.

RuntimeWebSocket

Purpose — the WebSocket handle passed to a RuntimeWebSocketHandler's callbacks.

Signature

interface RuntimeWebSocket {
  readonly data: unknown
  send(message: string | ArrayBuffer | ArrayBufferView): void
  close(code?: number, reason?: string): void
}

Behavior — data carries whatever payload the upgrade produced; it is undefined unless something explicitly attached one (see RuntimeUpgradeOptions).

RuntimeWebSocketHandler

Purpose — the callbacks for a registered ws() route.

Signature

interface RuntimeWebSocketHandler {
  message(ws: RuntimeWebSocket, message: string | ArrayBuffer): void | Promise<void>
  open?(ws: RuntimeWebSocket): void | Promise<void>
  close?(ws: RuntimeWebSocket, code: number, reason: string): void | Promise<void>
  drain?(ws: RuntimeWebSocket): void | Promise<void>
}

Behavior — only message is required. See WebSockets for app.ws() itself and worked examples.

Example — a fragment showing the shape:

import type { RuntimeWebSocketHandler } from '@arcton/contracts'

const echoHandler: RuntimeWebSocketHandler = {
  message(ws, message) {
    if (message === 'bye') {
      ws.close(1000, 'client said bye')
      return
    }
    ws.send(message)
  }
}

RuntimeWebSocketRoute

Purpose — one entry in RuntimeServeOptions.websocket.

Signature

interface RuntimeWebSocketRoute {
  path: string
  handler: RuntimeWebSocketHandler
}

RuntimeServer

Purpose — what RuntimeAdapter.serve() returns, and what app.listen() returns to the caller.

Signature

interface RuntimeServer {
  readonly port: number
  readonly url: URL
  stop(closeActiveConnections?: boolean): void | Promise<void>
}

Behavior — stop() returns void on the Bun adapter and a Promise<void> on the Node adapter (see Adapters); await-ing it works either way. Full usage — including port: 0 to pick a free port — is covered in listen().

On this page