Error codes

(no submodules)

Purpose

This module owns the stable SAND_VM_BRIDGE.* error-code registry used by every public failure path inside the host bridge. The registry is built once via defineCodes("SAND_VM_BRIDGE", […]) so the namespace prefix and per-code suffix are co-derived — that guarantee lets the host's error boundary, audit sink, and the conformance harness branch on literal code strings without ever decoding free-form messages.

Side-effect-importing this module from src/index.ts ensures every consumer that imports the package barrel (or any subpath export) participates in the same registration that the scripts/conformance.ts audit walks.

Features

Five stable codes — INVALID_PLUGIN_SURFACE, MARSHAL_FAILED, UNMARSHAL_FAILED, HANDLER_REJECTED, LIFECYCLE_FAILED — each mapped to exactly one failure surface inside the bridge.
A typed SandboxVmBridgeError subclass of SuaveplanError so consumers may discriminate via instanceof or by code string.
A public constructor (new SandboxVmBridgeError(code, message, options?)) so consumers can synthesise the error at the host edge when re-wrapping a non-SuaveplanError cause.

Usage: Basic

import {
    SAND_VM_BRIDGE_CODES,
    SandboxVmBridgeError,
} from "@suaveplan/api-sandbox-vm-host-bridge/error-codes/error-codes";

throw new SandboxVmBridgeError(
    SAND_VM_BRIDGE_CODES.MARSHAL_FAILED,
    "request body type is not supported by the bridge marshal layer"
);

Usage: Advanced

Preserve the sandbox-side cause so the host's error boundary can walk the chain back to the original SandboxVmError:

import {
    SAND_VM_BRIDGE_CODES,
    SandboxVmBridgeError,
} from "@suaveplan/api-sandbox-vm-host-bridge/error-codes/error-codes";

try {
    await invokeHandler();
} catch (err) {
    throw new SandboxVmBridgeError(
        SAND_VM_BRIDGE_CODES.HANDLER_REJECTED,
        "sandboxed handler threw",
        { cause: err, context: { route: "/foo", method: "GET" } }
    );
}

API Reference

SAND_VM_BRIDGE_CODES — frozen record mapping enum key (e.g. HANDLER_REJECTED) to the namespaced string code ("SAND_VM_BRIDGE.HANDLER_REJECTED").
type SandboxVmBridgeCode — literal union of every value in SAND_VM_BRIDGE_CODES.
class SandboxVmBridgeError extends SuaveplanError<SandboxVmBridgeCode> — public constructor (code, message, options?). options.cause preserves the original sandbox throw for the host's cause-chain walker.

Implementation Notes

The registry is declared as const so the compiler retains literal types — essential for exhaustive switch narrowing in the bridge's internal dispatch. The class sets this.name = "SandboxVmBridgeError" so heap snapshots, sourcemaps and uncaught-exception handlers attribute failures to this package rather than the generic SuaveplanError superclass. Registry ordering reflects the request lifecycle: discovery first, then per-request marshal failures, then the in-handler reject, then lifecycle failures last.

3.1 KiB Raw Blame History