gizapp/jobs
Durable jobs on GizDB: one record for a one-off job, a recurring one and a long run with checkpoints. A claim takes the next generation of the job's lease (Task.claimLease), and a worker writes only while the lease of its generation holds; every change is a compare-and-set on the job's id, generation and state, so a stale claim never settles a job. Delivery can repeat (a lost lease, a retry), so a handler uses the job's id to stay idempotent. A failure that finish settles is retried after 1 s, then 2 s: MAX_ATTEMPTS runs in all. A run that advance steps decides its own retries (a checkpoint), so an error it throws ends it.
import * as Jobs from "gizapp/jobs";Types
Job
type Job = { @Model.Key id: string; @Model.Min(0) owner: string; operation: string; @Model.Min(0) input: string; @Model.Values("queued,running,waiting,paused,cancelled,failed,done") state: string; @Model.Min(0) checkpoint: string; @Model.Min(0) output: string; @Model.Min(0) error: string; attempts: i64; due: i64; @Model.Column("interval_ms") intervalMs: i64; revision: i64; lease: i64; elapsed: i64; @Model.Column("max_ms") maxMs: i64; created: i64; }One job. owner is who it is for (a project; empty: the app). due is when it may run and lease when the running
claim of generation revision ends (ms). A recurring job has intervalMs; a run with a budget has maxMs of
elapsed time. checkpoint is where a run that yields goes on; output is what a finished job gives.
id:stringowner:stringoperation:stringinput:stringstate:stringcheckpoint:stringoutput:stringerror:stringattempts:i64due:i64intervalMs:i64revision:i64lease:i64elapsed:i64maxMs:i64created:i64
Finish
type Finish = (scoped: Data.Db) => bool throws Model.RejectionWhat a run ends with, in the transaction that settles it.
Step
type Step = | { kind: "checkpoint"; value: string; afterMs: Option<i64>; } | { kind: "waiting"; value: string; } | { kind: "complete"; output: string; finish: Option<Finish>; } | { kind: "failed"; error: string; finish: Finish; } | { kind: "cancelled"; finish: Finish; }What one attempt of a run did: yield at a checkpoint (due again after afterMs, or now), wait for a person, or end.
checkpointwaitingcompletefailedcancelled
Execute
type Execute = (job: Job) => Step throws stringOne attempt of the claimed job. A thrown error is retried as a failure of finish is.
Functions
install
function install(d: Data.Db): bool throws Model.RejectionMakes the jobs table when it is not there.
Effects: fail, read, write, console, io, alloc.
job
function job(id: string, owner: string, operation: string, input: string, maxMs: i64, now: i64): Job throws stringA job ID of OPERATION with INPUT for OWNER, with MAX_MS of run time (0: no budget), made and due at NOW.
Effects: fail.
enqueue
function enqueue(d: Data.Db, id: string, operation: string, input: string, due: i64): bool throws Model.RejectionQueues a job of OPERATION with INPUT under the fresh ID, due at DUE.
Effects: fail, read, write, console, io, alloc.
schedule
function schedule(d: Data.Db, name: string, operation: string, interval: i64, due: i64): bool throws Model.RejectionRuns OPERATION every INTERVAL ms under the job id "schedule:NAME", first at DUE. A second call changes its operation and interval and keeps its state.
Effects: fail, read, write, console, io, alloc.
wait
function wait(d: Data.Db, id: string, ms: i64): Option<Job> throws Model.RejectionThe job ID once it is no longer queued, running or waiting, or as it is after MS; none when there is no such job. It
only reads: the workers of serve or advance run the job.
Effects: fail, read, write, console, io, alloc.
next
function next(d: Data.Db): Option<i64> throws Model.RejectionWhen the next job is due or its lease ends, so a worker sleeps until then; none when no job waits.
Effects: fail, read, write, console, io, alloc.
claim
function claim(d: Data.Db, now: i64, leaseMs: i64 = LEASE_MS): Option<Job> throws Model.RejectionClaims the job that is due first at NOW, if any, for LEASE_MS.
Effects: fail, read, write, console, io, alloc.
take
function take(d: Data.Db, job: Job, now: i64, leaseMs: i64 = LEASE_MS): Option<Job> throws Model.RejectionClaims JOB at NOW for LEASE_MS when it is due, or running under a lease that ended: its next generation. None when it is not claimable or another worker claimed it first. A running job whose attempts are spent ends here instead.
Effects: fail, read, write, console, io, alloc.
ended
function ended(job: Job, error: string, now: i64): JobJOB after it ran at NOW: done, or, with an ERROR, due again until its attempts are spent. A recurring job is due again one interval after its last due time.
Effects: fail, alloc.
finish
function finish(d: Data.Db, job: Job, error: string, now: i64): bool throws Model.RejectionSettles the claim JOB at NOW, as ended says. False when JOB is no longer the current claim or its lease ended.
Effects: fail, read, write, console, io, alloc.
control
function control(context: Table.Context, job: Job, state: string): bool throws stringMoves JOB to STATE on the word of CONTEXT's person, as the Gate admits: pause or cancel it, queue a paused or waiting one again, or "retry" an ended one from its input alone. Each starts a new generation, so the worker of the old one can no longer write.
Effects: fail, read, write, console, io, alloc.
fence
function fence(held: Data.Db, job: Job, now: i64): void throws Model.RejectionRefuses the transaction HELD unless JOB is still the current claim at NOW, so a write in it is the worker's own.
Effects: fail, read, write, console, io, alloc.
fenced
function fenced(context: Table.Context, job: Job, work: (scoped: Data.Db) => bool throws Model.Rejection): bool throws Model.RejectionA Desk write in the transaction of WORK is admitted only for the current generation of JOB.
Effects: fail, read, write, console, io, alloc.
advance
function advance(context: Table.Context, before: Job, execute: Execute, leaseMs: i64 = LEASE_MS): bool throws stringOne attempt of the job BEFORE: claims it, runs EXECUTE within its budget while a heartbeat renews the lease, and settles it with the step's own writes in one transaction. False when another worker holds it or took it first.
Effects: fail, read, write, console, io, alloc.
serve
function serve(db: Data.Db, context: () => Table.Context, execute: Execute, concurrency: i64 = 4, operations: Vec<string> = []): voidRuns every queued job of DB (of OPERATIONS only, when given), and every running one whose worker's lease ran out, for as long as the host runs; each attempt gets a fresh CONTEXT.
Effects: fail, read, write, console, io, alloc.
current
function current(job: Job): Query.Query<Job>The stored record of JOB: the same id, generation and state. A claim's worker is current while it finds one.
Effects: fail, read, write, console, io, alloc.
Constants
MAX_ATTEMPTS
const MAX_ATTEMPTS: i64 = 3The runs a job gets before it fails for good.
LEASE_MS
const LEASE_MS: i64 = 30000How long a claim holds a job before another worker may take it; advance renews it while its work runs.