Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions core/crates/layerfs-history/src/contract/catalog.rs
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ use crate::identity::{BranchId, CatalogId, CommitId, HistoryName, LayerId, Layer
use crate::records::{
AddLayerOutcome, AddLayerRequest, BranchMergeRequest, BranchRecord, BranchSnapshot,
CommitHistoryRequest, CommitOutcome, CommitRecord, CommitRequest, ForkRequest,
LayerHistoryRequest, LayerRecord, LayerStackRecord, Page, PageResult, Reservation,
ReserveRequest, StackInitialization,
LayerHistoryRequest, LayerRecord, LayerStackRecord, Page, PageResult, PathRemovalOutcome,
PathRemovalRecord, PathRemovalRequest, Reservation, ReserveRequest, StackInitialization,
};
/// Checked inputs that establish one catalog binding.
#[derive(Clone, Eq, PartialEq)]
Expand Down Expand Up @@ -332,6 +332,29 @@ pub trait HistoryCatalog: Send + Sync {
))
}

/// Applies one `project.remove_file` marker in one write transaction:
/// reads the Store high-water as the new frontier, returns `UpToDate`
/// when the path's marker already covers every project node, otherwise
/// advances the marker and the project epoch. The default refuses.
fn remove_path(&self, _request: &PathRemovalRequest) -> HistoryResult<PathRemovalOutcome> {
Err(crate::error::HistoryError::Unsupported("path removal"))
}

/// Every `path_removed` marker of one Stack. The default refuses.
fn path_removals(&self, _stack: LayerStackId) -> HistoryResult<Vec<PathRemovalRecord>> {
Err(crate::error::HistoryError::Unsupported(
"path removal markers",
))
}

/// The `history_serial` a Commit or Layer records, if it exists. The
/// default refuses.
fn node_history_serial(&self, _node: NodeId) -> HistoryResult<Option<u64>> {
Err(crate::error::HistoryError::Unsupported(
"node history position",
))
}

