1# @ajax/mesh-fleetd
2
3meshd's fleet member, wired over the daemon's shared state (`@ajax/mesh-shared`). The fleet area's
4`@ajax/mesh-peer-relay` runs the links, the election, the desired state, the leader's policies and the
5lockstep data plane, and reaches the daemon only through `mpr_host`. This package is that host, plus
6the reconciler's driver actions and the bridges between mesh_shared and the relay.
7
8- **The relay's host** (`mpr_host`):
9  - the status block, the mailbox, the lockstep feed and the round statistics are mesh_shared's
10    (`host`, `mb`, `lock_feed`, `round_of`, `rtt`, `wait`);
11  - the catalog (`catalog`, `image`) is `--programs`, read with `@ajax/mesh-loader`, as peer.rs's
12    `catalog` and `serve_image`;
13  - the driver: `inventory` (Cmd Inventory), `stop_and_view` (ProgRun off, then ViewGet), `driver_view`
14    (FleetView), and F_PLACE / F_FRAME / F_INPUT decoded into Cmd PeerPlace / PeerFrame / PeerInput;
15  - jobs and blobs go to `@ajax/mesh-jobd` (`mjd_jobs_frame`, `mjd_blobs_frame`, `mjd_set_view`,
16    `mjd_jobs_sched`); a `job ...` request becomes JobEvent::Ctl, answered straight to the control port's
17    waiter when the change came through the bridge;
18  - the texts and the fleet view's records go where the control port reads them (`fleet_text`,
19    `groups_text`, `sched_all`, `sched_dry`, `sched_explain`, `fleet_view`).
20- **The reconciler** (`@ajax/mesh-reconcile`'s thread), with reconcile.rs's timeouts (60 s an action,
21  35 s an image or a view from a member, 20 s a placement): Load, Upgrade, Unload, Rollback, ProgRun,
22  Reset, Task, Place and ViewPut through `mesh_shared_ask`. An image comes from the local catalog when
23  it is the committed one (name and hash), else from a member (`mpr_fetch_image`). Its status and
24  failures are kept for the beats (`recon`) and the F_PERF (`fails`).
25- **The bridges.**
26  - The `peer` channel: a change (the control port, the driver's run requests, the jobs thread's
27    forwarded `job` changes) becomes `mpr_change`, its answer the waiter's; a wake becomes `mpr_wake`.
28    Events wait until the relay runs, as they waited in the Rust's channel.
29  - The link queues: every linked member has a `link_out` and a `bulk_out` queue (made and dropped as
30    S_LINKED changes, so `mesh_shared_send_peer` refuses a member that is not linked), written to its
31    link with `mpr_send`, control frames before each bulk frame. A full link queue is waited on for up
32    to 2 s while the member stays linked.
33- **F_PERF** (`mesh_load_perf`, load.rs `perf_report`): this member's CPUs, RAM and disk, each loaded
34  program's measured performance from the pload records just sampled, the reconciler's failures, the
35  perf board's echoes and link RTTs; broadcast and put on the board (`mpr_board_own`).
36
37The fleet thread waits for the driver's startup loads (`sh->ready`) before it starts the relay (the
38first leader's document is what it runs). A listener that cannot be bound ends it, as the Rust's thread
39returned: the member runs alone and its changes are refused.
40
41## Using it
42
43```c
44bool skip_startup;
45mesh_fleetd *f = mesh_fleetd_open(sh, &topo, fleet_state, &skip_startup, &err); /* before the driver */
46...                                                       /* the driver with skip_startup */
47mpk_caps caps = mesh_fleetd_caps(sh, gpu_name, arch);
48mesh_fleetd_start(f, &caps);                              /* after the driver started */
49```
50
51## Ported from
52
53[alpha-rust-mesh](https://github.com/rsafier/alpha-rust-mesh) (Richard Safier, MIT),
54`crates/mesh-host/src/`:
55
56- `main.rs`: the fleet member's start (the store before anything runs, `skip_startup`, the caps).
57- `peer.rs`: `run`'s start, `writer`, the reader's direct frames to the driver and jobs, `catalog`,
58  `serve_image`, `send_view`; `peer_sched.rs`'s view-out thread.
59- `reconcile.rs`: `run`'s driver calls (`source`, `ask`, `inventory`, `fetch_view`, `quiesce`,
60  `set_group_words`, `ready`, `status`).
61- `load.rs`: `perf_report` and its frame.
62
63## Tests
64
65meshd's `tests/cluster.c` runs three whole meshds on loopback as one fleet (see apps/meshd).
66
67## Licence
68
69MIT. See the repository's LICENSE.