Durability and Atomic Writes

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• IMPLEMENTATION_PLAN.md
• Cargo.toml
• crates/sentinel/Cargo.toml
• crates/sentinel/src/lib.rs
• CODE_OF_CONDUCT.md
• rustfmt.toml

Durability and atomic writes are foundational to Cyberpath Sentinel's goal of providing a trustworthy and compliant data store. Since the database is built directly on the filesystem, it must implement robust mechanisms to handle partial writes (e.g., from a power failure) and ensure that operations are applied in an all-or-nothing manner. Without these guarantees, the integrity of the data cannot be assured, undermining the core principles of auditability and transparency.

The primary strategy to achieve this is through Write-Ahead Logging (WAL), which ensures crash recovery and durability. This is complemented by atomic rename patterns and data integrity checks like checksums and digital signatures. These features are planned for Phase 2 and beyond, transforming the basic file storage into a durable database system.

Sources: README.md:52-53, README.md:88, IMPLEMENTATION_PLAN.md:10-14, IMPLEMENTATION_PLAN.md:310-318

Core Challenge: Partial Write Safety

The main threat to durability in a filesystem-based database is a partial write caused by an unexpected interruption, such as a power failure or application crash. If a write operation is in progress and the system halts, a document file could be left in a corrupted, incomplete state. Sentinel identifies this as a key trade-off and plans to solve it with a combination of techniques.

Sources: README.md:52-53, IMPLEMENTATION_PLAN.md:364-368

Write-Ahead Logging (WAL)

The cornerstone of Sentinel's durability strategy is the implementation of a Write-Ahead Log (WAL). The principle is that all modifications are first written to an append-only log file before being applied to the actual data files. This ensures that in the event of a crash, the system can recover its state by replaying the log.

Sources: README.md:88, IMPLEMENTATION_PLAN.md:143-148, IMPLEMENTATION_PLAN.md:310-318

WAL Architecture

The WAL is managed by the TransactionLog component. It maintains a path to the log files (e.g., data/audit_logs/.wal/) and handles writing log entries, checkpointing, and recovery.

The key data structures for the WAL are TransactionLog and LogEntry.

This diagram shows the TransactionLog struct and its relationship with the LogEntry enum, which defines the types of operations that can be logged.

Sources: IMPLEMENTATION_PLAN.md:65, IMPLEMENTATION_PLAN.md:143-162

The planned Rust implementation for these structures is as follows:

pub struct TransactionLog {
    path: PathBuf,
    current_log: RwLock<File>,
    entries: Arc<RwLock<Vec<LogEntry>>>,
}

pub enum LogEntry {
    Begin { transaction_id: String },
    Insert { collection: String, id: String, data: Value },
    Update { collection: String, id: String, data: Value },
    Delete { collection: String, id: String },
    Commit { transaction_id: String },
    Rollback { transaction_id: String },
}

impl TransactionLog {
    pub async fn write_entry(&self, entry: LogEntry) -> io::Result<()>
    pub async fn checkpoint(&self) -> io::Result<()>
    pub async fn recover(&self) -> io::Result<()>
}

Sources: IMPLEMENTATION_PLAN.md:144-162

Log Entry Format

For efficiency, log entries are planned to be written in a binary format using bincode, with a CRC32 checksum to ensure integrity of each entry.

[Entry Type (1 byte)] [Transaction ID (16 bytes)] [Collection (32 bytes)] [Document ID (256 bytes)] [Data Length (8 bytes)] [Data (N bytes)] [CRC32 (4 bytes)]

The use of bincode and crc32fast is indicated by the planned technology stack.

Sources: IMPLEMENTATION_PLAN.md:165, IMPLEMENTATION_PLAN.md:321-322, IMPLEMENTATION_PLAN.md:424-425

WAL Process Flow

The WAL enables atomic and durable writes through a specific sequence of operations.

1. Begin Transaction: A Begin entry is written to the log.
2. Write Entries: All data operations (Insert, Update, Delete) are written to the log as separate entries. The actual data files are not touched yet.
3. Commit: A Commit entry is written to the log. Once this is successfully flushed to disk, the transaction is considered durable. Even if a crash occurs now, the changes can be recovered.
4. Apply to Files: The changes are written to the actual document files on the filesystem.
5. Checkpoint: Periodically, the system performs a checkpoint, ensuring all committed changes from the log are written to the data files. After a successful checkpoint, the log can be compacted or cleared.

This flow is illustrated below:

Transaction Management

The WAL is the mechanism that enables ACID transactions. The Collection will expose a transaction method to batch multiple operations atomically.

impl Collection {
    // ...
    pub async fn transaction<F>(&self, operations: F) -> io::Result<()>
    // ...
}

Sources: IMPLEMENTATION_PLAN.md:137

The Transaction Manager is a core component responsible for orchestrating these operations, ensuring they have ACID properties, rollback capabilities, and support for savepoints. This is a Phase 2 feature.

Sources: README.md:87, IMPLEMENTATION_PLAN.md:27, IMPLEMENTATION_PLAN.md:328-333

Data Integrity Mechanisms

In addition to the WAL, Sentinel plans other mechanisms to ensure data is not corrupted.

Atomic Rename Pattern

As a simpler alternative or supplement to WAL, an atomic rename pattern can be used for single-file updates. The process is:

1. Write the new content to a temporary file in the same directory.
2. fsync the temporary file to ensure it's on disk.
3. Use an atomic rename operation to replace the original file with the temporary file.

This pattern is mentioned as a solution for partial write safety.

Sources: README.md:53, IMPLEMENTATION_PLAN.md:379

Checksums and Digital Signatures

To protect against silent data corruption, each document includes metadata for integrity verification.

Field	Description	Purpose
_hash	A SHA-256 hash of the document's content.	Detects accidental corruption.
_sig	An RSA-2048 signature of the document.	Detects tampering and provides non-repudiation.

These fields are verified on read to ensure the data has not been altered since it was last written. The use of sha2 and rsa libraries is planned for this.

Sources: README.md:41, README.md:120, IMPLEMENTATION_PLAN.md:74, IMPLEMENTATION_PLAN.md:113, IMPLEMENTATION_PLAN.md:370-377, IMPLEMENTATION_PLAN.md:440

Configuration

Durability features can be configured at the store level.

StoreConfig Option	Type	Default	Description
enable_wal	bool	true	Enables or disables the Write-Ahead Log.
checkpoint_interval	Duration	5 minutes	The time interval between automatic checkpoints.

Sources: IMPLEMENTATION_PLAN.md:93-98

Summary

Cyberpath Sentinel's approach to durability and atomic writes is multi-layered, addressing the inherent risks of a filesystem-based architecture. The Write-Ahead Log is the central component, providing crash recovery and enabling ACID transactions. This is reinforced by atomic file operations, checksums for corruption detection, and digital signatures for tamper-proofing. Together, these planned features are designed to deliver the high level of data integrity and trust that Sentinel aims to provide.

Sources: README.md:35-41, IMPLEMENTATION_PLAN.md:10-14, IMPLEMENTATION_PLAN.md:310-318