mod model;
mod paths;
mod registered;
mod stream;
pub(crate) mod wire;
use crate::{
Dataset, ExecutionContext,
execution::{ExecutionError, ExecutionStage},
};
use std::io::{Read, Write};
use wire::{Budget, Codec};
pub const SNAPSHOT_VERSION: u32 = 1;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SnapshotLimits {
pub max_bytes: u64,
pub max_sample_bytes: usize,
pub max_metadata_bytes: usize,
pub max_working_bytes: usize,
pub max_depth: usize,
}
impl Default for SnapshotLimits {
fn default() -> Self {
Self {
max_bytes: 1024 * 1024 * 1024,
max_sample_bytes: 512 * 1024 * 1024,
max_metadata_bytes: 128 * 1024 * 1024,
max_working_bytes: 640 * 1024 * 1024,
max_depth: 128,
}
}
}
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum SnapshotError {
#[error(transparent)]
Execution(#[from] ExecutionError),
#[error(transparent)]
Io(#[from] std::io::Error),
#[error("truncated snapshot")]
Truncated,
#[error("snapshot integrity check failed")]
Integrity,
#[error("snapshot resource limit exceeded")]
ResourceLimit,
#[error("snapshot size overflow")]
SizeOverflow,
#[error("snapshot allocation failed")]
Allocation,
#[error("invalid snapshot structure")]
Structure,
#[error("unsupported snapshot version {0}")]
UnsupportedVersion(u32),
#[error("unsupported snapshot history version {0}")]
UnsupportedHistoryVersion(String),
#[error("invalid snapshot model: {0}")]
Validation(String),
#[error("snapshot scientific digest mismatch")]
DigestMismatch,
#[error("snapshot path encoding is unsupported on this platform")]
PathEncoding,
}
impl SnapshotError {
fn sampling_declaration(
error: crate::raw::model::sampling_declaration::SamplingDeclarationError,
) -> Self {
match error {
crate::raw::model::sampling_declaration::SamplingDeclarationError::Execution(error) => {
Self::Execution(error)
}
other => Self::Validation(crate::ReadError::from(other).to_string()),
}
}
}
#[derive(Clone, Copy, Debug)]
pub struct AcceptRecordedHistory;
pub fn decode_snapshot(
bytes: &[u8],
limits: SnapshotLimits,
) -> Result<CheckedSnapshot, SnapshotError> {
decode_snapshot_with_context(bytes, limits, &mut ExecutionContext::default())
}
pub fn decode_snapshot_with_context(
bytes: &[u8],
limits: SnapshotLimits,
control: &mut ExecutionContext<'_>,
) -> Result<CheckedSnapshot, SnapshotError> {
let mut remainder = bytes;
let checked = read_snapshot_with_context(&mut remainder, limits, control)?;
if !remainder.is_empty() {
return Err(SnapshotError::Structure);
}
Ok(checked)
}
#[derive(Debug)]
pub struct CheckedSnapshot {
dataset: Dataset,
}
impl CheckedSnapshot {
pub fn canonical_digests(&self) -> crate::provenance::CanonicalDatasetDigests {
self.dataset.canonical_digests()
}
pub fn descriptor(&self) -> crate::dataset::DescriptorRef<'_> {
self.dataset.descriptor()
}
pub fn metadata(&self) -> &crate::dataset::DatasetMetadata {
self.dataset.metadata()
}
pub fn restore(mut self, _accept: AcceptRecordedHistory) -> Dataset {
self.dataset.accept_archived_history();
self.dataset
}
}
pub fn write_snapshot(
dataset: &Dataset,
writer: &mut impl Write,
limits: SnapshotLimits,
) -> Result<(), SnapshotError> {
write_snapshot_with_context(dataset, writer, limits, &mut ExecutionContext::default())
}
pub fn write_snapshot_with_context(
dataset: &Dataset,
writer: &mut impl Write,
limits: SnapshotLimits,
control: &mut ExecutionContext<'_>,
) -> Result<(), SnapshotError> {
control.begin(ExecutionStage::Snapshot, None, None)?;
let mut ancestry = dataset
.as_processed()
.map(|p| (p.provenance().origin(), 0usize))
.into_iter()
.collect::<Vec<_>>();
while let Some((origin, depth)) = ancestry.pop() {
control.check_cancelled()?;
if depth > limits.max_depth.min(256) / 8 {
return Err(SnapshotError::ResourceLimit);
}
match origin {
crate::processed::ProcessedOrigin::External(boundary) => {
ancestry.push((boundary.parent().provenance().origin(), depth + 1))
}
crate::processed::ProcessedOrigin::Library(boundary) => {
for input in boundary.inputs() {
if let crate::derivation::DerivationInput::Processed(parent) = input {
ancestry.push((parent.provenance().origin(), depth + 1));
}
}
}
_ => {}
}
}
let mut budget = Budget::new(control, limits);
budget.reserve::<u8>(4096 * 16)?;
let value = dataset.to_wire(&mut budget)?;
let length = stream::size(&value, budget.control, 0, limits.max_depth)?;
if length.checked_add(60).is_none_or(|n| n > limits.max_bytes) {
return Err(SnapshotError::ResourceLimit);
}
stream::write(writer, &value, length, budget.control)
}
pub fn read_snapshot(
reader: &mut impl Read,
limits: SnapshotLimits,
) -> Result<CheckedSnapshot, SnapshotError> {
read_snapshot_with_context(reader, limits, &mut ExecutionContext::default())
}
pub fn read_snapshot_with_context(
reader: &mut impl Read,
limits: SnapshotLimits,
control: &mut ExecutionContext<'_>,
) -> Result<CheckedSnapshot, SnapshotError> {
control.begin(ExecutionStage::Snapshot, None, None)?;
let mut budget = Budget::new(control, limits);
budget.reserve::<u8>(4096 * 16)?;
let value = stream::read(reader, &mut budget)?;
let dataset = Dataset::from_wire(value, &mut budget)?;
dataset
.validate_recorded(budget.control)
.map_err(SnapshotError::model)?;
Ok(CheckedSnapshot { dataset })
}
impl SnapshotError {
fn model(error: crate::internal::ModelError) -> Self {
use crate::internal::ModelError as M;
match error {
M::Structure => Self::Structure,
M::Validation(message) => Self::Validation(message),
M::UnsupportedHistoryVersion(version) => Self::UnsupportedHistoryVersion(version),
M::DigestMismatch => Self::DigestMismatch,
M::Execution(error) => Self::Execution(error),
}
}
}