64 lines
2.7 KiB
TypeScript
64 lines
2.7 KiB
TypeScript
import type { SuaveplanErrorOptions } from "@suaveplan/error";
|
|
import { defineCodes, SuaveplanError } from "@suaveplan/error";
|
|
|
|
/**
|
|
* Stable error-code registry for `@suaveplan/api-sandbox-vm-host-bridge`.
|
|
*
|
|
* Every failure surface inside the bridge raises a
|
|
* {@link SandboxVmBridgeError} whose `code` is one of the namespaced
|
|
* `SAND_VM_BRIDGE.*` strings declared below.
|
|
*
|
|
* Code semantics:
|
|
*
|
|
* - `INVALID_PLUGIN_SURFACE` — the sandboxed plugin did not register any
|
|
* routes via the host-installed `bridge.registerRoute` capability
|
|
* before its module body finished evaluating, OR a registration was
|
|
* structurally invalid (missing method, missing path, non-function
|
|
* handler). The bridge refuses to expose a partially-initialised
|
|
* plugin to the host.
|
|
* - `MARSHAL_FAILED` — the host's `Request` could not be serialised
|
|
* into a {@link SerializedRequest}. The most common cause is an
|
|
* unsupported body type (e.g. `ReadableStream` that the marshal layer
|
|
* cannot drain inside the request handler) or a header value that
|
|
* failed the Zod validator. The route handler does NOT reach the
|
|
* sandbox in this case.
|
|
* - `UNMARSHAL_FAILED` — the sandbox-side handler returned a value the
|
|
* bridge could not turn into a {@link SerializedResponse} — either
|
|
* a non-object, an object missing the required fields, or a body of
|
|
* an unsupported type.
|
|
* - `HANDLER_REJECTED` — the sandboxed handler threw or its returned
|
|
* promise rejected. The thrown value is preserved as `cause` so the
|
|
* host's error boundary can walk the chain back to the original
|
|
* `SandboxVmError` (or whatever the sandbox emitted).
|
|
* - `LIFECYCLE_FAILED` — a delegated `start` or `dispose` call into the
|
|
* sandbox failed. Used only when the underlying sandbox throws — the
|
|
* bridge's own idempotency guards never raise this code.
|
|
*/
|
|
export const SAND_VM_BRIDGE_CODES = defineCodes("SAND_VM_BRIDGE", [
|
|
"INVALID_PLUGIN_SURFACE",
|
|
"MARSHAL_FAILED",
|
|
"UNMARSHAL_FAILED",
|
|
"HANDLER_REJECTED",
|
|
"LIFECYCLE_FAILED",
|
|
] as const);
|
|
|
|
/** Union of every fully-qualified code in {@link SAND_VM_BRIDGE_CODES}. */
|
|
export type SandboxVmBridgeCode =
|
|
(typeof SAND_VM_BRIDGE_CODES)[keyof typeof SAND_VM_BRIDGE_CODES];
|
|
|
|
/**
|
|
* Typed error class for `@suaveplan/api-sandbox-vm-host-bridge`. Extends
|
|
* {@link SuaveplanError} so callers may discriminate by
|
|
* `instanceof SandboxVmBridgeError` OR by `code` string.
|
|
*/
|
|
export class SandboxVmBridgeError extends SuaveplanError<SandboxVmBridgeCode> {
|
|
public constructor(
|
|
code: SandboxVmBridgeCode,
|
|
message: string,
|
|
options?: SuaveplanErrorOptions
|
|
) {
|
|
super(code, message, options);
|
|
this.name = "SandboxVmBridgeError";
|
|
}
|
|
}
|