use std::{collections::TryReserveError, fmt, io};
mod file;
pub use file::{load, load_with, save, save_with};
pub const FORMAT_VERSION: u32 = 1;
pub const HEADER_LEN: usize = 28;
const MAGIC: &[u8; 8] = b"RAYSAVE\0";
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct SaveLimits {
pub max_payload_bytes: usize,
}
impl Default for SaveLimits {
fn default() -> Self {
Self {
max_payload_bytes: 64 * 1024 * 1024,
}
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Durability {
Atomic,
#[default]
Durable,
}
#[derive(Clone, Copy, Debug, Default)]
pub struct SaveOptions {
pub limits: SaveLimits,
pub durability: Durability,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SaveStage {
Read,
OpenDirectory,
CreateTemporary,
WriteTemporary,
SyncTemporary,
Rename,
SyncDirectory,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum CommitState {
NotCommitted,
Unknown,
Committed,
}
#[derive(Debug)]
pub enum SaveError {
TruncatedHeader {
bytes: usize,
},
BadMagic,
UnsupportedFormat {
found: u32,
},
UnsupportedSchema {
expected: u32,
found: u32,
},
TooLarge {
bytes: u64,
limit: usize,
},
SizeOverflow,
LengthMismatch {
declared: u64,
actual: u64,
},
ChecksumMismatch {
expected: u32,
actual: u32,
},
InvalidPath,
NotRegularFile,
UnsupportedDurability,
Allocation(TryReserveError),
Io {
stage: SaveStage,
source: io::Error,
},
}
impl SaveError {
pub fn commit_state(&self) -> CommitState {
match self {
Self::Io {
stage: SaveStage::Rename,
..
} => CommitState::Unknown,
Self::Io {
stage: SaveStage::SyncDirectory,
..
} => CommitState::Committed,
_ => CommitState::NotCommitted,
}
}
}
impl fmt::Display for SaveError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::TruncatedHeader { bytes } => {
write!(f, "save header has {bytes} bytes; needs {HEADER_LEN}")
}
Self::BadMagic => f.write_str("invalid save magic"),
Self::UnsupportedFormat { found } => write!(f, "unsupported save format {found}"),
Self::UnsupportedSchema { expected, found } => {
write!(f, "expected game schema {expected}, found {found}")
}
Self::TooLarge { bytes, limit } => {
write!(f, "save payload {bytes} exceeds limit {limit}")
}
Self::SizeOverflow => f.write_str("save size exceeds platform limits"),
Self::LengthMismatch { declared, actual } => {
write!(f, "save declares {declared} payload bytes, found {actual}")
}
Self::ChecksumMismatch { expected, actual } => write!(
f,
"save checksum mismatch: expected {expected:08x}, found {actual:08x}"
),
Self::InvalidPath => f.write_str("save path must name a file"),
Self::NotRegularFile => f.write_str("save source must be a regular file"),
Self::UnsupportedDurability => f.write_str(
"durable saves require Linux; choose Atomic explicitly on other targets",
),
Self::Allocation(source) => write!(f, "save allocation: {source}"),
Self::Io { stage, source } => write!(f, "save {stage:?}: {source}"),
}
}
}
impl std::error::Error for SaveError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Allocation(source) => Some(source),
Self::Io { source, .. } => Some(source),
_ => None,
}
}
}
#[derive(Debug)]
pub enum CodecError<E> {
Container(SaveError),
Payload(E),
}
impl<E: fmt::Display> fmt::Display for CodecError<E> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Container(e) => e.fmt(f),
Self::Payload(e) => write!(f, "save payload codec: {e}"),
}
}
}
impl<E: std::error::Error + 'static> std::error::Error for CodecError<E> {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Container(e) => Some(e),
Self::Payload(e) => Some(e),
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct SaveRef<'a> {
pub schema_version: u32,
pub payload: &'a [u8],
}
impl SaveRef<'_> {
pub fn require_schema(&self, expected: u32) -> Result<(), SaveError> {
if self.schema_version == expected {
Ok(())
} else {
Err(SaveError::UnsupportedSchema {
expected,
found: self.schema_version,
})
}
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SaveData {
pub schema_version: u32,
pub payload: Vec<u8>,
}
impl SaveData {
pub fn as_ref(&self) -> SaveRef<'_> {
SaveRef {
schema_version: self.schema_version,
payload: &self.payload,
}
}
pub fn require_schema(&self, expected: u32) -> Result<(), SaveError> {
self.as_ref().require_schema(expected)
}
}
pub fn encode(
schema_version: u32,
payload: &[u8],
limits: SaveLimits,
) -> Result<Vec<u8>, SaveError> {
let mut output = Vec::new();
encode_into(&mut output, schema_version, payload, limits)?;
Ok(output)
}
pub fn encode_into(
output: &mut Vec<u8>,
schema_version: u32,
payload: &[u8],
limits: SaveLimits,
) -> Result<(), SaveError> {
let header = make_header(schema_version, payload, limits)?;
let total = HEADER_LEN
.checked_add(payload.len())
.ok_or(SaveError::SizeOverflow)?;
output
.try_reserve(total.saturating_sub(output.len()))
.map_err(SaveError::Allocation)?;
output.clear();
output.extend_from_slice(&header);
output.extend_from_slice(payload);
Ok(())
}
pub fn decode(bytes: &[u8], limits: SaveLimits) -> Result<SaveRef<'_>, SaveError> {
let header = bytes
.get(..HEADER_LEN)
.ok_or(SaveError::TruncatedHeader { bytes: bytes.len() })?;
let (schema_version, size) = parse_header(header, limits)?;
let payload = &bytes[HEADER_LEN..];
if payload.len() != size {
return Err(SaveError::LengthMismatch {
declared: size as u64,
actual: payload.len() as u64,
});
}
verify_checksum(header, payload)?;
Ok(SaveRef {
schema_version,
payload,
})
}
fn make_header(
schema: u32,
payload: &[u8],
limits: SaveLimits,
) -> Result<[u8; HEADER_LEN], SaveError> {
let size = u64::try_from(payload.len()).map_err(|_| SaveError::SizeOverflow)?;
if payload.len() > limits.max_payload_bytes {
return Err(SaveError::TooLarge {
bytes: size,
limit: limits.max_payload_bytes,
});
}
HEADER_LEN
.checked_add(payload.len())
.ok_or(SaveError::SizeOverflow)?;
let mut header = [0; HEADER_LEN];
header[..8].copy_from_slice(MAGIC);
header[8..12].copy_from_slice(&FORMAT_VERSION.to_le_bytes());
header[12..16].copy_from_slice(&schema.to_le_bytes());
header[16..24].copy_from_slice(&size.to_le_bytes());
let crc = checksum(&header[..24], payload);
header[24..].copy_from_slice(&crc.to_le_bytes());
Ok(header)
}
fn parse_header(header: &[u8], limits: SaveLimits) -> Result<(u32, usize), SaveError> {
if &header[..8] != MAGIC {
return Err(SaveError::BadMagic);
}
let format = u32::from_le_bytes(header[8..12].try_into().expect("fixed header"));
if format != FORMAT_VERSION {
return Err(SaveError::UnsupportedFormat { found: format });
}
let schema = u32::from_le_bytes(header[12..16].try_into().expect("fixed header"));
let length = u64::from_le_bytes(header[16..24].try_into().expect("fixed header"));
let size = usize::try_from(length).map_err(|_| SaveError::TooLarge {
bytes: length,
limit: limits.max_payload_bytes,
})?;
if size > limits.max_payload_bytes {
return Err(SaveError::TooLarge {
bytes: length,
limit: limits.max_payload_bytes,
});
}
HEADER_LEN
.checked_add(size)
.ok_or(SaveError::SizeOverflow)?;
Ok((schema, size))
}
fn checksum(prefix: &[u8], payload: &[u8]) -> u32 {
let mut hasher = crc32fast::Hasher::new();
hasher.update(prefix);
hasher.update(payload);
hasher.finalize()
}
fn verify_checksum(header: &[u8], payload: &[u8]) -> Result<(), SaveError> {
let expected = u32::from_le_bytes(header[24..28].try_into().expect("fixed header"));
let actual = checksum(&header[..24], payload);
if actual == expected {
Ok(())
} else {
Err(SaveError::ChecksumMismatch { expected, actual })
}
}
#[cfg(test)]
mod tests;