neuwirth
/
LeVCS
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
LeVCS/crates/levcs-store/src/roots.rs

1379 lines
45 KiB
Rust
Raw Blame History

//! Immutable publication roots for committed and in-flight store state.
//!
//! **Lead-owned (D0-B).** The types in this file are the boundary between the
//! shard writers and every reader. Writers build a complete [`ShardSubtree`],
//! merge it into the last root they loaded, and publish the resulting
//! [`CommittedRoot`] through `ArcSwap`. Nothing reachable from an already
//! published root is mutated.
//!
//! The persistent collections are intentional. A group touching a few
//! repositories, receipts, or refs must share the untouched majority rather
//! than clone it. Typed refs use [`im::OrdMap`] because their canonical order
//! feeds checkpoint/digest construction; hot lookup tables use
//! [`im::HashMap`].
use std::fs::File;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
use im::{HashMap, OrdMap, Vector};
use levcs_core::ObjectId;
use levcs_protocol::v2::RefTarget;
use crate::index::{
IndexDelta, IndexKey, IndexLocation, IndexRun, LookupResult, NamespaceLifecycle,
NamespaceStorageMode,
};
use crate::types::{
CommitReceipt, NamespaceId, OperationId, PendingPhase, StoreError, TransactionStatus,
};
/// Key shared by the committed terminal table and the transient status root.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct OperationKey {
pub namespace: NamespaceId,
pub operation_id: OperationId,
}
impl OperationKey {
pub const fn new(namespace: NamespaceId, operation_id: OperationId) -> Self {
Self {
namespace,
operation_id,
}
}
}
/// Canonically ordered typed refs.
///
/// Ref order is observable anywhere a state digest or checkpoint is encoded,
/// so this is the one hot publication map for which `OrdMap`, rather than the
/// faster unordered HAMT, is required.
pub type TypedRefMap = OrdMap<RefTarget, ObjectId>;
/// One repository's complete logical state at a committed publication.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RepoState {
pub repo_sequence: u64,
pub current_authority: ObjectId,
pub genesis_authority: ObjectId,
pub refs: TypedRefMap,
pub lifecycle: NamespaceLifecycle,
pub storage_mode: NamespaceStorageMode,
pub previous_event_digest: ObjectId,
}
/// A committed operation retained while its receipt remains visible.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RetainedReceipt {
pub operation_digest: ObjectId,
pub receipt: CommitReceipt,
pub shard_sequence: u64,
pub retry_until_micros: i64,
pub first_visible_at_micros: i64,
pub receipt_visible_until_micros: i64,
}
/// A committed operation whose receipt aged out but whose ID/digest tombstone
/// still prevents ambiguous reuse.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ReceiptTombstone {
pub operation_digest: ObjectId,
pub retry_until_micros: i64,
pub tombstone_until_micros: i64,
}
/// Durable terminal state for one `(namespace, operation ID)`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum TerminalStatusEntry {
Committed(RetainedReceipt),
Expired(ReceiptTombstone),
}
impl TerminalStatusEntry {
pub fn operation_digest(&self) -> ObjectId {
match self {
Self::Committed(receipt) => receipt.operation_digest,
Self::Expired(tombstone) => tombstone.operation_digest,
}
}
pub fn transaction_status(&self) -> TransactionStatus {
match self {
Self::Committed(receipt) => TransactionStatus::Committed(receipt.receipt.clone()),
Self::Expired(tombstone) => TransactionStatus::Expired {
operation_digest: tombstone.operation_digest,
retry_until_micros: tombstone.retry_until_micros,
tombstone_until_micros: tombstone.tombstone_until_micros,
},
}
}
}
/// A file pin retained by a committed generation.
///
/// The live `File`, not the path, is the ownership. On the supported Unix
/// storage targets it keeps the inode alive even after reclamation removes a
/// directory entry. The path remains for diagnostics and reference proofs.
#[derive(Clone, Debug)]
pub struct PinnedFile {
path: PathBuf,
file: Arc<File>,
}
impl PinnedFile {
pub fn new(path: PathBuf, file: File) -> Self {
Self {
path,
file: Arc::new(file),
}
}
pub fn from_shared(path: PathBuf, file: Arc<File>) -> Self {
Self { path, file }
}
pub fn open(path: impl Into<PathBuf>) -> Result<Self, StoreError> {
let path = path.into();
let file = File::open(&path)?;
Ok(Self::new(path, file))
}
pub fn path(&self) -> &Path {
&self.path
}
pub fn file(&self) -> &Arc<File> {
&self.file
}
}
/// A validated immutable index run together with its installed name.
///
/// `IndexRun` owns its mapping; retaining the `Arc` therefore retains the
/// mapped inode. Keeping the path alongside it makes adoption cleanup's
/// committed-root reference proof possible without consulting mutable
/// staging bookkeeping.
#[derive(Clone, Debug)]
pub struct RetainedIndexRun {
path: PathBuf,
run: Arc<IndexRun>,
}
impl RetainedIndexRun {
pub fn new(path: PathBuf, run: Arc<IndexRun>) -> Self {
Self { path, run }
}
pub fn path(&self) -> &Path {
&self.path
}
pub fn run(&self) -> &Arc<IndexRun> {
&self.run
}
}
/// A validated sealed segment addressed by the generation stored in index
/// locations.
///
/// The pin keeps the inode alive; the logical generation is what lets a
/// reader resolve `IndexLocation::segment_generation` without parsing a file
/// name or consulting mutable manifest state.
#[derive(Clone, Debug)]
pub struct RetainedSegment {
pub logical_generation: u64,
pub journal_id: [u8; 16],
pub first_shard_sequence: u64,
pub last_shard_sequence: u64,
pub file: PinnedFile,
}
impl RetainedSegment {
pub fn new(
logical_generation: u64,
journal_id: [u8; 16],
first_shard_sequence: u64,
last_shard_sequence: u64,
file: PinnedFile,
) -> Self {
Self {
logical_generation,
journal_id,
first_shard_sequence,
last_shard_sequence,
file,
}
}
pub fn path(&self) -> &Path {
self.file.path()
}
}
/// A validated active journal prefix addressed as one logical segment.
///
/// Replayed index entries use `IndexLocation::segment_generation`, so the
/// generation assigned during recovery must travel with the file pin into
/// every committed root. A bare `PinnedFile` would keep the bytes alive but
/// leave readers unable to resolve those locations without reopening or
/// guessing a path.
#[derive(Clone, Debug)]
pub struct RetainedTail {
pub logical_generation: u64,
pub file: PinnedFile,
}
impl RetainedTail {
pub fn new(logical_generation: u64, file: PinnedFile) -> Self {
Self {
logical_generation,
file,
}
}
pub fn path(&self) -> &Path {
self.file.path()
}
}
/// Physical encoding used by an adopted projection artifact.
///
/// Staged chunks are independently canonical and checksummed; they are not
/// transaction frames. The source kind therefore travels with the generation
/// pin so a reader never applies the journal-frame decoder to chunk bytes.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum ProjectionArtifactFormat {
CanonicalStageChunkV1,
}
/// One adopted projection artifact addressable by index locations.
#[derive(Clone, Debug)]
pub struct RetainedProjectionArtifact {
pub logical_generation: u64,
pub format: ProjectionArtifactFormat,
pub file: PinnedFile,
}
impl RetainedProjectionArtifact {
pub fn new(
logical_generation: u64,
format: ProjectionArtifactFormat,
file: PinnedFile,
) -> Self {
Self {
logical_generation,
format,
file,
}
}
pub fn path(&self) -> &Path {
self.file.path()
}
}
/// The physical record decoder selected by one index generation.
#[derive(Copy, Clone, Debug)]
pub enum RetainedObjectSource<'a> {
Segment(&'a RetainedSegment),
ActiveTail(&'a RetainedTail),
ProjectionArtifact(&'a RetainedProjectionArtifact),
}
impl RetainedObjectSource<'_> {
pub fn path(&self) -> &Path {
match self {
Self::Segment(source) => source.path(),
Self::ActiveTail(source) => source.path(),
Self::ProjectionArtifact(source) => source.path(),
}
}
}
/// Stable identity of one retained manifest generation.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct GenerationId {
pub shard_index: u16,
pub manifest_generation: u64,
}
impl GenerationId {
pub const fn new(shard_index: u16, manifest_generation: u64) -> Self {
Self {
shard_index,
manifest_generation,
}
}
}
/// Live ownership of every artifact retained by one manifest generation.
///
/// Recovery constructs this only after validating all referents. Moving it
/// into a root leaves no interval where the artifacts are merely named but
/// unowned and therefore reclaimable.
#[derive(Clone, Debug)]
pub struct RetainedGeneration {
pub id: GenerationId,
pub segments: Arc<[RetainedSegment]>,
pub index_runs: Arc<[RetainedIndexRun]>,
pub checkpoints: Arc<[PinnedFile]>,
pub active_tails: Arc<[RetainedTail]>,
pub projection_artifacts: Arc<[RetainedProjectionArtifact]>,
}
impl RetainedGeneration {
pub fn new(
id: GenerationId,
segments: Arc<[RetainedSegment]>,
index_runs: Arc<[RetainedIndexRun]>,
checkpoints: Arc<[PinnedFile]>,
active_tails: Arc<[RetainedTail]>,
projection_artifacts: Arc<[RetainedProjectionArtifact]>,
) -> Self {
Self {
id,
segments,
index_runs,
checkpoints,
active_tails,
projection_artifacts,
}
}
pub fn references_path(&self, path: &Path) -> bool {
self.segments.iter().any(|segment| segment.path() == path)
|| self.index_runs.iter().any(|run| run.path() == path)
|| self.checkpoints.iter().any(|file| file.path() == path)
|| self.active_tails.iter().any(|tail| tail.path() == path)
|| self
.projection_artifacts
.iter()
.any(|artifact| artifact.path() == path)
}
pub fn retained_tail(&self, logical_generation: u64) -> Option<&RetainedTail> {
self.active_tails
.iter()
.find(|tail| tail.logical_generation == logical_generation)
}
pub fn retained_segment(&self, logical_generation: u64) -> Option<&RetainedSegment> {
self.segments
.iter()
.find(|segment| segment.logical_generation == logical_generation)
}
pub fn retained_projection_artifact(
&self,
logical_generation: u64,
) -> Option<&RetainedProjectionArtifact> {
self.projection_artifacts
.iter()
.find(|artifact| artifact.logical_generation == logical_generation)
}
}
/// Immutable object-index layering captured by every reader.
///
/// Both vectors are newest-first. Group deltas sit above sealed runs, and the
/// first hit wins. Each layer/run is `Arc`-shared, so a merge adds only the
/// new group's layer and shares every older one. Delta layers carry their
/// shard and upper sequence so installing a sealed run can discard exactly
/// the layers that run covers instead of allowing lookup fan-out to grow once
/// per committed group forever.
#[derive(Clone, Debug)]
pub struct IndexDeltaLayer {
pub shard_index: u16,
pub through_shard_sequence: u64,
pub delta: Arc<IndexDelta>,
}
impl IndexDeltaLayer {
pub fn new(shard_index: u16, through_shard_sequence: u64, delta: Arc<IndexDelta>) -> Self {
Self {
shard_index,
through_shard_sequence,
delta,
}
}
}
#[derive(Clone, Debug, Default)]
pub struct LayeredObjectIndex {
delta_layers_newest_first: Vector<IndexDeltaLayer>,
sealed_runs_newest_first: Vector<Arc<IndexRun>>,
}
impl LayeredObjectIndex {
pub fn new(
delta_layers_newest_first: Vector<IndexDeltaLayer>,
sealed_runs_newest_first: Vector<Arc<IndexRun>>,
) -> Self {
Self {
delta_layers_newest_first,
sealed_runs_newest_first,
}
}
/// Construct the complete recovery lookup stack: replayed tail above the
/// selected generation's already ordered sealed runs.
pub fn from_recovery(
shard_index: u16,
through_shard_sequence: u64,
replayed_delta: Arc<IndexDelta>,
sealed_runs_newest_first: Vector<Arc<IndexRun>>,
) -> Self {
let mut delta_layers = Vector::new();
if !replayed_delta.is_empty() {
delta_layers.push_back(IndexDeltaLayer::new(
shard_index,
through_shard_sequence,
replayed_delta,
));
}
Self::new(delta_layers, sealed_runs_newest_first)
}
pub fn delta_layers(&self) -> &Vector<IndexDeltaLayer> {
&self.delta_layers_newest_first
}
pub fn sealed_runs(&self) -> &Vector<Arc<IndexRun>> {
&self.sealed_runs_newest_first
}
pub fn delta_layer_count(&self) -> usize {
self.delta_layers_newest_first.len()
}
pub fn sealed_run_count(&self) -> usize {
self.sealed_runs_newest_first.len()
}
pub fn lookup(&self, key: &IndexKey) -> LookupResult {
for layer in &self.delta_layers_newest_first {
if let Some(location) = layer.delta.get(key) {
return LookupResult {
location: Some(location),
runs_searched: 0,
runs_filtered: 0,
answered_by_delta: true,
};
}
}
let mut result = LookupResult::default();
for run in &self.sealed_runs_newest_first {
if !run.may_contain(key) {
result.runs_filtered += 1;
continue;
}
result.runs_searched += 1;
if let Some(location) = run.get(key) {
result.location = Some(location);
return result;
}
}
result
}
pub fn get(&self, key: &IndexKey) -> Option<IndexLocation> {
self.lookup(key).location
}
fn with_subtree(&self, subtree: &ShardSubtree) -> Self {
let mut next = self.clone();
if let Some(sealed_through) = subtree.sealed_through_shard_sequence {
next.delta_layers_newest_first.retain(|layer| {
layer.shard_index != subtree.shard_index
|| layer.through_shard_sequence > sealed_through
});
}
let delta_is_sealed = subtree
.sealed_through_shard_sequence
.is_some_and(|sealed_through| sealed_through >= subtree.shard_committed_sequence);
if !delta_is_sealed && !subtree.index_delta.is_empty() {
next.delta_layers_newest_first
.push_front(IndexDeltaLayer::new(
subtree.shard_index,
subtree.shard_committed_sequence,
Arc::clone(&subtree.index_delta),
));
}
// `subtree` is already newest-first. Pushing from its back preserves
// that order at the front of the composed stack.
for run in subtree.sealed_runs_newest_first.iter().rev() {
next.sealed_runs_newest_first.push_front(Arc::clone(run));
}
next
}
}
pub type RepoMap = HashMap<NamespaceId, Arc<RepoState>>;
pub type TerminalStatusMap = HashMap<OperationKey, TerminalStatusEntry>;
pub type ShardSequenceMap = HashMap<u16, u64>;
pub type GenerationMap = HashMap<GenerationId, Arc<RetainedGeneration>>;
/// The immutable visibility boundary for all committed reads.
#[derive(Clone, Debug, Default)]
pub struct CommittedRoot {
repositories: RepoMap,
index: LayeredObjectIndex,
terminal_statuses: TerminalStatusMap,
shard_committed_sequences: ShardSequenceMap,
retained_generations: GenerationMap,
}
impl CommittedRoot {
pub fn new(
repositories: RepoMap,
index: LayeredObjectIndex,
terminal_statuses: TerminalStatusMap,
shard_committed_sequences: ShardSequenceMap,
retained_generations: GenerationMap,
) -> Self {
Self {
repositories,
index,
terminal_statuses,
shard_committed_sequences,
retained_generations,
}
}
pub fn repositories(&self) -> &RepoMap {
&self.repositories
}
pub fn repo(&self, namespace: &NamespaceId) -> Option<&Arc<RepoState>> {
self.repositories.get(namespace)
}
pub fn index(&self) -> &LayeredObjectIndex {
&self.index
}
pub fn terminal_statuses(&self) -> &TerminalStatusMap {
&self.terminal_statuses
}
pub fn terminal_status(&self, key: &OperationKey) -> Option<&TerminalStatusEntry> {
self.terminal_statuses.get(key)
}
pub fn shard_committed_sequences(&self) -> &ShardSequenceMap {
&self.shard_committed_sequences
}
pub fn shard_committed_sequence(&self, shard_index: u16) -> Option<u64> {
self.shard_committed_sequences.get(&shard_index).copied()
}
pub fn retained_generations(&self) -> &GenerationMap {
&self.retained_generations
}
/// Reference proof used by finalized-staging cleanup.
///
/// The answer comes from the captured committed root's live generation
/// ownership, never from staging's mutable bookkeeping.
pub fn references_path(&self, path: &Path) -> bool {
self.retained_generations
.values()
.any(|generation| generation.references_path(path))
}
/// Staging-facing spelling of [`Self::references_path`].
pub fn references_artifact(&self, path: &Path) -> bool {
self.references_path(path)
}
pub fn references_generation(&self, id: GenerationId) -> bool {
self.retained_generations.contains_key(&id)
}
/// Resolve a replayed active-tail index generation to its retained pin.
pub fn retained_tail(
&self,
shard_index: u16,
logical_generation: u64,
) -> Option<&RetainedTail> {
self.retained_generations
.values()
.filter(|generation| generation.id.shard_index == shard_index)
.find_map(|generation| generation.retained_tail(logical_generation))
}
/// Resolve a sealed-run index generation to its retained segment pin.
pub fn retained_segment(
&self,
shard_index: u16,
logical_generation: u64,
) -> Option<&RetainedSegment> {
self.retained_generations
.values()
.filter(|generation| generation.id.shard_index == shard_index)
.find_map(|generation| generation.retained_segment(logical_generation))
}
/// Resolve an adopted projection generation to its retained artifact.
pub fn retained_projection_artifact(
&self,
shard_index: u16,
logical_generation: u64,
) -> Option<&RetainedProjectionArtifact> {
self.retained_generations
.values()
.filter(|generation| generation.id.shard_index == shard_index)
.find_map(|generation| generation.retained_projection_artifact(logical_generation))
}
/// Resolve the decoder and live pin for an index location.
///
/// A logical generation may be retained by several manifest generations,
/// but every occurrence must name the same path and source kind. A
/// segment/chunk collision is corruption, never an arbitrary lookup
/// preference.
pub fn object_source(
&self,
shard_index: u16,
logical_generation: u64,
) -> Result<Option<RetainedObjectSource<'_>>, StoreError> {
let mut found: Option<RetainedObjectSource<'_>> = None;
for generation in self
.retained_generations
.values()
.filter(|generation| generation.id.shard_index == shard_index)
{
let candidates = [
generation
.retained_segment(logical_generation)
.map(RetainedObjectSource::Segment),
generation
.retained_tail(logical_generation)
.map(RetainedObjectSource::ActiveTail),
generation
.retained_projection_artifact(logical_generation)
.map(RetainedObjectSource::ProjectionArtifact),
];
for candidate in candidates.into_iter().flatten() {
if let Some(existing) = found {
if std::mem::discriminant(&existing) != std::mem::discriminant(&candidate)
|| existing.path() != candidate.path()
{
return Err(StoreError::Corruption(format!(
"shard {shard_index} generation {logical_generation} names \
multiple object sources"
)));
}
} else {
found = Some(candidate);
}
}
}
Ok(found)
}
/// Purely merge one fenced shard publication into this root.
///
/// Reapplying a subtree whose shard sequence is already present is a
/// no-op. This makes the CAS retry path idempotent in effect while still
/// allowing a subtree from another shard to merge against a newer root.
/// No object reachable through `self` is mutated.
///
/// # Maintenance publications
///
/// Contract review 2026-07-29-C, amendment 3. An index seal publishes a
/// subtree that appends **no frame**, so its `shard_committed_sequence` is
/// the one already published — and the guard above, which exists to make a
/// re-merged *group* idempotent, would discard it as a duplicate. Sealing
/// would then advance the manifest on disk and never reach the root, which is
/// exactly the ambiguity the seal path poisons to avoid; it would have been
/// silent instead.
///
/// So the guard asks what the subtree carries rather than only what sequence
/// it names. Re-merging a maintenance subtree stays idempotent for a
/// different reason: the layer-discard is a `retain` (already-dropped layers
/// stay dropped), and the CAS loop re-merges the same subtree against a fresh
/// root each attempt rather than accumulating onto its own output, so a run
/// is pushed once into whichever root wins.
pub fn merge(&self, subtree: &ShardSubtree) -> CommittedRoot {
if self
.shard_committed_sequence(subtree.shard_index)
.is_some_and(|published| published >= subtree.shard_committed_sequence)
&& !subtree.publishes_index_maintenance()
{
return self.clone();
}
let mut repositories = self.repositories.clone();
for (namespace, state) in &subtree.repositories {
repositories.insert(*namespace, Arc::clone(state));
}
let mut terminal_statuses = self.terminal_statuses.clone();
for key in &subtree.terminal_status_removals {
terminal_statuses.remove(key);
}
for (key, status) in &subtree.terminal_statuses {
terminal_statuses.insert(*key, status.clone());
}
let mut shard_committed_sequences = self.shard_committed_sequences.clone();
shard_committed_sequences.insert(subtree.shard_index, subtree.shard_committed_sequence);
let mut retained_generations = self.retained_generations.clone();
for id in &subtree.retained_generation_removals {
retained_generations.remove(id);
}
for (id, generation) in &subtree.retained_generations {
retained_generations.insert(*id, Arc::clone(generation));
}
Self {
repositories,
index: self.index.with_subtree(subtree),
terminal_statuses,
shard_committed_sequences,
retained_generations,
}
}
}
/// Complete immutable output of one fenced group, before root merge.
#[derive(Clone, Debug)]
pub struct ShardSubtree {
pub shard_index: u16,
pub shard_committed_sequence: u64,
pub index_delta: Arc<IndexDelta>,
/// When present, the newly installed sealed runs cover every delta layer
/// from this shard through the named sequence, including this subtree's
/// delta when the value reaches `shard_committed_sequence`.
pub sealed_through_shard_sequence: Option<u64>,
/// Any newly installed runs, newest-first. Most groups leave this empty.
pub sealed_runs_newest_first: Vector<Arc<IndexRun>>,
pub repositories: RepoMap,
/// Terminal rows whose tombstone horizon has ended. Removals are applied
/// before replacements, which keeps retrying the same subtree idempotent.
pub terminal_status_removals: Vector<OperationKey>,
pub terminal_statuses: TerminalStatusMap,
/// Generation pins released by the same publication after every newer
/// root/index reference has been installed.
pub retained_generation_removals: Vector<GenerationId>,
pub retained_generations: GenerationMap,
}
impl ShardSubtree {
#[allow(clippy::too_many_arguments)]
pub fn new(
shard_index: u16,
shard_committed_sequence: u64,
index_delta: Arc<IndexDelta>,
sealed_through_shard_sequence: Option<u64>,
sealed_runs_newest_first: Vector<Arc<IndexRun>>,
repositories: RepoMap,
terminal_statuses: TerminalStatusMap,
retained_generations: GenerationMap,
) -> Self {
Self {
shard_index,
shard_committed_sequence,
index_delta,
sealed_through_shard_sequence,
sealed_runs_newest_first,
repositories,
terminal_status_removals: Vector::new(),
terminal_statuses,
retained_generation_removals: Vector::new(),
retained_generations,
}
}
/// Whether this subtree publishes index maintenance rather than (or as well
/// as) a group.
///
/// Read by [`CommittedRoot::merge`] so a publication that appends no frame is
/// not mistaken for a re-merged duplicate. Deliberately a question about the
/// payload and not a flag the writer sets: a boolean could disagree with the
/// fields, and the disagreement that matters — a seal marked as a group —
/// would drop the seal.
pub fn publishes_index_maintenance(&self) -> bool {
self.sealed_through_shard_sequence.is_some()
|| !self.sealed_runs_newest_first.is_empty()
|| !self.retained_generations.is_empty()
|| !self.retained_generation_removals.is_empty()
}
}
/// Phase stored in the bounded transient status root.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum StatusPhase {
Pending(PendingPhase),
Resolving,
}
/// One transient operation reservation.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub struct StatusEntry {
pub operation_digest: ObjectId,
pub retry_until_micros: i64,
pub phase: StatusPhase,
pub shard_sequence: Option<u64>,
}
impl StatusEntry {
pub fn pending(
operation_digest: ObjectId,
retry_until_micros: i64,
phase: PendingPhase,
) -> Self {
Self {
operation_digest,
retry_until_micros,
phase: StatusPhase::Pending(phase),
shard_sequence: None,
}
}
pub fn resolving(
operation_digest: ObjectId,
retry_until_micros: i64,
shard_sequence: Option<u64>,
) -> Self {
Self {
operation_digest,
retry_until_micros,
phase: StatusPhase::Resolving,
shard_sequence,
}
}
pub fn transaction_status(self) -> TransactionStatus {
match self.phase {
StatusPhase::Pending(phase) => TransactionStatus::Pending {
operation_digest: self.operation_digest,
retry_until_micros: self.retry_until_micros,
phase,
},
StatusPhase::Resolving => TransactionStatus::Resolving {
operation_digest: self.operation_digest,
retry_until_micros: self.retry_until_micros,
shard_sequence: self.shard_sequence,
},
}
}
}
/// Result of atomically reconsidering a reservation against one status root.
///
/// The engine reruns this operation after an `ArcSwap` CAS failure. Existing
/// IDs are examined before the capacity bound, preserving attachment and
/// mismatch semantics under overload.
#[derive(Clone, Debug)]
pub enum StatusReservation {
Attached(StatusEntry),
OperationIdMismatch {
existing_digest: ObjectId,
submitted_digest: ObjectId,
},
AtCapacity {
limit: u64,
},
Inserted(OperationStatusRoot),
}
/// Observable capacity metrics for the status-root CAS owner.
///
/// These counters deliberately live beside, not inside, the immutable root.
/// The engine records occupancy only after a successful CAS and records a
/// rejection only after the retry loop reaches a final `AtCapacity` result;
/// speculative CAS attempts therefore cannot inflate either value.
#[derive(Debug, Default)]
pub struct OperationStatusMetrics {
occupancy: AtomicU64,
rejections: AtomicU64,
}
impl OperationStatusMetrics {
pub fn record_published(&self, root: &OperationStatusRoot) {
self.occupancy.store(root.len() as u64, Ordering::Relaxed);
}
pub fn record_rejection(&self) {
self.rejections.fetch_add(1, Ordering::Relaxed);
}
pub fn snapshot(&self) -> OperationStatusMetricSnapshot {
OperationStatusMetricSnapshot {
occupancy: self.occupancy.load(Ordering::Relaxed),
rejections: self.rejections.load(Ordering::Relaxed),
}
}
}
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
pub struct OperationStatusMetricSnapshot {
pub occupancy: u64,
pub rejections: u64,
}
/// Bounded immutable map of operations that have not reached terminal state.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct OperationStatusRoot {
entries: HashMap<OperationKey, StatusEntry>,
max_entries: u64,
}
impl OperationStatusRoot {
pub fn new(max_entries: u64) -> Self {
assert!(
max_entries > 0,
"max_status_entries is validated as nonzero at startup"
);
Self {
entries: HashMap::new(),
max_entries,
}
}
pub fn entries(&self) -> &HashMap<OperationKey, StatusEntry> {
&self.entries
}
pub fn get(&self, key: &OperationKey) -> Option<&StatusEntry> {
self.entries.get(key)
}
pub fn len(&self) -> usize {
self.entries.len()
}
pub fn is_empty(&self) -> bool {
self.entries.is_empty()
}
pub fn max_entries(&self) -> u64 {
self.max_entries
}
/// Reconsider and, when possible, immutably insert one reservation.
///
/// The caller must publish an `Inserted` root with CAS and retry this
/// method on contention. That retry is what makes the bound and insertion
/// atomic under concurrent reservations.
pub fn reserve(&self, key: OperationKey, entry: StatusEntry) -> StatusReservation {
if let Some(existing) = self.entries.get(&key).copied() {
if existing.operation_digest == entry.operation_digest {
return StatusReservation::Attached(existing);
}
return StatusReservation::OperationIdMismatch {
existing_digest: existing.operation_digest,
submitted_digest: entry.operation_digest,
};
}
if self.entries.len() as u64 >= self.max_entries {
return StatusReservation::AtCapacity {
limit: self.max_entries,
};
}
let mut entries = self.entries.clone();
entries.insert(key, entry);
StatusReservation::Inserted(Self {
entries,
max_entries: self.max_entries,
})
}
/// Replace an already reserved entry without applying the admission
/// bound. In particular, a transition to `Resolving` can never be evicted
/// or refused because unrelated entries filled the root afterward.
pub fn replace_existing(&self, key: OperationKey, entry: StatusEntry) -> Option<Self> {
let existing = self.entries.get(&key)?;
if existing.operation_digest != entry.operation_digest {
return None;
}
let mut entries = self.entries.clone();
entries.insert(key, entry);
Some(Self {
entries,
max_entries: self.max_entries,
})
}
pub fn without(&self, key: &OperationKey) -> Self {
let mut entries = self.entries.clone();
entries.remove(key);
Self {
entries,
max_entries: self.max_entries,
}
}
pub fn without_all<'a>(&self, keys: impl IntoIterator<Item = &'a OperationKey>) -> Self {
let mut entries = self.entries.clone();
for key in keys {
entries.remove(key);
}
Self {
entries,
max_entries: self.max_entries,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::index::{IndexKey, IndexLocation};
fn id(byte: u8) -> ObjectId {
ObjectId([byte; 32])
}
fn namespace(byte: u8) -> NamespaceId {
NamespaceId([byte; 32])
}
fn operation(byte: u8) -> OperationId {
OperationId([byte; 16])
}
fn repo(sequence: u64) -> Arc<RepoState> {
Arc::new(RepoState {
repo_sequence: sequence,
current_authority: id(1),
genesis_authority: id(2),
refs: TypedRefMap::new(),
lifecycle: NamespaceLifecycle::Active,
storage_mode: NamespaceStorageMode::Full,
previous_event_digest: id(3),
})
}
fn delta(namespace: NamespaceId, object: ObjectId, location: IndexLocation) -> Arc<IndexDelta> {
let mut delta = IndexDelta::new(100, 1 << 20);
delta
.insert(IndexKey::new(namespace, object), location)
.expect("insert");
Arc::new(delta)
}
fn subtree(
shard: u16,
shard_sequence: u64,
namespace: NamespaceId,
repo_sequence: u64,
index_delta: Arc<IndexDelta>,
) -> ShardSubtree {
let mut repositories = RepoMap::new();
repositories.insert(namespace, repo(repo_sequence));
ShardSubtree::new(
shard,
shard_sequence,
index_delta,
None,
Vector::new(),
repositories,
TerminalStatusMap::new(),
GenerationMap::new(),
)
}
#[test]
fn duplicate_subtree_is_idempotent_in_effect() {
let ns = namespace(1);
let object = id(7);
let location = IndexLocation {
segment_generation: 3,
frame_offset: 40,
frame_len: 50,
object_type: 1,
shard_sequence: 9,
};
let mut subtree = subtree(0, 9, ns, 1, delta(ns, object, location));
let key = OperationKey::new(ns, operation(4));
subtree.terminal_statuses.insert(
key,
TerminalStatusEntry::Expired(ReceiptTombstone {
operation_digest: id(8),
retry_until_micros: 100,
tombstone_until_micros: 200,
}),
);
let once = CommittedRoot::default().merge(&subtree);
let twice = once.merge(&subtree);
assert_eq!(twice.repositories().len(), 1);
assert_eq!(twice.terminal_statuses().len(), 1);
assert_eq!(twice.index().delta_layer_count(), 1);
assert_eq!(twice.shard_committed_sequence(0), Some(9));
assert_eq!(
twice.index().get(&IndexKey::new(ns, object)),
Some(location)
);
}
#[test]
fn subtree_can_prune_terminal_rows_without_rebuilding_the_table() {
let ns = namespace(1);
let removed = OperationKey::new(ns, operation(4));
let retained = OperationKey::new(ns, operation(5));
let mut statuses = TerminalStatusMap::new();
for key in [removed, retained] {
statuses.insert(
key,
TerminalStatusEntry::Expired(ReceiptTombstone {
operation_digest: id(key.operation_id.0[0]),
retry_until_micros: 100,
tombstone_until_micros: 200,
}),
);
}
let root = CommittedRoot::new(
RepoMap::new(),
LayeredObjectIndex::default(),
statuses,
ShardSequenceMap::new(),
GenerationMap::new(),
);
let mut prune = subtree(0, 1, ns, 1, Arc::new(IndexDelta::new(10, 1024)));
prune.terminal_status_removals.push_back(removed);
let merged = root.merge(&prune);
assert!(merged.terminal_status(&removed).is_none());
assert!(merged.terminal_status(&retained).is_some());
}
#[test]
fn concurrent_shards_merge_without_losing_the_other_subtree() {
let ns_a = namespace(1);
let ns_b = namespace(2);
let empty_a = Arc::new(IndexDelta::new(10, 1024));
let empty_b = Arc::new(IndexDelta::new(10, 1024));
let a = subtree(0, 4, ns_a, 4, empty_a);
let b = subtree(1, 8, ns_b, 7, empty_b);
let after_a = CommittedRoot::default().merge(&a);
let after_b_retry = after_a.merge(&b);
assert_eq!(after_b_retry.repo(&ns_a).unwrap().repo_sequence, 4);
assert_eq!(after_b_retry.repo(&ns_b).unwrap().repo_sequence, 7);
assert_eq!(after_b_retry.shard_committed_sequence(0), Some(4));
assert_eq!(after_b_retry.shard_committed_sequence(1), Some(8));
}
#[test]
fn sealed_publication_discards_only_covered_layers_from_its_shard() {
let ns_a = namespace(1);
let ns_b = namespace(2);
let a = subtree(
0,
1,
ns_a,
1,
delta(
ns_a,
id(10),
IndexLocation {
segment_generation: 1,
frame_offset: 1,
frame_len: 1,
object_type: 1,
shard_sequence: 1,
},
),
);
let b = subtree(
1,
1,
ns_b,
1,
delta(
ns_b,
id(11),
IndexLocation {
segment_generation: 1,
frame_offset: 2,
frame_len: 1,
object_type: 1,
shard_sequence: 1,
},
),
);
let root = CommittedRoot::default().merge(&a).merge(&b);
assert_eq!(root.index().delta_layer_count(), 2);
let mut seal = subtree(0, 2, ns_a, 2, Arc::new(IndexDelta::new(10, 1024)));
seal.sealed_through_shard_sequence = Some(2);
let sealed = root.merge(&seal);
assert_eq!(sealed.index().delta_layer_count(), 1);
let survivor = sealed.index().delta_layers().front().unwrap();
assert_eq!(survivor.shard_index, 1);
}
#[test]
fn untouched_repository_arc_is_shared_across_merge() {
let untouched_namespace = namespace(1);
let changed_namespace = namespace(2);
let untouched = repo(5);
let mut repositories = RepoMap::new();
repositories.insert(untouched_namespace, Arc::clone(&untouched));
let root = CommittedRoot::new(
repositories,
LayeredObjectIndex::default(),
TerminalStatusMap::new(),
ShardSequenceMap::new(),
GenerationMap::new(),
);
let update = subtree(
1,
1,
changed_namespace,
1,
Arc::new(IndexDelta::new(10, 1024)),
);
let merged = root.merge(&update);
assert!(Arc::ptr_eq(
merged.repo(&untouched_namespace).unwrap(),
&untouched
));
}
#[test]
fn status_reservation_checks_identity_before_capacity() {
let ns = namespace(1);
let key = OperationKey::new(ns, operation(1));
let entry = StatusEntry::pending(id(1), 100, PendingPhase::Queued);
let root = match OperationStatusRoot::new(1).reserve(key, entry) {
StatusReservation::Inserted(root) => root,
other => panic!("expected insertion, got {other:?}"),
};
assert!(matches!(
root.reserve(key, entry),
StatusReservation::Attached(found) if found == entry
));
assert!(matches!(
root.reserve(key, StatusEntry::pending(id(2), 100, PendingPhase::Queued)),
StatusReservation::OperationIdMismatch { .. }
));
assert!(matches!(
root.reserve(
OperationKey::new(ns, operation(2)),
StatusEntry::pending(id(3), 100, PendingPhase::Queued)
),
StatusReservation::AtCapacity { limit: 1 }
));
}
#[test]
fn resolving_transition_is_not_subject_to_the_capacity_bound() {
let ns = namespace(1);
let key = OperationKey::new(ns, operation(1));
let root = match OperationStatusRoot::new(1).reserve(
key,
StatusEntry::pending(id(1), 100, PendingPhase::Sequenced),
) {
StatusReservation::Inserted(root) => root,
other => panic!("expected insertion, got {other:?}"),
};
let resolving = StatusEntry::resolving(id(1), 100, Some(9));
let root = root
.replace_existing(key, resolving)
.expect("existing reservations transition despite full capacity");
assert_eq!(root.get(&key), Some(&resolving));
}
#[test]
fn status_metrics_observe_only_final_publications_and_rejections() {
let metrics = OperationStatusMetrics::default();
let root = OperationStatusRoot::new(1);
metrics.record_published(&root);
metrics.record_rejection();
metrics.record_rejection();
assert_eq!(
metrics.snapshot(),
OperationStatusMetricSnapshot {
occupancy: 0,
rejections: 2,
}
);
}
#[test]
fn retained_generation_reference_proof_uses_the_committed_root() {
let temp = tempfile::tempdir().expect("tempdir");
let segment_path = temp.path().join("1-1-1.seg");
let tail_path = temp.path().join("2.journal");
let projection_path = temp.path().join("3.stage-chunk");
std::fs::write(&segment_path, b"segment").expect("write");
std::fs::write(&tail_path, b"tail").expect("write");
std::fs::write(&projection_path, b"projection").expect("write");
let pinned = RetainedSegment::new(
1,
[7; 16],
1,
1,
PinnedFile::open(segment_path.clone()).expect("pin"),
);
let tail = RetainedTail::new(
2,
PinnedFile::open(tail_path.clone()).expect("pin active tail"),
);
let generation = Arc::new(RetainedGeneration::new(
GenerationId::new(0, 1),
Arc::from([pinned]),
Arc::from([]),
Arc::from([]),
Arc::from([tail]),
Arc::from([RetainedProjectionArtifact::new(
3,
ProjectionArtifactFormat::CanonicalStageChunkV1,
PinnedFile::open(projection_path.clone()).expect("pin projection artifact"),
)]),
));
let mut generations = GenerationMap::new();
generations.insert(generation.id, generation);
let root = CommittedRoot::new(
RepoMap::new(),
LayeredObjectIndex::default(),
TerminalStatusMap::new(),
ShardSequenceMap::new(),
generations,
);
assert!(root.references_path(&segment_path));
assert!(root.references_path(&tail_path));
assert!(root.references_path(&projection_path));
assert!(root.references_generation(GenerationId::new(0, 1)));
assert_eq!(
root.retained_tail(0, 2).map(RetainedTail::path),
Some(tail_path.as_path())
);
assert_eq!(
root.retained_segment(0, 1).map(RetainedSegment::path),
Some(segment_path.as_path())
);
assert_eq!(
root.retained_projection_artifact(0, 3)
.map(RetainedProjectionArtifact::path),
Some(projection_path.as_path())
);
assert!(matches!(
root.object_source(0, 3).expect("unambiguous source"),
Some(RetainedObjectSource::ProjectionArtifact(_))
));
assert!(root.retained_tail(1, 2).is_none());
assert!(root.retained_segment(1, 1).is_none());
assert!(!root.references_path(&temp.path().join("unreferenced.seg")));
}
}
Reference in New Issue View Git Blame Copy Permalink