# 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.

```gizlang
import * as Jobs from "gizapp/jobs";
```

## Types

### `Job`

```gizlang
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`: `string`
- `owner`: `string`
- `operation`: `string`
- `input`: `string`
- `state`: `string`
- `checkpoint`: `string`
- `output`: `string`
- `error`: `string`
- `attempts`: `i64`
- `due`: `i64`
- `intervalMs`: `i64`
- `revision`: `i64`
- `lease`: `i64`
- `elapsed`: `i64`
- `maxMs`: `i64`
- `created`: `i64`

### `Finish`

```gizlang
type Finish = (scoped: Data.Db) => bool throws Model.Rejection
```

What a run ends with, in the transaction that settles it.

### `Step`

```gizlang
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.

- `checkpoint`
- `waiting`
- `complete`
- `failed`
- `cancelled`

### `Execute`

```gizlang
type Execute = (job: Job) => Step throws string
```

One attempt of the claimed job. A thrown error is retried as a failure of `finish` is.

## Functions

### `install`

```gizlang
function install(d: Data.Db): bool throws Model.Rejection
```

Makes the jobs table when it is not there.

Effects: fail, read, write, console, io, alloc.

### `job`

```gizlang
function job(id: string, owner: string, operation: string, input: string, maxMs: i64, now: i64): Job throws string
```

A 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`

```gizlang
function enqueue(d: Data.Db, id: string, operation: string, input: string, due: i64): bool throws Model.Rejection
```

Queues a job of OPERATION with INPUT under the fresh ID, due at DUE.

Effects: fail, read, write, console, io, alloc.

### `schedule`

```gizlang
function schedule(d: Data.Db, name: string, operation: string, interval: i64, due: i64): bool throws Model.Rejection
```

Runs 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`

```gizlang
function wait(d: Data.Db, id: string, ms: i64): Option<Job> throws Model.Rejection
```

The 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`

```gizlang
function next(d: Data.Db): Option<i64> throws Model.Rejection
```

When 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`

```gizlang
function claim(d: Data.Db, now: i64, leaseMs: i64 = LEASE_MS): Option<Job> throws Model.Rejection
```

Claims the job that is due first at NOW, if any, for LEASE_MS.

Effects: fail, read, write, console, io, alloc.

### `take`

```gizlang
function take(d: Data.Db, job: Job, now: i64, leaseMs: i64 = LEASE_MS): Option<Job> throws Model.Rejection
```

Claims 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`

```gizlang
function ended(job: Job, error: string, now: i64): Job
```

JOB 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`

```gizlang
function finish(d: Data.Db, job: Job, error: string, now: i64): bool throws Model.Rejection
```

Settles 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`

```gizlang
function control(context: Table.Context, job: Job, state: string): bool throws string
```

Moves 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`

```gizlang
function fence(held: Data.Db, job: Job, now: i64): void throws Model.Rejection
```

Refuses 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`

```gizlang
function fenced(context: Table.Context, job: Job, work: (scoped: Data.Db) => bool throws Model.Rejection): bool throws Model.Rejection
```

A Desk write in the transaction of WORK is admitted only for the current generation of JOB.

Effects: fail, read, write, console, io, alloc.

### `advance`

```gizlang
function advance(context: Table.Context, before: Job, execute: Execute, leaseMs: i64 = LEASE_MS): bool throws string
```

One 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`

```gizlang
function serve(db: Data.Db, context: () => Table.Context, execute: Execute, concurrency: i64 = 4, operations: Vec<string> = []): void
```

Runs 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`

```gizlang
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`

```gizlang
const MAX_ATTEMPTS: i64 = 3
```

The runs a job gets before it fails for good.

### `LEASE_MS`

```gizlang
const LEASE_MS: i64 = 30000
```

How long a claim holds a job before another worker may take it; `advance` renews it while its work runs.

