first commit
This commit is contained in:
72
docs/api-stack/api/api-worker-host/README.md
Normal file
72
docs/api-stack/api/api-worker-host/README.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# @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.
|
||||
|
||||
Reference in New Issue
Block a user