1# @ajax/mesh-jobs-node
2
3A meshd's job node, sans IO. It holds the member's replica of the fleet's job table, runs the
4leader's dispatcher when it leads, and handles the member's side of the leases. Every input returns
5outputs for the caller to make durable and act on, in order. The inputs are: the fleet's view, a
6frame from a member, a finished item, a stored or acknowledged blob, a change request, and a tick.
7
8- **Replication.** The leader appends deltas every tick, persists them and sends them to every
9  member, which persist them and acknowledge. An entry is committed once a majority persisted it.
10  Reads show committed entries only. A new leader pulls a majority's tables, merges them
11  (`@ajax/mesh-jobs-merge`), commits the merge as its first entry, and sends snapshots to members
12  that need them. Transfers come in numbered parts.
13- **Dispatch.** Each member that runs the program gets leases sized to `LEASE_MS` at its measured
14  rate, after a probe, with slow start. A member gets the next lease when half of its current one is
15  done, pipelined two deep. With nothing left to lease, an idle member steals the tail of the lease
16  with the most time left. Who gets leases is `@ajax/mesh-jobs-select`.
17- **Failures.** The items of a lost member, an expired lease or a cut lease go back to the queue.
18  Results are recorded once per item, so committed results are exactly-once, and later duplicates
19  are counted and dropped. A failing item is retried up to `attempts`. Deadlines, cancels and
20  forgets are handled. A submit for a program nobody runs yet waits `SUBMIT_WAIT_MS`.
21- **Payloads.** A result with a payload is staged until its copies are durable
22  (`@ajax/mesh-jobs-copies`). The leader commits it only while it holds the blob itself; otherwise
23  it parks the result and fetches the blob.
24
25## Ported from
26
27[alpha-rust-mesh](https://github.com/rsafier/alpha-rust-mesh) (Richard Safier, MIT):
28`crates/mesh-host/src/jobs.rs`: `Node` and its inputs, `Cfg`, `View`, `Lease`, `Queue`, `Disp`,
29`Lead`, `Staging`, `Staged`, `SchedCx` (now `mj_sched`), `RESEND_MS`, `AVAIL_MS`, `HOLDOFF_MS`,
30`EXPIRY_TRIES_MAX`, `RESULTS_MAX`, `SUBMIT_WAIT_MS`, `lease_time`, `fleet_members`, `cancel`.
31
32## Tests
33
34- `tests/node.c`: the Rust's direct node tests:
35  - `a_snapshot_keeps_the_entries_acknowledged_past_it` (the node half);
36  - `a_table_with_a_part_lost_is_not_installed`;
37  - `no_snapshot_before_the_merge_commits`;
38  - `an_answer_packs_its_entries`;
39  - `nothing_leaves_without_its_persist`.
40- `@ajax/mesh-jobs-sim`'s `trace.c`: the node checked output for output against the Rust's, in seven
41  scenarios of up to five members (crashes, restarts, failing disks, dropped frames, hung members,
42  clock jumps, payloads, forgets).
43- `@ajax/mesh-jobs-sim`'s `fleet.c`: the Rust's fleet tests over the fleet's election core.
44
45## Licence
46
47MIT. See the repository's LICENSE.