71 lines
4.6 KiB
Markdown
71 lines
4.6 KiB
Markdown
# @suaveplan/api-jobs-worker-proxy - Bidirectional MessagePort proxy that lets a worker-isolated API plugin register cron + queued jobs with the host's main-process job scheduler. Worker calls registerCron/registerQueued; main side stores handler refs and dispatches runJob RPC back to the worker when due. Universal. Stage-3 of the worker-isolation chain.
|
|
|
|
Bidirectional `MessagePort` proxy that lets a worker-isolated API plugin
|
|
participate in the host's main-process job scheduler. The worker calls
|
|
`registerCron` / `registerQueued` against a local handle implementing
|
|
`JobRegistrationHandle` from `@suaveplan/api-types`; the proxy marshals
|
|
the registration to the main side, which wires the closure into the
|
|
real `JobRegistrationHandle` (typically backed by
|
|
`@suaveplan/job-scheduler`). When the scheduler ticks a job, a
|
|
`runJob` RPC flows back over the same port to invoke the worker's
|
|
handler.
|
|
|
|
This is worker-isolation chain. The protocol layer
|
|
(`@suaveplan/api-worker-rpc`) supplies correlation ids, abort
|
|
forwarding, Zod-validated frames, and error reconstruction — this
|
|
package adds only the jobs-specific verbs.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [client](./src/client/client.md) — `createJobsProxyClient(port, opts)` is the worker-tier entry point for the `@suaveplan/api-jobs-worker-proxy` package.…
|
|
- [client](./src/client/client.md) — `createJobsProxyClient(port, opts)` is the worker-tier entry point for the `@suaveplan/api-jobs-worker-proxy` package.…
|
|
- [error-codes](./src/error-codes/error-codes.md) — This module owns the stable error-code registry for `@suaveplan/api-jobs-worker-proxy`. Every public failure path raise…
|
|
- [error-codes](./src/error-codes/error-codes.md) — This module owns the stable error-code registry for `@suaveplan/api-jobs-worker-proxy`. Every public failure path raise…
|
|
- [handler-bridge](./src/handler-bridge/handler-bridge.md) — This module owns the shared wire schemas, the worker-side `HandlerRegistry`, and the `runWithTimeout` helper used by bo…
|
|
- [handler-bridge](./src/handler-bridge/handler-bridge.md) — This module owns the shared wire schemas, the worker-side `HandlerRegistry`, and the `runWithTimeout` helper used by bo…
|
|
- [server](./src/server/server.md) — `createJobsProxyServer(port, mainHandle, opts)` runs in the host main process. It receives `registerJob` RPC frames fro…
|
|
- [server](./src/server/server.md) — `createJobsProxyServer(port, mainHandle, opts)` runs in the host main process. It receives `registerJob` RPC frames fro…
|
|
- [testing](./src/testing/testing.md) — The testing module exposes a fully-wired in-process harness so consumers can exercise the worker-proxy surface without…
|
|
- [testing](./src/testing/testing.md) — The testing module exposes a fully-wired in-process harness so consumers can exercise the worker-proxy surface without…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Module map
|
|
|
|
| Subpath | File | Doc |
|
|
|---|---|---|
|
|
| `./worker-side` | [`src/client/client.ts`](./src/client/client.ts) | [client.md](./src/client/client.md) |
|
|
| `./main-side` | [`src/server/server.ts`](./src/server/server.ts) | [server.md](./src/server/server.md) |
|
|
| `./handler-bridge` | [`src/handler-bridge/handler-bridge.ts`](./src/handler-bridge/handler-bridge.ts) | [handler-bridge.md](./src/handler-bridge/handler-bridge.md) |
|
|
| `./error-codes` | [`src/error-codes/error-codes.ts`](./src/error-codes/error-codes.ts) | [error-codes.md](./src/error-codes/error-codes.md) |
|
|
| `./testing` | [`src/testing/testing.ts`](./src/testing/testing.ts) | [testing.md](./src/testing/testing.md) |
|
|
|
|
## Scope notes
|
|
|
|
- **Out of scope: tick delivery for non-jobs RPC.** Job ticks arrive
|
|
via the `runJob` request envelope handled here; arbitrary request
|
|
delivery for routes is the responsibility of the
|
|
`api-router-worker-bridge`-style envelope path.
|
|
- **Out of scope: cron expression parsing.** That is owned by
|
|
`@suaveplan/cron` and runs on the main side.
|
|
- **Out of scope: per-tenant fan-out.** Owned by
|
|
`@suaveplan/job-scheduler` plus the `tenant.provider` capability.
|
|
|
|
## Local conformance harness
|
|
|
|
The proposal originally referenced `runJobsConformance` from
|
|
`@suaveplan/job-scheduler/testing`. That harness does not yet exist;
|
|
this package therefore provides its own
|
|
`JOBS_CONFORMANCE_CASES` + `runJobsConformance` under `./testing`. The
|
|
surface matches what the upstream harness is intended to be — a
|
|
factory-driven scenario driver returning per-case pass/fail — so the
|
|
in-repo substitute can be swapped out without changing consumers.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
bunx turbo lint typecheck test --filter=@suaveplan/api-jobs-worker-proxy
|
|
bunx turbo test:coverage --filter=@suaveplan/api-jobs-worker-proxy
|
|
```
|
|
|