/// The retained history roots of one Stack. The default refuses.
///
/// # Errors
Expand Down
3 changes: 3 additions & 0 deletions core/crates/layerfs-history/src/contract/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,8 @@ pub enum HistoryError {
NameTaken(Box<NameTakenState>),
/// A path is hidden by `remove_file`.
Removed(Box<RemovedState>),
/// A required marker or fence row is missing or contradicts the request.
Conflict(&'static str),
/// The Store was replaced or moved under this handle.
StaleStore,
/// Immediate metadata admission was refused; the caller may retry later.
Expand Down Expand Up @@ -208,6 +210,7 @@ impl std::fmt::Display for HistoryError {
Self::Unsupported(what) => write!(formatter, "unsupported: {what}"),
Self::NameTaken(state) => write!(formatter, "name taken: {:?}", state.holder),
Self::Removed(state) => write!(formatter, "removed: {} paths", state.paths.len()),
Self::Conflict(what) => write!(formatter, "conflict: {what}"),
Self::StaleStore => formatter.write_str("stale Store"),
Self::Busy => formatter.write_str("busy"),
Self::OwnershipUnavailable => formatter.write_str("ownership unavailable"),
Expand Down
1 change: 1 addition & 0 deletions core/crates/layerfs-history/src/contract/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,6 @@
pub mod catalog;
pub mod error;
pub mod identity;
pub mod path;
pub mod query;
pub mod records;
154 changes: 154 additions & 0 deletions core/crates/layerfs-history/src/contract/path.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
//! The `project.remove_file` path grammar and its keys.
//!
//! The call accepts an absolute POSIX path and stores it as the normalized
//! relative path (`/a` and `a` are the same). A path is refused when it is
//! empty, `/`, `//a`, has an empty, `.` or `..` component, a trailing `/`, a
//! `\` or NUL byte, is longer than 4096 bytes, or has more than 256
//! components. The stored key is `BLAKE3(normalized path)`; the trace key is
//! keyed by the Store's `trace_salt` over the stack and the normalized path.

use crate::identity::LayerStackId;

/// The most bytes one normalized path may have.
pub const MAXIMUM_PATH_BYTES: usize = 4096;
/// The most components one normalized path may have.
pub const MAXIMUM_PATH_COMPONENTS: usize = 256;

/// A checked, normalized relative path.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct NormalizedPath {
relative: String,
}

impl NormalizedPath {
/// Checks `text` and returns its normalized relative path.
///
/// One leading `/` is stripped; everything after it is the relative path.
/// The returned value never starts or ends with `/` and never holds an
/// empty, `.` or `..` component.
pub fn new(text: &str) -> Result<Self, &'static str> {
if text.is_empty() {
return Err("path is empty");
}
if text.as_bytes().contains(&0) {
return Err("path contains a NUL byte");
}
if text.contains('\\') {
return Err("path contains a backslash");
}
let relative = text.strip_prefix('/').unwrap_or(text);
if relative.is_empty() {
return Err("path is the root");
}
if relative.starts_with('/') {
return Err("path has an empty component");
}
let mut components = 0usize;
for component in relative.split('/') {
if component.is_empty() {
return Err("path has an empty component");
}
if component == "." || component == ".." {
return Err("path has a dot component");
}
components += 1;
}
if components > MAXIMUM_PATH_COMPONENTS {
return Err("path has too many components");
}
if relative.len() > MAXIMUM_PATH_BYTES {
return Err("path is too long");
}
Ok(Self {
relative: relative.to_owned(),
})
}

/// The normalized relative path, without a leading `/`.
pub fn as_str(&self) -> &str {
&self.relative
}

/// The normalized path bytes as stored in the marker.
pub fn as_bytes(&self) -> &[u8] {
self.relative.as_bytes()
}

/// `BLAKE3(normalized path)`, the marker key.
pub fn key(&self) -> [u8; 32] {
path_key(self.as_bytes())
}
}

/// `BLAKE3(path)` over already normalized path bytes, the marker key.
pub fn path_key(path: &[u8]) -> [u8; 32] {
*blake3::hash(path).as_bytes()
}

/// True when `path` is `marker` or lies below it at a `/` boundary
/// (`p == m OR p begins m ++ b"/"`), compared over bytes, never `||`/`LIKE`.
pub fn governs(marker: &[u8], path: &[u8]) -> bool {
path == marker
|| (path.len() > marker.len() && path.starts_with(marker) && path[marker.len()] == b'/')
}

/// The key a trace hashes for one stack and path: keyed by the Store's
/// 32-byte `trace_salt` over the stack identity and the normalized path.
pub fn trace_key(salt: &[u8; 32], stack: LayerStackId, path: &[u8]) -> [u8; 32] {
let mut hasher = blake3::Hasher::new_keyed(salt);
hasher.update(stack.as_slice());
hasher.update(path);
*hasher.finalize().as_bytes()
}

#[cfg(test)]
mod tests {
use super::*;

#[test]
fn accepts_one_leading_slash_and_relative_paths() {
assert_eq!(NormalizedPath::new("/a").unwrap().as_str(), "a");
assert_eq!(NormalizedPath::new("a").unwrap().as_str(), "a");
assert_eq!(NormalizedPath::new("/a/b").unwrap().as_str(), "a/b");
assert_eq!(NormalizedPath::new("a-b_c.d").unwrap().as_str(), "a-b_c.d");
}

#[test]
fn refuses_the_bad_grammar() {
for text in [
"", "/", "//a", "a//b", "a/", "./a", "a/./b", ".", "..", "/./a", "a\\b", "a\0b",
] {
assert!(NormalizedPath::new(text).is_err(), "accepted {text:?}");
}
}

#[test]
fn refuses_long_paths_and_many_components() {
assert!(NormalizedPath::new(&"a".repeat(MAXIMUM_PATH_BYTES)).is_ok());
assert!(NormalizedPath::new(&"a".repeat(MAXIMUM_PATH_BYTES + 1)).is_err());
let many = vec!["a"; MAXIMUM_PATH_COMPONENTS].join("/");
assert!(NormalizedPath::new(&many).is_ok());
let more = vec!["a"; MAXIMUM_PATH_COMPONENTS + 1].join("/");
assert!(NormalizedPath::new(&more).is_err());
}

#[test]
fn subtree_matches_only_at_a_slash_boundary() {
assert!(governs(b"a", b"a"));
assert!(governs(b"a", b"a/b"));
assert!(!governs(b"a", b"ab"));
assert!(!governs(b"ab", b"a"));
assert!(governs(b"a/b", b"a/b/c"));
assert!(!governs(b"a/b", b"a/bc"));
}

#[test]
fn keys_are_stable_and_salted_traces_differ() {
let path = NormalizedPath::new("/a/b").unwrap();
assert_eq!(path.key(), path_key(b"a/b"));
let stack = LayerStackId::from_authority([7; 16]);
let first = trace_key(&[1; 32], stack, path.as_bytes());
let second = trace_key(&[2; 32], stack, path.as_bytes());
assert_ne!(first, second);
}
}
47 changes: 47 additions & 0 deletions core/crates/layerfs-history/src/contract/records.rs
Original file line number Diff line number Diff line change
Expand Up @@ -636,3 +636,50 @@ pub struct InitStatistics {
/// Init's wall time in milliseconds, up to the first Branch.
pub millis: u64,
}

/// One `path_removed` marker as stored for a project.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PathRemovalRecord {
/// The normalized relative path the marker names.
pub path: Vec<u8>,
/// The Store high-water when the marker last advanced.
pub frontier_serial: u64,
/// When the marker last advanced, in milliseconds since the epoch.
pub removed_ms: i64,
}

