flow-core: the runner update protocol's types 732b4de405e6
UpdateAnswer, UpdatePolicy, UpdateOffer, UpdateReport for GET/POST /api/v1/flow/runner/update (oxygenhub#322). refs #84
- Author
- Andy McCall @andymccall <[email protected]>
- When
- · 2026-10-26 00:59 UTC
- Signature
- ◈ sealed by Andy McCall
- Hash
732b4de405e6c078b6de84031e7815b6f5c9faa92046af557ba6d5b2a2341021- Depends on
- 85275e1ef3b7 b11e30f5031d c3db750ed96e e0918b887850
- Depended on by
- cedd12342afa
- In bookmarks
- main
- In tags
- v0.4.0 v0.5.0 v0.5.1 v0.5.2 v0.5.3
- Edits
- 2 atoms, 0 tree operations, 2 files
Browse the tree at this change
modified CHANGELOG.md +1 −0
| … | 3 unchanged lines |
||
| 4 | 4 | ||
| 5 | 5 | ## Unreleased |
|
| 6 | 6 | ||
| 7 | + | - **The runner update protocol's types (oxygenhub#322):** `UpdateAnswer`, `UpdatePolicy`, `UpdateOffer` and `UpdateReport` in flow-core, for `GET`/`POST /api/v1/flow/runner/update`: the policy that applies to a runner once every level is applied, and the release asset it should run. |
|
| 7 | 8 | - **`flow runner update --from FILE` (#85):** the runner's side of self-updating runners (docs/jetstream.md §8.2). It checks a new build (this machine's target, `--version`, a tier it can run here), keeps the installed one as `flow.prev`, swaps the new one in with a single rename, and tells the running runner (SIGUSR1, its pid in `runner.pid`) to leave within `--notice` seconds (600 by default): jobs that fit finish, the rest are handed back with their checkpoints, and the unit starts the new build. The new build proves itself by getting an answer from the hub; four starts or ten minutes without one put `flow.prev` back. `--dry-run` changes nothing; `[runner.update] allow = false` in `flow.toml` refuses every update; `updates.log` in the home records each install, proof and rollback. Spec §11.5.3. |
|
| 8 | 9 | - **A local `flow run` of a WASM or syscall job copies the workspace whole:** it copied into a directory it never made, so a file at the top of the workspace (a README) failed with `No such file or directory`. |
|
| 9 | 10 | - **Checkpoints: a handed-back job resumes (#77):** `checkpoint "/src/…"` on a job names directories that hold its progress; a runner handing the job back packs and keeps them (`POST …/checkpoint`), and the next attempt's runner restores them before running the same exec, so it carries on rather than starting again. The receipt lists the checkpoint among its inputs. WASM and syscall tiers for now. Spec §11.5.2. |
|
| … | 95 unchanged lines |
modified crates/flow-core/src/api.rs +58 −0
| … | 356 unchanged lines |
||
| 357 | 357 | pub reason: String, |
|
| 358 | 358 | } |
|
| 359 | 359 | ||
| 360 | + | /// `GET /api/v1/flow/runner/update` (docs/jetstream.md §8.2, oxygenhub#322): |
|
| 361 | + | /// the update policy that applies to the asking runner, and the build it |
|
| 362 | + | /// should run when that is not the one it runs. |
|
| 363 | + | #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] |
|
| 364 | + | pub struct UpdateAnswer { |
|
| 365 | + | pub policy: UpdatePolicy, |
|
| 366 | + | /// The build to install now; none when updates are off, the runner is |
|
| 367 | + | /// up to date, it is outside its window, or no build suits it. |
|
| 368 | + | #[serde(default)] |
|
| 369 | + | pub offer: Option<UpdateOffer>, |
|
| 370 | + | /// Why there is no offer, or what the offer is for, in words. |
|
| 371 | + | #[serde(default)] |
|
| 372 | + | pub note: String, |
|
| 373 | + | } |
|
| 374 | + | ||
| 375 | + | /// A runner's update policy once every level is applied (nearest wins). |
|
| 376 | + | #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] |
|
| 377 | + | pub struct UpdatePolicy { |
|
| 378 | + | /// Off unless some level turned it on. |
|
| 379 | + | pub updates: bool, |
|
| 380 | + | /// `stable`, `canary`, or a version such as `0.3.4`. |
|
| 381 | + | pub channel: String, |
|
| 382 | + | /// Hours (UTC) in which it may update, from and to, when limited. |
|
| 383 | + | #[serde(default)] |
|
| 384 | + | pub window: Option<(u8, u8)>, |
|
| 385 | + | /// Fetch and check, say what would happen, do not swap. |
|
| 386 | + | #[serde(default)] |
|
| 387 | + | pub dry_run: bool, |
|
| 388 | + | /// Where each setting came from: `site`, `owner acme`, `group canary`, |
|
| 389 | + | /// `runner`, or `default`, in the order updates, channel, window, dry run. |
|
| 390 | + | #[serde(default)] |
|
| 391 | + | pub from: Vec<String>, |
|
| 392 | + | } |
|
| 393 | + | ||
| 394 | + | /// A build to install: a release asset of the site's runner releases. |
|
| 395 | + | #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] |
|
| 396 | + | pub struct UpdateOffer { |
|
| 397 | + | pub version: String, |
|
| 398 | + | pub tag: String, |
|
| 399 | + | /// The asset's name, `flow-linux-x86_64`. |
|
| 400 | + | pub asset: String, |
|
| 401 | + | /// Where to download it, relative to the hub. |
|
| 402 | + | pub url: String, |
|
| 403 | + | /// Its BLAKE3, as the hub stores and attests it: the download must match. |
|
| 404 | + | pub blake3: String, |
|
| 405 | + | pub size: u64, |
|
| 406 | + | /// Older than the runner's build: a pinned channel going back. |
|
| 407 | + | #[serde(default)] |
|
| 408 | + | pub older: bool, |
|
| 409 | + | } |
|
| 410 | + | ||
| 411 | + | /// `POST /api/v1/flow/runner/update`: what the runner did about its update, |
|
| 412 | + | /// shown on its page. |
|
| 413 | + | #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] |
|
| 414 | + | pub struct UpdateReport { |
|
| 415 | + | pub note: String, |
|
| 416 | + | } |
|
| 417 | + | ||
| 360 | 418 | /// `POST /api/v1/flow/jobs/{id}/log`. |
|
| 361 | 419 | #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] |
|
| 362 | 420 | pub struct LogBatch { |
|
| … | 29 unchanged lines |