Guide: Integrating with Git
Relevant source files
The following files were used as context for generating this wiki page:Cyberpath Sentinel is designed with a "filesystem is the database" philosophy, and Git integration is a cornerstone of this approach. By leveraging Git, Sentinel provides native auditability, transparent versioning, and simplified replication. Every change to a document can be a commit, creating an immutable, inspectable history of who changed what, when, and why. This makes Sentinel particularly well-suited for applications requiring high levels of trust and compliance, such as audit logs and configuration management.
This integration is not an afterthought but a fundamental part of the system's architecture, enabling powerful features like disaster recovery through a simple git clone and synchronization for edge devices. The Git-based replication is planned as a Phase 5 feature, as detailed in the Implementation Plan.
Sources: README.md:10, 16, 28, IMPLEMENTATION_PLAN.md:15, 345
Architecture and Components
The core of the Git integration is the ReplicationManager, a component designed to handle data synchronization between Sentinel instances.
Sources: IMPLEMENTATION_PLAN.md:218
Replication Manager
The ReplicationManager is responsible for managing the Git repository associated with a Sentinel store. It orchestrates operations like committing changes, pushing to remotes, and pulling updates. The implementation will use the git2 crate for all Git-related operations.
Sources: IMPLEMENTATION_PLAN.md:218-221, 238, 381
The planned structure for the ReplicationManager is as follows:
pub struct ReplicationManager {
store: Arc<Store>,
git_repo: Repository,
}
impl ReplicationManager {
pub async fn sync(&self) -> io::Result<SyncResult>
pub async fn push(&self, remote: &str) -> io::Result<()>
pub async fn pull(&self, remote: &str) -> io::Result<MergeResult>
pub async fn conflict_resolve(&self, strategy: ConflictResolution) -> io::Result<()>
}
Sources: IMPLEMENTATION_PLAN.md:218-233
This diagram illustrates the key components of the ReplicationManager and its relationship with the Store and the git2 library.
Sources: IMPLEMENTATION_PLAN.md:218-233, 381
Replication Strategies
Sentinel will support several replication strategies to accommodate different use cases, from simple one-way syncs to distributed consensus.
| Strategy | Description |
|---|---|
PushPull | Enables bidirectional synchronization. |
PushOnly | The node only writes its changes to a remote. |
PullOnly | The node only reads changes from a remote, acting as a replica. |
Consensus(Raft) | For distributed consensus, using the Raft protocol (optional). |
Sources: IMPLEMENTATION_PLAN.md:222-227
Conflict Resolution
When using bidirectional sync, conflicts can occur. The ReplicationManager is designed to handle them with configurable strategies.
| Strategy | Description |
|---|---|
LastWriteWins | The most recent change automatically overwrites the older one. |
Merge(MergeStrategy) | A specific merge strategy is applied to resolve the conflict. |
Manual | The system flags the conflict for manual intervention. |
Sources: IMPLEMENTATION_PLAN.md:231, 234-238
Deployment and Usage
A key advantage of Git integration is the ability to set up a replicated cluster with standard Git commands and a few Sentinel-specific flags.
Sources: README.md:188-197
Replicated Cluster (Git-backed)
This model consists of a primary node that pushes changes to a central bare Git repository and one or more secondary nodes that pull changes from it.
Example Setup:
- Initialize a bare Git repository on a central server:
git init --bare /data/cyberpath.git - Run the primary Sentinel node:
This node will automatically commit and push changes to themainbranch of theoriginremote.cyberpath-sentinel serve --path /data/cyberpath --git-push origin main - Run a secondary (replica) node:
This node clones the repository and continuously pulls changes.git clone /data/cyberpath.git /data/cyberpath cyberpath-sentinel serve --path /data/cyberpath --git-pull origin main
Sources: README.md:188-197
Synchronization Flow
The following diagram illustrates the data flow in a Git-backed replicated cluster.
This sequence shows how a write operation on the primary node is propagated to a secondary node via the central Git repository.
Sources: README.md:188-197, IMPLEMENTATION_PLAN.md:222-227, 345-350
Roadmap and Implementation
Git-based replication is a planned feature for Sentinel, categorized under Phase 5 of the implementation plan.
| Feature | Phase | Complexity | Priority |
|---|---|---|---|
| Git Replication | 5 | High | P1 |
The core functionality will be built using the git2 Rust crate, which provides bindings for libgit2. This dependency is defined in the project's Cargo.toml and activated via the git-sync feature flag.
Sources: IMPLEMENTATION_PLAN.md:321, 381, Cargo.toml:1
Use Cases Enabled by Git Integration
The tight integration with Git is what enables many of Sentinel's unique advantages for security and compliance-focused applications.
- Audit Logs: Every entry is a file, and every change is a versioned commit, providing a perfect, inspectable audit trail.
- Disaster Recovery: Restoring a database is as simple as running
git clone. - Edge & Disconnected Systems: Sentinel can run on edge devices without a central server and sync its data via Git whenever a connection is available.
- Compliance: The version history can be used to demonstrate compliance over time and satisfy requirements for standards like SOC 2 and ISO 27001.
Sources: README.md:16, 28, 32, 53
Conclusion
Sentinel's use of Git is a deliberate architectural choice that elevates it from a simple file-based database to a trust-oriented data store. It provides native versioning, audibility, and replication, aligning perfectly with the project's goals of transparency and operational simplicity. While the full replication feature is part of the future roadmap, its design is central to the project's vision for creating the gold standard in auditable data storage.