zc2 0.0.45

P2P compute broker with credit-based billing, WAL, and broker mesh support
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
//! On-disk state of `zc agent` under `~/.zakuro/agent/` (spec §6.2).

use serde::{de::DeserializeOwned, Deserialize, Serialize};
use std::collections::BTreeMap;
use std::io::Write;
use std::path::Path;

pub const AGENT_FILE: &str = "agent.json";
pub const STATE_FILE: &str = "state.json";
pub const CHILDREN_FILE: &str = "children.json";
pub const HISTORY_FILE: &str = "history.json";
pub const LOG_FILE: &str = "agent.log";
/// Written by the desktop app, never by the agent (docs/agent-api.md, "The
/// app file"): which app is installed next to this agent, for presence.
pub const APP_FILE: &str = "app.json";
/// The agent's bounded jobs journal (`agent::jobs`).
pub const JOBS_FILE: &str = "jobs.json";
pub const WORKER_LOG_DIR: &str = "workers";

/// `agent.json`: how the app and the CLI reach the running agent.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AgentFile {
    pub v: u32,
    pub port: u16,
    pub token: String,
    pub pid: u32,
    pub version: String,
    /// Bumped on every rewrite of `agent.json` (start, restart, token
    /// re-mint), so a watcher -- the desktop app republishing the endpoint
    /// into the App Group (ADR ZC-0019 §7) -- can tell "rewritten" from
    /// "unchanged" without comparing tokens. Added without a `v` bump: a
    /// file written before it existed decodes as 0.
    #[serde(default)]
    pub rev: u64,
}

/// `app.json`, written by the desktop app next to `agent.json` (format in
/// docs/agent-api.md). The agent only reads it, to report presence to the hub.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AppFile {
    pub v: u32,
    /// `"desktop"`: the only app that writes this file today.
    pub app: String,
    pub app_version: String,
    /// The app's pid. When set and that process is gone, the app is not
    /// running and presence reports no app.
    #[serde(default)]
    pub pid: Option<u32>,
}

/// The app this agent runs beside, from `<dir>/app.json`: `(app, version)`.
/// `None` when the file is missing, unreadable, an unknown `v` or `app`, or
/// names a pid that `alive` says is gone.
pub fn running_app(dir: &Path, alive: impl Fn(u32) -> bool) -> Option<(String, String)> {
    let f: AppFile = load_json(&dir.join(APP_FILE))?;
    if f.v != 1 || f.app != "desktop" || f.app_version.trim().is_empty() {
        return None;
    }
    if f.pid.is_some_and(|p| !alive(p)) {
        return None;
    }
    Some((f.app, f.app_version.trim().chars().take(64).collect()))
}

/// `state.json`: what the owner asked for. The agent is its only owner.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DesiredState {
    pub sharing: bool,
    pub workers: u32,
    /// Hub worker-row ids of this Mac already seen, for new-row price seeding (§6.7).
    #[serde(default)]
    pub known_worker_ids: Vec<i64>,
}

impl Default for DesiredState {
    fn default() -> Self {
        Self {
            sharing: false,
            workers: 1,
            known_worker_ids: vec![],
        }
    }
}

/// A child the agent spawned, identified across agent restarts by pid + start
/// time -- or, for a container-backed worker, by container name + the time
/// that container was started.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChildRecord {
    pub pid: u32,
    pub started_at: String,
    /// The broker's port, so an adopted broker is talked to on the port it
    /// actually started on (it may have fallen back from 9000). `None` for a
    /// worker record (its port is deterministic), and for a broker record
    /// written before this field existed -- a missing value means 9000.
    #[serde(default)]
    pub port: Option<u16>,
    /// The Docker container this child runs in, when it is a container-backed
    /// worker (`ZAKURO_SHARE_RUNTIME`, issues #263, #387) rather than a host process.
    /// `None` -- including for every record written before this field existed
    /// -- means a host process, so `pid`/`started_at` are a real pid and its
    /// start time. When it is `Some`, `pid` is 0 (never a real pid) and
    /// `started_at` is the container's `.State.StartedAt`.
    #[serde(default)]
    pub container: Option<String>,
}

