51 lines
2.9 KiB
Markdown
51 lines
2.9 KiB
Markdown
# `@suaveplan/api-events-worker-proxy` — worker-side proxy to main-process `@suaveplan/events` bus
|
|
|
|
**Package**: `@suaveplan/api-events-worker-proxy`
|
|
**Status**: PROPOSED
|
|
**Type**: new-package
|
|
**Stage**: 3 (Worker isolation infrastructure)
|
|
|
|
## Why
|
|
|
|
Per design doc §5.2a, every capability ships a proxy surface for worker-tier plugins. The `events` capability is special: there is no abstract `api-events` contract package — the host injects the existing `@suaveplan/events` bus directly into `PluginContext.events`. So this proxy is a worker-side surface over the existing `@suaveplan/events` `EventBusLike` interface, NOT a new contract layer. Worker-side `ctx.events.emit(...)` / `ctx.events.on(...)` calls marshal across `MessagePort` to the main-process bus.
|
|
|
|
Per §5.2b sandboxed gating: only manifested `publishes` topics are emittable; only manifested `subscribes` topics deliverable. That gating is enforced MAIN-SIDE; this proxy is the transport.
|
|
|
|
## What changes
|
|
|
|
Net-new package.
|
|
|
|
**ADDED exports:**
|
|
|
|
- `./client` — `createEventsProxyClient(port): WorkerProxyOf<EventBusLike>`.
|
|
- `./subscriber` — `on(topic, handler)` / `off` / `once`; handlers run worker-side; backpressure carried by `api-worker-rpc` so a slow worker-side subscriber cannot exhaust main-side memory.
|
|
- `./publisher` — `emit(topic, payload)` marshals payload; main-side does the topic-allow check + actual bus publish; emit-not-allowed returns `EVENTS_PROXY_TOPIC_NOT_ALLOWED` (rebuilt `SuaveplanError`).
|
|
- `./error-codes` — `EVENTS_PROXY_*` codes (`EVENTS_PROXY_TOPIC_NOT_ALLOWED`, `EVENTS_PROXY_HANDLER_THROW`, `EVENTS_PROXY_PORT_CLOSED`, `EVENTS_PROXY_BACKPRESSURE_DROP`).
|
|
- `./testing` — paired `MessageChannel` + stub bus.
|
|
|
|
## Out of scope
|
|
|
|
- **Topic allowlisting policy** — enforced main-side per §5.2b.
|
|
- **Cross-host fan-out** — `@suaveplan/events`'s job (and `api-ws-broker-redis` for WS specifically).
|
|
- **Bounded-queue capability** — `events.bounded-queue` capability flag is honored main-side; the proxy only marshals.
|
|
|
|
## Source mapping
|
|
|
|
Genesis-original. Design doc sections: §5.2a (worker-RPC variants), §5.2b (sandboxed gating), §6 (capability scoping).
|
|
|
|
| Requirement | Design doc section |
|
|
|---|---|
|
|
| Proxy surface over existing `@suaveplan/events` bus (no new contract) | §5.2a |
|
|
| Topic allow-check on main side; proxy rejects with reconstructed error | §5.2b |
|
|
| Handler throws reconstructed via `api-worker-rpc` | §5.2a |
|
|
|
|
## Verification approach
|
|
|
|
- `src/publisher/publisher.test.ts` — emit allowed topic round-trips; disallowed topic throws.
|
|
- `src/subscriber/subscriber.test.ts` — handler invocation; off cancels; backpressure throttles main → worker.
|
|
- `tests/conformance/run-events-bus-conformance.test.ts` — `runEventsBusConformance` from `@suaveplan/events/testing` passes against the proxy as surface. **Required before Stage 4 can complete.**
|
|
|
|
## Migration impact
|
|
|
|
None — additive only.
|