Initial import of the CBDDC codebase with docs and tests. Add a .NET-focused gitignore to keep generated artifacts out of source control.

2026-02-20 13:03:21 -05:00
commit 08bfc17218
218 changed files with 33910 additions and 0 deletions
--- a/docs/remote-peer-configuration.md
+++ b/docs/remote-peer-configuration.md
@@ -0,0 +1,108 @@
+# Remote Peer Configuration
+
+Use `IPeerManagementService` to manage persistent remote peers and their pruning
+tracking lifecycle at runtime.
+
+## Supported peer operations
+
+- Add a static remote peer
+- Remove a configured peer and tracking
+- Remove tracking only (keep static peer config)
+- Enable/disable a peer
+- List all configured peers
+
+## Add a static peer
+
+```csharp
+await peerManagement.AddStaticPeerAsync(
+    "branch-2",
+    "branch2.example.com:9000",
+    cancellationToken);
+```
+
+## Peer lifecycle model
+
+Peer management now has two independent dimensions:
+
+- **Remote peer configuration**: whether a static peer exists in remote peer config.
+- **Peer confirmation tracking**: whether the peer participates in
+  peer-confirmed prune gating.
+
+Common states:
+
+- **Enabled + tracked**: normal operation, peer is eligible for sync and prune gating.
+- **Disabled + tracked**: peer config retained, outbound static sync disabled, still
+  counted as tracked until tracking is removed/deactivated.
+- **Enabled/disabled + untracked**: peer config may remain, but peer is excluded from
+  prune confirmation gating.
+- **Removed**: peer config removed and tracking removed.
+
+## Remove tracking only (deprecate peer from pruning)
+
+Use this when a peer should no longer gate pruning but you are not removing static
+configuration yet.
+
+```csharp
+await peerManagement.RemovePeerTrackingAsync(
+    nodeId: "branch-2",
+    removeRemoteConfig: false,
+    cancellationToken);
+```
+
+## Remove a peer and tracking (full removal)
+
+`RemoveRemotePeerAsync` performs full cleanup by removing both peer tracking and
+static peer configuration.
+
+```csharp
+await peerManagement.RemoveRemotePeerAsync("branch-2", cancellationToken);
+```
+
+Equivalent explicit call:
+
+```csharp
+await peerManagement.RemovePeerTrackingAsync(
+    nodeId: "branch-2",
+    removeRemoteConfig: true,
+    cancellationToken);
+```
+
+## Enable or disable a peer
+
+```csharp
+await peerManagement.DisablePeerAsync("branch-2", cancellationToken);
+await peerManagement.EnablePeerAsync("branch-2", cancellationToken);
+```
+
+## List configured peers
+
+```csharp
+var peers = await peerManagement.GetAllRemotePeersAsync(cancellationToken);
+
+foreach (var peer in peers)
+{
+    Console.WriteLine($"{peer.NodeId} @ {peer.Address} ({peer.Type}) Enabled={peer.IsEnabled}");
+}
+```
+
+## Storage model
+
+Remote peer configuration is persisted in the peer configuration store and synced across nodes as part of CBDDC metadata replication.
+
+Fields stored per peer:
+- `NodeId`
+- `Address`
+- `Type`
+- `IsEnabled`
+- `InterestingCollections`
+
+## Notes
+
+- Authentication for sync handshakes is based on the cluster shared token (`AuthToken`) from node configuration.
+- Disabled peers remain persisted but are excluded from active sync.
+- Peer tracking removal is implemented as deactivation in the confirmation store,
+  which removes the peer from active prune-gating.
+- Re-observed peers can be re-registered and become active for tracking again.
+- For rollout steps and production operations, see:
+  - [Upgrade: Peer-Confirmed Pruning](upgrade-peer-confirmed-pruning.html)
+  - [Peer Deprecation & Removal Runbook](peer-deprecation-removal-runbook.html)