/// Whether a `project.remove_file` call advanced the marker or found it current.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PathRemovalKind {
/// The marker advanced to a new frontier.
Removed,
/// No project node is above the marker's frontier; the stored values are returned.
UpToDate,
}

/// One `project.remove_file` request: the project, the normalized path and the
/// time the caller observed.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PathRemovalRequest {
/// Project (LayerStack) the path is removed in.
pub stack: LayerStackId,
/// The normalized relative path bytes; `BLAKE3` keys the marker.
pub path: Vec<u8>,
/// When the call was made, in milliseconds since the epoch.
pub removed_ms: i64,
}

/// One `project.remove_file` result: the stored marker values.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PathRemovalOutcome {
/// Whether the call advanced the marker or found it current.
pub kind: PathRemovalKind,
/// Project (LayerStack) the marker belongs to.
pub stack: LayerStackId,
/// The stored normalized relative path.
pub path: Vec<u8>,
/// The stored frontier serial.
pub frontier_serial: u64,
/// The stored `removed_ms`.
pub removed_ms: i64,
}
4 changes: 3 additions & 1 deletion core/crates/layerfs-history/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ mod contract;
pub use contract::catalog;
pub use contract::error;
pub use contract::identity;
pub use contract::path;
pub use contract::query;
pub use contract::records;

Expand All @@ -34,6 +35,7 @@ pub use records::{
BranchSnapshot, CommitHistoryRequest, CommitMeta, CommitOutcome, CommitRecord, CommitRequest,
CommitStatistics, CommitVia, FileDigest, ForkRequest, ForkSource, InitStatistics,
LayerHistoryRequest, LayerRecord, LayerStackRecord, MergeCommit, MergeHead, MergeSide, Page,
PageResult, RecordKind, Reservation, ReserveRequest, StackInitialization, StoreStatistics,
PageResult, PathRemovalKind, PathRemovalOutcome, PathRemovalRecord, PathRemovalRequest,
RecordKind, Reservation, ReserveRequest, StackInitialization, StoreStatistics,
FILE_DIGEST_WINDOW, MAXIMUM_MESSAGE_BYTES, MAXIMUM_PAGE_RECORDS,
};
Loading
Loading