CBDDC/docs/remote-peer-configuration.md

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

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.

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.

await peerManagement.RemoveRemotePeerAsync("branch-2", cancellationToken);

Equivalent explicit call:

await peerManagement.RemovePeerTrackingAsync(
    nodeId: "branch-2",
    removeRemoteConfig: true,
    cancellationToken);

Enable or disable a peer

await peerManagement.DisablePeerAsync("branch-2", cancellationToken);
await peerManagement.EnablePeerAsync("branch-2", cancellationToken);

List configured peers

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
  • Peer Deprecation & Removal Runbook