use std::fs::{self, File, OpenOptions};
use std::io::{self, Read, Seek, SeekFrom, Write};
use std::path::{Path, PathBuf};
use std::time::{SystemTime, UNIX_EPOCH};
use uuid::Uuid;
use crate::error::{Neo4jStoreError, Result};
use super::page;
const METADATA_FILE: &str = "neostore";
const METADATA_RECORD_SIZE: u64 = 9;
const EXTERNAL_STORE_ID_FIRST_SLOT: u64 = 0;
const LEGACY_VERSION_SLOT: u64 = 4;
const STORE_ID_FIRST_SLOT: u64 = 5;
const STORE_ID_SLOT_COUNT: usize = 8;
const STORE_ID_SIZE: usize = 64;
const STORE_ID_SERIALIZATION_VERSION: u8 = 1;
const LEGACY_STORE_VERSION: u64 = 0xcf1b_bcdc_b7a5_6463;
const IN_USE: u8 = 1;
const EMPTY_DYNAMIC_RECORD_SIZE: u32 = 9;
const REQUIRED_STORE_FILES: &[&str] = &[
METADATA_FILE,
"neostore.schemastore.db",
"neostore.nodestore.db",
"neostore.nodestore.db.labels",
"neostore.relationshipstore.db",
"neostore.relationshiptypestore.db",
"neostore.relationshiptypestore.db.names",
"neostore.propertystore.db",
"neostore.propertystore.db.arrays",
"neostore.propertystore.db.strings",
"neostore.propertystore.db.index",
"neostore.propertystore.db.index.keys",
"neostore.labeltokenstore.db",
"neostore.labeltokenstore.db.names",
];
const DYNAMIC_STORE_FILES: &[&str] = &[
"neostore.nodestore.db.labels",
"neostore.relationshiptypestore.db.names",
"neostore.propertystore.db.arrays",
"neostore.propertystore.db.strings",
"neostore.propertystore.db.index.keys",
"neostore.labeltokenstore.db.names",
];
const WRITABLE_FIXED_STORE_FILES: &[&str] = &["neostore.relationshipgroupstore.db"];
const ID_GENERATOR_STORES: &[(&str, u64)] = &[
("neostore.propertystore.db", 0),
("neostore.propertystore.db.strings", 1),
("neostore.propertystore.db.arrays", 1),
("neostore.propertystore.db.index", 0),
("neostore.propertystore.db.index.keys", 1),
("neostore.nodestore.db", 0),
("neostore.nodestore.db.labels", 1),
("neostore.labeltokenstore.db", 0),
("neostore.labeltokenstore.db.names", 1),
("neostore.relationshiptypestore.db", 0),
("neostore.relationshiptypestore.db.names", 1),
("neostore.relationshipstore.db", 0),
("neostore.relationshipgroupstore.db", 0),
];
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Neo4jStoreFormat {
StandardV5_0,
AlignedV5_0,
}
impl Neo4jStoreFormat {
pub fn name(self) -> &'static str {
match self {
Self::StandardV5_0 => "standard",
Self::AlignedV5_0 => "aligned",
}
}
pub fn major_version(self) -> u8 {
1
}
pub fn minor_version(self) -> u8 {
1
}
}
#[derive(Debug, PartialEq, Eq)]
struct StoreId {
creation_time: i64,
storage_engine: String,
format_name: String,
major_version: i8,
minor_version: i8,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub(super) struct StoreMetadata {
pub(super) external_store_id: [u8; 16],
pub(super) creation_time_millis: i64,
}
pub(super) fn validate(database_directory: &Path) -> Result<Neo4jStoreFormat> {
validate_directory(database_directory)?;
let metadata_path = database_directory.join(METADATA_FILE);
ensure_file(&metadata_path)?;
let store_id = read_store_id(&metadata_path)?;
let format = supported_format(&metadata_path, &store_id)?;
for file_name in REQUIRED_STORE_FILES.iter().skip(1) {
ensure_file(&database_directory.join(file_name))?;
}
page::validate_store_file(
&database_directory.join("neostore.nodestore.db"),
"node",
format,
15,
)?;
Ok(format)
}
pub(super) fn initialize_if_empty(database_directory: &Path) -> Result<bool> {
match fs::metadata(database_directory) {
Ok(metadata) if metadata.is_dir() => {}
Ok(_) => {
return Err(Neo4jStoreError::NotADirectory {
path: database_directory.to_path_buf(),
}
.into())
}
Err(source) if source.kind() == io::ErrorKind::NotFound => {
fs::create_dir_all(database_directory).map_err(|source| Neo4jStoreError::Write {
path: database_directory.to_path_buf(),
source,
})?;
}
Err(source) => {
return Err(Neo4jStoreError::Read {
path: database_directory.to_path_buf(),
source,
}
.into())
}
}
let mut entries = fs::read_dir(database_directory).map_err(|source| Neo4jStoreError::Read {
path: database_directory.to_path_buf(),
source,
})?;
if let Some(entry) = entries.next() {
entry.map_err(|source| Neo4jStoreError::Read {
path: database_directory.to_path_buf(),
source,
})?;
return Ok(false);
}
super::checkpoint::validate_initialization_path(database_directory)?;
write_file(&database_directory.join(METADATA_FILE), &empty_metadata()?)?;
let dynamic_header = EMPTY_DYNAMIC_RECORD_SIZE.to_be_bytes();
for file_name in REQUIRED_STORE_FILES.iter().skip(1) {
let mut bytes = vec![0_u8; page::PAGE_SIZE];
if DYNAMIC_STORE_FILES.contains(file_name) {
bytes[..dynamic_header.len()].copy_from_slice(&dynamic_header);
}
write_file(&database_directory.join(file_name), &bytes)?;
}
for file_name in WRITABLE_FIXED_STORE_FILES {
write_file(
&database_directory.join(file_name),
&vec![0_u8; page::PAGE_SIZE],
)?;
}
for (store_name, high_id) in ID_GENERATOR_STORES {
write_file(
&database_directory.join(format!("{store_name}.id")),
&super::id_generator::empty_file(*high_id),
)?;
}
write_file(
&database_directory.join("neostore.counts.db"),
&super::counts::empty_file(true),
)?;
write_file(
&database_directory.join("neostore.relationshipgroupstore.degrees.db"),
&super::counts::empty_file(false),
)?;
super::checkpoint::initialize_empty(database_directory)?;
Ok(true)
}
fn empty_metadata() -> Result<Vec<u8>> {
let creation_time: i64 = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_err(|source| {
crate::Error::Validation(format!("system time precedes Unix epoch: {source}"))
})?
.as_millis()
.try_into()
.map_err(|_| {
crate::Error::Validation("system time exceeds Neo4j timestamp range".to_owned())
})?;
let external_store_id = *Uuid::new_v4().as_bytes();
let random_id = i64::from_be_bytes(external_store_id[..8].try_into().expect("UUID half"));
let mut store_id = [0_u8; STORE_ID_SIZE];
let mut position = 0;
store_id[position] = STORE_ID_SERIALIZATION_VERSION;
position += 1;
store_id[position..position + 8].copy_from_slice(&creation_time.to_be_bytes());
position += 8;
store_id[position..position + 8].copy_from_slice(&random_id.to_be_bytes());
position += 8;
store_id[position] = 6;
position += 1;
store_id[position..position + 6].copy_from_slice(b"record");
position += 6;
store_id[position] = 7;
position += 1;
store_id[position..position + 7].copy_from_slice(b"aligned");
position += 7;
store_id[position] = 1;
store_id[position + 1] = 1;
let mut metadata = vec![0_u8; (STORE_ID_FIRST_SLOT as usize + STORE_ID_SLOT_COUNT) * 9];
for (index, payload) in external_store_id.chunks_exact(8).enumerate() {
let offset =
(EXTERNAL_STORE_ID_FIRST_SLOT as usize + index) * METADATA_RECORD_SIZE as usize;
metadata[offset] = IN_USE;
metadata[offset + 1..offset + 9].copy_from_slice(payload);
}
let legacy_offset = LEGACY_VERSION_SLOT as usize * METADATA_RECORD_SIZE as usize;
metadata[legacy_offset] = IN_USE;
metadata[legacy_offset + 1..legacy_offset + 9]
.copy_from_slice(&LEGACY_STORE_VERSION.to_be_bytes());
for (index, payload) in store_id.chunks_exact(8).enumerate() {
let offset = (STORE_ID_FIRST_SLOT as usize + index) * METADATA_RECORD_SIZE as usize;
metadata[offset] = IN_USE;
metadata[offset + 1..offset + 9].copy_from_slice(payload);
}
Ok(metadata)
}
fn write_file(path: &Path, bytes: &[u8]) -> Result<()> {
let mut file = OpenOptions::new()
.write(true)
.create_new(true)
.open(path)
.map_err(|source| Neo4jStoreError::Write {
path: path.to_path_buf(),
source,
})?;
file.write_all(bytes)
.map_err(|source| Neo4jStoreError::Write {
path: path.to_path_buf(),
source,
})?;
file.sync_all().map_err(|source| {
Neo4jStoreError::Write {
path: path.to_path_buf(),
source,
}
.into()
})
}
fn validate_directory(path: &Path) -> Result<()> {
let metadata = fs::metadata(path).map_err(|source| Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
})?;
if !metadata.is_dir() {
return Err(Neo4jStoreError::NotADirectory {
path: path.to_path_buf(),
}
.into());
}
Ok(())
}
fn ensure_file(path: &Path) -> Result<()> {
match fs::metadata(path) {
Ok(metadata) if metadata.is_file() => Ok(()),
Ok(_) => Err(Neo4jStoreError::MissingFile {
path: path.to_path_buf(),
}
.into()),
Err(source) if source.kind() == io::ErrorKind::NotFound => {
Err(Neo4jStoreError::MissingFile {
path: path.to_path_buf(),
}
.into())
}
Err(source) => Err(Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
}
.into()),
}
}
fn read_store_id(path: &Path) -> Result<StoreId> {
let mut file = File::open(path).map_err(|source| Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
})?;
let legacy_bytes = read_metadata_payload(&mut file, path, LEGACY_VERSION_SLOT)?;
if u64::from_be_bytes(legacy_bytes) != LEGACY_STORE_VERSION {
return Err(invalid_metadata(
path,
LEGACY_VERSION_SLOT * METADATA_RECORD_SIZE + 1,
"legacy version marker does not identify a Neo4j 5.x store",
));
}
let mut serialized = [0_u8; STORE_ID_SIZE];
for slot_index in 0..STORE_ID_SLOT_COUNT {
let payload =
read_metadata_payload(&mut file, path, STORE_ID_FIRST_SLOT + slot_index as u64)?;
let start = slot_index * payload.len();
serialized[start..start + payload.len()].copy_from_slice(&payload);
}
decode_store_id(path, &serialized)
}
pub(super) fn read_metadata(database_directory: &Path) -> Result<StoreMetadata> {
let path = database_directory.join(METADATA_FILE);
let mut file = File::open(&path).map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?;
let mut external_store_id = [0_u8; 16];
for slot_index in 0..2 {
let slot = EXTERNAL_STORE_ID_FIRST_SLOT + slot_index as u64;
let offset = slot * METADATA_RECORD_SIZE;
file.seek(SeekFrom::Start(offset))
.map_err(|source| Neo4jStoreError::Read {
path: path.clone(),
source,
})?;
let mut record = [0_u8; METADATA_RECORD_SIZE as usize];
read_exact_at(&mut file, &path, offset, &mut record)?;
external_store_id[slot_index * 8..(slot_index + 1) * 8].copy_from_slice(&record[1..]);
}
let store_id = read_store_id(&path)?;
Ok(StoreMetadata {
external_store_id,
creation_time_millis: store_id.creation_time,
})
}
fn read_metadata_payload(file: &mut File, path: &Path, slot: u64) -> Result<[u8; 8]> {
let offset = slot * METADATA_RECORD_SIZE;
file.seek(SeekFrom::Start(offset))
.map_err(|source| Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
})?;
let mut record = [0_u8; METADATA_RECORD_SIZE as usize];
read_exact_at(file, path, offset, &mut record)?;
if record[0] != IN_USE {
return Err(invalid_metadata(
path,
offset,
format!("metadata slot {slot} is not in use"),
));
}
Ok(record[1..]
.try_into()
.expect("metadata payload has fixed size"))
}
fn read_exact_at(file: &mut File, path: &Path, offset: u64, buffer: &mut [u8]) -> Result<()> {
let mut actual = 0;
while actual < buffer.len() {
match file.read(&mut buffer[actual..]) {
Ok(0) => {
return Err(Neo4jStoreError::Truncated {
path: path.to_path_buf(),
offset: offset + actual as u64,
expected: buffer.len() - actual,
actual: 0,
}
.into());
}
Ok(count) => actual += count,
Err(source) if source.kind() == io::ErrorKind::Interrupted => {}
Err(source) => {
return Err(Neo4jStoreError::Read {
path: path.to_path_buf(),
source,
}
.into());
}
}
}
Ok(())
}
fn decode_store_id(path: &Path, bytes: &[u8; STORE_ID_SIZE]) -> Result<StoreId> {
let mut cursor = StoreIdCursor::new(path, bytes);
let version = cursor.byte()?;
if version != STORE_ID_SERIALIZATION_VERSION {
return Err(invalid_metadata(
path,
STORE_ID_FIRST_SLOT * METADATA_RECORD_SIZE + 1,
format!("unknown StoreId serialization version {version}"),
));
}
let creation_time = cursor.u64()? as i64;
let _random_id = cursor.u64()?;
let storage_engine = cursor.string("storage engine")?;
let format_name = cursor.string("format name")?;
let major_version = cursor.byte()? as i8;
let minor_version = cursor.byte()? as i8;
Ok(StoreId {
creation_time,
storage_engine,
format_name,
major_version,
minor_version,
})
}
fn supported_format(path: &Path, store_id: &StoreId) -> Result<Neo4jStoreFormat> {
match (
store_id.storage_engine.as_str(),
store_id.format_name.as_str(),
store_id.major_version,
store_id.minor_version,
) {
("record", "standard", 1, 1) => Ok(Neo4jStoreFormat::StandardV5_0),
("record", "aligned", 1, 1) => Ok(Neo4jStoreFormat::AlignedV5_0),
_ => Err(Neo4jStoreError::UnsupportedFormat {
path: path.to_path_buf(),
storage_engine: store_id.storage_engine.clone(),
format_name: store_id.format_name.clone(),
major_version: store_id.major_version,
minor_version: store_id.minor_version,
}
.into()),
}
}
struct StoreIdCursor<'a> {
path: &'a Path,
bytes: &'a [u8],
position: usize,
}
impl<'a> StoreIdCursor<'a> {
fn new(path: &'a Path, bytes: &'a [u8]) -> Self {
Self {
path,
bytes,
position: 0,
}
}
fn byte(&mut self) -> Result<u8> {
let byte = self.bytes.get(self.position).copied().ok_or_else(|| {
invalid_metadata(
self.path,
self.file_offset(),
"StoreId exceeds its 64-byte metadata field",
)
})?;
self.position += 1;
Ok(byte)
}
fn u64(&mut self) -> Result<u64> {
let bytes: [u8; 8] = self
.take(8)?
.try_into()
.map_err(|_| invalid_metadata(self.path, self.file_offset(), "invalid u64 field"))?;
Ok(u64::from_be_bytes(bytes))
}
fn string(&mut self, field: &str) -> Result<String> {
let length = self.byte()? as usize;
let offset = self.file_offset();
let bytes = self.take(length)?;
let value = std::str::from_utf8(bytes).map_err(|error| {
invalid_metadata(
self.path,
offset,
format!("{field} is not valid UTF-8: {error}"),
)
})?;
Ok(value.to_owned())
}
fn take(&mut self, count: usize) -> Result<&'a [u8]> {
let end = self.position.checked_add(count).ok_or_else(|| {
invalid_metadata(self.path, self.file_offset(), "StoreId length overflow")
})?;
let value = self.bytes.get(self.position..end).ok_or_else(|| {
invalid_metadata(
self.path,
self.file_offset(),
"StoreId exceeds its 64-byte metadata field",
)
})?;
self.position = end;
Ok(value)
}
fn file_offset(&self) -> u64 {
STORE_ID_FIRST_SLOT * METADATA_RECORD_SIZE
+ 1
+ self.position as u64
+ (self.position / 8) as u64
}
}
fn invalid_metadata(path: &Path, offset: u64, message: impl Into<String>) -> crate::Error {
Neo4jStoreError::InvalidMetadata {
path: PathBuf::from(path),
offset,
message: message.into(),
}
.into()
}
#[cfg(test)]
mod tests {
use super::*;
fn serialized_store_id(engine: &[u8], format: &[u8], major: i8, minor: i8) -> [u8; 64] {
let mut bytes = [0_u8; 64];
let mut position = 0;
bytes[position] = 1;
position += 1 + 16;
bytes[position] = engine.len() as u8;
position += 1;
bytes[position..position + engine.len()].copy_from_slice(engine);
position += engine.len();
bytes[position] = format.len() as u8;
position += 1;
bytes[position..position + format.len()].copy_from_slice(format);
position += format.len();
bytes[position] = major as u8;
bytes[position + 1] = minor as u8;
bytes
}
fn write_metadata(path: &Path, serialized_store_id: &[u8; 64]) {
let mut bytes = vec![0_u8; (STORE_ID_FIRST_SLOT as usize + STORE_ID_SLOT_COUNT) * 9];
for (index, payload) in [0x11_u8; 16].chunks_exact(8).enumerate() {
let offset = (EXTERNAL_STORE_ID_FIRST_SLOT as usize + index) * 9;
bytes[offset] = IN_USE;
bytes[offset + 1..offset + 9].copy_from_slice(payload);
}
let legacy_offset = LEGACY_VERSION_SLOT as usize * 9;
bytes[legacy_offset] = IN_USE;
bytes[legacy_offset + 1..legacy_offset + 9]
.copy_from_slice(&LEGACY_STORE_VERSION.to_be_bytes());
for (index, payload) in serialized_store_id.chunks_exact(8).enumerate() {
let offset = (STORE_ID_FIRST_SLOT as usize + index) * 9;
bytes[offset] = IN_USE;
bytes[offset + 1..offset + 9].copy_from_slice(payload);
}
std::fs::write(path, bytes).unwrap();
}
fn create_required_files(directory: &Path) {
for file_name in REQUIRED_STORE_FILES.iter().skip(1) {
std::fs::File::create(directory.join(file_name)).unwrap();
}
}
#[test]
fn decodes_supported_store_id_fields() {
let bytes = serialized_store_id(b"record", b"aligned", 1, 1);
let id = decode_store_id(Path::new("neostore"), &bytes).unwrap();
assert_eq!(
id,
StoreId {
creation_time: 0,
storage_engine: "record".to_owned(),
format_name: "aligned".to_owned(),
major_version: 1,
minor_version: 1,
}
);
}
#[test]
fn metadata_identity_and_creation_time_are_persistent() {
let directory = tempfile::tempdir().unwrap();
assert!(initialize_if_empty(directory.path()).unwrap());
let first = read_metadata(directory.path()).unwrap();
let second = read_metadata(directory.path()).unwrap();
assert_eq!(first, second);
assert_ne!(first.external_store_id, [0_u8; 16]);
assert!(first.creation_time_millis > 0);
}
#[test]
fn reads_metadata_for_standard_and_aligned_store_ids() {
for format in [b"standard".as_slice(), b"aligned".as_slice()] {
let directory = tempfile::tempdir().unwrap();
let mut store_id = serialized_store_id(b"record", format, 1, 1);
store_id[1..9].copy_from_slice(&1_704_164_645_006_i64.to_be_bytes());
write_metadata(&directory.path().join(METADATA_FILE), &store_id);
assert_eq!(
read_metadata(directory.path()).unwrap(),
StoreMetadata {
external_store_id: [0x11; 16],
creation_time_millis: 1_704_164_645_006,
}
);
}
}
#[test]
fn rejects_invalid_utf8() {
let bytes = serialized_store_id(&[0xff], b"aligned", 1, 1);
let error = decode_store_id(Path::new("neostore"), &bytes).unwrap_err();
assert!(error
.to_string()
.contains("storage engine is not valid UTF-8"));
}
#[test]
fn recognizes_only_supported_formats() {
for (format, expected) in [
("standard", Neo4jStoreFormat::StandardV5_0),
("aligned", Neo4jStoreFormat::AlignedV5_0),
] {
let id = StoreId {
creation_time: 0,
storage_engine: "record".to_owned(),
format_name: format.to_owned(),
major_version: 1,
minor_version: 1,
};
assert_eq!(
supported_format(Path::new("neostore"), &id).unwrap(),
expected
);
}
}
#[test]
fn rejects_block_high_limit_and_unknown_versions() {
for id in [
StoreId {
creation_time: 0,
storage_engine: "block".to_owned(),
format_name: "block".to_owned(),
major_version: 1,
minor_version: 1,
},
StoreId {
creation_time: 0,
storage_engine: "record".to_owned(),
format_name: "high_limit".to_owned(),
major_version: 1,
minor_version: 1,
},
StoreId {
creation_time: 0,
storage_engine: "record".to_owned(),
format_name: "aligned".to_owned(),
major_version: 1,
minor_version: 2,
},
] {
let error = supported_format(Path::new("neostore"), &id).unwrap_err();
assert!(matches!(
error,
crate::Error::Neo4jStore(Neo4jStoreError::UnsupportedFormat { .. })
));
}
}
#[test]
fn truncated_metadata_has_file_and_offset_context() {
let directory = tempfile::tempdir().unwrap();
let path = directory.path().join(METADATA_FILE);
std::fs::write(&path, [0_u8; 12]).unwrap();
let error = read_store_id(&path).unwrap_err();
let message = error.to_string();
assert!(message.contains(path.to_str().unwrap()));
assert!(message.contains("offset"));
assert!(matches!(
error,
crate::Error::Neo4jStore(Neo4jStoreError::Truncated { .. })
));
}
#[test]
fn validates_a_complete_aligned_layout() {
let directory = tempfile::tempdir().unwrap();
write_metadata(
&directory.path().join(METADATA_FILE),
&serialized_store_id(b"record", b"aligned", 1, 1),
);
create_required_files(directory.path());
assert_eq!(
validate(directory.path()).unwrap(),
Neo4jStoreFormat::AlignedV5_0
);
}
#[test]
fn reports_the_first_missing_required_store_file() {
let directory = tempfile::tempdir().unwrap();
write_metadata(
&directory.path().join(METADATA_FILE),
&serialized_store_id(b"record", b"standard", 1, 1),
);
let error = validate(directory.path()).unwrap_err();
assert!(matches!(
error,
crate::Error::Neo4jStore(Neo4jStoreError::MissingFile { path })
if path.ends_with("neostore.schemastore.db")
));
}
}