use std::collections::BTreeMap;
use std::fs::{self, File, OpenOptions};
use std::io::{self, BufWriter, Read, Seek, SeekFrom, Write};
use std::mem::size_of;
use std::path::{Component, Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Mutex;
use std::time::{SystemTime, UNIX_EPOCH};
use crate::error::{Neo4jStoreError, Result};
const JOURNAL_NAME: &str = ".littlegraph-write-journal";
const JOURNAL_TEMP_NAME: &str = ".littlegraph-write-journal.tmp";
const MAGIC: &[u8; 8] = b"LGJRNL01";
const COMMIT_MARKER: &[u8; 8] = b"COMMIT01";
const VERSION: u32 = 3;
const PREVIOUS_VERSION: u32 = 2;
const LEGACY_VERSION: u32 = 1;
const MAX_JOURNAL_BYTES: u64 = 1 << 30;
const MAX_PATCH_COUNT: usize = 1_000_000;
const JOURNAL_FIXED_BYTES: u64 = (MAGIC.len()
+ size_of::<u32>()
+ size_of::<u64>()
+ size_of::<u64>()
+ size_of::<u32>()
+ size_of::<u64>()
+ COMMIT_MARKER.len()) as u64;
const PATCH_FIXED_BYTES: u64 =
(size_of::<u16>() + size_of::<u64>() * 2 + size_of::<u32>() * 2) as u64;
static TRANSACTION_SEQUENCE: AtomicU64 = AtomicU64::new(1);
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum CommitCheckpoint {
AfterJournalCreate,
AfterJournalWrite,
AfterJournalSync,
AfterJournalPublish,
AfterDirectorySync,
AfterPatch(usize),
AfterStoreSync(usize),
#[cfg(test)]
AfterPartialMarker,
AfterMarkerWrite,
AfterMarkerSync,
BeforeJournalRemove,
AfterJournalRemove,
AfterFinalDirectorySync,
}
#[cfg(test)]
thread_local! {
static COMMIT_FAILURE: std::cell::Cell<Option<CommitCheckpoint>> = const { std::cell::Cell::new(None) };
}
#[cfg(test)]
pub(crate) fn fail_next_commit_after_patch(patch_index: usize) {
COMMIT_FAILURE.with(|failure| failure.set(Some(CommitCheckpoint::AfterPatch(patch_index))));
}
#[cfg(test)]
pub(super) fn fail_next_commit_after_store_sync(store_index: usize) {
COMMIT_FAILURE.with(|failure| failure.set(Some(CommitCheckpoint::AfterStoreSync(store_index))));
}
#[derive(Debug)]
pub(super) enum DurableCommitOutcome {
Committed,
CommittedStoragePoisoned(crate::Error),
RolledBack(crate::Error),
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(super) enum RecoveredTransaction {
None,
RolledBack,
Committed,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(super) struct RecoveryOutcome {
pub(super) transaction: RecoveredTransaction,
pub(super) journal_cleaned: bool,
}
#[allow(dead_code)]
#[derive(Debug)]
pub(super) struct DatabaseLock {
_file: File,
}
#[allow(dead_code)]
impl DatabaseLock {
pub(super) fn acquire(database_directory: &Path) -> Result<Self> {
let path = database_directory.join("database_lock");
let file = OpenOptions::new()
.read(true)
.write(true)
.create(true)
.truncate(false)
.open(&path)
.map_err(|source| Neo4jStoreError::DatabaseLock {
path: path.clone(),
source,
})?;
match file.try_lock() {
Ok(()) => Ok(Self { _file: file }),
Err(std::fs::TryLockError::WouldBlock) => {
Err(Neo4jStoreError::DatabaseLocked { path }.into())
}
Err(std::fs::TryLockError::Error(source)) => {
Err(Neo4jStoreError::DatabaseLock { path, source }.into())
}
}
}
pub(super) fn acquire_shared(database_directory: &Path) -> Result<Self> {
let path = database_directory.join("database_lock");
let file = OpenOptions::new()
.read(true)
.write(true)
.create(true)
.truncate(false)
.open(&path)
.map_err(|source| Neo4jStoreError::DatabaseLock {
path: path.clone(),
source,
})?;
match file.try_lock_shared() {
Ok(()) => Ok(Self { _file: file }),
Err(std::fs::TryLockError::WouldBlock) => {
Err(Neo4jStoreError::DatabaseLocked { path }.into())
}
Err(std::fs::TryLockError::Error(source)) => {
Err(Neo4jStoreError::DatabaseLock { path, source }.into())
}
}
}
}
#[derive(Debug)]
enum PatchData {
Memory(Vec<u8>),
Backed { offset: u64, len: usize },
}
impl PatchData {
fn len(&self) -> usize {
match self {
Self::Memory(bytes) => bytes.len(),
Self::Backed { len, .. } => *len,
}
}
fn is_empty(&self) -> bool {
self.len() == 0
}
}
#[derive(Debug)]
pub(super) struct FilePatch {
relative_path: PathBuf,
original_len: u64,
offset: u64,
before: PatchData,
after: PatchData,
}
#[derive(Debug)]
pub(super) struct ChangeSet {
database_directory: PathBuf,
store_identity: u64,
transaction_id: u64,
patches: Vec<FilePatch>,
max_journal_bytes: Option<u64>,
durable_bytes: u64,
backing: Option<Mutex<File>>,
}
#[allow(dead_code)]
impl ChangeSet {
pub(super) fn new(database_directory: impl AsRef<Path>) -> Result<Self> {
Self::new_with_limit(database_directory, None)
}
pub(super) fn new_with_limit(
database_directory: impl AsRef<Path>,
max_journal_bytes: Option<u64>,
) -> Result<Self> {
if max_journal_bytes.is_some_and(|limit| JOURNAL_FIXED_BYTES > limit) {
return Err(resource_limit());
}
let database_directory = database_directory.as_ref().to_path_buf();
let store_identity = store_identity(&database_directory)?;
let backing = tempfile::tempfile_in(&database_directory).map_err(|source| {
Neo4jStoreError::Write {
path: database_directory.join(".littlegraph-changeset"),
source,
}
})?;
Ok(Self {
database_directory,
store_identity,
transaction_id: next_transaction_id(store_identity),
patches: Vec::new(),
max_journal_bytes,
durable_bytes: JOURNAL_FIXED_BYTES,
backing: Some(Mutex::new(backing)),
})
}
pub(super) fn overwrite(
&mut self,
relative_path: impl AsRef<Path>,
offset: u64,
after: Vec<u8>,
) -> Result<()> {
if after.is_empty() {
return Err(invalid_journal(
self.journal_path(),
"overwrite patch cannot be empty",
));
}
let relative_path = validate_relative_path(relative_path.as_ref(), self.journal_path())?;
let path = store_path(
&self.database_directory,
&relative_path,
self.journal_path(),
)?;
let mut file = File::open(&path).map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?;
let original_len = file
.metadata()
.map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?
.len();
let end = offset
.checked_add(after.len() as u64)
.ok_or_else(|| invalid_journal(self.journal_path(), "patch end offset overflow"))?;
if end > original_len {
return Err(invalid_journal(
self.journal_path(),
format!(
"overwrite of {} ends at {end}, beyond file length {original_len}",
relative_path.display()
),
));
}
let projected_bytes =
self.projected_journal_bytes(&relative_path, after.len(), after.len())?;
let mut before = journal_buffer(after.len(), &self.journal_path())?;
file.seek(SeekFrom::Start(offset))
.and_then(|_| file.read_exact(&mut before))
.map_err(|source| Neo4jStoreError::Read { path, source })?;
let before = self.stage_image(before)?;
let after = self.stage_image(after)?;
self.patches.push(FilePatch {
relative_path,
original_len,
offset,
before,
after,
});
self.durable_bytes = projected_bytes;
Ok(())
}
pub(super) fn append(
&mut self,
relative_path: impl AsRef<Path>,
after: Vec<u8>,
) -> Result<u64> {
if after.is_empty() {
return Err(invalid_journal(
self.journal_path(),
"append patch cannot be empty",
));
}
let relative_path = validate_relative_path(relative_path.as_ref(), self.journal_path())?;
let path = store_path(
&self.database_directory,
&relative_path,
self.journal_path(),
)?;
let original_len = fs::metadata(&path)
.map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?
.len();
let projected_bytes = self.projected_journal_bytes(&relative_path, 0, after.len())?;
let after = self.stage_image(after)?;
self.patches.push(FilePatch {
relative_path,
original_len,
offset: original_len,
before: PatchData::Memory(Vec::new()),
after,
});
self.durable_bytes = projected_bytes;
Ok(original_len)
}
fn projected_journal_bytes(
&self,
relative_path: &Path,
before_len: usize,
after_len: usize,
) -> Result<u64> {
let patch_count =
self.patches.len().checked_add(1).ok_or_else(|| {
invalid_journal(self.journal_path(), "journal patch count overflow")
})?;
validate_patch_count(patch_count, &self.journal_path())?;
let path = relative_path
.to_str()
.ok_or_else(|| invalid_journal(self.journal_path(), "journal path is not UTF-8"))?;
u16::try_from(path.len())
.map_err(|_| invalid_journal(self.journal_path(), "journal path is too long"))?;
u32::try_from(before_len)
.map_err(|_| invalid_journal(self.journal_path(), "journal patch is too large"))?;
u32::try_from(after_len)
.map_err(|_| invalid_journal(self.journal_path(), "journal patch is too large"))?;
let projected = self
.durable_bytes
.checked_add(PATCH_FIXED_BYTES)
.and_then(|bytes| bytes.checked_add(path.len() as u64))
.and_then(|bytes| bytes.checked_add(before_len as u64))
.and_then(|bytes| bytes.checked_add(after_len as u64))
.ok_or_else(|| invalid_journal(self.journal_path(), "journal size overflow"))?;
if projected > MAX_JOURNAL_BYTES {
return Err(invalid_journal(
self.journal_path(),
format!("journal size {projected} exceeds limit {MAX_JOURNAL_BYTES}"),
));
}
if self
.max_journal_bytes
.is_some_and(|limit| projected > limit)
{
return Err(resource_limit());
}
Ok(projected)
}
fn stage_image(&self, bytes: Vec<u8>) -> Result<PatchData> {
let Some(backing) = &self.backing else {
return Ok(PatchData::Memory(bytes));
};
let mut backing = backing.lock().map_err(|_| {
invalid_journal(self.journal_path(), "change-set backing lock poisoned")
})?;
let offset = backing
.seek(SeekFrom::End(0))
.map_err(|source| Neo4jStoreError::Write {
path: self.database_directory.join(".littlegraph-changeset"),
source,
})?;
backing
.write_all(&bytes)
.map_err(|source| Neo4jStoreError::Write {
path: self.database_directory.join(".littlegraph-changeset"),
source,
})?;
Ok(PatchData::Backed {
offset,
len: bytes.len(),
})
}
fn read_image(&self, image: &PatchData) -> Result<Vec<u8>> {
match image {
PatchData::Memory(bytes) => Ok(bytes.clone()),
PatchData::Backed { offset, len } => {
let backing = self.backing.as_ref().ok_or_else(|| {
invalid_journal(self.journal_path(), "change-set backing file is missing")
})?;
let mut backing = backing.lock().map_err(|_| {
invalid_journal(self.journal_path(), "change-set backing lock poisoned")
})?;
let mut bytes = journal_buffer(*len, &self.journal_path())?;
backing
.seek(SeekFrom::Start(*offset))
.and_then(|_| backing.read_exact(&mut bytes))
.map_err(|source| Neo4jStoreError::Read {
path: self.database_directory.join(".littlegraph-changeset"),
source,
})?;
Ok(bytes)
}
}
}
fn rebase_images_to_journal(&mut self) -> Result<()> {
let journal_path = self.journal_path();
let journal = File::open(&journal_path).map_err(|source| Neo4jStoreError::Read {
path: journal_path.clone(),
source,
})?;
let mut offset = (MAGIC.len()
+ size_of::<u32>()
+ size_of::<u64>()
+ size_of::<u64>()
+ size_of::<u32>()) as u64;
for patch in &mut self.patches {
let path_len = patch
.relative_path
.to_str()
.expect("journal validation checked UTF-8 paths")
.len() as u64;
offset = offset
.checked_add(PATCH_FIXED_BYTES)
.and_then(|value| value.checked_add(path_len))
.ok_or_else(|| invalid_journal(&journal_path, "journal image offset overflow"))?;
let before_len = patch.before.len();
let after_len = patch.after.len();
patch.before = PatchData::Backed {
offset,
len: before_len,
};
offset = offset
.checked_add(before_len as u64)
.ok_or_else(|| invalid_journal(&journal_path, "journal image offset overflow"))?;
patch.after = PatchData::Backed {
offset,
len: after_len,
};
offset = offset
.checked_add(after_len as u64)
.ok_or_else(|| invalid_journal(&journal_path, "journal image offset overflow"))?;
}
self.backing = Some(Mutex::new(journal));
Ok(())
}
fn journal_path(&self) -> PathBuf {
self.database_directory.join(JOURNAL_NAME)
}
fn temporary_journal_path(&self) -> PathBuf {
self.database_directory.join(JOURNAL_TEMP_NAME)
}
fn validate(&self) -> Result<()> {
if self.patches.is_empty() {
return Err(invalid_journal(self.journal_path(), "change set is empty"));
}
validate_patch_count(self.patches.len(), &self.journal_path())?;
let mut ranges: BTreeMap<&Path, Vec<(u64, u64, u64)>> = BTreeMap::new();
for patch in &self.patches {
let (_, end) = validate_patch_shape(
&patch.relative_path,
patch.original_len,
patch.offset,
patch.before.len(),
patch.after.len(),
&self.journal_path(),
)?;
ranges.entry(&patch.relative_path).or_default().push((
patch.offset,
end,
patch.original_len,
));
}
for (path, ranges) in &mut ranges {
ranges.sort_unstable();
let original_len = ranges[0].2;
for pair in ranges.windows(2) {
if pair[0].1 > pair[1].0 {
return Err(invalid_journal(
self.journal_path(),
format!("overlapping patches for {}", path.display()),
));
}
if pair[1].2 != original_len {
return Err(invalid_journal(
self.journal_path(),
format!("inconsistent original length for {}", path.display()),
));
}
}
}
Ok(())
}
}
#[allow(dead_code)]
pub(super) fn commit(change_set: ChangeSet) -> Result<DurableCommitOutcome> {
commit_with_limit(change_set, None)
}
pub(super) fn commit_with_limit(
mut change_set: ChangeSet,
max_journal_bytes: Option<u64>,
) -> Result<DurableCommitOutcome> {
change_set.validate()?;
let journal_path = change_set.journal_path();
let temporary_journal_path = change_set.temporary_journal_path();
if path_entry_exists(&journal_path)? || path_entry_exists(&temporary_journal_path)? {
return Err(commit_recovery_error(
&change_set,
crate::Error::Transaction(crate::TransactionErrorKind::StoragePoisoned),
invalid_journal(
&journal_path,
"journal artifact already exists before commit",
),
));
}
change_set.patches.sort_by(|left, right| {
(&left.relative_path, left.offset).cmp(&(&right.relative_path, right.offset))
});
let encoded_len = encoded_journal_len(&change_set, MAX_JOURNAL_BYTES)?;
if max_journal_bytes.is_some_and(|limit| encoded_len as u64 > limit) {
return Err(crate::Error::Transaction(
crate::TransactionErrorKind::ResourceLimit,
));
}
let mut journal = match OpenOptions::new()
.write(true)
.create_new(true)
.open(&temporary_journal_path)
{
Ok(journal) => journal,
Err(source) => {
let commit_error: crate::Error = Neo4jStoreError::Write {
path: temporary_journal_path.clone(),
source,
}
.into();
return Ok(DurableCommitOutcome::RolledBack(commit_error));
}
};
if let Err(commit_error) = commit_checkpoint(&change_set, CommitCheckpoint::AfterJournalCreate)
{
drop(journal);
return cleanup_unpublished_journal(&change_set, commit_error);
}
let write_result: Result<()> = (|| {
let mut buffered = BufWriter::with_capacity(64 * 1024, &mut journal);
write_encoded(&change_set, &mut buffered)?;
buffered.flush().map_err(|source| Neo4jStoreError::Write {
path: temporary_journal_path.clone(),
source,
})?;
Ok(())
})();
if let Err(commit_error) = write_result {
drop(journal);
return cleanup_unpublished_journal(&change_set, commit_error);
}
if let Err(commit_error) = commit_checkpoint(&change_set, CommitCheckpoint::AfterJournalWrite) {
drop(journal);
return cleanup_unpublished_journal(&change_set, commit_error);
}
if let Err(source) = journal.sync_all() {
let commit_error: crate::Error = Neo4jStoreError::Write {
path: temporary_journal_path.clone(),
source,
}
.into();
drop(journal);
return cleanup_unpublished_journal(&change_set, commit_error);
}
if let Err(commit_error) = commit_checkpoint(&change_set, CommitCheckpoint::AfterJournalSync) {
drop(journal);
return cleanup_unpublished_journal(&change_set, commit_error);
}
drop(journal);
if let Err(source) = fs::rename(&temporary_journal_path, &journal_path) {
let commit_error = Neo4jStoreError::Write {
path: journal_path.clone(),
source,
}
.into();
return cleanup_unpublished_journal(&change_set, commit_error);
}
if let Err(commit_error) = commit_checkpoint(&change_set, CommitCheckpoint::AfterJournalPublish)
{
return recover_failed_commit(&change_set, commit_error, false);
}
if let Err(commit_error) = sync_directory(&change_set.database_directory) {
return recover_failed_commit(&change_set, commit_error, false);
}
if let Err(commit_error) = commit_checkpoint(&change_set, CommitCheckpoint::AfterDirectorySync)
{
return recover_failed_commit(&change_set, commit_error, false);
}
if let Err(commit_error) = change_set.rebase_images_to_journal() {
return recover_failed_commit(&change_set, commit_error, false);
}
let mut journal = match OpenOptions::new().append(true).open(&journal_path) {
Ok(journal) => journal,
Err(source) => {
let commit_error = Neo4jStoreError::Write {
path: journal_path.clone(),
source,
}
.into();
return recover_failed_commit(&change_set, commit_error, false);
}
};
if let Err(commit_error) = apply_patches(&change_set, PatchImage::After) {
drop(journal);
return recover_failed_commit(&change_set, commit_error, false);
}
#[cfg(test)]
if crash_checkpoint_configured(CommitCheckpoint::AfterPartialMarker) {
journal
.write_all(&COMMIT_MARKER[..3])
.map_err(|source| Neo4jStoreError::Write {
path: journal_path.clone(),
source,
})?;
injected_checkpoint(CommitCheckpoint::AfterPartialMarker)?;
unreachable!("configured crash checkpoint must terminate the process");
}
if let Err(source) = journal.write_all(COMMIT_MARKER) {
let commit_error = Neo4jStoreError::Write {
path: journal_path.clone(),
source,
}
.into();
drop(journal);
return recover_failed_commit(&change_set, commit_error, false);
}
if let Err(commit_error) = commit_checkpoint(&change_set, CommitCheckpoint::AfterMarkerWrite) {
drop(journal);
return recover_failed_commit(&change_set, commit_error, false);
}
if let Err(source) = journal.sync_all() {
let commit_error = Neo4jStoreError::Write {
path: journal_path.clone(),
source,
}
.into();
drop(journal);
return recover_failed_commit(&change_set, commit_error, false);
}
if let Err(commit_error) = commit_checkpoint(&change_set, CommitCheckpoint::AfterMarkerSync) {
drop(journal);
return recover_failed_commit(&change_set, commit_error, true);
}
drop(journal);
change_set.backing = None;
if let Err(commit_error) = commit_checkpoint(&change_set, CommitCheckpoint::BeforeJournalRemove)
{
return recover_failed_commit(&change_set, commit_error, true);
}
if let Err(source) = fs::remove_file(&journal_path) {
let commit_error = Neo4jStoreError::Write {
path: journal_path,
source,
}
.into();
return recover_failed_commit(&change_set, commit_error, true);
}
if let Err(commit_error) = commit_checkpoint(&change_set, CommitCheckpoint::AfterJournalRemove)
{
return recover_failed_commit(&change_set, commit_error, true);
}
if let Err(error) = sync_directory(&change_set.database_directory) {
return Ok(DurableCommitOutcome::CommittedStoragePoisoned(error));
}
if commit_checkpoint(&change_set, CommitCheckpoint::AfterFinalDirectorySync).is_err() {
return Ok(DurableCommitOutcome::Committed);
}
Ok(DurableCommitOutcome::Committed)
}
fn commit_checkpoint(change_set: &ChangeSet, checkpoint: CommitCheckpoint) -> Result<()> {
injected_checkpoint(checkpoint).map_err(|source| {
Neo4jStoreError::Write {
path: change_set.journal_path(),
source,
}
.into()
})
}
#[cfg(not(test))]
fn injected_checkpoint(_checkpoint: CommitCheckpoint) -> io::Result<()> {
Ok(())
}
#[cfg(test)]
fn injected_checkpoint(checkpoint: CommitCheckpoint) -> io::Result<()> {
if crash_checkpoint_configured(checkpoint) {
std::process::exit(86);
}
COMMIT_FAILURE.with(|failure| {
if failure.get() == Some(checkpoint) {
failure.set(None);
Err(io::Error::other(format!(
"injected commit failure at {checkpoint:?}"
)))
} else {
Ok(())
}
})
}
#[cfg(test)]
fn crash_checkpoint_configured(checkpoint: CommitCheckpoint) -> bool {
std::env::var("LITTLEGRAPH_TEST_CRASH_CHECKPOINT")
.is_ok_and(|configured| configured == format!("{checkpoint:?}"))
}
#[allow(dead_code)]
pub(super) fn recover(database_directory: &Path) -> Result<RecoveryOutcome> {
let journal_path = database_directory.join(JOURNAL_NAME);
let temporary_journal_path = database_directory.join(JOURNAL_TEMP_NAME);
let journal_exists = path_entry_exists(&journal_path)?;
let temporary_journal_exists = path_entry_exists(&temporary_journal_path)?;
if journal_exists && temporary_journal_exists {
return Err(invalid_journal(
&journal_path,
"both published and temporary journals exist",
));
}
if temporary_journal_exists {
fs::remove_file(&temporary_journal_path).map_err(|source| Neo4jStoreError::Write {
path: temporary_journal_path,
source,
})?;
sync_directory(database_directory)?;
return Ok(RecoveryOutcome {
transaction: RecoveredTransaction::RolledBack,
journal_cleaned: true,
});
}
if !journal_exists {
return Ok(RecoveryOutcome {
transaction: RecoveredTransaction::None,
journal_cleaned: false,
});
}
let bytes = read_journal(&journal_path)?;
let (change_set, committed) = decode(database_directory, &journal_path, &bytes)?;
if change_set.store_identity != store_identity(database_directory)? {
return Err(invalid_journal(
&journal_path,
"journal store identity does not match this database",
));
}
if committed {
verify_patches(&change_set, PatchImage::After)?;
} else {
apply_patches(&change_set, PatchImage::Before)?;
}
remove_journal(database_directory, &journal_path)?;
Ok(RecoveryOutcome {
transaction: if committed {
RecoveredTransaction::Committed
} else {
RecoveredTransaction::RolledBack
},
journal_cleaned: true,
})
}
pub(super) fn ensure_no_pending_journal(database_directory: &Path) -> Result<()> {
let journal_path = database_directory.join(JOURNAL_NAME);
let temporary_journal_path = database_directory.join(JOURNAL_TEMP_NAME);
if path_entry_exists(&journal_path)? {
return Err(invalid_journal(
journal_path,
"pending transaction requires writable recovery before the store can be opened",
));
}
if path_entry_exists(&temporary_journal_path)? {
return Err(invalid_journal(
temporary_journal_path,
"pending transaction requires writable recovery before the store can be opened",
));
}
Ok(())
}
fn cleanup_unpublished_journal(
change_set: &ChangeSet,
commit_error: crate::Error,
) -> Result<DurableCommitOutcome> {
match remove_journal(
&change_set.database_directory,
&change_set.temporary_journal_path(),
) {
Ok(()) => Ok(DurableCommitOutcome::RolledBack(commit_error)),
Err(recovery_error) => Err(commit_recovery_error(
change_set,
commit_error,
recovery_error,
)),
}
}
fn recover_failed_commit(
change_set: &ChangeSet,
commit_error: crate::Error,
marker_durable: bool,
) -> Result<DurableCommitOutcome> {
let journal_exists = match path_entry_exists(&change_set.journal_path()) {
Ok(exists) => exists,
Err(recovery_error) if marker_durable => {
return Ok(DurableCommitOutcome::CommittedStoragePoisoned(
commit_recovery_error(change_set, commit_error, recovery_error),
));
}
Err(recovery_error) => {
return Err(commit_recovery_error(
change_set,
commit_error,
recovery_error,
));
}
};
if !journal_exists {
return match sync_directory(&change_set.database_directory) {
Ok(()) if marker_durable => Ok(DurableCommitOutcome::Committed),
Ok(()) => Ok(DurableCommitOutcome::RolledBack(commit_error)),
Err(recovery_error) if marker_durable => {
Ok(DurableCommitOutcome::CommittedStoragePoisoned(
commit_recovery_error(change_set, commit_error, recovery_error),
))
}
Err(recovery_error) => Err(commit_recovery_error(
change_set,
commit_error,
recovery_error,
)),
};
}
if marker_durable {
if change_set.backing.is_none() {
return match recover(&change_set.database_directory) {
Ok(outcome)
if outcome.transaction == RecoveredTransaction::Committed
&& outcome.journal_cleaned =>
{
Ok(DurableCommitOutcome::Committed)
}
Ok(outcome) => Ok(DurableCommitOutcome::CommittedStoragePoisoned(
commit_recovery_error(
change_set,
commit_error,
invalid_journal(
change_set.journal_path(),
format!("unexpected durable recovery outcome {outcome:?}"),
),
),
)),
Err(recovery_error) => Ok(DurableCommitOutcome::CommittedStoragePoisoned(
commit_recovery_error(change_set, commit_error, recovery_error),
)),
};
}
return match verify_patches(change_set, PatchImage::After).and_then(|()| {
remove_journal(&change_set.database_directory, &change_set.journal_path())
}) {
Ok(()) => Ok(DurableCommitOutcome::Committed),
Err(recovery_error) => Ok(DurableCommitOutcome::CommittedStoragePoisoned(
commit_recovery_error(change_set, commit_error, recovery_error),
)),
};
}
match recover(&change_set.database_directory) {
Ok(outcome)
if outcome.transaction == RecoveredTransaction::Committed
&& outcome.journal_cleaned =>
{
Ok(DurableCommitOutcome::Committed)
}
Ok(outcome)
if outcome.transaction == RecoveredTransaction::RolledBack
&& outcome.journal_cleaned =>
{
Ok(DurableCommitOutcome::RolledBack(commit_error))
}
Ok(outcome) => Err(commit_recovery_error(
change_set,
commit_error,
invalid_journal(
change_set.journal_path(),
format!("unexpected recovery outcome {outcome:?}"),
),
)),
Err(recovery_error) => Err(commit_recovery_error(
change_set,
commit_error,
recovery_error,
)),
}
}
fn commit_recovery_error(
change_set: &ChangeSet,
commit_error: crate::Error,
recovery_error: crate::Error,
) -> crate::Error {
Neo4jStoreError::CommitRecovery {
path: change_set.database_directory.clone(),
commit_error: Box::new(commit_error),
recovery_error: Box::new(recovery_error),
}
.into()
}
#[derive(Clone, Copy)]
enum PatchImage {
Before,
After,
}
fn apply_patches(change_set: &ChangeSet, image: PatchImage) -> Result<()> {
let mut patches_by_path: BTreeMap<&Path, Vec<&FilePatch>> = BTreeMap::new();
for patch in &change_set.patches {
patches_by_path
.entry(&patch.relative_path)
.or_default()
.push(patch);
}
let mut patch_index = 0;
for (store_index, (relative_path, mut patches)) in patches_by_path.into_iter().enumerate() {
patches.sort_by_key(|patch| patch.offset);
let path = store_path(
&change_set.database_directory,
relative_path,
change_set.journal_path(),
)?;
let mut file = OpenOptions::new()
.read(true)
.write(true)
.open(&path)
.map_err(|source| Neo4jStoreError::Write {
path: path.clone(),
source,
})?;
let current_len = file
.metadata()
.map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?
.len();
validate_store_length(change_set, relative_path, &patches, current_len)?;
for patch in patches {
if patch.before.is_empty() {
apply_append_patch(change_set, patch, &path, &mut file, image)?;
} else {
apply_overwrite_patch(change_set, patch, &path, &mut file, image)?;
}
if let Err(source) = injected_checkpoint(CommitCheckpoint::AfterPatch(patch_index)) {
return Err(Neo4jStoreError::Write {
path: path.clone(),
source,
}
.into());
}
patch_index += 1;
}
file.sync_all().map_err(|source| Neo4jStoreError::Write {
path: path.clone(),
source,
})?;
if let Err(source) = injected_checkpoint(CommitCheckpoint::AfterStoreSync(store_index)) {
return Err(Neo4jStoreError::Write { path, source }.into());
}
}
Ok(())
}
fn apply_overwrite_patch(
change_set: &ChangeSet,
patch: &FilePatch,
path: &Path,
file: &mut File,
image: PatchImage,
) -> Result<()> {
let (expected_image, replacement_image) = match image {
PatchImage::Before => (&patch.after, &patch.before),
PatchImage::After => (&patch.before, &patch.after),
};
let mut current = journal_buffer(expected_image.len(), &change_set.journal_path())?;
file.seek(SeekFrom::Start(patch.offset))
.and_then(|_| file.read_exact(&mut current))
.map_err(|source| Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
})?;
let matches_expected = {
let expected = change_set.read_image(expected_image)?;
current == expected
};
let replacement = change_set.read_image(replacement_image)?;
if !matches_expected && current != replacement {
return Err(invalid_journal(
change_set.journal_path(),
format!(
"{} at offset {} matches neither journal image",
patch.relative_path.display(),
patch.offset
),
));
}
file.seek(SeekFrom::Start(patch.offset))
.and_then(|_| file.write_all(&replacement))
.map_err(|source| Neo4jStoreError::Write {
path: path.to_path_buf(),
source,
})?;
Ok(())
}
fn verify_append_patch(
change_set: &ChangeSet,
patch: &FilePatch,
path: &Path,
image: PatchImage,
) -> Result<()> {
let expected_len = match image {
PatchImage::Before => patch.original_len,
PatchImage::After => patch
.original_len
.checked_add(patch.after.len() as u64)
.ok_or_else(|| invalid_journal(change_set.journal_path(), "append length overflow"))?,
};
let mut file = File::open(path).map_err(|source| Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
})?;
let actual_len = file
.metadata()
.map_err(|source| Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
})?
.len();
if actual_len != expected_len {
return Err(invalid_journal(
change_set.journal_path(),
format!(
"committed append {} has length {actual_len}, expected {expected_len}",
patch.relative_path.display()
),
));
}
if matches!(image, PatchImage::After) {
let after = change_set.read_image(&patch.after)?;
let mut current = journal_buffer(patch.after.len(), &change_set.journal_path())?;
file.seek(SeekFrom::Start(patch.offset))
.and_then(|_| file.read_exact(&mut current))
.map_err(|source| Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
})?;
if current != after {
return Err(invalid_journal(
change_set.journal_path(),
format!(
"committed append {} does not match store",
patch.relative_path.display()
),
));
}
}
Ok(())
}
fn apply_append_patch(
change_set: &ChangeSet,
patch: &FilePatch,
path: &Path,
file: &mut File,
image: PatchImage,
) -> Result<()> {
let after = change_set.read_image(&patch.after)?;
let appended_len = patch
.original_len
.checked_add(patch.after.len() as u64)
.ok_or_else(|| invalid_journal(change_set.journal_path(), "append length overflow"))?;
let current_len = file
.metadata()
.map_err(|source| Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
})?
.len();
if current_len != patch.original_len && current_len != appended_len {
return Err(invalid_journal(
change_set.journal_path(),
format!(
"{} length {current_len} matches neither append journal image",
patch.relative_path.display()
),
));
}
if current_len == appended_len {
let mut current = journal_buffer(patch.after.len(), &change_set.journal_path())?;
file.seek(SeekFrom::Start(patch.offset))
.and_then(|_| file.read_exact(&mut current))
.map_err(|source| Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
})?;
if current != after {
return Err(invalid_journal(
change_set.journal_path(),
format!(
"{} appended bytes do not match the journal image",
patch.relative_path.display()
),
));
}
}
match image {
PatchImage::Before => file.set_len(patch.original_len),
PatchImage::After if current_len == patch.original_len => file
.seek(SeekFrom::Start(patch.offset))
.and_then(|_| file.write_all(&after)),
PatchImage::After => Ok(()),
}
.map_err(|source| Neo4jStoreError::Write {
path: path.to_path_buf(),
source,
})?;
Ok(())
}
fn verify_patches(change_set: &ChangeSet, image: PatchImage) -> Result<()> {
let mut patches_by_path: BTreeMap<&Path, Vec<&FilePatch>> = BTreeMap::new();
for patch in &change_set.patches {
patches_by_path
.entry(&patch.relative_path)
.or_default()
.push(patch);
}
for (relative_path, patches) in patches_by_path {
let path = store_path(
&change_set.database_directory,
relative_path,
change_set.journal_path(),
)?;
let current_len = fs::metadata(&path)
.map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?
.len();
validate_store_length(change_set, relative_path, &patches, current_len)?;
for patch in patches {
if patch.before.is_empty() {
verify_append_patch(change_set, patch, &path, image)?;
continue;
}
let expected = change_set.read_image(match image {
PatchImage::Before => &patch.before,
PatchImage::After => &patch.after,
})?;
let mut file = File::open(&path).map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?;
let mut current = journal_buffer(expected.len(), &change_set.journal_path())?;
file.seek(SeekFrom::Start(patch.offset))
.and_then(|_| file.read_exact(&mut current))
.map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?;
if current != expected {
return Err(invalid_journal(
change_set.journal_path(),
format!(
"committed patch {} does not match store",
patch.relative_path.display()
),
));
}
}
}
Ok(())
}
fn validate_store_length(
change_set: &ChangeSet,
relative_path: &Path,
patches: &[&FilePatch],
current_len: u64,
) -> Result<()> {
let original_len = patches[0].original_len;
let appended_len = patches
.iter()
.find(|patch| patch.before.is_empty())
.map(|patch| {
original_len
.checked_add(patch.after.len() as u64)
.ok_or_else(|| invalid_journal(change_set.journal_path(), "append length overflow"))
})
.transpose()?;
if current_len != original_len && Some(current_len) != appended_len {
return Err(invalid_journal(
change_set.journal_path(),
format!(
"{} length {current_len} matches neither journal file image",
relative_path.display()
),
));
}
Ok(())
}
#[cfg(test)]
fn encode(change_set: &ChangeSet) -> Result<Vec<u8>> {
let encoded_len = encoded_journal_len(change_set, MAX_JOURNAL_BYTES)?;
let content_len = encoded_len - COMMIT_MARKER.len();
let mut bytes = Vec::new();
bytes.try_reserve_exact(content_len).map_err(|error| {
invalid_journal(
change_set.journal_path(),
format!("cannot allocate journal buffer: {error}"),
)
})?;
write_encoded(change_set, &mut bytes)?;
debug_assert_eq!(bytes.len(), content_len);
Ok(bytes)
}
fn write_encoded(change_set: &ChangeSet, writer: &mut impl Write) -> Result<()> {
let mut checksum = 0xcbf2_9ce4_8422_2325_u64;
write_checksummed(change_set, writer, &mut checksum, MAGIC)?;
write_checksummed(change_set, writer, &mut checksum, &VERSION.to_be_bytes())?;
write_checksummed(
change_set,
writer,
&mut checksum,
&change_set.store_identity.to_be_bytes(),
)?;
write_checksummed(
change_set,
writer,
&mut checksum,
&change_set.transaction_id.to_be_bytes(),
)?;
let patch_count = u32::try_from(change_set.patches.len())
.expect("journal length validation checked the patch count");
write_checksummed(
change_set,
writer,
&mut checksum,
&patch_count.to_be_bytes(),
)?;
for patch in &change_set.patches {
let path = patch
.relative_path
.to_str()
.expect("journal length validation checked UTF-8 paths");
let path_len =
u16::try_from(path.len()).expect("journal length validation checked path lengths");
let before_len = u32::try_from(patch.before.len())
.expect("journal length validation checked patch lengths");
let after_len = u32::try_from(patch.after.len())
.expect("journal length validation checked patch lengths");
write_checksummed(change_set, writer, &mut checksum, &path_len.to_be_bytes())?;
write_checksummed(change_set, writer, &mut checksum, path.as_bytes())?;
write_checksummed(
change_set,
writer,
&mut checksum,
&patch.original_len.to_be_bytes(),
)?;
write_checksummed(
change_set,
writer,
&mut checksum,
&patch.offset.to_be_bytes(),
)?;
write_checksummed(change_set, writer, &mut checksum, &before_len.to_be_bytes())?;
write_checksummed(change_set, writer, &mut checksum, &after_len.to_be_bytes())?;
let before = change_set.read_image(&patch.before)?;
write_checksummed(change_set, writer, &mut checksum, &before)?;
drop(before);
let after = change_set.read_image(&patch.after)?;
write_checksummed(change_set, writer, &mut checksum, &after)?;
}
writer
.write_all(&checksum.to_be_bytes())
.map_err(|source| Neo4jStoreError::Write {
path: change_set.temporary_journal_path(),
source,
})?;
Ok(())
}
fn write_checksummed(
change_set: &ChangeSet,
writer: &mut impl Write,
checksum: &mut u64,
bytes: &[u8],
) -> Result<()> {
writer
.write_all(bytes)
.map_err(|source| Neo4jStoreError::Write {
path: change_set.temporary_journal_path(),
source,
})?;
*checksum = extend_checksum(*checksum, bytes);
Ok(())
}
fn encoded_journal_len(change_set: &ChangeSet, max_journal_bytes: u64) -> Result<usize> {
validate_patch_count(change_set.patches.len(), &change_set.journal_path())?;
let mut length =
MAGIC.len() + size_of::<u32>() + size_of::<u64>() + size_of::<u64>() + size_of::<u32>();
for patch in &change_set.patches {
let path = patch.relative_path.to_str().ok_or_else(|| {
invalid_journal(change_set.journal_path(), "journal path is not UTF-8")
})?;
u16::try_from(path.len())
.map_err(|_| invalid_journal(change_set.journal_path(), "journal path is too long"))?;
u32::try_from(patch.before.len()).map_err(|_| {
invalid_journal(change_set.journal_path(), "journal patch is too large")
})?;
u32::try_from(patch.after.len()).map_err(|_| {
invalid_journal(change_set.journal_path(), "journal patch is too large")
})?;
length = length
.checked_add(size_of::<u16>())
.and_then(|value| value.checked_add(path.len()))
.and_then(|value| value.checked_add(size_of::<u64>() * 2))
.and_then(|value| value.checked_add(size_of::<u32>() * 2))
.and_then(|value| value.checked_add(patch.before.len()))
.and_then(|value| value.checked_add(patch.after.len()))
.ok_or_else(|| invalid_journal(change_set.journal_path(), "journal size overflow"))?;
}
length = length
.checked_add(size_of::<u64>())
.and_then(|value| value.checked_add(COMMIT_MARKER.len()))
.ok_or_else(|| invalid_journal(change_set.journal_path(), "journal size overflow"))?;
let length_u64 = u64::try_from(length)
.map_err(|_| invalid_journal(change_set.journal_path(), "journal size overflow"))?;
if length_u64 > max_journal_bytes {
return Err(invalid_journal(
change_set.journal_path(),
format!("journal size {length_u64} exceeds limit {max_journal_bytes}"),
));
}
Ok(length)
}
fn validate_patch_count(patch_count: usize, journal_path: &Path) -> Result<u32> {
if patch_count > MAX_PATCH_COUNT {
return Err(invalid_journal(
journal_path,
format!("journal patch count {patch_count} exceeds limit {MAX_PATCH_COUNT}"),
));
}
u32::try_from(patch_count)
.map_err(|_| invalid_journal(journal_path, "journal patch count exceeds u32"))
}
fn decode(
database_directory: &Path,
journal_path: &Path,
bytes: &[u8],
) -> Result<(ChangeSet, bool)> {
let (content, committed) = decode_journal_envelope(bytes, journal_path)?;
let mut cursor = Cursor::new(content, journal_path);
if cursor.take(8)? != MAGIC {
return Err(invalid_journal(journal_path, "invalid journal magic"));
}
let version = cursor.u32()?;
if version != VERSION && version != PREVIOUS_VERSION && version != LEGACY_VERSION {
return Err(invalid_journal(journal_path, "unsupported journal version"));
}
let store_identity = cursor.u64()?;
let transaction_id = if version == VERSION {
let transaction_id = cursor.u64()?;
if transaction_id == 0 {
return Err(invalid_journal(
journal_path,
"journal transaction ID is zero",
));
}
transaction_id
} else {
0
};
let patch_count = cursor.u32()? as usize;
validate_patch_count(patch_count, journal_path)?;
validate_patch_count_fits_content(
patch_count,
cursor.remaining().len(),
version,
journal_path,
)?;
let mut patches = Vec::new();
patches.try_reserve_exact(patch_count).map_err(|error| {
invalid_journal(
journal_path,
format!("cannot allocate journal patch table: {error}"),
)
})?;
for _ in 0..patch_count {
let path_len = cursor.u16()? as usize;
let path = std::str::from_utf8(cursor.take(path_len)?)
.map_err(|_| invalid_journal(journal_path, "journal path is not UTF-8"))?;
let relative_path = validate_relative_path(Path::new(path), journal_path)?;
let original_len = cursor.u64()?;
let offset = cursor.u64()?;
let before_len = cursor.u32()? as usize;
let after_len = if version == LEGACY_VERSION {
before_len
} else {
cursor.u32()? as usize
};
validate_patch_shape(
&relative_path,
original_len,
offset,
before_len,
after_len,
journal_path,
)?;
let before = copy_journal_image(cursor.take(before_len)?, journal_path)?;
let after = copy_journal_image(cursor.take(after_len)?, journal_path)?;
patches.push(FilePatch {
relative_path,
original_len,
offset,
before: PatchData::Memory(before),
after: PatchData::Memory(after),
});
}
if !cursor.remaining().is_empty() {
return Err(invalid_journal(journal_path, "journal has trailing data"));
}
let change_set = ChangeSet {
database_directory: database_directory.to_path_buf(),
store_identity,
transaction_id,
patches,
max_journal_bytes: None,
durable_bytes: JOURNAL_FIXED_BYTES,
backing: None,
};
change_set.validate()?;
Ok((change_set, committed))
}
fn validate_patch_count_fits_content(
patch_count: usize,
remaining_bytes: usize,
version: u32,
journal_path: &Path,
) -> Result<()> {
let minimum_patch_bytes = size_of::<u16>()
+ 1
+ size_of::<u64>() * 2
+ size_of::<u32>()
+ if version == LEGACY_VERSION {
2
} else {
size_of::<u32>() + 1
};
if patch_count > remaining_bytes / minimum_patch_bytes {
return Err(invalid_journal(
journal_path,
format!(
"journal patch count {patch_count} cannot fit in the remaining {remaining_bytes} bytes"
),
));
}
Ok(())
}
fn validate_patch_shape(
relative_path: &Path,
original_len: u64,
offset: u64,
before_len: usize,
after_len: usize,
journal_path: &Path,
) -> Result<(bool, u64)> {
if after_len == 0 {
return Err(invalid_journal(
journal_path,
"journal patch cannot be empty",
));
}
let is_append = before_len == 0 && offset == original_len;
if before_len != after_len && !is_append {
return Err(invalid_journal(
journal_path,
"patch is neither a fixed-size overwrite nor an append",
));
}
let after_len = u64::try_from(after_len)
.map_err(|_| invalid_journal(journal_path, "patch range overflow"))?;
let end = offset
.checked_add(after_len)
.ok_or_else(|| invalid_journal(journal_path, "patch range overflow"))?;
if !is_append && end > original_len {
return Err(invalid_journal(
journal_path,
format!(
"overwrite of {} ends at {end}, beyond original length {original_len}",
relative_path.display()
),
));
}
Ok((is_append, end))
}
fn copy_journal_image(image: &[u8], journal_path: &Path) -> Result<Vec<u8>> {
let mut copy = Vec::new();
copy.try_reserve_exact(image.len()).map_err(|error| {
invalid_journal(
journal_path,
format!("cannot allocate journal patch image: {error}"),
)
})?;
copy.extend_from_slice(image);
Ok(copy)
}
fn journal_buffer(length: usize, journal_path: &Path) -> Result<Vec<u8>> {
let mut buffer = Vec::new();
buffer.try_reserve_exact(length).map_err(|error| {
invalid_journal(
journal_path,
format!("cannot allocate journal I/O buffer: {error}"),
)
})?;
buffer.resize(length, 0);
Ok(buffer)
}
fn decode_journal_envelope<'a>(bytes: &'a [u8], journal_path: &Path) -> Result<(&'a [u8], bool)> {
if bytes.len() < size_of::<u64>() {
return Err(invalid_journal(journal_path, "journal is truncated"));
}
let marker_lengths = std::iter::once(0)
.chain(std::iter::once(COMMIT_MARKER.len()))
.chain((1..COMMIT_MARKER.len()).rev());
for marker_len in marker_lengths {
if marker_len > 0 && !bytes.ends_with(&COMMIT_MARKER[..marker_len]) {
continue;
}
let Some(content_len) = bytes
.len()
.checked_sub(marker_len)
.and_then(|length| length.checked_sub(size_of::<u64>()))
else {
continue;
};
let content = &bytes[..content_len];
let stored_checksum = u64::from_be_bytes(
bytes[content_len..content_len + size_of::<u64>()]
.try_into()
.expect("checksum slice has eight bytes"),
);
if checksum(content) == stored_checksum {
return Ok((content, marker_len == COMMIT_MARKER.len()));
}
}
Err(invalid_journal(journal_path, "journal checksum mismatch"))
}
struct Cursor<'a> {
bytes: &'a [u8],
offset: usize,
journal_path: &'a Path,
}
impl<'a> Cursor<'a> {
fn new(bytes: &'a [u8], journal_path: &'a Path) -> Self {
Self {
bytes,
offset: 0,
journal_path,
}
}
fn take(&mut self, length: usize) -> Result<&'a [u8]> {
let end = self
.offset
.checked_add(length)
.ok_or_else(|| invalid_journal(self.journal_path, "journal offset overflow"))?;
let value = self
.bytes
.get(self.offset..end)
.ok_or_else(|| invalid_journal(self.journal_path, "journal is truncated"))?;
self.offset = end;
Ok(value)
}
fn u16(&mut self) -> Result<u16> {
Ok(u16::from_be_bytes(
self.take(2)?.try_into().expect("two bytes"),
))
}
fn u32(&mut self) -> Result<u32> {
Ok(u32::from_be_bytes(
self.take(4)?.try_into().expect("four bytes"),
))
}
fn u64(&mut self) -> Result<u64> {
Ok(u64::from_be_bytes(
self.take(8)?.try_into().expect("eight bytes"),
))
}
fn remaining(&self) -> &[u8] {
&self.bytes[self.offset..]
}
}
fn validate_relative_path(path: &Path, journal_path: impl AsRef<Path>) -> Result<PathBuf> {
if path.as_os_str().is_empty()
|| path.is_absolute()
|| path == Path::new(JOURNAL_NAME)
|| path == Path::new(JOURNAL_TEMP_NAME)
|| path
.components()
.any(|component| !matches!(component, Component::Normal(_)))
{
return Err(invalid_journal(
journal_path.as_ref(),
format!("unsafe store path {}", path.display()),
));
}
Ok(path.to_path_buf())
}
fn store_path(
database_directory: &Path,
relative: &Path,
journal_path: impl AsRef<Path>,
) -> Result<PathBuf> {
validate_relative_path(relative, journal_path.as_ref())?;
let path = database_directory.join(relative);
let canonical_database =
database_directory
.canonicalize()
.map_err(|source| Neo4jStoreError::Read {
path: database_directory.to_path_buf(),
source,
})?;
let canonical_path = path
.canonicalize()
.map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?;
if !canonical_path.starts_with(canonical_database) {
return Err(invalid_journal(
journal_path.as_ref(),
"store path escapes database directory",
));
}
Ok(canonical_path)
}
fn store_identity(database_directory: &Path) -> Result<u64> {
let path = database_directory.join("neostore");
let mut file = File::open(&path).map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?;
let mut buffer = [0_u8; 8192];
let mut hash = 0xcbf2_9ce4_8422_2325_u64;
loop {
let read = file
.read(&mut buffer)
.map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?;
if read == 0 {
return Ok(hash);
}
hash = extend_checksum(hash, &buffer[..read]);
}
}
fn checksum(bytes: &[u8]) -> u64 {
extend_checksum(0xcbf2_9ce4_8422_2325_u64, bytes)
}
fn extend_checksum(mut hash: u64, bytes: &[u8]) -> u64 {
for byte in bytes {
hash ^= *byte as u64;
hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
}
hash
}
fn next_transaction_id(store_identity: u64) -> u64 {
let timestamp = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|duration| duration.as_nanos() as u64)
.unwrap_or_default();
let sequence = TRANSACTION_SEQUENCE.fetch_add(1, Ordering::Relaxed);
let transaction_id = timestamp ^ store_identity.rotate_left(17) ^ sequence;
if transaction_id == 0 {
sequence.max(1)
} else {
transaction_id
}
}
fn remove_journal(database_directory: &Path, journal_path: &Path) -> Result<()> {
fs::remove_file(journal_path).map_err(|source| Neo4jStoreError::Write {
path: journal_path.to_path_buf(),
source,
})?;
sync_directory(database_directory)
}
fn sync_directory(database_directory: &Path) -> Result<()> {
File::open(database_directory)
.and_then(|directory| directory.sync_all())
.map_err(|source| Neo4jStoreError::Write {
path: database_directory.to_path_buf(),
source,
})?;
Ok(())
}
fn invalid_journal(path: impl AsRef<Path>, message: impl Into<String>) -> crate::Error {
Neo4jStoreError::InvalidJournal {
path: path.as_ref().to_path_buf(),
message: message.into(),
}
.into()
}
fn resource_limit() -> crate::Error {
crate::Error::Transaction(crate::TransactionErrorKind::ResourceLimit)
}
fn path_entry_exists(path: &Path) -> Result<bool> {
match fs::symlink_metadata(path) {
Ok(_) => Ok(true),
Err(source) if source.kind() == io::ErrorKind::NotFound => Ok(false),
Err(source) => Err(Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
}
.into()),
}
}
fn read_journal(journal_path: &Path) -> Result<Vec<u8>> {
let entry = fs::symlink_metadata(journal_path).map_err(|source| Neo4jStoreError::Read {
path: journal_path.to_path_buf(),
source,
})?;
if !entry.file_type().is_file() {
return Err(invalid_journal(
journal_path,
"published journal is not a regular file",
));
}
let file = File::open(journal_path).map_err(|source| Neo4jStoreError::Read {
path: journal_path.to_path_buf(),
source,
})?;
let journal_len = file
.metadata()
.map_err(|source| Neo4jStoreError::Read {
path: journal_path.to_path_buf(),
source,
})?
.len();
if journal_len > MAX_JOURNAL_BYTES {
return Err(invalid_journal(
journal_path,
format!("journal size {journal_len} exceeds limit {MAX_JOURNAL_BYTES}"),
));
}
let capacity = usize::try_from(journal_len)
.map_err(|_| invalid_journal(journal_path, "journal size exceeds address space"))?;
let mut bytes = Vec::new();
bytes.try_reserve_exact(capacity).map_err(|error| {
invalid_journal(
journal_path,
format!("cannot allocate journal input buffer: {error}"),
)
})?;
file.take(MAX_JOURNAL_BYTES + 1)
.read_to_end(&mut bytes)
.map_err(|source| Neo4jStoreError::Read {
path: journal_path.to_path_buf(),
source,
})?;
if bytes.len() as u64 > MAX_JOURNAL_BYTES {
return Err(invalid_journal(
journal_path,
format!("journal size exceeds limit {MAX_JOURNAL_BYTES} while being read"),
));
}
Ok(bytes)
}
#[cfg(test)]
mod tests {
use super::*;
use std::collections::BTreeSet;
use std::process::Command;
fn database() -> tempfile::TempDir {
let directory = tempfile::tempdir().unwrap();
fs::write(directory.path().join("neostore"), b"store-identity").unwrap();
fs::write(directory.path().join("records.db"), b"abcdefghij").unwrap();
directory
}
fn change_set(directory: &Path) -> ChangeSet {
let mut change_set = ChangeSet::new(directory).unwrap();
change_set
.overwrite("records.db", 2, b"XYZ".to_vec())
.unwrap();
change_set
}
fn persist_journal(change_set: &ChangeSet, committed: bool) {
let mut bytes = encode(change_set).unwrap();
if committed {
bytes.extend_from_slice(COMMIT_MARKER);
}
fs::write(change_set.journal_path(), bytes).unwrap();
}
fn encode_version_2(change_set: &ChangeSet) -> Vec<u8> {
let mut bytes = encode(change_set).unwrap();
bytes[8..12].copy_from_slice(&PREVIOUS_VERSION.to_be_bytes());
bytes.drain(20..28);
let checksum_offset = bytes.len() - 8;
let updated_checksum = checksum(&bytes[..checksum_offset]);
bytes[checksum_offset..].copy_from_slice(&updated_checksum.to_be_bytes());
bytes
}
fn encode_version_1(change_set: &ChangeSet) -> Vec<u8> {
let mut bytes = Vec::new();
bytes.extend_from_slice(MAGIC);
bytes.extend_from_slice(&LEGACY_VERSION.to_be_bytes());
bytes.extend_from_slice(&change_set.store_identity.to_be_bytes());
bytes.extend_from_slice(&(change_set.patches.len() as u32).to_be_bytes());
for patch in &change_set.patches {
assert_eq!(patch.before.len(), patch.after.len());
let path = patch.relative_path.to_str().unwrap();
bytes.extend_from_slice(&(path.len() as u16).to_be_bytes());
bytes.extend_from_slice(path.as_bytes());
bytes.extend_from_slice(&patch.original_len.to_be_bytes());
bytes.extend_from_slice(&patch.offset.to_be_bytes());
bytes.extend_from_slice(&(patch.before.len() as u32).to_be_bytes());
bytes.extend_from_slice(&change_set.read_image(&patch.before).unwrap());
bytes.extend_from_slice(&change_set.read_image(&patch.after).unwrap());
}
let checksum = checksum(&bytes);
bytes.extend_from_slice(&checksum.to_be_bytes());
bytes
}
fn assert_recovery(directory: &Path, expected: RecoveredTransaction) {
let outcome = recover(directory).unwrap();
assert_eq!(outcome.transaction, expected);
assert_eq!(
outcome.journal_cleaned,
expected != RecoveredTransaction::None
);
}
fn set_commit_failure(checkpoint: CommitCheckpoint) {
COMMIT_FAILURE.with(|failure| {
assert!(failure.replace(Some(checkpoint)).is_none());
});
}
fn multi_store_change_set(directory: &Path) -> ChangeSet {
fs::write(directory.join("records.db.id"), b"0123456789").unwrap();
let mut change_set = ChangeSet::new(directory).unwrap();
change_set
.overwrite("records.db", 1, b"XYZ".to_vec())
.unwrap();
change_set
.overwrite("records.db", 6, b"UVW".to_vec())
.unwrap();
change_set
.overwrite("records.db.id", 3, b"ID".to_vec())
.unwrap();
change_set
}
fn assert_before_images(directory: &Path) {
assert_eq!(
fs::read(directory.join("records.db")).unwrap(),
b"abcdefghij"
);
assert_eq!(
fs::read(directory.join("records.db.id")).unwrap(),
b"0123456789"
);
assert!(!directory.join(JOURNAL_NAME).exists());
assert!(!directory.join(JOURNAL_TEMP_NAME).exists());
}
fn assert_after_images(directory: &Path) {
assert_eq!(
fs::read(directory.join("records.db")).unwrap(),
b"aXYZefUVWj"
);
assert_eq!(
fs::read(directory.join("records.db.id")).unwrap(),
b"012ID56789"
);
assert!(!directory.join(JOURNAL_NAME).exists());
assert!(!directory.join(JOURNAL_TEMP_NAME).exists());
}
fn run_crashing_commit(directory: &Path, checkpoint: CommitCheckpoint) {
let output = Command::new(std::env::current_exe().unwrap())
.args([
"--exact",
"neo4j_storage::transaction::tests::crash_commit_child",
"--nocapture",
])
.env("LITTLEGRAPH_TEST_CRASH_DATABASE", directory)
.env(
"LITTLEGRAPH_TEST_CRASH_CHECKPOINT",
format!("{checkpoint:?}"),
)
.output()
.unwrap();
assert_eq!(
output.status.code(),
Some(86),
"child output:\nstdout:\n{}\nstderr:\n{}",
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr)
);
}
#[test]
fn crash_commit_child() {
let Ok(directory) = std::env::var("LITTLEGRAPH_TEST_CRASH_DATABASE") else {
return;
};
let change_set = multi_store_change_set(Path::new(&directory));
let _ = commit(change_set);
panic!("configured crash checkpoint was not reached");
}
#[test]
fn database_lock_is_exclusive() {
let directory = database();
let first = DatabaseLock::acquire(directory.path()).unwrap();
let error = DatabaseLock::acquire(directory.path()).unwrap_err();
assert!(matches!(
error,
crate::Error::Neo4jStore(Neo4jStoreError::DatabaseLocked { .. })
));
drop(first);
DatabaseLock::acquire(directory.path()).unwrap();
}
#[test]
fn store_identity_streaming_matches_the_in_memory_checksum() {
let directory = tempfile::tempdir().unwrap();
let bytes = (0..20_000)
.map(|index| (index % 251) as u8)
.collect::<Vec<_>>();
fs::write(directory.path().join("neostore"), &bytes).unwrap();
assert_eq!(store_identity(directory.path()).unwrap(), checksum(&bytes));
}
#[test]
fn commit_applies_all_patches_and_removes_the_journal() {
let directory = database();
let change_set = change_set(directory.path());
let journal_path = change_set.journal_path();
assert!(matches!(
commit(change_set).unwrap(),
DurableCommitOutcome::Committed
));
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abXYZfghij"
);
assert!(!journal_path.exists());
}
#[test]
fn commit_refuses_to_overwrite_an_existing_journal_artifact() {
let directory = database();
let change_set = change_set(directory.path());
fs::write(
directory.path().join(JOURNAL_TEMP_NAME),
b"unrecovered transaction",
)
.unwrap();
let error = commit(change_set).unwrap_err();
let crate::Error::Neo4jStore(Neo4jStoreError::CommitRecovery {
commit_error,
recovery_error,
..
}) = error
else {
panic!("expected commit recovery error");
};
assert!(matches!(
*commit_error,
crate::Error::Transaction(crate::TransactionErrorKind::StoragePoisoned)
));
assert!(matches!(
*recovery_error,
crate::Error::Neo4jStore(Neo4jStoreError::InvalidJournal { .. })
));
assert_eq!(
fs::read(directory.path().join(JOURNAL_TEMP_NAME)).unwrap(),
b"unrecovered transaction"
);
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
}
#[cfg(unix)]
#[test]
fn commit_refuses_a_dangling_temporary_journal_symlink() {
use std::os::unix::fs::symlink;
let directory = database();
let change_set = change_set(directory.path());
let temporary_journal = directory.path().join(JOURNAL_TEMP_NAME);
symlink(directory.path().join("missing-target"), &temporary_journal).unwrap();
let error = commit(change_set).unwrap_err();
assert!(matches!(
error,
crate::Error::Neo4jStore(Neo4jStoreError::CommitRecovery { .. })
));
assert!(fs::symlink_metadata(&temporary_journal)
.unwrap()
.file_type()
.is_symlink());
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
}
#[cfg(unix)]
#[test]
fn recovery_rejects_a_published_journal_symlink() {
use std::os::unix::fs::symlink;
let directory = database();
let change_set = change_set(directory.path());
let outside = tempfile::NamedTempFile::new().unwrap();
let journal_bytes = encode(&change_set).unwrap();
fs::write(outside.path(), &journal_bytes).unwrap();
symlink(outside.path(), change_set.journal_path()).unwrap();
let error = recover(directory.path()).unwrap_err();
assert!(error
.to_string()
.contains("published journal is not a regular file"));
assert_eq!(fs::read(outside.path()).unwrap(), journal_bytes);
assert!(fs::symlink_metadata(change_set.journal_path())
.unwrap()
.file_type()
.is_symlink());
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
}
#[test]
fn failures_before_the_commit_marker_restore_all_before_images() {
let checkpoints = [
CommitCheckpoint::AfterJournalCreate,
CommitCheckpoint::AfterJournalWrite,
CommitCheckpoint::AfterJournalSync,
CommitCheckpoint::AfterJournalPublish,
CommitCheckpoint::AfterDirectorySync,
CommitCheckpoint::AfterPatch(0),
CommitCheckpoint::AfterPatch(1),
CommitCheckpoint::AfterPatch(2),
CommitCheckpoint::AfterStoreSync(0),
CommitCheckpoint::AfterStoreSync(1),
];
for checkpoint in checkpoints {
let directory = database();
let change_set = multi_store_change_set(directory.path());
set_commit_failure(checkpoint);
let outcome = commit(change_set).unwrap();
assert!(matches!(outcome, DurableCommitOutcome::RolledBack(_)));
assert_before_images(directory.path());
}
}
#[test]
fn failures_after_a_complete_commit_marker_report_committed() {
let checkpoints = [
CommitCheckpoint::AfterMarkerWrite,
CommitCheckpoint::AfterMarkerSync,
CommitCheckpoint::BeforeJournalRemove,
CommitCheckpoint::AfterJournalRemove,
];
for checkpoint in checkpoints {
let directory = database();
let change_set = multi_store_change_set(directory.path());
set_commit_failure(checkpoint);
let outcome = commit(change_set).unwrap();
assert!(matches!(outcome, DurableCommitOutcome::Committed));
assert_after_images(directory.path());
}
}
#[test]
fn process_exit_before_the_commit_marker_recovers_before_images() {
let checkpoints = [
CommitCheckpoint::AfterJournalCreate,
CommitCheckpoint::AfterJournalWrite,
CommitCheckpoint::AfterJournalSync,
CommitCheckpoint::AfterJournalPublish,
CommitCheckpoint::AfterDirectorySync,
CommitCheckpoint::AfterPatch(0),
CommitCheckpoint::AfterPatch(1),
CommitCheckpoint::AfterPatch(2),
CommitCheckpoint::AfterStoreSync(0),
CommitCheckpoint::AfterStoreSync(1),
CommitCheckpoint::AfterPartialMarker,
];
for checkpoint in checkpoints {
let directory = database();
multi_store_change_set(directory.path());
run_crashing_commit(directory.path(), checkpoint);
let outcome = recover(directory.path()).unwrap();
assert_eq!(outcome.transaction, RecoveredTransaction::RolledBack);
assert!(outcome.journal_cleaned);
assert_before_images(directory.path());
}
}
#[test]
fn process_exit_after_a_complete_marker_recovers_after_images() {
let checkpoints = [
CommitCheckpoint::AfterMarkerWrite,
CommitCheckpoint::AfterMarkerSync,
CommitCheckpoint::BeforeJournalRemove,
];
for checkpoint in checkpoints {
let directory = database();
multi_store_change_set(directory.path());
run_crashing_commit(directory.path(), checkpoint);
let outcome = recover(directory.path()).unwrap();
assert_eq!(outcome.transaction, RecoveredTransaction::Committed);
assert!(outcome.journal_cleaned);
assert_after_images(directory.path());
}
}
#[test]
fn process_exit_after_journal_removal_leaves_durable_after_images() {
for checkpoint in [
CommitCheckpoint::AfterJournalRemove,
CommitCheckpoint::AfterFinalDirectorySync,
] {
let directory = database();
multi_store_change_set(directory.path());
run_crashing_commit(directory.path(), checkpoint);
let outcome = recover(directory.path()).unwrap();
assert_eq!(outcome.transaction, RecoveredTransaction::None);
assert!(!outcome.journal_cleaned);
assert_after_images(directory.path());
}
}
#[test]
fn commit_atomically_appends_to_a_store_file() {
let directory = database();
let mut change_set = ChangeSet::new(directory.path()).unwrap();
assert_eq!(
change_set.append("records.db", b"klmnop".to_vec()).unwrap(),
10
);
assert!(matches!(
commit(change_set).unwrap(),
DurableCommitOutcome::Committed
));
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghijklmnop"
);
}
#[test]
fn commit_combines_an_append_and_overwrite_on_the_same_file() {
let directory = database();
let mut change_set = ChangeSet::new(directory.path()).unwrap();
change_set.append("records.db", b"klmnop".to_vec()).unwrap();
change_set
.overwrite("records.db", 2, b"XYZ".to_vec())
.unwrap();
assert!(matches!(
commit(change_set).unwrap(),
DurableCommitOutcome::Committed
));
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abXYZfghijklmnop"
);
}
#[test]
fn recovery_rolls_back_an_uncommitted_partial_write_idempotently() {
let directory = database();
let change_set = change_set(directory.path());
persist_journal(&change_set, false);
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
assert_recovery(directory.path(), RecoveredTransaction::RolledBack);
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
assert_recovery(directory.path(), RecoveredTransaction::None);
}
#[test]
fn recovery_discards_an_unpublished_partial_journal() {
let directory = database();
fs::write(
directory.path().join(JOURNAL_TEMP_NAME),
b"partial journal header",
)
.unwrap();
assert_recovery(directory.path(), RecoveredTransaction::RolledBack);
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
assert!(!directory.path().join(JOURNAL_TEMP_NAME).exists());
}
#[test]
fn recovery_rejects_simultaneous_published_and_temporary_journals() {
let directory = database();
let change_set = change_set(directory.path());
persist_journal(&change_set, false);
fs::write(directory.path().join(JOURNAL_TEMP_NAME), b"partial").unwrap();
let error = recover(directory.path()).unwrap_err();
assert!(error.to_string().contains("both published and temporary"));
assert!(change_set.journal_path().exists());
assert!(directory.path().join(JOURNAL_TEMP_NAME).exists());
}
#[test]
fn recovery_accepts_a_version_2_journal_without_a_transaction_id() {
let directory = database();
let change_set = change_set(directory.path());
fs::write(change_set.journal_path(), encode_version_2(&change_set)).unwrap();
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
assert_recovery(directory.path(), RecoveredTransaction::RolledBack);
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
}
#[test]
fn recovery_accepts_a_version_1_fixed_size_journal() {
let directory = database();
let change_set = change_set(directory.path());
fs::write(change_set.journal_path(), encode_version_1(&change_set)).unwrap();
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
assert_recovery(directory.path(), RecoveredTransaction::RolledBack);
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
}
#[test]
fn recovery_rejects_a_zero_version_3_transaction_id() {
let directory = database();
let change_set = change_set(directory.path());
let mut bytes = encode(&change_set).unwrap();
bytes[20..28].fill(0);
let checksum_offset = bytes.len() - 8;
let updated_checksum = checksum(&bytes[..checksum_offset]);
bytes[checksum_offset..].copy_from_slice(&updated_checksum.to_be_bytes());
fs::write(change_set.journal_path(), bytes).unwrap();
let error = recover(directory.path()).unwrap_err();
assert!(error.to_string().contains("transaction ID is zero"));
}
#[test]
fn failed_commit_before_the_marker_reports_a_definite_rollback() {
let directory = database();
let change_set = change_set(directory.path());
persist_journal(&change_set, false);
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
let outcome = recover_failed_commit(
&change_set,
crate::Error::Execution("injected store write failure".to_owned()),
false,
)
.unwrap();
assert!(matches!(outcome, DurableCommitOutcome::RolledBack(_)));
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
assert!(!change_set.journal_path().exists());
}
#[test]
fn failed_cleanup_after_the_marker_still_reports_committed() {
let directory = database();
let change_set = change_set(directory.path());
persist_journal(&change_set, true);
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
let outcome = recover_failed_commit(
&change_set,
crate::Error::Execution("injected journal cleanup failure".to_owned()),
true,
)
.unwrap();
assert!(matches!(outcome, DurableCommitOutcome::Committed));
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abXYZfghij"
);
assert!(!change_set.journal_path().exists());
}
#[test]
fn durable_marker_uses_the_validated_change_set_if_the_journal_is_corrupt() {
let directory = database();
let change_set = change_set(directory.path());
fs::write(change_set.journal_path(), b"corrupt journal").unwrap();
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
let outcome = recover_failed_commit(
&change_set,
crate::Error::Execution("injected post-marker failure".to_owned()),
true,
)
.unwrap();
assert!(matches!(outcome, DurableCommitOutcome::Committed));
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abXYZfghij"
);
assert!(!change_set.journal_path().exists());
}
#[test]
fn durable_marker_with_failed_final_sync_reports_committed_and_poisoned() {
let directory = database();
let moved_parent = tempfile::tempdir().unwrap();
let change_set = change_set(directory.path());
fs::rename(directory.path(), moved_parent.path().join("database")).unwrap();
let outcome = recover_failed_commit(
&change_set,
crate::Error::Transaction(crate::TransactionErrorKind::StoragePoisoned),
true,
)
.unwrap();
let DurableCommitOutcome::CommittedStoragePoisoned(error) = outcome else {
panic!("expected committed poisoned outcome");
};
assert!(matches!(
error,
crate::Error::Neo4jStore(Neo4jStoreError::CommitRecovery { .. })
));
}
#[cfg(unix)]
#[test]
fn failed_journal_lookup_preserves_commit_context_and_durable_outcome() {
use std::os::unix::fs::symlink;
let directory = database();
let moved_parent = tempfile::tempdir().unwrap();
let database_path = directory.path().to_path_buf();
let change_set = change_set(&database_path);
fs::rename(&database_path, moved_parent.path().join("database")).unwrap();
symlink(&database_path, &database_path).unwrap();
let rollback_error = recover_failed_commit(
&change_set,
crate::Error::Execution("injected pre-marker failure".to_owned()),
false,
)
.unwrap_err();
let committed_outcome = recover_failed_commit(
&change_set,
crate::Error::Execution("injected post-marker failure".to_owned()),
true,
)
.unwrap();
fs::remove_file(&database_path).unwrap();
assert!(matches!(
rollback_error,
crate::Error::Neo4jStore(Neo4jStoreError::CommitRecovery { .. })
));
let DurableCommitOutcome::CommittedStoragePoisoned(committed_error) = committed_outcome
else {
panic!("expected committed poisoned outcome");
};
assert!(matches!(
committed_error,
crate::Error::Neo4jStore(Neo4jStoreError::CommitRecovery { .. })
));
}
#[test]
fn complete_marker_observed_after_a_sync_error_reports_committed() {
let directory = database();
let change_set = change_set(directory.path());
persist_journal(&change_set, true);
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
let outcome = recover_failed_commit(
&change_set,
crate::Error::Execution("injected marker sync failure".to_owned()),
false,
)
.unwrap();
assert!(matches!(outcome, DurableCommitOutcome::Committed));
assert!(!change_set.journal_path().exists());
}
#[test]
fn recovery_truncates_an_uncommitted_append_idempotently() {
let directory = database();
let mut change_set = ChangeSet::new(directory.path()).unwrap();
change_set.append("records.db", b"klmnop".to_vec()).unwrap();
persist_journal(&change_set, false);
fs::write(directory.path().join("records.db"), b"abcdefghijklmnop").unwrap();
assert_recovery(directory.path(), RecoveredTransaction::RolledBack);
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
}
#[test]
fn recovery_rolls_back_store_and_id_header_patches_together() {
let directory = database();
fs::write(directory.path().join("records.db.id"), b"0123456789").unwrap();
let mut change_set = ChangeSet::new(directory.path()).unwrap();
change_set
.overwrite("records.db", 2, b"XYZ".to_vec())
.unwrap();
change_set
.overwrite("records.db.id", 4, b"ID".to_vec())
.unwrap();
persist_journal(&change_set, false);
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
fs::write(directory.path().join("records.db.id"), b"0123ID6789").unwrap();
assert_recovery(directory.path(), RecoveredTransaction::RolledBack);
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
assert_eq!(
fs::read(directory.path().join("records.db.id")).unwrap(),
b"0123456789"
);
}
#[test]
fn recovery_rejects_an_overwrite_store_with_an_unexpected_length() {
let directory = database();
let change_set = change_set(directory.path());
persist_journal(&change_set, false);
fs::write(directory.path().join("records.db"), b"abXYZfghij-extra").unwrap();
let error = recover(directory.path()).unwrap_err();
assert!(error
.to_string()
.contains("length 16 matches neither journal file image"));
assert!(change_set.journal_path().exists());
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abXYZfghij-extra"
);
}
#[test]
fn recovery_rolls_back_after_a_partial_commit_marker() {
let directory = database();
let change_set = change_set(directory.path());
let mut bytes = encode(&change_set).unwrap();
bytes.extend_from_slice(&COMMIT_MARKER[..3]);
fs::write(change_set.journal_path(), bytes).unwrap();
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
assert_recovery(directory.path(), RecoveredTransaction::RolledBack);
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
}
#[test]
fn recovery_does_not_mistake_a_checksum_suffix_for_a_partial_marker() {
let directory = database();
let mut change_set = change_set(directory.path());
let bytes = (1..=10_000)
.find_map(|transaction_id| {
change_set.transaction_id = transaction_id;
let bytes = encode(&change_set).unwrap();
bytes.ends_with(&COMMIT_MARKER[..1]).then_some(bytes)
})
.expect("find a checksum ending with the marker's first byte");
assert!(!bytes.ends_with(COMMIT_MARKER));
fs::write(change_set.journal_path(), bytes).unwrap();
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
assert_recovery(directory.path(), RecoveredTransaction::RolledBack);
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
}
#[test]
fn recovery_finishes_cleanup_after_the_commit_marker() {
let directory = database();
let change_set = change_set(directory.path());
persist_journal(&change_set, true);
fs::write(directory.path().join("records.db"), b"abXYZfghij").unwrap();
assert_recovery(directory.path(), RecoveredTransaction::Committed);
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abXYZfghij"
);
assert!(!change_set.journal_path().exists());
}
#[test]
fn committed_append_recovery_requires_the_complete_after_image() {
let directory = database();
let mut change_set = ChangeSet::new(directory.path()).unwrap();
change_set.append("records.db", b"klmnop".to_vec()).unwrap();
persist_journal(&change_set, true);
let error = recover(directory.path()).unwrap_err();
assert!(error.to_string().contains("expected 16"));
}
#[test]
fn recovery_rejects_corrupt_and_foreign_journals() {
let directory = database();
let change_set = change_set(directory.path());
persist_journal(&change_set, false);
let journal_path = change_set.journal_path();
let mut bytes = fs::read(&journal_path).unwrap();
bytes[12] ^= 0xff;
fs::write(&journal_path, bytes).unwrap();
let error = recover(directory.path()).unwrap_err();
assert!(error.to_string().contains("checksum mismatch"));
fs::remove_file(&journal_path).unwrap();
persist_journal(&change_set, false);
fs::write(directory.path().join("neostore"), b"different-store").unwrap();
let error = recover(directory.path()).unwrap_err();
assert!(error.to_string().contains("identity does not match"));
}
#[test]
fn decode_rejects_an_empty_patch_before_copying_images() {
let directory = database();
let change_set = change_set(directory.path());
let mut bytes = encode(&change_set).unwrap();
let patch_header =
MAGIC.len() + size_of::<u32>() + size_of::<u64>() + size_of::<u64>() + size_of::<u32>();
let path_len =
u16::from_be_bytes(bytes[patch_header..patch_header + 2].try_into().unwrap()) as usize;
let after_len_offset = patch_header
+ size_of::<u16>()
+ path_len
+ size_of::<u64>()
+ size_of::<u64>()
+ size_of::<u32>();
bytes[after_len_offset..after_len_offset + size_of::<u32>()].fill(0);
let checksum_offset = bytes.len() - size_of::<u64>();
let updated_checksum = checksum(&bytes[..checksum_offset]);
bytes[checksum_offset..].copy_from_slice(&updated_checksum.to_be_bytes());
let error = decode(directory.path(), &change_set.journal_path(), &bytes).unwrap_err();
assert!(error.to_string().contains("journal patch cannot be empty"));
}
#[test]
fn recovery_rejects_journal_resource_limits_without_removing_evidence() {
let directory = database();
let change_set = change_set(directory.path());
let journal_path = change_set.journal_path();
let oversized = OpenOptions::new()
.write(true)
.create_new(true)
.open(&journal_path)
.unwrap();
oversized.set_len(MAX_JOURNAL_BYTES + 1).unwrap();
drop(oversized);
let error = recover(directory.path()).unwrap_err();
assert!(error.to_string().contains("journal size"));
assert!(error.to_string().contains("exceeds limit"));
assert!(journal_path.exists());
fs::remove_file(&journal_path).unwrap();
let mut bytes = encode(&change_set).unwrap();
bytes[28..32].copy_from_slice(&((MAX_PATCH_COUNT + 1) as u32).to_be_bytes());
let checksum_offset = bytes.len() - 8;
let updated_checksum = checksum(&bytes[..checksum_offset]);
bytes[checksum_offset..].copy_from_slice(&updated_checksum.to_be_bytes());
fs::write(&journal_path, bytes).unwrap();
let error = recover(directory.path()).unwrap_err();
assert!(error.to_string().contains("journal patch count"));
assert!(error.to_string().contains("exceeds limit"));
assert!(journal_path.exists());
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
let mut bytes = encode(&change_set).unwrap();
bytes[28..32].copy_from_slice(&(MAX_PATCH_COUNT as u32).to_be_bytes());
let checksum_offset = bytes.len() - size_of::<u64>();
let updated_checksum = checksum(&bytes[..checksum_offset]);
bytes[checksum_offset..].copy_from_slice(&updated_checksum.to_be_bytes());
fs::write(&journal_path, bytes).unwrap();
let error = recover(directory.path()).unwrap_err();
assert!(error.to_string().contains("journal patch count"));
assert!(error.to_string().contains("cannot fit"));
assert!(journal_path.exists());
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
}
#[test]
fn commit_encoding_accounts_for_the_durable_marker_before_allocating() {
let directory = database();
let change_set = change_set(directory.path());
let encoded = encode(&change_set).unwrap();
let durable_len = encoded.len() + COMMIT_MARKER.len();
assert_eq!(
encoded_journal_len(&change_set, durable_len as u64).unwrap(),
durable_len
);
let error = encoded_journal_len(&change_set, (durable_len - 1) as u64).unwrap_err();
assert!(error.to_string().contains("journal size"));
assert!(error.to_string().contains("exceeds limit"));
}
#[test]
fn configurable_journal_limit_accepts_the_exact_durable_size() {
let exact_len = JOURNAL_FIXED_BYTES + PATCH_FIXED_BYTES + "records.db".len() as u64 + 2 * 3;
let exact_directory = database();
let mut exact_change_set =
ChangeSet::new_with_limit(exact_directory.path(), Some(exact_len)).unwrap();
exact_change_set
.overwrite("records.db", 2, b"XYZ".to_vec())
.unwrap();
assert_eq!(exact_change_set.durable_bytes, exact_len);
assert!(matches!(
commit_with_limit(exact_change_set, Some(exact_len)).unwrap(),
DurableCommitOutcome::Committed
));
let limited_directory = database();
let mut limited_change_set =
ChangeSet::new_with_limit(limited_directory.path(), Some(exact_len - 1)).unwrap();
assert!(matches!(
limited_change_set.overwrite("records.db", 2, b"XYZ".to_vec()),
Err(crate::Error::Transaction(
crate::TransactionErrorKind::ResourceLimit
))
));
assert!(limited_change_set.patches.is_empty());
assert_eq!(limited_change_set.durable_bytes, JOURNAL_FIXED_BYTES);
assert_eq!(
limited_change_set
.backing
.as_ref()
.unwrap()
.lock()
.unwrap()
.metadata()
.unwrap()
.len(),
0
);
assert_eq!(
fs::read(limited_directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
assert!(!limited_directory.path().join(JOURNAL_NAME).exists());
assert!(!limited_directory.path().join(JOURNAL_TEMP_NAME).exists());
}
#[test]
fn new_change_sets_stage_patch_images_in_their_backing_file() {
let directory = database();
let mut change_set = ChangeSet::new(directory.path()).unwrap();
change_set
.overwrite("records.db", 2, b"XYZ".to_vec())
.unwrap();
let patch = &change_set.patches[0];
assert!(matches!(patch.before, PatchData::Backed { len: 3, .. }));
assert!(matches!(patch.after, PatchData::Backed { len: 3, .. }));
assert_eq!(change_set.read_image(&patch.before).unwrap(), b"cde");
assert_eq!(change_set.read_image(&patch.after).unwrap(), b"XYZ");
assert_eq!(
change_set
.backing
.as_ref()
.unwrap()
.lock()
.unwrap()
.metadata()
.unwrap()
.len(),
6
);
persist_journal(&change_set, false);
let journal_len = fs::metadata(change_set.journal_path()).unwrap().len();
change_set.rebase_images_to_journal().unwrap();
let patch = &change_set.patches[0];
assert!(matches!(
patch.before,
PatchData::Backed { offset: 68, len: 3 }
));
assert!(matches!(
patch.after,
PatchData::Backed { offset: 71, len: 3 }
));
assert_eq!(change_set.read_image(&patch.before).unwrap(), b"cde");
assert_eq!(change_set.read_image(&patch.after).unwrap(), b"XYZ");
assert_eq!(
change_set
.backing
.as_ref()
.unwrap()
.lock()
.unwrap()
.metadata()
.unwrap()
.len(),
journal_len
);
}
#[test]
fn change_set_backing_does_not_create_a_named_database_artifact() {
let directory = database();
let entries_before = fs::read_dir(directory.path())
.unwrap()
.map(|entry| entry.unwrap().file_name())
.collect::<BTreeSet<_>>();
let mut change_set = ChangeSet::new(directory.path()).unwrap();
change_set
.overwrite("records.db", 2, b"XYZ".to_vec())
.unwrap();
let entries_after = fs::read_dir(directory.path())
.unwrap()
.map(|entry| entry.unwrap().file_name())
.collect::<BTreeSet<_>>();
assert_eq!(entries_after, entries_before);
}
#[test]
fn truncated_change_set_backing_rolls_back_and_removes_the_temporary_journal() {
let directory = database();
let change_set = change_set(directory.path());
change_set
.backing
.as_ref()
.unwrap()
.lock()
.unwrap()
.set_len(4)
.unwrap();
let outcome = commit(change_set).unwrap();
assert!(matches!(outcome, DurableCommitOutcome::RolledBack(_)));
assert_eq!(
fs::read(directory.path().join("records.db")).unwrap(),
b"abcdefghij"
);
assert!(!directory.path().join(JOURNAL_NAME).exists());
assert!(!directory.path().join(JOURNAL_TEMP_NAME).exists());
}
#[test]
fn change_set_rejects_unsafe_paths_and_overlapping_patches() {
let directory = database();
let mut change_set = ChangeSet::new(directory.path()).unwrap();
assert!(change_set.overwrite("records.db", 0, Vec::new()).is_err());
assert!(change_set.overwrite("../records.db", 0, vec![1]).is_err());
assert!(change_set.overwrite(JOURNAL_NAME, 0, vec![1]).is_err());
assert!(change_set.overwrite(JOURNAL_TEMP_NAME, 0, vec![1]).is_err());
change_set
.overwrite("records.db", 1, vec![1, 2, 3])
.unwrap();
change_set.overwrite("records.db", 3, vec![4, 5]).unwrap();
assert!(change_set
.validate()
.unwrap_err()
.to_string()
.contains("overlapping"));
let mut decoded_shape = ChangeSet::new(directory.path()).unwrap();
decoded_shape.patches.push(FilePatch {
relative_path: PathBuf::from("records.db"),
original_len: 10,
offset: 0,
before: PatchData::Memory(Vec::new()),
after: PatchData::Memory(Vec::new()),
});
assert!(decoded_shape
.validate()
.unwrap_err()
.to_string()
.contains("cannot be empty"));
}
#[cfg(unix)]
#[test]
fn change_set_rejects_store_symlinks_that_escape_the_database() {
use std::os::unix::fs::symlink;
let directory = database();
let outside = tempfile::NamedTempFile::new().unwrap();
fs::write(outside.path(), b"outside-data").unwrap();
symlink(outside.path(), directory.path().join("escaped.db")).unwrap();
let mut change_set = ChangeSet::new(directory.path()).unwrap();
let error = change_set
.overwrite("escaped.db", 0, b"changed".to_vec())
.unwrap_err();
assert!(error.to_string().contains("escapes database directory"));
assert_eq!(fs::read(outside.path()).unwrap(), b"outside-data");
}
}