From 2b690d6b42bbe8156ed9cdeb0c847be52db27b7e Mon Sep 17 00:00:00 2001 From: Eric Wendland Date: Thu, 21 May 2026 01:42:13 +0200 Subject: [PATCH] Clarify pubsub durability boundary --- README.md | 8 +++++--- crates/geth-pubsub/src/lib.rs | 2 +- crates/geth/tests/bootstrap.rs | 1 + docs/architecture.md | 8 +++++--- docs/roadmap.md | 2 +- 5 files changed, 13 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index c90a406..729344d 100644 --- a/README.md +++ b/README.md @@ -210,9 +210,11 @@ older than the local value. Remote pubsub publish uses the protected Iroh control path too. The remote peer requires `pubsub.publish` on `resource:pubsub:` before recording the message in its local daemon-lifetime ring buffer. Pubsub remains lossy and is -not durable storage. Remote pubsub subscribe uses the same protected path and -requires `pubsub.subscribe` on `resource:pubsub:` before returning the -peer's current daemon-lifetime snapshot for that topic. +not durable storage; facts that must survive restart or reconcile offline +belong in CAS, KV, document, or DB resources. Remote pubsub subscribe uses the +same protected path and requires `pubsub.subscribe` on +`resource:pubsub:` before returning the peer's current daemon-lifetime +snapshot for that topic. Remote pipe connect uses the same protected Iroh control path and requires `pipe.connect` on `resource:pipe:`. The current prototype records a remote connection attempt and whether a listener exists. `geth pipe send diff --git a/crates/geth-pubsub/src/lib.rs b/crates/geth-pubsub/src/lib.rs index 3eb68d3..47ed350 100644 --- a/crates/geth-pubsub/src/lib.rs +++ b/crates/geth-pubsub/src/lib.rs @@ -43,7 +43,7 @@ pub fn validate_message(message: &str) -> Result<(), PubsubError> { #[must_use] pub fn pubsub_storage_warning() -> &'static str { - "pubsub is lossy notification transport, not authoritative storage" + "pubsub is lossy notification transport, not authoritative storage; durable facts belong in CAS, KV, documents, or DB resources" } #[cfg(test)] diff --git a/crates/geth/tests/bootstrap.rs b/crates/geth/tests/bootstrap.rs index 604d168..4981e25 100644 --- a/crates/geth/tests/bootstrap.rs +++ b/crates/geth/tests/bootstrap.rs @@ -1554,6 +1554,7 @@ fn pubsub_pub_sub_uses_lossy_in_memory_runtime() { assert_eq!(messages.len(), 1); assert_eq!(messages[0].message, "online"); assert!(note.contains("not authoritative storage")); + assert!(note.contains("CAS, KV, documents, or DB resources")); } other => panic!("unexpected response: {other:?}"), } diff --git a/docs/architecture.md b/docs/architecture.md index 3d5f160..e368415 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -196,9 +196,11 @@ encoding and sync are future work. `geth-pubsub` currently supports local publish/subscribe snapshots through the daemon control protocol. Messages live in a bounded in-memory ring buffer and are lost when the daemon stops. This is deliberate: pubsub is a lossy wakeup and -presence channel, not authoritative storage. `geth pubsub pub ---node ` can publish to an imported peer over the protected Iroh -control ALPN. The remote daemon validates endpoint/card binding and requires +presence channel, not authoritative storage. Durable facts must be written to +CAS, KV, document, or DB resources before pubsub is used as a wakeup. `geth +pubsub pub --node ` can publish to an imported peer +over the protected Iroh control ALPN. The remote daemon validates endpoint/card +binding and requires `pubsub.publish` on `resource:pubsub:` before recording the message in its local ring buffer. `geth pubsub sub --node ` can read an authorized peer's current snapshot for that topic over the same protected path diff --git a/docs/roadmap.md b/docs/roadmap.md index 15ba401..58377a8 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -350,7 +350,7 @@ authorization and durable-state boundaries clear. `resource:pubsub:`. - `[x]` Tests cover denied and allowed remote pubsub subscribe. - `[ ]` Replace bootstrap remote publish with iroh-gossip topics. - - `[ ]` Docs and tests keep durable state in CAS/KV/document/db instead. + - `[x]` Docs and tests keep durable state in CAS/KV/document/db instead. ## Phase 4: Pipes, SSH Proxy, And SSH Distribution