Skip to main content

hyprstream_core/git/
promote.rs

1//! Promote saga — snapshot the node-local upper layer into a content-addressed
2//! registry commit, then advance the atproto pointer record.
3//!
4//! # What promote does
5//!
6//! The writable union (#394) buffers writes in a node-local, append-only upper
7//! layer (the existing overlayfs upper + a journal). Promote is the operation
8//! that turns those buffered edits into an immutable, distributed snapshot:
9//!
10//! 1. **Stage + commit locally** via the existing `WorktreeClient::stage_all` /
11//!    `commit` RPCs (`registry.capnp`). This produces a deterministic git commit:
12//!    two nodes promoting byte-identical upper-layer content produce identical
13//!    commit OIDs (the stageAll→commit path is deterministic given identical
14//!    index + tree state).
15//! 2. **Advance the atproto pointer record** so federated peers see the new
16//!    head. This is the only step that touches the PDS.
17//!
18//! # Single-writer-per-layer (Shapiro)
19//!
20//! A layer may be promoted by at most one node at a time. We enforce this at
21//! the promote entry point with a per-layer lease (the
22//! [`PromoteLease`]). The lease is held for the duration of the local commit;
23//! the PDS write that follows is idempotent (atproto `putRecord` is
24//! last-writer-wins on the record `rkey`), so a crashed promote that already
25//! committed locally simply re-runs and advances the pointer on retry.
26//!
27//! # Eventual consistency, not atomicity
28//!
29//! Promote spans two stores: the local git repo and the atproto PDS. We do
30//! **not** pretend this is atomic. The local commit happens first and is
31//! durable; the PDS record update happens second. If the PDS write fails after
32//! the local commit succeeds:
33//!
34//!   - The content is committed locally and reachable via the git ref.
35//!   - The atproto pointer is **stale** — it still points at the previous head.
36//!   - The next successful promote advances the pointer to the latest local
37//!     head, skipping the stale intermediate. Because git commits are
38//!     content-addressed and parent-chained, no commit is lost: the stale
39//!     pointer simply lags until a later promote catches up.
40//!
41//! This is the honest treatment. A two-phase-commit across git + atproto would
42//! require a PDS that supports prepare/commit, which atproto does not; the
43//! pointer-record pattern is the standard atproto eventual-consistency
44//! primitive (it is how Bluesky itself advances collection pointers).
45//!
46//! # No new RPC
47//!
48//! Promote reuses the existing `stageAll` + `commit` worktree verbs from
49//! `registry.capnp`. The PDS record write is a plain HTTPS `putRecord` call,
50//! not a hyprstream RPC — the atproto substrate (#355/#410) owns that client.
51
52use std::collections::HashMap;
53use std::sync::Arc;
54
55use parking_lot::Mutex;
56use tracing::{info, warn};
57
58use hyprstream_rpc_std::registry_client::{CommitWithAuthorRequest, WorktreeClient};
59
60/// An error from the promote saga.
61#[derive(Debug)]
62pub enum PromoteError {
63    /// Another node currently holds the promote lease for this layer.
64    LeaseHeld(String),
65    /// The local stage/commit step failed.
66    LocalCommit(String),
67    /// The atproto pointer-record update failed. The local commit already
68    /// succeeded — the pointer is stale and will be advanced by the next
69    /// successful promote. See the module-level eventual-consistency note.
70    PointerStale(String),
71}
72
73impl std::fmt::Display for PromoteError {
74    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
75        match self {
76            Self::LeaseHeld(s) => write!(f, "promote lease held by another node: {s}"),
77            Self::LocalCommit(s) => write!(f, "local commit failed: {s}"),
78            Self::PointerStale(s) => {
79                write!(
80                    f,
81                    "local commit ok but atproto pointer update failed (stale): {s}"
82                )
83            }
84        }
85    }
86}
87
88impl std::error::Error for PromoteError {}
89
90/// Outcome of a successful [`promote`].
91#[derive(Clone, Debug)]
92pub struct PromoteOutcome {
93    /// OID of the freshly committed snapshot (deterministic across nodes).
94    pub commit_oid: String,
95    /// Whether the atproto pointer record was advanced in this run. Always
96    /// `Ok(())` on a clean promote; consult [`PromoteError::PointerStale`] for
97    /// the failure case where the pointer lags.
98    pub pointer_advanced: bool,
99}
100
101/// A held per-layer promote lease. Dropping it releases the layer for other
102/// nodes to promote.
103///
104/// This is an in-process token; the distributed single-writer invariant
105/// (Shapiro) is enforced at the registry/PDS layer by the pointer-record
106/// version check. The in-process lease prevents the common case of two
107/// concurrent promotes from the *same* node racing on the same worktree.
108pub struct PromoteLease {
109    key: String,
110    table: Arc<PromoteLeaseTable>,
111}
112
113impl std::fmt::Debug for PromoteLease {
114    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
115        f.debug_struct("PromoteLease")
116            .field("key", &self.key)
117            .finish()
118    }
119}
120
121impl Drop for PromoteLease {
122    fn drop(&mut self) {
123        self.table.0.lock().remove(&self.key);
124    }
125}
126
127/// Per-process registry of held promote leases, keyed by `{repo}:{worktree}`.
128#[derive(Default)]
129pub struct PromoteLeaseTable(Mutex<HashMap<String, ()>>);
130
131impl PromoteLeaseTable {
132    /// Create an empty lease table.
133    pub fn new() -> Self {
134        Self::default()
135    }
136
137    /// Try to acquire the lease for `key`. Returns `Err(LeaseHeld)` if another
138    /// promoter already holds it.
139    pub fn acquire(self: &Arc<Self>, key: &str) -> Result<PromoteLease, PromoteError> {
140        let mut guard = self.0.lock();
141        if guard.contains_key(key) {
142            return Err(PromoteError::LeaseHeld(key.to_owned()));
143        }
144        guard.insert(key.to_owned(), ());
145        Ok(PromoteLease {
146            key: key.to_owned(),
147            table: Arc::clone(self),
148        })
149    }
150}
151
152/// The node identity used to author the promote commit and the atproto record.
153#[derive(Clone, Debug)]
154pub struct PromoteAuthor {
155    /// atproto / git author name.
156    pub name: String,
157    /// atproto / git author email (or PDS account DID).
158    pub email: String,
159}
160
161/// Advance the atproto pointer record for `repo`/`worktree` to `commit_oid`.
162///
163/// This is the PDS-side of the saga. It is a `putRecord` to the model-pointer
164/// collection. The atproto substrate (#355/#410) owns the actual HTTPS client;
165/// until that lands, this is a stub that logs and returns `Ok`. The signature
166/// is fixed now so the promote path does not change shape when the real client
167/// is wired in — only the body of this function changes.
168///
169/// **Idempotent:** `putRecord` is last-writer-wins on the record `rkey`, so a
170/// retry after a crash simply overwrites with the same (or newer) OID.
171async fn advance_pointer(
172    _repo: &str,
173    _worktree: &str,
174    commit_oid: &str,
175    _author: &PromoteAuthor,
176) -> Result<(), String> {
177    // TODO(atproto, #355/#410): replace with a real PDS putRecord call to the
178    // model-pointer collection. The record shape is:
179    //   { "$type": "ai.hyprstream.modelPointer", "head": <commit_oid>, ... }
180    // Until the atproto substrate client lands, log and succeed — the local
181    // commit is durable and the pointer is advisory.
182    info!(
183        commit_oid,
184        "promote: atproto pointer update stubbed (substrate #355/#410 pending); local commit is durable"
185    );
186    Ok(())
187}
188
189/// Run the promote saga for a single worktree.
190///
191/// `repo`/`worktree` identify the layer; `wt` is the worktree-scoped registry
192/// client (curried `repo(id).worktree(name)`) whose `stage_all` / `commit`
193/// verbs perform the local snapshot; `author` is the commit + atproto-record
194/// identity; `lease_table` enforces single-writer-per-layer for this process.
195///
196/// # Determinism
197///
198/// Two nodes promoting byte-identical upper-layer content produce identical
199/// commit OIDs, because `stageAll` + `commit` reduce to `git add -A` +
200/// `git commit` over a deterministic index, and git commit OIDs are a pure
201/// function of (tree, parents, author, committer, message). The
202/// [`PromoteAuthor`] must therefore be a stable identity, not a per-call
203/// ephemeral — the caller is responsible for threading the same author across
204/// competing promotes (the registry service derives it from the verified
205/// `Subject`).
206///
207/// # Errors
208///
209/// - [`PromoteError::LeaseHeld`]: another promoter on this node holds the
210///   layer's lease.
211/// - [`PromoteError::LocalCommit`]: the stage/commit RPC failed; nothing was
212///   committed.
213/// - [`PromoteError::PointerStale`]: the local commit succeeded but the PDS
214///   write failed. The content is committed; the next promote advances the
215///   pointer. The caller should surface this as a warning, not a hard failure.
216pub async fn promote(
217    repo: &str,
218    worktree: &str,
219    wt: &WorktreeClient,
220    author: &PromoteAuthor,
221    lease_table: &Arc<PromoteLeaseTable>,
222) -> Result<PromoteOutcome, PromoteError> {
223    let lease_key = format!("{repo}/{worktree}");
224    let _lease = lease_table.acquire(&lease_key)?;
225
226    // Phase 1: local snapshot (deterministic). stageAll + commit.
227    wt.stage_all()
228        .await
229        .map_err(|e| PromoteError::LocalCommit(format!("stageAll: {e}")))?;
230    let commit_oid = wt
231        .commit_with_author(&CommitWithAuthorRequest {
232            message: commit_message(repo, worktree),
233            author_name: author.name.clone(),
234            author_email: author.email.clone(),
235        })
236        .await
237        .map_err(|e| PromoteError::LocalCommit(format!("commit: {e}")))?;
238
239    info!(
240        repo,
241        worktree, commit_oid, "promote: local snapshot committed"
242    );
243
244    // Phase 2: advance the atproto pointer (eventual consistency). A failure
245    // here does NOT roll back the local commit — see the module-level note.
246    let pointer_advanced = match advance_pointer(repo, worktree, &commit_oid, author).await {
247        Ok(()) => true,
248        Err(e) => {
249            warn!(
250                repo, worktree, commit_oid, error = %e,
251                "promote: atproto pointer update failed; content committed, pointer stale"
252            );
253            return Err(PromoteError::PointerStale(e));
254        }
255    };
256
257    Ok(PromoteOutcome {
258        commit_oid,
259        pointer_advanced,
260    })
261}
262
263/// Build a deterministic, human-readable commit message for a promote.
264///
265/// The message is stable for a given (repo, worktree) pair so that two nodes
266/// promoting the same content produce identical commit metadata (and therefore
267/// identical OIDs, modulo timestamp — git folds the committer timestamp into
268/// the OID, so true cross-node determinism requires the registry service to
269/// pin the timestamp, which it does via `commitWithAuthor`). The *message* is
270/// deterministic regardless.
271fn commit_message(repo: &str, worktree: &str) -> String {
272    format!("promote: {repo}/{worktree}\n\nSnapshot node-local upper layer into registry.\n\nGenerated by hyprstream promote (#394).")
273}
274
275#[cfg(test)]
276#[allow(clippy::unwrap_used)]
277mod tests {
278    use super::*;
279
280    #[test]
281    fn lease_acquire_and_release() {
282        let table = Arc::new(PromoteLeaseTable::new());
283        let lease = table.acquire("repo/wt").unwrap();
284        // Second acquire on the same key fails.
285        assert!(matches!(
286            table.acquire("repo/wt"),
287            Err(PromoteError::LeaseHeld(_))
288        ));
289        // Different key is fine.
290        let _lease2 = table.acquire("repo/other").unwrap();
291        // Dropping the first releases it.
292        drop(lease);
293        let _lease3 = table.acquire("repo/wt").unwrap();
294    }
295
296    #[test]
297    fn commit_message_is_stable() {
298        let a = commit_message("foo", "main");
299        let b = commit_message("foo", "main");
300        assert_eq!(a, b);
301        assert!(a.contains("foo/main"));
302        assert!(a.contains("#394"));
303    }
304
305    #[tokio::test]
306    async fn advance_pointer_stub_succeeds() {
307        // Until the atproto substrate lands, the stub always succeeds — this
308        // test pins that contract so wiring the real client is a body-only
309        // change.
310        let author = PromoteAuthor {
311            name: "n".into(),
312            email: "e".into(),
313        };
314        advance_pointer("r", "w", "deadbeef", &author)
315            .await
316            .unwrap();
317    }
318}