Updating Documents (Update)
Relevant source files
The following files were used as context for generating this wiki page:Introduction
In Cyberpath Sentinel, the "Update" operation is a fundamental part of the CRUD (Create, Read, Update, Delete) capabilities. Since Sentinel is a document-based DBMS where the filesystem is the database, updating a document is conceptually an atomic file operation. This design prioritizes auditability and transparency, as every change can be versioned and inspected. The goal is to provide a simple, robust mechanism for modifying documents while ensuring data integrity and durability, even in concurrent environments.
The update process is designed to be efficient, targeting an O(1) time complexity for the core operation by leveraging atomic file renames. However, the full process involves several layers, including concurrency control, durability mechanisms like Write-Ahead Logging (WAL), and maintenance of associated indices, which are critical for performance and reliability at scale.
Sources: README.md:12-14, 114-116, IMPLEMENTATION_PLAN.md:16-22, 395-398
Core API and Data Structures
The primary interface for updating a document is the Collection::update method. This asynchronous function takes a document ID and its new data as input.
Sources: IMPLEMENTATION_PLAN.md:112-114
API Definition
The planned update function signature within the Collection struct is as follows:
// From IMPLEMENTATION_PLAN.md
impl Collection {
// ...
pub async fn update(&self, id: &str, data: Value) -> io::Result<()>
// ...
}
Sources: IMPLEMENTATION_PLAN.md:112, 114
A basic usage example demonstrates its simplicity from the client's perspective:
// From README.md
users.update("user-123", json!({
"name": "Alice",
"email": "alice.smith@example.com",
"role": "admin",
"created_at": "2026-01-11T12:00:00Z"
})).expect("Failed to update");
Sources: README.md:99-105
Key Data Structures
The update operation interacts with the Collection and Document structures. The Document itself contains metadata that is modified during an update, such as the version and timestamp.
The diagram below shows the relationship between the core structures involved in an update.
Sources: IMPLEMENTATION_PLAN.md:104-110, 114
Update Operation Flow
The update process is designed to be atomic and durable. It involves acquiring locks, writing to a Write-Ahead Log (WAL), performing the file operation, and finally updating any relevant indices.
This sequence diagram illustrates the planned high-level flow for an update operation.
Concurrency, Durability, and Integrity
Handling concurrent writes and ensuring data is not lost during failures are critical challenges. The implementation plan outlines a multi-layered strategy to address these issues.
Sources: README.md:52-57, IMPLEMENTATION_PLAN.md:395-412
Concurrency Control
To prevent data corruption from multiple writers, a file locking mechanism is planned. The FileLockManager will be responsible for acquiring and releasing locks on document files.
| Strategy | Description | Implementation |
|---|---|---|
| Exclusive Lock | A single writer is allowed; no readers can access the file during the update. | Implemented using fs2 crate for cross-platform file locking. |
| Optimistic (MVCC) | A long-term goal is to use Multi-Version Concurrency Control, where writers create new versions of a document, and readers see a consistent snapshot. | Planned for a later phase (Phase 7). |
Sources: IMPLEMENTATION_PLAN.md:154-165, 401-405, 411-412
The following flowchart shows the basic logic for acquiring a lock before an update.
Sources: IMPLEMENTATION_PLAN.md:160-164
Durability with Write-Ahead Logging (WAL)
To ensure updates are not lost during a crash, a Write-Ahead Log is used. Before any file is modified on disk, a log entry describing the update is written to the transaction log. If the system crashes, the log can be replayed upon recovery to complete any unfinished operations.
The LogEntry for an update is defined as:
// From IMPLEMENTATION_PLAN.md
pub enum LogEntry {
// ...
Update { collection: String, id: String, data: Value },
// ...
}
Sources: IMPLEMENTATION_PLAN.md:137, 142
Data Integrity
To detect corruption or tampering, each document update will also update the document's metadata with a new hash and an optional digital signature.
- Checksums: A SHA-256 hash of the document content is stored in the
_hashmetadata field. This is verified on read. - Digital Signatures: For higher security, the document can be signed (e.g., with RSA-2048), and the signature is stored in the
_sigfield.
Sources: IMPLEMENTATION_PLAN.md:70-75, 442-452
Performance and Indexing
The update operation is designed for O(1) time complexity, but this only applies to the core file write. The overall performance is affected by other factors like indexing.
Sources: README.md:114-116
Performance Characteristics
| Aspect | Time Complexity | Notes |
|---|---|---|
| Base Update | O(1) | Achieved via an atomic file rename operation. |
| Index Maintenance | O(log n) or O(1) | When an indexed field is updated, the corresponding index (e.g., B-Tree or Hash) must also be updated. |
| WAL Write | O(1) | Appending to the log file is a fast operation. |
Sources: README.md:114-116, IMPLEMENTATION_PLAN.md:323-325, 201
Index Management
When a document is updated, the IndexManager is responsible for updating any indices that involve the modified fields. This is crucial for keeping queries fast and accurate. The IndexManager::update_index function is called as part of the update transaction.
Sources: IMPLEMENTATION_PLAN.md:193, 201
Auditing and Compliance
Every update operation is a recordable event, which is central to Sentinel's design for auditability. An Update event is logged to an immutable audit trail, capturing what changed, when, and by whom.
The AuditEvent and Operation enums are planned to support this:
// From IMPLEMENTATION_PLAN.md
pub enum Operation {
Insert,
Update,
Delete,
// ...
}
pub struct AuditEvent {
pub timestamp: DateTime<Utc>,
pub operation: Operation,
pub user: Option<String>,
pub resource: String,
// ...
}
This structured logging allows for automated compliance reporting for standards like SOC 2, GDPR, and HIPAA.