Skip to main content

second_brain_core/
write_queue.rs

1//! Writes held on disk for the daemon. An entry is either sealed to the
2//! device's `device.pub`, keeping only its [`Label`] readable, or plaintext,
3//! as older binaries and a writer without the recipient write it.
4
5use std::io::Write;
6use std::path::Path;
7
8use age::x25519::{Identity, Recipient};
9use anyhow::{Context, bail};
10use base64::Engine;
11use base64::engine::general_purpose::STANDARD;
12use serde::{Deserialize, Serialize};
13use serde_json::Value;
14
15/// The directory under the data dir where writes wait for the daemon; the
16/// MCP server, the daemon's write gate and its replayer all use it.
17pub const DIR_NAME: &str = "queue";
18
19const PLAIN_SUFFIX: &str = ".json";
20/// Older binaries' entry rule skips this suffix, so after a downgrade a
21/// sealed entry waits for a daemon that can open it instead of replaying
22/// with no body.
23const SEALED_SUFFIX: &str = ".sealed";
24
25/// `<19-digit unix nanos>-<uuid>.json`, or `.sealed`; no other name in the
26/// directory is an entry, so a file still being written under a temporary
27/// name is never read.
28pub fn is_entry_name(name: &str) -> bool {
29    let Some(stem) = name
30        .strip_suffix(PLAIN_SUFFIX)
31        .or_else(|| name.strip_suffix(SEALED_SUFFIX))
32    else {
33        return false;
34    };
35    let Some((nanos, id)) = stem.split_at_checked(19) else {
36        return false;
37    };
38    nanos.bytes().all(|b| b.is_ascii_digit())
39        && id
40            .strip_prefix('-')
41            .is_some_and(|id| id.len() == 36 && uuid::Uuid::parse_str(id).is_ok())
42}
43
44pub fn is_sealed_name(name: &str) -> bool {
45    name.ends_with(SEALED_SUFFIX) && is_entry_name(name)
46}
47
48/// A fresh entry name for a write made at `nanos` since the epoch.
49pub fn entry_name(nanos: u128, sealed: bool) -> String {
50    let suffix = if sealed { SEALED_SUFFIX } else { PLAIN_SUFFIX };
51    format!("{nanos:019}-{}{suffix}", uuid::Uuid::new_v4())
52}
53
54/// One queued write, as it is sent to the daemon.
55#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
56pub struct Entry {
57    pub tool: String,
58    pub method: String,
59    pub path: String,
60    /// Already URL-encoded, without the leading `?`.
61    #[serde(default)]
62    pub query: Option<String>,
63    #[serde(default)]
64    pub body: Option<Value>,
65}
66
67/// What a sealed entry keeps readable without the device key.
68#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
69pub struct Label {
70    pub tool: String,
71    pub method: String,
72    pub path: String,
73    /// An ingest's source, so a writer can collapse ingests per source.
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub source: Option<String>,
76    /// A note's session and kind, so the stop hook can find a queued
77    /// session-end note.
78    #[serde(default, skip_serializing_if = "Option::is_none")]
79    pub session_id: Option<String>,
80    #[serde(default, skip_serializing_if = "Option::is_none")]
81    pub kind: Option<String>,
82}
83
84#[derive(Serialize, Deserialize)]
85struct SealedFile {
86    #[serde(flatten)]
87    label: Label,
88    sealed: String,
89}
90
91#[derive(Deserialize)]
92struct StoredFile {
93    #[serde(flatten)]
94    label: Label,
95    #[serde(default)]
96    sealed: Option<String>,
97    #[serde(default)]
98    query: Option<String>,
99    #[serde(default)]
100    body: Option<Value>,
101}
102
103#[derive(Debug)]
104pub enum OpenError {
105    /// A sealed entry, and no device identity to open it with.
106    NoKey,
107    Unreadable(anyhow::Error),
108}
109
110impl std::fmt::Display for OpenError {
111    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
112        match self {
113            Self::NoKey => f.write_str("the entry is sealed and the device key is unavailable"),
114            Self::Unreadable(e) => write!(f, "{e:#}"),
115        }
116    }
117}
118
119impl std::error::Error for OpenError {}
120
121impl Entry {
122    pub fn label(&self) -> Label {
123        let field = |name: &str| {
124            self.body
125                .as_ref()
126                .and_then(|b| b.get(name))
127                .and_then(Value::as_str)
128                .map(str::to_string)
129        };
130        let (source, session_id, kind) = match self.tool.as_str() {
131            "ingest" => (field("source"), None, None),
132            "note" => (None, field("session_id"), field("kind")),
133            _ => (None, None, None),
134        };
135        Label {
136            tool: self.tool.clone(),
137            method: self.method.clone(),
138            path: self.path.clone(),
139            source,
140            session_id,
141            kind,
142        }
143    }
144
145    pub fn to_plain_file(&self) -> anyhow::Result<Vec<u8>> {
146        Ok(serde_json::to_vec(self)?)
147    }
148
149    /// The whole entry is sealed, to every recipient; the label beside it is
150    /// only an index, and [`open`] takes nothing from it.
151    pub fn to_sealed_file(&self, recipients: &[Recipient]) -> anyhow::Result<Vec<u8>> {
152        if recipients.is_empty() {
153            bail!("sealing a queued write needs a recipient");
154        }
155        let encryptor =
156            age::Encryptor::with_recipients(recipients.iter().map(|r| r as &dyn age::Recipient))
157                .context("sealing a queued write")?;
158        let mut ciphertext = Vec::new();
159        let mut writer = encryptor.wrap_output(&mut ciphertext)?;
160        writer.write_all(&serde_json::to_vec(self)?)?;
161        writer.finish()?;
162        Ok(serde_json::to_vec(&SealedFile {
163            label: self.label(),
164            sealed: STANDARD.encode(ciphertext),
165        })?)
166    }
167}
168
169/// Reads an entry file of either kind; a sealed one needs `identity`.
170pub fn open(bytes: &[u8], identity: Option<&Identity>) -> Result<Entry, OpenError> {
171    let stored: StoredFile =
172        serde_json::from_slice(bytes).map_err(|e| OpenError::Unreadable(e.into()))?;
173    let Some(sealed) = stored.sealed else {
174        return Ok(Entry {
175            tool: stored.label.tool,
176            method: stored.label.method,
177            path: stored.label.path,
178            query: stored.query,
179            body: stored.body,
180        });
181    };
182    let identity = identity.ok_or(OpenError::NoKey)?;
183    let opened = STANDARD
184        .decode(sealed)
185        .context("decoding a sealed queued write")
186        .and_then(|ciphertext| {
187            age::decrypt(identity, &ciphertext).context("opening a sealed queued write")
188        })
189        .and_then(|plain| Ok(serde_json::from_slice(&plain)?))
190        .map_err(OpenError::Unreadable)?;
191    Ok(opened)
192}
193
194/// Seals again, to `recipients`, every sealed entry in `dir` that `old`
195/// opens, so writes queued under a device key outlive it; entries `old`
196/// can't open, or that can't be read, are left as they are. Failing to
197/// write a resealed entry is an error, since the caller may be about to
198/// drop `old`. Returns how many it resealed.
199pub fn reseal_dir(dir: &Path, old: &Identity, recipients: &[Recipient]) -> anyhow::Result<usize> {
200    let items = match std::fs::read_dir(dir) {
201        Ok(items) => items,
202        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(0),
203        Err(e) => return Err(e).with_context(|| format!("listing {}", dir.display())),
204    };
205    let mut resealed = 0;
206    for item in items {
207        let name = item?.file_name().to_string_lossy().into_owned();
208        if !is_sealed_name(&name) {
209            continue;
210        }
211        let path = dir.join(&name);
212        let bytes = match std::fs::read(&path) {
213            Ok(bytes) => bytes,
214            Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
215            Err(e) => {
216                tracing::warn!("cannot reseal {}: {e}", path.display());
217                continue;
218            }
219        };
220        let Ok(entry) = open(&bytes, Some(old)) else {
221            continue;
222        };
223        replace_file(dir, &name, &entry.to_sealed_file(recipients)?)?;
224        resealed += 1;
225    }
226    if resealed > 0 {
227        std::fs::File::open(dir)
228            .and_then(|d| d.sync_all())
229            .with_context(|| format!("syncing {}", dir.display()))?;
230    }
231    Ok(resealed)
232}
233
234fn replace_file(dir: &Path, name: &str, bytes: &[u8]) -> anyhow::Result<()> {
235    let tmp = dir.join(format!("{name}.{}.tmp", uuid::Uuid::new_v4().simple()));
236    let mut options = std::fs::OpenOptions::new();
237    options.write(true).create_new(true);
238    #[cfg(unix)]
239    std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600);
240    let written = options
241        .open(&tmp)
242        .and_then(|mut file| {
243            file.write_all(bytes)?;
244            file.sync_all()
245        })
246        .and_then(|()| std::fs::rename(&tmp, dir.join(name)));
247    if let Err(e) = written {
248        if let Err(cleanup) = std::fs::remove_file(&tmp)
249            && cleanup.kind() != std::io::ErrorKind::NotFound
250        {
251            tracing::warn!("cannot remove {}: {cleanup}", tmp.display());
252        }
253        return Err(e).with_context(|| format!("resealing {}", dir.join(name).display()));
254    }
255    Ok(())
256}
257
258/// The label of an entry file of either kind, read without any key.
259pub fn read_label(bytes: &[u8]) -> anyhow::Result<Label> {
260    let stored: StoredFile = serde_json::from_slice(bytes)?;
261    if stored.sealed.is_some() {
262        return Ok(stored.label);
263    }
264    Ok(Entry {
265        tool: stored.label.tool,
266        method: stored.label.method,
267        path: stored.label.path,
268        query: stored.query,
269        body: stored.body,
270    }
271    .label())
272}
273
274#[cfg(test)]
275mod tests {
276    use serde_json::json;
277
278    use super::*;
279
280    fn note() -> Entry {
281        Entry {
282            tool: "note".to_string(),
283            method: "POST".to_string(),
284            path: "/v1/notes".to_string(),
285            query: None,
286            body: Some(json!({
287                "session_id": "s-1",
288                "kind": "session_end",
289                "content": "the plan for the migration",
290            })),
291        }
292    }
293
294    fn forget() -> Entry {
295        Entry {
296            tool: "forget".to_string(),
297            method: "DELETE".to_string(),
298            path: "/v1/memory/m-1".to_string(),
299            query: Some("hard=true&reason=leaked+the+password".to_string()),
300            body: None,
301        }
302    }
303
304    #[test]
305    fn only_timestamped_uuid_entry_names_count() {
306        let id = "0b5c2f9e-5d0e-4c1a-9a57-0c7f4f1f2a10";
307        assert!(is_entry_name(&format!("1793505622000000000-{id}.json")));
308        assert!(is_entry_name(&format!("1793505622000000000-{id}.sealed")));
309        for name in [
310            "projects.json".to_string(),
311            ".lock".to_string(),
312            format!("1793505622000000000-{id}.json.tmp"),
313            format!("1793505622000000000-{id}.sealed.tmp"),
314            format!("179350562200000000-{id}.json"),
315            format!("1793505622000000000-{id}.unreadable"),
316            format!("1793505622000000000-{id}.sealed.json"),
317            "1793505622000000000-not-a-uuid.json".to_string(),
318        ] {
319            assert!(!is_entry_name(&name), "{name}");
320        }
321        assert!(is_entry_name(&entry_name(7, true)));
322        assert!(is_sealed_name(&entry_name(7, true)));
323        assert!(!is_sealed_name(&entry_name(7, false)));
324        assert!(entry_name(7, true).ends_with(".sealed"));
325        assert!(entry_name(7, false).ends_with(".json"));
326        assert!(entry_name(7, false).starts_with("0000000000000000007-"));
327    }
328
329    #[test]
330    fn a_sealed_entry_shows_only_its_label_and_opens_with_the_device_key() {
331        let identity = Identity::generate();
332        for entry in [note(), forget()] {
333            let file = entry.to_sealed_file(&[identity.to_public()]).unwrap();
334            let text = String::from_utf8_lossy(&file);
335            for secret in ["migration", "password", "reason", "content"] {
336                assert!(!text.contains(secret), "{secret} in {text}");
337            }
338            assert_eq!(read_label(&file).unwrap(), entry.label());
339            assert_eq!(open(&file, Some(&identity)).unwrap(), entry);
340            assert!(matches!(open(&file, None), Err(OpenError::NoKey)));
341            assert!(matches!(
342                open(&file, Some(&Identity::generate())),
343                Err(OpenError::Unreadable(_))
344            ));
345        }
346    }
347
348    #[test]
349    fn a_plaintext_entry_from_an_older_binary_opens_without_a_key() {
350        let older = br#"{"tool":"note","method":"POST","path":"/v1/notes","query":null,"body":{"session_id":"s-1","kind":"session_end","content":"x"}}"#;
351        assert_eq!(
352            open(older, None).unwrap().body,
353            note().body.map(|mut b| {
354                b["content"] = json!("x");
355                b
356            })
357        );
358        let label = read_label(older).unwrap();
359        assert_eq!(label.session_id.as_deref(), Some("s-1"));
360        assert_eq!(label.kind.as_deref(), Some("session_end"));
361        let entry = forget();
362        assert_eq!(open(&entry.to_plain_file().unwrap(), None).unwrap(), entry);
363    }
364
365    #[test]
366    fn labels_carry_an_ingests_source_and_a_notes_session_only() {
367        let ingest = Entry {
368            tool: "ingest".to_string(),
369            method: "POST".to_string(),
370            path: "/v1/ingest".to_string(),
371            query: None,
372            body: Some(json!({ "source": "cursor", "session_id": "s-1" })),
373        };
374        let label = ingest.label();
375        assert_eq!(label.source.as_deref(), Some("cursor"));
376        assert_eq!(label.session_id, None);
377        let note = note().label();
378        assert_eq!(
379            (
380                note.source,
381                note.session_id.as_deref(),
382                note.kind.as_deref()
383            ),
384            (None, Some("s-1"), Some("session_end"))
385        );
386        let remember = Entry {
387            tool: "remember".to_string(),
388            body: Some(json!({ "session_id": "s-1", "source": "x" })),
389            ..forget()
390        };
391        assert_eq!(
392            remember.label(),
393            Label {
394                tool: "remember".to_string(),
395                method: "DELETE".to_string(),
396                path: "/v1/memory/m-1".to_string(),
397                ..Label::default()
398            }
399        );
400    }
401
402    #[test]
403    fn a_sealed_entry_opens_with_any_of_its_recipients() {
404        let (a, b) = (Identity::generate(), Identity::generate());
405        let file = forget()
406            .to_sealed_file(&[a.to_public(), b.to_public()])
407            .unwrap();
408        assert_eq!(open(&file, Some(&a)).unwrap(), forget());
409        assert_eq!(open(&file, Some(&b)).unwrap(), forget());
410        assert!(forget().to_sealed_file(&[]).is_err());
411    }
412
413    #[test]
414    fn resealing_moves_what_the_old_key_opens_to_the_new_recipients() {
415        let dir = tempfile::tempdir().unwrap();
416        let (old, fresh, stranger) = (
417            Identity::generate(),
418            Identity::generate(),
419            Identity::generate(),
420        );
421        let ours = entry_name(1, true);
422        let theirs = entry_name(2, true);
423        let plain = entry_name(3, false);
424        let write =
425            |name: &str, bytes: Vec<u8>| std::fs::write(dir.path().join(name), bytes).unwrap();
426        write(&ours, note().to_sealed_file(&[old.to_public()]).unwrap());
427        write(
428            &theirs,
429            forget().to_sealed_file(&[stranger.to_public()]).unwrap(),
430        );
431        write(&plain, forget().to_plain_file().unwrap());
432
433        let resealed = reseal_dir(dir.path(), &old, &[fresh.to_public()]).unwrap();
434        assert_eq!(resealed, 1);
435        let read = |name: &str| std::fs::read(dir.path().join(name)).unwrap();
436        assert_eq!(open(&read(&ours), Some(&fresh)).unwrap(), note());
437        assert!(open(&read(&ours), Some(&old)).is_err());
438        assert_eq!(open(&read(&theirs), Some(&stranger)).unwrap(), forget());
439        assert_eq!(open(&read(&plain), None).unwrap(), forget());
440        let names: Vec<_> = std::fs::read_dir(dir.path())
441            .unwrap()
442            .flatten()
443            .map(|e| e.file_name().to_string_lossy().into_owned())
444            .collect();
445        assert_eq!(names.len(), 3, "{names:?}");
446        assert_eq!(
447            reseal_dir(&dir.path().join("missing"), &old, &[fresh.to_public()]).unwrap(),
448            0
449        );
450    }
451
452    #[test]
453    fn a_reseal_that_cannot_write_fails_and_leaves_the_entry() {
454        use std::os::unix::fs::PermissionsExt;
455        let dir = tempfile::tempdir().unwrap();
456        let (old, fresh) = (Identity::generate(), Identity::generate());
457        let name = entry_name(1, true);
458        let sealed = note().to_sealed_file(&[old.to_public()]).unwrap();
459        std::fs::write(dir.path().join(&name), &sealed).unwrap();
460        let read_only = std::fs::Permissions::from_mode(0o500);
461        std::fs::set_permissions(dir.path(), read_only).unwrap();
462        let result = reseal_dir(dir.path(), &old, &[fresh.to_public()]);
463        std::fs::set_permissions(dir.path(), std::fs::Permissions::from_mode(0o700)).unwrap();
464        assert!(result.is_err());
465        assert_eq!(std::fs::read(dir.path().join(&name)).unwrap(), sealed);
466    }
467
468    #[test]
469    fn a_corrupt_entry_is_unreadable() {
470        assert!(matches!(open(b"{", None), Err(OpenError::Unreadable(_))));
471        let bad = br#"{"tool":"note","method":"POST","path":"/v1/notes","sealed":"!!"}"#;
472        assert!(matches!(
473            open(bad, Some(&Identity::generate())),
474            Err(OpenError::Unreadable(_))
475        ));
476    }
477}