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