73 lines
5.1 KiB
Markdown
73 lines
5.1 KiB
Markdown
# @suaveplan/api-worker-host - Worker-side runtime that hosts exactly one Suaveplan API plugin inside an isolated Worker thread. Provides the bootstrap entry point that handshakes with the main host, wires capability proxies via @suaveplan/api-worker-rpc, dispatches lifecycle commands (install/start/stop/uninstall/reload) to plugin hooks, and surfaces uncaught exceptions as WORKER_HOST.CRASHED envelopes so the main host's LifecycleDriver can transition the plugin to the crashed state.
|
|
|
|
Worker-side runtime that hosts exactly one Suaveplan API plugin inside
|
|
an isolated `Worker` thread. The main-process counterpart is
|
|
`@suaveplan/api-host`; this package owns everything that runs *inside*
|
|
the worker: bootstrap handshake, capability proxy wiring, lifecycle
|
|
command dispatch, and uncaught-exception → `WORKER_HOST.CRASHED`
|
|
propagation.
|
|
|
|
This is API plugin system (design doc §2.2, §5.2a).
|
|
The transport layer (`@suaveplan/api-worker-rpc`) is consumed here for
|
|
every cross-boundary frame.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [bootstrap](./src/bootstrap/bootstrap.md) — `bootstrapWorkerPlugin` is the single entry point a worker thread invokes to host exactly one Suaveplan API plugin. It…
|
|
- [bootstrap](./src/bootstrap/bootstrap.md) — `bootstrapWorkerPlugin` is the single entry point a worker thread invokes to host exactly one Suaveplan API plugin. It…
|
|
- [capability-proxies](./src/capability-proxies/capability-proxies.md) — This module turns the capability-handle descriptor table delivered by the main host into a live, frozen map of RPC-back…
|
|
- [capability-proxies](./src/capability-proxies/capability-proxies.md) — This module turns the capability-handle descriptor table delivered by the main host into a live, frozen map of RPC-back…
|
|
- [crash-detection](./src/crash-detection/crash-detection.md) — This module installs the worker-side safety net that turns silent process death into observable crash telemetry. Withou…
|
|
- [crash-detection](./src/crash-detection/crash-detection.md) — This module installs the worker-side safety net that turns silent process death into observable crash telemetry. Withou…
|
|
- [error-codes](./src/error-codes/error-codes.md) — This module owns the namespaced `WORKER_HOST.*` error registry consumed by the worker-side runtime that hosts exactly o…
|
|
- [error-codes](./src/error-codes/error-codes.md) — This module owns the namespaced `WORKER_HOST.*` error registry consumed by the worker-side runtime that hosts exactly o…
|
|
- [lifecycle](./src/lifecycle/lifecycle.md) — This module hosts the worker-side counterpart to the main host's `LifecycleDriver`. It owns the worker's nine-state lif…
|
|
- [lifecycle](./src/lifecycle/lifecycle.md) — This module hosts the worker-side counterpart to the main host's `LifecycleDriver`. It owns the worker's nine-state lif…
|
|
- [protocol-extension](./src/protocol-extension/protocol-extension.md) — This module defines the Zod schemas that the worker host layers on top of the transport-level frame protocol owned by `…
|
|
- [protocol-extension](./src/protocol-extension/protocol-extension.md) — This module defines the Zod schemas that the worker host layers on top of the transport-level frame protocol owned by `…
|
|
- [testing](./src/testing/testing.md) — `runWorkerHostConformance` spins up an in-process worker-shaped peer using paired `MessageChannel` ports. It exists so…
|
|
- [testing](./src/testing/testing.md) — `runWorkerHostConformance` spins up an in-process worker-shaped peer using paired `MessageChannel` ports. It exists so…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Layout
|
|
|
|
- [bootstrap](./src/bootstrap/bootstrap.md) — `bootstrapWorkerPlugin`
|
|
validates the manifest + capability handles, builds the proxy map,
|
|
mounts the lifecycle RPC server, posts the `worker-ready` frame.
|
|
- [capability-proxies](./src/capability-proxies/capability-proxies.md) —
|
|
`installCapabilityProxies` builds frozen RPC-backed capability slots;
|
|
`getCapability` enforces declared capabilities.
|
|
- [lifecycle](./src/lifecycle/lifecycle.md) — `createLifecycleReceiver`
|
|
owns the nine-state worker-side FSM and the `LifecycleAck` envelope.
|
|
- [crash-detection](./src/crash-detection/crash-detection.md) —
|
|
`installCrashDetector` wires `uncaughtException` /
|
|
`unhandledRejection` to a `WORKER_HOST.CRASHED` envelope before
|
|
exiting.
|
|
- [protocol-extension](./src/protocol-extension/protocol-extension.md) —
|
|
Zod schemas for every worker-host envelope.
|
|
- [error-codes](./src/error-codes/error-codes.md) — nine stable
|
|
`WORKER_HOST.*` codes.
|
|
- [testing](./src/testing/testing.md) —
|
|
`runWorkerHostConformance` in-process simulator.
|
|
|
|
## Stability
|
|
|
|
- **Version**: `0.1.0` (Original).
|
|
- **Tier**: server (requires Node `process` + `MessageChannel`; Node
|
|
18+).
|
|
- **Dependencies**: `@suaveplan/api-types`,
|
|
`@suaveplan/api-worker-rpc`, `@suaveplan/api-lifecycle`,
|
|
`@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`,
|
|
`tslib`, `zod`.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
bunx turbo lint typecheck test build --filter=@suaveplan/api-worker-host
|
|
bunx turbo test:coverage --filter=@suaveplan/api-worker-host
|
|
```
|
|
|
|
All four coverage dimensions land at 100/100/100/100.
|
|
|