Skip to main content

nb_api/transaction/
commit.rs

1use std::collections::HashSet;
2use std::fs::OpenOptions;
3use std::path::{Path, PathBuf};
4
5use crate::error::NbError;
6use crate::gate;
7use crate::git;
8use crate::types::{CommitOutcome, OpOutcome};
9
10use super::apply::{OpMeta, PlanEffects, validate_and_apply_virtual};
11use super::index::{
12    PendingIndexEdit, acquire_index_lock, apply_index_edits, index_id_on_disk,
13    index_rel_for_folder, is_index_rel, numeric_selector, reap_stale_index_lock,
14    split_folder_basename,
15};
16use super::plan::annotate_plan_index;
17use super::virtual_tree::{
18    VirtualNode, VirtualTree, normalize_rel, parent_path, refuse_symlink_ancestors,
19};
20
21use super::plan::Transaction;
22
23impl Transaction {
24    /// Validate-all, apply-all, at most one Git checkpoint.
25    pub async fn commit(self) -> Result<CommitOutcome, NbError> {
26        // Resolve root without invoking `nb` when possible (avoids nb
27        // auto-checkpoint clearing dirty state before the baseline check).
28        let notebook_root = self
29            .client
30            .show_notebook_path_unguarded(Some(&self.notebook))
31            .await?;
32        let gate_key = gate::git_common_dir_realpath(&notebook_root)?;
33        let _hold = gate::acquire_notebook(gate_key, self.gate_timeout, false).await?;
34
35        // A crashed writer may leave its `.nb-api-index.lock` behind; an
36        // untracked lock file reads as dirty, so reap a stale one first.
37        reap_stale_index_lock(&notebook_root, self.gate_timeout);
38
39        if git::notebook_is_dirty(&notebook_root)? {
40            return Err(NbError::DirtyBaseline {
41                guidance: "commit or clean the notebook worktree/index before Transaction::commit"
42                    .into(),
43            });
44        }
45
46        let pre_revision = git::notebook_head(&notebook_root)?;
47        if self.plan.is_empty() {
48            return Ok(CommitOutcome {
49                commit_created: false,
50                revision_id: None,
51                pre_revision,
52                ops: Vec::new(),
53            });
54        }
55
56        let ignored_existing: HashSet<String> = git::list_ignored_paths(&notebook_root)?
57            .into_iter()
58            .map(|p| normalize_rel(&p))
59            .collect();
60        let mut tree = VirtualTree::from_disk(&notebook_root)?;
61        let mut op_meta: Vec<OpMeta> = Vec::with_capacity(self.plan.len());
62        let mut effects = PlanEffects::default();
63        // Disk keys at snapshot time: materialize refuses a planned create
64        // that appears on disk afterwards (external same-path race).
65        let snapshot_keys: HashSet<String> = tree.nodes.keys().cloned().collect();
66
67        for (index, op) in self.plan.iter().enumerate() {
68            match validate_and_apply_virtual(
69                &self.notebook,
70                &notebook_root,
71                &mut tree,
72                &ignored_existing,
73                op,
74                index,
75                &mut effects,
76            ) {
77                Ok(meta) => op_meta.push(meta),
78                Err(err) => {
79                    return Err(annotate_plan_index(err, index as u32));
80                }
81            }
82        }
83
84        #[cfg(feature = "testing")]
85        if std::env::var_os("NB_API_SIMULATE_EXTERNAL_WRITER").is_some() {
86            // Deterministic stand-in for an external `nb add` racing our
87            // snapshot: create AND commit a note this transaction knows
88            // nothing about. Our commit must preserve it (file + index line).
89            simulate_external_writer(&notebook_root)?;
90        }
91
92        // Disk baseline before materialize (for rollback of new owned outputs).
93        // Virtual tree already includes planned ops; disk is still pre-apply.
94        let baseline_on_disk: HashSet<String> = {
95            let mut s: HashSet<String> = git::list_notebook_paths(&notebook_root)?
96                .into_iter()
97                .map(|p| normalize_rel(&p))
98                .collect();
99            s.extend(ignored_existing.iter().cloned());
100            s
101        };
102
103        // Force-stage every final file path so ignore rules cannot drop
104        // transaction-owned outputs (new ignored names, `.gitkeep`, etc.).
105        // `.index` files are applied post-materialize (fresh read under the
106        // index lock) but staged by the same checkpoint, so list them too.
107        let mut force_paths: Vec<String> = tree
108            .nodes
109            .iter()
110            .filter_map(|(p, n)| match n {
111                VirtualNode::File(_) => Some(p.clone()),
112                VirtualNode::Folder => None,
113            })
114            .collect();
115        for meta in &op_meta {
116            for edit in &meta.index_edits {
117                if !force_paths.iter().any(|p| p == &edit.file_rel) {
118                    force_paths.push(edit.file_rel.clone());
119                }
120            }
121        }
122
123        // Directories that already exist before materialize must never be
124        // pruned during rollback (including empty ignored parents).
125        let baseline_dirs = existing_dirs_under(&notebook_root);
126
127        // Materialize non-index files, apply `.index` edits from fresh
128        // on-disk content under `.nb-api-index.lock` (released before git
129        // staging — never held across `git add`/`commit`), then checkpoint.
130        // The lock serializes nb-api writers only; external `nb` writers are
131        // covered by O_APPEND plus post-write selector derivation.
132        let apply_result = async {
133            materialize_tree(&notebook_root, &tree, &effects, &snapshot_keys)?;
134            let mut pending: Vec<(u32, PendingIndexEdit)> = Vec::new();
135            for (i, meta) in op_meta.iter().enumerate() {
136                for edit in &meta.index_edits {
137                    pending.push((i as u32, edit.clone()));
138                }
139            }
140            let placements = if pending.is_empty() {
141                Vec::new()
142            } else {
143                let _lock = acquire_index_lock(&notebook_root, self.gate_timeout).await?;
144                let placements = apply_index_edits(&notebook_root, &pending, self.gate_timeout)?;
145                drop(_lock);
146                placements
147            };
148            let created = git::notebook_commit_all(
149                &notebook_root,
150                &format!("nb-api transaction ({} ops)", self.plan.len()),
151                &force_paths,
152            )?;
153            Ok::<_, NbError>((created, placements))
154        }
155        .await;
156
157        match apply_result {
158            Ok((created, placements)) => {
159                let revision_id = if created {
160                    match git::notebook_head(&notebook_root) {
161                        Ok(head) => Some(head),
162                        Err(_) => {
163                            return Err(NbError::IndeterminateCommit {
164                                pre_revision,
165                                post_revision_observed: None,
166                                guidance: "git commit may have succeeded but HEAD could not be re-read; do not retry blindly".into(),
167                            });
168                        }
169                    }
170                } else {
171                    None
172                };
173                let ops = op_meta
174                    .into_iter()
175                    .enumerate()
176                    .map(|(i, meta)| {
177                        // Creates/moves/deletes carry post-write placements:
178                        // selector becomes the numeric `<folder>/<id>` form.
179                        // A cross-folder move records both a blank (source)
180                        // and an append (destination); the destination
181                        // placement is last, so take the last match.
182                        // All other ops keep the echoed target selector and
183                        // gain a numeric id when the path is indexed.
184                        let (selector, numeric_id) =
185                            match placements.iter().rev().find(|p| p.op_index == i as u32) {
186                                Some(p) => (
187                                    Some(numeric_selector(&self.notebook, &p.folder, p.id)),
188                                    Some(p.id),
189                                ),
190                                None => (
191                                    meta.selector,
192                                    meta.path
193                                        .as_deref()
194                                        .and_then(|p| index_id_on_disk(&notebook_root, p)),
195                                ),
196                            };
197                        OpOutcome {
198                            index: i as u32,
199                            path: meta.path,
200                            selector,
201                            numeric_id,
202                            noop: meta.noop,
203                            fingerprint: meta.fingerprint,
204                        }
205                    })
206                    .collect();
207                Ok(CommitOutcome {
208                    commit_created: created,
209                    revision_id,
210                    pre_revision,
211                    ops,
212                })
213            }
214            Err(err) => {
215                let post = git::notebook_head(&notebook_root).ok();
216                if post.as_deref().is_some_and(|h| h != pre_revision.as_str()) {
217                    return Err(NbError::IndeterminateCommit {
218                        pre_revision,
219                        post_revision_observed: post,
220                        guidance: "checkpoint may have completed; re-read HEAD/status and do not retry the same plan blindly".into(),
221                    });
222                }
223                // Owned outputs that did not exist at baseline must be removed
224                // even when ignored (git clean -fd keeps ignored files).
225                // Baseline directories are never owned outputs: pruning one
226                // would `remove_dir_all` a pre-existing folder.
227                let owned_new: Vec<String> = force_paths
228                    .into_iter()
229                    .filter(|p| !baseline_on_disk.contains(p))
230                    .filter(|p| !baseline_dirs.contains(p))
231                    .collect();
232                match try_restore(&notebook_root, &pre_revision, &owned_new, &baseline_dirs) {
233                    Ok(()) => Err(err),
234                    Err(recovery) => Err(recovery),
235                }
236            }
237        }
238    }
239}
240
241/// All directory paths under the notebook root before materialize (relative,
242/// `/`-separated). Used so rollback never deletes pre-existing dirs.
243fn existing_dirs_under(notebook_root: &Path) -> HashSet<String> {
244    let mut dirs = HashSet::new();
245    fn walk(base: &Path, rel: &Path, out: &mut HashSet<String>) {
246        let entries = match std::fs::read_dir(base) {
247            Ok(e) => e,
248            Err(_) => return,
249        };
250        for entry in entries.flatten() {
251            let name = entry.file_name();
252            if name == ".git" {
253                continue;
254            }
255            let Ok(ft) = entry.file_type() else {
256                continue;
257            };
258            // Do not follow symlinks.
259            if ft.is_symlink() || !ft.is_dir() {
260                continue;
261            }
262            let child_rel = if rel.as_os_str().is_empty() {
263                PathBuf::from(&name)
264            } else {
265                rel.join(&name)
266            };
267            let key = child_rel.to_string_lossy().replace('\\', "/");
268            out.insert(key);
269            walk(&entry.path(), &child_rel, out);
270        }
271    }
272    walk(notebook_root, Path::new(""), &mut dirs);
273    dirs
274}
275
276fn try_restore(
277    notebook_root: &Path,
278    pre_revision: &str,
279    remove_new_owned: &[String],
280    baseline_dirs: &HashSet<String>,
281) -> Result<(), NbError> {
282    if let Err(e) = git::notebook_reset_clean(notebook_root, pre_revision) {
283        let post = git::notebook_head(notebook_root).ok();
284        let status = git::notebook_status_porcelain(notebook_root).ok();
285        return Err(NbError::RecoveryRequired {
286            pre_revision: pre_revision.to_string(),
287            post_revision_observed: post,
288            status_observed: status,
289            preserved_paths: Some(remove_new_owned.to_vec()),
290            guidance: format!(
291                "cleanup after failed commit could not be verified; inspect HEAD/status before retry. underlying: {e}"
292            ),
293        });
294    }
295    // `git clean -fd` can remove empty untracked dirs (including ignored
296    // parents) once staged children are cleared by reset --hard. Restore any
297    // baseline directory that disappeared.
298    for d in baseline_dirs {
299        let abs = notebook_root.join(d);
300        if !abs.exists()
301            && let Err(e) = std::fs::create_dir_all(&abs)
302        {
303            return Err(NbError::RecoveryRequired {
304                pre_revision: pre_revision.to_string(),
305                post_revision_observed: git::notebook_head(notebook_root).ok(),
306                status_observed: git::notebook_status_porcelain(notebook_root).ok(),
307                preserved_paths: Some(vec![d.clone()]),
308                guidance: format!(
309                    "failed to restore baseline directory `{d}` after cleanup; do not retry blindly. underlying: {e}"
310                ),
311            });
312        }
313    }
314    // Explicitly delete transaction-owned outputs that reset/clean leave behind
315    // when they are Git-ignored untracked files.
316    let mut remaining = Vec::new();
317    for rel in remove_new_owned {
318        let abs = notebook_root.join(rel);
319        match std::fs::symlink_metadata(&abs) {
320            Ok(meta) if meta.file_type().is_symlink() || meta.is_file() => {
321                if let Err(e) = std::fs::remove_file(&abs) {
322                    remaining.push(format!("{rel} ({e})"));
323                }
324            }
325            Ok(meta) if meta.is_dir() => {
326                if let Err(e) = std::fs::remove_dir_all(&abs) {
327                    remaining.push(format!("{rel} ({e})"));
328                }
329            }
330            Ok(_) => {}
331            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
332            Err(e) => remaining.push(format!("{rel} ({e})")),
333        }
334        // Prune only empty parents that the transaction created — never a
335        // directory that existed at baseline (e.g. pre-existing ignored parent).
336        if let Some(parent) = parent_path(rel) {
337            let mut cur = parent;
338            loop {
339                if baseline_dirs.contains(&cur) {
340                    break;
341                }
342                let p = notebook_root.join(&cur);
343                match std::fs::remove_dir(&p) {
344                    Ok(()) => {}
345                    Err(_) => break,
346                }
347                match parent_path(&cur) {
348                    Some(next) => cur = next,
349                    None => break,
350                }
351            }
352        }
353    }
354    if !remaining.is_empty() {
355        return Err(NbError::RecoveryRequired {
356            pre_revision: pre_revision.to_string(),
357            post_revision_observed: git::notebook_head(notebook_root).ok(),
358            status_observed: git::notebook_status_porcelain(notebook_root).ok(),
359            preserved_paths: Some(remaining),
360            guidance: "failed to remove transaction-owned outputs after aborted commit; do not retry blindly".into(),
361        });
362    }
363    // Verify none of the new owned paths remain (including ignored).
364    let mut still_present = Vec::new();
365    for rel in remove_new_owned {
366        if notebook_root.join(rel).exists() {
367            still_present.push(rel.clone());
368        }
369    }
370    let head = match restore_verify_head(notebook_root) {
371        Ok(h) => h,
372        Err(e) => {
373            return Err(NbError::RecoveryRequired {
374                pre_revision: pre_revision.to_string(),
375                post_revision_observed: None,
376                status_observed: git::notebook_status_porcelain(notebook_root).ok(),
377                preserved_paths: if still_present.is_empty() {
378                    None
379                } else {
380                    Some(still_present)
381                },
382                guidance: format!(
383                    "cleanup ran but HEAD re-read failed during verification; do not retry blindly. underlying: {e}"
384                ),
385            });
386        }
387    };
388    let dirty = match restore_verify_dirty(notebook_root) {
389        Ok(d) => d,
390        Err(e) => {
391            return Err(NbError::RecoveryRequired {
392                pre_revision: pre_revision.to_string(),
393                post_revision_observed: Some(head),
394                status_observed: git::notebook_status_porcelain(notebook_root).ok(),
395                preserved_paths: if still_present.is_empty() {
396                    None
397                } else {
398                    Some(still_present)
399                },
400                guidance: format!(
401                    "cleanup ran but dirty-status check failed during verification; do not retry blindly. underlying: {e}"
402                ),
403            });
404        }
405    };
406    if head != pre_revision || dirty || !still_present.is_empty() {
407        return Err(NbError::RecoveryRequired {
408            pre_revision: pre_revision.to_string(),
409            post_revision_observed: Some(head),
410            status_observed: git::notebook_status_porcelain(notebook_root).ok(),
411            preserved_paths: if still_present.is_empty() {
412                None
413            } else {
414                Some(still_present)
415            },
416            guidance:
417                "cleanup ran but HEAD/status/owned-path verification failed; do not retry blindly"
418                    .into(),
419        });
420    }
421    Ok(())
422}
423
424/// HEAD observation used only in post-cleanup verification.
425fn restore_verify_head(notebook_root: &Path) -> Result<String, NbError> {
426    #[cfg(feature = "testing")]
427    if std::env::var_os("NB_API_FAIL_RESTORE_HEAD").is_some() {
428        return Err(NbError::CommandFailed {
429            command: "nb-api://fail-restore-head".into(),
430            stderr: "injected HEAD verify failure for rollback tests".into(),
431            exit_code: Some(1),
432        });
433    }
434    git::notebook_head(notebook_root)
435}
436
437/// Dirty-status observation used only in post-cleanup verification.
438fn restore_verify_dirty(notebook_root: &Path) -> Result<bool, NbError> {
439    #[cfg(feature = "testing")]
440    if std::env::var_os("NB_API_FAIL_RESTORE_DIRTY").is_some() {
441        return Err(NbError::CommandFailed {
442            command: "nb-api://fail-restore-dirty".into(),
443            stderr: "injected dirty-status verify failure for rollback tests".into(),
444            exit_code: Some(1),
445        });
446    }
447    git::notebook_is_dirty(notebook_root)
448}
449
450/// Deterministic stand-in for an external `nb add` racing our snapshot
451/// (testing only, behind `NB_API_SIMULATE_EXTERNAL_WRITER`): create AND
452/// commit a note plus its `.index` line that this transaction knows nothing
453/// about. The commit must preserve both.
454///
455/// `NB_API_SIMULATE_EXTERNAL_SAME_PATH=<rel>` makes the external writer take
456/// the given path instead (to test the same-path race: our commit must fail
457/// `PathCollision`, never overwrite).
458#[cfg(feature = "testing")]
459fn simulate_external_writer(notebook_root: &Path) -> Result<(), NbError> {
460    use std::io::Write as _;
461    let (folder, name) = match std::env::var("NB_API_SIMULATE_EXTERNAL_SAME_PATH") {
462        Ok(rel) => {
463            let (folder, basename) = split_folder_basename(&normalize_rel(&rel));
464            (folder, basename)
465        }
466        Err(_) => (String::new(), format!("external-{}.md", std::process::id())),
467    };
468    let rel = if folder.is_empty() {
469        name.clone()
470    } else {
471        format!("{folder}/{name}")
472    };
473    if !folder.is_empty() {
474        std::fs::create_dir_all(notebook_root.join(&folder)).map_err(|e| NbError::Io {
475            path: notebook_root.join(&folder),
476            source: e.into(),
477        })?;
478    }
479    std::fs::write(notebook_root.join(&rel), b"# External\n\nexternal body\n").map_err(|e| {
480        NbError::Io {
481            path: notebook_root.join(&rel),
482            source: e.into(),
483        }
484    })?;
485    let index_abs = notebook_root.join(index_rel_for_folder(&folder));
486    let mut f = OpenOptions::new()
487        .create(true)
488        .append(true)
489        .open(&index_abs)
490        .map_err(|e| NbError::Io {
491            path: index_abs.clone(),
492            source: e.into(),
493        })?;
494    writeln!(f, "{name}").map_err(|e| NbError::Io {
495        path: index_abs.clone(),
496        source: e.into(),
497    })?;
498    drop(f);
499    git::notebook_commit_all(
500        notebook_root,
501        "external writer",
502        &[rel, index_rel_for_folder(&folder)],
503    )?;
504    Ok(())
505}
506
507/// Write the plan's effects to disk.
508///
509/// ONLY paths recorded in `effects` are touched: files created after the
510/// snapshot by an external writer are never deleted, and files deleted
511/// externally are never resurrected. `.index` rels are skipped here (applied
512/// separately from fresh on-disk content under `.nb-api-index.lock`).
513///
514/// `snapshot_keys` are the tree keys at snapshot time. A `created` path that
515/// exists on disk now but was absent from the snapshot means an external
516/// writer created the same path after our collision validation — refuse with
517/// `PathCollision` instead of overwriting it (which would also leave
518/// ambiguous duplicate `.index` entries).
519fn materialize_tree(
520    root: &Path,
521    tree: &VirtualTree,
522    effects: &PlanEffects,
523    snapshot_keys: &HashSet<String>,
524) -> Result<(), NbError> {
525    // Preflight: no path may traverse an existing symlink ancestor (including
526    // ignored directory symlinks excluded from the virtual snapshot).
527    for rel in tree.nodes.keys() {
528        refuse_symlink_ancestors(root, rel)?;
529    }
530
531    // Remove ONLY plan delete/move sources that exist on disk as files.
532    let mut removed: Vec<&String> = effects.removed.iter().collect();
533    removed.sort();
534    removed.dedup();
535    for rel in removed {
536        let key = normalize_rel(rel);
537        let abs = root.join(&key);
538        let meta = match std::fs::symlink_metadata(&abs) {
539            Ok(m) => m,
540            Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
541            Err(e) => {
542                return Err(NbError::Io {
543                    path: abs,
544                    source: e.into(),
545                });
546            }
547        };
548        if meta.file_type().is_symlink() {
549            return Err(NbError::UnsupportedStructure {
550                reason: format!("refusing to materialize through symlink `{key}`"),
551            });
552        }
553        if meta.is_file() && !matches!(tree.nodes.get(&key), Some(VirtualNode::File(_))) {
554            std::fs::remove_file(&abs).map_err(|e| NbError::Io {
555                path: abs,
556                source: e.into(),
557            })?;
558        }
559    }
560    // Create ONLY plan folders.
561    let mut mkdirs: Vec<&String> = effects.mkdirs.iter().collect();
562    mkdirs.sort();
563    mkdirs.dedup();
564    for rel in mkdirs {
565        let key = normalize_rel(rel);
566        let abs = root.join(&key);
567        refuse_symlink_ancestors(root, &key)?;
568        std::fs::create_dir_all(&abs).map_err(|e| NbError::Io {
569            path: abs.clone(),
570            source: e.into(),
571        })?;
572    }
573    // Write ONLY plan-created/modified files (never `.index`).
574    let mut written: Vec<&String> = effects
575        .written
576        .iter()
577        .filter(|rel| !is_index_rel(rel))
578        .collect();
579    written.sort();
580    written.dedup();
581    let created: HashSet<&String> = effects.created.iter().collect();
582    for rel in written {
583        let key = normalize_rel(rel);
584        let created_contains = created.contains(rel);
585        let Some(VirtualNode::File(bytes)) = tree.nodes.get(&key) else {
586            return Err(NbError::ValidationError {
587                reason: format!("plan effect `{key}` has no file content"),
588                location: None,
589            });
590        };
591        let abs = root.join(&key);
592        // Never write through an existing symlink leaf or ancestor.
593        refuse_symlink_ancestors(root, &key)?;
594        if let Ok(meta) = std::fs::symlink_metadata(&abs) {
595            if meta.file_type().is_symlink() {
596                return Err(NbError::UnsupportedStructure {
597                    reason: format!("refusing to write through symlink `{key}`"),
598                });
599            }
600            // A planned create racing an external same-path create (file or
601            // directory appearing after the snapshot): refuse instead of
602            // overwriting the external note or failing obscurely on a dir.
603            if created_contains && !snapshot_keys.contains(&key) {
604                return Err(NbError::PathCollision {
605                    path: key,
606                    plan_index: None,
607                });
608            }
609        }
610        if let Some(parent) = abs.parent() {
611            std::fs::create_dir_all(parent).map_err(|e| NbError::Io {
612                path: parent.to_path_buf(),
613                source: e.into(),
614            })?;
615        }
616        std::fs::write(&abs, bytes).map_err(|e| NbError::Io {
617            path: abs,
618            source: e.into(),
619        })?;
620    }
621    Ok(())
622}