/// `children.json`: the broker and workers (keyed by index) the agent owns.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct Children {
    #[serde(default)]
    pub broker: Option<ChildRecord>,
    #[serde(default)]
    pub workers: BTreeMap<String, ChildRecord>,
}

/// Create `dir` (and parents) and set it to 0700.
pub fn ensure_dir(dir: &Path) -> std::io::Result<()> {
    std::fs::create_dir_all(dir)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        std::fs::set_permissions(dir, std::fs::Permissions::from_mode(0o700))?;
    }
    Ok(())
}

/// Write `bytes` to `path` as 0600, atomically (temp file + rename), so a
/// reader never sees half a token. The temp file carries the writer's pid, so
/// two processes writing the same file (an agent restarting while `zc agent
/// install` re-mints) never share one half-written temp file.
pub fn write_private(path: &Path, bytes: &[u8]) -> std::io::Result<()> {
    let tmp = path.with_extension(format!("tmp.{}", std::process::id()));
    {
        let mut opts = std::fs::OpenOptions::new();
        opts.write(true).create(true).truncate(true);
        #[cfg(unix)]
        {
            use std::os::unix::fs::OpenOptionsExt;
            opts.mode(0o600);
        }
        let mut f = opts.open(&tmp)?;
        f.write_all(bytes)?;
        f.sync_all()?;
    }
    std::fs::rename(&tmp, path)
}

pub fn load_json<T: DeserializeOwned>(path: &Path) -> Option<T> {
    serde_json::from_slice(&std::fs::read(path).ok()?).ok()
}

pub fn save_json<T: Serialize>(path: &Path, value: &T) -> std::io::Result<()> {
    let bytes = serde_json::to_vec_pretty(value).map_err(std::io::Error::other)?;
    write_private(path, &bytes)
}

/// 32 random bytes as unpadded base64url: always 43 characters.
pub fn new_token() -> String {
    use base64::Engine;
    use ring::rand::SecureRandom;
    let mut buf = [0u8; 32];
    ring::rand::SystemRandom::new()
        .fill(&mut buf)
        .expect("system rng");
    base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(buf)
}

/// Load `agent.json`, keeping its token across restarts; `rotate` (from
/// `zc agent install`) mints a new one. Always rewrites pid/port/version,
/// atomically, and bumps `rev` so a watcher sees every rewrite.
pub fn load_or_init_agent_file(dir: &Path, port: u16, rotate: bool) -> std::io::Result<AgentFile> {
    ensure_dir(dir)?;
    let path = dir.join(AGENT_FILE);
    let existing = load_json::<AgentFile>(&path);
    let rev = existing.as_ref().map_or(0, |e| e.rev).wrapping_add(1);
    let token = match (rotate, existing) {
        (false, Some(existing)) if existing.token.len() == 43 => existing.token,
        _ => new_token(),
    };
    let file = AgentFile {
        v: 1,
        port,
        token,
        pid: std::process::id(),
        version: env!("CARGO_PKG_VERSION").to_string(),
        rev,
    };
    save_json(&path, &file)?;
    Ok(file)
}

/// `pub(crate)` so other agent test modules can reuse `tmp`.
#[cfg(test)]
pub(crate) mod tests {
    use super::*;
    use std::path::PathBuf;

    pub(crate) fn tmp(tag: &str) -> PathBuf {
        use std::sync::atomic::{AtomicU32, Ordering};
        static N: AtomicU32 = AtomicU32::new(0);
        let d = std::env::temp_dir().join(format!(
            "zc-agent-{tag}-{}-{}",
            std::process::id(),
            N.fetch_add(1, Ordering::Relaxed)
        ));
        let _ = std::fs::remove_dir_all(&d);
        d
    }

