Skip to main content

oak_core/
traits.rs

1use std::collections::HashMap;
2
3use crate::{
4    Blob, Branch, BranchStatus, ChunkInfo, Commit, FileChange, Hash, Manifest, ManifestEntry,
5    MetadataKey, Result, Tree, TreeEntry,
6};
7
8/// A working-tree stat-cache row: the blob hash a file produced the last time
9/// it was scanned, keyed (by the caller) on its path and validated by `(mtime_ns,
10/// ctime_ns, size)`. If a file's mtime, ctime, and size all match a cached row,
11/// the scan can reuse `blob_hash` instead of re-reading and re-hashing the file —
12/// the same trick git's index uses to keep `status` cheap on large trees.
13///
14/// `ctime_ns` (inode change time) is the guard against a forged `(mtime, size)`:
15/// any content write bumps ctime, and so does an mtime reset (`touch`, `utime`,
16/// a checkout), because the metadata-update syscall itself touches ctime — and
17/// ctime can't be set backwards from userspace. Without it, an edit that keeps
18/// the size and reuses an old mtime (same-second clock, rapid edits, explicit
19/// reset) looks unchanged and the change is silently dropped by status, diff,
20/// AND commit. `ctime_ns` is 0 on platforms with no POSIX ctime (e.g. Windows),
21/// where the hit check degrades to the previous `(mtime, size)` behavior.
22#[derive(Debug, Clone, PartialEq, Eq)]
23pub struct StatCacheEntry {
24    /// Modification time in nanoseconds since the Unix epoch.
25    pub mtime_ns: i64,
26    /// Inode change time (ctime) in nanoseconds since the Unix epoch, or 0 when
27    /// the platform can't report one.
28    pub ctime_ns: i64,
29    /// File size in bytes.
30    pub size: i64,
31    /// The blob hash this file content produced when last hashed.
32    pub blob_hash: Hash,
33}
34
35/// A deferred blob content producer for [`Repository::put_blob_sources`]:
36/// `read` is invoked exactly once — possibly on a worker thread — to obtain
37/// the bytes to store (e.g. by reading a file). Boxed so the trait stays
38/// object-safe.
39pub struct BlobSource {
40    /// Content size in bytes when known in advance (e.g. from the directory
41    /// walk's stat), letting a backend bound how much content it keeps in
42    /// flight at once. `None` is treated as "could be huge" and admitted with
43    /// the most conservative charge.
44    pub size_hint: Option<u64>,
45    /// Produces the content. Invoked exactly once.
46    pub read: Box<dyn FnOnce() -> Result<Vec<u8>> + Send>,
47}
48
49impl BlobSource {
50    pub fn new(
51        size_hint: Option<u64>,
52        read: impl FnOnce() -> Result<Vec<u8>> + Send + 'static,
53    ) -> Self {
54        Self {
55            size_hint,
56            read: Box::new(read),
57        }
58    }
59
60    /// Wrap content that's already in memory (its size hint is exact).
61    pub fn from_content(content: Vec<u8>) -> Self {
62        let size = content.len() as u64;
63        Self::new(Some(size), move || Ok(content))
64    }
65}
66
67/// Trait defining the storage interface for Oak repositories
68pub trait Repository: Send + Sync {
69    // Blob operations
70    fn store_blob(&self, blob: &Blob) -> Result<()>;
71    /// The hash this backend would assign `content` via [`Self::put_blob`],
72    /// computed without storing anything. Read-only paths (`oak status`,
73    /// `restore` previews) compare working files against manifest entries
74    /// with this; BLAKE3 by default, the git blob OID on the git backend.
75    fn hash_blob_content(&self, content: &[u8]) -> Hash {
76        crate::hash_bytes(content)
77    }
78    fn get_blob(&self, hash: &Hash) -> Result<Option<Blob>>;
79    fn has_blob(&self, hash: &Hash) -> Result<bool>;
80    /// [`Repository::has_blob`] for many hashes, in order. Backends override
81    /// it to answer a whole manifest's presence check with one prepared
82    /// statement instead of one round trip per entry.
83    fn has_blobs(&self, hashes: &[&Hash]) -> Result<Vec<bool>> {
84        hashes.iter().map(|hash| self.has_blob(hash)).collect()
85    }
86    fn get_blob_size(&self, hash: &Hash) -> Result<Option<u64>> {
87        Ok(self.get_blob(hash)?.map(|blob| blob.size))
88    }
89
90    // Manifest operations
91    fn store_manifest(&self, manifest: &Manifest) -> Result<()>;
92    fn get_manifest(&self, hash: &Hash) -> Result<Option<Manifest>>;
93
94    // Tree operations (content-addressed nested manifests).
95    //
96    // Defaults are intentionally inefficient — they emulate trees on top of the
97    // flat manifest tables so backends can opt in incrementally. SQLite/Postgres
98    // override these with native tree-table implementations; the git backend
99    // overrides them to use git's native tree objects.
100    fn store_tree(&self, tree: &Tree) -> Result<()> {
101        let _ = tree;
102        Err(crate::OakError::Unsupported {
103            backend: "default",
104            op: "store_tree",
105        })
106    }
107
108    fn get_tree(&self, hash: &Hash) -> Result<Option<Tree>> {
109        let _ = hash;
110        Err(crate::OakError::Unsupported {
111            backend: "default",
112            op: "get_tree",
113        })
114    }
115
116    fn has_tree(&self, hash: &Hash) -> Result<bool> {
117        Ok(self.get_tree(hash)?.is_some())
118    }
119
120    /// Build a nested tree from a flat list of entries and store every tree
121    /// object produced. Returns the root tree hash. Default impl uses
122    /// [`crate::build_tree`] and the per-tree `store_tree`.
123    fn put_tree(&self, entries: Vec<ManifestEntry>) -> Result<Hash> {
124        let built = crate::build_tree(&entries)?;
125        for tree in &built.trees {
126            self.store_tree(tree)?;
127        }
128        Ok(built.root_hash)
129    }
130
131    /// Walk the tree rooted at `root` and return its flat entry list.
132    fn walk_tree(&self, root: &Hash) -> Result<Vec<ManifestEntry>> {
133        let mut fetch = |h: &Hash| -> Result<Tree> {
134            self.get_tree(h)?
135                .ok_or_else(|| crate::OakError::ManifestNotFound(h.to_string()))
136        };
137        crate::flatten_tree(root, &mut fetch)
138    }
139
140    /// Resolve a `/`-separated path to a TreeEntry within the tree at `root`.
141    fn resolve_path_in_tree(&self, root: &Hash, path: &str) -> Result<Option<TreeEntry>> {
142        let mut fetch = |h: &Hash| -> Result<Tree> {
143            self.get_tree(h)?
144                .ok_or_else(|| crate::OakError::ManifestNotFound(h.to_string()))
145        };
146        crate::resolve_path(root, path, &mut fetch)
147    }
148
149    /// Return the hash of the subtree at `path` (must be a directory).
150    /// An empty `path` returns `Some(root)`.
151    fn subtree_at_path(&self, root: &Hash, path: &str) -> Result<Option<Hash>> {
152        let mut fetch = |h: &Hash| -> Result<Tree> {
153            self.get_tree(h)?
154                .ok_or_else(|| crate::OakError::ManifestNotFound(h.to_string()))
155        };
156        crate::subtree_at_path(root, path, &mut fetch)
157    }
158
159    // Branch operations
160    fn store_branch(&self, branch: &Branch) -> Result<()>;
161    fn get_branch(&self, name: &str) -> Result<Option<Branch>>;
162    fn list_branches(&self) -> Result<Vec<Branch>>;
163    /// Like [`Self::list_branches`], but one stored row whose metadata cannot
164    /// be decoded becomes an `Err(UnreadableBranch)` entry instead of failing
165    /// the whole listing (fb-118). Batch assessment uses this so a single
166    /// corrupt row cannot hide every other branch.
167    fn list_branches_isolated(
168        &self,
169    ) -> Result<Vec<std::result::Result<Branch, crate::UnreadableBranch>>> {
170        Ok(self.list_branches()?.into_iter().map(Ok).collect())
171    }
172    fn update_branch_status(&self, name: &str, status: BranchStatus) -> Result<()>;
173    /// Close a branch and optionally record an explicit close reason.
174    fn close_branch(&self, name: &str, close_reason: Option<crate::CloseReason>) -> Result<()> {
175        self.update_branch_status(name, BranchStatus::Closed)?;
176        if let Some(reason) = close_reason {
177            self.update_branch_close_reason(name, reason)?;
178        }
179        Ok(())
180    }
181    fn update_branch_close_reason(
182        &self,
183        name: &str,
184        close_reason: crate::CloseReason,
185    ) -> Result<()> {
186        let _ = (name, close_reason);
187        Err(crate::OakError::Unsupported {
188            backend: "default",
189            op: "update_branch_close_reason",
190        })
191    }
192    fn update_branch_description(&self, name: &str, description: &str) -> Result<()>;
193    /// Re-parent an existing branch (restacking it). Unlike `store_branch`,
194    /// which never touches an existing row, this overwrites `parent_branch`.
195    fn set_branch_parent(&self, name: &str, parent: Option<&str>) -> Result<()> {
196        let _ = (name, parent);
197        Err(crate::OakError::Unsupported {
198            backend: "default",
199            op: "set_branch_parent",
200        })
201    }
202    /// Record user-authored text separately from server/import metadata updates.
203    fn edit_branch_description(&self, name: &str, description: &str) -> Result<()> {
204        self.update_branch_description(name, description)
205    }
206    /// Capture before reading description text for publication. Backends without
207    /// local synchronization tracking return no token and do not acknowledge.
208    fn description_publication_generation(&self) -> Result<Option<i64>> {
209        Ok(None)
210    }
211    /// Acknowledge exact text and generation, without clearing a newer/ABA edit.
212    fn acknowledge_branch_description(
213        &self,
214        name: &str,
215        description: Option<&str>,
216        generation: Option<i64>,
217    ) -> Result<()> {
218        let _ = (name, description, generation);
219        Ok(())
220    }
221    fn rename_branch(&self, old_name: &str, new_name: &str) -> Result<()> {
222        let _ = (old_name, new_name);
223        Err(crate::OakError::Unsupported {
224            backend: "default",
225            op: "rename_branch",
226        })
227    }
228    /// Remove a branch row and its head pointer from local storage. Commits
229    /// authored on the branch are untouched — `commits.branch_name` is a soft
230    /// label. Deleting a branch that doesn't exist is a no-op.
231    fn delete_branch(&self, name: &str) -> Result<()> {
232        let _ = name;
233        Err(crate::OakError::Unsupported {
234            backend: "default",
235            op: "delete_branch",
236        })
237    }
238    fn get_branch_head(&self, name: &str) -> Result<Option<Hash>>;
239    fn set_branch_head(&self, name: &str, hash: &Hash) -> Result<()>;
240
241    /// Atomically close a remotely-merged branch, create the fresh current
242    /// branch, and point branch/HEAD metadata at `seed_head`.
243    ///
244    /// Default impl calls individual methods (not atomic across calls). SQLite
245    /// overrides with a true single-transaction impl.
246    fn reconcile_remote_merge_branch_state(
247        &self,
248        closed_branch: &str,
249        new_branch: &Branch,
250        seed_head: &Hash,
251    ) -> Result<()> {
252        self.update_branch_status(closed_branch, BranchStatus::Closed)?;
253        self.store_branch(new_branch)?;
254        self.set_branch_head(&new_branch.name, seed_head)?;
255        self.set_head(seed_head)?;
256        self.set_current_branch(&new_branch.name)
257    }
258
259    // Commit operations
260    fn store_commit(&self, commit: &Commit) -> Result<()>;
261    fn get_commit(&self, hash: &Hash) -> Result<Option<Commit>>;
262    fn has_commit(&self, hash: &Hash) -> Result<bool>;
263    fn get_commits_for_branch(&self, branch_name: &str) -> Result<Vec<Commit>>;
264    fn get_commits_since(&self, branch_name: &str, since: Option<&Hash>) -> Result<Vec<Commit>>;
265    fn get_all_commits(&self) -> Result<Vec<Commit>>;
266
267    /// Repair the commit row stored under `verified.hash` when its stored
268    /// fields don't reproduce that hash. `store_commit` keeps the first row it
269    /// sees, so a row written with a placeholder author and the client's
270    /// clock (older `oak merge` binaries did this for the server's squash
271    /// commit) would otherwise never self-verify.
272    ///
273    /// `verified` must itself reproduce its hash, and must carry the stored
274    /// row's parents and manifest: only the metadata fields (branch name,
275    /// author, message, timestamp) are rewritten, never graph edges, the
276    /// snapshot or file rows. Returns whether a row changed; a missing row
277    /// or one that already verifies is left alone.
278    fn repair_commit_fields(&self, verified: &Commit) -> Result<bool> {
279        let _ = verified;
280        Err(crate::OakError::Unsupported {
281            backend: "default",
282            op: "repair_commit_fields",
283        })
284    }
285
286    /// Fast negative check for "does any local commit claim this commit as its
287    /// merge parent?" SQLite backs this with an index on
288    /// `commits.merge_parent_hash`; the default implementation is only for
289    /// backends without a native query path.
290    fn merge_child_exists(&self, branch_head: &Hash) -> Result<bool> {
291        Ok(self
292            .get_all_commits()?
293            .iter()
294            .any(|c| c.merge_parent_hash.as_ref() == Some(branch_head)))
295    }
296
297    /// Number of commits authored directly on `branch_name` — rows whose
298    /// `branch_name` column equals this branch. In Oak's branch-per-session
299    /// model a feature branch is seeded at its parent's head with none of its
300    /// own commits; each `oak commit` adds one, and a squash-merge moves you
301    /// onto a fresh branch with zero again. So this count is exactly the
302    /// branch's local work not yet merged into its parent. Purely local — it
303    /// never consults the server. Defaults to counting
304    /// [`Repository::get_commits_for_branch`]; backends override it with a
305    /// cheaper `COUNT(*)`.
306    fn count_commits_for_branch(&self, branch_name: &str) -> Result<usize> {
307        Ok(self.get_commits_for_branch(branch_name)?.len())
308    }
309
310    // Metadata operations
311    fn get_metadata(&self, key: MetadataKey) -> Result<Option<String>>;
312    fn set_metadata(&self, key: MetadataKey, value: &str) -> Result<()>;
313    /// Write `value` only when `key` has no value yet; returns whether it was
314    /// written. Backends that can should make this a single atomic statement
315    /// so a concurrent writer's value is never overwritten.
316    fn insert_metadata_if_absent(&self, key: MetadataKey, value: &str) -> Result<bool> {
317        if self.get_metadata(key)?.is_some() {
318            return Ok(false);
319        }
320        self.set_metadata(key, value)?;
321        Ok(true)
322    }
323
324    // --- Working-tree stat cache ----------------------------------------------------
325    //
326    // Lets the CLI's working-dir scan skip re-reading + re-hashing files whose
327    // `(mtime, size)` are unchanged since the last scan. Purely a local
328    // working-tree optimization, so the default impls are no-ops: backends that
329    // don't materialize a working tree (or haven't opted in) simply re-hash every
330    // file as before. SQLite overrides these with a real `stat_cache` table.
331
332    /// Load the entire stat cache as a `path -> entry` map.
333    fn load_stat_cache(&self) -> Result<HashMap<String, StatCacheEntry>> {
334        Ok(HashMap::new())
335    }
336
337    /// Apply a batch of stat-cache changes: upsert `upserts` (path + entry) and
338    /// delete the paths in `removed`. Implementations should run this as one
339    /// transaction. An empty batch must be a no-op so an unchanged `oak status`
340    /// performs zero writes.
341    fn update_stat_cache(
342        &self,
343        upserts: &[(String, StatCacheEntry)],
344        removed: &[String],
345    ) -> Result<()> {
346        let _ = (upserts, removed);
347        Ok(())
348    }
349
350    // Chunk operations
351    fn store_chunk(&self, hash: &Hash, content: &[u8]) -> Result<()>;
352    fn get_chunk(&self, hash: &Hash) -> Result<Option<Vec<u8>>>;
353    fn has_chunk(&self, hash: &Hash) -> Result<bool>;
354    fn store_blob_chunks(&self, blob_hash: &Hash, chunks: &[ChunkInfo]) -> Result<()>;
355    fn get_blob_chunks(&self, blob_hash: &Hash) -> Result<Option<Vec<ChunkInfo>>>;
356
357    // --- Backend-aware "put" methods ------------------------------------------------
358    //
359    // These hash and store in one shot, returning the canonical hash assigned by the
360    // backend. SQLite/Postgres backends compute BLAKE3 (matches their storage primary
361    // key); the git backend writes the object via gix and returns the git OID, which
362    // is unrelated to the BLAKE3 a caller might have precomputed.
363    //
364    // Default impls preserve the existing two-step (Blob::new + store_blob) behavior
365    // for backends that haven't overridden them — that means the input data is
366    // BLAKE3-hashed even though it could be wasted work on backends that don't use
367    // BLAKE3. Backends that care about that cost should override.
368
369    /// Hash and store a blob's content. Returns the backend's canonical hash.
370    fn put_blob(&self, content: Vec<u8>) -> Result<Hash> {
371        let blob = Blob::new(content);
372        let hash = blob.hash.clone();
373        self.store_blob(&blob)?;
374        Ok(hash)
375    }
376
377    /// Hash and store many blobs, returning each source's canonical hash in
378    /// input order. Each source's `read` is invoked exactly once, possibly on
379    /// a worker thread, to obtain the bytes to store. Semantically identical
380    /// to a [`Repository::put_blob`] loop (which is the default impl), but it lets
381    /// a backend overlap producing one blob's content (e.g. reading a file)
382    /// with hashing/encoding/storing another's instead of forcing
383    /// all-produce-then-all-hash barriers — which is what makes a snapshot of
384    /// a few large files fast.
385    fn put_blob_sources(&self, sources: Vec<BlobSource>) -> Result<Vec<Hash>> {
386        sources
387            .into_iter()
388            .map(|source| self.put_blob((source.read)()?))
389            .collect()
390    }
391
392    /// Build and store a manifest from the given entries. Returns the backend's
393    /// canonical hash for the manifest (a tree OID on the git backend).
394    fn put_manifest(&self, entries: Vec<ManifestEntry>) -> Result<Hash> {
395        let manifest = Manifest::new(entries);
396        let hash = manifest.hash.clone();
397        self.store_manifest(&manifest)?;
398        Ok(hash)
399    }
400
401    /// Build and store a commit. Returns the backend's canonical commit hash.
402    ///
403    /// Note: the `branch_name` and `files` fields are part of Oak's commit model
404    /// but have no representation on the git backend (git commits know nothing
405    /// about branches and derive file lists from tree diffs). The git backend
406    /// will drop them on write.
407    #[allow(clippy::too_many_arguments)]
408    fn put_commit(
409        &self,
410        branch_name: String,
411        parent_hash: Option<Hash>,
412        merge_parent_hash: Option<Hash>,
413        manifest_hash: Hash,
414        author: String,
415        message: Option<String>,
416        _timestamp: chrono::DateTime<chrono::Utc>,
417        files: Vec<FileChange>,
418    ) -> Result<Hash> {
419        // Default impl uses `Commit::new` which stamps `Utc::now()` and includes it
420        // in the BLAKE3 derivation — so the supplied `_timestamp` is dropped. That's
421        // fine for SQLite's existing callers (they compute "now" themselves and don't
422        // depend on bit-for-bit timestamp preservation). Backends that need to honor
423        // the supplied timestamp (git) should override this method.
424        let commit = Commit::new(
425            branch_name,
426            parent_hash,
427            merge_parent_hash,
428            manifest_hash,
429            author,
430            message,
431            files,
432        )?;
433        let hash = commit.hash.clone();
434        self.store_commit(&commit)?;
435        Ok(hash)
436    }
437
438    /// Build/store a manifest, create a commit for it, and advance the branch
439    /// head plus legacy HEAD to that commit. Backends that can transactionally
440    /// publish the whole transition should override this method.
441    #[allow(clippy::too_many_arguments)]
442    fn put_commit_and_advance_refs(
443        &self,
444        branch_name: String,
445        parent_hash: Option<Hash>,
446        merge_parent_hash: Option<Hash>,
447        entries: Vec<ManifestEntry>,
448        author: String,
449        message: Option<String>,
450        timestamp: chrono::DateTime<chrono::Utc>,
451        files: Vec<FileChange>,
452    ) -> Result<Hash> {
453        let manifest_hash = self.put_manifest(entries)?;
454        let commit_hash = self.put_commit(
455            branch_name.clone(),
456            parent_hash,
457            merge_parent_hash,
458            manifest_hash,
459            author,
460            message,
461            timestamp,
462            files,
463        )?;
464        self.set_branch_head(&branch_name, &commit_hash)?;
465        self.set_head(&commit_hash)?;
466        Ok(commit_hash)
467    }
468
469    /// [`Self::put_commit_and_advance_refs`] for a snapshot that already
470    /// exists as trees — a tree-level merge's result — so the whole tree is
471    /// never rebuilt from a flat entry list. `root` is the commit's root
472    /// tree; `trees` are the ones not stored yet (every other tree under
473    /// `root` must already be). Backends that can publish the whole
474    /// transition in one transaction should override this method.
475    #[allow(clippy::too_many_arguments)]
476    fn put_tree_commit_and_advance_refs(
477        &self,
478        branch_name: String,
479        parent_hash: Option<Hash>,
480        merge_parent_hash: Option<Hash>,
481        root: Hash,
482        trees: &[Tree],
483        author: String,
484        message: Option<String>,
485        timestamp: chrono::DateTime<chrono::Utc>,
486        files: Vec<FileChange>,
487    ) -> Result<Hash> {
488        for tree in trees {
489            self.store_tree(tree)?;
490        }
491        let commit_hash = self.put_commit(
492            branch_name.clone(),
493            parent_hash,
494            merge_parent_hash,
495            root,
496            author,
497            message,
498            timestamp,
499            files,
500        )?;
501        self.set_branch_head(&branch_name, &commit_hash)?;
502        self.set_head(&commit_hash)?;
503        Ok(commit_hash)
504    }
505
506    // Head operations (convenience methods)
507    fn get_head(&self) -> Result<Option<Hash>> {
508        self.get_metadata(MetadataKey::Head)
509            .map(|opt| opt.map(Hash))
510    }
511
512    fn set_head(&self, hash: &Hash) -> Result<()> {
513        self.set_metadata(MetadataKey::Head, hash.as_str())
514    }
515
516    // Remote operations
517    fn get_remote_url(&self) -> Result<Option<String>> {
518        self.get_metadata(MetadataKey::RemoteUrl)
519    }
520
521    // Current branch convenience.
522    //
523    // The detached-HEAD state is recorded by writing an empty string into the
524    // CurrentBranch metadata (see `oak switch -d` / `oak checkout`). All
525    // callers want to treat that the same as "no branch", so we collapse
526    // `Some("")` to `None` here at the read boundary instead of forcing
527    // every caller to remember the convention.
528    fn get_current_branch_name(&self) -> Result<Option<String>> {
529        Ok(self
530            .get_metadata(MetadataKey::CurrentBranch)?
531            .filter(|s| !s.is_empty()))
532    }
533
534    fn set_current_branch(&self, name: &str) -> Result<()> {
535        self.set_metadata(MetadataKey::CurrentBranch, name)
536    }
537}