error-codes

(no submodules)

Purpose

Defines the stable SAND_WASM.* error-code registry and the SandWasmError subclass thrown by every production path inside the WASM sandbox host. Concentrating codes in a single module keeps the catch sites code-matchable (no message-string parsing) and lets the repo-wide conformance gate verify every documented code is thrown from at least one non-test source file.

The registry is frozen at module load via defineCodes so accidental mutation surfaces immediately, and the side-effect import from the package's src/index.ts ensures any consumer that touches the public surface registers the namespace.

Features

SAND_WASM_CODES — frozen literal map of every code.
SandWasmError — SuaveplanError subclass with a public constructor (required by scripts/lint/check-error-subclass-constructors.ts).
SAND_WASM_ERROR_NAME — stable error.name for logger aggregation.
SandWasmCode — type-level union for catch-site discrimination.

Usage: Basic

import {
    SAND_WASM_CODES,
    SandWasmError,
} from "@suaveplan/api-sandbox-wasm/error-codes";

throw new SandWasmError(
    SAND_WASM_CODES.OUTBOUND_DENIED,
    "error.sand_wasm.outbound_denied",
    { context: { destination: "evil.example.com" } }
);

Usage: Advanced

try {
    await createWasmSandbox({ ... });
} catch (err) {
    if (err instanceof SandWasmError) {
        switch (err.code) {
            case SAND_WASM_CODES.INSTANTIATION_FAILED:
                metrics.increment("plugin.instantiation_failed");
                break;
            case SAND_WASM_CODES.WASI_VERSION_UNSUPPORTED:
                logger.error("Unsupported WASI version", err.context);
                break;
        }
    }
}

API Reference

SAND_WASM_CODES.INSTANTIATION_FAILED — compile or instantiate threw.
SAND_WASM_CODES.WASI_VERSION_UNSUPPORTED — module imports a WASI namespace not on the allowlist.
SAND_WASM_CODES.PREOPEN_DENIED — path_open resolved outside any preopen OR requested write against a read-only preopen.
SAND_WASM_CODES.OUTBOUND_DENIED — sock_connect destination not in policy.fetch[].

Implementation Notes

The SuaveplanError base class has a protected constructor. Without the public re-declaration in the subclass, callers cannot new SandWasmError(...) (TS2674). The repo's check-error-subclass-constructors.ts lint gate enforces this — a missing public constructor has surfaced four times in other packages, which is why the rule exists.

Codes are kept in alphabetical order in tests but emitted in spec order in the registry to match the proposal's enumeration. The registry is frozen, so adding a new code requires editing both this module AND its .test.ts AND extending the spec delta — three-way diffing keeps drift visible during code review.

2.9 KiB Raw Blame History