import type { ImportJob, IssuePhase, JobCounts, JobStage, JobStatus, StoredIssue } from '../job/types.js'; import type { ImportEntity } from '../types.js'; /** What a checkpoint writes: the counts, the new problems and the stage, together. */ export interface Checkpoint { counts: JobCounts; stage?: JobStage | null; issues: StoredIssue[]; /** * Rows of the import whose earlier problems are replaced by what this * checkpoint says about them (a resumed run that wrote them again): their old * problems are deleted in the same step that stores the new ones, so a run * that ends before it reaches a row leaves that row's problem for the next * resume to retry. */ supersedes?: number[]; } export interface FinishPatch { errorMessage?: string | null; counts?: JobCounts; } export type CheckpointResult = { ok: true; control: 'cancel' | null; } /** The job was deleted, canceled, declared dead, or claimed by a newer attempt. */ | { ok: false; }; /** * The jobs, as the worker sees them (§ 4.5, point 2; § 8.4). Every write after * the claim carries the `attempt` the worker was given, and **fails when it is * stale**: the worker then stops at once, before its next service call, so one * that recovery has given up on cannot write beside its replacement. * * The real one is `PgJobRepository`; the test double is `MemoryJobRepository`, * with the same status machine. The API side (upload, start, cancel, resume, * delete) and the cron jobs add their own operations. */ export interface JobRepository { get(jobId: number): Promise; /** * Compare-and-swap on the status: `from` → `to`, `attempt` + 1, the worker and * the heartbeat set. Returns the new `attempt`, or null when someone else got * there first or the job is gone: the worker exits quietly. */ claim(jobId: number, from: JobStatus, to: JobStatus, worker: string): Promise; /** * Entering `validating` and the check at the start begin from row 1. A resumed * import keeps the problems of the rows it has yet to write again (`keepRows`); * a checkpoint deletes them one by one (`Checkpoint.supersedes`). */ clearIssues(jobId: number, attempt: number, phase: IssuePhase, keepRows?: readonly number[]): Promise; /** * The heartbeat: the counts, the new problems and the stage in one step, with * the fencing condition, so that a checkpoint never has problems without the * matching `lastUnit` or the reverse. Also tells the worker about `control`. */ checkpoint(jobId: number, attempt: number, checkpoint: Checkpoint): Promise; /** * The entity of an import that is queued or running, whichever it is, or null * (§ 8.4, `overlappedImport`). A check that ran beside one may show errors that * are not real, and says so. */ busyImport(): Promise; /** Sets `started_at` the first time a worker begins to write. */ markStarted(jobId: number, attempt: number): Promise; /** * Says that the worker is waiting for the event queue (`waiting_since`, by the * clock of the store, § 8.5) or that it is not any more. A job that is * already waiting keeps the time it began. Written at once and not with the * next heartbeat, so that the page shows "Slowing down" without a delay. * False when the write is stale. */ setWaiting(jobId: number, attempt: number, waiting: boolean): Promise; /** * The row numbers that have a problem of severity `error` in a phase: the * rows that failed or were skipped (resume retries them first). */ errorRows(jobId: number, phase: IssuePhase): Promise>; /** * The problems of a phase for the file with errors (§ 7.3): those without a * row first, then by row number, and inside a row in the order they were * found. It streams, so a job with 100,000 problems is not held in memory. */ issuesInRowOrder(jobId: number, phase: IssuePhase): AsyncIterable; /** * The final write of a run: `to` is one of the statuses a worker may leave * `validating` or `running` for (§ 8.4, transitions). False when stale. */ finish(jobId: number, attempt: number, to: JobStatus, patch?: FinishPatch): Promise; }