use std::collections::BTreeSet;
use std::fmt;
use std::str::FromStr;
use gix::objs::tree::EntryKind;
use indexmap::IndexMap;
use serde::{Deserialize, Serialize};
use crate::plan::TargetPath;
const SNAPSHOT_FORMAT: u32 = 1;
pub(crate) const SNAPSHOT_REF_PREFIX: &str = "refs/toha/snapshots/";
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct SnapshotId(u128);
const CROCKFORD: &[u8; 32] = b"0123456789ABCDEFGHJKMNPQRSTVWXYZ";
const ULID_LEN: usize = 26;
const MIN_PREFIX: usize = 6;
impl SnapshotId {
pub fn from_parts(timestamp_ms: u64, entropy: [u8; 10]) -> Self {
let ts = u128::from(timestamp_ms & 0x0000_FFFF_FFFF_FFFF);
let mut rand = 0u128;
for byte in entropy {
rand = (rand << 8) | u128::from(byte);
}
Self((ts << 80) | rand)
}
pub fn parse_prefix(text: &str) -> Result<String, SnapshotError> {
let trimmed = text.trim();
if trimmed.len() < MIN_PREFIX || trimmed.len() > ULID_LEN {
return Err(SnapshotError::Prefix(trimmed.to_owned()));
}
let mut out = String::with_capacity(trimmed.len());
for ch in trimmed.chars() {
out.push(char::from(
canonical_digit(ch).ok_or_else(|| SnapshotError::Prefix(trimmed.to_owned()))?,
));
}
Ok(out)
}
pub fn has_prefix(&self, prefix: &str) -> bool {
self.to_string().starts_with(prefix)
}
pub fn generate() -> Self {
let millis = jiff::Timestamp::now().as_millisecond().max(0) as u64;
let mut entropy = [0u8; 10];
getrandom::fill(&mut entropy).expect("system entropy");
Self::from_parts(millis, entropy)
}
}
fn canonical_digit(ch: char) -> Option<u8> {
let upper = ch.to_ascii_uppercase();
match upper {
'I' | 'L' => Some(b'1'),
'O' => Some(b'0'),
_ if CROCKFORD.contains(&(upper as u8)) => Some(upper as u8),
_ => None,
}
}
fn digit_value(ch: char) -> Option<u32> {
let canon = canonical_digit(ch)?;
CROCKFORD.iter().position(|&d| d == canon).map(|p| p as u32)
}
impl fmt::Display for SnapshotId {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let mut buf = [0u8; ULID_LEN];
let mut value = self.0;
for slot in buf.iter_mut().rev() {
*slot = CROCKFORD[(value & 0x1f) as usize];
value >>= 5;
}
f.write_str(std::str::from_utf8(&buf).expect("crockford is ascii"))
}
}
impl FromStr for SnapshotId {
type Err = SnapshotError;
fn from_str(text: &str) -> Result<Self, Self::Err> {
if text.len() != ULID_LEN {
return Err(SnapshotError::Id(text.to_owned()));
}
let mut value: u128 = 0;
for ch in text.chars() {
let digit = digit_value(ch).ok_or_else(|| SnapshotError::Id(text.to_owned()))?;
value = (value << 5) | u128::from(digit);
}
let first = digit_value(text.chars().next().expect("length checked")).expect("valid digit");
if first > 7 {
return Err(SnapshotError::Id(text.to_owned()));
}
Ok(Self(value))
}
}
impl Serialize for SnapshotId {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.serialize_str(&self.to_string())
}
}
impl<'de> Deserialize<'de> for SnapshotId {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let text = String::deserialize(deserializer)?;
text.parse().map_err(serde::de::Error::custom)
}
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct RepoPath(String);
impl RepoPath {
pub fn root() -> Self {
Self(".".to_owned())
}
pub fn parse(text: &str) -> Result<Self, SnapshotError> {
if text.is_empty() || text == "." {
return Ok(Self::root());
}
TargetPath::parse(text).map_err(|message| SnapshotError::Path {
path: text.to_owned(),
message,
})?;
Ok(Self(text.replace('\\', "/")))
}
pub fn is_root(&self) -> bool {
self.0 == "."
}
pub fn as_str(&self) -> &str {
&self.0
}
}
impl fmt::Display for RepoPath {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.0)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CommitId(String);
impl CommitId {
pub fn parse(text: &str) -> Result<Self, SnapshotError> {
let ok = text.len() == 40 && text.bytes().all(|b| b.is_ascii_hexdigit());
if ok {
Ok(Self(text.to_ascii_lowercase()))
} else {
Err(SnapshotError::Commit(text.to_owned()))
}
}
pub fn as_str(&self) -> &str {
&self.0
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ContentDigest(String);
impl ContentDigest {
pub fn parse(text: &str) -> Result<Self, SnapshotError> {
if text.len() == 64
&& text
.bytes()
.all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
{
Ok(Self(text.to_owned()))
} else {
Err(SnapshotError::ContentDigest(text.to_owned()))
}
}
pub fn as_str(&self) -> &str {
&self.0
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Revision {
Commit(CommitId),
Content(ContentDigest),
Unversioned,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProjectPoint {
commit: CommitId,
branch: Option<String>,
}
impl ProjectPoint {
pub fn new(commit: CommitId, branch: Option<String>) -> Self {
Self { commit, branch }
}
pub fn commit(&self) -> &CommitId {
&self.commit
}
pub fn branch(&self) -> Option<&str> {
self.branch.as_deref()
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FrozenNow(jiff::Zoned);
impl FrozenNow {
pub fn new(instant: jiff::Zoned) -> Self {
Self(instant)
}
pub fn parse(text: &str) -> Result<Self, SnapshotError> {
text.parse::<jiff::Zoned>()
.map(Self)
.map_err(|_| SnapshotError::Instant(text.to_owned()))
}
pub fn get(&self) -> &jiff::Zoned {
&self.0
}
}
impl fmt::Display for FrozenNow {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.0.fmt(f)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Timestamp(jiff::Timestamp);
impl Timestamp {
pub fn now() -> Self {
Self(jiff::Timestamp::now())
}
pub fn parse(text: &str) -> Result<Self, SnapshotError> {
text.parse::<jiff::Timestamp>()
.map(Self)
.map_err(|_| SnapshotError::Instant(text.to_owned()))
}
pub fn get(&self) -> jiff::Timestamp {
self.0
}
}
impl fmt::Display for Timestamp {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.0.fmt(f)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Origin {
Toha,
Edit {
regions: Vec<String>,
values: Vec<String>,
},
Hook,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PathOwnership {
path: TargetPath,
origin: Origin,
}
impl PathOwnership {
pub fn new(path: TargetPath, origin: Origin) -> Self {
Self { path, origin }
}
pub fn path(&self) -> &TargetPath {
&self.path
}
pub fn origin(&self) -> &Origin {
&self.origin
}
}
#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
struct DocWire {
snapshot: u32,
id: String,
template: String,
source: String,
commit: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
content_digest: Option<String>,
target: String,
created: String,
generated: String,
project: ProjectWire,
built_from: Option<String>,
submissions: Vec<IndexMap<String, serde_json::Value>>,
paths: IndexMap<String, PathWire>,
}
#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
struct ProjectWire {
commit: String,
branch: Option<String>,
}
#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
struct PathWire {
origin: OriginWire,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
regions: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
values: Vec<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
enum OriginWire {
Toha,
Edit,
Hook,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnapshotDoc {
id: SnapshotId,
template: String,
source: String,
revision: Revision,
target: RepoPath,
created: Timestamp,
generated: FrozenNow,
project: ProjectPoint,
built_from: Option<SnapshotId>,
submissions: Vec<IndexMap<String, serde_json::Value>>,
paths: Vec<PathOwnership>,
}
impl SnapshotDoc {
#[allow(clippy::too_many_arguments)]
pub fn new(
id: SnapshotId,
template: String,
revision: Revision,
target: RepoPath,
created: Timestamp,
generated: FrozenNow,
project: ProjectPoint,
built_from: Option<SnapshotId>,
submissions: Vec<IndexMap<String, serde_json::Value>>,
paths: Vec<PathOwnership>,
) -> Self {
let source = strip_reference(&template).to_owned();
Self {
id,
template,
source,
revision,
target,
created,
generated,
project,
built_from,
submissions,
paths,
}
}
pub fn id(&self) -> &SnapshotId {
&self.id
}
pub fn target(&self) -> &RepoPath {
&self.target
}
pub fn paths(&self) -> &[PathOwnership] {
&self.paths
}
pub fn to_json_bytes(&self) -> Vec<u8> {
let wire = DocWire {
snapshot: SNAPSHOT_FORMAT,
id: self.id.to_string(),
template: self.template.clone(),
source: self.source.clone(),
commit: match &self.revision {
Revision::Commit(commit) => Some(commit.as_str().to_owned()),
Revision::Content(_) | Revision::Unversioned => None,
},
content_digest: match &self.revision {
Revision::Content(digest) => Some(digest.as_str().to_owned()),
_ => None,
},
target: self.target.to_string(),
created: self.created.to_string(),
generated: self.generated.to_string(),
project: ProjectWire {
commit: self.project.commit.as_str().to_owned(),
branch: self.project.branch.clone(),
},
built_from: self.built_from.map(|id| id.to_string()),
submissions: self.submissions.clone(),
paths: self
.paths
.iter()
.map(|entry| (entry.path.to_string(), PathWire::from(entry.origin.clone())))
.collect(),
};
let mut bytes = serde_json::to_vec_pretty(&wire).expect("snapshot serialises");
bytes.push(b'\n');
bytes
}
}
impl From<Origin> for PathWire {
fn from(origin: Origin) -> Self {
match origin {
Origin::Toha => PathWire {
origin: OriginWire::Toha,
regions: Vec::new(),
values: Vec::new(),
},
Origin::Hook => PathWire {
origin: OriginWire::Hook,
regions: Vec::new(),
values: Vec::new(),
},
Origin::Edit { regions, values } => PathWire {
origin: OriginWire::Edit,
regions,
values,
},
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Snapshot {
doc: SnapshotDoc,
}
impl Snapshot {
pub fn validate(
ref_id: SnapshotId,
bytes: &[u8],
files: &BTreeSet<String>,
) -> Result<Self, SnapshotError> {
let wire: DocWire = serde_json::from_slice(bytes).map_err(SnapshotError::Json)?;
if wire.snapshot != SNAPSHOT_FORMAT {
return Err(SnapshotError::Format(wire.snapshot));
}
let id: SnapshotId = wire.id.parse()?;
if id != ref_id {
return Err(SnapshotError::IdRefMismatch {
declared: id,
r#ref: ref_id,
});
}
if wire.source != strip_reference(&wire.template) {
return Err(SnapshotError::Source {
template: wire.template.clone(),
declared: wire.source.clone(),
});
}
let revision = match (wire.commit.as_deref(), wire.content_digest.as_deref()) {
(Some(_), Some(_)) => return Err(SnapshotError::ConflictingRevision),
(Some(text), None) => Revision::Commit(CommitId::parse(text)?),
(None, Some(text)) => Revision::Content(ContentDigest::parse(text)?),
(None, None) => Revision::Unversioned,
};
let target = RepoPath::parse(&wire.target)?;
let created = Timestamp::parse(&wire.created)?;
let generated = FrozenNow::parse(&wire.generated)?;
let project = ProjectPoint {
commit: CommitId::parse(&wire.project.commit)?,
branch: wire.project.branch,
};
let built_from = match wire.built_from {
None => None,
Some(text) => Some(text.parse()?),
};
let mut paths = Vec::with_capacity(wire.paths.len());
let mut keys = BTreeSet::new();
for (raw, entry) in wire.paths {
let path = TargetPath::parse(&raw).map_err(|message| SnapshotError::Path {
path: raw.clone(),
message,
})?;
let origin = validate_origin(&raw, entry)?;
keys.insert(raw);
paths.push(PathOwnership { path, origin });
}
if &keys != files {
return Err(SnapshotError::PathsFilesMismatch);
}
Ok(Self {
doc: SnapshotDoc {
id,
template: wire.template,
source: wire.source,
revision,
target,
created,
generated,
project,
built_from,
submissions: wire.submissions,
paths,
},
})
}
pub fn id(&self) -> &SnapshotId {
&self.doc.id
}
pub fn template(&self) -> &str {
&self.doc.template
}
pub fn source(&self) -> &str {
&self.doc.source
}
pub fn revision(&self) -> &Revision {
&self.doc.revision
}
pub fn target(&self) -> &RepoPath {
&self.doc.target
}
pub fn created(&self) -> Timestamp {
self.doc.created
}
pub fn generated(&self) -> &FrozenNow {
&self.doc.generated
}
pub fn project(&self) -> &ProjectPoint {
&self.doc.project
}
pub fn built_from(&self) -> Option<&SnapshotId> {
self.doc.built_from.as_ref()
}
pub fn submissions(&self) -> &[IndexMap<String, serde_json::Value>] {
&self.doc.submissions
}
pub fn paths(&self) -> &[PathOwnership] {
&self.doc.paths
}
}
pub(crate) struct CapturedBlob {
pub path: TargetPath,
pub kind: EntryKind,
pub oid: gix::ObjectId,
}
pub(crate) fn save(
repo: &gix::Repository,
doc: &SnapshotDoc,
blobs: &[CapturedBlob],
) -> Result<SnapshotId, SnapshotError> {
let empty = gix::ObjectId::empty_tree(repo.object_hash());
let files_tree = if blobs.is_empty() {
None
} else {
let mut editor = repo.edit_tree(empty).map_err(git_error)?;
for blob in blobs {
editor
.upsert(blob.path.to_string().as_str(), blob.kind, blob.oid)
.map_err(git_error)?;
}
Some(editor.write().map_err(git_error)?.detach())
};
let json_oid = repo
.write_blob(doc.to_json_bytes())
.map_err(git_error)?
.detach();
let mut top = repo.edit_tree(empty).map_err(git_error)?;
top.upsert("snapshot.json", EntryKind::Blob, json_oid)
.map_err(git_error)?;
if let Some(files_tree) = files_tree {
top.upsert("files", EntryKind::Tree, files_tree)
.map_err(git_error)?;
}
let top_tree = top.write().map_err(git_error)?.detach();
let signature = gix::actor::Signature {
name: "Toha".into(),
email: "toha@example.invalid".into(),
time: gix::date::Time::now_utc(),
};
let mut author_buf = gix::date::parse::TimeBuf::default();
let mut committer_buf = gix::date::parse::TimeBuf::default();
let refname = format!("{SNAPSHOT_REF_PREFIX}{}", doc.id);
repo.commit_as(
signature.to_ref(&mut committer_buf),
signature.to_ref(&mut author_buf),
refname.as_str(),
format!("toha snapshot {}\n", doc.id),
top_tree,
Vec::<gix::ObjectId>::new(),
)
.map_err(git_error)?;
Ok(doc.id)
}
fn git_error(err: impl std::fmt::Display) -> SnapshotError {
SnapshotError::Git(err.to_string())
}
fn strip_reference(template: &str) -> &str {
template
.split_once('@')
.map_or(template, |(source, _)| source)
}
pub fn source_identity(formal_name: &str) -> &str {
strip_reference(formal_name)
}
fn validate_origin(path: &str, entry: PathWire) -> Result<Origin, SnapshotError> {
match entry.origin {
OriginWire::Toha | OriginWire::Hook
if !entry.regions.is_empty() || !entry.values.is_empty() =>
{
Err(SnapshotError::Ownership {
path: path.to_owned(),
})
}
OriginWire::Toha => Ok(Origin::Toha),
OriginWire::Hook => Ok(Origin::Hook),
OriginWire::Edit => Ok(Origin::Edit {
regions: entry.regions,
values: entry.values,
}),
}
}
#[derive(Debug, thiserror::Error)]
pub enum SnapshotError {
#[error("snapshot id is not a valid ULID: {0}")]
Id(String),
#[error("snapshot prefix must be 6 to 26 Crockford characters: {0}")]
Prefix(String),
#[error("snapshot.json is not valid JSON: {0}")]
Json(#[source] serde_json::Error),
#[error("unsupported snapshot format version: {0}")]
Format(u32),
#[error("snapshot id {declared} does not match its ref {ref}")]
IdRefMismatch {
declared: SnapshotId,
r#ref: SnapshotId,
},
#[error("snapshot source {declared} does not match template {template}")]
Source { template: String, declared: String },
#[error("invalid commit in snapshot: {0}")]
Commit(String),
#[error("invalid content digest in snapshot: {0}")]
ContentDigest(String),
#[error("snapshot cannot carry both a commit and a content digest")]
ConflictingRevision,
#[error("invalid instant in snapshot: {0}")]
Instant(String),
#[error("invalid snapshot path {path}: {message}")]
Path { path: String, message: String },
#[error("snapshot path {path} carries ownership its origin cannot hold")]
Ownership { path: String },
#[error("snapshot paths do not equal the files under files/")]
PathsFilesMismatch,
#[error("snapshot commit has a parent")]
HasParent,
#[error("snapshot tree is missing snapshot.json")]
MissingSnapshotJson,
#[error("snapshot.json is not a regular file")]
SnapshotJsonNotBlob,
#[error("snapshot files/ is not a tree")]
FilesNotTree,
#[error("snapshot tree has an unexpected entry: {0}")]
ExtraTreeEntry(String),
#[error("snapshot files/ contains a non-regular entry: {0}")]
BadFileEntry(String),
#[error("unknown snapshot: {0}")]
Unknown(String),
#[error("ambiguous snapshot prefix {prefix} matches {matches:?}")]
Ambiguous {
prefix: String,
matches: Vec<String>,
},
#[error("cannot read snapshot from git: {0}")]
Git(String),
#[error("removing every snapshot of {name} needs --force")]
WholeSource { name: String },
}
#[cfg(test)]
mod tests;