Initial Commit
This commit is contained in:
@@ -0,0 +1,152 @@
|
||||
# OpenSpec Change: enterprise-server-job-scheduler
|
||||
|
||||
- **Change ID**: enterprise-server-job-scheduler
|
||||
- **Package**: `@suaveplan/job-scheduler`
|
||||
- **Category**: server/infra
|
||||
- **Target path**: `server/infra/job-scheduler`
|
||||
- **Status**: PROPOSED (amended 2026-05-11)
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/job-scheduler.md`
|
||||
- **Amendment 2026-05-11**: Cron-expression parsing extracted to standalone `@suaveplan/cron` primitive (see `openspec/changes/primitives-cron/`). This package now depends on it instead of bundling its own `cron/cron-parser` module.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/job-scheduler` on the genesis branch from scratch at enterprise quality. The package provides background job scheduling with cron expressions and immediate/delayed queuing. It exposes a `JobScheduler` with `schedule(cronExpr, handler)`, `queue(handler, options)`, `cancel(jobId)`, `pause` / `resume`, and a `JobRegistry` for named jobs. Jobs run with configurable concurrency, retry-with-backoff via `@suaveplan/retry`, `AbortSignal` cancellation, missed-execution detection (catchup strategy), and OTel span per execution. Injectable `Clock` enables deterministic testing.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Does not exist on genesis — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | Typed `JOB_SCHEDULER.*` error codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `Clock`, `LoggerLike` |
|
||||
| `@suaveplan/events` (`workspace:^`) | Job lifecycle events |
|
||||
| `@suaveplan/retry` (`workspace:^`) | Per-job retry + backoff |
|
||||
| `@suaveplan/logger` (`workspace:^`) | Structured logs |
|
||||
| `@suaveplan/cron` (`workspace:^`) | Cron-expression parsing + `nextRun(tz)` (split out 2026-05-11) |
|
||||
| `zod` (`catalog:forms`) | Options validation |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters + histograms |
|
||||
| `tslib` (`catalog:build`) | Runtime helpers |
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
```ts
|
||||
class JobScheduler {
|
||||
constructor(options?: JobSchedulerOptions)
|
||||
schedule(cronExpr: string, handler: JobHandler, options?: JobOptions): string // returns jobId
|
||||
queue(handler: JobHandler, options?: QueueJobOptions): string
|
||||
cancel(jobId: string): boolean
|
||||
pause(jobId?: string): void // pause one or all
|
||||
resume(jobId?: string): void
|
||||
jobs(): JobStatus[]
|
||||
start(): void
|
||||
stop(): Promise<void>
|
||||
}
|
||||
|
||||
function createJobScheduler(options?: JobSchedulerOptions): JobScheduler
|
||||
|
||||
type JobHandler = (ctx: JobContext) => Promise<void>
|
||||
|
||||
interface JobContext {
|
||||
jobId: string
|
||||
signal: AbortSignal
|
||||
attempt: number
|
||||
scheduledAt: number
|
||||
logger: LoggerLike
|
||||
}
|
||||
|
||||
interface JobSchedulerOptions {
|
||||
concurrency?: number // default: 5
|
||||
clock?: Clock
|
||||
logger?: LoggerLike
|
||||
catchupMissed?: boolean // default: false
|
||||
maxMissedRuns?: number // default: 1 when catchupMissed
|
||||
}
|
||||
|
||||
interface JobOptions {
|
||||
id?: string
|
||||
name?: string
|
||||
retries?: number
|
||||
retryDelayMs?: number
|
||||
timeout?: number
|
||||
tz?: string // IANA timezone for cron
|
||||
}
|
||||
|
||||
interface QueueJobOptions extends JobOptions {
|
||||
delayMs?: number
|
||||
runAt?: number // epoch ms
|
||||
}
|
||||
|
||||
interface JobStatus {
|
||||
id: string
|
||||
name?: string
|
||||
cronExpr?: string
|
||||
status: 'pending' | 'running' | 'paused' | 'cancelled'
|
||||
lastRun?: number
|
||||
nextRun?: number
|
||||
runs: number
|
||||
failures: number
|
||||
}
|
||||
|
||||
type JobSchedulerErrorCode =
|
||||
| 'JOB_SCHEDULER_JOB_NOT_FOUND'
|
||||
| 'JOB_SCHEDULER_EXECUTION_FAILED'
|
||||
| 'JOB_SCHEDULER_TIMEOUT'
|
||||
|
||||
// Cron parse errors surface as @suaveplan/cron's CRON.* codes — no JOB_SCHEDULER_INVALID_CRON wrapper.
|
||||
|
||||
function registerJobSchedulerErrorCodes(): void
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
server/infra/job-scheduler/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/index.ts
|
||||
types/
|
||||
job-scheduler.types.ts
|
||||
job-scheduler.types.md
|
||||
scheduler/
|
||||
job-scheduler/
|
||||
job-scheduler.ts
|
||||
job-scheduler.md
|
||||
job-scheduler.types.ts
|
||||
job-scheduler.test.ts
|
||||
index.ts
|
||||
queue/
|
||||
job-queue/
|
||||
job-queue.ts
|
||||
job-queue.md
|
||||
job-queue.test.ts
|
||||
index.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
Downstream: any server package requiring periodic tasks (cache warm-up, report generation, cleanup). No genesis package currently depends on it.
|
||||
|
||||
**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/retry`, `@suaveplan/logger`, `@suaveplan/cron`.
|
||||
@@ -0,0 +1,75 @@
|
||||
# Tasks: enterprise-server-job-scheduler
|
||||
|
||||
**Change ID**: enterprise-server-job-scheduler
|
||||
**Package**: `@suaveplan/job-scheduler`
|
||||
**Target path**: `packages/control-flow/job-scheduler`
|
||||
**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/retry`, `@suaveplan/logger`, `@suaveplan/cron`
|
||||
|
||||
> **Amended 2026-05-11**: Cron parsing extracted to `@suaveplan/cron`. Task §3 is replaced by a thin consumer wrapper; the bundled cron-parser is removed.
|
||||
|
||||
> **Amended 2026-05-12**: Implemented at the genesis-canonical path `packages/control-flow/job-scheduler/` (universal-tier control-flow primitive). The proposal's `server/infra/job-scheduler` path was pre-reorg; flat layout per cron-sibling convention used here.
|
||||
|
||||
---
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] Create directory tree (flat layout mirroring `@suaveplan/cron`).
|
||||
- [x] `package.json` at `0.1.0`, `"sideEffects": false`, exports `.` + per-feature subpaths.
|
||||
- [x] Deps: workspace + catalog deps (incl. `@suaveplan/cron workspace:^`).
|
||||
- [x] DevDeps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `@suaveplan/testing`.
|
||||
- [x] `tsconfig.lib.json` extending `tsconfig.base.json` (universal tier — no `library-node.json`).
|
||||
- [x] `vitest.config.ts` standalone with istanbul + 100% thresholds.
|
||||
- [x] Scripts: `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`.
|
||||
|
||||
## 2. Types and errors
|
||||
|
||||
- [x] All interfaces in `src/scheduler/job-scheduler.types.ts`; Zod schemas in `src/scheduler/job-scheduler.schemas.ts`.
|
||||
- [x] Sibling `.md` docs ≥200 words per impl file.
|
||||
- [x] `src/errors/job-scheduler-error.ts`: three codes (`JOB_NOT_FOUND`, `EXECUTION_FAILED`, `TIMEOUT`); `registerJobSchedulerErrorCodes()`; eager call. Cron parse failures propagate as `CRON.*` codes from `@suaveplan/cron`.
|
||||
|
||||
## 3. Cron integration
|
||||
|
||||
- [x] Consume `@suaveplan/cron`: `parseCron`, `CronExpression`. No local cron-parser module.
|
||||
- [x] In `schedule(cronExpr, handler, options)`: call `parseCron(cronExpr)`; store the returned `CronExpression`; compute first + every subsequent fire via `expression.nextRun(clock.now(), tz)`.
|
||||
- [x] Honour `CRON.NEXT_RUN_NOT_FOUND`: drop the job after emitting `job:scheduling_exhausted` and incrementing `job_scheduler.cron_exhausted_total`. Implemented in `src/scheduler/cron-rescheduler.ts`.
|
||||
|
||||
## 4. Job queue
|
||||
|
||||
- [x] `src/queue/job-queue.ts`: array-backed binary min-heap by `runAt`; `enqueue`/`dequeue`/`peek`/`size`/`remove(jobId)`/`snapshot`.
|
||||
- [x] `src/queue/job-queue.test.ts`: priority order, head/tail/mid removal, empty edge cases, large randomised sequence.
|
||||
- [x] `src/queue/job-queue.md` ≥200 words.
|
||||
- [x] Property-tested in `tests/property.test.ts` (monotonic dequeue, remove-all-leaves-empty, sorted-output).
|
||||
|
||||
## 5. Job scheduler
|
||||
|
||||
- [x] `src/scheduler/job-scheduler.ts`: `JobScheduler` + `createJobScheduler`. Tick loop driven by injected `timers`. `start`/`stop`/`schedule`/`queue`/`cancel`/`pause`/`resume`/`jobs`.
|
||||
- [x] `src/scheduler/job-dispatcher.ts`: per-job dispatch + bookkeeping (separated so scheduler core stays <300 lines).
|
||||
- [x] `src/execution/job-execution.ts`: per-attempt retry/timeout/abort/event surface.
|
||||
- [x] `src/scheduler/cron-rescheduler.ts`: cron-next-fire + catchup-missed branching.
|
||||
- [x] `src/scheduler/job-snapshot.ts`: `JobStatus` projection.
|
||||
- [x] `src/scheduler/job-scheduler.test.ts` + `src/scheduler/job-scheduler-edge.test.ts` (split for ≤500-line cap): covers immediate queue execution, cron scheduling, concurrency cap, cancel-during-run, retry, catchup, pause/resume, lifecycle idempotency.
|
||||
- [x] Sibling `.md` per impl file (≥200 words, all 6 sections).
|
||||
- [x] Events emitted via `EventBusLike` from `@suaveplan/types`: `job:start`, `job:complete`, `job:fail`, `job:scheduling_exhausted`, `job:paused`, `job:resumed`, `job:cancelled`. `JOB_SCHEDULER_EVENTS` registry in `src/events/events.ts`.
|
||||
- [x] OTel surface in `src/otel/job-scheduler-otel.ts`: `duration_ms` histogram, `runs_total` counter, `failures_total` counter, `cron_exhausted_total` counter, `queue_depth` histogram. Closed `outcome ∈ {success,error,timeout}` and `kind ∈ {cron,queued}` labels.
|
||||
|
||||
## 6. Registry
|
||||
|
||||
- [x] `src/registry/job-registry.ts`: `register`/`unregister`/`resolve`/`list`; duplicate-name throws `JOB_SCHEDULER.JOB_NOT_FOUND`.
|
||||
- [x] Sibling `.md` ≥200 words.
|
||||
|
||||
## 7. Integration + property tests
|
||||
|
||||
- [x] `tests/integration.test.ts`: three cron jobs over 10 simulated minutes (every-1m, every-2m, every-5m) with expected counts 10/5/2; `stop()` drains a slow handler.
|
||||
- [x] `tests/property.test.ts` (fast-check): monotonic dequeue, enqueue+remove-all leaves empty, sorted-output property.
|
||||
|
||||
## 8. Docs + verify
|
||||
|
||||
- [x] Root `README.md`: quick-start, queued example, retries+timeout, FakeClock recipe, API table, relationship to `@suaveplan/cron`, events list, observability list.
|
||||
- [x] `bunx turbo lint --filter=@suaveplan/job-scheduler` — green.
|
||||
- [x] `bunx turbo typecheck --filter=@suaveplan/job-scheduler` — green.
|
||||
- [x] `bunx turbo test --filter=@suaveplan/job-scheduler` — 96 tests pass.
|
||||
- [x] `bunx turbo test:coverage --filter=@suaveplan/job-scheduler` — 100% statements/branches/functions/lines.
|
||||
- [x] `bun run docs:check` — 10/10 files at ≥200 words.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/job-scheduler` _(deferred to maintainer)_.
|
||||
- [ ] Update `CLAUDE.md` and `MANIFEST.md` _(deferred to maintainer)_.
|
||||
- [ ] Archive to `openspec/archive/2026-05-12-enterprise-server-job-scheduler/` _(deferred to maintainer)_.
|
||||
Reference in New Issue
Block a user