74 lines
6.1 KiB
Markdown
74 lines
6.1 KiB
Markdown
# @suaveplan/api-sandbox-wasm-host-bridge - Host bridge wrapping a @suaveplan/api-sandbox-wasm WasmSandboxHandle as a @suaveplan/api-host PluginModule. Validates the WASM ABI surface (__suaveplan_alloc / free / handle_request / routes / start / dispose + memory) at bridge-init, marshals SerializedRequest bytes into linear memory via __suaveplan_alloc, invokes __suaveplan_handle_request, reads the packed (responsePtr, responseLen) result, JSON-decodes the SerializedResponse, and unmarshals it back to a host Response. Traps surface as SAND_WASM_BRIDGE.HANDLER_TRAPPED with classified trapKind; denied capabilities surface as SAND_PERM.DENIED.
|
|
|
|
Host-integration layer that wraps a `@suaveplan/api-sandbox-wasm` `WasmSandboxHandle` as a `@suaveplan/api-host` `PluginModule`. Sandboxed-tier plugins compiled to WebAssembly export the `__suaveplan_*` ABI surface (`memory`, `__suaveplan_alloc`, `__suaveplan_free`, `__suaveplan_handle_request`, `__suaveplan_routes`, `__suaveplan_start`, `__suaveplan_dispose`); this bridge validates that surface, discovers the guest's routes once at bridge-init time, and emits per-route closures that marshal `SerializedRequest` records through the guest's linear memory.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [bridge](./src/bridge/bridge.md) — `createSandboxedWasmPluginModule({ sandbox, manifest })` is the public entry point of `@suaveplan/api-sandbox-wasm-host…
|
|
- [bridge](./src/bridge/bridge.md) — `createSandboxedWasmPluginModule({ sandbox, manifest })` is the public entry point of `@suaveplan/api-sandbox-wasm-host…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Defines the seven stable `SAND_WASM_BRIDGE.*` error codes raised on production paths in `@suaveplan/api-sandbox-wasm-ho…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Defines the seven stable `SAND_WASM_BRIDGE.*` error codes raised on production paths in `@suaveplan/api-sandbox-wasm-ho…
|
|
- [instruments](./src/instruments/instruments.md) — `createSandboxWasmBridgeInstruments(config)` constructs the OTel counter + histogram registry every production path in…
|
|
- [instruments](./src/instruments/instruments.md) — `createSandboxWasmBridgeInstruments(config)` constructs the OTel counter + histogram registry every production path in…
|
|
- [lifecycle](./src/lifecycle/lifecycle.md) — `createIdempotentLifecycle(deps)` returns the `start` / `dispose` pair the bridge installs on the host's `PluginModule.…
|
|
- [lifecycle](./src/lifecycle/lifecycle.md) — `createIdempotentLifecycle(deps)` returns the `start` / `dispose` pair the bridge installs on the host's `PluginModule.…
|
|
- [marshal](./src/marshal/marshal.md) — Encodes a `SerializedRequest` to UTF-8 JSON bytes for transport into the guest's linear memory and decodes the matching…
|
|
- [marshal](./src/marshal/marshal.md) — Encodes a `SerializedRequest` to UTF-8 JSON bytes for transport into the guest's linear memory and decodes the matching…
|
|
- [memory](./src/memory/memory.md) — Wraps the four primitive operations the host bridge performs against the guest's linear memory: allocating a buffer via…
|
|
- [memory](./src/memory/memory.md) — Wraps the four primitive operations the host bridge performs against the guest's linear memory: allocating a buffer via…
|
|
- [trap-classifier](./src/memory/trap-classifier.md) — `classifyTrap(cause)` maps a raw `WebAssembly.RuntimeError` (or any thrown value the bridge catches around a guest call…
|
|
- [route-discovery](./src/route-discovery/route-discovery.md) — `discoverRoutes(exports, pluginName)` calls the guest's `__suaveplan_routes` export exactly once at bridge-init time, u…
|
|
- [route-discovery](./src/route-discovery/route-discovery.md) — `discoverRoutes(exports, pluginName)` calls the guest's `__suaveplan_routes` export exactly once at bridge-init time, u…
|
|
- [wasm-host-bridge-conformance](./src/testing/wasm-host-bridge-conformance/wasm-host-bridge-conformance.md) — `runWasmHostBridgeConformance({ buildBridge })` is the contract test every wasm host-bridge configuration must pass. Th…
|
|
- [wasm-host-bridge-conformance](./src/testing/wasm-host-bridge-conformance/wasm-host-bridge-conformance.md) — `runWasmHostBridgeConformance({ buildBridge })` is the contract test every wasm host-bridge configuration must pass. Th…
|
|
- [abi-validator](./src/wasm-abi/abi-validator.md) — `validateWasmAbi(instance, pluginName)` performs the bridge-init-time ABI check that gates every other operation in `@s…
|
|
- [abi](./src/wasm-abi/abi.md) — Declares the `__suaveplan_*` ABI surface a sandboxed WASM plugin must export for `@suaveplan/api-sandbox-wasm-host-brid…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/api-sandbox-wasm-host-bridge
|
|
```
|
|
|
|
Peer-style dependencies (already required by any host that boots sandboxed-tier plugins):
|
|
|
|
- `@suaveplan/api-host`
|
|
- `@suaveplan/api-sandbox-permissions`
|
|
- `@suaveplan/api-sandbox-wasm`
|
|
- `@suaveplan/api-types`
|
|
|
|
## Basic usage
|
|
|
|
```ts
|
|
import { createWasmSandbox } from "@suaveplan/api-sandbox-wasm";
|
|
import { createSandboxedWasmPluginModule } from "@suaveplan/api-sandbox-wasm-host-bridge";
|
|
|
|
const sandbox = await createWasmSandbox({
|
|
pluginName: "example",
|
|
policy,
|
|
capabilities,
|
|
checker,
|
|
wasmBytes,
|
|
});
|
|
|
|
const install = createSandboxedWasmPluginModule({ sandbox, manifest });
|
|
|
|
await host.installPlugin({
|
|
module: install.module,
|
|
manifest: install.manifest,
|
|
manifestHash,
|
|
specifier: "example@0.1.0",
|
|
routes: install.routes,
|
|
});
|
|
```
|
|
|
|
## Conformance
|
|
|
|
The package ships `runWasmHostBridgeConformance({ buildBridge })` under `./testing`. Five invariants — route registration, request round-trip, lifecycle idempotency, trap propagation, and capability-gate fidelity — are asserted against the supplied factory. The harness uses a hand-encoded WASM fixture (no `wabt` build step) so the test suite has no external compile-time dependency.
|
|
|
|
## Error codes
|
|
|
|
`SAND_WASM_BRIDGE.*`: `INVALID_PLUGIN_SURFACE`, `MEMORY_ALLOC_FAILED`, `MARSHAL_FAILED`, `UNMARSHAL_FAILED`, `HANDLER_TRAPPED`, `CAPABILITY_DENIED`, `LIFECYCLE_FAILED`. Capability denials are surfaced through the canonical `SAND_PERM.DENIED` code from `@suaveplan/api-sandbox-permissions`.
|