    #[test]
    fn token_is_43_char_base64url_and_random() {
        let t = new_token();
        assert_eq!(t.len(), 43);
        assert!(t
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_'));
        assert_ne!(t, new_token());
    }

    #[test]
    fn token_survives_a_restart_and_rotates_on_install() {
        let d = tmp("tok");
        let first = load_or_init_agent_file(&d, 4720, false).unwrap();
        let restart = load_or_init_agent_file(&d, 4720, false).unwrap();
        assert_eq!(first.token, restart.token);
        assert_eq!(restart.v, 1);
        assert_eq!(restart.pid, std::process::id());
        let installed = load_or_init_agent_file(&d, 4720, true).unwrap();
        assert_ne!(first.token, installed.token);
        assert_eq!(
            (first.rev, restart.rev, installed.rev),
            (1, 2, 3),
            "every rewrite bumps rev, so a watcher sees a re-mint"
        );
    }

    /// The contract the desktop app's watcher relies on (ADR ZC-0019 §7):
    /// `agent.json` is replaced by a rename, never rewritten in place, so a
    /// reader sees the old file or the new one and never half of either; no
    /// temp file is left behind; and an older file without `rev` still loads.
    #[test]
    fn agent_json_is_replaced_atomically_and_old_files_still_load() {
        let d = tmp("atomic");
        let first = load_or_init_agent_file(&d, 4720, false).unwrap();
        #[cfg(unix)]
        let inode = |p: &std::path::Path| {
            use std::os::unix::fs::MetadataExt;
            std::fs::metadata(p).unwrap().ino()
        };
        #[cfg(unix)]
        let before = inode(&d.join(AGENT_FILE));
        let reminted = load_or_init_agent_file(&d, 4720, true).unwrap();
        #[cfg(unix)]
        assert_ne!(before, inode(&d.join(AGENT_FILE)), "a new file, renamed in");
        assert_ne!(first.token, reminted.token);
        let leftovers: Vec<_> = std::fs::read_dir(&d)
            .unwrap()
            .filter_map(|e| e.ok())
            .map(|e| e.file_name().to_string_lossy().into_owned())
            .filter(|n| n.contains(".tmp"))
            .collect();
        assert!(leftovers.is_empty(), "{leftovers:?}");

        std::fs::write(
            d.join(AGENT_FILE),
            r#"{"v":1,"port":4720,"token":"t","pid":1,"version":"0.0.30"}"#,
        )
        .unwrap();
        let old: AgentFile = load_json(&d.join(AGENT_FILE)).unwrap();
        assert_eq!(old.rev, 0);
        assert_eq!(load_or_init_agent_file(&d, 4720, false).unwrap().rev, 1);
    }

    #[test]
    fn the_app_file_names_a_running_desktop_app_or_nothing() {
        let d = tmp("appfile");
        ensure_dir(&d).unwrap();
        let alive = |_: u32| true;
        assert_eq!(running_app(&d, alive), None, "no file, no app");
        let write = |s: &str| std::fs::write(d.join(APP_FILE), s).unwrap();
        write(r#"{"v":1,"app":"desktop","app_version":"0.3.1","pid":42}"#);
        assert_eq!(
            running_app(&d, alive),
            Some(("desktop".into(), "0.3.1".into()))
        );
        assert_eq!(running_app(&d, |_| false), None, "the app quit");
        write(r#"{"v":1,"app":"desktop","app_version":"0.3.1"}"#);
        assert_eq!(
            running_app(&d, |_| false),
            Some(("desktop".into(), "0.3.1".into())),
            "no pid: present while the file is"
        );
        write(r#"{"v":2,"app":"desktop","app_version":"0.3.1"}"#);
        assert_eq!(running_app(&d, alive), None, "unknown v");
        write(r#"{"v":1,"app":"something","app_version":"0.3.1"}"#);
        assert_eq!(running_app(&d, alive), None, "unknown app");
        write("not json");
        assert_eq!(running_app(&d, alive), None);
    }

    #[cfg(unix)]
    #[test]
    fn agent_files_are_private() {
        use std::os::unix::fs::PermissionsExt;
        let d = tmp("modes");
        load_or_init_agent_file(&d, 4720, false).unwrap();
        save_json(&d.join(STATE_FILE), &DesiredState::default()).unwrap();
        let mode = |p: &std::path::Path| std::fs::metadata(p).unwrap().permissions().mode() & 0o777;
        assert_eq!(mode(&d), 0o700);
        assert_eq!(mode(&d.join(AGENT_FILE)), 0o600);
        assert_eq!(mode(&d.join(STATE_FILE)), 0o600);
    }

    #[test]
    #[allow(clippy::field_reassign_with_default)]
    fn state_and_children_round_trip() {
        let d = tmp("rt");
        ensure_dir(&d).unwrap();
        let state = DesiredState {
            sharing: true,
            workers: 2,
            known_worker_ids: vec![123, 124],
        };
        save_json(&d.join(STATE_FILE), &state).unwrap();
        assert_eq!(load_json::<DesiredState>(&d.join(STATE_FILE)), Some(state));
        let raw: serde_json::Value =
            serde_json::from_slice(&std::fs::read(d.join(STATE_FILE)).unwrap()).unwrap();
        assert_eq!(
            raw,
            serde_json::json!({"sharing":true,"workers":2,"known_worker_ids":[123,124]})
        );

        let mut children = Children::default();
        children.broker = Some(ChildRecord {
            pid: 7,
            started_at: "t0".into(),
            port: Some(9001),
            container: None,
        });
        children.workers.insert(
            "0".into(),
            ChildRecord {
                pid: 8,
                started_at: "t1".into(),
                port: None,
                container: None,
            },
        );
        save_json(&d.join(CHILDREN_FILE), &children).unwrap();
        assert_eq!(
            load_json::<Children>(&d.join(CHILDREN_FILE)),
            Some(children)
        );
    }

    /// A `children.json` written before `port` existed decodes with `None`,
    /// which the supervisor treats as 9000 on adoption.
    #[test]
    fn a_broker_record_without_a_port_field_decodes_as_none() {
        let raw = r#"{"broker":{"pid":7,"started_at":"t0"},"workers":{}}"#;
        let c: Children = serde_json::from_str(raw).unwrap();
        assert_eq!(c.broker.unwrap().port, None);
    }

    /// A record written by any earlier zc has no `container` field, and
    /// decodes as the host process it was: adoption after an upgrade must not
    /// mistake a recorded pid for a container.
    #[test]
    fn a_record_without_a_container_field_is_a_host_process() {
        let raw = r#"{"broker":null,"workers":{"0":{"pid":8,"started_at":"t1","port":null}}}"#;
        let c: Children = serde_json::from_str(raw).unwrap();
        assert_eq!(c.workers["0"].container, None);
    }

    /// A container-backed worker records the container's name and its
    /// `.State.StartedAt` instead of a pid and a process start time. The pid
    /// field is 0, which is never a real one.
    #[test]
    fn a_container_backed_worker_record_round_trips() {
        let d = tmp("children-container");
        ensure_dir(&d).unwrap();
        let mut children = Children::default();
        children.workers.insert(
            "0".into(),
            ChildRecord {
                pid: 0,
                started_at: "2026-09-18T07:01:02.3456789Z".into(),
                port: None,
                container: Some("zc-share-testfp00-w0".into()),
            },
        );
        save_json(&d.join(CHILDREN_FILE), &children).unwrap();
        assert_eq!(
            load_json::<Children>(&d.join(CHILDREN_FILE)),
            Some(children)
        );
    }

    #[test]
    fn a_missing_state_file_means_one_worker_not_sharing() {
        let d = tmp("missing");
        let s = load_json::<DesiredState>(&d.join(STATE_FILE)).unwrap_or_default();
        assert_eq!(
            s,
            DesiredState {
                sharing: false,
                workers: 1,
                known_worker_ids: vec![]
            }
        );
    }
}