use alloc::vec::Vec;
use serde::{Deserialize, Serialize};
use super::ledger::{Ingested, Ledger, LedgerSnapshot, TransactionEvent};
use crate::engine::StoreError;
use crate::types::DateTime;
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "op", rename_all = "snake_case")]
#[non_exhaustive]
pub enum JournalEntry {
Ingest {
event: TransactionEvent,
},
IngestUnsequenced {
event: TransactionEvent,
},
PruneEndedBefore {
cutoff: DateTime,
},
}
impl JournalEntry {
fn apply(&self, ledger: &mut Ledger) {
match self {
JournalEntry::Ingest { event } => {
let _ = ledger.ingest(event);
}
JournalEntry::IngestUnsequenced { event } => {
let _ = ledger.ingest_unsequenced(event);
}
JournalEntry::PruneEndedBefore { cutoff } => {
ledger.prune_ended_before(*cutoff);
}
}
}
}
pub trait LedgerStore {
fn load(&mut self) -> Result<(Option<LedgerSnapshot>, Vec<JournalEntry>), StoreError>;
fn append(&mut self, entry: &JournalEntry) -> Result<(), StoreError>;
fn checkpoint(&mut self, snapshot: &LedgerSnapshot) -> Result<(), StoreError>;
}
#[derive(Clone, Debug, Default)]
pub struct MemLedgerStore {
snapshot: Option<LedgerSnapshot>,
journal: Vec<JournalEntry>,
}
impl MemLedgerStore {
#[must_use]
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn journal_len(&self) -> usize {
self.journal.len()
}
}
impl LedgerStore for MemLedgerStore {
fn load(&mut self) -> Result<(Option<LedgerSnapshot>, Vec<JournalEntry>), StoreError> {
Ok((self.snapshot.clone(), self.journal.clone()))
}
fn append(&mut self, entry: &JournalEntry) -> Result<(), StoreError> {
self.journal.push(entry.clone());
Ok(())
}
fn checkpoint(&mut self, snapshot: &LedgerSnapshot) -> Result<(), StoreError> {
self.snapshot = Some(snapshot.clone());
self.journal.clear();
Ok(())
}
}
#[derive(Debug)]
pub struct DurableLedger<S> {
ledger: Ledger,
store: S,
}
impl<S: LedgerStore> DurableLedger<S> {
pub fn open(mut store: S) -> Result<Self, StoreError> {
let (snapshot, journal) = store.load()?;
let mut ledger = snapshot.map_or_else(Ledger::new, Ledger::from_snapshot);
for entry in &journal {
entry.apply(&mut ledger);
}
Ok(Self { ledger, store })
}
pub fn ingest(&mut self, event: &TransactionEvent) -> Result<Ingested, StoreError> {
if self.ledger.is_duplicate(event) {
return Ok(Ingested::Duplicate);
}
self.store.append(&JournalEntry::Ingest {
event: event.clone(),
})?;
Ok(self.ledger.ingest(event))
}
pub fn ingest_unsequenced(&mut self, event: &TransactionEvent) -> Result<Ingested, StoreError> {
if self.ledger.is_duplicate_unsequenced(event) {
return Ok(Ingested::Duplicate);
}
self.store.append(&JournalEntry::IngestUnsequenced {
event: event.clone(),
})?;
Ok(self.ledger.ingest_unsequenced(event))
}
pub fn prune_ended_before(&mut self, cutoff: DateTime) -> Result<usize, StoreError> {
self.store
.append(&JournalEntry::PruneEndedBefore { cutoff })?;
Ok(self.ledger.prune_ended_before(cutoff))
}
pub fn checkpoint(&mut self) -> Result<(), StoreError> {
self.store.checkpoint(&self.ledger.snapshot())
}
#[must_use]
pub const fn ledger(&self) -> &Ledger {
&self.ledger
}
#[must_use]
pub const fn store(&self) -> &S {
&self.store
}
#[must_use]
pub fn into_store(self) -> S {
self.store
}
}
#[cfg(feature = "std")]
pub use file::FileLedgerStore;
#[cfg(feature = "std")]
mod file {
use alloc::format;
use alloc::vec::Vec;
use std::fs::{File, OpenOptions};
use std::io::{BufRead, BufReader, Write};
use std::path::{Path, PathBuf};
use super::{JournalEntry, LedgerSnapshot, LedgerStore, StoreError};
#[derive(Debug)]
pub struct FileLedgerStore {
dir: PathBuf,
journal: File,
}
impl FileLedgerStore {
pub fn open(dir: impl AsRef<Path>) -> Result<Self, StoreError> {
let dir = dir.as_ref().to_path_buf();
let journal = Self::open_journal(&dir)?;
Ok(Self { dir, journal })
}
fn journal_path(dir: &Path) -> PathBuf {
dir.join("journal.jsonl")
}
fn snapshot_path(dir: &Path) -> PathBuf {
dir.join("snapshot.json")
}
fn open_journal(dir: &Path) -> Result<File, StoreError> {
let path = Self::journal_path(dir);
OpenOptions::new()
.create(true)
.append(true)
.open(&path)
.map_err(|error| io(&path, &error))
}
fn replace(path: &Path, bytes: &[u8]) -> Result<(), StoreError> {
let temporary = path.with_extension("tmp");
let mut file = File::create(&temporary).map_err(|error| io(&temporary, &error))?;
file.write_all(bytes)
.and_then(|()| file.sync_data())
.map_err(|error| io(&temporary, &error))?;
drop(file);
std::fs::rename(&temporary, path).map_err(|error| io(path, &error))
}
}
impl LedgerStore for FileLedgerStore {
fn load(&mut self) -> Result<(Option<LedgerSnapshot>, Vec<JournalEntry>), StoreError> {
let snapshot_path = Self::snapshot_path(&self.dir);
let snapshot = match std::fs::read(&snapshot_path) {
Ok(bytes) => Some(serde_json::from_slice(&bytes).map_err(|error| {
StoreError::new(format!(
"{}: not a ledger snapshot: {error}",
snapshot_path.display()
))
})?),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
Err(error) => return Err(io(&snapshot_path, &error)),
};
let journal_path = Self::journal_path(&self.dir);
let mut entries = Vec::new();
let mut torn = false;
let file = File::open(&journal_path).map_err(|error| io(&journal_path, &error))?;
for line in BufReader::new(file).lines() {
let Ok(text) = line else {
torn = true;
break;
};
if text.trim().is_empty() {
continue;
}
let Ok(entry) = serde_json::from_str::<JournalEntry>(&text) else {
torn = true;
break;
};
entries.push(entry);
}
if torn {
let mut clean = Vec::new();
for entry in &entries {
serde_json::to_writer(&mut clean, entry).map_err(|error| {
StoreError::new(format!("unserializable entry: {error}"))
})?;
clean.push(b'\n');
}
Self::replace(&journal_path, &clean)?;
self.journal = Self::open_journal(&self.dir)?;
}
Ok((snapshot, entries))
}
fn append(&mut self, entry: &JournalEntry) -> Result<(), StoreError> {
let path = Self::journal_path(&self.dir);
let mut line = serde_json::to_string(entry)
.map_err(|error| StoreError::new(format!("unserializable entry: {error}")))?;
line.push('\n');
self.journal
.write_all(line.as_bytes())
.and_then(|()| self.journal.sync_data())
.map_err(|error| io(&path, &error))
}
fn checkpoint(&mut self, snapshot: &LedgerSnapshot) -> Result<(), StoreError> {
let bytes = serde_json::to_vec(snapshot)
.map_err(|error| StoreError::new(format!("unserializable snapshot: {error}")))?;
Self::replace(&Self::snapshot_path(&self.dir), &bytes)?;
Self::replace(&Self::journal_path(&self.dir), b"")?;
self.journal = Self::open_journal(&self.dir)?;
Ok(())
}
}
fn io(path: &Path, error: &std::io::Error) -> StoreError {
StoreError::new(format!("{}: {error}", path.display()))
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::csms::ledger::EventKind;
use crate::decimal;
use crate::types::Identity;
fn station() -> Identity {
Identity::new("CS-0001").unwrap()
}
fn at(text: &str) -> DateTime {
DateTime::parse(text).unwrap()
}
fn session() -> [TransactionEvent; 3] {
[
TransactionEvent::new(
station(),
"tx-1",
0,
EventKind::Started,
at("2026-11-07T10:00:00Z"),
)
.with_meter(decimal!(1000.0)),
TransactionEvent::new(
station(),
"tx-1",
1,
EventKind::Updated,
at("2026-11-07T10:30:00Z"),
)
.with_meter(decimal!(1500.0)),
TransactionEvent::new(
station(),
"tx-1",
2,
EventKind::Ended,
at("2026-11-07T11:00:00Z"),
)
.with_meter(decimal!(2100.0)),
]
}
#[test]
fn a_retry_after_a_restart_is_still_a_duplicate() {
let mut ledger = DurableLedger::open(MemLedgerStore::new()).unwrap();
for event in &session()[..2] {
assert_eq!(ledger.ingest(event).unwrap(), Ingested::Applied);
}
let mut ledger = DurableLedger::open(ledger.into_store()).unwrap();
assert_eq!(ledger.ingest(&session()[1]).unwrap(), Ingested::Duplicate);
assert_eq!(ledger.ingest(&session()[2]).unwrap(), Ingested::Applied);
let record = ledger.ledger().transaction(&station(), "tx-1").unwrap();
assert_eq!(record.energy().unwrap().unverified_wh(), decimal!(1100.0));
}
#[test]
fn a_duplicate_is_not_journaled() {
let mut ledger = DurableLedger::open(MemLedgerStore::new()).unwrap();
let event = &session()[0];
let _ = ledger.ingest(event).unwrap();
let _ = ledger.ingest(event).unwrap();
assert_eq!(ledger.store().journal_len(), 1);
}
#[test]
fn replaying_the_journal_rebuilds_exactly_the_live_state() {
let mut ledger = DurableLedger::open(MemLedgerStore::new()).unwrap();
let unsequenced = TransactionEvent::new(
station(),
"tx-16",
0,
EventKind::Started,
at("2026-11-07T09:00:00Z"),
);
let _ = ledger.ingest_unsequenced(&unsequenced).unwrap();
for event in &session() {
let _ = ledger.ingest(event).unwrap();
}
let _ = ledger
.prune_ended_before(at("2026-11-07T10:30:00Z"))
.unwrap();
let live = ledger.ledger().clone();
let rebuilt = DurableLedger::open(ledger.into_store()).unwrap();
assert_eq!(rebuilt.ledger(), &live);
}
#[test]
fn a_crash_between_snapshot_and_journal_truncation_replays_correctly() {
let mut ledger = DurableLedger::open(MemLedgerStore::new()).unwrap();
for event in &session() {
let _ = ledger.ingest(event).unwrap();
}
let live = ledger.ledger().clone();
let mut store = ledger.into_store();
let (_, journal) = store.load().unwrap();
store.checkpoint(&live.snapshot()).unwrap();
for entry in &journal {
store.append(entry).unwrap();
}
let rebuilt = DurableLedger::open(store).unwrap();
assert_eq!(rebuilt.ledger(), &live);
}
#[cfg(feature = "std")]
#[test]
fn the_file_store_survives_a_restart_a_checkpoint_and_a_torn_line() {
let dir = std::env::temp_dir().join(format!(
"ocpp-kit-ledger-{}-{:?}",
std::process::id(),
std::thread::current().id()
));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
let mut ledger = DurableLedger::open(FileLedgerStore::open(&dir).unwrap()).unwrap();
let _ = ledger.ingest(&session()[0]).unwrap();
ledger.checkpoint().unwrap();
let _ = ledger.ingest(&session()[1]).unwrap();
drop(ledger);
let mut journal = std::fs::OpenOptions::new()
.append(true)
.open(dir.join("journal.jsonl"))
.unwrap();
std::io::Write::write_all(&mut journal, br#"{"op":"ingest","event":{"ident"#).unwrap();
drop(journal);
let mut ledger = DurableLedger::open(FileLedgerStore::open(&dir).unwrap()).unwrap();
assert_eq!(ledger.ingest(&session()[0]).unwrap(), Ingested::Duplicate);
assert_eq!(ledger.ingest(&session()[1]).unwrap(), Ingested::Duplicate);
assert_eq!(ledger.ingest(&session()[2]).unwrap(), Ingested::Applied);
drop(ledger);
let mut ledger = DurableLedger::open(FileLedgerStore::open(&dir).unwrap()).unwrap();
assert_eq!(ledger.ingest(&session()[2]).unwrap(), Ingested::Duplicate);
let record = ledger.ledger().transaction(&station(), "tx-1").unwrap();
assert!(!record.is_open());
let _ = std::fs::remove_dir_all(&dir);
}
}