115 lines
5.7 KiB
Markdown
115 lines
5.7 KiB
Markdown
# OpenSpec Change: retry-injectable-timers
|
|
|
|
- **Change ID**: retry-injectable-timers
|
|
- **Packages touched**: `@suaveplan/types`, `@suaveplan/retry`, `@suaveplan/cron`, `@suaveplan/job-scheduler`
|
|
- **Category**: control-flow / foundation
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-05-12
|
|
- **Motivation**: When `@suaveplan/job-scheduler` was implemented (archived 2026-05-12), `executeJob` could not delegate to `@suaveplan/retry.retry()` because the retry primitive's `sleep()` and `withTimeout()` use raw `setTimeout`/`clearTimeout`. Under `FakeClock`-driven tests those timers don't advance, so the retry loop hangs and the integration test would never deterministically progress. The job-scheduler shipped with an inline retry loop carrying the comment "switch over when retry's timers become injectable". This change does that.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Add an injectable `TimersLike` contract (`{ setTimer, clearTimer }`) to `@suaveplan/types` so every package needing test-controllable scheduling can accept it through one shared interface. Extend `@suaveplan/retry`'s `RetryConfig` with an optional `timers?: TimersLike` field. Thread the pair through `sleep()` and `withTimeout()`. Update `@suaveplan/cron`'s pre-existing `SchedulerTimers` interface to be a type alias of `TimersLike` (preserving its public name for backwards compatibility). Once retry's timers are injectable, replace `@suaveplan/job-scheduler`'s inline retry loop with `retry.retry()` — removing duplicated retry semantics from the scheduler and letting the proven retry primitive own that concern.
|
|
|
|
---
|
|
|
|
## Current-state audit
|
|
|
|
- `@suaveplan/types` exposes `Clock`, `MonotonicClock`, `Rng`, etc. — but no timer-pair contract.
|
|
- `@suaveplan/cron` defines `SchedulerTimers` locally in `src/scheduler/cron-scheduler.types.ts`. This is the de-facto contract that should move to `@suaveplan/types`.
|
|
- `@suaveplan/retry` calls `setTimeout`/`clearTimeout` directly in `src/retry/retry.ts` (`sleep` and `withTimeout`). `RetryConfig` has `clock?` and `rng?` but no `timers?`.
|
|
- `@suaveplan/job-scheduler` has an inline retry loop in `src/execution/job-execution.ts` driven by the scheduler's injected `timers`. The `@suaveplan/retry` workspace dep is declared but only as a future hook.
|
|
|
|
---
|
|
|
|
## Public API changes
|
|
|
|
### `@suaveplan/types`
|
|
|
|
```ts
|
|
// New, exported from the package root.
|
|
export interface TimersLike {
|
|
/** Schedule `callback` to run after `delayMs`. Returns a handle. */
|
|
setTimer(callback: () => void, delayMs: number): number;
|
|
/** Cancel a pending timer by handle. Idempotent for unknown handles. */
|
|
clearTimer(handle: number): void;
|
|
}
|
|
```
|
|
|
|
The shape mirrors `globalThis.setTimeout`/`clearTimeout` minus variadic args and Node's `Timeout` object — the lowest-common-denominator that works across `Date.now()`-driven production code and `FakeClock`-driven test code.
|
|
|
|
### `@suaveplan/cron`
|
|
|
|
```ts
|
|
// Was: locally-defined interface.
|
|
// Now: type alias of the shared contract; existing import names remain valid.
|
|
import type { TimersLike } from "@suaveplan/types";
|
|
export type SchedulerTimers = TimersLike;
|
|
```
|
|
|
|
No behavioral change. The local name is preserved so existing internal call sites compile unchanged.
|
|
|
|
### `@suaveplan/retry`
|
|
|
|
```ts
|
|
import type { Clock, Rng, TimersLike } from "@suaveplan/types";
|
|
|
|
export interface RetryConfig<_T = unknown> {
|
|
maxAttempts: number;
|
|
delay: RetryStrategy;
|
|
shouldRetry?: (error: unknown, attempt: number) => boolean;
|
|
signal?: AbortSignal;
|
|
clock?: Clock;
|
|
rng?: Rng;
|
|
/** Pluggable timer pair. Defaults to `globalThis.setTimeout`/`clearTimeout`. */
|
|
timers?: TimersLike;
|
|
}
|
|
|
|
// sleep + withTimeout gain an optional final `timers?: TimersLike` argument.
|
|
export function sleep(
|
|
ms: number,
|
|
signal?: AbortSignal,
|
|
timers?: TimersLike
|
|
): Promise<void>;
|
|
|
|
export function withTimeout<T>(
|
|
fn: (signal?: AbortSignal) => Promise<T>,
|
|
ms: number,
|
|
attemptNumber: number,
|
|
signal?: AbortSignal,
|
|
timers?: TimersLike
|
|
): Promise<T>;
|
|
```
|
|
|
|
When `timers` is omitted the implementation falls back to the platform `setTimeout`/`clearTimeout` — every existing caller keeps the current behavior.
|
|
|
|
### `@suaveplan/job-scheduler`
|
|
|
|
No public-API change. The inline retry loop in `src/execution/job-execution.ts` is replaced with a single `retry()` call, threading the scheduler's injected `timers` and `clock` through. `JobSchedulerOptions.timers` stays exactly the same.
|
|
|
|
---
|
|
|
|
## Why a shared `TimersLike`
|
|
|
|
Per `openspec/AGENTS.md §0 step 6`: any type shared across ≥2 packages belongs in `@suaveplan/types` to keep the public contract in one place and prevent circular deps. Two packages (`cron` shipped, `retry` after this change) already need it; a third (`job-scheduler`) consumes it transitively. The alternative — three copies of the same interface — is the kind of drift the rule explicitly exists to prevent.
|
|
|
|
---
|
|
|
|
## Backwards compatibility
|
|
|
|
- `retry`: every existing call site works unchanged (new field is optional; new function parameters are optional).
|
|
- `cron`: `SchedulerTimers` keeps its name as a type alias; consumers importing it from `@suaveplan/cron` see no behavioral or type change.
|
|
- `job-scheduler`: `JobScheduler` public surface unchanged. Internally swapping retry implementations is a refactor, not an API break.
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
- Removes ~40 lines of duplicated retry logic from `job-scheduler/src/execution/job-execution.ts`.
|
|
- Unifies the timers contract for future packages (e.g. a future `@suaveplan/circuit-breaker` extracted from retry, or workflow-tier scheduler peers).
|
|
- Slightly increases `@suaveplan/types` payload (one tiny interface, zero runtime impact — types-only).
|
|
|
|
**Prerequisites on Verdaccio**: `@suaveplan/types@0.0.0+`, `@suaveplan/retry@0.0.0+`, `@suaveplan/cron@0.0.0+`, `@suaveplan/job-scheduler@0.0.0+`. All already published.
|