46 lines
2.4 KiB
Markdown
46 lines
2.4 KiB
Markdown
# `@suaveplan/api-jobs-worker-proxy` — worker-side proxy to main-process job scheduler
|
|
|
|
**Package**: `@suaveplan/api-jobs-worker-proxy`
|
|
**Status**: PROPOSED
|
|
**Type**: new-package
|
|
**Stage**: 3 (Worker isolation infrastructure)
|
|
|
|
## Why
|
|
|
|
Per design doc §5.4, plugins register jobs (cron + on-demand + per-tenant fan-out) via their manifest, and the host's job scheduler — `@suaveplan/job-scheduler` — owns the actual scheduling, ticking, and per-tenant fan-out. Worker-tier plugins still need a `ctx.jobs` slot that lets them do the runtime work (enqueue an on-demand run, observe a registration handle), so this proxy surfaces those operations over `MessagePort`. Job TICKS themselves arrive at the worker via the same request-dispatch path used by routes — this proxy is for the registration-handle side of the contract, not the tick delivery.
|
|
|
|
## What changes
|
|
|
|
Net-new package.
|
|
|
|
**ADDED exports:**
|
|
|
|
- `./client` — `createJobsProxyClient(port): WorkerProxyOf<JobRegistrationHandle>`. Worker-side `ctx.jobs.enqueue(...)`, `ctx.jobs.pause(...)`, `ctx.jobs.resume(...)` calls marshal to the main-process `@suaveplan/job-scheduler`.
|
|
- `./error-codes` — `JOBS_PROXY_*` codes (`JOBS_PROXY_NOT_MANIFESTED`, `JOBS_PROXY_BACKPRESSURE`, `JOBS_PROXY_PORT_CLOSED`, `JOBS_PROXY_HANDLER_THROW`).
|
|
- `./testing` — paired `MessageChannel` + stub scheduler.
|
|
|
|
## Out of scope
|
|
|
|
- **Job tick delivery** — ticks arrive via `api-router-worker-bridge`-style envelopes (a "job invocation" envelope analogous to "request invocation"). This package handles the OUTBOUND registration-handle calls.
|
|
- **Cron expression parsing** — `@suaveplan/cron`'s job; main-side.
|
|
- **Per-tenant fan-out** — `@suaveplan/job-scheduler` + `tenant.provider` on the main side.
|
|
|
|
## Source mapping
|
|
|
|
Genesis-original. Design doc sections: §5.2a, §5.4.
|
|
|
|
| Requirement | Design doc section |
|
|
|---|---|
|
|
| Proxy over the host's `@suaveplan/job-scheduler` | §5.4 |
|
|
| Outbound handle calls marshalled via `MessagePort` | §5.2a |
|
|
| Tick delivery is request-style envelope (handled by sibling package) | §6 |
|
|
|
|
## Verification approach
|
|
|
|
- `src/client/client.test.ts` — `enqueue` / `pause` / `resume` round-trip; non-manifested job rejected.
|
|
- `tests/conformance/run-jobs-conformance.test.ts` — `runJobsConformance` from `@suaveplan/job-scheduler/testing` passes. **Required before Stage 4 can complete.**
|
|
|
|
## Migration impact
|
|
|
|
None — additive only.
|