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}