@lastshotlabs/slingshot-runtime-node

npm install @lastshotlabs/slingshot-runtime-node

Functions

configureRuntimeNodeLogger

Replace the runtime’s structured logger. Pass null to reset to the default console-backed logger. Returns the previous logger so tests can save and restore the state.

function configureRuntimeNodeLogger(logger: RuntimeNodeLogger | null): RuntimeNodeLogger

Source: packages/runtime-node/src/index.ts

configureRuntimeNodeStructuredLogger

Replace the structured Logger. Pass null to reset to the default JSON console logger. Returns the previous logger so tests can save and restore state.

function configureRuntimeNodeStructuredLogger(logger: Logger | null): Logger

Source: packages/runtime-node/src/index.ts

installProcessSafetyNet

Install once-per-process handlers for unhandledRejection and uncaughtException. Both are forwarded to the structured logger, then a process exit is scheduled so production does not continue in an undefined state.

Idempotent — safe to call across multiple nodeRuntime() invocations in the same process.

function installProcessSafetyNet(): void

Source: packages/runtime-node/src/index.ts

nodeRuntime

Creates a SlingshotRuntime implementation powered by the Node.js runtime.

Provides the following capabilities using Node.js built-ins and peer dependencies:

• password — argon2 (peer dep: argon2) for hashing and verification
• sqlite — better-sqlite3 (peer dep: better-sqlite3) with WAL mode enabled
• server — @hono/node-server (peer dep: @hono/node-server) wrapping Node’s http.Server
• fs — node:fs/promises for async file I/O with ENOENT-safe readFile
• glob — fast-glob (peer dep: fast-glob) for file pattern scanning

Runtime contract enforcement. Unlike earlier versions, this runtime fully implements the RuntimeServerOptions and RuntimeWebSocketHandler contract: maxRequestBodySize (413 enforcement), idleTimeout (server-side heartbeat), perMessageDeflate (compression), and publishToSelf (publish fan-out) all behave as documented.

Graceful shutdown. instance.stop({ timeoutMs }) drains in-flight connections for up to timeoutMs before force-closing leftover sockets. The runtime does not register SIGTERM or SIGINT handlers — process lifecycle belongs to the calling app. In production, register handlers:

const server = await runtime.server.listen({ ...opts });
const drain = async () => {
try { await server.stop({ timeoutMs: 25_000 }); } finally { process.exit(0); }
};
process.once('SIGTERM', drain);
process.once('SIGINT', drain);

Optionally call installProcessSafetyNet() to forward unhandled rejections and uncaught exceptions to the structured logger.

Structured logging. Operational events (websocket handler errors, upgrade timeouts, body-size rejections, drain timeouts, fetch handler exceptions) are emitted via configureRuntimeNodeLogger. The default logger writes to console.warn / console.error; production deployments should swap in a logger that forwards to pino/bunyan/OpenTelemetry.

function nodeRuntime(options?: NodeRuntimeOptions): NodeSlingshotRuntime

Source: packages/runtime-node/src/index.ts

runtimeNodeInternals

Expose low-level Node runtime helpers for unit-test access.

Source: packages/runtime-node/src/index.ts

Classes

NodeContentLengthError

Raised when an incoming request has an invalid Content-Length header.

Source: packages/runtime-node/src/errors.ts

NodeRequestBodyTooLargeError

Raised when a Node runtime request body exceeds the configured maximum size.

Source: packages/runtime-node/src/errors.ts

NodeRuntimeError

Errors thrown by the Node runtime implementation.

Source: packages/runtime-node/src/errors.ts

NodeServerError

Raised when the Node runtime HTTP server cannot start or serve requests safely.

Source: packages/runtime-node/src/errors.ts

NodeShutdownError

Raised when the Node runtime cannot complete server shutdown cleanly.

Source: packages/runtime-node/src/errors.ts

NodeWebSocketError

Raised when Node runtime WebSocket setup or delivery fails.

Source: packages/runtime-node/src/errors.ts

Interfaces

NodeRuntimeOptions

Per-runtime knobs for the Node.js runtime. None are required — defaults match the documented behaviour. Pass via nodeRuntime(options).

Source: packages/runtime-node/src/index.ts

NodeRuntimeServerFactory

The server factory returned by the Node runtime — listen() always resolves asynchronously to a NodeRuntimeServerInstance.

Source: packages/runtime-node/src/index.ts

NodeRuntimeServerInstance

The server instance returned by the Node runtime’s server.listen().

Narrows the core RuntimeServerInstance contract to what the Node implementation actually provides:

• stop() always returns a promise and additionally accepts the richer object form stop({ timeoutMs, closeActiveConnections }) for bounded graceful drains.
• upgrade() / publish() are always available (backed by ws).

Source: packages/runtime-node/src/index.ts

NodeSlingshotRuntime

The runtime returned by nodeRuntime.

Narrows the core SlingshotRuntime contract to the Node implementation’s concrete behavior: server.listen() resolves to a NodeRuntimeServerInstance and glob.scan() (fast-glob) always resolves to a string[].

Source: packages/runtime-node/src/index.ts

RuntimeNodeLogger

Structured logging hook. The runtime emits operational events (websocket handler errors, upgrade timeouts, body-size rejections, drain timeouts) to the configured logger. Defaults to defaultLogger which mirrors the previous console.warn / console.error behaviour.

Pass a custom logger via configureRuntimeNodeLogger to forward into pino, bunyan, OpenTelemetry logs, etc. — see the README for examples.

Source: packages/runtime-node/src/index.ts