71 lines
3.6 KiB
Markdown
Executable File
71 lines
3.6 KiB
Markdown
Executable File
# Architecture & Concepts
|
|
|
|
## Design Philosophy
|
|
|
|
CBDDC is designed for **Local Area Networks (LAN)** and **Local-First** scenarios.
|
|
It does not rely on a central master server. Every node is equal (Peer-to-Peer).
|
|
|
|
**Target Deployment**: Trusted LAN environments (offices, homes, private networks)
|
|
**Cross-Platform**: Windows, Linux, macOS (.NET 8.0+, with .NET 6.0 and .NET Standard 2.0 support)
|
|
|
|
### HLC (Hybrid Logical Clock)
|
|
To resolve conflicts without a central authority, we use **Hybrid Logical Clocks**.
|
|
This allows us to determine the "happened-before" relationship between events even if system clocks are slightly skewed.
|
|
In case of concurrent edits, the "Last Write Wins" (LWW) policy based on HLC is applied.
|
|
|
|
## Synchronization
|
|
|
|
### Anti-Entropy
|
|
When two nodes connect, they exchange their latest HLC timestamps.
|
|
- If Node A is ahead of Node B, Node B "pulls" the missing operations from Node A.
|
|
- If Node B is ahead, Node A "pushes" its operations.
|
|
|
|
### Gossip Protocol
|
|
Nodes discover each other via UDP Broadcast (LAN) and then form random TCP connections to gossip updates.
|
|
This ensures that updates propagate exponentially through the network (Epidemic Algorithm).
|
|
|
|
### Snapshots & Fast Recovery
|
|
To optimize reconnection, each node maintains a **Snapshot** of the last known state (Hash & Timestamp) for every peer.
|
|
- When re-connecting, nodes compare their snapshot state.
|
|
- If the chain hash matches, they only exchange the delta.
|
|
- This avoids re-processing the entire operation history and ensures efficient gap recovery.
|
|
|
|
### Peer-Confirmed Oplog Pruning
|
|
CBDDC maintenance pruning now uses a two-cutoff model:
|
|
|
|
- **Retention cutoff**: derived from `OplogRetentionHours` (time-based policy).
|
|
- **Confirmation cutoff**: the oldest confirmation watermark across all active tracked peers and relevant source nodes.
|
|
|
|
The effective prune cutoff is:
|
|
|
|
- `min(retention cutoff, confirmation cutoff)` when confirmation data is complete.
|
|
- retention cutoff only when confirmation tracking is not configured or when there are no active tracked peers.
|
|
- **no prune** for that maintenance cycle when any active tracked peer is missing confirmation for any relevant source stream.
|
|
|
|
Key semantics:
|
|
|
|
- Relevant source streams are taken from the local non-default vector clock entries.
|
|
- A peer only gates pruning while it is active in peer tracking.
|
|
- Removing peer tracking excludes that peer from prune gating.
|
|
- Maintenance logs include explicit skip reasons when pruning is blocked (for example,
|
|
missing confirmation for a tracked peer/source pair).
|
|
|
|
## Security Disclaimer
|
|
|
|
::: warning FOR LAN USE ONLY
|
|
**CBDDC is designed for trusted Local Area Networks.**
|
|
:::
|
|
|
|
- **P2P Mesh Mode**: Designed for **LAN/VPN** use. Uses raw TCP and UDP broadcast. Not safe for public internet by default.
|
|
- **ASP.NET Core Server**: Designed for controlled server deployments. Supports standard HTTPS and hosted sync endpoints.
|
|
- **Transport**: Data is transmitted via raw TCP. There is **NO Encryption (TLS/SSL)** by default.
|
|
- **Authentication**: A basic "Shared Key" mechanism is implemented. Nodes must share the same `AuthToken` to sync.
|
|
- **Authorization**: Once authenticated, a node has full read/write access to all collections.
|
|
|
|
**Recommendation**:
|
|
- Use only within trusted private networks (LAN, VPN, or localhost)
|
|
- For internet deployment, implement TLS, proper authentication, and firewall rules
|
|
- Consider the production hardening features for resilience on LAN
|
|
|
|
**Cross-Platform Support**: Runs on Windows, Linux, and macOS with .NET 8.0+ (also supports .NET 6.0 and .NET Standard 2.0).
|