use std::cmp::Ordering;
use super::errors::{err, Category, Result};
use super::types::{
Head, ENGINE_NAME, KNOWN_READER_FEATURES, KNOWN_WRITER_FEATURES, PROTOCOL_VERSION,
};
use super::version::{compare_engine_versions, max_engine_version};
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct RunningEngine {
pub(crate) version: String,
pub(crate) backup_format: u64,
}
fn unknown_features(declared: &[String], known: &[&str]) -> Vec<String> {
declared
.iter()
.filter(|feature| !known.contains(&feature.as_str()))
.cloned()
.collect()
}
pub(crate) fn assert_readable(head: &Head) -> Result<()> {
if head.protocol.version > PROTOCOL_VERSION {
return Err(err(
Category::ProtocolUnsupported,
format!(
"durable: object uses protocol version {}, this build implements {PROTOCOL_VERSION}",
head.protocol.version
),
));
}
let missing = unknown_features(&head.protocol.reader_features, KNOWN_READER_FEATURES);
if !missing.is_empty() {
return Err(err(
Category::ProtocolUnsupported,
format!(
"durable: object requires reader features this build does not implement: {}",
missing.join(", ")
),
)
.with_features(missing));
}
Ok(())
}
pub(crate) fn assert_writable(head: &Head) -> Result<()> {
let missing = unknown_features(&head.protocol.writer_features, KNOWN_WRITER_FEATURES);
if !missing.is_empty() {
return Err(err(
Category::ProtocolUnsupported,
format!(
"durable: object requires writer features this build does not implement: {}; \
it can still be opened read-only",
missing.join(", ")
),
)
.with_features(missing));
}
Ok(())
}
pub(crate) fn assert_engine_compatible(head: &Head, running: &RunningEngine) -> Result<()> {
if head.engine.name != ENGINE_NAME {
return Err(err(
Category::EngineIncompatible,
format!(
"durable: object was written by engine {:?}, not {ENGINE_NAME:?}",
head.engine.name
),
)
.with_bounds(head.engine.name.clone(), ENGINE_NAME));
}
if head.engine.backup_format > running.backup_format {
return Err(err(
Category::EngineIncompatible,
format!(
"durable: object uses archive format generation {}, and this engine restores up \
to {}; a newer chdb-core is required, since the format generation only moves \
when older archives can no longer be restored",
head.engine.backup_format, running.backup_format
),
)
.with_bounds(
head.engine.backup_format.to_string(),
running.backup_format.to_string(),
));
}
if compare_engine_versions(&running.version, &head.engine.min_reader)? == Ordering::Less {
return Err(err(
Category::EngineIncompatible,
format!(
"durable: object requires chdb {} or later to read, and this process runs {} \
(written by {})",
head.engine.min_reader, running.version, head.engine.version
),
)
.with_bounds(head.engine.min_reader.clone(), running.version.clone()));
}
Ok(())
}
pub(crate) fn raise_compatibility_floor(mut head: Head, running: &RunningEngine) -> Result<Head> {
head.engine.version = running.version.clone();
if running.backup_format > head.engine.backup_format {
head.engine.backup_format = running.backup_format;
}
head.engine.min_reader = max_engine_version(&head.engine.min_reader, &running.version)?;
Ok(head)
}
#[cfg(test)]
mod test {
use super::*;
use crate::durable::types::BACKUP_FORMAT_BASELINE;
fn running() -> RunningEngine {
RunningEngine {
version: "26.7.2".to_string(),
backup_format: BACKUP_FORMAT_BASELINE,
}
}
fn head() -> Head {
Head::cold("mem", "26.7.2-rc.2", BACKUP_FORMAT_BASELINE)
}
#[test]
fn a_producer_on_an_earlier_release_is_not_a_refusal() {
assert!(assert_engine_compatible(&head(), &running()).is_ok());
}
#[test]
fn a_reader_below_min_reader_is_refused() {
let mut head = head();
head.engine.min_reader = "26.8.0".to_string();
let error = assert_engine_compatible(&head, &running()).expect_err("too old to read");
assert_eq!(error.category(), Category::EngineIncompatible);
assert_eq!(error.expected(), Some("26.8.0"));
assert_eq!(error.actual(), Some("26.7.2"));
}
#[test]
fn an_archive_generation_beyond_this_engine_is_refused() {
let mut head = head();
head.engine.backup_format = BACKUP_FORMAT_BASELINE + 1;
let error = assert_engine_compatible(&head, &running()).expect_err("format too new");
assert_eq!(error.category(), Category::EngineIncompatible);
}
#[test]
fn another_engines_object_is_not_ours_to_open() {
let mut head = head();
head.engine.name = "duckdb".to_string();
let error = assert_engine_compatible(&head, &running()).expect_err("not chdb");
assert_eq!(error.category(), Category::EngineIncompatible);
}
#[test]
fn an_unknown_reader_feature_closes_the_object_and_a_writer_one_only_closes_the_lease() {
let mut reader_side = head();
reader_side.protocol.reader_features = vec!["parquet-wal".to_string()];
let error = assert_readable(&reader_side).expect_err("cannot interpret the bytes");
assert_eq!(error.category(), Category::ProtocolUnsupported);
assert_eq!(error.features(), ["parquet-wal"]);
let mut writer_side = head();
writer_side.protocol.writer_features = vec!["preamble".to_string()];
assert!(assert_readable(&writer_side).is_ok(), "reading stays sound");
assert_eq!(
assert_writable(&writer_side).unwrap_err().category(),
Category::ProtocolUnsupported
);
}
#[test]
fn a_future_protocol_version_closes_the_object() {
let mut head = head();
head.protocol.version = PROTOCOL_VERSION + 1;
assert_eq!(
assert_readable(&head).unwrap_err().category(),
Category::ProtocolUnsupported
);
}
#[test]
fn the_floor_only_ever_rises() {
let mut head = head();
head.engine.min_reader = "26.9.0".to_string();
let raised = raise_compatibility_floor(head, &running()).unwrap();
assert_eq!(raised.engine.min_reader, "26.9.0");
assert_eq!(
raised.engine.version, "26.7.2",
"the producer is still recorded"
);
}
}