use crate::error::{OakError, Result};
use crate::hash::{hash_bytes, Hash};
use crate::{ChangeType, FileChange, FileMode};
use chrono::{DateTime, Utc};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum HashFormat {
#[default]
V1,
V2,
}
impl HashFormat {
pub fn from_metadata(value: Option<&str>) -> Result<Self> {
match value {
None | Some("v1") => Ok(HashFormat::V1),
Some("v2") => Ok(HashFormat::V2),
Some(other) => Err(OakError::Config(format!(
"unknown hash format {other:?} (this build understands v1 and v2)"
))),
}
}
pub fn as_str(&self) -> &'static str {
match self {
HashFormat::V1 => "v1",
HashFormat::V2 => "v2",
}
}
}
pub fn hash_blob(format: HashFormat, content: &[u8]) -> Hash {
domain_hash(format, b"oak-blob\0", content)
}
pub fn hash_chunk(format: HashFormat, content: &[u8]) -> Hash {
domain_hash(format, b"oak-chunk\0", content)
}
pub fn hash_tree(format: HashFormat, canonical_bytes: &[u8]) -> Hash {
domain_hash(format, b"oak-tree\0", canonical_bytes)
}
fn domain_hash(format: HashFormat, domain: &[u8], content: &[u8]) -> Hash {
match format {
HashFormat::V1 => hash_bytes(content),
HashFormat::V2 => {
let mut preimage = Vec::with_capacity(domain.len() + content.len());
preimage.extend_from_slice(domain);
preimage.extend_from_slice(content);
hash_bytes(&preimage)
}
}
}
#[derive(Clone, Copy)]
pub struct CommitFields<'a> {
pub branch_name: &'a str,
pub parent_hash: Option<&'a Hash>,
pub merge_parent_hash: Option<&'a Hash>,
pub manifest_hash: &'a Hash,
pub author: &'a str,
pub message: Option<&'a str>,
pub timestamp: &'a DateTime<Utc>,
pub files: &'a [FileChange],
}
pub fn hash_commit(format: HashFormat, f: &CommitFields) -> Hash {
match format {
HashFormat::V1 => {
let content = format!(
"{}\n{}\n{}\n{}\n{}\n{}\n{}",
f.branch_name,
f.parent_hash.map(|h| h.as_str()).unwrap_or_default(),
f.merge_parent_hash.map(|h| h.as_str()).unwrap_or_default(),
f.manifest_hash,
f.author,
f.message.unwrap_or_default(),
f.timestamp.to_rfc3339()
);
hash_bytes(content.as_bytes())
}
HashFormat::V2 => {
let mut p = Vec::new();
p.extend_from_slice(b"oak-commit\0");
field(&mut p, f.branch_name.as_bytes());
opt_field(&mut p, f.parent_hash.map(|h| h.as_str()));
opt_field(&mut p, f.merge_parent_hash.map(|h| h.as_str()));
field(&mut p, f.manifest_hash.as_str().as_bytes());
field(&mut p, f.author.as_bytes());
opt_field(&mut p, f.message);
field(&mut p, f.timestamp.to_rfc3339().as_bytes());
field(&mut p, f.files.len().to_string().as_bytes());
for c in f.files {
field(&mut p, c.path.as_bytes());
field(&mut p, change_type_str(c.change_type).as_bytes());
opt_field(&mut p, c.old_blob_hash.as_ref().map(|h| h.as_str()));
opt_field(&mut p, c.new_blob_hash.as_ref().map(|h| h.as_str()));
opt_field(&mut p, c.old_path.as_deref());
opt_field(&mut p, c.old_mode.map(mode_str));
opt_field(&mut p, c.new_mode.map(mode_str));
}
hash_bytes(&p)
}
}
}
pub fn hash_commit_v1_pre_merge_parent(f: &CommitFields) -> Hash {
let content = format!(
"{}\n{}\n{}\n{}\n{}\n{}",
f.branch_name,
f.parent_hash.map(|h| h.as_str()).unwrap_or_default(),
f.manifest_hash,
f.author,
f.message.unwrap_or_default(),
f.timestamp.to_rfc3339()
);
hash_bytes(content.as_bytes())
}
fn field(out: &mut Vec<u8>, bytes: &[u8]) {
out.extend_from_slice(bytes.len().to_string().as_bytes());
out.push(b':');
out.extend_from_slice(bytes);
}
fn opt_field(out: &mut Vec<u8>, value: Option<&str>) {
match value {
None => out.push(b'-'),
Some(v) => field(out, v.as_bytes()),
}
}
fn change_type_str(t: ChangeType) -> &'static str {
match t {
ChangeType::Added => "A",
ChangeType::Modified => "M",
ChangeType::Deleted => "D",
ChangeType::Renamed => "R",
}
}
fn mode_str(m: FileMode) -> &'static str {
match m {
FileMode::Regular => "regular",
FileMode::Executable => "executable",
FileMode::Symlink => "symlink",
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::hash::hash_string;
use crate::{Commit, FileMode, ManifestEntry, TreeEntry, TreeEntryKind};
use chrono::TimeZone;
fn fixed_timestamp() -> DateTime<Utc> {
Utc.with_ymd_and_hms(2024, 1, 2, 3, 4, 5).unwrap()
}
fn sample_files() -> Vec<FileChange> {
vec![FileChange {
path: "src/lib.rs".to_string(),
change_type: ChangeType::Modified,
old_blob_hash: Some(hash_string("old")),
new_blob_hash: Some(hash_string("new")),
old_path: None,
old_mode: Some(FileMode::Regular),
new_mode: Some(FileMode::Regular),
}]
}
const V1_EMPTY: &str = "af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262";
#[test]
fn v1_blob_chunk_tree_are_bare_blake3() {
for content in [&b""[..], b"hello world", b"\x00\x01\xff"] {
let expected = hash_bytes(content);
assert_eq!(hash_blob(HashFormat::V1, content), expected);
assert_eq!(hash_chunk(HashFormat::V1, content), expected);
assert_eq!(hash_tree(HashFormat::V1, content), expected);
}
}
#[test]
fn v1_empty_golden() {
assert_eq!(hash_blob(HashFormat::V1, b"").as_str(), V1_EMPTY);
assert_eq!(crate::Tree::empty_hash().as_str(), V1_EMPTY);
assert_eq!(crate::Blob::empty_hash().as_str(), V1_EMPTY);
assert_eq!(crate::Blob::empty().hash.as_str(), V1_EMPTY);
assert!(crate::Blob::is_empty_hash(&crate::Blob::empty_hash()));
assert!(!crate::Blob::is_empty_hash(&hash_blob(
HashFormat::V1,
b"not empty"
)));
}
#[test]
fn v1_blob_golden() {
assert_eq!(
hash_blob(HashFormat::V1, b"hello world").as_str(),
"d74981efa70a0c880b8d8c1985d075dbcbf679b99a5f9914e5aaf96b831a9e24"
);
}
#[test]
fn v1_tree_golden() {
let tree = crate::Tree::new(vec![
TreeEntry {
name: "a.txt".to_string(),
kind: TreeEntryKind::Blob,
hash: hash_string("a"),
mode: FileMode::Regular,
},
TreeEntry {
name: "sub".to_string(),
kind: TreeEntryKind::Tree,
hash: hash_string("sub"),
mode: FileMode::Regular,
},
])
.unwrap();
assert_eq!(
tree.hash.as_str(),
"26fa3b9ad707a970f25bb9821cde463e244307bfe8234a1237eed50a421e85ea"
);
assert_eq!(
hash_tree(HashFormat::V1, &tree.canonical_bytes()),
tree.hash
);
}
#[test]
fn v1_commit_matches_live_commit_path_and_golden() {
let manifest = hash_string("manifest");
let files = sample_files();
let commit = Commit::with_timestamp(
"main".to_string(),
None,
None,
manifest.clone(),
"tester".to_string(),
Some("a message".to_string()),
files.clone(),
fixed_timestamp(),
)
.unwrap();
let ts = fixed_timestamp();
let via_module = hash_commit(
HashFormat::V1,
&CommitFields {
branch_name: "main",
parent_hash: None,
merge_parent_hash: None,
manifest_hash: &manifest,
author: "tester",
message: Some("a message"),
timestamp: &ts,
files: &files,
},
);
assert_eq!(commit.hash, via_module);
assert_eq!(
commit.hash.as_str(),
"6b575aadf3ed7e96f242a521087baf9498a67e3b107ee6a2880ab321151912fb"
);
}
#[test]
fn v1_manifest_root_golden() {
let manifest = crate::Manifest::new(vec![ManifestEntry {
path: "dir/file.txt".to_string(),
blob_hash: hash_string("content"),
mode: FileMode::Regular,
}]);
assert_eq!(
manifest.hash.as_str(),
"863eb9a88032134f08722aa08b4aaa346d7408c17dbea4597957175bf907ab2f"
);
}
#[test]
fn v2_domains_separate_identical_bytes() {
for content in [&b""[..], b"same bytes"] {
let blob = hash_blob(HashFormat::V2, content);
let chunk = hash_chunk(HashFormat::V2, content);
let tree = hash_tree(HashFormat::V2, content);
assert_ne!(blob, chunk);
assert_ne!(blob, tree);
assert_ne!(chunk, tree);
let v1 = hash_bytes(content);
assert_ne!(blob, v1);
assert_ne!(chunk, v1);
assert_ne!(tree, v1);
}
}
#[test]
fn v2_empty_blob_differs_from_empty_tree() {
assert_ne!(
hash_blob(HashFormat::V2, b""),
hash_tree(HashFormat::V2, b"")
);
}
#[test]
fn v2_commit_includes_files() {
let manifest = hash_string("manifest");
let files = sample_files();
let ts = fixed_timestamp();
let base = CommitFields {
branch_name: "main",
parent_hash: None,
merge_parent_hash: None,
manifest_hash: &manifest,
author: "tester",
message: None,
timestamp: &ts,
files: &[],
};
let without = hash_commit(HashFormat::V2, &base);
let with = hash_commit(
HashFormat::V2,
&CommitFields {
files: &files,
..base
},
);
assert_ne!(without, with);
let v1_without = hash_commit(HashFormat::V1, &base);
let v1_with = hash_commit(
HashFormat::V1,
&CommitFields {
files: &files,
..base
},
);
assert_eq!(v1_without, v1_with);
}
#[test]
fn v2_none_and_empty_message_differ() {
let manifest = hash_string("manifest");
let ts = fixed_timestamp();
let base = CommitFields {
branch_name: "main",
parent_hash: None,
merge_parent_hash: None,
manifest_hash: &manifest,
author: "tester",
message: None,
timestamp: &ts,
files: &[],
};
let none = hash_commit(HashFormat::V2, &base);
let empty = hash_commit(
HashFormat::V2,
&CommitFields {
message: Some(""),
..base
},
);
assert_ne!(none, empty);
}
#[test]
fn v2_fields_cannot_shift_between_positions() {
let manifest = hash_string("manifest");
let ts = fixed_timestamp();
let a = hash_commit(
HashFormat::V2,
&CommitFields {
branch_name: "main",
parent_hash: None,
merge_parent_hash: None,
manifest_hash: &manifest,
author: "x\ny",
message: Some("z"),
timestamp: &ts,
files: &[],
},
);
let b = hash_commit(
HashFormat::V2,
&CommitFields {
branch_name: "main",
parent_hash: None,
merge_parent_hash: None,
manifest_hash: &manifest,
author: "x",
message: Some("y\nz"),
timestamp: &ts,
files: &[],
},
);
assert_ne!(a, b);
}
#[test]
fn rfc3339_timestamp_rendering_is_stable() {
use chrono::DateTime;
let render = |s: &str| {
DateTime::parse_from_rfc3339(s)
.unwrap()
.with_timezone(&Utc)
.to_rfc3339()
};
assert_eq!(
render("2024-01-02T03:04:05+00:00"),
"2024-01-02T03:04:05+00:00"
);
assert_eq!(
render("2026-06-27T04:33:39.250+00:00"),
"2026-06-27T04:33:39.250+00:00"
);
assert_eq!(
render("2026-06-27T04:33:39.965405+00:00"),
"2026-06-27T04:33:39.965405+00:00"
);
assert_eq!(
render("2026-06-27T04:33:39.123456789+00:00"),
"2026-06-27T04:33:39.123456789+00:00"
);
assert_eq!(
render("2026-06-27T04:33:39.965405+05:30"),
"2026-06-26T23:03:39.965405+00:00"
);
}
#[test]
fn v1_commit_timestamp_precision_golden() {
use chrono::DateTime;
let manifest = hash_string("manifest");
let parent = hash_string("parent");
let commit_hash = |rfc: &str| {
let ts = DateTime::parse_from_rfc3339(rfc)
.unwrap()
.with_timezone(&Utc);
hash_commit(
HashFormat::V1,
&CommitFields {
branch_name: "main",
parent_hash: Some(&parent),
merge_parent_hash: None,
manifest_hash: &manifest,
author: "Zach <zach@oak.space>",
message: Some("subject\n\nbody"),
timestamp: &ts,
files: &[],
},
)
.0
};
for (rfc, expected) in [
(
"2024-01-02T03:04:05+00:00",
"e4fe01caceba2c8fb905de9477af391e9c9ac50195f48025e922f70608868ae0",
),
(
"2026-06-27T04:33:39.250+00:00",
"7a667e00cf11830eb56b2014827566dd92fd379be836f49cbcb24939dc367081",
),
(
"2026-06-27T04:33:39.965405+00:00",
"ed0e25d76ab3af99c91b19a0b96e7e3ae8e972c92a3bf8106b392813f29506a9",
),
(
"2026-06-27T04:33:39.123456789+00:00",
"bd691a79fccc1a680c59ab7fdeb06d0506af828d62703605d35e72cf55798070",
),
(
"2026-06-27T04:33:39.965405+05:30",
"5154b359afbae5b4a92afcb076867baf531ce6d19c3cc3ebe4ee15f159575065",
),
] {
assert_eq!(commit_hash(rfc), expected, "commit hash drift for {rfc}");
}
}
#[test]
fn v1_merge_commit_golden() {
use chrono::DateTime;
let manifest = hash_string("manifest");
let parent = hash_string("parent");
let merge = hash_string("merge");
let ts = DateTime::parse_from_rfc3339("2026-06-27T04:33:39.965405+00:00")
.unwrap()
.with_timezone(&Utc);
let h = hash_commit(
HashFormat::V1,
&CommitFields {
branch_name: "main",
parent_hash: Some(&parent),
merge_parent_hash: Some(&merge),
manifest_hash: &manifest,
author: "tester",
message: Some("merge"),
timestamp: &ts,
files: &[],
},
);
assert_eq!(
h.as_str(),
"1375c4cb565921d18c3a06c5b6366ba4aa802c71d228cc4e32f750b1f5d4c99d"
);
}
#[test]
fn format_flag_defaults_to_v1_and_rejects_unknown() {
assert_eq!(HashFormat::from_metadata(None).unwrap(), HashFormat::V1);
assert_eq!(
HashFormat::from_metadata(Some("v1")).unwrap(),
HashFormat::V1
);
assert_eq!(
HashFormat::from_metadata(Some("v2")).unwrap(),
HashFormat::V2
);
assert!(HashFormat::from_metadata(Some("v3")).is_err());
assert_eq!(HashFormat::default(), HashFormat::V1);
}
}