dohertj2/CBDDC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reformat/cleanup
All checks were successful
NuGet Package Publish / nuget (push) Successful in 1m10s
Details

Browse Source
This commit is contained in:
Joseph Doherty
2026-02-21 07:53:53 -05:00
parent c6f6d9329a
commit 7ebc2cb567
160 changed files with 7258 additions and 7262 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
CBDDC.slnx
View File

@@ -1,23 +1,23 @@
<Solution>
<Configurations>
<Platform Name="Any CPU" />
<Platform Name="x64" />
<Platform Name="x86" />
</Configurations>
<Folder Name="/samples/">
<Project Path="samples/ZB.MOM.WW.CBDDC.Sample.Console/ZB.MOM.WW.CBDDC.Sample.Console.csproj" />
</Folder>
<Folder Name="/src/">
<Project Path="src/ZB.MOM.WW.CBDDC.Hosting/ZB.MOM.WW.CBDDC.Hosting.csproj" />
<Project Path="src/ZB.MOM.WW.CBDDC.Core/ZB.MOM.WW.CBDDC.Core.csproj" />
<Project Path="src/ZB.MOM.WW.CBDDC.Network/ZB.MOM.WW.CBDDC.Network.csproj" />
<Project Path="src/ZB.MOM.WW.CBDDC.Persistence/ZB.MOM.WW.CBDDC.Persistence.csproj" />
</Folder>
<Folder Name="/tests/">
<Project Path="tests/ZB.MOM.WW.CBDDC.Core.Tests/ZB.MOM.WW.CBDDC.Core.Tests.csproj" />
<Project Path="tests/ZB.MOM.WW.CBDDC.E2E.Tests/ZB.MOM.WW.CBDDC.E2E.Tests.csproj" />
<Project Path="tests/ZB.MOM.WW.CBDDC.Hosting.Tests/ZB.MOM.WW.CBDDC.Hosting.Tests.csproj" />
<Project Path="tests/ZB.MOM.WW.CBDDC.Network.Tests/ZB.MOM.WW.CBDDC.Network.Tests.csproj" />
<Project Path="tests/ZB.MOM.WW.CBDDC.Sample.Console.Tests/ZB.MOM.WW.CBDDC.Sample.Console.Tests.csproj" />
</Folder>
<Configurations>
<Platform Name="Any CPU"/>
<Platform Name="x64"/>
<Platform Name="x86"/>
</Configurations>
<Folder Name="/samples/">
<Project Path="samples/ZB.MOM.WW.CBDDC.Sample.Console/ZB.MOM.WW.CBDDC.Sample.Console.csproj"/>
</Folder>
<Folder Name="/src/">
<Project Path="src/ZB.MOM.WW.CBDDC.Hosting/ZB.MOM.WW.CBDDC.Hosting.csproj"/>
<Project Path="src/ZB.MOM.WW.CBDDC.Core/ZB.MOM.WW.CBDDC.Core.csproj"/>
<Project Path="src/ZB.MOM.WW.CBDDC.Network/ZB.MOM.WW.CBDDC.Network.csproj"/>
<Project Path="src/ZB.MOM.WW.CBDDC.Persistence/ZB.MOM.WW.CBDDC.Persistence.csproj"/>
</Folder>
<Folder Name="/tests/">
<Project Path="tests/ZB.MOM.WW.CBDDC.Core.Tests/ZB.MOM.WW.CBDDC.Core.Tests.csproj"/>
<Project Path="tests/ZB.MOM.WW.CBDDC.E2E.Tests/ZB.MOM.WW.CBDDC.E2E.Tests.csproj"/>
<Project Path="tests/ZB.MOM.WW.CBDDC.Hosting.Tests/ZB.MOM.WW.CBDDC.Hosting.Tests.csproj"/>
<Project Path="tests/ZB.MOM.WW.CBDDC.Network.Tests/ZB.MOM.WW.CBDDC.Network.Tests.csproj"/>
<Project Path="tests/ZB.MOM.WW.CBDDC.Sample.Console.Tests/ZB.MOM.WW.CBDDC.Sample.Console.Tests.csproj"/>
</Folder>
</Solution>

10
Directory.Build.props
View File

@@ -1,7 +1,7 @@
<Project>
<PropertyGroup>
<EnableNETAnalyzers>true</EnableNETAnalyzers>
<AnalysisLevel>latest</AnalysisLevel>
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>
<PropertyGroup>
<EnableNETAnalyzers>true</EnableNETAnalyzers>
<AnalysisLevel>latest</AnalysisLevel>
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>
</Project>

106
samples/ZB.MOM.WW.CBDDC.Sample.Console/ConsoleInteractiveService.cs
View File

@@ -1,37 +1,33 @@
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ZB.MOM.WW.CBDDC.Core;
using Serilog.Context;
using ZB.MOM.WW.CBDDC.Core.Cache;
using ZB.MOM.WW.CBDDC.Core.Diagnostics;
using ZB.MOM.WW.CBDDC.Core.Sync;
using ZB.MOM.WW.CBDDC.Core.Storage;
using ZB.MOM.WW.CBDDC.Network;
using ZB.MOM.WW.CBDDC.Persistence.BLite;
using Microsoft.Extensions.DependencyInjection; // For IServiceProvider if needed
using Serilog.Context;
using ZB.MOM.WW.CBDDC.Sample.Console;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core.Sync;
using ZB.MOM.WW.CBDDC.Network;
using ZB.MOM.WW.CBDDC.Network.Security;
// For IServiceProvider if needed
namespace ZB.MOM.WW.CBDDC.Sample.Console;
public class ConsoleInteractiveService : BackgroundService
{
private readonly ILogger<ConsoleInteractiveService> _logger;
private readonly SampleDbContext _db;
private readonly ICBDDCNode _node;
private readonly IHostApplicationLifetime _lifetime;
// Auxiliary services for status/commands
private readonly IDocumentCache _cache;
private readonly IOfflineQueue _queue;
private readonly ICBDDCHealthCheck _healthCheck;
private readonly ISyncStatusTracker _syncTracker;
private readonly IServiceProvider _serviceProvider;
private readonly IPeerNodeConfigurationProvider _configProvider;
private readonly SampleDbContext _db;
private readonly ICBDDCHealthCheck _healthCheck;
private readonly IHostApplicationLifetime _lifetime;
private readonly ILogger<ConsoleInteractiveService> _logger;
private readonly ICBDDCNode _node;
private readonly IOfflineQueue _queue;
private readonly IServiceProvider _serviceProvider;
private readonly ISyncStatusTracker _syncTracker;
/// <summary>
/// Initializes a new instance of the <see cref="ConsoleInteractiveService"/> class.
/// Initializes a new instance of the <see cref="ConsoleInteractiveService" /> class.
/// </summary>
/// <param name="logger">The logger used by the interactive service.</param>
/// <param name="db">The sample database context.</param>
@@ -72,7 +68,7 @@ public class ConsoleInteractiveService : BackgroundService
{
var config = await _configProvider.GetConfiguration();
System.Console.WriteLine($"--- Interactive Console ---");
System.Console.WriteLine("--- Interactive Console ---");
System.Console.WriteLine($"Node ID: {config.NodeId}");
PrintHelp();
@@ -85,7 +81,7 @@ public class ConsoleInteractiveService : BackgroundService
continue;
}
var input = System.Console.ReadLine();
string? input = System.Console.ReadLine();
if (string.IsNullOrEmpty(input)) continue;
try
@@ -118,42 +114,53 @@ public class ConsoleInteractiveService : BackgroundService
System.Console.WriteLine(" [n]ew (auto), [s]pam (5x), [c]ount, [t]odos");
System.Console.WriteLine(" [h]ealth, cac[h]e");
System.Console.WriteLine(" [r]esolver [lww|merge], [demo] conflict");
}
}
private async Task HandleInput(string input)
{
var config = await _configProvider.GetConfiguration();
if (input.StartsWith("n"))
{
var ts = DateTime.Now.ToString("HH:mm:ss.fff");
var user = new User { Id = Guid.NewGuid().ToString(), Name = $"User-{ts}", Age = new Random().Next(18, 90), Address = new Address { City = "AutoCity" } };
var user = new User
{
Id = Guid.NewGuid().ToString(), Name = $"User-{ts}", Age = new Random().Next(18, 90),
Address = new Address { City = "AutoCity" }
};
await _db.Users.InsertAsync(user);
await _db.SaveChangesAsync();
System.Console.WriteLine($"[+] Created {user.Name} with Id: {user.Id}...");
}
else if (input.StartsWith("s"))
{
for (int i = 0; i < 5; i++)
for (var i = 0; i < 5; i++)
{
var ts = DateTime.Now.ToString("HH:mm:ss.fff");
var user = new User { Id = Guid.NewGuid().ToString(), Name = $"User-{ts}", Age = new Random().Next(18, 90), Address = new Address { City = "SpamCity" } };
var user = new User
{
Id = Guid.NewGuid().ToString(), Name = $"User-{ts}", Age = new Random().Next(18, 90),
Address = new Address { City = "SpamCity" }
};
await _db.Users.InsertAsync(user);
System.Console.WriteLine($"[+] Created {user.Name} with Id: {user.Id}...");
await Task.Delay(100);
}
await _db.SaveChangesAsync();
}
else if (input.StartsWith("c"))
{
var userCount = _db.Users.FindAll().Count();
var todoCount = _db.TodoLists.FindAll().Count();
int userCount = _db.Users.FindAll().Count();
int todoCount = _db.TodoLists.FindAll().Count();
System.Console.WriteLine($"Collection 'Users': {userCount} documents");
System.Console.WriteLine($"Collection 'TodoLists': {todoCount} documents");
}
else if (input.StartsWith("p"))
{
var alice = new User { Id = Guid.NewGuid().ToString(), Name = "Alice", Age = 30, Address = new Address { City = "Paris" } };
var bob = new User { Id = Guid.NewGuid().ToString(), Name = "Bob", Age = 25, Address = new Address { City = "Rome" } };
var alice = new User
{ Id = Guid.NewGuid().ToString(), Name = "Alice", Age = 30, Address = new Address { City = "Paris" } };
var bob = new User
{ Id = Guid.NewGuid().ToString(), Name = "Bob", Age = 25, Address = new Address { City = "Rome" } };
await _db.Users.InsertAsync(alice);
await _db.Users.InsertAsync(bob);
await _db.SaveChangesAsync();
@@ -162,17 +169,19 @@ public class ConsoleInteractiveService : BackgroundService
else if (input.StartsWith("g"))
{
System.Console.Write("Enter user Id: ");
var id = System.Console.ReadLine();
string? id = System.Console.ReadLine();
if (!string.IsNullOrEmpty(id))
{
var u = _db.Users.FindById(id);
System.Console.WriteLine(u != null ? $"Got: {u.Name}, Age {u.Age}, City: {u.Address?.City}" : "Not found");
System.Console.WriteLine(u != null
? $"Got: {u.Name}, Age {u.Age}, City: {u.Address?.City}"
: "Not found");
}
}
else if (input.StartsWith("d"))
{
System.Console.Write("Enter user Id to delete: ");
var id = System.Console.ReadLine();
string? id = System.Console.ReadLine();
if (!string.IsNullOrEmpty(id))
{
await _db.Users.DeleteAsync(id);
@@ -183,8 +192,8 @@ public class ConsoleInteractiveService : BackgroundService
else if (input.StartsWith("l"))
{
var peers = _node.Discovery.GetActivePeers();
var handshakeSvc = _serviceProvider.GetService<ZB.MOM.WW.CBDDC.Network.Security.IPeerHandshakeService>();
var secureIcon = handshakeSvc != null ? "🔒" : "🔓";
var handshakeSvc = _serviceProvider.GetService<IPeerHandshakeService>();
string secureIcon = handshakeSvc != null ? "🔒" : "🔓";
System.Console.WriteLine($"Active Peers ({secureIcon}):");
foreach (var p in peers)
@@ -203,7 +212,7 @@ public class ConsoleInteractiveService : BackgroundService
{
var health = await _healthCheck.CheckAsync();
var syncStatus = _syncTracker.GetStatus();
var handshakeSvc = _serviceProvider.GetService<ZB.MOM.WW.CBDDC.Network.Security.IPeerHandshakeService>();
var handshakeSvc = _serviceProvider.GetService<IPeerHandshakeService>();
System.Console.WriteLine("=== Health Check ===");
System.Console.WriteLine($"Database: {(health.DatabaseHealthy ? "✓" : "✗")}");
@@ -216,17 +225,18 @@ public class ConsoleInteractiveService : BackgroundService
if (health.Errors.Any())
{
System.Console.WriteLine("Errors:");
foreach (var err in health.Errors.Take(3)) System.Console.WriteLine($" - {err}");
foreach (string err in health.Errors.Take(3)) System.Console.WriteLine($" - {err}");
}
}
else if (input.StartsWith("ch") || input == "cache")
{
var stats = _cache.GetStatistics();
System.Console.WriteLine($"=== Cache Stats ===\nSize: {stats.Size}\nHits: {stats.Hits}\nMisses: {stats.Misses}\nRate: {stats.HitRate:P1}");
System.Console.WriteLine(
$"=== Cache Stats ===\nSize: {stats.Size}\nHits: {stats.Hits}\nMisses: {stats.Misses}\nRate: {stats.HitRate:P1}");
}
else if (input.StartsWith("r") && input.Contains("resolver"))
{
var parts = input.Split(' ');
string[] parts = input.Split(' ');
if (parts.Length > 1)
{
var newResolver = parts[1].ToLower() switch
@@ -240,7 +250,7 @@ public class ConsoleInteractiveService : BackgroundService
{
// Note: Requires restart to fully apply. For demo, we inform user.
System.Console.WriteLine($"⚠️ Resolver changed to {parts[1].ToUpper()}. Restart node to apply.");
System.Console.WriteLine($" (Current session continues with previous resolver)");
System.Console.WriteLine(" (Current session continues with previous resolver)");
}
else
{
@@ -262,7 +272,7 @@ public class ConsoleInteractiveService : BackgroundService
System.Console.WriteLine($"📋 {list.Name} ({list.Items.Count} items)");
foreach (var item in list.Items)
{
var status = item.Completed ? "✓" : " ";
string status = item.Completed ? "✓" : " ";
System.Console.WriteLine($" [{status}] {item.Task}");
}
}
@@ -281,8 +291,8 @@ public class ConsoleInteractiveService : BackgroundService
Name = "Shopping List",
Items = new List<TodoItem>
{
new TodoItem { Task = "Buy milk", Completed = false },
new TodoItem { Task = "Buy bread", Completed = false }
new() { Task = "Buy milk", Completed = false },
new() { Task = "Buy bread", Completed = false }
}
};
@@ -325,24 +335,20 @@ public class ConsoleInteractiveService : BackgroundService
System.Console.WriteLine($" List: {merged.Name}");
foreach (var item in merged.Items)
{
var status = item.Completed ? "✓" : " ";
string status = item.Completed ? "✓" : " ";
System.Console.WriteLine($" [{status}] {item.Task}");
}
var resolver = _serviceProvider.GetRequiredService<IConflictResolver>();
var resolverType = resolver.GetType().Name;
string resolverType = resolver.GetType().Name;
System.Console.WriteLine($"\nℹ️ Resolution Strategy: {resolverType}");
if (resolverType.Contains("Recursive"))
{
System.Console.WriteLine(" → Items merged by 'id', both edits preserved");
}
else
{
System.Console.WriteLine(" → Last write wins, Node B changes override Node A");
}
}
System.Console.WriteLine("\n✓ Demo complete. Run 'todos' to see all lists.\n");
}
}
}

65
samples/ZB.MOM.WW.CBDDC.Sample.Console/Program.cs
View File

@@ -1,33 +1,26 @@
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Core.Storage;
using ZB.MOM.WW.CBDDC.Core.Cache;
using ZB.MOM.WW.CBDDC.Core.Sync;
using ZB.MOM.WW.CBDDC.Core.Diagnostics;
using ZB.MOM.WW.CBDDC.Core.Resilience;
using ZB.MOM.WW.CBDDC.Network;
using ZB.MOM.WW.CBDDC.Network.Security;
using ZB.MOM.WW.CBDDC.Persistence.BLite;
using ZB.MOM.WW.CBDDC.Sample.Console;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Serilog;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core.Sync;
using ZB.MOM.WW.CBDDC.Network;
using ZB.MOM.WW.CBDDC.Persistence.BLite;
namespace ZB.MOM.WW.CBDDC.Sample.Console;
// Local User/Address classes removed in favor of Shared project
class Program
internal class Program
{
static async Task Main(string[] args)
private static async Task Main(string[] args)
{
var builder = Host.CreateApplicationBuilder(args);
// Configuration
builder.Configuration.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true);
.AddJsonFile("appsettings.json", true, true);
// Logging
builder.Logging.ClearProviders();
@@ -38,39 +31,36 @@ class Program
.Enrich.WithProperty("Application", "CBDDC.Sample.Console")
.WriteTo.Console());
var randomPort = new Random().Next(1000, 9999);
int randomPort = new Random().Next(1000, 9999);
// Node ID
string nodeId = args.Length > 0 ? args[0] : ("node-" + randomPort);
string nodeId = args.Length > 0 ? args[0] : "node-" + randomPort;
int tcpPort = args.Length > 1 ? int.Parse(args[1]) : randomPort;
// Conflict Resolution Strategy (can be switched at runtime via service replacement)
var useRecursiveMerge = args.Contains("--merge");
if (useRecursiveMerge)
{
builder.Services.AddSingleton<IConflictResolver, RecursiveNodeMergeConflictResolver>();
}
bool useRecursiveMerge = args.Contains("--merge");
if (useRecursiveMerge) builder.Services.AddSingleton<IConflictResolver, RecursiveNodeMergeConflictResolver>();
IPeerNodeConfigurationProvider peerNodeConfigurationProvider = new StaticPeerNodeConfigurationProvider(
new PeerNodeConfiguration
{
NodeId = nodeId,
TcpPort = tcpPort,
AuthToken = "Test-Cluster-Key",
AuthToken = "Test-Cluster-Key"
//KnownPeers = builder.Configuration.GetSection("CBDDC:KnownPeers").Get<List<KnownPeerConfiguration>>() ?? new()
});
builder.Services.AddSingleton<IPeerNodeConfigurationProvider>(peerNodeConfigurationProvider);
builder.Services.AddSingleton(peerNodeConfigurationProvider);
// Database path
var dataPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "data");
string dataPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "data");
Directory.CreateDirectory(dataPath);
var databasePath = Path.Combine(dataPath, $"{nodeId}.blite");
string databasePath = Path.Combine(dataPath, $"{nodeId}.blite");
// Register CBDDC Services using Fluent Extensions with BLite, SampleDbContext, and SampleDocumentStore
builder.Services.AddCBDDCCore()
.AddCBDDCBLite<SampleDbContext, SampleDocumentStore>(sp => new SampleDbContext(databasePath))
.AddCBDDCNetwork<StaticPeerNodeConfigurationProvider>(); // useHostedService = true by default
.AddCBDDCBLite<SampleDbContext, SampleDocumentStore>(sp => new SampleDbContext(databasePath))
.AddCBDDCNetwork<StaticPeerNodeConfigurationProvider>(); // useHostedService = true by default
builder.Services.AddHostedService<ConsoleInteractiveService>(); // Runs the Input Loop
@@ -86,12 +76,7 @@ class Program
private class StaticPeerNodeConfigurationProvider : IPeerNodeConfigurationProvider
{
/// <summary>
/// Gets or sets the current peer node configuration.
/// </summary>
public PeerNodeConfiguration Configuration { get; set; }
/// <summary>
/// Initializes a new instance of the <see cref="StaticPeerNodeConfigurationProvider"/> class.
/// Initializes a new instance of the <see cref="StaticPeerNodeConfigurationProvider" /> class.
/// </summary>
/// <param name="configuration">The initial peer node configuration.</param>
public StaticPeerNodeConfigurationProvider(PeerNodeConfiguration configuration)
@@ -100,12 +85,17 @@ class Program
}
/// <summary>
/// Occurs when the peer node configuration changes.
/// Gets or sets the current peer node configuration.
/// </summary>
public PeerNodeConfiguration Configuration { get; }
/// <summary>
/// Occurs when the peer node configuration changes.
/// </summary>
public event PeerNodeConfigurationChangedEventHandler? ConfigurationChanged;
/// <summary>
/// Gets the current peer node configuration.
/// Gets the current peer node configuration.
/// </summary>
/// <returns>A task that returns the current configuration.</returns>
public Task<PeerNodeConfiguration> GetConfiguration()
@@ -114,7 +104,7 @@ class Program
}
/// <summary>
/// Raises the configuration changed event.
/// Raises the configuration changed event.
/// </summary>
/// <param name="newConfig">The new configuration value.</param>
protected virtual void OnConfigurationChanged(PeerNodeConfiguration newConfig)
@@ -122,5 +112,4 @@ class Program
ConfigurationChanged?.Invoke(this, newConfig);
}
}
}
}

35
samples/ZB.MOM.WW.CBDDC.Sample.Console/README.md
View File

@@ -5,21 +5,25 @@ This sample demonstrates the core features of CBDDC, a distributed peer-to-peer
## Features Demonstrated
### 🔑 Primary Keys & Auto-Generation
- Automatic GUID generation for entities
- Convention-based key detection (`Id` property)
- `[PrimaryKey]` attribute support
### 🎯 Generic Type-Safe API
- `Collection<T>()` for compile-time type safety
- Keyless `Put(entity)` with auto-key extraction
- IntelliSense-friendly operations
### 🔍 LINQ Query Support
- Expression-based queries
- Paging and sorting
- Complex predicates (>, >=, ==, !=, nested properties)
### 🌐 Network Synchronization
- UDP peer discovery
- TCP synchronization
- Automatic conflict resolution (Last-Write-Wins)
@@ -35,16 +39,19 @@ dotnet run
### Multi-Node (Peer-to-Peer)
Terminal 1:
```bash
dotnet run -- --node-id node1 --tcp-port 5001 --udp-port 6001
```
Terminal 2:
```bash
dotnet run -- --node-id node2 --tcp-port 5002 --udp-port 6002
```
Terminal 3:
```bash
dotnet run -- --node-id node3 --tcp-port 5003 --udp-port 6003
```
@@ -53,20 +60,20 @@ Changes made on any node will automatically sync to all peers!
## Available Commands
| Command | Description |
|---------|-------------|
| `p` | Put Alice and Bob (auto-generated IDs) |
| `g` | Get user by ID (prompts for ID) |
| `d` | Delete user by ID (prompts for ID) |
| `n` | Create new user with auto-generated ID |
| `s` | Spam 5 users with auto-generated IDs |
| `c` | Count total documents |
| `f` | Demo various Find queries |
| `f2` | Demo Find with paging (skip/take) |
| `a` | Demo auto-generated primary keys |
| `t` | Demo generic typed API |
| `l` | List active peers |
| `q` | Quit |
| Command | Description |
|---------|----------------------------------------|
| `p` | Put Alice and Bob (auto-generated IDs) |
| `g` | Get user by ID (prompts for ID) |
| `d` | Delete user by ID (prompts for ID) |
| `n` | Create new user with auto-generated ID |
| `s` | Spam 5 users with auto-generated IDs |
| `c` | Count total documents |
| `f` | Demo various Find queries |
| `f2` | Demo Find with paging (skip/take) |
| `a` | Demo auto-generated primary keys |
| `t` | Demo generic typed API |
| `l` | List active peers |
| `q` | Quit |
## Example Session

35
samples/ZB.MOM.WW.CBDDC.Sample.Console/SampleDbContext.cs
View File

@@ -2,28 +2,13 @@
using BLite.Core.Metadata;
using BLite.Core.Storage;
using ZB.MOM.WW.CBDDC.Persistence.BLite;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Sample.Console;
public partial class SampleDbContext : CBDDCDocumentDbContext
public class SampleDbContext : CBDDCDocumentDbContext
{
/// <summary>
/// Gets the users collection.
/// </summary>
public DocumentCollection<string, User> Users { get; private set; } = null!;
/// <summary>
/// Gets the todo lists collection.
/// </summary>
public DocumentCollection<string, TodoList> TodoLists { get; private set; } = null!;
/// <summary>
/// Initializes a new instance of the SampleDbContext class using the specified database file path.
/// Initializes a new instance of the SampleDbContext class using the specified database file path.
/// </summary>
/// <param name="databasePath">The file system path to the database file. Cannot be null or empty.</param>
public SampleDbContext(string databasePath) : base(databasePath)
@@ -31,8 +16,8 @@ public partial class SampleDbContext : CBDDCDocumentDbContext
}
/// <summary>
/// Initializes a new instance of the SampleDbContext class using the specified database file path and page file
/// configuration.
/// Initializes a new instance of the SampleDbContext class using the specified database file path and page file
/// configuration.
/// </summary>
/// <param name="databasePath">The file system path to the database file. Cannot be null or empty.</param>
/// <param name="config">The configuration settings for the page file. Cannot be null.</param>
@@ -40,6 +25,16 @@ public partial class SampleDbContext : CBDDCDocumentDbContext
{
}
/// <summary>
/// Gets the users collection.
/// </summary>
public DocumentCollection<string, User> Users { get; private set; } = null!;
/// <summary>
/// Gets the todo lists collection.
/// </summary>
public DocumentCollection<string, TodoList> TodoLists { get; private set; } = null!;
/// <inheritdoc />
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
@@ -52,4 +47,4 @@ public partial class SampleDbContext : CBDDCDocumentDbContext
.ToCollection("TodoLists")
.HasKey(t => t.Id);
}
}
}

74
samples/ZB.MOM.WW.CBDDC.Sample.Console/SampleDocumentStore.cs
View File

@@ -1,16 +1,15 @@
using ZB.MOM.WW.CBDDC.Core;
using System.Text.Json;
using Microsoft.Extensions.Logging;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core.Storage;
using ZB.MOM.WW.CBDDC.Core.Sync;
using ZB.MOM.WW.CBDDC.Persistence.BLite;
using Microsoft.Extensions.Logging;
using System.Text.Json;
namespace ZB.MOM.WW.CBDDC.Sample.Console;
/// <summary>
/// Document store implementation for CBDDC Sample using BLite persistence.
/// Extends BLiteDocumentStore to automatically handle Oplog creation via CDC.
/// Document store implementation for CBDDC Sample using BLite persistence.
/// Extends BLiteDocumentStore to automatically handle Oplog creation via CDC.
/// </summary>
public class SampleDocumentStore : BLiteDocumentStore<SampleDbContext>
{
@@ -18,7 +17,7 @@ public class SampleDocumentStore : BLiteDocumentStore<SampleDbContext>
private const string TodoListsCollection = "TodoLists";
/// <summary>
/// Initializes a new instance of the <see cref="SampleDocumentStore"/> class.
/// Initializes a new instance of the <see cref="SampleDocumentStore" /> class.
/// </summary>
/// <param name="context">The sample database context.</param>
/// <param name="configProvider">The peer node configuration provider.</param>
@@ -37,6 +36,16 @@ public class SampleDocumentStore : BLiteDocumentStore<SampleDbContext>
WatchCollection(TodoListsCollection, context.TodoLists, t => t.Id);
}
#region Helper Methods
private static JsonElement? SerializeEntity<T>(T? entity) where T : class
{
if (entity == null) return null;
return JsonSerializer.SerializeToElement(entity);
}
#endregion
#region Abstract Method Implementations
/// <inheritdoc />
@@ -49,12 +58,10 @@ public class SampleDocumentStore : BLiteDocumentStore<SampleDbContext>
/// <inheritdoc />
protected override async Task ApplyContentToEntitiesBatchAsync(
IEnumerable<(string Collection, string Key, JsonElement Content)> documents, CancellationToken cancellationToken)
IEnumerable<(string Collection, string Key, JsonElement Content)> documents,
CancellationToken cancellationToken)
{
foreach (var (collection, key, content) in documents)
{
UpsertEntity(collection, key, content);
}
foreach ((string collection, string key, var content) in documents) UpsertEntity(collection, key, content);
await _context.SaveChangesAsync(cancellationToken);
}
@@ -91,10 +98,10 @@ public class SampleDocumentStore : BLiteDocumentStore<SampleDbContext>
protected override Task<JsonElement?> GetEntityAsJsonAsync(
string collection, string key, CancellationToken cancellationToken)
{
return Task.FromResult<JsonElement?>(collection switch
return Task.FromResult(collection switch
{
UsersCollection => SerializeEntity(_context.Users.Find(u => u.Id == key).FirstOrDefault()),
TodoListsCollection => SerializeEntity(_context.TodoLists.Find(t => t.Id == key).FirstOrDefault()),
UsersCollection => SerializeEntity(_context.Users.Find(u => u.Id == key).FirstOrDefault()),
TodoListsCollection => SerializeEntity(_context.TodoLists.Find(t => t.Id == key).FirstOrDefault()),
_ => null
});
}
@@ -111,10 +118,7 @@ public class SampleDocumentStore : BLiteDocumentStore<SampleDbContext>
protected override async Task RemoveEntitiesBatchAsync(
IEnumerable<(string Collection, string Key)> documents, CancellationToken cancellationToken)
{
foreach (var (collection, key) in documents)
{
DeleteEntity(collection, key);
}
foreach ((string collection, string key) in documents) DeleteEntity(collection, key);
await _context.SaveChangesAsync(cancellationToken);
}
@@ -140,25 +144,15 @@ public class SampleDocumentStore : BLiteDocumentStore<SampleDbContext>
{
return await Task.Run(() => collection switch
{
UsersCollection => _context.Users.FindAll()
.Select(u => (u.Id, SerializeEntity(u)!.Value)),
TodoListsCollection => _context.TodoLists.FindAll()
.Select(t => (t.Id, SerializeEntity(t)!.Value)),
_ => Enumerable.Empty<(string, JsonElement)>()
}, cancellationToken);
}
#endregion
#region Helper Methods
private static JsonElement? SerializeEntity<T>(T? entity) where T : class
{
if (entity == null) return null;
return JsonSerializer.SerializeToElement(entity);
}
#endregion
}
UsersCollection => _context.Users.FindAll()
.Select(u => (u.Id, SerializeEntity(u)!.Value)),
TodoListsCollection => _context.TodoLists.FindAll()
.Select(t => (t.Id, SerializeEntity(t)!.Value)),
_ => Enumerable.Empty<(string, JsonElement)>()
}, cancellationToken);
}
#endregion
}

23
samples/ZB.MOM.WW.CBDDC.Sample.Console/TodoList.cs
View File

@@ -1,23 +1,22 @@
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
namespace ZB.MOM.WW.CBDDC.Sample.Console;
using System.ComponentModel.DataAnnotations;
namespace ZB.MOM.WW.CBDDC.Sample.Console;
public class TodoList
{
/// <summary>
/// Gets or sets the document identifier.
/// Gets or sets the document identifier.
/// </summary>
[Key]
public string Id { get; set; } = Guid.NewGuid().ToString();
/// <summary>
/// Gets or sets the list name.
/// Gets or sets the list name.
/// </summary>
public string Name { get; set; } = string.Empty;
/// <summary>
/// Gets or sets the todo items in the list.
/// Gets or sets the todo items in the list.
/// </summary>
public List<TodoItem> Items { get; set; } = new();
}
@@ -25,17 +24,17 @@ public class TodoList
public class TodoItem
{
/// <summary>
/// Gets or sets the task description.
/// Gets or sets the task description.
/// </summary>
public string Task { get; set; } = string.Empty;
/// <summary>
/// Gets or sets a value indicating whether the task is completed.
/// Gets or sets a value indicating whether the task is completed.
/// </summary>
public bool Completed { get; set; }
/// <summary>
/// Gets or sets the UTC creation timestamp.
/// Gets or sets the UTC creation timestamp.
/// </summary>
public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}
}

20
samples/ZB.MOM.WW.CBDDC.Sample.Console/User.cs
View File

@@ -1,27 +1,27 @@
using System.ComponentModel.DataAnnotations;
namespace ZB.MOM.WW.CBDDC.Sample.Console;
using System.ComponentModel.DataAnnotations;
namespace ZB.MOM.WW.CBDDC.Sample.Console;
public class User
{
/// <summary>
/// Gets or sets the unique user identifier.
/// Gets or sets the unique user identifier.
/// </summary>
[Key]
public string Id { get; set; } = "";
/// <summary>
/// Gets or sets the user name.
/// Gets or sets the user name.
/// </summary>
public string? Name { get; set; }
/// <summary>
/// Gets or sets the user age.
/// Gets or sets the user age.
/// </summary>
public int Age { get; set; }
/// <summary>
/// Gets or sets the user address.
/// Gets or sets the user address.
/// </summary>
public Address? Address { get; set; }
}
@@ -29,7 +29,7 @@ public class User
public class Address
{
/// <summary>
/// Gets or sets the city value.
/// Gets or sets the city value.
/// </summary>
public string? City { get; set; }
}
}

70
samples/ZB.MOM.WW.CBDDC.Sample.Console/ZB.MOM.WW.CBDDC.Sample.Console.csproj
View File

@@ -1,41 +1,41 @@
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<PackageReference Include="Lifter.Core" Version="1.1.0" />
<PackageReference Include="BLite.SourceGenerators" Version="1.3.1">
<PrivateAssets>all</PrivateAssets>
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
<ProjectReference Include="..\..\src\ZB.MOM.WW.CBDDC.Core\ZB.MOM.WW.CBDDC.Core.csproj" />
<ProjectReference Include="..\..\src\ZB.MOM.WW.CBDDC.Network\ZB.MOM.WW.CBDDC.Network.csproj" />
<ProjectReference Include="..\..\src\ZB.MOM.WW.CBDDC.Persistence\ZB.MOM.WW.CBDDC.Persistence.csproj" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Lifter.Core" Version="1.1.0"/>
<PackageReference Include="BLite.SourceGenerators" Version="1.3.1">
<PrivateAssets>all</PrivateAssets>
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
<ProjectReference Include="..\..\src\ZB.MOM.WW.CBDDC.Core\ZB.MOM.WW.CBDDC.Core.csproj"/>
<ProjectReference Include="..\..\src\ZB.MOM.WW.CBDDC.Network\ZB.MOM.WW.CBDDC.Network.csproj"/>
<ProjectReference Include="..\..\src\ZB.MOM.WW.CBDDC.Persistence\ZB.MOM.WW.CBDDC.Persistence.csproj"/>
</ItemGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.0" />
<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.0" />
<PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="9.0.0" />
<PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.0" />
<PackageReference Include="Serilog" Version="4.2.0" />
<PackageReference Include="Serilog.Extensions.Hosting" Version="9.0.0" />
<PackageReference Include="Serilog.Sinks.Console" Version="6.0.0" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.0"/>
<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.0"/>
<PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="9.0.0"/>
<PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.0"/>
<PackageReference Include="Serilog" Version="4.2.0"/>
<PackageReference Include="Serilog.Extensions.Hosting" Version="9.0.0"/>
<PackageReference Include="Serilog.Sinks.Console" Version="6.0.0"/>
</ItemGroup>
<ItemGroup>
<None Update="appsettings.json">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>
</ItemGroup>
<ItemGroup>
<None Update="appsettings.json">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>
</ItemGroup>
<PropertyGroup>
<AssemblyName>ZB.MOM.WW.CBDDC.Sample.Console</AssemblyName>
<RootNamespace>ZB.MOM.WW.CBDDC.Sample.Console</RootNamespace>
<PackageId>ZB.MOM.WW.CBDDC.Sample.Console</PackageId>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<IsPackable>false</IsPackable>
</PropertyGroup>
<PropertyGroup>
<AssemblyName>ZB.MOM.WW.CBDDC.Sample.Console</AssemblyName>
<RootNamespace>ZB.MOM.WW.CBDDC.Sample.Console</RootNamespace>
<PackageId>ZB.MOM.WW.CBDDC.Sample.Console</PackageId>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<IsPackable>false</IsPackable>
</PropertyGroup>
</Project>
</Project>

94
samples/ZB.MOM.WW.CBDDC.Sample.Console/appsettings.json
View File

@@ -1,51 +1,51 @@
{
"Logging": {
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"System": "Warning",
"CBDDC": "Information",
"ZB.MOM.WW.CBDDC.Network.SyncOrchestrator": "Information",
"ZB.MOM.WW.CBDDC.Core.Storage.OplogCoordinator": "Warning",
"ZB.MOM.WW.CBDDC.Persistence": "Warning"
}
},
"CBDDC": {
"Network": {
"TcpPort": 5001,
"UdpPort": 6000,
"AuthToken": "demo-secret-key",
"ConnectionTimeoutMs": 5000,
"RetryAttempts": 3,
"RetryDelayMs": 1000,
"LocalhostOnly": false
},
"Persistence": {
"DatabasePath": "data/cbddc.db",
"EnableWalMode": true,
"CacheSizeMb": 50,
"EnableAutoBackup": true,
"BackupPath": "backups/",
"BusyTimeoutMs": 5000
},
"Sync": {
"SyncIntervalMs": 5000,
"BatchSize": 100,
"EnableOfflineQueue": true,
"MaxQueueSize": 1000
},
"Logging": {
"LogLevel": "Information",
"LogFilePath": "logs/cbddc.log",
"MaxLogFileSizeMb": 10,
"MaxLogFiles": 5
},
"KnownPeers": [
{
"NodeId": "AspNetSampleNode",
"Host": "localhost",
"Port": 6001
}
]
"Default": "Information",
"Microsoft": "Warning",
"System": "Warning",
"CBDDC": "Information",
"ZB.MOM.WW.CBDDC.Network.SyncOrchestrator": "Information",
"ZB.MOM.WW.CBDDC.Core.Storage.OplogCoordinator": "Warning",
"ZB.MOM.WW.CBDDC.Persistence": "Warning"
}
},
"CBDDC": {
"Network": {
"TcpPort": 5001,
"UdpPort": 6000,
"AuthToken": "demo-secret-key",
"ConnectionTimeoutMs": 5000,
"RetryAttempts": 3,
"RetryDelayMs": 1000,
"LocalhostOnly": false
},
"Persistence": {
"DatabasePath": "data/cbddc.db",
"EnableWalMode": true,
"CacheSizeMb": 50,
"EnableAutoBackup": true,
"BackupPath": "backups/",
"BusyTimeoutMs": 5000
},
"Sync": {
"SyncIntervalMs": 5000,
"BatchSize": 100,
"EnableOfflineQueue": true,
"MaxQueueSize": 1000
},
"Logging": {
"LogLevel": "Information",
"LogFilePath": "logs/cbddc.log",
"MaxLogFileSizeMb": 10,
"MaxLogFiles": 5
},
"KnownPeers": [
{
"NodeId": "AspNetSampleNode",
"Host": "localhost",
"Port": 6001
}
]
}
}

171
src/ZB.MOM.WW.CBDDC.Core/Cache/DocumentCache.cs
View File

@@ -1,76 +1,75 @@
using System;
using System.Collections.Generic;
using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Core.Network;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using System.Threading.Tasks;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.CBDDC.Core.Network;
namespace ZB.MOM.WW.CBDDC.Core.Cache;
/// <summary>
/// LRU cache entry with linked list node.
/// LRU cache entry with linked list node.
/// </summary>
internal class CacheEntry
{
/// <summary>
/// Gets the cached document.
/// </summary>
public Document Document { get; }
/// <summary>
/// Gets the linked-list node used for LRU tracking.
/// </summary>
public LinkedListNode<string> Node { get; }
/// <summary>
/// Initializes a new instance of the <see cref="CacheEntry"/> class.
/// </summary>
/// <param name="document">The cached document.</param>
/// <param name="node">The linked-list node used for LRU tracking.</param>
public CacheEntry(Document document, LinkedListNode<string> node)
{
Document = document;
Node = node;
internal class CacheEntry
{
/// <summary>
/// Initializes a new instance of the <see cref="CacheEntry" /> class.
/// </summary>
/// <param name="document">The cached document.</param>
/// <param name="node">The linked-list node used for LRU tracking.</param>
public CacheEntry(Document document, LinkedListNode<string> node)
{
Document = document;
Node = node;
}
/// <summary>
/// Gets the cached document.
/// </summary>
public Document Document { get; }
/// <summary>
/// Gets the linked-list node used for LRU tracking.
/// </summary>
public LinkedListNode<string> Node { get; }
}
/// <summary>
/// In-memory LRU cache for documents.
/// In-memory LRU cache for documents.
/// </summary>
public class DocumentCache : IDocumentCache
{
private readonly IPeerNodeConfigurationProvider _peerNodeConfigurationProvider;
private readonly Dictionary<string, CacheEntry> _cache = new();
private readonly LinkedList<string> _lru = new();
private readonly ILogger<DocumentCache> _logger;
public class DocumentCache : IDocumentCache
{
private readonly Dictionary<string, CacheEntry> _cache = new();
private readonly object _lock = new();
private readonly ILogger<DocumentCache> _logger;
private readonly LinkedList<string> _lru = new();
private readonly IPeerNodeConfigurationProvider _peerNodeConfigurationProvider;
// Statistics
private long _hits = 0;
private long _misses = 0;
/// <summary>
/// Initializes a new instance of the <see cref="DocumentCache"/> class.
/// </summary>
/// <param name="peerNodeConfigurationProvider">The configuration provider used for cache size limits.</param>
/// <param name="logger">The logger instance.</param>
public DocumentCache(IPeerNodeConfigurationProvider peerNodeConfigurationProvider, ILogger<DocumentCache>? logger = null)
{
_peerNodeConfigurationProvider = peerNodeConfigurationProvider;
_logger = logger ?? NullLogger<DocumentCache>.Instance;
}
// Statistics
private long _hits;
private long _misses;
/// <summary>
/// Gets a document from cache.
/// </summary>
/// <param name="collection">The document collection name.</param>
/// <param name="key">The document key.</param>
/// <returns>A task whose result is the cached document, or <see langword="null"/> if not found.</returns>
public async Task<Document?> Get(string collection, string key)
{
lock (_lock)
{
/// <summary>
/// Initializes a new instance of the <see cref="DocumentCache" /> class.
/// </summary>
/// <param name="peerNodeConfigurationProvider">The configuration provider used for cache size limits.</param>
/// <param name="logger">The logger instance.</param>
public DocumentCache(IPeerNodeConfigurationProvider peerNodeConfigurationProvider,
ILogger<DocumentCache>? logger = null)
{
_peerNodeConfigurationProvider = peerNodeConfigurationProvider;
_logger = logger ?? NullLogger<DocumentCache>.Instance;
}
/// <summary>
/// Gets a document from cache.
/// </summary>
/// <param name="collection">The document collection name.</param>
/// <param name="key">The document key.</param>
/// <returns>A task whose result is the cached document, or <see langword="null" /> if not found.</returns>
public async Task<Document?> Get(string collection, string key)
{
lock (_lock)
{
var cacheKey = $"{collection}:{key}";
if (_cache.TryGetValue(cacheKey, out var entry))
@@ -90,16 +89,16 @@ public class DocumentCache : IDocumentCache
}
}
/// <summary>
/// Sets a document in cache.
/// </summary>
/// <param name="collection">The document collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="document">The document to cache.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task Set(string collection, string key, Document document)
{
var peerConfig = await _peerNodeConfigurationProvider.GetConfiguration();
/// <summary>
/// Sets a document in cache.
/// </summary>
/// <param name="collection">The document collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="document">The document to cache.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task Set(string collection, string key, Document document)
{
var peerConfig = await _peerNodeConfigurationProvider.GetConfiguration();
lock (_lock)
{
@@ -118,7 +117,7 @@ public class DocumentCache : IDocumentCache
// Evict if full
if (_cache.Count >= peerConfig.MaxDocumentCacheSize)
{
var oldest = _lru.Last!.Value;
string oldest = _lru.Last!.Value;
_lru.RemoveLast();
_cache.Remove(oldest);
_logger.LogTrace("Evicted oldest cache entry {Key}", oldest);
@@ -130,15 +129,15 @@ public class DocumentCache : IDocumentCache
}
}
/// <summary>
/// Removes a document from cache.
/// </summary>
/// <param name="collection">The document collection name.</param>
/// <param name="key">The document key.</param>
public void Remove(string collection, string key)
{
lock (_lock)
{
/// <summary>
/// Removes a document from cache.
/// </summary>
/// <param name="collection">The document collection name.</param>
/// <param name="key">The document key.</param>
public void Remove(string collection, string key)
{
lock (_lock)
{
var cacheKey = $"{collection}:{key}";
if (_cache.TryGetValue(cacheKey, out var entry))
@@ -151,13 +150,13 @@ public class DocumentCache : IDocumentCache
}
/// <summary>
/// Clears all cached documents.
/// Clears all cached documents.
/// </summary>
public void Clear()
{
lock (_lock)
{
var count = _cache.Count;
int count = _cache.Count;
_cache.Clear();
_lru.Clear();
_logger.LogInformation("Cleared cache ({Count} entries)", count);
@@ -165,15 +164,15 @@ public class DocumentCache : IDocumentCache
}
/// <summary>
/// Gets cache statistics.
/// Gets cache statistics.
/// </summary>
public (long Hits, long Misses, int Size, double HitRate) GetStatistics()
{
lock (_lock)
{
var total = _hits + _misses;
var hitRate = total > 0 ? (double)_hits / total : 0;
long total = _hits + _misses;
double hitRate = total > 0 ? (double)_hits / total : 0;
return (_hits, _misses, _cache.Count, hitRate);
}
}
}
}

75
src/ZB.MOM.WW.CBDDC.Core/Cache/IDocumentCache.cs
View File

@@ -1,45 +1,44 @@
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Cache
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Cache;
/// <summary>
/// Defines operations for caching documents by collection and key.
/// </summary>
public interface IDocumentCache
{
/// <summary>
/// Defines operations for caching documents by collection and key.
/// Clears all cached documents.
/// </summary>
public interface IDocumentCache
{
/// <summary>
/// Clears all cached documents.
/// </summary>
void Clear();
void Clear();
/// <summary>
/// Gets a cached document by collection and key.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
/// <returns>The cached document, or <see langword="null"/> if not found.</returns>
Task<Document?> Get(string collection, string key);
/// <summary>
/// Gets a cached document by collection and key.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
/// <returns>The cached document, or <see langword="null" /> if not found.</returns>
Task<Document?> Get(string collection, string key);
/// <summary>
/// Gets cache hit/miss statistics.
/// </summary>
/// <returns>A tuple containing hits, misses, current size, and hit rate.</returns>
(long Hits, long Misses, int Size, double HitRate) GetStatistics();
/// <summary>
/// Gets cache hit/miss statistics.
/// </summary>
/// <returns>A tuple containing hits, misses, current size, and hit rate.</returns>
(long Hits, long Misses, int Size, double HitRate) GetStatistics();
/// <summary>
/// Removes a cached document by collection and key.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
void Remove(string collection, string key);
/// <summary>
/// Removes a cached document by collection and key.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
void Remove(string collection, string key);
/// <summary>
/// Adds or updates a cached document.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="document">The document to cache.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Set(string collection, string key, Document document);
}
}
/// <summary>
/// Adds or updates a cached document.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="document">The document to cache.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Set(string collection, string key, Document document);
}

30
src/ZB.MOM.WW.CBDDC.Core/ChangesAppliedEventArgs.cs
View File

@@ -1,24 +1,24 @@
using System;
using System.Collections.Generic;
namespace ZB.MOM.WW.CBDDC.Core;
/// <summary>
/// Event arguments for when changes are applied to the peer store.
/// </summary>
using System;
using System.Collections.Generic;
namespace ZB.MOM.WW.CBDDC.Core;
/// <summary>
/// Event arguments for when changes are applied to the peer store.
/// </summary>
public class ChangesAppliedEventArgs : EventArgs
{
/// <summary>
/// Gets the changes that were applied.
/// </summary>
public IEnumerable<OplogEntry> Changes { get; }
/// <summary>
/// Initializes a new instance of the <see cref="ChangesAppliedEventArgs"/> class.
/// Initializes a new instance of the <see cref="ChangesAppliedEventArgs" /> class.
/// </summary>
/// <param name="changes">The changes that were applied.</param>
public ChangesAppliedEventArgs(IEnumerable<OplogEntry> changes)
{
Changes = changes;
}
}
/// <summary>
/// Gets the changes that were applied.
/// </summary>
public IEnumerable<OplogEntry> Changes { get; }
}

73
src/ZB.MOM.WW.CBDDC.Core/Diagnostics/CBDDCHealthCheck.cs
View File

@@ -1,45 +1,44 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.CBDDC.Core.Storage;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.CBDDC.Core.Storage;
namespace ZB.MOM.WW.CBDDC.Core.Diagnostics;
/// <summary>
/// Provides health check functionality.
/// Provides health check functionality.
/// </summary>
public class CBDDCHealthCheck : ICBDDCHealthCheck
{
private readonly IOplogStore _store;
private readonly ISyncStatusTracker _syncTracker;
private readonly ILogger<CBDDCHealthCheck> _logger;
/// <summary>
/// Initializes a new instance of the <see cref="CBDDCHealthCheck"/> class.
/// </summary>
/// <param name="store">The oplog store used for database health checks.</param>
/// <param name="syncTracker">The tracker that provides synchronization status.</param>
/// <param name="logger">The logger instance.</param>
public CBDDCHealthCheck(
IOplogStore store,
ISyncStatusTracker syncTracker,
ILogger<CBDDCHealthCheck>? logger = null)
{
_store = store ?? throw new ArgumentNullException(nameof(store));
_syncTracker = syncTracker ?? throw new ArgumentNullException(nameof(syncTracker));
_logger = logger ?? NullLogger<CBDDCHealthCheck>.Instance;
}
public class CBDDCHealthCheck : ICBDDCHealthCheck
{
private readonly ILogger<CBDDCHealthCheck> _logger;
private readonly IOplogStore _store;
private readonly ISyncStatusTracker _syncTracker;
/// <summary>
/// Performs a comprehensive health check.
/// </summary>
/// <param name="cancellationToken">A token used to cancel the health check.</param>
public async Task<HealthStatus> CheckAsync(CancellationToken cancellationToken = default)
{
/// <summary>
/// Initializes a new instance of the <see cref="CBDDCHealthCheck" /> class.
/// </summary>
/// <param name="store">The oplog store used for database health checks.</param>
/// <param name="syncTracker">The tracker that provides synchronization status.</param>
/// <param name="logger">The logger instance.</param>
public CBDDCHealthCheck(
IOplogStore store,
ISyncStatusTracker syncTracker,
ILogger<CBDDCHealthCheck>? logger = null)
{
_store = store ?? throw new ArgumentNullException(nameof(store));
_syncTracker = syncTracker ?? throw new ArgumentNullException(nameof(syncTracker));
_logger = logger ?? NullLogger<CBDDCHealthCheck>.Instance;
}
/// <summary>
/// Performs a comprehensive health check.
/// </summary>
/// <param name="cancellationToken">A token used to cancel the health check.</param>
public async Task<HealthStatus> CheckAsync(CancellationToken cancellationToken = default)
{
var status = new HealthStatus();
// Check database health
@@ -65,9 +64,7 @@ public class CBDDCHealthCheck : ICBDDCHealthCheck
// Add error messages from sync tracker
foreach (var error in syncStatus.SyncErrors.Take(5)) // Last 5 errors
{
status.Errors.Add($"{error.Timestamp:yyyy-MM-dd HH:mm:ss} - {error.Message}");
}
// Add metadata
status.Metadata["TotalDocumentsSynced"] = syncStatus.TotalDocumentsSynced;
@@ -79,4 +76,4 @@ public class CBDDCHealthCheck : ICBDDCHealthCheck
return status;
}
}
}

58
src/ZB.MOM.WW.CBDDC.Core/Diagnostics/DiagnosticsModels.cs
View File

@@ -4,145 +4,145 @@ using System.Collections.Generic;
namespace ZB.MOM.WW.CBDDC.Core.Diagnostics;
/// <summary>
/// Represents the health status of an CBDDC instance.
/// Represents the health status of an CBDDC instance.
/// </summary>
public class HealthStatus
{
/// <summary>
/// Indicates if the database is healthy.
/// Indicates if the database is healthy.
/// </summary>
public bool DatabaseHealthy { get; set; }
/// <summary>
/// Indicates if network connectivity is available.
/// Indicates if network connectivity is available.
/// </summary>
public bool NetworkHealthy { get; set; }
/// <summary>
/// Number of currently connected peers.
/// Number of currently connected peers.
/// </summary>
public int ConnectedPeers { get; set; }
/// <summary>
/// Timestamp of the last successful sync operation.
/// Timestamp of the last successful sync operation.
/// </summary>
public DateTime? LastSyncTime { get; set; }
/// <summary>
/// List of recent errors.
/// List of recent errors.
/// </summary>
public List<string> Errors { get; set; } = new();
/// <summary>
/// Overall health status.
/// Overall health status.
/// </summary>
public bool IsHealthy => DatabaseHealthy && NetworkHealthy && Errors.Count == 0;
/// <summary>
/// Additional diagnostic information.
/// Additional diagnostic information.
/// </summary>
public Dictionary<string, object> Metadata { get; set; } = new();
}
/// <summary>
/// Represents the synchronization status.
/// Represents the synchronization status.
/// </summary>
public class SyncStatus
{
/// <summary>
/// Indicates if the node is currently online.
/// Indicates if the node is currently online.
/// </summary>
public bool IsOnline { get; set; }
/// <summary>
/// Timestamp of the last sync operation.
/// Timestamp of the last sync operation.
/// </summary>
public DateTime? LastSyncTime { get; set; }
/// <summary>
/// Number of pending operations in the offline queue.
/// Number of pending operations in the offline queue.
/// </summary>
public int PendingOperations { get; set; }
/// <summary>
/// List of active peer nodes.
/// List of active peer nodes.
/// </summary>
public List<PeerInfo> ActivePeers { get; set; } = new();
/// <summary>
/// Recent sync errors.
/// Recent sync errors.
/// </summary>
public List<SyncError> SyncErrors { get; set; } = new();
/// <summary>
/// Total number of documents synced.
/// Total number of documents synced.
/// </summary>
public long TotalDocumentsSynced { get; set; }
/// <summary>
/// Total bytes transferred.
/// Total bytes transferred.
/// </summary>
public long TotalBytesTransferred { get; set; }
}
/// <summary>
/// Information about a peer node.
/// Information about a peer node.
/// </summary>
public class PeerInfo
{
/// <summary>
/// Unique identifier of the peer.
/// Unique identifier of the peer.
/// </summary>
public string NodeId { get; set; } = "";
/// <summary>
/// Network address of the peer.
/// Network address of the peer.
/// </summary>
public string Address { get; set; } = "";
/// <summary>
/// Last time the peer was seen.
/// Last time the peer was seen.
/// </summary>
public DateTime LastSeen { get; set; }
/// <summary>
/// Indicates if the peer is currently connected.
/// Indicates if the peer is currently connected.
/// </summary>
public bool IsConnected { get; set; }
/// <summary>
/// Number of successful syncs with this peer.
/// Number of successful syncs with this peer.
/// </summary>
public int SuccessfulSyncs { get; set; }
/// <summary>
/// Number of failed syncs with this peer.
/// Number of failed syncs with this peer.
/// </summary>
public int FailedSyncs { get; set; }
}
/// <summary>
/// Represents a synchronization error.
/// Represents a synchronization error.
/// </summary>
public class SyncError
{
/// <summary>
/// Timestamp when the error occurred.
/// Timestamp when the error occurred.
/// </summary>
public DateTime Timestamp { get; set; }
/// <summary>
/// Error message.
/// Error message.
/// </summary>
public string Message { get; set; } = "";
/// <summary>
/// Peer node ID if applicable.
/// Peer node ID if applicable.
/// </summary>
public string? PeerNodeId { get; set; }
/// <summary>
/// Error code.
/// Error code.
/// </summary>
public string? ErrorCode { get; set; }
}
}

27
src/ZB.MOM.WW.CBDDC.Core/Diagnostics/ICBDDCHealthCheck.cs
View File

@@ -1,15 +1,14 @@
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Diagnostics
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Diagnostics;
public interface ICBDDCHealthCheck
{
public interface ICBDDCHealthCheck
{
/// <summary>
/// Performs a health check for the implementing component.
/// </summary>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>The resulting health status.</returns>
Task<HealthStatus> CheckAsync(CancellationToken cancellationToken = default);
}
}
/// <summary>
/// Performs a health check for the implementing component.
/// </summary>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>The resulting health status.</returns>
Task<HealthStatus> CheckAsync(CancellationToken cancellationToken = default);
}

105
src/ZB.MOM.WW.CBDDC.Core/Diagnostics/ISyncStatusTracker.cs
View File

@@ -1,63 +1,62 @@
using System;
namespace ZB.MOM.WW.CBDDC.Core.Diagnostics
using System;
namespace ZB.MOM.WW.CBDDC.Core.Diagnostics;
/// <summary>
/// Tracks synchronization status and peer health metrics.
/// </summary>
public interface ISyncStatusTracker
{
/// <summary>
/// Tracks synchronization status and peer health metrics.
/// Removes peer entries that have been inactive longer than the specified threshold.
/// </summary>
public interface ISyncStatusTracker
{
/// <summary>
/// Removes peer entries that have been inactive longer than the specified threshold.
/// </summary>
/// <param name="inactiveThreshold">The inactivity threshold used to prune peers.</param>
void CleanupInactivePeers(TimeSpan inactiveThreshold);
/// <param name="inactiveThreshold">The inactivity threshold used to prune peers.</param>
void CleanupInactivePeers(TimeSpan inactiveThreshold);
/// <summary>
/// Gets the current synchronization status snapshot.
/// </summary>
/// <returns>The current <see cref="SyncStatus"/>.</returns>
SyncStatus GetStatus();
/// <summary>
/// Gets the current synchronization status snapshot.
/// </summary>
/// <returns>The current <see cref="SyncStatus" />.</returns>
SyncStatus GetStatus();
/// <summary>
/// Records an error encountered during synchronization.
/// </summary>
/// <param name="message">The error message.</param>
/// <param name="peerNodeId">The related peer node identifier, if available.</param>
/// <param name="errorCode">An optional error code.</param>
void RecordError(string message, string? peerNodeId = null, string? errorCode = null);
/// <summary>
/// Records an error encountered during synchronization.
/// </summary>
/// <param name="message">The error message.</param>
/// <param name="peerNodeId">The related peer node identifier, if available.</param>
/// <param name="errorCode">An optional error code.</param>
void RecordError(string message, string? peerNodeId = null, string? errorCode = null);
/// <summary>
/// Records a failed operation for the specified peer.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
void RecordPeerFailure(string nodeId);
/// <summary>
/// Records a failed operation for the specified peer.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
void RecordPeerFailure(string nodeId);
/// <summary>
/// Records a successful operation for the specified peer.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
void RecordPeerSuccess(string nodeId);
/// <summary>
/// Records a successful operation for the specified peer.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
void RecordPeerSuccess(string nodeId);
/// <summary>
/// Records synchronization throughput metrics.
/// </summary>
/// <param name="documentCount">The number of synchronized documents.</param>
/// <param name="bytesTransferred">The number of bytes transferred.</param>
void RecordSync(int documentCount, long bytesTransferred);
/// <summary>
/// Records synchronization throughput metrics.
/// </summary>
/// <param name="documentCount">The number of synchronized documents.</param>
/// <param name="bytesTransferred">The number of bytes transferred.</param>
void RecordSync(int documentCount, long bytesTransferred);
/// <summary>
/// Sets whether the local node is currently online.
/// </summary>
/// <param name="isOnline">A value indicating whether the node is online.</param>
void SetOnlineStatus(bool isOnline);
/// <summary>
/// Sets whether the local node is currently online.
/// </summary>
/// <param name="isOnline">A value indicating whether the node is online.</param>
void SetOnlineStatus(bool isOnline);
/// <summary>
/// Updates peer connectivity details.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
/// <param name="address">The peer network address.</param>
/// <param name="isConnected">A value indicating whether the peer is connected.</param>
void UpdatePeer(string nodeId, string address, bool isConnected);
}
}
/// <summary>
/// Updates peer connectivity details.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
/// <param name="address">The peer network address.</param>
/// <param name="isConnected">A value indicating whether the peer is connected.</param>
void UpdatePeer(string nodeId, string address, bool isConnected);
}

208
src/ZB.MOM.WW.CBDDC.Core/Diagnostics/SyncStatusTracker.cs
View File

@@ -1,44 +1,44 @@
using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
namespace ZB.MOM.WW.CBDDC.Core.Diagnostics;
/// <summary>
/// Tracks synchronization status and provides diagnostics.
/// Tracks synchronization status and provides diagnostics.
/// </summary>
public class SyncStatusTracker : ISyncStatusTracker
{
private readonly ILogger<SyncStatusTracker> _logger;
private readonly object _lock = new();
private bool _isOnline = false;
private DateTime? _lastSyncTime;
public class SyncStatusTracker : ISyncStatusTracker
{
private const int MaxErrorHistory = 50;
private readonly List<PeerInfo> _activePeers = new();
private readonly object _lock = new();
private readonly ILogger<SyncStatusTracker> _logger;
private readonly Queue<SyncError> _recentErrors = new();
private long _totalDocumentsSynced = 0;
private long _totalBytesTransferred = 0;
private const int MaxErrorHistory = 50;
/// <summary>
/// Initializes a new instance of the <see cref="SyncStatusTracker"/> class.
/// </summary>
/// <param name="logger">Optional logger instance.</param>
public SyncStatusTracker(ILogger<SyncStatusTracker>? logger = null)
{
_logger = logger ?? NullLogger<SyncStatusTracker>.Instance;
}
/// <summary>
/// Updates online status.
/// </summary>
/// <param name="isOnline">Whether the node is currently online.</param>
public void SetOnlineStatus(bool isOnline)
{
lock (_lock)
{
private bool _isOnline;
private DateTime? _lastSyncTime;
private long _totalBytesTransferred;
private long _totalDocumentsSynced;
/// <summary>
/// Initializes a new instance of the <see cref="SyncStatusTracker" /> class.
/// </summary>
/// <param name="logger">Optional logger instance.</param>
public SyncStatusTracker(ILogger<SyncStatusTracker>? logger = null)
{
_logger = logger ?? NullLogger<SyncStatusTracker>.Instance;
}
/// <summary>
/// Updates online status.
/// </summary>
/// <param name="isOnline">Whether the node is currently online.</param>
public void SetOnlineStatus(bool isOnline)
{
lock (_lock)
{
if (_isOnline != isOnline)
{
_isOnline = isOnline;
@@ -47,15 +47,15 @@ public class SyncStatusTracker : ISyncStatusTracker
}
}
/// <summary>
/// Records a successful sync operation.
/// </summary>
/// <param name="documentCount">The number of documents synchronized.</param>
/// <param name="bytesTransferred">The number of bytes transferred.</param>
public void RecordSync(int documentCount, long bytesTransferred)
{
lock (_lock)
{
/// <summary>
/// Records a successful sync operation.
/// </summary>
/// <param name="documentCount">The number of documents synchronized.</param>
/// <param name="bytesTransferred">The number of bytes transferred.</param>
public void RecordSync(int documentCount, long bytesTransferred)
{
lock (_lock)
{
_lastSyncTime = DateTime.UtcNow;
_totalDocumentsSynced += documentCount;
_totalBytesTransferred += bytesTransferred;
@@ -64,16 +64,16 @@ public class SyncStatusTracker : ISyncStatusTracker
}
}
/// <summary>
/// Records a sync error.
/// </summary>
/// <param name="message">The error message.</param>
/// <param name="peerNodeId">The related peer node identifier, if available.</param>
/// <param name="errorCode">The error code, if available.</param>
public void RecordError(string message, string? peerNodeId = null, string? errorCode = null)
{
lock (_lock)
{
/// <summary>
/// Records a sync error.
/// </summary>
/// <param name="message">The error message.</param>
/// <param name="peerNodeId">The related peer node identifier, if available.</param>
/// <param name="errorCode">The error code, if available.</param>
public void RecordError(string message, string? peerNodeId = null, string? errorCode = null)
{
lock (_lock)
{
var error = new SyncError
{
Timestamp = DateTime.UtcNow,
@@ -84,25 +84,22 @@ public class SyncStatusTracker : ISyncStatusTracker
_recentErrors.Enqueue(error);
while (_recentErrors.Count > MaxErrorHistory)
{
_recentErrors.Dequeue();
}
while (_recentErrors.Count > MaxErrorHistory) _recentErrors.Dequeue();
_logger.LogWarning("Sync error recorded: {Message} (Peer: {Peer})", message, peerNodeId ?? "N/A");
}
}
/// <summary>
/// Updates peer information.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
/// <param name="address">The peer address.</param>
/// <param name="isConnected">Whether the peer is currently connected.</param>
public void UpdatePeer(string nodeId, string address, bool isConnected)
{
lock (_lock)
{
/// <summary>
/// Updates peer information.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
/// <param name="address">The peer address.</param>
/// <param name="isConnected">Whether the peer is currently connected.</param>
public void UpdatePeer(string nodeId, string address, bool isConnected)
{
lock (_lock)
{
var peer = _activePeers.FirstOrDefault(p => p.NodeId == nodeId);
if (peer == null)
@@ -126,40 +123,34 @@ public class SyncStatusTracker : ISyncStatusTracker
}
}
/// <summary>
/// Records successful sync with a peer.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
public void RecordPeerSuccess(string nodeId)
{
lock (_lock)
{
/// <summary>
/// Records successful sync with a peer.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
public void RecordPeerSuccess(string nodeId)
{
lock (_lock)
{
var peer = _activePeers.FirstOrDefault(p => p.NodeId == nodeId);
if (peer != null)
{
peer.SuccessfulSyncs++;
}
}
}
/// <summary>
/// Records failed sync with a peer.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
public void RecordPeerFailure(string nodeId)
{
lock (_lock)
{
var peer = _activePeers.FirstOrDefault(p => p.NodeId == nodeId);
if (peer != null)
{
peer.FailedSyncs++;
}
if (peer != null) peer.SuccessfulSyncs++;
}
}
/// <summary>
/// Gets current sync status.
/// Records failed sync with a peer.
/// </summary>
/// <param name="nodeId">The peer node identifier.</param>
public void RecordPeerFailure(string nodeId)
{
lock (_lock)
{
var peer = _activePeers.FirstOrDefault(p => p.NodeId == nodeId);
if (peer != null) peer.FailedSyncs++;
}
}
/// <summary>
/// Gets current sync status.
/// </summary>
public SyncStatus GetStatus()
{
@@ -178,21 +169,18 @@ public class SyncStatusTracker : ISyncStatusTracker
}
}
/// <summary>
/// Cleans up inactive peers.
/// </summary>
/// <param name="inactiveThreshold">The inactivity threshold used to remove peers.</param>
public void CleanupInactivePeers(TimeSpan inactiveThreshold)
{
lock (_lock)
{
/// <summary>
/// Cleans up inactive peers.
/// </summary>
/// <param name="inactiveThreshold">The inactivity threshold used to remove peers.</param>
public void CleanupInactivePeers(TimeSpan inactiveThreshold)
{
lock (_lock)
{
var cutoff = DateTime.UtcNow - inactiveThreshold;
var removed = _activePeers.RemoveAll(p => p.LastSeen < cutoff);
int removed = _activePeers.RemoveAll(p => p.LastSeen < cutoff);
if (removed > 0)
{
_logger.LogInformation("Removed {Count} inactive peers", removed);
}
if (removed > 0) _logger.LogInformation("Removed {Count} inactive peers", removed);
}
}
}
}

109
src/ZB.MOM.WW.CBDDC.Core/Document.cs
View File

@@ -1,41 +1,15 @@
using ZB.MOM.WW.CBDDC.Core.Sync;
using System;
using System.Text.Json;
using System.Text.Json;
using ZB.MOM.WW.CBDDC.Core.Sync;
namespace ZB.MOM.WW.CBDDC.Core;
/// <summary>
/// Represents a stored document and its synchronization metadata.
/// Represents a stored document and its synchronization metadata.
/// </summary>
public class Document
{
/// <summary>
/// Gets the collection that contains the document.
/// </summary>
public string Collection { get; private set; }
/// <summary>
/// Gets the document key.
/// </summary>
public string Key { get; private set; }
/// <summary>
/// Gets the document content.
/// </summary>
public JsonElement Content { get; private set; }
/// <summary>
/// Gets the timestamp of the latest applied update.
/// </summary>
public HlcTimestamp UpdatedAt { get; private set; }
/// <summary>
/// Gets a value indicating whether the document is deleted.
/// </summary>
public bool IsDeleted { get; private set; }
/// <summary>
/// Initializes a new instance of the <see cref="Document"/> class.
/// Initializes a new instance of the <see cref="Document" /> class.
/// </summary>
/// <param name="collection">The collection that contains the document.</param>
/// <param name="key">The document key.</param>
@@ -52,32 +26,59 @@ public class Document
}
/// <summary>
/// Merges a remote operation into the current document using last-write-wins or a conflict resolver.
/// Gets the collection that contains the document.
/// </summary>
public string Collection { get; }
/// <summary>
/// Gets the document key.
/// </summary>
public string Key { get; }
/// <summary>
/// Gets the document content.
/// </summary>
public JsonElement Content { get; private set; }
/// <summary>
/// Gets the timestamp of the latest applied update.
/// </summary>
public HlcTimestamp UpdatedAt { get; private set; }
/// <summary>
/// Gets a value indicating whether the document is deleted.
/// </summary>
public bool IsDeleted { get; private set; }
/// <summary>
/// Merges a remote operation into the current document using last-write-wins or a conflict resolver.
/// </summary>
/// <param name="oplogEntry">The remote operation to merge.</param>
/// <param name="resolver">An optional conflict resolver for custom merge behavior.</param>
public void Merge(OplogEntry oplogEntry, IConflictResolver? resolver = null)
{
if (oplogEntry == null) return;
if (Collection != oplogEntry.Collection) return;
if (Key != oplogEntry.Key) return;
if (resolver == null)
{
//last wins
if (UpdatedAt <= oplogEntry.Timestamp)
{
Content = oplogEntry.Payload ?? default;
UpdatedAt = oplogEntry.Timestamp;
IsDeleted = oplogEntry.Operation == OperationType.Delete;
}
return;
}
var resolutionResult = resolver.Resolve(this, oplogEntry);
if (resolutionResult.ShouldApply && resolutionResult.MergedDocument != null)
{
Content = resolutionResult.MergedDocument.Content;
UpdatedAt = resolutionResult.MergedDocument.UpdatedAt;
IsDeleted = resolutionResult.MergedDocument.IsDeleted;
}
}
}
if (Collection != oplogEntry.Collection) return;
if (Key != oplogEntry.Key) return;
if (resolver == null)
{
//last wins
if (UpdatedAt <= oplogEntry.Timestamp)
{
Content = oplogEntry.Payload ?? default;
UpdatedAt = oplogEntry.Timestamp;
IsDeleted = oplogEntry.Operation == OperationType.Delete;
}
return;
}
var resolutionResult = resolver.Resolve(this, oplogEntry);
if (resolutionResult.ShouldApply && resolutionResult.MergedDocument != null)
{
Content = resolutionResult.MergedDocument.Content;
UpdatedAt = resolutionResult.MergedDocument.UpdatedAt;
IsDeleted = resolutionResult.MergedDocument.IsDeleted;
}
}
}

175
src/ZB.MOM.WW.CBDDC.Core/Exceptions/CBDDCExceptions.cs
View File

@@ -1,19 +1,14 @@
using System;
namespace ZB.MOM.WW.CBDDC.Core.Exceptions;
/// <summary>
/// Base exception for all CBDDC-related errors.
/// </summary>
public class CBDDCException : Exception
{
/// <summary>
/// Error code for programmatic error handling.
/// </summary>
public string ErrorCode { get; }
using System;
namespace ZB.MOM.WW.CBDDC.Core.Exceptions;
/// <summary>
/// Base exception for all CBDDC-related errors.
/// </summary>
public class CBDDCException : Exception
{
/// <summary>
/// Initializes a new instance of the <see cref="CBDDCException"/> class.
/// Initializes a new instance of the <see cref="CBDDCException" /> class.
/// </summary>
/// <param name="errorCode">The application-specific error code.</param>
/// <param name="message">The exception message.</param>
@@ -24,7 +19,7 @@ public class CBDDCException : Exception
}
/// <summary>
/// Initializes a new instance of the <see cref="CBDDCException"/> class.
/// Initializes a new instance of the <see cref="CBDDCException" /> class.
/// </summary>
/// <param name="errorCode">The application-specific error code.</param>
/// <param name="message">The exception message.</param>
@@ -34,137 +29,151 @@ public class CBDDCException : Exception
{
ErrorCode = errorCode;
}
}
/// <summary>
/// Exception thrown when network operations fail.
/// </summary>
/// <summary>
/// Error code for programmatic error handling.
/// </summary>
public string ErrorCode { get; }
}
/// <summary>
/// Exception thrown when network operations fail.
/// </summary>
public class NetworkException : CBDDCException
{
/// <summary>
/// Initializes a new instance of the <see cref="NetworkException"/> class.
/// Initializes a new instance of the <see cref="NetworkException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
public NetworkException(string message)
: base("NETWORK_ERROR", message) { }
: base("NETWORK_ERROR", message)
{
}
/// <summary>
/// Initializes a new instance of the <see cref="NetworkException"/> class.
/// Initializes a new instance of the <see cref="NetworkException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
/// <param name="innerException">The exception that caused the current exception.</param>
public NetworkException(string message, Exception innerException)
: base("NETWORK_ERROR", message, innerException) { }
: base("NETWORK_ERROR", message, innerException)
{
}
}
/// <summary>
/// Exception thrown when persistence operations fail.
/// </summary>
/// <summary>
/// Exception thrown when persistence operations fail.
/// </summary>
public class PersistenceException : CBDDCException
{
/// <summary>
/// Initializes a new instance of the <see cref="PersistenceException"/> class.
/// Initializes a new instance of the <see cref="PersistenceException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
public PersistenceException(string message)
: base("PERSISTENCE_ERROR", message) { }
: base("PERSISTENCE_ERROR", message)
{
}
/// <summary>
/// Initializes a new instance of the <see cref="PersistenceException"/> class.
/// Initializes a new instance of the <see cref="PersistenceException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
/// <param name="innerException">The exception that caused the current exception.</param>
public PersistenceException(string message, Exception innerException)
: base("PERSISTENCE_ERROR", message, innerException) { }
: base("PERSISTENCE_ERROR", message, innerException)
{
}
}
/// <summary>
/// Exception thrown when synchronization operations fail.
/// </summary>
/// <summary>
/// Exception thrown when synchronization operations fail.
/// </summary>
public class SyncException : CBDDCException
{
/// <summary>
/// Initializes a new instance of the <see cref="SyncException"/> class.
/// Initializes a new instance of the <see cref="SyncException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
public SyncException(string message)
: base("SYNC_ERROR", message) { }
: base("SYNC_ERROR", message)
{
}
/// <summary>
/// Initializes a new instance of the <see cref="SyncException"/> class.
/// Initializes a new instance of the <see cref="SyncException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
/// <param name="innerException">The exception that caused the current exception.</param>
public SyncException(string message, Exception innerException)
: base("SYNC_ERROR", message, innerException) { }
: base("SYNC_ERROR", message, innerException)
{
}
}
/// <summary>
/// Exception thrown when configuration is invalid.
/// </summary>
/// <summary>
/// Exception thrown when configuration is invalid.
/// </summary>
public class ConfigurationException : CBDDCException
{
/// <summary>
/// Initializes a new instance of the <see cref="ConfigurationException"/> class.
/// Initializes a new instance of the <see cref="ConfigurationException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
public ConfigurationException(string message)
: base("CONFIG_ERROR", message) { }
: base("CONFIG_ERROR", message)
{
}
}
/// <summary>
/// Exception thrown when database corruption is detected.
/// </summary>
/// <summary>
/// Exception thrown when database corruption is detected.
/// </summary>
public class DatabaseCorruptionException : PersistenceException
{
/// <summary>
/// Initializes a new instance of the <see cref="DatabaseCorruptionException"/> class.
/// Initializes a new instance of the <see cref="DatabaseCorruptionException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
public DatabaseCorruptionException(string message)
: base(message) { }
: base(message)
{
}
/// <summary>
/// Initializes a new instance of the <see cref="DatabaseCorruptionException"/> class.
/// Initializes a new instance of the <see cref="DatabaseCorruptionException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
/// <param name="innerException">The exception that caused the current exception.</param>
public DatabaseCorruptionException(string message, Exception innerException)
: base(message, innerException) { }
: base(message, innerException)
{
}
}
/// <summary>
/// Exception thrown when a timeout occurs.
/// </summary>
/// <summary>
/// Exception thrown when a timeout occurs.
/// </summary>
public class TimeoutException : CBDDCException
{
/// <summary>
/// Initializes a new instance of the <see cref="TimeoutException"/> class.
/// Initializes a new instance of the <see cref="TimeoutException" /> class.
/// </summary>
/// <param name="operation">The operation that timed out.</param>
/// <param name="timeoutMs">The timeout in milliseconds.</param>
public TimeoutException(string operation, int timeoutMs)
: base("TIMEOUT_ERROR", $"Operation '{operation}' timed out after {timeoutMs}ms") { }
: base("TIMEOUT_ERROR", $"Operation '{operation}' timed out after {timeoutMs}ms")
{
}
}
/// <summary>
/// Exception thrown when a document is not found in a collection.
/// Exception thrown when a document is not found in a collection.
/// </summary>
public class DocumentNotFoundException : PersistenceException
{
/// <summary>
/// Gets the document key that was not found.
/// </summary>
public string Key { get; }
/// <summary>
/// Gets the collection where the document was searched.
/// </summary>
public string Collection { get; }
/// <summary>
/// Initializes a new instance of the <see cref="DocumentNotFoundException"/> class.
/// Initializes a new instance of the <see cref="DocumentNotFoundException" /> class.
/// </summary>
/// <param name="collection">The collection where the document was searched.</param>
/// <param name="key">The document key that was not found.</param>
@@ -174,16 +183,28 @@ public class DocumentNotFoundException : PersistenceException
Collection = collection;
Key = key;
}
/// <summary>
/// Gets the document key that was not found.
/// </summary>
public string Key { get; }
/// <summary>
/// Gets the collection where the document was searched.
/// </summary>
public string Collection { get; }
}
/// <summary>
/// Exception thrown when a concurrency conflict occurs during persistence operations.
/// Exception thrown when a concurrency conflict occurs during persistence operations.
/// </summary>
public class CBDDCConcurrencyException : PersistenceException
{
/// <summary>
/// Initializes a new instance of the <see cref="CBDDCConcurrencyException"/> class.
/// Initializes a new instance of the <see cref="CBDDCConcurrencyException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
public CBDDCConcurrencyException(string message) : base(message) { }
}
public CBDDCConcurrencyException(string message) : base(message)
{
}
}

142
src/ZB.MOM.WW.CBDDC.Core/HlcTimestamp.cs
View File

@@ -1,31 +1,31 @@
using System;
namespace ZB.MOM.WW.CBDDC.Core;
/// <summary>
/// Represents a Hybrid Logical Clock timestamp.
/// Provides a Total Ordering of events in a distributed system.
/// Implements value semantics and comparable interfaces.
/// </summary>
using System;
namespace ZB.MOM.WW.CBDDC.Core;
/// <summary>
/// Represents a Hybrid Logical Clock timestamp.
/// Provides a Total Ordering of events in a distributed system.
/// Implements value semantics and comparable interfaces.
/// </summary>
public readonly struct HlcTimestamp : IComparable<HlcTimestamp>, IComparable, IEquatable<HlcTimestamp>
{
/// <summary>
/// Gets the physical time component of the timestamp.
/// Gets the physical time component of the timestamp.
/// </summary>
public long PhysicalTime { get; }
/// <summary>
/// Gets the logical counter component used to order events with equal physical time.
/// Gets the logical counter component used to order events with equal physical time.
/// </summary>
public int LogicalCounter { get; }
/// <summary>
/// Gets the node identifier that produced this timestamp.
/// Gets the node identifier that produced this timestamp.
/// </summary>
public string NodeId { get; }
/// <summary>
/// Initializes a new instance of the <see cref="HlcTimestamp"/> struct.
/// Initializes a new instance of the <see cref="HlcTimestamp" /> struct.
/// </summary>
/// <param name="physicalTime">The physical time component.</param>
/// <param name="logicalCounter">The logical counter component.</param>
@@ -35,36 +35,36 @@ public readonly struct HlcTimestamp : IComparable<HlcTimestamp>, IComparable, IE
PhysicalTime = physicalTime;
LogicalCounter = logicalCounter;
NodeId = nodeId ?? throw new ArgumentNullException(nameof(nodeId));
}
}
/// <summary>
/// Compares two timestamps to establish a total order.
/// Order: PhysicalTime -> LogicalCounter -> NodeId (lexicographical tie-breaker).
/// Compares two timestamps to establish a total order.
/// Order: PhysicalTime -> LogicalCounter -> NodeId (lexicographical tie-breaker).
/// </summary>
/// <param name="other">The other timestamp to compare with this instance.</param>
/// <returns>
/// A value less than zero if this instance is earlier than <paramref name="other"/>, zero if they are equal,
/// or greater than zero if this instance is later than <paramref name="other"/>.
/// A value less than zero if this instance is earlier than <paramref name="other" />, zero if they are equal,
/// or greater than zero if this instance is later than <paramref name="other" />.
/// </returns>
public int CompareTo(HlcTimestamp other)
{
int timeComparison = PhysicalTime.CompareTo(other.PhysicalTime);
if (timeComparison != 0) return timeComparison;
int counterComparison = LogicalCounter.CompareTo(other.LogicalCounter);
if (counterComparison != 0) return counterComparison;
int counterComparison = LogicalCounter.CompareTo(other.LogicalCounter);
if (counterComparison != 0) return counterComparison;
// Use Ordinal comparison for consistent tie-breaking across cultures/platforms
return string.Compare(NodeId, other.NodeId, StringComparison.Ordinal);
}
/// <summary>
/// Compares this instance with another object.
/// Compares this instance with another object.
/// </summary>
/// <param name="obj">The object to compare with this instance.</param>
/// <returns>
/// A value less than zero if this instance is earlier than <paramref name="obj"/>, zero if equal, or greater
/// than zero if later.
/// A value less than zero if this instance is earlier than <paramref name="obj" />, zero if equal, or greater
/// than zero if later.
/// </returns>
public int CompareTo(object? obj)
{
@@ -74,10 +74,10 @@ public readonly struct HlcTimestamp : IComparable<HlcTimestamp>, IComparable, IE
}
/// <summary>
/// Determines whether this instance and another timestamp are equal.
/// Determines whether this instance and another timestamp are equal.
/// </summary>
/// <param name="other">The other timestamp to compare.</param>
/// <returns><see langword="true"/> if the timestamps are equal; otherwise, <see langword="false"/>.</returns>
/// <returns><see langword="true" /> if the timestamps are equal; otherwise, <see langword="false" />.</returns>
public bool Equals(HlcTimestamp other)
{
return PhysicalTime == other.PhysicalTime &&
@@ -96,42 +96,68 @@ public readonly struct HlcTimestamp : IComparable<HlcTimestamp>, IComparable, IE
{
unchecked
{
var hashCode = PhysicalTime.GetHashCode();
hashCode = (hashCode * 397) ^ LogicalCounter;
// Ensure HashCode uses the same comparison logic as Equals/CompareTo
// Handle null NodeId gracefully (possible via default(HlcTimestamp))
hashCode = (hashCode * 397) ^ (NodeId != null ? StringComparer.Ordinal.GetHashCode(NodeId) : 0);
return hashCode;
}
}
public static bool operator ==(HlcTimestamp left, HlcTimestamp right) => left.Equals(right);
public static bool operator !=(HlcTimestamp left, HlcTimestamp right) => !left.Equals(right);
// Standard comparison operators making usage in SyncOrchestrator cleaner (e.g., remote > local)
public static bool operator <(HlcTimestamp left, HlcTimestamp right) => left.CompareTo(right) < 0;
public static bool operator <=(HlcTimestamp left, HlcTimestamp right) => left.CompareTo(right) <= 0;
public static bool operator >(HlcTimestamp left, HlcTimestamp right) => left.CompareTo(right) > 0;
public static bool operator >=(HlcTimestamp left, HlcTimestamp right) => left.CompareTo(right) >= 0;
int hashCode = PhysicalTime.GetHashCode();
hashCode = (hashCode * 397) ^ LogicalCounter;
// Ensure HashCode uses the same comparison logic as Equals/CompareTo
// Handle null NodeId gracefully (possible via default(HlcTimestamp))
hashCode = (hashCode * 397) ^ (NodeId != null ? StringComparer.Ordinal.GetHashCode(NodeId) : 0);
return hashCode;
}
}
public static bool operator ==(HlcTimestamp left, HlcTimestamp right)
{
return left.Equals(right);
}
public static bool operator !=(HlcTimestamp left, HlcTimestamp right)
{
return !left.Equals(right);
}
// Standard comparison operators making usage in SyncOrchestrator cleaner (e.g., remote > local)
public static bool operator <(HlcTimestamp left, HlcTimestamp right)
{
return left.CompareTo(right) < 0;
}
public static bool operator <=(HlcTimestamp left, HlcTimestamp right)
{
return left.CompareTo(right) <= 0;
}
public static bool operator >(HlcTimestamp left, HlcTimestamp right)
{
return left.CompareTo(right) > 0;
}
public static bool operator >=(HlcTimestamp left, HlcTimestamp right)
{
return left.CompareTo(right) >= 0;
}
/// <inheritdoc />
public override string ToString() => FormattableString.Invariant($"{PhysicalTime}:{LogicalCounter}:{NodeId}");
public override string ToString()
{
return FormattableString.Invariant($"{PhysicalTime}:{LogicalCounter}:{NodeId}");
}
/// <summary>
/// Parses a timestamp string.
/// Parses a timestamp string.
/// </summary>
/// <param name="s">The string to parse, in the format "PhysicalTime:LogicalCounter:NodeId".</param>
/// <returns>The parsed <see cref="HlcTimestamp"/>.</returns>
/// <returns>The parsed <see cref="HlcTimestamp" />.</returns>
public static HlcTimestamp Parse(string s)
{
if (string.IsNullOrEmpty(s)) throw new ArgumentNullException(nameof(s));
var parts = s.Split(':');
if (parts.Length != 3) throw new FormatException("Invalid HlcTimestamp format. Expected 'PhysicalTime:LogicalCounter:NodeId'.");
if (!long.TryParse(parts[0], out var physicalTime))
throw new FormatException("Invalid PhysicalTime component in HlcTimestamp.");
if (!int.TryParse(parts[1], out var logicalCounter))
throw new FormatException("Invalid LogicalCounter component in HlcTimestamp.");
var nodeId = parts[2];
return new HlcTimestamp(physicalTime, logicalCounter, nodeId);
}
}
string[] parts = s.Split(':');
if (parts.Length != 3)
throw new FormatException("Invalid HlcTimestamp format. Expected 'PhysicalTime:LogicalCounter:NodeId'.");
if (!long.TryParse(parts[0], out long physicalTime))
throw new FormatException("Invalid PhysicalTime component in HlcTimestamp.");
if (!int.TryParse(parts[1], out int logicalCounter))
throw new FormatException("Invalid LogicalCounter component in HlcTimestamp.");
string nodeId = parts[2];
return new HlcTimestamp(physicalTime, logicalCounter, nodeId);
}
}

18
src/ZB.MOM.WW.CBDDC.Core/Management/IPeerManagementService.cs
View File

@@ -6,13 +6,13 @@ using ZB.MOM.WW.CBDDC.Core.Network;
namespace ZB.MOM.WW.CBDDC.Core.Management;
/// <summary>
/// Service for managing remote peer configurations.
/// Provides CRUD operations for adding, removing, enabling/disabling remote cloud nodes.
/// Service for managing remote peer configurations.
/// Provides CRUD operations for adding, removing, enabling/disabling remote cloud nodes.
/// </summary>
public interface IPeerManagementService
{
/// <summary>
/// Adds a static remote peer with simple authentication.
/// Adds a static remote peer with simple authentication.
/// </summary>
/// <param name="nodeId">Unique identifier for the remote peer.</param>
/// <param name="address">Network address (hostname:port) of the remote peer.</param>
@@ -20,14 +20,14 @@ public interface IPeerManagementService
Task AddStaticPeerAsync(string nodeId, string address, CancellationToken cancellationToken = default);
/// <summary>
/// Removes a remote peer configuration.
/// Removes a remote peer configuration.
/// </summary>
/// <param name="nodeId">Unique identifier of the peer to remove.</param>
/// <param name="cancellationToken">Cancellation token.</param>
Task RemoveRemotePeerAsync(string nodeId, CancellationToken cancellationToken = default);
/// <summary>
/// Removes confirmation tracking for a peer and optionally removes static remote configuration.
/// Removes confirmation tracking for a peer and optionally removes static remote configuration.
/// </summary>
/// <param name="nodeId">Unique identifier of the peer to untrack.</param>
/// <param name="removeRemoteConfig">When true, also removes static remote peer configuration.</param>
@@ -38,23 +38,23 @@ public interface IPeerManagementService
CancellationToken cancellationToken = default);
/// <summary>
/// Retrieves all configured remote peers.
/// Retrieves all configured remote peers.
/// </summary>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>Collection of remote peer configurations.</returns>
Task<IEnumerable<RemotePeerConfiguration>> GetAllRemotePeersAsync(CancellationToken cancellationToken = default);
/// <summary>
/// Enables synchronization with a remote peer.
/// Enables synchronization with a remote peer.
/// </summary>
/// <param name="nodeId">Unique identifier of the peer to enable.</param>
/// <param name="cancellationToken">Cancellation token.</param>
Task EnablePeerAsync(string nodeId, CancellationToken cancellationToken = default);
/// <summary>
/// Disables synchronization with a remote peer (keeps configuration).
/// Disables synchronization with a remote peer (keeps configuration).
/// </summary>
/// <param name="nodeId">Unique identifier of the peer to disable.</param>
/// <param name="cancellationToken">Cancellation token.</param>
Task DisablePeerAsync(string nodeId, CancellationToken cancellationToken = default);
}
}

66
src/ZB.MOM.WW.CBDDC.Core/Management/PeerManagementService.cs
View File

@@ -2,29 +2,28 @@ using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core.Storage;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core.Storage;
namespace ZB.MOM.WW.CBDDC.Core.Management;
/// <summary>
/// Implementation of peer management service.
/// Provides CRUD operations for managing remote peer configurations.
///
/// Remote peer configurations are stored in a synchronized collection and automatically
/// replicated across all nodes in the cluster. Any change made on one node will be
/// synchronized to all other nodes through the normal CBDDC sync process.
/// Implementation of peer management service.
/// Provides CRUD operations for managing remote peer configurations.
/// Remote peer configurations are stored in a synchronized collection and automatically
/// replicated across all nodes in the cluster. Any change made on one node will be
/// synchronized to all other nodes through the normal CBDDC sync process.
/// </summary>
public class PeerManagementService : IPeerManagementService
{
private readonly IPeerConfigurationStore _store;
private readonly IPeerOplogConfirmationStore _peerOplogConfirmationStore;
private readonly ILogger<PeerManagementService> _logger;
private readonly IPeerOplogConfirmationStore _peerOplogConfirmationStore;
private readonly IPeerConfigurationStore _store;
/// <summary>
/// Initializes a new instance of the PeerManagementService class.
/// Initializes a new instance of the PeerManagementService class.
/// </summary>
/// <param name="store">Database instance for accessing the synchronized collection.</param>
/// <param name="peerOplogConfirmationStore">Peer confirmation tracking store.</param>
@@ -35,12 +34,13 @@ public class PeerManagementService : IPeerManagementService
ILogger<PeerManagementService>? logger = null)
{
_store = store ?? throw new ArgumentNullException(nameof(store));
_peerOplogConfirmationStore = peerOplogConfirmationStore ?? throw new ArgumentNullException(nameof(peerOplogConfirmationStore));
_peerOplogConfirmationStore = peerOplogConfirmationStore ??
throw new ArgumentNullException(nameof(peerOplogConfirmationStore));
_logger = logger ?? NullLogger<PeerManagementService>.Instance;
}
/// <summary>
/// Adds or updates a static remote peer configuration.
/// Adds or updates a static remote peer configuration.
/// </summary>
/// <param name="nodeId">The unique node identifier of the peer.</param>
/// <param name="address">The peer network address in host:port format.</param>
@@ -60,22 +60,23 @@ public class PeerManagementService : IPeerManagementService
};
await _store.SaveRemotePeerAsync(config, cancellationToken);
_logger.LogInformation("Added static remote peer: {NodeId} at {Address} (will sync to all cluster nodes)", nodeId, address);
_logger.LogInformation("Added static remote peer: {NodeId} at {Address} (will sync to all cluster nodes)",
nodeId, address);
}
/// <summary>
/// Removes a remote peer configuration.
/// Removes a remote peer configuration.
/// </summary>
/// <param name="nodeId">The unique node identifier of the peer to remove.</param>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public async Task RemoveRemotePeerAsync(string nodeId, CancellationToken cancellationToken = default)
{
await RemovePeerTrackingAsync(nodeId, removeRemoteConfig: true, cancellationToken);
await RemovePeerTrackingAsync(nodeId, true, cancellationToken);
}
/// <summary>
/// Removes peer tracking and optionally removes remote peer configuration.
/// Removes peer tracking and optionally removes remote peer configuration.
/// </summary>
/// <param name="nodeId">The unique node identifier of the peer to untrack.</param>
/// <param name="removeRemoteConfig">When true, also removes static remote peer configuration.</param>
@@ -93,7 +94,8 @@ public class PeerManagementService : IPeerManagementService
if (removeRemoteConfig)
{
await _store.RemoveRemotePeerAsync(nodeId, cancellationToken);
_logger.LogInformation("Removed remote peer and tracking: {NodeId} (will sync to all cluster nodes)", nodeId);
_logger.LogInformation("Removed remote peer and tracking: {NodeId} (will sync to all cluster nodes)",
nodeId);
return;
}
@@ -101,17 +103,18 @@ public class PeerManagementService : IPeerManagementService
}
/// <summary>
/// Gets all configured remote peers.
/// Gets all configured remote peers.
/// </summary>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous operation. The task result contains remote peer configurations.</returns>
public async Task<IEnumerable<RemotePeerConfiguration>> GetAllRemotePeersAsync(CancellationToken cancellationToken = default)
public async Task<IEnumerable<RemotePeerConfiguration>> GetAllRemotePeersAsync(
CancellationToken cancellationToken = default)
{
return await _store.GetRemotePeersAsync(cancellationToken);
}
/// <summary>
/// Enables a configured remote peer.
/// Enables a configured remote peer.
/// </summary>
/// <param name="nodeId">The unique node identifier of the peer to enable.</param>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
@@ -122,10 +125,7 @@ public class PeerManagementService : IPeerManagementService
var peer = await _store.GetRemotePeerAsync(nodeId, cancellationToken);
if (peer == null)
{
return; // Peer not found, nothing to enable
}
if (peer == null) return; // Peer not found, nothing to enable
if (!peer.IsEnabled)
{
@@ -136,7 +136,7 @@ public class PeerManagementService : IPeerManagementService
}
/// <summary>
/// Disables a configured remote peer.
/// Disables a configured remote peer.
/// </summary>
/// <param name="nodeId">The unique node identifier of the peer to disable.</param>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
@@ -147,10 +147,7 @@ public class PeerManagementService : IPeerManagementService
var peer = await _store.GetRemotePeerAsync(nodeId, cancellationToken);
if (peer == null)
{
return; // Peer not found, nothing to disable
}
if (peer == null) return; // Peer not found, nothing to disable
if (peer.IsEnabled)
{
@@ -163,23 +160,16 @@ public class PeerManagementService : IPeerManagementService
private static void ValidateNodeId(string nodeId)
{
if (string.IsNullOrWhiteSpace(nodeId))
{
throw new ArgumentException("NodeId cannot be null or empty", nameof(nodeId));
}
}
private static void ValidateAddress(string address)
{
if (string.IsNullOrWhiteSpace(address))
{
throw new ArgumentException("Address cannot be null or empty", nameof(address));
}
// Basic format validation (should contain host:port)
if (!address.Contains(':'))
{
throw new ArgumentException("Address must be in format 'host:port'", nameof(address));
}
}
}
}

56
src/ZB.MOM.WW.CBDDC.Core/Network/IPeerNodeConfigurationProvider.cs
View File

@@ -1,38 +1,40 @@
using System;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Network;
/// <summary>
/// Represents a method that handles peer node configuration change notifications.
/// </summary>
/// <param name="sender">The source of the event.</param>
/// <param name="newConfig">The updated peer node configuration.</param>
public delegate void PeerNodeConfigurationChangedEventHandler(object? sender, PeerNodeConfiguration newConfig);
namespace ZB.MOM.WW.CBDDC.Core.Network;
/// <summary>
/// Defines a contract for retrieving and monitoring configuration settings for a peer node.
/// Represents a method that handles peer node configuration change notifications.
/// </summary>
/// <remarks>Implementations of this interface provide access to the current configuration and notify subscribers
/// when configuration changes occur. This interface is typically used by components that require up-to-date
/// configuration information for peer-to-peer networking scenarios.</remarks>
/// <param name="sender">The source of the event.</param>
/// <param name="newConfig">The updated peer node configuration.</param>
public delegate void PeerNodeConfigurationChangedEventHandler(object? sender, PeerNodeConfiguration newConfig);
/// <summary>
/// Defines a contract for retrieving and monitoring configuration settings for a peer node.
/// </summary>
/// <remarks>
/// Implementations of this interface provide access to the current configuration and notify subscribers
/// when configuration changes occur. This interface is typically used by components that require up-to-date
/// configuration information for peer-to-peer networking scenarios.
/// </remarks>
public interface IPeerNodeConfigurationProvider
{
/// <summary>
/// Asynchronously retrieves the current configuration settings for the peer node.
/// </summary>
/// <returns>
/// A task that represents the asynchronous operation. The task result contains the current
/// <see cref="PeerNodeConfiguration"/>.
/// </returns>
public Task<PeerNodeConfiguration> GetConfiguration();
/// <summary>
/// Asynchronously retrieves the current configuration settings for the peer node.
/// </summary>
/// <returns>
/// A task that represents the asynchronous operation. The task result contains the current
/// <see cref="PeerNodeConfiguration" />.
/// </returns>
public Task<PeerNodeConfiguration> GetConfiguration();
/// <summary>
/// Occurs when the configuration of the peer node changes.
/// Occurs when the configuration of the peer node changes.
/// </summary>
/// <remarks>Subscribe to this event to be notified when any configuration settings for the peer node are
/// modified. Event handlers can use this notification to update dependent components or respond to configuration
/// changes as needed.</remarks>
/// <remarks>
/// Subscribe to this event to be notified when any configuration settings for the peer node are
/// modified. Event handlers can use this notification to update dependent components or respond to configuration
/// changes as needed.
/// </remarks>
public event PeerNodeConfigurationChangedEventHandler? ConfigurationChanged;
}
}

14
src/ZB.MOM.WW.CBDDC.Core/Network/NodeRole.cs
View File

@@ -1,20 +1,20 @@
namespace ZB.MOM.WW.CBDDC.Core.Network;
/// <summary>
/// Defines the role of a node in the distributed network cluster.
/// Defines the role of a node in the distributed network cluster.
/// </summary>
public enum NodeRole
{
/// <summary>
/// Standard member node that synchronizes only within the local area network.
/// Does not connect to cloud remote nodes.
/// Standard member node that synchronizes only within the local area network.
/// Does not connect to cloud remote nodes.
/// </summary>
Member = 0,
/// <summary>
/// Leader node that acts as a gateway to cloud remote nodes.
/// Elected via the Bully algorithm (lexicographically smallest NodeId).
/// Responsible for synchronizing local cluster changes with cloud nodes.
/// Leader node that acts as a gateway to cloud remote nodes.
/// Elected via the Bully algorithm (lexicographically smallest NodeId).
/// Responsible for synchronizing local cluster changes with cloud nodes.
/// </summary>
CloudGateway = 1
}
}

87
src/ZB.MOM.WW.CBDDC.Core/Network/PeerNode.cs
View File

@@ -1,53 +1,17 @@
using System;
using System.Collections.Generic;
using System.Linq;
namespace ZB.MOM.WW.CBDDC.Core.Network;
/// <summary>
/// Represents a peer node in a distributed network, including its unique identifier, network address, and last seen
/// timestamp.
/// Represents a peer node in a distributed network, including its unique identifier, network address, and last seen
/// timestamp.
/// </summary>
public class PeerNode
{
/// <summary>
/// Gets the unique identifier for the node.
/// </summary>
public string NodeId { get; }
/// <summary>
/// Gets the address associated with the current instance.
/// </summary>
public string Address { get; }
/// <summary>
/// Gets the date and time when the entity was last observed or updated.
/// </summary>
public DateTimeOffset LastSeen { get; }
/// <summary>
/// Gets the configuration settings for the peer node.
/// </summary>
public PeerNodeConfiguration? Configuration { get; }
/// <summary>
/// Gets the type of the peer node (LanDiscovered, StaticRemote, or CloudRemote).
/// </summary>
public PeerType Type { get; }
/// <summary>
/// Gets the role assigned to this node within the cluster.
/// </summary>
public NodeRole Role { get; }
/// <summary>
/// Gets the list of collections this peer is interested in.
/// </summary>
public System.Collections.Generic.IReadOnlyList<string> InterestingCollections { get; }
/// <summary>
/// Initializes a new instance of the PeerNode class with the specified node identifier, network address, and last
/// seen timestamp.
/// Initializes a new instance of the PeerNode class with the specified node identifier, network address, and last
/// seen timestamp.
/// </summary>
/// <param name="nodeId">The unique identifier for the peer node. Cannot be null or empty.</param>
/// <param name="address">The network address of the peer node. Cannot be null or empty.</param>
@@ -57,10 +21,10 @@ public class PeerNode
/// <param name="configuration">The peer node configuration</param>
/// <param name="interestingCollections">The list of collections this peer is interested in.</param>
public PeerNode(
string nodeId,
string address,
string nodeId,
string address,
DateTimeOffset lastSeen,
PeerType type = PeerType.LanDiscovered,
PeerType type = PeerType.LanDiscovered,
NodeRole role = NodeRole.Member,
PeerNodeConfiguration? configuration = null,
IEnumerable<string>? interestingCollections = null)
@@ -73,4 +37,39 @@ public class PeerNode
Configuration = configuration;
InterestingCollections = new List<string>(interestingCollections ?? []).AsReadOnly();
}
}
/// <summary>
/// Gets the unique identifier for the node.
/// </summary>
public string NodeId { get; }
/// <summary>
/// Gets the address associated with the current instance.
/// </summary>
public string Address { get; }
/// <summary>
/// Gets the date and time when the entity was last observed or updated.
/// </summary>
public DateTimeOffset LastSeen { get; }
/// <summary>
/// Gets the configuration settings for the peer node.
/// </summary>
public PeerNodeConfiguration? Configuration { get; }
/// <summary>
/// Gets the type of the peer node (LanDiscovered, StaticRemote, or CloudRemote).
/// </summary>
public PeerType Type { get; }
/// <summary>
/// Gets the role assigned to this node within the cluster.
/// </summary>
public NodeRole Role { get; }
/// <summary>
/// Gets the list of collections this peer is interested in.
/// </summary>
public IReadOnlyList<string> InterestingCollections { get; }
}

73
src/ZB.MOM.WW.CBDDC.Core/Network/PeerNodeConfiguration.cs
View File

@@ -1,96 +1,101 @@
using System;
using System.Collections.Generic;
namespace ZB.MOM.WW.CBDDC.Core.Network;
/// <summary>
/// Represents the configuration settings for a peer node in a distributed network.
/// Represents the configuration settings for a peer node in a distributed network.
/// </summary>
/// <remarks>Use this class to specify identification, network port, and authentication details required for a
/// peer node to participate in a cluster or peer-to-peer environment. The <see cref="Default"/> property provides a
/// basic configuration suitable for development or testing scenarios.</remarks>
/// <remarks>
/// Use this class to specify identification, network port, and authentication details required for a
/// peer node to participate in a cluster or peer-to-peer environment. The <see cref="Default" /> property provides a
/// basic configuration suitable for development or testing scenarios.
/// </remarks>
public class PeerNodeConfiguration
{
/// <summary>
/// Gets or sets the unique identifier for the node.
/// Gets or sets the unique identifier for the node.
/// </summary>
public string NodeId { get; set; } = string.Empty;
public string NodeId { get; set; } = string.Empty;
/// <summary>
/// Gets or sets the TCP port number used for network communication.
/// Gets or sets the TCP port number used for network communication.
/// </summary>
public int TcpPort { get; set; }
/// <summary>
/// Gets or sets the authentication token used to authorize API requests.
/// Gets or sets the authentication token used to authorize API requests.
/// </summary>
public string AuthToken { get; set; } = string.Empty;
public string AuthToken { get; set; } = string.Empty;
/// <summary>
/// Maximum size of the document cache items. Default: 10.
/// Maximum size of the document cache items. Default: 10.
/// </summary>
public int MaxDocumentCacheSize { get; set; } = 100;
/// <summary>
/// Maximum size of offline queue. Default: 1000.
/// Maximum size of offline queue. Default: 1000.
/// </summary>
public int MaxQueueSize { get; set; } = 1000;
/// <summary>
/// Number of retry attempts for failed network operations. Default: 3.
/// Number of retry attempts for failed network operations. Default: 3.
/// </summary>
public int RetryAttempts { get; set; } = 3;
/// <summary>
/// Delay between retry attempts in milliseconds. Default: 1000ms.
/// Delay between retry attempts in milliseconds. Default: 1000ms.
/// </summary>
public int RetryDelayMs { get; set; } = 1000;
/// <summary>
/// Interval between periodic maintenance operations (Oplog pruning) in minutes. Default: 60 minutes.
/// Interval between periodic maintenance operations (Oplog pruning) in minutes. Default: 60 minutes.
/// </summary>
public int MaintenanceIntervalMinutes { get; set; } = 60;
/// <summary>
/// Oplog retention period in hours. Entries older than this will be pruned. Default: 24 hours.
/// Oplog retention period in hours. Entries older than this will be pruned. Default: 24 hours.
/// </summary>
public int OplogRetentionHours { get; set; } = 24;
/// <summary>
/// Gets or sets a list of known peers to connect to directly, bypassing discovery.
/// Gets or sets a list of known peers to connect to directly, bypassing discovery.
/// </summary>
public System.Collections.Generic.List<KnownPeerConfiguration> KnownPeers { get; set; } = new();
public List<KnownPeerConfiguration> KnownPeers { get; set; } = new();
/// <summary>
/// Gets the default configuration settings for a peer node.
/// Gets the default configuration settings for a peer node.
/// </summary>
/// <remarks>Each access returns a new instance of the configuration with a unique node identifier. The
/// default settings use TCP port 9000 and a generated authentication token. Modify the returned instance as needed
/// before use.</remarks>
public static PeerNodeConfiguration Default => new PeerNodeConfiguration
{
NodeId = Guid.NewGuid().ToString(),
TcpPort = 9000,
AuthToken = Guid.NewGuid().ToString("N")
};
/// <remarks>
/// Each access returns a new instance of the configuration with a unique node identifier. The
/// default settings use TCP port 9000 and a generated authentication token. Modify the returned instance as needed
/// before use.
/// </remarks>
public static PeerNodeConfiguration Default => new()
{
NodeId = Guid.NewGuid().ToString(),
TcpPort = 9000,
AuthToken = Guid.NewGuid().ToString("N")
};
}
/// <summary>
/// Configuration for a known peer node.
/// Configuration for a known peer node.
/// </summary>
public class KnownPeerConfiguration
{
/// <summary>
/// The unique identifier of the peer node.
/// The unique identifier of the peer node.
/// </summary>
public string NodeId { get; set; } = string.Empty;
public string NodeId { get; set; } = string.Empty;
/// <summary>
/// The hostname or IP address of the peer.
/// The hostname or IP address of the peer.
/// </summary>
public string Host { get; set; } = string.Empty;
public string Host { get; set; } = string.Empty;
/// <summary>
/// The TCP port of the peer.
/// The TCP port of the peer.
/// </summary>
public int Port { get; set; }
}
}

18
src/ZB.MOM.WW.CBDDC.Core/Network/PeerType.cs
View File

@@ -1,26 +1,26 @@
namespace ZB.MOM.WW.CBDDC.Core.Network;
/// <summary>
/// Defines the type of peer node in the distributed network.
/// Defines the type of peer node in the distributed network.
/// </summary>
public enum PeerType
{
/// <summary>
/// Peer discovered via UDP broadcast on the local area network.
/// These peers are ephemeral and removed after timeout when no longer broadcasting.
/// Peer discovered via UDP broadcast on the local area network.
/// These peers are ephemeral and removed after timeout when no longer broadcasting.
/// </summary>
LanDiscovered = 0,
/// <summary>
/// Peer manually configured with a static address.
/// These peers are persistent across restarts and stored in the database.
/// Peer manually configured with a static address.
/// These peers are persistent across restarts and stored in the database.
/// </summary>
StaticRemote = 1,
/// <summary>
/// Cloud remote node.
/// Always active if internet connectivity is available.
/// Synchronized only by the elected leader node to reduce overhead.
/// Cloud remote node.
/// Always active if internet connectivity is available.
/// Synchronized only by the elected leader node to reduce overhead.
/// </summary>
CloudRemote = 2
}
}

23
src/ZB.MOM.WW.CBDDC.Core/Network/RemotePeerConfiguration.cs
View File

@@ -1,38 +1,39 @@
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
namespace ZB.MOM.WW.CBDDC.Core.Network;
/// <summary>
/// Configuration for a remote peer node that is persistent across restarts.
/// This collection is automatically synchronized across all nodes in the cluster.
/// Configuration for a remote peer node that is persistent across restarts.
/// This collection is automatically synchronized across all nodes in the cluster.
/// </summary>
public class RemotePeerConfiguration
{
/// <summary>
/// Gets or sets the unique identifier for the remote peer node.
/// Gets or sets the unique identifier for the remote peer node.
/// </summary>
[Key]
public string NodeId { get; set; } = "";
/// <summary>
/// Gets or sets the network address of the remote peer (hostname:port).
/// Gets or sets the network address of the remote peer (hostname:port).
/// </summary>
public string Address { get; set; } = "";
/// <summary>
/// Gets or sets the type of the peer (StaticRemote or CloudRemote).
/// Gets or sets the type of the peer (StaticRemote or CloudRemote).
/// </summary>
public PeerType Type { get; set; }
/// <summary>
/// Gets or sets whether this peer is enabled for synchronization.
/// Disabled peers are stored but not used for sync.
/// Gets or sets whether this peer is enabled for synchronization.
/// Disabled peers are stored but not used for sync.
/// </summary>
public bool IsEnabled { get; set; } = true;
/// <summary>
/// Gets or sets the list of collections this peer is interested in.
/// If empty, the peer is interested in all collections.
/// Gets or sets the list of collections this peer is interested in.
/// If empty, the peer is interested in all collections.
/// </summary>
public System.Collections.Generic.List<string> InterestingCollections { get; set; } = new();
}
public List<string> InterestingCollections { get; set; } = new();
}

48
src/ZB.MOM.WW.CBDDC.Core/Network/StaticPeerNodeConfigurationProvider.cs
View File

@@ -1,32 +1,16 @@
using System.Threading.Tasks;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Network;
/// <summary>
/// Provides peer node configuration from an in-memory static source.
/// Provides peer node configuration from an in-memory static source.
/// </summary>
public class StaticPeerNodeConfigurationProvider : IPeerNodeConfigurationProvider
{
private PeerNodeConfiguration _configuration = new();
/// <summary>
/// Gets or sets the current peer node configuration.
/// </summary>
public PeerNodeConfiguration Configuration
{
get => _configuration;
set
{
if (_configuration != value)
{
_configuration = value;
OnConfigurationChanged(_configuration);
}
}
}
/// <summary>
/// Initializes a new instance of the <see cref="StaticPeerNodeConfigurationProvider"/> class.
/// Initializes a new instance of the <see cref="StaticPeerNodeConfigurationProvider" /> class.
/// </summary>
/// <param name="configuration">The initial peer node configuration.</param>
public StaticPeerNodeConfigurationProvider(PeerNodeConfiguration configuration)
@@ -35,12 +19,28 @@ public class StaticPeerNodeConfigurationProvider : IPeerNodeConfigurationProvide
}
/// <summary>
/// Occurs when the peer node configuration changes.
/// Gets or sets the current peer node configuration.
/// </summary>
public PeerNodeConfiguration Configuration
{
get => _configuration;
set
{
if (_configuration != value)
{
_configuration = value;
OnConfigurationChanged(_configuration);
}
}
}
/// <summary>
/// Occurs when the peer node configuration changes.
/// </summary>
public event PeerNodeConfigurationChangedEventHandler? ConfigurationChanged;
/// <summary>
/// Gets the current peer node configuration.
/// Gets the current peer node configuration.
/// </summary>
/// <returns>A task whose result is the current configuration.</returns>
public Task<PeerNodeConfiguration> GetConfiguration()
@@ -49,11 +49,11 @@ public class StaticPeerNodeConfigurationProvider : IPeerNodeConfigurationProvide
}
/// <summary>
/// Raises the <see cref="ConfigurationChanged"/> event.
/// Raises the <see cref="ConfigurationChanged" /> event.
/// </summary>
/// <param name="newConfig">The new peer node configuration.</param>
protected virtual void OnConfigurationChanged(PeerNodeConfiguration newConfig)
{
ConfigurationChanged?.Invoke(this, newConfig);
}
}
}

131
src/ZB.MOM.WW.CBDDC.Core/OplogEntry.cs
View File

@@ -1,5 +1,7 @@
using System;
using System.ComponentModel.DataAnnotations;
using System.Globalization;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
namespace ZB.MOM.WW.CBDDC.Core;
@@ -10,84 +12,56 @@ public enum OperationType
Delete
}
public static class OplogEntryExtensions
{
/// <summary>
/// Computes a deterministic hash for the specified oplog entry.
/// </summary>
/// <param name="entry">The oplog entry to hash.</param>
/// <returns>The lowercase hexadecimal SHA-256 hash of the entry.</returns>
public static string ComputeHash(this OplogEntry entry)
{
using var sha256 = System.Security.Cryptography.SHA256.Create();
var sb = new System.Text.StringBuilder();
public static class OplogEntryExtensions
{
/// <summary>
/// Computes a deterministic hash for the specified oplog entry.
/// </summary>
/// <param name="entry">The oplog entry to hash.</param>
/// <returns>The lowercase hexadecimal SHA-256 hash of the entry.</returns>
public static string ComputeHash(this OplogEntry entry)
{
using var sha256 = SHA256.Create();
var sb = new StringBuilder();
sb.Append(entry.Collection);
sb.Append('|');
sb.Append(entry.Key);
sb.Append('|');
// Ensure stable string representation for Enum (integer value)
sb.Append(((int)entry.Operation).ToString(System.Globalization.CultureInfo.InvariantCulture));
sb.Append(((int)entry.Operation).ToString(CultureInfo.InvariantCulture));
sb.Append('|');
// Payload excluded from hash to avoid serialization non-determinism
// sb.Append(entry.Payload...);
sb.Append('|');
// Timestamp.ToString() is now Invariant
sb.Append(entry.Timestamp.ToString());
sb.Append(entry.Timestamp.ToString());
sb.Append('|');
sb.Append(entry.PreviousHash);
var bytes = System.Text.Encoding.UTF8.GetBytes(sb.ToString());
var hashBytes = sha256.ComputeHash(bytes);
byte[] bytes = Encoding.UTF8.GetBytes(sb.ToString());
byte[] hashBytes = sha256.ComputeHash(bytes);
// Convert to hex string
return BitConverter.ToString(hashBytes).Replace("-", "").ToLowerInvariant();
}
}
public class OplogEntry
{
/// <summary>
/// Gets the collection name associated with this entry.
/// </summary>
public string Collection { get; }
/// <summary>
/// Gets the document key associated with this entry.
/// </summary>
public string Key { get; }
/// <summary>
/// Gets the operation represented by this entry.
/// </summary>
public OperationType Operation { get; }
/// <summary>
/// Gets the serialized payload for the operation.
/// </summary>
public JsonElement? Payload { get; }
/// <summary>
/// Gets the logical timestamp for this entry.
/// </summary>
public HlcTimestamp Timestamp { get; }
/// <summary>
/// Gets the hash of this entry.
/// </summary>
public string Hash { get; }
/// <summary>
/// Gets the hash of the previous entry in the chain.
/// </summary>
public string PreviousHash { get; }
/// <summary>
/// Initializes a new instance of the <see cref="OplogEntry"/> class.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="operation">The operation type.</param>
/// <param name="payload">The serialized payload.</param>
/// <param name="timestamp">The logical timestamp.</param>
/// <param name="previousHash">The previous entry hash.</param>
/// <param name="hash">The current entry hash. If null, it is computed.</param>
public OplogEntry(string collection, string key, OperationType operation, JsonElement? payload, HlcTimestamp timestamp, string previousHash, string? hash = null)
{
public class OplogEntry
{
/// <summary>
/// Initializes a new instance of the <see cref="OplogEntry" /> class.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="operation">The operation type.</param>
/// <param name="payload">The serialized payload.</param>
/// <param name="timestamp">The logical timestamp.</param>
/// <param name="previousHash">The previous entry hash.</param>
/// <param name="hash">The current entry hash. If null, it is computed.</param>
public OplogEntry(string collection, string key, OperationType operation, JsonElement? payload,
HlcTimestamp timestamp, string previousHash, string? hash = null)
{
Collection = collection;
Key = key;
Operation = operation;
@@ -98,10 +72,45 @@ public class OplogEntry
}
/// <summary>
/// Verifies if the stored Hash matches the content.
/// Gets the collection name associated with this entry.
/// </summary>
public string Collection { get; }
/// <summary>
/// Gets the document key associated with this entry.
/// </summary>
public string Key { get; }
/// <summary>
/// Gets the operation represented by this entry.
/// </summary>
public OperationType Operation { get; }
/// <summary>
/// Gets the serialized payload for the operation.
/// </summary>
public JsonElement? Payload { get; }
/// <summary>
/// Gets the logical timestamp for this entry.
/// </summary>
public HlcTimestamp Timestamp { get; }
/// <summary>
/// Gets the hash of this entry.
/// </summary>
public string Hash { get; }
/// <summary>
/// Gets the hash of the previous entry in the chain.
/// </summary>
public string PreviousHash { get; }
/// <summary>
/// Verifies if the stored Hash matches the content.
/// </summary>
public bool IsValid()
{
return Hash == this.ComputeHash();
}
}
}

18
src/ZB.MOM.WW.CBDDC.Core/PeerOplogConfirmation.cs
View File

@@ -3,42 +3,42 @@ using System;
namespace ZB.MOM.WW.CBDDC.Core;
/// <summary>
/// Represents a persisted confirmation watermark for a tracked peer and source node.
/// Represents a persisted confirmation watermark for a tracked peer and source node.
/// </summary>
public class PeerOplogConfirmation
{
/// <summary>
/// Gets or sets the tracked peer node identifier.
/// Gets or sets the tracked peer node identifier.
/// </summary>
public string PeerNodeId { get; set; } = "";
/// <summary>
/// Gets or sets the source node identifier this confirmation applies to.
/// Gets or sets the source node identifier this confirmation applies to.
/// </summary>
public string SourceNodeId { get; set; } = "";
/// <summary>
/// Gets or sets the physical wall-clock component of the confirmed HLC timestamp.
/// Gets or sets the physical wall-clock component of the confirmed HLC timestamp.
/// </summary>
public long ConfirmedWall { get; set; }
/// <summary>
/// Gets or sets the logical counter component of the confirmed HLC timestamp.
/// Gets or sets the logical counter component of the confirmed HLC timestamp.
/// </summary>
public int ConfirmedLogic { get; set; }
/// <summary>
/// Gets or sets the confirmed hash at the watermark.
/// Gets or sets the confirmed hash at the watermark.
/// </summary>
public string ConfirmedHash { get; set; } = "";
/// <summary>
/// Gets or sets when this confirmation record was last updated in UTC.
/// Gets or sets when this confirmation record was last updated in UTC.
/// </summary>
public DateTimeOffset LastConfirmedUtc { get; set; } = DateTimeOffset.UtcNow;
/// <summary>
/// Gets or sets whether this tracked peer is active for pruning/sync gating.
/// Gets or sets whether this tracked peer is active for pruning/sync gating.
/// </summary>
public bool IsActive { get; set; } = true;
}
}

256
src/ZB.MOM.WW.CBDDC.Core/QueryNode.cs
View File

@@ -1,225 +1,269 @@
using System.Text.Json;
namespace ZB.MOM.WW.CBDDC.Core;
public abstract class QueryNode { }
namespace ZB.MOM.WW.CBDDC.Core;
public abstract class QueryNode
{
}
public class Eq : QueryNode
{
/// <summary>
/// Gets the field name to compare.
/// Initializes a new equality query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The value to compare against.</param>
public Eq(string field, object value)
{
Field = field;
Value = value;
}
/// <summary>
/// Gets the field name to compare.
/// </summary>
public string Field { get; }
/// <summary>
/// Gets the value to compare against.
/// Gets the value to compare against.
/// </summary>
public object Value { get; }
/// <summary>
/// Initializes a new equality query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The value to compare against.</param>
public Eq(string field, object value) { Field = field; Value = value; }
}
public class Gt : QueryNode
{
/// <summary>
/// Gets the field name to compare.
/// Initializes a new greater-than query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The threshold value.</param>
public Gt(string field, object value)
{
Field = field;
Value = value;
}
/// <summary>
/// Gets the field name to compare.
/// </summary>
public string Field { get; }
/// <summary>
/// Gets the threshold value.
/// Gets the threshold value.
/// </summary>
public object Value { get; }
/// <summary>
/// Initializes a new greater-than query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The threshold value.</param>
public Gt(string field, object value) { Field = field; Value = value; }
}
public class Lt : QueryNode
{
/// <summary>
/// Gets the field name to compare.
/// Initializes a new less-than query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The threshold value.</param>
public Lt(string field, object value)
{
Field = field;
Value = value;
}
/// <summary>
/// Gets the field name to compare.
/// </summary>
public string Field { get; }
/// <summary>
/// Gets the threshold value.
/// Gets the threshold value.
/// </summary>
public object Value { get; }
/// <summary>
/// Initializes a new less-than query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The threshold value.</param>
public Lt(string field, object value) { Field = field; Value = value; }
}
public class Gte : QueryNode
{
/// <summary>
/// Gets the field name to compare.
/// Initializes a new greater-than-or-equal query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The threshold value.</param>
public Gte(string field, object value)
{
Field = field;
Value = value;
}
/// <summary>
/// Gets the field name to compare.
/// </summary>
public string Field { get; }
/// <summary>
/// Gets the threshold value.
/// Gets the threshold value.
/// </summary>
public object Value { get; }
/// <summary>
/// Initializes a new greater-than-or-equal query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The threshold value.</param>
public Gte(string field, object value) { Field = field; Value = value; }
}
public class Lte : QueryNode
{
/// <summary>
/// Gets the field name to compare.
/// Initializes a new less-than-or-equal query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The threshold value.</param>
public Lte(string field, object value)
{
Field = field;
Value = value;
}
/// <summary>
/// Gets the field name to compare.
/// </summary>
public string Field { get; }
/// <summary>
/// Gets the threshold value.
/// Gets the threshold value.
/// </summary>
public object Value { get; }
/// <summary>
/// Initializes a new less-than-or-equal query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The threshold value.</param>
public Lte(string field, object value) { Field = field; Value = value; }
}
public class Neq : QueryNode
{
/// <summary>
/// Gets the field name to compare.
/// Initializes a new not-equal query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The value to compare against.</param>
public Neq(string field, object value)
{
Field = field;
Value = value;
}
/// <summary>
/// Gets the field name to compare.
/// </summary>
public string Field { get; }
/// <summary>
/// Gets the value to compare against.
/// Gets the value to compare against.
/// </summary>
public object Value { get; }
/// <summary>
/// Initializes a new not-equal query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The value to compare against.</param>
public Neq(string field, object value) { Field = field; Value = value; }
}
public class In : QueryNode
{
/// <summary>
/// Gets the field name to compare.
/// Initializes a new in-list query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="values">The set of values to compare against.</param>
public In(string field, object[] values)
{
Field = field;
Values = values;
}
/// <summary>
/// Gets the field name to compare.
/// </summary>
public string Field { get; }
/// <summary>
/// Gets the set of values to compare against.
/// Gets the set of values to compare against.
/// </summary>
public object[] Values { get; }
/// <summary>
/// Initializes a new in-list query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="values">The set of values to compare against.</param>
public In(string field, object[] values) { Field = field; Values = values; }
}
public class Contains : QueryNode
{
/// <summary>
/// Gets the field name to compare.
/// Initializes a new contains query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The substring value to search for.</param>
public Contains(string field, string value)
{
Field = field;
Value = value;
}
/// <summary>
/// Gets the field name to compare.
/// </summary>
public string Field { get; }
/// <summary>
/// Gets the substring value to search for.
/// Gets the substring value to search for.
/// </summary>
public string Value { get; }
/// <summary>
/// Initializes a new contains query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The substring value to search for.</param>
public Contains(string field, string value) { Field = field; Value = value; }
}
public class NotContains : QueryNode
{
/// <summary>
/// Gets the field name to compare.
/// Initializes a new not-contains query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The substring value to exclude.</param>
public NotContains(string field, string value)
{
Field = field;
Value = value;
}
/// <summary>
/// Gets the field name to compare.
/// </summary>
public string Field { get; }
/// <summary>
/// Gets the substring value to exclude.
/// Gets the substring value to exclude.
/// </summary>
public string Value { get; }
/// <summary>
/// Initializes a new not-contains query node.
/// </summary>
/// <param name="field">The field name to compare.</param>
/// <param name="value">The substring value to exclude.</param>
public NotContains(string field, string value) { Field = field; Value = value; }
}
public class And : QueryNode
{
/// <summary>
/// Gets the left side of the logical operation.
/// Initializes a new logical AND query node.
/// </summary>
/// <param name="left">The left query node.</param>
/// <param name="right">The right query node.</param>
public And(QueryNode left, QueryNode right)
{
Left = left;
Right = right;
}
/// <summary>
/// Gets the left side of the logical operation.
/// </summary>
public QueryNode Left { get; }
/// <summary>
/// Gets the right side of the logical operation.
/// Gets the right side of the logical operation.
/// </summary>
public QueryNode Right { get; }
/// <summary>
/// Initializes a new logical AND query node.
/// </summary>
/// <param name="left">The left query node.</param>
/// <param name="right">The right query node.</param>
public And(QueryNode left, QueryNode right) { Left = left; Right = right; }
}
public class Or : QueryNode
{
/// <summary>
/// Gets the left side of the logical operation.
/// Initializes a new logical OR query node.
/// </summary>
/// <param name="left">The left query node.</param>
/// <param name="right">The right query node.</param>
public Or(QueryNode left, QueryNode right)
{
Left = left;
Right = right;
}
/// <summary>
/// Gets the left side of the logical operation.
/// </summary>
public QueryNode Left { get; }
/// <summary>
/// Gets the right side of the logical operation.
/// Gets the right side of the logical operation.
/// </summary>
public QueryNode Right { get; }
/// <summary>
/// Initializes a new logical OR query node.
/// </summary>
/// <param name="left">The left query node.</param>
/// <param name="right">The right query node.</param>
public Or(QueryNode left, QueryNode right) { Left = left; Right = right; }
}
}

27
src/ZB.MOM.WW.CBDDC.Core/README.md
View File

@@ -4,7 +4,9 @@ Core abstractions and logic for **CBDDC**, a peer-to-peer data synchronization m
## What Is CBDDC?
CBDDC is **not** a database — it's a sync layer that plugs into your existing data store (BLite) and enables automatic P2P replication across nodes in a mesh network. Your application reads and writes to its database as usual; CBDDC handles synchronization in the background.
CBDDC is **not** a database <EFBFBD> it's a sync layer that plugs into your existing data store (BLite) and enables automatic
P2P replication across nodes in a mesh network. Your application reads and writes to its database as usual; CBDDC
handles synchronization in the background.
## What's In This Package
@@ -17,7 +19,7 @@ CBDDC is **not** a database
```bash
# Pick a persistence provider
dotnet add package ZB.MOM.WW.CBDDC.Persistence # Embedded document DB
dotnet add package ZB.MOM.WW.CBDDC.Persistence # Embedded document DB
# Add networking
dotnet add package ZB.MOM.WW.CBDDC.Network
@@ -65,12 +67,12 @@ builder.Services.AddCBDDCCore()
## Key Concepts
| Concept | Description |
|---------|-------------|
| **CDC** | Change Data Capture — watches collections registered via `WatchCollection()` |
| **Oplog** | Append-only hash-chained journal of changes per node |
| **VectorClock** | Tracks causal ordering across the mesh |
| **DocumentStore** | Your bridge between entities and the sync engine |
| Concept | Description |
|-------------------|------------------------------------------------------------------------------|
| **CDC** | Change Data Capture <EFBFBD> watches collections registered via `WatchCollection()` |
| **Oplog** | Append-only hash-chained journal of changes per node |
| **VectorClock** | Tracks causal ordering across the mesh |
| **DocumentStore** | Your bridge between entities and the sync engine |
## Architecture
@@ -91,15 +93,16 @@ Your App ? DbContext.SaveChangesAsync()
## Related Packages
- **ZB.MOM.WW.CBDDC.Persistence** � BLite embedded provider (.NET 10+)
- **ZB.MOM.WW.CBDDC.Network** — P2P networking (UDP discovery, TCP sync, Gossip)
- **ZB.MOM.WW.CBDDC.Persistence** <EFBFBD> BLite embedded provider (.NET 10+)
- **ZB.MOM.WW.CBDDC.Network** <EFBFBD> P2P networking (UDP discovery, TCP sync, Gossip)
## Documentation
- **[Complete Documentation](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net)**
- **[Sample Application](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/tree/main/samples/ZB.MOM.WW.CBDDC.Sample.Console)**
- **[Sample Application](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/tree/main/samples/ZB.MOM.WW.CBDDC.Sample.Console)
**
- **[Integration Guide](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net#integrating-with-your-database)**
## License
MIT — see [LICENSE](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/blob/main/LICENSE)
MIT <EFBFBD> see [LICENSE](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/blob/main/LICENSE)

53
src/ZB.MOM.WW.CBDDC.Core/Resilience/IRetryPolicy.cs
View File

@@ -1,27 +1,28 @@
using System;
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Resilience
using System;
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Resilience;
public interface IRetryPolicy
{
public interface IRetryPolicy
{
/// <summary>
/// Executes an asynchronous operation with retry handling.
/// </summary>
/// <param name="operation">The operation to execute.</param>
/// <param name="operationName">The operation name used for diagnostics.</param>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous execution.</returns>
Task ExecuteAsync(Func<Task> operation, string operationName, CancellationToken cancellationToken = default);
/// <summary>
/// Executes an asynchronous operation with retry handling and returns a result.
/// </summary>
/// <typeparam name="T">The result type.</typeparam>
/// <param name="operation">The operation to execute.</param>
/// <param name="operationName">The operation name used for diagnostics.</param>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous execution and yields the operation result.</returns>
Task<T> ExecuteAsync<T>(Func<Task<T>> operation, string operationName, CancellationToken cancellationToken = default);
}
}
/// <summary>
/// Executes an asynchronous operation with retry handling.
/// </summary>
/// <param name="operation">The operation to execute.</param>
/// <param name="operationName">The operation name used for diagnostics.</param>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous execution.</returns>
Task ExecuteAsync(Func<Task> operation, string operationName, CancellationToken cancellationToken = default);
/// <summary>
/// Executes an asynchronous operation with retry handling and returns a result.
/// </summary>
/// <typeparam name="T">The result type.</typeparam>
/// <param name="operation">The operation to execute.</param>
/// <param name="operationName">The operation name used for diagnostics.</param>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous execution and yields the operation result.</returns>
Task<T> ExecuteAsync<T>(Func<Task<T>> operation, string operationName,
CancellationToken cancellationToken = default);
}

126
src/ZB.MOM.WW.CBDDC.Core/Resilience/RetryPolicy.cs
View File

@@ -1,50 +1,53 @@
using System;
using System.Threading;
using System.Threading.Tasks;
using ZB.MOM.WW.CBDDC.Core.Exceptions;
using ZB.MOM.WW.CBDDC.Core.Network;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using System;
using System.IO;
using System.Net.Sockets;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.CBDDC.Core.Exceptions;
using ZB.MOM.WW.CBDDC.Core.Network;
using TimeoutException = ZB.MOM.WW.CBDDC.Core.Exceptions.TimeoutException;
namespace ZB.MOM.WW.CBDDC.Core.Resilience;
/// <summary>
/// Provides retry logic for transient failures.
/// Provides retry logic for transient failures.
/// </summary>
public class RetryPolicy : IRetryPolicy
{
private readonly IPeerNodeConfigurationProvider _peerNodeConfigurationProvider;
private readonly ILogger<RetryPolicy> _logger;
/// <summary>
/// Initializes a new instance of the <see cref="RetryPolicy"/> class.
/// </summary>
/// <param name="peerNodeConfigurationProvider">The provider for retry configuration values.</param>
/// <param name="logger">The logger instance.</param>
public RetryPolicy(IPeerNodeConfigurationProvider peerNodeConfigurationProvider, ILogger<RetryPolicy>? logger = null)
{
_logger = logger ?? NullLogger<RetryPolicy>.Instance;
_peerNodeConfigurationProvider = peerNodeConfigurationProvider
?? throw new ArgumentNullException(nameof(peerNodeConfigurationProvider));
}
public class RetryPolicy : IRetryPolicy
{
private readonly ILogger<RetryPolicy> _logger;
private readonly IPeerNodeConfigurationProvider _peerNodeConfigurationProvider;
/// <summary>
/// Executes an operation with retry logic.
/// </summary>
/// <typeparam name="T">The result type returned by the operation.</typeparam>
/// <param name="operation">The asynchronous operation to execute.</param>
/// <param name="operationName">The operation name used for logging.</param>
/// <param name="cancellationToken">A token used to cancel retry delays.</param>
public async Task<T> ExecuteAsync<T>(
Func<Task<T>> operation,
string operationName,
CancellationToken cancellationToken = default)
/// <summary>
/// Initializes a new instance of the <see cref="RetryPolicy" /> class.
/// </summary>
/// <param name="peerNodeConfigurationProvider">The provider for retry configuration values.</param>
/// <param name="logger">The logger instance.</param>
public RetryPolicy(IPeerNodeConfigurationProvider peerNodeConfigurationProvider,
ILogger<RetryPolicy>? logger = null)
{
_logger = logger ?? NullLogger<RetryPolicy>.Instance;
_peerNodeConfigurationProvider = peerNodeConfigurationProvider
?? throw new ArgumentNullException(nameof(peerNodeConfigurationProvider));
}
/// <summary>
/// Executes an operation with retry logic.
/// </summary>
/// <typeparam name="T">The result type returned by the operation.</typeparam>
/// <param name="operation">The asynchronous operation to execute.</param>
/// <param name="operationName">The operation name used for logging.</param>
/// <param name="cancellationToken">A token used to cancel retry delays.</param>
public async Task<T> ExecuteAsync<T>(
Func<Task<T>> operation,
string operationName,
CancellationToken cancellationToken = default)
{
var config = await _peerNodeConfigurationProvider.GetConfiguration();
Exception? lastException = null;
for (int attempt = 1; attempt <= config.RetryAttempts; attempt++)
{
for (var attempt = 1; attempt <= config.RetryAttempts; attempt++)
try
{
_logger.LogDebug("Executing {Operation} (attempt {Attempt}/{Max})",
@@ -55,7 +58,7 @@ public class RetryPolicy : IRetryPolicy
catch (Exception ex) when (attempt < config.RetryAttempts && IsTransient(ex))
{
lastException = ex;
var delay = config.RetryDelayMs * attempt; // Exponential backoff
int delay = config.RetryDelayMs * attempt; // Exponential backoff
_logger.LogWarning(ex,
"Operation {Operation} failed (attempt {Attempt}/{Max}). Retrying in {Delay}ms...",
@@ -63,36 +66,31 @@ public class RetryPolicy : IRetryPolicy
await Task.Delay(delay, cancellationToken);
}
}
if (lastException != null)
{
_logger.LogError(lastException,
"Operation {Operation} failed after {Attempts} attempts",
operationName, config.RetryAttempts);
}
else
{
_logger.LogError(
"Operation {Operation} failed after {Attempts} attempts",
operationName, config.RetryAttempts);
}
if (lastException != null)
_logger.LogError(lastException,
"Operation {Operation} failed after {Attempts} attempts",
operationName, config.RetryAttempts);
else
_logger.LogError(
"Operation {Operation} failed after {Attempts} attempts",
operationName, config.RetryAttempts);
throw new CBDDCException("RETRY_EXHAUSTED",
$"Operation '{operationName}' failed after {config.RetryAttempts} attempts",
lastException!);
}
/// <summary>
/// Executes an operation with retry logic (void return).
/// </summary>
/// <param name="operation">The asynchronous operation to execute.</param>
/// <param name="operationName">The operation name used for logging.</param>
/// <param name="cancellationToken">A token used to cancel retry delays.</param>
public async Task ExecuteAsync(
Func<Task> operation,
string operationName,
CancellationToken cancellationToken = default)
/// <summary>
/// Executes an operation with retry logic (void return).
/// </summary>
/// <param name="operation">The asynchronous operation to execute.</param>
/// <param name="operationName">The operation name used for logging.</param>
/// <param name="cancellationToken">A token used to cancel retry delays.</param>
public async Task ExecuteAsync(
Func<Task> operation,
string operationName,
CancellationToken cancellationToken = default)
{
await ExecuteAsync(async () =>
{
@@ -104,13 +102,13 @@ public class RetryPolicy : IRetryPolicy
private static bool IsTransient(Exception ex)
{
// Network errors are typically transient
if (ex is NetworkException or System.Net.Sockets.SocketException or System.IO.IOException)
if (ex is NetworkException or SocketException or IOException)
return true;
// Timeout errors are transient
if (ex is Exceptions.TimeoutException or OperationCanceledException)
if (ex is TimeoutException or OperationCanceledException)
return true;
return false;
}
}
}

17
src/ZB.MOM.WW.CBDDC.Core/SnapshotMetadata.cs
View File

@@ -1,21 +1,24 @@
namespace ZB.MOM.WW.CBDDC.Core;
namespace ZB.MOM.WW.CBDDC.Core;
public class SnapshotMetadata
{
/// <summary>
/// Gets or sets the node identifier associated with the snapshot.
/// Gets or sets the node identifier associated with the snapshot.
/// </summary>
public string NodeId { get; set; } = "";
/// <summary>
/// Gets or sets the physical time component of the snapshot timestamp.
/// Gets or sets the physical time component of the snapshot timestamp.
/// </summary>
public long TimestampPhysicalTime { get; set; }
/// <summary>
/// Gets or sets the logical counter component of the snapshot timestamp.
/// Gets or sets the logical counter component of the snapshot timestamp.
/// </summary>
public int TimestampLogicalCounter { get; set; }
/// <summary>
/// Gets or sets the snapshot hash.
/// Gets or sets the snapshot hash.
/// </summary>
public string Hash { get; set; } = "";
}
}

14
src/ZB.MOM.WW.CBDDC.Core/Storage/CorruptDatabaseException.cs
View File

@@ -1,16 +1,18 @@
using System;
using System;
namespace ZB.MOM.WW.CBDDC.Core.Storage;
/// <summary>
/// Represents an error that occurs when a database is found to be corrupt.
/// Represents an error that occurs when a database is found to be corrupt.
/// </summary>
public class CorruptDatabaseException : Exception
{
/// <summary>
/// Initializes a new instance of the <see cref="CorruptDatabaseException"/> class.
/// Initializes a new instance of the <see cref="CorruptDatabaseException" /> class.
/// </summary>
/// <param name="message">The exception message.</param>
/// <param name="innerException">The underlying exception that caused this error.</param>
public CorruptDatabaseException(string message, Exception innerException) : base(message, innerException) { }
}
public CorruptDatabaseException(string message, Exception innerException) : base(message, innerException)
{
}
}

107
src/ZB.MOM.WW.CBDDC.Core/Storage/IDocumentMetadataStore.cs
View File

@@ -1,108 +1,115 @@
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Storage;
/// <summary>
/// Defines the contract for storing and retrieving document metadata for sync tracking.
/// Document metadata stores HLC timestamps and deleted state without modifying application entities.
/// Defines the contract for storing and retrieving document metadata for sync tracking.
/// Document metadata stores HLC timestamps and deleted state without modifying application entities.
/// </summary>
public interface IDocumentMetadataStore : ISnapshotable<DocumentMetadata>
{
/// <summary>
/// Gets the metadata for a specific document.
/// Gets the metadata for a specific document.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="cancellationToken">A cancellation token.</param>
/// <returns>The document metadata if found; otherwise null.</returns>
Task<DocumentMetadata?> GetMetadataAsync(string collection, string key, CancellationToken cancellationToken = default);
Task<DocumentMetadata?> GetMetadataAsync(string collection, string key,
CancellationToken cancellationToken = default);
/// <summary>
/// Gets metadata for all documents in a collection.
/// Gets metadata for all documents in a collection.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="cancellationToken">A cancellation token.</param>
/// <returns>Enumerable of document metadata for the collection.</returns>
Task<IEnumerable<DocumentMetadata>> GetMetadataByCollectionAsync(string collection, CancellationToken cancellationToken = default);
Task<IEnumerable<DocumentMetadata>> GetMetadataByCollectionAsync(string collection,
CancellationToken cancellationToken = default);
/// <summary>
/// Upserts (inserts or updates) metadata for a document.
/// Upserts (inserts or updates) metadata for a document.
/// </summary>
/// <param name="metadata">The metadata to upsert.</param>
/// <param name="cancellationToken">A cancellation token.</param>
Task UpsertMetadataAsync(DocumentMetadata metadata, CancellationToken cancellationToken = default);
/// <summary>
/// Upserts metadata for multiple documents in batch.
/// Upserts metadata for multiple documents in batch.
/// </summary>
/// <param name="metadatas">The metadata items to upsert.</param>
/// <param name="cancellationToken">A cancellation token.</param>
Task UpsertMetadataBatchAsync(IEnumerable<DocumentMetadata> metadatas, CancellationToken cancellationToken = default);
Task UpsertMetadataBatchAsync(IEnumerable<DocumentMetadata> metadatas,
CancellationToken cancellationToken = default);
/// <summary>
/// Marks a document as deleted by setting IsDeleted=true and updating the timestamp.
/// Marks a document as deleted by setting IsDeleted=true and updating the timestamp.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="timestamp">The HLC timestamp of the deletion.</param>
/// <param name="cancellationToken">A cancellation token.</param>
Task MarkDeletedAsync(string collection, string key, HlcTimestamp timestamp, CancellationToken cancellationToken = default);
Task MarkDeletedAsync(string collection, string key, HlcTimestamp timestamp,
CancellationToken cancellationToken = default);
/// <summary>
/// Gets all document metadata with timestamps after the specified timestamp.
/// Used for incremental sync to find documents modified since last sync.
/// Gets all document metadata with timestamps after the specified timestamp.
/// Used for incremental sync to find documents modified since last sync.
/// </summary>
/// <param name="since">The timestamp to compare against.</param>
/// <param name="collections">Optional collection filter.</param>
/// <param name="cancellationToken">A cancellation token.</param>
/// <returns>Documents modified after the specified timestamp.</returns>
Task<IEnumerable<DocumentMetadata>> GetMetadataAfterAsync(HlcTimestamp since, IEnumerable<string>? collections = null, CancellationToken cancellationToken = default);
Task<IEnumerable<DocumentMetadata>> GetMetadataAfterAsync(HlcTimestamp since,
IEnumerable<string>? collections = null, CancellationToken cancellationToken = default);
}
/// <summary>
/// Represents metadata for a document used in sync tracking.
/// Represents metadata for a document used in sync tracking.
/// </summary>
public class DocumentMetadata
{
/// <summary>
/// Gets or sets the collection name.
/// Initializes a new instance of the <see cref="DocumentMetadata" /> class.
/// </summary>
public string Collection { get; set; } = "";
public DocumentMetadata()
{
}
/// <summary>
/// Gets or sets the document key.
/// Initializes a new instance of the <see cref="DocumentMetadata" /> class.
/// </summary>
public string Key { get; set; } = "";
/// <summary>
/// Gets or sets the HLC timestamp of the last modification.
/// </summary>
public HlcTimestamp UpdatedAt { get; set; }
/// <summary>
/// Gets or sets whether this document is marked as deleted (tombstone).
/// </summary>
public bool IsDeleted { get; set; }
/// <summary>
/// Initializes a new instance of the <see cref="DocumentMetadata"/> class.
/// </summary>
public DocumentMetadata() { }
/// <summary>
/// Initializes a new instance of the <see cref="DocumentMetadata"/> class.
/// </summary>
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="updatedAt">The last update timestamp.</param>
/// <param name="isDeleted">Whether the document is marked as deleted.</param>
public DocumentMetadata(string collection, string key, HlcTimestamp updatedAt, bool isDeleted = false)
{
Collection = collection;
/// <param name="collection">The collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="updatedAt">The last update timestamp.</param>
/// <param name="isDeleted">Whether the document is marked as deleted.</param>
public DocumentMetadata(string collection, string key, HlcTimestamp updatedAt, bool isDeleted = false)
{
Collection = collection;
Key = key;
UpdatedAt = updatedAt;
IsDeleted = isDeleted;
}
}
/// <summary>
/// Gets or sets the collection name.
/// </summary>
public string Collection { get; set; } = "";
/// <summary>
/// Gets or sets the document key.
/// </summary>
public string Key { get; set; } = "";
/// <summary>
/// Gets or sets the HLC timestamp of the last modification.
/// </summary>
public HlcTimestamp UpdatedAt { get; set; }
/// <summary>
/// Gets or sets whether this document is marked as deleted (tombstone).
/// </summary>
public bool IsDeleted { get; set; }
}

124
src/ZB.MOM.WW.CBDDC.Core/Storage/IDocumentStore.cs
View File

@@ -1,91 +1,112 @@
using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Storage;
/// <summary>
/// Handles basic CRUD operations for documents.
/// Handles basic CRUD operations for documents.
/// </summary>
public interface IDocumentStore : ISnapshotable<Document>
{
/// <summary>
/// Gets the collections this store is interested in.
/// </summary>
IEnumerable<string> InterestedCollection { get; }
public interface IDocumentStore : ISnapshotable<Document>
{
/// <summary>
/// Gets the collections this store is interested in.
/// </summary>
IEnumerable<string> InterestedCollection { get; }
/// <summary>
/// Asynchronously retrieves a incoming from the specified collection by its key.
/// Asynchronously retrieves a incoming from the specified collection by its key.
/// </summary>
/// <param name="collection">The name of the collection containing the incoming to retrieve. Cannot be null or empty.</param>
/// <param name="key">The unique key identifying the incoming within the collection. Cannot be null or empty.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous operation. The task result contains the incoming if found; otherwise, null.</returns>
/// <returns>
/// A task that represents the asynchronous operation. The task result contains the incoming if found; otherwise,
/// null.
/// </returns>
Task<Document?> GetDocumentAsync(string collection, string key, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously retrieves all documents belonging to the specified collection.
/// Asynchronously retrieves all documents belonging to the specified collection.
/// </summary>
/// <param name="collection">The name of the collection from which to retrieve documents. Cannot be null or empty.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation. The task result contains an enumerable collection of
/// documents in the specified collection. The collection is empty if no documents are found.</returns>
Task<IEnumerable<Document>> GetDocumentsByCollectionAsync(string collection, CancellationToken cancellationToken = default);
/// <returns>
/// A task that represents the asynchronous operation. The task result contains an enumerable collection of
/// documents in the specified collection. The collection is empty if no documents are found.
/// </returns>
Task<IEnumerable<Document>> GetDocumentsByCollectionAsync(string collection,
CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously inserts a batch of documents into the data store.
/// Asynchronously inserts a batch of documents into the data store.
/// </summary>
/// <param name="documents">The collection of documents to insert. Cannot be null or contain null elements.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous operation. The task result is <see langword="true"/> if all documents
/// were inserted successfully; otherwise, <see langword="false"/>.</returns>
Task<bool> InsertBatchDocumentsAsync(IEnumerable<Document> documents, CancellationToken cancellationToken = default);
/// <returns>
/// A task that represents the asynchronous operation. The task result is <see langword="true" /> if all documents
/// were inserted successfully; otherwise, <see langword="false" />.
/// </returns>
Task<bool> InsertBatchDocumentsAsync(IEnumerable<Document> documents,
CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously updates the specified incoming in the data store.
/// Asynchronously updates the specified incoming in the data store.
/// </summary>
/// <param name="document">The incoming to update. Cannot be null.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the update operation.</param>
/// <returns>A task that represents the asynchronous operation. The task result is <see langword="true"/> if the incoming was
/// successfully updated; otherwise, <see langword="false"/>.</returns>
/// <returns>
/// A task that represents the asynchronous operation. The task result is <see langword="true" /> if the incoming was
/// successfully updated; otherwise, <see langword="false" />.
/// </returns>
Task<bool> PutDocumentAsync(Document document, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously updates a batch of documents in the data store.
/// Asynchronously updates a batch of documents in the data store.
/// </summary>
/// <param name="documents">The collection of documents to update. Cannot be null or contain null elements.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous operation. The task result is <see langword="true"/> if all documents
/// were updated successfully; otherwise, <see langword="false"/>.</returns>
Task<bool> UpdateBatchDocumentsAsync(IEnumerable<Document> documents, CancellationToken cancellationToken = default);
/// <returns>
/// A task that represents the asynchronous operation. The task result is <see langword="true" /> if all documents
/// were updated successfully; otherwise, <see langword="false" />.
/// </returns>
Task<bool> UpdateBatchDocumentsAsync(IEnumerable<Document> documents,
CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously deletes a incoming identified by the specified key from the given collection.
/// Asynchronously deletes a incoming identified by the specified key from the given collection.
/// </summary>
/// <param name="collection">The name of the collection containing the incoming to delete. Cannot be null or empty.</param>
/// <param name="key">The unique key identifying the incoming to delete. Cannot be null or empty.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the delete operation.</param>
/// <returns>A task that represents the asynchronous delete operation. The task result is <see langword="true"/> if the
/// incoming was successfully deleted; otherwise, <see langword="false"/>.</returns>
/// <returns>
/// A task that represents the asynchronous delete operation. The task result is <see langword="true" /> if the
/// incoming was successfully deleted; otherwise, <see langword="false" />.
/// </returns>
Task<bool> DeleteDocumentAsync(string collection, string key, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously deletes a batch of documents identified by their keys.
/// </summary>
/// <remarks>
/// If any of the specified documents cannot be deleted, the method returns <see langword="false"/> but does not
/// throw an exception. The operation is performed asynchronously and may complete partially if cancellation is requested.
/// </remarks>
/// <param name="documentKeys">A collection of incoming keys that specify the documents to delete. Cannot be null or contain null or empty
/// values.</param>
/// <summary>
/// Asynchronously deletes a batch of documents identified by their keys.
/// </summary>
/// <remarks>
/// If any of the specified documents cannot be deleted, the method returns <see langword="false" /> but does not
/// throw an exception. The operation is performed asynchronously and may complete partially if cancellation is
/// requested.
/// </remarks>
/// <param name="documentKeys">
/// A collection of incoming keys that specify the documents to delete. Cannot be null or contain null or empty
/// values.
/// </param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the delete operation.</param>
/// <returns>A task that represents the asynchronous delete operation. The task result is <see langword="true"/> if all
/// specified documents were successfully deleted; otherwise, <see langword="false"/>.</returns>
Task<bool> DeleteBatchDocumentsAsync(IEnumerable<string> documentKeys, CancellationToken cancellationToken = default);
/// <returns>
/// A task that represents the asynchronous delete operation. The task result is <see langword="true" /> if all
/// specified documents were successfully deleted; otherwise, <see langword="false" />.
/// </returns>
Task<bool> DeleteBatchDocumentsAsync(IEnumerable<string> documentKeys,
CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously merges the specified incoming with existing data and returns the updated incoming.
/// Asynchronously merges the specified incoming with existing data and returns the updated incoming.
/// </summary>
/// <param name="incoming">The incoming to merge. Cannot be null.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the merge operation.</param>
@@ -93,11 +114,14 @@ public interface IDocumentStore : ISnapshotable<Document>
Task<Document> MergeAsync(Document incoming, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously retrieves documents identified by the specified collection and key pairs.
/// Asynchronously retrieves documents identified by the specified collection and key pairs.
/// </summary>
/// <param name="documentKeys">A list of tuples, each containing the collection name and the document key that uniquely identify the documents
/// to retrieve. Cannot be null or empty.</param>
/// <param name="documentKeys">
/// A list of tuples, each containing the collection name and the document key that uniquely identify the documents
/// to retrieve. Cannot be null or empty.
/// </param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous retrieval operation.</returns>
Task<IEnumerable<Document>> GetDocumentsAsync(List<(string Collection, string Key)> documentKeys, CancellationToken cancellationToken);
}
Task<IEnumerable<Document>> GetDocumentsAsync(List<(string Collection, string Key)> documentKeys,
CancellationToken cancellationToken);
}

43
src/ZB.MOM.WW.CBDDC.Core/Storage/IOplogStore.cs
View File

@@ -1,5 +1,4 @@
using System;
using System.Buffers;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
@@ -7,17 +6,17 @@ using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Storage;
/// <summary>
/// Handles operations related to the Operation Log (Oplog), synchronization, and logical clocks.
/// Handles operations related to the Operation Log (Oplog), synchronization, and logical clocks.
/// </summary>
public interface IOplogStore : ISnapshotable<OplogEntry>
{
/// <summary>
/// Occurs when changes are applied to the store from external sources (sync).
/// Occurs when changes are applied to the store from external sources (sync).
/// </summary>
event EventHandler<ChangesAppliedEventArgs> ChangesApplied;
/// <summary>
/// Appends a new entry to the operation log asynchronously.
/// Appends a new entry to the operation log asynchronously.
/// </summary>
/// <param name="entry">The operation log entry to append. Cannot be null.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the append operation.</param>
@@ -25,57 +24,64 @@ public interface IOplogStore : ISnapshotable<OplogEntry>
Task AppendOplogEntryAsync(OplogEntry entry, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously retrieves all oplog entries that occurred after the specified timestamp.
/// Asynchronously retrieves all oplog entries that occurred after the specified timestamp.
/// </summary>
/// <param name="timestamp">The timestamp after which oplog entries should be returned.</param>
/// <param name="collections">An optional collection of collection names to filter the results.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation containing matching oplog entries.</returns>
Task<IEnumerable<OplogEntry>> GetOplogAfterAsync(HlcTimestamp timestamp, IEnumerable<string>? collections = null, CancellationToken cancellationToken = default);
Task<IEnumerable<OplogEntry>> GetOplogAfterAsync(HlcTimestamp timestamp, IEnumerable<string>? collections = null,
CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously retrieves the latest observed hybrid logical clock (HLC) timestamp.
/// Asynchronously retrieves the latest observed hybrid logical clock (HLC) timestamp.
/// </summary>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous operation containing the latest HLC timestamp.</returns>
Task<HlcTimestamp> GetLatestTimestampAsync(CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously retrieves the current vector clock representing the state of distributed events.
/// Asynchronously retrieves the current vector clock representing the state of distributed events.
/// </summary>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation containing the current vector clock.</returns>
Task<VectorClock> GetVectorClockAsync(CancellationToken cancellationToken = default);
/// <summary>
/// Retrieves a collection of oplog entries for the specified node that occurred after the given timestamp.
/// Retrieves a collection of oplog entries for the specified node that occurred after the given timestamp.
/// </summary>
/// <param name="nodeId">The unique identifier of the node for which to retrieve oplog entries. Cannot be null or empty.</param>
/// <param name="since">The timestamp after which oplog entries should be returned.</param>
/// <param name="collections">An optional collection of collection names to filter the oplog entries.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation containing oplog entries for the specified node.</returns>
Task<IEnumerable<OplogEntry>> GetOplogForNodeAfterAsync(string nodeId, HlcTimestamp since, IEnumerable<string>? collections = null, CancellationToken cancellationToken = default);
Task<IEnumerable<OplogEntry>> GetOplogForNodeAfterAsync(string nodeId, HlcTimestamp since,
IEnumerable<string>? collections = null, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously retrieves the hash of the most recent entry for the specified node.
/// Asynchronously retrieves the hash of the most recent entry for the specified node.
/// </summary>
/// <param name="nodeId">The unique identifier of the node for which to retrieve the last entry hash. Cannot be null or empty.</param>
/// <param name="nodeId">
/// The unique identifier of the node for which to retrieve the last entry hash. Cannot be null or
/// empty.
/// </param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
/// <returns>A task that represents the asynchronous operation containing the hash string of the last entry or null.</returns>
Task<string?> GetLastEntryHashAsync(string nodeId, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously retrieves a sequence of oplog entries representing the chain between the specified start and end hashes.
/// Asynchronously retrieves a sequence of oplog entries representing the chain between the specified start and end
/// hashes.
/// </summary>
/// <param name="startHash">The hash of the first entry in the chain range. Cannot be null or empty.</param>
/// <param name="endHash">The hash of the last entry in the chain range. Cannot be null or empty.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation containing OplogEntry objects in chain order.</returns>
Task<IEnumerable<OplogEntry>> GetChainRangeAsync(string startHash, string endHash, CancellationToken cancellationToken = default);
Task<IEnumerable<OplogEntry>> GetChainRangeAsync(string startHash, string endHash,
CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously retrieves the oplog entry associated with the specified hash value.
/// Asynchronously retrieves the oplog entry associated with the specified hash value.
/// </summary>
/// <param name="hash">The hash string identifying the oplog entry to retrieve. Cannot be null or empty.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
@@ -83,7 +89,7 @@ public interface IOplogStore : ISnapshotable<OplogEntry>
Task<OplogEntry?> GetEntryByHashAsync(string hash, CancellationToken cancellationToken = default);
/// <summary>
/// Applies a batch of oplog entries asynchronously to the target data store.
/// Applies a batch of oplog entries asynchronously to the target data store.
/// </summary>
/// <param name="oplogEntries">A collection of OplogEntry objects representing the operations to apply. Cannot be null.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the batch operation.</param>
@@ -91,11 +97,10 @@ public interface IOplogStore : ISnapshotable<OplogEntry>
Task ApplyBatchAsync(IEnumerable<OplogEntry> oplogEntries, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously removes entries from the oplog that are older than the specified cutoff timestamp.
/// Asynchronously removes entries from the oplog that are older than the specified cutoff timestamp.
/// </summary>
/// <param name="cutoff">The timestamp that defines the upper bound for entries to be pruned.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the prune operation.</param>
/// <returns>A task that represents the asynchronous prune operation.</returns>
Task PruneOplogAsync(HlcTimestamp cutoff, CancellationToken cancellationToken = default);
}
}

12
src/ZB.MOM.WW.CBDDC.Core/Storage/IPeerConfigurationStore.cs
View File

@@ -6,26 +6,26 @@ using ZB.MOM.WW.CBDDC.Core.Network;
namespace ZB.MOM.WW.CBDDC.Core.Storage;
/// <summary>
/// Handles storage and retrieval of remote peer configurations.
/// Handles storage and retrieval of remote peer configurations.
/// </summary>
public interface IPeerConfigurationStore : ISnapshotable<RemotePeerConfiguration>
{
/// <summary>
/// Saves or updates a remote peer configuration in the persistent store.
/// Saves or updates a remote peer configuration in the persistent store.
/// </summary>
/// <param name="peer">The remote peer configuration to save.</param>
/// <param name="cancellationToken">Cancellation token.</param>
Task SaveRemotePeerAsync(RemotePeerConfiguration peer, CancellationToken cancellationToken = default);
/// <summary>
/// Retrieves all remote peer configurations from the persistent store.
/// Retrieves all remote peer configurations from the persistent store.
/// </summary>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>Collection of remote peer configurations.</returns>
Task<IEnumerable<RemotePeerConfiguration>> GetRemotePeersAsync(CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously retrieves the configuration for a remote peer identified by the specified node ID.
/// Asynchronously retrieves the configuration for a remote peer identified by the specified node ID.
/// </summary>
/// <param name="nodeId">The unique identifier of the remote peer whose configuration is to be retrieved.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
@@ -33,9 +33,9 @@ public interface IPeerConfigurationStore : ISnapshotable<RemotePeerConfiguration
Task<RemotePeerConfiguration?> GetRemotePeerAsync(string nodeId, CancellationToken cancellationToken);
/// <summary>
/// Removes a remote peer configuration from the persistent store.
/// Removes a remote peer configuration from the persistent store.
/// </summary>
/// <param name="nodeId">The unique identifier of the peer to remove.</param>
/// <param name="cancellationToken">Cancellation token.</param>
Task RemoveRemotePeerAsync(string nodeId, CancellationToken cancellationToken = default);
}
}

16
src/ZB.MOM.WW.CBDDC.Core/Storage/IPeerOplogConfirmationStore.cs
View File

@@ -6,12 +6,12 @@ using ZB.MOM.WW.CBDDC.Core.Network;
namespace ZB.MOM.WW.CBDDC.Core.Storage;
/// <summary>
/// Defines persistence operations for peer oplog confirmation tracking.
/// Defines persistence operations for peer oplog confirmation tracking.
/// </summary>
public interface IPeerOplogConfirmationStore : ISnapshotable<PeerOplogConfirmation>
{
/// <summary>
/// Ensures the specified peer is tracked for confirmation-based pruning.
/// Ensures the specified peer is tracked for confirmation-based pruning.
/// </summary>
/// <param name="peerNodeId">The peer node identifier.</param>
/// <param name="address">The peer network address.</param>
@@ -24,7 +24,7 @@ public interface IPeerOplogConfirmationStore : ISnapshotable<PeerOplogConfirmati
CancellationToken cancellationToken = default);
/// <summary>
/// Updates the confirmation watermark for a tracked peer and source node.
/// Updates the confirmation watermark for a tracked peer and source node.
/// </summary>
/// <param name="peerNodeId">The tracked peer node identifier.</param>
/// <param name="sourceNodeId">The source node identifier of the confirmed oplog stream.</param>
@@ -39,14 +39,14 @@ public interface IPeerOplogConfirmationStore : ISnapshotable<PeerOplogConfirmati
CancellationToken cancellationToken = default);
/// <summary>
/// Gets all persisted peer confirmations.
/// Gets all persisted peer confirmations.
/// </summary>
/// <param name="cancellationToken">A cancellation token.</param>
/// <returns>All peer confirmations.</returns>
Task<IEnumerable<PeerOplogConfirmation>> GetConfirmationsAsync(CancellationToken cancellationToken = default);
/// <summary>
/// Gets persisted confirmations for a specific tracked peer.
/// Gets persisted confirmations for a specific tracked peer.
/// </summary>
/// <param name="peerNodeId">The peer node identifier.</param>
/// <param name="cancellationToken">A cancellation token.</param>
@@ -56,16 +56,16 @@ public interface IPeerOplogConfirmationStore : ISnapshotable<PeerOplogConfirmati
CancellationToken cancellationToken = default);
/// <summary>
/// Deactivates tracking for the specified peer.
/// Deactivates tracking for the specified peer.
/// </summary>
/// <param name="peerNodeId">The peer node identifier.</param>
/// <param name="cancellationToken">A cancellation token.</param>
Task RemovePeerTrackingAsync(string peerNodeId, CancellationToken cancellationToken = default);
/// <summary>
/// Gets all active tracked peer identifiers.
/// Gets all active tracked peer identifiers.
/// </summary>
/// <param name="cancellationToken">A cancellation token.</param>
/// <returns>Distinct active tracked peer identifiers.</returns>
Task<IEnumerable<string>> GetActiveTrackedPeersAsync(CancellationToken cancellationToken = default);
}
}

23
src/ZB.MOM.WW.CBDDC.Core/Storage/ISnapshotMetadataStore.cs
View File

@@ -7,16 +7,21 @@ namespace ZB.MOM.WW.CBDDC.Core.Storage;
public interface ISnapshotMetadataStore : ISnapshotable<SnapshotMetadata>
{
/// <summary>
/// Asynchronously retrieves the snapshot metadata associated with the specified node identifier.
/// Asynchronously retrieves the snapshot metadata associated with the specified node identifier.
/// </summary>
/// <param name="nodeId">The unique identifier of the node for which to retrieve snapshot metadata. Cannot be null or empty.</param>
/// <param name="nodeId">
/// The unique identifier of the node for which to retrieve snapshot metadata. Cannot be null or
/// empty.
/// </param>
/// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
/// <returns>A task that represents the asynchronous operation. The task result contains the <see cref="SnapshotMetadata"/>
/// for the specified node if found; otherwise, <see langword="null"/>.</returns>
/// <returns>
/// A task that represents the asynchronous operation. The task result contains the <see cref="SnapshotMetadata" />
/// for the specified node if found; otherwise, <see langword="null" />.
/// </returns>
Task<SnapshotMetadata?> GetSnapshotMetadataAsync(string nodeId, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously inserts the specified snapshot metadata into the data store.
/// Asynchronously inserts the specified snapshot metadata into the data store.
/// </summary>
/// <param name="metadata">The snapshot metadata to insert. Cannot be null.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
@@ -24,7 +29,7 @@ public interface ISnapshotMetadataStore : ISnapshotable<SnapshotMetadata>
Task InsertSnapshotMetadataAsync(SnapshotMetadata metadata, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously updates the metadata for an existing snapshot.
/// Asynchronously updates the metadata for an existing snapshot.
/// </summary>
/// <param name="existingMeta">The metadata object representing the snapshot to update. Cannot be null.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
@@ -32,7 +37,7 @@ public interface ISnapshotMetadataStore : ISnapshotable<SnapshotMetadata>
Task UpdateSnapshotMetadataAsync(SnapshotMetadata existingMeta, CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously retrieves the hash of the current snapshot for the specified node.
/// Asynchronously retrieves the hash of the current snapshot for the specified node.
/// </summary>
/// <param name="nodeId">The unique identifier of the node for which to obtain the snapshot hash.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
@@ -40,9 +45,9 @@ public interface ISnapshotMetadataStore : ISnapshotable<SnapshotMetadata>
Task<string?> GetSnapshotHashAsync(string nodeId, CancellationToken cancellationToken = default);
/// <summary>
/// Gets all snapshot metadata entries. Used for initializing VectorClock cache.
/// Gets all snapshot metadata entries. Used for initializing VectorClock cache.
/// </summary>
/// <param name="cancellationToken">A cancellation token.</param>
/// <returns>All snapshot metadata entries.</returns>
Task<IEnumerable<SnapshotMetadata>> GetAllSnapshotMetadataAsync(CancellationToken cancellationToken = default);
}
}

10
src/ZB.MOM.WW.CBDDC.Core/Storage/ISnapshotService.cs
View File

@@ -5,12 +5,12 @@ using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Storage;
/// <summary>
/// Handles full database lifecycle operations such as snapshots, replacement, and clearing data.
/// Handles full database lifecycle operations such as snapshots, replacement, and clearing data.
/// </summary>
public interface ISnapshotService
{
/// <summary>
/// Asynchronously creates a snapshot of the current state and writes it to the specified destination stream.
/// Asynchronously creates a snapshot of the current state and writes it to the specified destination stream.
/// </summary>
/// <param name="destination">The stream to which the snapshot data will be written.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the snapshot creation operation.</param>
@@ -18,7 +18,7 @@ public interface ISnapshotService
Task CreateSnapshotAsync(Stream destination, CancellationToken cancellationToken = default);
/// <summary>
/// Replaces the existing database with the contents provided in the specified stream asynchronously.
/// Replaces the existing database with the contents provided in the specified stream asynchronously.
/// </summary>
/// <param name="databaseStream">A stream containing the new database data to be used for replacement.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
@@ -26,10 +26,10 @@ public interface ISnapshotService
Task ReplaceDatabaseAsync(Stream databaseStream, CancellationToken cancellationToken = default);
/// <summary>
/// Merges the provided snapshot stream into the current data store asynchronously.
/// Merges the provided snapshot stream into the current data store asynchronously.
/// </summary>
/// <param name="snapshotStream">A stream containing the snapshot data to be merged.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the merge operation.</param>
/// <returns>A task that represents the asynchronous merge operation.</returns>
Task MergeSnapshotAsync(Stream snapshotStream, CancellationToken cancellationToken = default);
}
}

30
src/ZB.MOM.WW.CBDDC.Core/Storage/ISnapshotable.cs
View File

@@ -7,24 +7,28 @@ namespace ZB.MOM.WW.CBDDC.Core.Storage;
public interface ISnapshotable<T>
{
/// <summary>
/// Asynchronously deletes the underlying data store and all of its contents.
/// Asynchronously deletes the underlying data store and all of its contents.
/// </summary>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the drop operation.</param>
/// <remarks>After calling this method, the data store and all stored data will be permanently removed.
/// This operation cannot be undone. Any further operations on the data store may result in errors.</remarks>
/// <remarks>
/// After calling this method, the data store and all stored data will be permanently removed.
/// This operation cannot be undone. Any further operations on the data store may result in errors.
/// </remarks>
/// <returns>A task that represents the asynchronous drop operation.</returns>
Task DropAsync(CancellationToken cancellationToken = default);
/// <summary>
/// Asynchronously exports a collection of items of type T.
/// Asynchronously exports a collection of items of type T.
/// </summary>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the export operation.</param>
/// <returns>A task that represents the asynchronous export operation. The task result contains an enumerable collection of
/// exported items of type T.</returns>
/// <returns>
/// A task that represents the asynchronous export operation. The task result contains an enumerable collection of
/// exported items of type T.
/// </returns>
Task<IEnumerable<T>> ExportAsync(CancellationToken cancellationToken = default);
/// <summary>
/// Imports the specified collection of items asynchronously.
/// Imports the specified collection of items asynchronously.
/// </summary>
/// <param name="items">The collection of items to import. Cannot be null. Each item will be processed in sequence.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the import operation.</param>
@@ -32,13 +36,15 @@ public interface ISnapshotable<T>
Task ImportAsync(IEnumerable<T> items, CancellationToken cancellationToken = default);
/// <summary>
/// Merges the specified collection of items into the target data store asynchronously.
/// Merges the specified collection of items into the target data store asynchronously.
/// </summary>
/// <remarks>If the operation is canceled via the provided cancellation token, the returned task will be
/// in a canceled state. The merge operation may update existing items or add new items, depending on the
/// implementation.</remarks>
/// <remarks>
/// If the operation is canceled via the provided cancellation token, the returned task will be
/// in a canceled state. The merge operation may update existing items or add new items, depending on the
/// implementation.
/// </remarks>
/// <param name="items">The collection of items to merge into the data store. Cannot be null.</param>
/// <param name="cancellationToken">A cancellation token that can be used to cancel the merge operation.</param>
/// <returns>A task that represents the asynchronous merge operation.</returns>
Task MergeAsync(IEnumerable<T> items, CancellationToken cancellationToken = default);
}
}

40
src/ZB.MOM.WW.CBDDC.Core/Storage/IVectorClockService.cs
View File

@@ -1,49 +1,49 @@
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Storage;
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Storage;
/// <summary>
/// Manages Vector Clock state for the local node.
/// Tracks the latest timestamp and hash per node for sync coordination.
/// Manages Vector Clock state for the local node.
/// Tracks the latest timestamp and hash per node for sync coordination.
/// </summary>
public interface IVectorClockService
{
/// <summary>
/// Indicates whether the cache has been populated with initial data.
/// Reset to false by <see cref="Invalidate"/>.
/// Indicates whether the cache has been populated with initial data.
/// Reset to false by <see cref="Invalidate" />.
/// </summary>
bool IsInitialized { get; set; }
/// <summary>
/// Updates the cache with a new OplogEntry's timestamp and hash.
/// Called by both DocumentStore (local CDC) and OplogStore (remote sync).
/// Updates the cache with a new OplogEntry's timestamp and hash.
/// Called by both DocumentStore (local CDC) and OplogStore (remote sync).
/// </summary>
/// <param name="entry">The oplog entry containing timestamp and hash data.</param>
void Update(OplogEntry entry);
/// <summary>
/// Returns the current Vector Clock built from cached node timestamps.
/// Returns the current Vector Clock built from cached node timestamps.
/// </summary>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
Task<VectorClock> GetVectorClockAsync(CancellationToken cancellationToken = default);
/// <summary>
/// Returns the latest known timestamp across all nodes.
/// Returns the latest known timestamp across all nodes.
/// </summary>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
Task<HlcTimestamp> GetLatestTimestampAsync(CancellationToken cancellationToken = default);
/// <summary>
/// Returns the last known hash for the specified node.
/// Returns null if the node is unknown.
/// Returns the last known hash for the specified node.
/// Returns null if the node is unknown.
/// </summary>
/// <param name="nodeId">The node identifier.</param>
string? GetLastHash(string nodeId);
/// <summary>
/// Updates the cache with a specific node's timestamp and hash.
/// Used for snapshot metadata fallback.
/// Updates the cache with a specific node's timestamp and hash.
/// Used for snapshot metadata fallback.
/// </summary>
/// <param name="nodeId">The node identifier.</param>
/// <param name="timestamp">The timestamp to store for the node.</param>
@@ -51,8 +51,8 @@ public interface IVectorClockService
void UpdateNode(string nodeId, HlcTimestamp timestamp, string hash);
/// <summary>
/// Clears the cache and resets <see cref="IsInitialized"/> to false,
/// forcing re-initialization on next access.
/// Clears the cache and resets <see cref="IsInitialized" /> to false,
/// forcing re-initialization on next access.
/// </summary>
void Invalidate();
}
}

47
src/ZB.MOM.WW.CBDDC.Core/Sync/IConflictResolver.cs
View File

@@ -1,21 +1,9 @@
using System.Text.Json;
using ZB.MOM.WW.CBDDC.Core;
namespace ZB.MOM.WW.CBDDC.Core.Sync;
namespace ZB.MOM.WW.CBDDC.Core.Sync;
public class ConflictResolutionResult
{
/// <summary>
/// Gets a value indicating whether the remote change should be applied.
/// </summary>
public bool ShouldApply { get; }
/// <summary>
/// Gets the merged document to apply when conflict resolution produced one.
/// </summary>
public Document? MergedDocument { get; }
/// <summary>
/// Initializes a new instance of the <see cref="ConflictResolutionResult"/> class.
/// Initializes a new instance of the <see cref="ConflictResolutionResult" /> class.
/// </summary>
/// <param name="shouldApply">Indicates whether the change should be applied.</param>
/// <param name="mergedDocument">The merged document produced by resolution, if any.</param>
@@ -26,25 +14,42 @@ public class ConflictResolutionResult
}
/// <summary>
/// Creates a result indicating that the resolved document should be applied.
/// Gets a value indicating whether the remote change should be applied.
/// </summary>
public bool ShouldApply { get; }
/// <summary>
/// Gets the merged document to apply when conflict resolution produced one.
/// </summary>
public Document? MergedDocument { get; }
/// <summary>
/// Creates a result indicating that the resolved document should be applied.
/// </summary>
/// <param name="document">The merged document to apply.</param>
/// <returns>A resolution result that applies the provided document.</returns>
public static ConflictResolutionResult Apply(Document document) => new(true, document);
public static ConflictResolutionResult Apply(Document document)
{
return new ConflictResolutionResult(true, document);
}
/// <summary>
/// Creates a result indicating that the remote change should be ignored.
/// Creates a result indicating that the remote change should be ignored.
/// </summary>
/// <returns>A resolution result that skips applying the remote change.</returns>
public static ConflictResolutionResult Ignore() => new(false, null);
public static ConflictResolutionResult Ignore()
{
return new ConflictResolutionResult(false, null);
}
}
public interface IConflictResolver
{
/// <summary>
/// Resolves a conflict between local state and a remote oplog entry.
/// Resolves a conflict between local state and a remote oplog entry.
/// </summary>
/// <param name="local">The local document state, if present.</param>
/// <param name="remote">The incoming remote oplog entry.</param>
/// <returns>The resolution outcome indicating whether and how to apply changes.</returns>
ConflictResolutionResult Resolve(Document? local, OplogEntry remote);
}
}

68
src/ZB.MOM.WW.CBDDC.Core/Sync/IOfflineQueue.cs
View File

@@ -1,40 +1,40 @@
using System;
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Sync
using System;
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Sync;
/// <summary>
/// Represents a queue for operations that should be executed when connectivity is restored.
/// </summary>
public interface IOfflineQueue
{
/// <summary>
/// Represents a queue for operations that should be executed when connectivity is restored.
/// Gets the number of pending operations in the queue.
/// </summary>
public interface IOfflineQueue
{
/// <summary>
/// Gets the number of pending operations in the queue.
/// </summary>
int Count { get; }
int Count { get; }
/// <summary>
/// Clears all pending operations from the queue.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Clear();
/// <summary>
/// Clears all pending operations from the queue.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Clear();
/// <summary>
/// Enqueues a pending operation.
/// </summary>
/// <param name="operation">The operation to enqueue.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Enqueue(PendingOperation operation);
/// <summary>
/// Enqueues a pending operation.
/// </summary>
/// <param name="operation">The operation to enqueue.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Enqueue(PendingOperation operation);
/// <summary>
/// Flushes the queue by executing each pending operation.
/// </summary>
/// <param name="executor">The delegate used to execute each operation.</param>
/// <param name="cancellationToken">A token used to cancel the flush operation.</param>
/// <returns>
/// A task that returns a tuple containing the number of successful and failed operations.
/// </returns>
Task<(int Successful, int Failed)> FlushAsync(Func<PendingOperation, Task> executor, CancellationToken cancellationToken = default);
}
}
/// <summary>
/// Flushes the queue by executing each pending operation.
/// </summary>
/// <param name="executor">The delegate used to execute each operation.</param>
/// <param name="cancellationToken">A token used to cancel the flush operation.</param>
/// <returns>
/// A task that returns a tuple containing the number of successful and failed operations.
/// </returns>
Task<(int Successful, int Failed)> FlushAsync(Func<PendingOperation, Task> executor,
CancellationToken cancellationToken = default);
}

31
src/ZB.MOM.WW.CBDDC.Core/Sync/LastWriteWinsConflictResolver.cs
View File

@@ -1,24 +1,22 @@
using System.Text.Json;
using ZB.MOM.WW.CBDDC.Core;
namespace ZB.MOM.WW.CBDDC.Core.Sync;
public class LastWriteWinsConflictResolver : IConflictResolver
{
/// <summary>
/// Resolves document conflicts by preferring the entry with the latest timestamp.
/// </summary>
/// <param name="local">The local document, if available.</param>
/// <param name="remote">The incoming remote oplog entry.</param>
/// <returns>The conflict resolution result indicating whether to apply or ignore the remote change.</returns>
public ConflictResolutionResult Resolve(Document? local, OplogEntry remote)
{
public class LastWriteWinsConflictResolver : IConflictResolver
{
/// <summary>
/// Resolves document conflicts by preferring the entry with the latest timestamp.
/// </summary>
/// <param name="local">The local document, if available.</param>
/// <param name="remote">The incoming remote oplog entry.</param>
/// <returns>The conflict resolution result indicating whether to apply or ignore the remote change.</returns>
public ConflictResolutionResult Resolve(Document? local, OplogEntry remote)
{
// If no local document exists, always apply remote change
if (local == null)
{
// Construct new document from oplog entry
var content = remote.Payload ?? default;
var newDoc = new Document(remote.Collection, remote.Key, content, remote.Timestamp, remote.Operation == OperationType.Delete);
var newDoc = new Document(remote.Collection, remote.Key, content, remote.Timestamp,
remote.Operation == OperationType.Delete);
return ConflictResolutionResult.Apply(newDoc);
}
@@ -27,11 +25,12 @@ public class LastWriteWinsConflictResolver : IConflictResolver
{
// Remote is newer, apply it
var content = remote.Payload ?? default;
var newDoc = new Document(remote.Collection, remote.Key, content, remote.Timestamp, remote.Operation == OperationType.Delete);
var newDoc = new Document(remote.Collection, remote.Key, content, remote.Timestamp,
remote.Operation == OperationType.Delete);
return ConflictResolutionResult.Apply(newDoc);
}
// Local is newer or equal, ignore remote
return ConflictResolutionResult.Ignore();
}
}
}

100
src/ZB.MOM.WW.CBDDC.Core/Sync/OfflineQueue.cs
View File

@@ -1,37 +1,38 @@
using ZB.MOM.WW.CBDDC.Core.Network;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using System;
using System.Collections.Generic;
using System.Linq;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.CBDDC.Core.Network;
namespace ZB.MOM.WW.CBDDC.Core.Sync;
/// <summary>
/// Queue for operations performed while offline.
/// Queue for operations performed while offline.
/// </summary>
public class OfflineQueue : IOfflineQueue
{
private readonly IPeerNodeConfigurationProvider _peerNodeConfigurationProvider;
private readonly Queue<PendingOperation> _queue = new();
private readonly ILogger<OfflineQueue> _logger;
private readonly object _lock = new();
/// <summary>
/// Initializes a new instance of the <see cref="OfflineQueue"/> class.
/// </summary>
/// <param name="peerNodeConfigurationProvider">The configuration provider used for queue limits.</param>
/// <param name="logger">The logger instance.</param>
public OfflineQueue(IPeerNodeConfigurationProvider peerNodeConfigurationProvider, ILogger<OfflineQueue>? logger = null)
{
_peerNodeConfigurationProvider = peerNodeConfigurationProvider;
_logger = logger ?? NullLogger<OfflineQueue>.Instance;
}
public class OfflineQueue : IOfflineQueue
{
private readonly object _lock = new();
private readonly ILogger<OfflineQueue> _logger;
private readonly IPeerNodeConfigurationProvider _peerNodeConfigurationProvider;
private readonly Queue<PendingOperation> _queue = new();
/// <summary>
/// Gets the number of pending operations.
/// Initializes a new instance of the <see cref="OfflineQueue" /> class.
/// </summary>
/// <param name="peerNodeConfigurationProvider">The configuration provider used for queue limits.</param>
/// <param name="logger">The logger instance.</param>
public OfflineQueue(IPeerNodeConfigurationProvider peerNodeConfigurationProvider,
ILogger<OfflineQueue>? logger = null)
{
_peerNodeConfigurationProvider = peerNodeConfigurationProvider;
_logger = logger ?? NullLogger<OfflineQueue>.Instance;
}
/// <summary>
/// Gets the number of pending operations.
/// </summary>
public int Count
{
@@ -44,15 +45,15 @@ public class OfflineQueue : IOfflineQueue
}
}
/// <summary>
/// Enqueues an operation for later execution.
/// </summary>
/// <param name="operation">The pending operation to enqueue.</param>
/// <returns>A task that represents the asynchronous enqueue operation.</returns>
public async Task Enqueue(PendingOperation operation)
{
var config = await _peerNodeConfigurationProvider.GetConfiguration();
lock (_lock)
/// <summary>
/// Enqueues an operation for later execution.
/// </summary>
/// <param name="operation">The pending operation to enqueue.</param>
/// <returns>A task that represents the asynchronous enqueue operation.</returns>
public async Task Enqueue(PendingOperation operation)
{
var config = await _peerNodeConfigurationProvider.GetConfiguration();
lock (_lock)
{
if (_queue.Count >= config.MaxQueueSize)
{
@@ -67,15 +68,16 @@ public class OfflineQueue : IOfflineQueue
}
}
/// <summary>
/// Flushes all pending operations.
/// </summary>
/// <param name="executor">The delegate that executes each pending operation.</param>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
/// <returns>A task whose result contains the number of successful and failed operations.</returns>
public async Task<(int Successful, int Failed)> FlushAsync(Func<PendingOperation, Task> executor, CancellationToken cancellationToken = default)
{
List<PendingOperation> operations;
/// <summary>
/// Flushes all pending operations.
/// </summary>
/// <param name="executor">The delegate that executes each pending operation.</param>
/// <param name="cancellationToken">A token used to cancel the operation.</param>
/// <returns>A task whose result contains the number of successful and failed operations.</returns>
public async Task<(int Successful, int Failed)> FlushAsync(Func<PendingOperation, Task> executor,
CancellationToken cancellationToken = default)
{
List<PendingOperation> operations;
lock (_lock)
{
@@ -91,11 +93,10 @@ public class OfflineQueue : IOfflineQueue
_logger.LogInformation("Flushing {Count} pending operations", operations.Count);
int successful = 0;
int failed = 0;
var successful = 0;
var failed = 0;
foreach (var op in operations)
{
try
{
await executor(op);
@@ -107,7 +108,6 @@ public class OfflineQueue : IOfflineQueue
_logger.LogError(ex, "Failed to execute pending {Type} operation for {Collection}:{Key}",
op.Type, op.Collection, op.Key);
}
}
_logger.LogInformation("Flush completed: {Successful} successful, {Failed} failed",
successful, failed);
@@ -116,15 +116,15 @@ public class OfflineQueue : IOfflineQueue
}
/// <summary>
/// Clears all pending operations.
/// Clears all pending operations.
/// </summary>
public async Task Clear()
{
lock (_lock)
{
var count = _queue.Count;
int count = _queue.Count;
_queue.Clear();
_logger.LogInformation("Cleared {Count} pending operations", count);
}
}
}
}

32
src/ZB.MOM.WW.CBDDC.Core/Sync/PendingOperation.cs
View File

@@ -1,32 +1,34 @@
using System;
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Core.Sync;
/// <summary>
/// Represents a pending operation to be executed when connection is restored.
/// </summary>
using System;
namespace ZB.MOM.WW.CBDDC.Core.Sync;
/// <summary>
/// Represents a pending operation to be executed when connection is restored.
/// </summary>
public class PendingOperation
{
/// <summary>
/// Gets or sets the operation type.
/// Gets or sets the operation type.
/// </summary>
public string Type { get; set; } = "";
/// <summary>
/// Gets or sets the collection targeted by the operation.
/// Gets or sets the collection targeted by the operation.
/// </summary>
public string Collection { get; set; } = "";
/// <summary>
/// Gets or sets the document key targeted by the operation.
/// Gets or sets the document key targeted by the operation.
/// </summary>
public string Key { get; set; } = "";
/// <summary>
/// Gets or sets the payload associated with the operation.
/// Gets or sets the payload associated with the operation.
/// </summary>
public object? Data { get; set; }
/// <summary>
/// Gets or sets the UTC time when the operation was queued.
/// Gets or sets the UTC time when the operation was queued.
/// </summary>
public DateTime QueuedAt { get; set; }
}
}

132
src/ZB.MOM.WW.CBDDC.Core/Sync/RecursiveNodeMergeConflictResolver.cs
View File

@@ -1,28 +1,27 @@
using System;
using System.Buffers;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;
namespace ZB.MOM.WW.CBDDC.Core.Sync;
/// <summary>
/// Resolves merge conflicts by recursively merging object and array nodes.
/// </summary>
public class RecursiveNodeMergeConflictResolver : IConflictResolver
{
/// <summary>
/// Resolves a conflict between a local document and a remote operation.
/// </summary>
/// <param name="local">The local document, or <see langword="null"/> if none exists.</param>
/// <param name="remote">The remote operation to apply.</param>
/// <returns>The conflict resolution result indicating whether and what to apply.</returns>
public ConflictResolutionResult Resolve(Document? local, OplogEntry remote)
{
if (local == null)
{
namespace ZB.MOM.WW.CBDDC.Core.Sync;
/// <summary>
/// Resolves merge conflicts by recursively merging object and array nodes.
/// </summary>
public class RecursiveNodeMergeConflictResolver : IConflictResolver
{
/// <summary>
/// Resolves a conflict between a local document and a remote operation.
/// </summary>
/// <param name="local">The local document, or <see langword="null" /> if none exists.</param>
/// <param name="remote">The remote operation to apply.</param>
/// <returns>The conflict resolution result indicating whether and what to apply.</returns>
public ConflictResolutionResult Resolve(Document? local, OplogEntry remote)
{
if (local == null)
{
var content = remote.Payload ?? default;
var newDoc = new Document(remote.Collection, remote.Key, content, remote.Timestamp, remote.Operation == OperationType.Delete);
var newDoc = new Document(remote.Collection, remote.Key, content, remote.Timestamp,
remote.Operation == OperationType.Delete);
return ConflictResolutionResult.Apply(newDoc);
}
@@ -33,6 +32,7 @@ public class RecursiveNodeMergeConflictResolver : IConflictResolver
var newDoc = new Document(remote.Collection, remote.Key, default, remote.Timestamp, true);
return ConflictResolutionResult.Apply(newDoc);
}
return ConflictResolutionResult.Ignore();
}
@@ -41,12 +41,14 @@ public class RecursiveNodeMergeConflictResolver : IConflictResolver
var localTs = local.UpdatedAt;
var remoteTs = remote.Timestamp;
if (localJson.ValueKind == JsonValueKind.Undefined) return ConflictResolutionResult.Apply(new Document(remote.Collection, remote.Key, remoteJson, remoteTs, false));
if (remoteJson.ValueKind == JsonValueKind.Undefined) return ConflictResolutionResult.Ignore();
// Optimization: Use ArrayBufferWriter (Net6.0) or MemoryStream (NS2.0)
// Utf8JsonWriter works with both, but ArrayBufferWriter is more efficient for high throughput.
if (localJson.ValueKind == JsonValueKind.Undefined)
return ConflictResolutionResult.Apply(new Document(remote.Collection, remote.Key, remoteJson, remoteTs,
false));
if (remoteJson.ValueKind == JsonValueKind.Undefined) return ConflictResolutionResult.Ignore();
// Optimization: Use ArrayBufferWriter (Net6.0) or MemoryStream (NS2.0)
// Utf8JsonWriter works with both, but ArrayBufferWriter is more efficient for high throughput.
JsonElement mergedDocJson;
#if NET6_0_OR_GREATER
@@ -55,7 +57,8 @@ public class RecursiveNodeMergeConflictResolver : IConflictResolver
{
MergeJson(writer, localJson, localTs, remoteJson, remoteTs);
}
mergedDocJson = JsonDocument.Parse(bufferWriter.WrittenMemory).RootElement;
mergedDocJson = JsonDocument.Parse(bufferWriter.WrittenMemory).RootElement;
#else
using (var ms = new MemoryStream())
{
@@ -67,13 +70,14 @@ public class RecursiveNodeMergeConflictResolver : IConflictResolver
mergedDocJson = JsonDocument.Parse(ms.ToArray()).RootElement;
}
#endif
var maxTimestamp = remoteTs.CompareTo(localTs) > 0 ? remoteTs : localTs;
var mergedDoc = new Document(remote.Collection, remote.Key, mergedDocJson, maxTimestamp, false);
return ConflictResolutionResult.Apply(mergedDoc);
}
private void MergeJson(Utf8JsonWriter writer, JsonElement local, HlcTimestamp localTs, JsonElement remote, HlcTimestamp remoteTs)
private void MergeJson(Utf8JsonWriter writer, JsonElement local, HlcTimestamp localTs, JsonElement remote,
HlcTimestamp remoteTs)
{
if (local.ValueKind != remote.ValueKind)
{
@@ -93,7 +97,7 @@ public class RecursiveNodeMergeConflictResolver : IConflictResolver
break;
default:
// Primitives
if (local.GetRawText() == remote.GetRawText())
if (local.GetRawText() == remote.GetRawText())
{
local.WriteTo(writer);
}
@@ -102,54 +106,51 @@ public class RecursiveNodeMergeConflictResolver : IConflictResolver
if (remoteTs.CompareTo(localTs) > 0) remote.WriteTo(writer);
else local.WriteTo(writer);
}
break;
}
}
private void MergeObjects(Utf8JsonWriter writer, JsonElement local, HlcTimestamp localTs, JsonElement remote, HlcTimestamp remoteTs)
private void MergeObjects(Utf8JsonWriter writer, JsonElement local, HlcTimestamp localTs, JsonElement remote,
HlcTimestamp remoteTs)
{
writer.WriteStartObject();
// We need to iterate keys. To avoid double iteration efficiently, we can use a dictionary for the UNION of keys.
// But populating a dictionary is effectively what we did before.
// Can we do better?
// Yes: Iterate Local, write merged/local. Track handled keys. Then iterate Remote, write remaining.
writer.WriteStartObject();
// We need to iterate keys. To avoid double iteration efficiently, we can use a dictionary for the UNION of keys.
// But populating a dictionary is effectively what we did before.
// Can we do better?
// Yes: Iterate Local, write merged/local. Track handled keys. Then iterate Remote, write remaining.
var processedKeys = new HashSet<string>();
foreach (var prop in local.EnumerateObject())
{
var key = prop.Name;
string key = prop.Name;
processedKeys.Add(key); // Mark as processed
writer.WritePropertyName(key);
if (remote.TryGetProperty(key, out var remoteVal))
{
// Collision -> Merge
MergeJson(writer, prop.Value, localTs, remoteVal, remoteTs);
}
else
{
// Only local
prop.Value.WriteTo(writer);
}
}
foreach (var prop in remote.EnumerateObject())
{
if (!processedKeys.Contains(prop.Name))
{
// New from remote
writer.WritePropertyName(prop.Name);
prop.Value.WriteTo(writer);
}
}
writer.WriteEndObject();
}
private void MergeArrays(Utf8JsonWriter writer, JsonElement local, HlcTimestamp localTs, JsonElement remote, HlcTimestamp remoteTs)
private void MergeArrays(Utf8JsonWriter writer, JsonElement local, HlcTimestamp localTs, JsonElement remote,
HlcTimestamp remoteTs)
{
// Heuristic check
bool localIsObj = HasObjects(local);
@@ -164,10 +165,10 @@ public class RecursiveNodeMergeConflictResolver : IConflictResolver
}
if (localIsObj != remoteIsObj)
{
// Mixed mistmatch LWW
if (remoteTs.CompareTo(localTs) > 0) remote.WriteTo(writer);
else local.WriteTo(writer);
{
// Mixed mistmatch LWW
if (remoteTs.CompareTo(localTs) > 0) remote.WriteTo(writer);
else local.WriteTo(writer);
return;
}
@@ -184,44 +185,36 @@ public class RecursiveNodeMergeConflictResolver : IConflictResolver
return;
}
writer.WriteStartArray();
// We want to write Union of items by ID.
// To preserve some semblance of order (or just determinism), we can iterate local IDs first, then remote new IDs.
// Or just use the dictionary values.
// NOTE: We cannot simply write to writer inside the map loop if we are creating a merged map.
// Let's iterate the union of keys similar to Objects.
writer.WriteStartArray();
// We want to write Union of items by ID.
// To preserve some semblance of order (or just determinism), we can iterate local IDs first, then remote new IDs.
// Or just use the dictionary values.
// NOTE: We cannot simply write to writer inside the map loop if we are creating a merged map.
// Let's iterate the union of keys similar to Objects.
var processedIds = new HashSet<string>();
// 1. Process Local Items (Merge or Write)
foreach (var kvp in localMap)
{
var id = kvp.Key;
string id = kvp.Key;
var localItem = kvp.Value;
processedIds.Add(id);
if (remoteMap.TryGetValue(id, out var remoteItem))
{
// Merge recursively
MergeJson(writer, localItem, localTs, remoteItem, remoteTs);
}
else
{
// Keep local item
localItem.WriteTo(writer);
}
}
// 2. Process New Remote Items
foreach (var kvp in remoteMap)
{
if (!processedIds.Contains(kvp.Key))
{
kvp.Value.WriteTo(writer);
}
}
writer.WriteEndArray();
}
@@ -249,6 +242,7 @@ public class RecursiveNodeMergeConflictResolver : IConflictResolver
map[id] = item;
}
return map;
}
}
}

220
src/ZB.MOM.WW.CBDDC.Core/VectorClock.cs
View File

@@ -5,86 +5,84 @@ using System.Linq;
namespace ZB.MOM.WW.CBDDC.Core;
/// <summary>
/// Represents a Vector Clock for tracking causality in a distributed system.
/// Maps NodeId -> HlcTimestamp to track the latest known state of each node.
/// Represents a Vector Clock for tracking causality in a distributed system.
/// Maps NodeId -> HlcTimestamp to track the latest known state of each node.
/// </summary>
public class VectorClock
{
private readonly Dictionary<string, HlcTimestamp> _clock;
/// <summary>
/// Initializes a new empty vector clock.
/// </summary>
public VectorClock()
{
_clock = new Dictionary<string, HlcTimestamp>(StringComparer.Ordinal);
}
/// <summary>
/// Initializes a new vector clock from an existing clock state.
/// </summary>
/// <param name="clock">The clock state to copy.</param>
public VectorClock(Dictionary<string, HlcTimestamp> clock)
{
_clock = new Dictionary<string, HlcTimestamp>(clock, StringComparer.Ordinal);
}
public class VectorClock
{
private readonly Dictionary<string, HlcTimestamp> _clock;
/// <summary>
/// Gets all node IDs in this vector clock.
/// Initializes a new empty vector clock.
/// </summary>
public VectorClock()
{
_clock = new Dictionary<string, HlcTimestamp>(StringComparer.Ordinal);
}
/// <summary>
/// Initializes a new vector clock from an existing clock state.
/// </summary>
/// <param name="clock">The clock state to copy.</param>
public VectorClock(Dictionary<string, HlcTimestamp> clock)
{
_clock = new Dictionary<string, HlcTimestamp>(clock, StringComparer.Ordinal);
}
/// <summary>
/// Gets all node IDs in this vector clock.
/// </summary>
public IEnumerable<string> NodeIds => _clock.Keys;
/// <summary>
/// Gets the timestamp for a specific node, or default if not present.
/// </summary>
/// <param name="nodeId">The node identifier.</param>
public HlcTimestamp GetTimestamp(string nodeId)
{
return _clock.TryGetValue(nodeId, out var ts) ? ts : default;
}
/// <summary>
/// Gets the timestamp for a specific node, or default if not present.
/// </summary>
/// <param name="nodeId">The node identifier.</param>
public HlcTimestamp GetTimestamp(string nodeId)
{
return _clock.TryGetValue(nodeId, out var ts) ? ts : default;
}
/// <summary>
/// Sets or updates the timestamp for a specific node.
/// </summary>
/// <param name="nodeId">The node identifier.</param>
/// <param name="timestamp">The timestamp to set.</param>
public void SetTimestamp(string nodeId, HlcTimestamp timestamp)
{
_clock[nodeId] = timestamp;
}
/// <summary>
/// Sets or updates the timestamp for a specific node.
/// </summary>
/// <param name="nodeId">The node identifier.</param>
/// <param name="timestamp">The timestamp to set.</param>
public void SetTimestamp(string nodeId, HlcTimestamp timestamp)
{
_clock[nodeId] = timestamp;
}
/// <summary>
/// Merges another vector clock into this one, taking the maximum timestamp for each node.
/// </summary>
/// <param name="other">The vector clock to merge from.</param>
public void Merge(VectorClock other)
{
foreach (var nodeId in other.NodeIds)
{
/// <summary>
/// Merges another vector clock into this one, taking the maximum timestamp for each node.
/// </summary>
/// <param name="other">The vector clock to merge from.</param>
public void Merge(VectorClock other)
{
foreach (string nodeId in other.NodeIds)
{
var otherTs = other.GetTimestamp(nodeId);
if (!_clock.TryGetValue(nodeId, out var currentTs) || otherTs.CompareTo(currentTs) > 0)
{
_clock[nodeId] = otherTs;
}
}
}
/// <summary>
/// Compares this vector clock with another to determine causality.
/// Returns:
/// - Positive: This is strictly ahead (dominates other)
/// - Negative: Other is strictly ahead (other dominates this)
/// - Zero: Concurrent (neither dominates)
/// </summary>
/// <param name="other">The vector clock to compare with.</param>
public CausalityRelation CompareTo(VectorClock other)
{
bool thisAhead = false;
bool otherAhead = false;
/// Compares this vector clock with another to determine causality.
/// Returns:
/// - Positive: This is strictly ahead (dominates other)
/// - Negative: Other is strictly ahead (other dominates this)
/// - Zero: Concurrent (neither dominates)
/// </summary>
/// <param name="other">The vector clock to compare with.</param>
public CausalityRelation CompareTo(VectorClock other)
{
var thisAhead = false;
var otherAhead = false;
var allNodes = new HashSet<string>(_clock.Keys.Union(other._clock.Keys), StringComparer.Ordinal);
foreach (var nodeId in allNodes)
foreach (string nodeId in allNodes)
{
var thisTs = GetTimestamp(nodeId);
var otherTs = other.GetTimestamp(nodeId);
@@ -92,19 +90,11 @@ public class VectorClock
int cmp = thisTs.CompareTo(otherTs);
if (cmp > 0)
{
thisAhead = true;
}
else if (cmp < 0)
{
otherAhead = true;
}
else if (cmp < 0) otherAhead = true;
// Early exit if concurrent
if (thisAhead && otherAhead)
{
return CausalityRelation.Concurrent;
}
if (thisAhead && otherAhead) return CausalityRelation.Concurrent;
}
if (thisAhead && !otherAhead)
@@ -115,65 +105,56 @@ public class VectorClock
return CausalityRelation.Equal;
}
/// <summary>
/// Determines which nodes have updates that this vector clock doesn't have.
/// Returns node IDs where the other vector clock is ahead.
/// </summary>
/// <param name="other">The vector clock to compare against.</param>
public IEnumerable<string> GetNodesWithUpdates(VectorClock other)
{
var allNodes = new HashSet<string>(_clock.Keys, StringComparer.Ordinal);
foreach (var nodeId in other._clock.Keys)
{
allNodes.Add(nodeId);
}
/// <summary>
/// Determines which nodes have updates that this vector clock doesn't have.
/// Returns node IDs where the other vector clock is ahead.
/// </summary>
/// <param name="other">The vector clock to compare against.</param>
public IEnumerable<string> GetNodesWithUpdates(VectorClock other)
{
var allNodes = new HashSet<string>(_clock.Keys, StringComparer.Ordinal);
foreach (string nodeId in other._clock.Keys) allNodes.Add(nodeId);
foreach (var nodeId in allNodes)
foreach (string nodeId in allNodes)
{
var thisTs = GetTimestamp(nodeId);
var otherTs = other.GetTimestamp(nodeId);
if (otherTs.CompareTo(thisTs) > 0)
{
yield return nodeId;
}
}
}
/// <summary>
/// Determines which nodes have updates that the other vector clock doesn't have.
/// Returns node IDs where this vector clock is ahead.
/// </summary>
/// <param name="other">The vector clock to compare against.</param>
public IEnumerable<string> GetNodesToPush(VectorClock other)
{
var allNodes = new HashSet<string>(_clock.Keys.Union(other._clock.Keys), StringComparer.Ordinal);
foreach (var nodeId in allNodes)
{
var thisTs = GetTimestamp(nodeId);
var otherTs = other.GetTimestamp(nodeId);
if (thisTs.CompareTo(otherTs) > 0)
{
yield return nodeId;
}
if (otherTs.CompareTo(thisTs) > 0) yield return nodeId;
}
}
/// <summary>
/// Creates a copy of this vector clock.
/// Determines which nodes have updates that the other vector clock doesn't have.
/// Returns node IDs where this vector clock is ahead.
/// </summary>
/// <param name="other">The vector clock to compare against.</param>
public IEnumerable<string> GetNodesToPush(VectorClock other)
{
var allNodes = new HashSet<string>(_clock.Keys.Union(other._clock.Keys), StringComparer.Ordinal);
foreach (string nodeId in allNodes)
{
var thisTs = GetTimestamp(nodeId);
var otherTs = other.GetTimestamp(nodeId);
if (thisTs.CompareTo(otherTs) > 0) yield return nodeId;
}
}
/// <summary>
/// Creates a copy of this vector clock.
/// </summary>
public VectorClock Clone()
{
return new VectorClock(new Dictionary<string, HlcTimestamp>(_clock, StringComparer.Ordinal));
}
/// <inheritdoc />
public override string ToString()
{
if (_clock.Count == 0)
return "{}";
/// <inheritdoc />
public override string ToString()
{
if (_clock.Count == 0)
return "{}";
var entries = _clock.Select(kvp => $"{kvp.Key}:{kvp.Value}");
return "{" + string.Join(", ", entries) + "}";
@@ -181,16 +162,19 @@ public class VectorClock
}
/// <summary>
/// Represents the causality relationship between two vector clocks.
/// Represents the causality relationship between two vector clocks.
/// </summary>
public enum CausalityRelation
{
/// <summary>Both vector clocks are equal.</summary>
Equal,
/// <summary>This vector clock is strictly ahead (dominates).</summary>
StrictlyAhead,
/// <summary>This vector clock is strictly behind (dominated).</summary>
StrictlyBehind,
/// <summary>Vector clocks are concurrent (neither dominates).</summary>
Concurrent
}
}

56
src/ZB.MOM.WW.CBDDC.Core/ZB.MOM.WW.CBDDC.Core.csproj
View File

@@ -1,33 +1,33 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<AssemblyName>ZB.MOM.WW.CBDDC.Core</AssemblyName>
<RootNamespace>ZB.MOM.WW.CBDDC.Core</RootNamespace>
<PackageId>ZB.MOM.WW.CBDDC.Core</PackageId>
<TargetFramework>net10.0</TargetFramework>
<LangVersion>latest</LangVersion>
<Nullable>enable</Nullable>
<Version>1.0.3</Version>
<Authors>MrDevRobot</Authors>
<Description>Core abstractions and logic for CBDDC, a lightweight P2P mesh database.</Description>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageTags>p2p;mesh;database;gossip;cbddc;lan;offline-first;distributed</PackageTags>
<PackageProjectUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</PackageProjectUrl>
<RepositoryUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup>
<PropertyGroup>
<AssemblyName>ZB.MOM.WW.CBDDC.Core</AssemblyName>
<RootNamespace>ZB.MOM.WW.CBDDC.Core</RootNamespace>
<PackageId>ZB.MOM.WW.CBDDC.Core</PackageId>
<TargetFramework>net10.0</TargetFramework>
<LangVersion>latest</LangVersion>
<Nullable>enable</Nullable>
<Version>1.0.3</Version>
<Authors>MrDevRobot</Authors>
<Description>Core abstractions and logic for CBDDC, a lightweight P2P mesh database.</Description>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageTags>p2p;mesh;database;gossip;cbddc;lan;offline-first;distributed</PackageTags>
<PackageProjectUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</PackageProjectUrl>
<RepositoryUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup>
<ItemGroup>
<None Include="README.md" Pack="true" PackagePath="\" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" />
</ItemGroup>
<ItemGroup>
<Folder Include="Storage\Events\" />
</ItemGroup>
<ItemGroup>
<None Include="README.md" Pack="true" PackagePath="\"/>
</ItemGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0"/>
</ItemGroup>
<ItemGroup>
<Folder Include="Storage\Events\"/>
</ItemGroup>
</Project>

27
src/ZB.MOM.WW.CBDDC.Hosting/CBDDCHostingExtensions.cs
View File

@@ -1,22 +1,22 @@
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Diagnostics.HealthChecks;
using Microsoft.Extensions.Hosting;
using ZB.MOM.WW.CBDDC.Hosting.Configuration;
using ZB.MOM.WW.CBDDC.Hosting.HealthChecks;
using ZB.MOM.WW.CBDDC.Hosting.HostedServices;
using ZB.MOM.WW.CBDDC.Hosting.Services;
using ZB.MOM.WW.CBDDC.Network;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Diagnostics.HealthChecks;
using Microsoft.Extensions.Hosting;
namespace ZB.MOM.WW.CBDDC.Hosting;
/// <summary>
/// Extension methods for configuring CBDDC in ASP.NET Core applications.
/// Extension methods for configuring CBDDC in ASP.NET Core applications.
/// </summary>
public static class CBDDCHostingExtensions
{
/// <summary>
/// Adds CBDDC ASP.NET integration with the specified configuration.
/// Adds CBDDC ASP.NET integration with the specified configuration.
/// </summary>
/// <param name="services">The service collection.</param>
/// <param name="configure">Action to configure CBDDC options.</param>
@@ -43,7 +43,7 @@ public static class CBDDCHostingExtensions
}
/// <summary>
/// Adds CBDDC ASP.NET integration for single-cluster mode.
/// Adds CBDDC ASP.NET integration for single-cluster mode.
/// </summary>
/// <param name="services">The service collection.</param>
/// <param name="configure">Action to configure single-cluster options.</param>
@@ -51,10 +51,7 @@ public static class CBDDCHostingExtensions
this IServiceCollection services,
Action<ClusterOptions>? configure = null)
{
return services.AddCBDDCHosting(options =>
{
configure?.Invoke(options.Cluster);
});
return services.AddCBDDCHosting(options => { configure?.Invoke(options.Cluster); });
}
private static void RegisterSingleClusterServices(
@@ -81,12 +78,10 @@ public static class CBDDCHostingExtensions
{
// Health checks
if (options.EnableHealthChecks)
{
services.AddHealthChecks()
.AddCheck<CBDDCHealthCheck>(
"cbddc",
failureStatus: HealthStatus.Unhealthy,
tags: new[] { "db", "ready" });
}
HealthStatus.Unhealthy,
new[] { "db", "ready" });
}
}
}

10
src/ZB.MOM.WW.CBDDC.Hosting/Configuration/CBDDCHostingOptions.cs
View File

@@ -1,18 +1,18 @@
namespace ZB.MOM.WW.CBDDC.Hosting.Configuration;
/// <summary>
/// Configuration options for CBDDC ASP.NET integration.
/// Configuration options for CBDDC ASP.NET integration.
/// </summary>
public class CBDDCHostingOptions
{
/// <summary>
/// Gets or sets the cluster configuration.
/// Gets or sets the cluster configuration.
/// </summary>
public ClusterOptions Cluster { get; set; } = new();
/// <summary>
/// Gets or sets whether to enable health checks.
/// Default: true
/// Gets or sets whether to enable health checks.
/// Default: true
/// </summary>
public bool EnableHealthChecks { get; set; } = true;
}
}

29
src/ZB.MOM.WW.CBDDC.Hosting/Configuration/ClusterOptions.cs
View File

@@ -1,40 +1,39 @@
using System;
namespace ZB.MOM.WW.CBDDC.Hosting.Configuration;
/// <summary>
/// Configuration options for cluster mode.
/// Configuration options for cluster mode.
/// </summary>
public class ClusterOptions
{
/// <summary>
/// Gets or sets the node identifier for this instance.
/// Gets or sets the node identifier for this instance.
/// </summary>
public string NodeId { get; set; } = Environment.MachineName;
/// <summary>
/// Gets or sets the TCP port for sync operations.
/// Default: 5001
/// Gets or sets the TCP port for sync operations.
/// Default: 5001
/// </summary>
public int TcpPort { get; set; } = 5001;
/// <summary>
/// Gets or sets whether to enable UDP discovery.
/// Default: false (disabled in server mode)
/// Gets or sets whether to enable UDP discovery.
/// Default: false (disabled in server mode)
/// </summary>
public bool EnableUdpDiscovery { get; set; } = false;
/// <summary>
/// Gets or sets the lag threshold (in milliseconds) used to determine when a tracked peer is considered lagging.
/// Peers above this threshold degrade health status.
/// Default: 30,000 ms.
/// Gets or sets the lag threshold (in milliseconds) used to determine when a tracked peer is considered lagging.
/// Peers above this threshold degrade health status.
/// Default: 30,000 ms.
/// </summary>
public long PeerConfirmationLagThresholdMs { get; set; } = 30_000;
/// <summary>
/// Gets or sets the critical lag threshold (in milliseconds) used to determine when a tracked peer causes unhealthy status.
/// Peers above this threshold mark health as unhealthy.
/// Default: 120,000 ms.
/// Gets or sets the critical lag threshold (in milliseconds) used to determine when a tracked peer causes unhealthy
/// status.
/// Peers above this threshold mark health as unhealthy.
/// Default: 120,000 ms.
/// </summary>
public long PeerConfirmationCriticalLagThresholdMs { get; set; } = 120_000;
}
}

56
src/ZB.MOM.WW.CBDDC.Hosting/HealthChecks/CBDDCHealthCheck.cs
View File

@@ -1,8 +1,3 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Diagnostics.HealthChecks;
using ZB.MOM.WW.CBDDC.Core.Storage;
using ZB.MOM.WW.CBDDC.Hosting.Configuration;
@@ -10,17 +5,17 @@ using ZB.MOM.WW.CBDDC.Hosting.Configuration;
namespace ZB.MOM.WW.CBDDC.Hosting.HealthChecks;
/// <summary>
/// Health check for CBDDC persistence layer.
/// Verifies that the database connection is healthy.
/// Health check for CBDDC persistence layer.
/// Verifies that the database connection is healthy.
/// </summary>
public class CBDDCHealthCheck : IHealthCheck
{
private readonly IOplogStore _oplogStore;
private readonly IPeerOplogConfirmationStore _peerOplogConfirmationStore;
private readonly CBDDCHostingOptions _options;
private readonly IPeerOplogConfirmationStore _peerOplogConfirmationStore;
/// <summary>
/// Initializes a new instance of the <see cref="CBDDCHealthCheck"/> class.
/// Initializes a new instance of the <see cref="CBDDCHealthCheck" /> class.
/// </summary>
/// <param name="oplogStore">The oplog store used to verify persistence health.</param>
/// <param name="peerOplogConfirmationStore">The peer confirmation store used for confirmation lag health checks.</param>
@@ -31,16 +26,17 @@ public class CBDDCHealthCheck : IHealthCheck
CBDDCHostingOptions options)
{
_oplogStore = oplogStore ?? throw new ArgumentNullException(nameof(oplogStore));
_peerOplogConfirmationStore = peerOplogConfirmationStore ?? throw new ArgumentNullException(nameof(peerOplogConfirmationStore));
_peerOplogConfirmationStore = peerOplogConfirmationStore ??
throw new ArgumentNullException(nameof(peerOplogConfirmationStore));
_options = options ?? throw new ArgumentNullException(nameof(options));
}
/// <summary>
/// Performs a health check against the CBDDC persistence layer.
/// Performs a health check against the CBDDC persistence layer.
/// </summary>
/// <param name="context">The health check execution context.</param>
/// <param name="cancellationToken">A token used to cancel the health check.</param>
/// <returns>A <see cref="HealthCheckResult"/> describing the health status.</returns>
/// <returns>A <see cref="HealthCheckResult" /> describing the health status.</returns>
public async Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context,
CancellationToken cancellationToken = default)
@@ -58,15 +54,18 @@ public class CBDDCHealthCheck : IHealthCheck
var peersWithNoConfirmation = new List<string>();
var laggingPeers = new List<string>();
var criticalLaggingPeers = new List<string>();
var lastSuccessfulConfirmationUpdateByPeer = new Dictionary<string, DateTimeOffset?>(StringComparer.Ordinal);
var lastSuccessfulConfirmationUpdateByPeer =
new Dictionary<string, DateTimeOffset?>(StringComparer.Ordinal);
var maxLagMs = 0L;
var lagThresholdMs = Math.Max(0, _options.Cluster.PeerConfirmationLagThresholdMs);
var criticalLagThresholdMs = Math.Max(lagThresholdMs, _options.Cluster.PeerConfirmationCriticalLagThresholdMs);
long lagThresholdMs = Math.Max(0, _options.Cluster.PeerConfirmationLagThresholdMs);
long criticalLagThresholdMs =
Math.Max(lagThresholdMs, _options.Cluster.PeerConfirmationCriticalLagThresholdMs);
foreach (var peerNodeId in trackedPeers)
foreach (string peerNodeId in trackedPeers)
{
var confirmations = (await _peerOplogConfirmationStore.GetConfirmationsForPeerAsync(peerNodeId, cancellationToken))
var confirmations =
(await _peerOplogConfirmationStore.GetConfirmationsForPeerAsync(peerNodeId, cancellationToken))
.Where(confirmation => confirmation.IsActive)
.ToList();
@@ -83,19 +82,14 @@ public class CBDDCHealthCheck : IHealthCheck
.ThenBy(confirmation => confirmation.ConfirmedLogic)
.First();
var lagMs = Math.Max(0, localHead.PhysicalTime - oldestConfirmation.ConfirmedWall);
long lagMs = Math.Max(0, localHead.PhysicalTime - oldestConfirmation.ConfirmedWall);
maxLagMs = Math.Max(maxLagMs, lagMs);
lastSuccessfulConfirmationUpdateByPeer[peerNodeId] = confirmations.Max(confirmation => confirmation.LastConfirmedUtc);
lastSuccessfulConfirmationUpdateByPeer[peerNodeId] =
confirmations.Max(confirmation => confirmation.LastConfirmedUtc);
if (lagMs > lagThresholdMs)
{
laggingPeers.Add(peerNodeId);
}
if (lagMs > lagThresholdMs) laggingPeers.Add(peerNodeId);
if (lagMs > criticalLagThresholdMs)
{
criticalLaggingPeers.Add(peerNodeId);
}
if (lagMs > criticalLagThresholdMs) criticalLaggingPeers.Add(peerNodeId);
}
var payload = new Dictionary<string, object>
@@ -108,18 +102,14 @@ public class CBDDCHealthCheck : IHealthCheck
};
if (criticalLaggingPeers.Count > 0)
{
return HealthCheckResult.Unhealthy(
$"CBDDC is unhealthy. Critical lag detected for {criticalLaggingPeers.Count} tracked peer(s).",
data: payload);
}
if (peersWithNoConfirmation.Count > 0 || laggingPeers.Count > 0)
{
return HealthCheckResult.Degraded(
$"CBDDC is degraded. Lagging peers: {laggingPeers.Count}, unconfirmed peers: {peersWithNoConfirmation.Count}.",
data: payload);
}
return HealthCheckResult.Healthy(
$"CBDDC is healthy. Latest timestamp: {localHead.PhysicalTime}.",
@@ -129,7 +119,7 @@ public class CBDDCHealthCheck : IHealthCheck
{
return HealthCheckResult.Unhealthy(
"CBDDC persistence layer is unavailable",
exception: ex);
ex);
}
}
}
}

12
src/ZB.MOM.WW.CBDDC.Hosting/HostedServices/DiscoveryServiceHostedService.cs
View File

@@ -1,5 +1,3 @@
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Serilog.Context;
@@ -8,7 +6,7 @@ using ZB.MOM.WW.CBDDC.Network;
namespace ZB.MOM.WW.CBDDC.Hosting.HostedServices;
/// <summary>
/// Hosted service that manages the lifecycle of the discovery service.
/// Hosted service that manages the lifecycle of the discovery service.
/// </summary>
public class DiscoveryServiceHostedService : IHostedService
{
@@ -16,7 +14,7 @@ public class DiscoveryServiceHostedService : IHostedService
private readonly ILogger<DiscoveryServiceHostedService> _logger;
/// <summary>
/// Initializes a new instance of the <see cref="DiscoveryServiceHostedService"/> class.
/// Initializes a new instance of the <see cref="DiscoveryServiceHostedService" /> class.
/// </summary>
/// <param name="discoveryService">The discovery service to manage.</param>
/// <param name="logger">The logger used for service lifecycle events.</param>
@@ -29,7 +27,7 @@ public class DiscoveryServiceHostedService : IHostedService
}
/// <summary>
/// Starts the discovery service.
/// Starts the discovery service.
/// </summary>
/// <param name="cancellationToken">A token used to cancel the startup operation.</param>
/// <returns>A task that represents the asynchronous start operation.</returns>
@@ -45,7 +43,7 @@ public class DiscoveryServiceHostedService : IHostedService
}
/// <summary>
/// Stops the discovery service.
/// Stops the discovery service.
/// </summary>
/// <param name="cancellationToken">A token used to cancel the shutdown operation.</param>
/// <returns>A task that represents the asynchronous stop operation.</returns>
@@ -59,4 +57,4 @@ public class DiscoveryServiceHostedService : IHostedService
await _discoveryService.Stop();
_logger.LogInformation("Discovery Service stopped");
}
}
}

14
src/ZB.MOM.WW.CBDDC.Hosting/HostedServices/TcpSyncServerHostedService.cs
View File

@@ -1,5 +1,3 @@
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Serilog.Context;
@@ -8,15 +6,15 @@ using ZB.MOM.WW.CBDDC.Network;
namespace ZB.MOM.WW.CBDDC.Hosting.HostedServices;
/// <summary>
/// Hosted service that manages the lifecycle of the TCP sync server.
/// Hosted service that manages the lifecycle of the TCP sync server.
/// </summary>
public class TcpSyncServerHostedService : IHostedService
{
private readonly ISyncServer _syncServer;
private readonly ILogger<TcpSyncServerHostedService> _logger;
private readonly ISyncServer _syncServer;
/// <summary>
/// Initializes a new instance of the <see cref="TcpSyncServerHostedService"/> class.
/// Initializes a new instance of the <see cref="TcpSyncServerHostedService" /> class.
/// </summary>
/// <param name="syncServer">The sync server to start and stop.</param>
/// <param name="logger">The logger instance.</param>
@@ -29,7 +27,7 @@ public class TcpSyncServerHostedService : IHostedService
}
/// <summary>
/// Starts the TCP sync server.
/// Starts the TCP sync server.
/// </summary>
/// <param name="cancellationToken">A token used to cancel startup.</param>
public async Task StartAsync(CancellationToken cancellationToken)
@@ -44,7 +42,7 @@ public class TcpSyncServerHostedService : IHostedService
}
/// <summary>
/// Stops the TCP sync server.
/// Stops the TCP sync server.
/// </summary>
/// <param name="cancellationToken">A token used to cancel shutdown.</param>
public async Task StopAsync(CancellationToken cancellationToken)
@@ -57,4 +55,4 @@ public class TcpSyncServerHostedService : IHostedService
await _syncServer.Stop();
_logger.LogInformation("TCP Sync Server stopped");
}
}
}

13
src/ZB.MOM.WW.CBDDC.Hosting/README.md
View File

@@ -41,6 +41,7 @@ app.Run();
## Health Checks
CBDDC registers health checks that verify:
- Database connectivity
- Latest timestamp retrieval
@@ -53,6 +54,7 @@ curl http://localhost:5000/health
### Cluster
Best for:
- Dedicated database servers
- Simple deployments
- Development/testing environments
@@ -60,6 +62,7 @@ Best for:
## Server Behavior
CBDDC servers operate in respond-only mode:
- Accept incoming sync connections
- Respond to sync requests
- Do not initiate outbound sync
@@ -69,11 +72,11 @@ CBDDC servers operate in respond-only mode:
### ClusterOptions
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| NodeId | string | MachineName | Unique node identifier |
| TcpPort | int | 5001 | TCP port for sync |
| EnableUdpDiscovery | bool | false | Enable UDP discovery |
| Property | Type | Default | Description |
|--------------------|--------|-------------|------------------------|
| NodeId | string | MachineName | Unique node identifier |
| TcpPort | int | 5001 | TCP port for sync |
| EnableUdpDiscovery | bool | false | Enable UDP discovery |
## Production Checklist

20
src/ZB.MOM.WW.CBDDC.Hosting/Services/NoOpDiscoveryService.cs
View File

@@ -1,5 +1,3 @@
using System;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using Serilog.Context;
@@ -9,24 +7,24 @@ using ZB.MOM.WW.CBDDC.Network;
namespace ZB.MOM.WW.CBDDC.Hosting.Services;
/// <summary>
/// No-op implementation of IDiscoveryService for server scenarios.
/// Does not perform UDP broadcast discovery - relies on explicit peer configuration.
/// No-op implementation of IDiscoveryService for server scenarios.
/// Does not perform UDP broadcast discovery - relies on explicit peer configuration.
/// </summary>
public class NoOpDiscoveryService : IDiscoveryService
{
private readonly ILogger<NoOpDiscoveryService> _logger;
/// <summary>
/// Initializes a new instance of the <see cref="NoOpDiscoveryService"/> class.
/// Initializes a new instance of the <see cref="NoOpDiscoveryService" /> class.
/// </summary>
/// <param name="logger">The logger instance to use, or <see langword="null"/> to use a no-op logger.</param>
/// <param name="logger">The logger instance to use, or <see langword="null" /> to use a no-op logger.</param>
public NoOpDiscoveryService(ILogger<NoOpDiscoveryService>? logger = null)
{
_logger = logger ?? NullLogger<NoOpDiscoveryService>.Instance;
}
/// <summary>
/// Gets the currently active peers.
/// Gets the currently active peers.
/// </summary>
/// <returns>An empty sequence because discovery is disabled.</returns>
public IEnumerable<PeerNode> GetActivePeers()
@@ -35,7 +33,7 @@ public class NoOpDiscoveryService : IDiscoveryService
}
/// <summary>
/// Starts the discovery service.
/// Starts the discovery service.
/// </summary>
/// <returns>A completed task.</returns>
public Task Start()
@@ -49,7 +47,7 @@ public class NoOpDiscoveryService : IDiscoveryService
}
/// <summary>
/// Stops the discovery service.
/// Stops the discovery service.
/// </summary>
/// <returns>A completed task.</returns>
public Task Stop()
@@ -63,10 +61,10 @@ public class NoOpDiscoveryService : IDiscoveryService
}
/// <summary>
/// Releases resources used by this instance.
/// Releases resources used by this instance.
/// </summary>
public void Dispose()
{
_logger.LogDebug("NoOpDiscoveryService disposed");
}
}
}

17
src/ZB.MOM.WW.CBDDC.Hosting/Services/NoOpSyncOrchestrator.cs
View File

@@ -1,4 +1,3 @@
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using Serilog.Context;
@@ -7,24 +6,24 @@ using ZB.MOM.WW.CBDDC.Network;
namespace ZB.MOM.WW.CBDDC.Hosting.Services;
/// <summary>
/// No-op implementation of ISyncOrchestrator for server scenarios.
/// Does not initiate outbound sync - only responds to incoming sync requests.
/// No-op implementation of ISyncOrchestrator for server scenarios.
/// Does not initiate outbound sync - only responds to incoming sync requests.
/// </summary>
public class NoOpSyncOrchestrator : ISyncOrchestrator
{
private readonly ILogger<NoOpSyncOrchestrator> _logger;
/// <summary>
/// Initializes a new instance of the <see cref="NoOpSyncOrchestrator"/> class.
/// Initializes a new instance of the <see cref="NoOpSyncOrchestrator" /> class.
/// </summary>
/// <param name="logger">The logger instance to use, or <see langword="null"/> for a no-op logger.</param>
/// <param name="logger">The logger instance to use, or <see langword="null" /> for a no-op logger.</param>
public NoOpSyncOrchestrator(ILogger<NoOpSyncOrchestrator>? logger = null)
{
_logger = logger ?? NullLogger<NoOpSyncOrchestrator>.Instance;
}
/// <summary>
/// Starts the orchestrator lifecycle.
/// Starts the orchestrator lifecycle.
/// </summary>
/// <returns>A completed task.</returns>
public Task Start()
@@ -38,7 +37,7 @@ public class NoOpSyncOrchestrator : ISyncOrchestrator
}
/// <summary>
/// Stops the orchestrator lifecycle.
/// Stops the orchestrator lifecycle.
/// </summary>
/// <returns>A completed task.</returns>
public Task Stop()
@@ -52,10 +51,10 @@ public class NoOpSyncOrchestrator : ISyncOrchestrator
}
/// <summary>
/// Releases resources used by the orchestrator.
/// Releases resources used by the orchestrator.
/// </summary>
public void Dispose()
{
_logger.LogDebug("NoOpSyncOrchestrator disposed");
}
}
}

60
src/ZB.MOM.WW.CBDDC.Hosting/ZB.MOM.WW.CBDDC.Hosting.csproj
View File

@@ -1,37 +1,37 @@
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<ProjectReference Include="..\ZB.MOM.WW.CBDDC.Network\ZB.MOM.WW.CBDDC.Network.csproj" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\ZB.MOM.WW.CBDDC.Network\ZB.MOM.WW.CBDDC.Network.csproj"/>
</ItemGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" />
<PackageReference Include="Serilog" Version="4.2.0" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="8.0.0"/>
<PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="8.0.0"/>
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0"/>
<PackageReference Include="Serilog" Version="4.2.0"/>
</ItemGroup>
<PropertyGroup>
<AssemblyName>ZB.MOM.WW.CBDDC.Hosting</AssemblyName>
<RootNamespace>ZB.MOM.WW.CBDDC.Hosting</RootNamespace>
<PackageId>ZB.MOM.WW.CBDDC.Hosting</PackageId>
<TargetFramework>net10.0</TargetFramework>
<LangVersion>latest</LangVersion>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<Version>1.0.3</Version>
<Authors>MrDevRobot</Authors>
<Description>ASP.NET Core integration for CBDDC with health checks and hosted services.</Description>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageTags>p2p;database;aspnetcore;healthcheck;hosting;cluster</PackageTags>
<PackageProjectUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</PackageProjectUrl>
<RepositoryUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup>
<PropertyGroup>
<AssemblyName>ZB.MOM.WW.CBDDC.Hosting</AssemblyName>
<RootNamespace>ZB.MOM.WW.CBDDC.Hosting</RootNamespace>
<PackageId>ZB.MOM.WW.CBDDC.Hosting</PackageId>
<TargetFramework>net10.0</TargetFramework>
<LangVersion>latest</LangVersion>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<Version>1.0.3</Version>
<Authors>MrDevRobot</Authors>
<Description>ASP.NET Core integration for CBDDC with health checks and hosted services.</Description>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageTags>p2p;database;aspnetcore;healthcheck;hosting;cluster</PackageTags>
<PackageProjectUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</PackageProjectUrl>
<RepositoryUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup>
<ItemGroup>
<None Include="README.md" Pack="true" PackagePath="\" />
</ItemGroup>
<ItemGroup>
<None Include="README.md" Pack="true" PackagePath="\"/>
</ItemGroup>
</Project>

121
src/ZB.MOM.WW.CBDDC.Network/CBDDCNode.cs
View File

@@ -1,37 +1,21 @@
using System;
using System.Net;
using System.Net.NetworkInformation;
using System.Net.Sockets;
using Microsoft.Extensions.Logging;
using System.Linq;
using System.Threading.Tasks;
using ZB.MOM.WW.CBDDC.Core.Storage;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Represents a single CBDDC Peer Node.
/// Acts as a facade to orchestrate the lifecycle of Networking, Discovery, and Synchronization components.
/// Represents a single CBDDC Peer Node.
/// Acts as a facade to orchestrate the lifecycle of Networking, Discovery, and Synchronization components.
/// </summary>
public class CBDDCNode : ICBDDCNode
{
private readonly ILogger<CBDDCNode> _logger;
/// <summary>
/// Gets the Sync Server instance.
/// </summary>
public ISyncServer Server { get; }
/// <summary>
/// Gets the Discovery Service instance.
/// </summary>
public IDiscoveryService Discovery { get; }
/// <summary>
/// Gets the Synchronization Orchestrator instance.
/// </summary>
public ISyncOrchestrator Orchestrator { get; }
/// <summary>
/// Initializes a new instance of the <see cref="CBDDCNode"/> class.
/// Initializes a new instance of the <see cref="CBDDCNode" /> class.
/// </summary>
/// <param name="server">The TCP server for handling incoming sync requests.</param>
/// <param name="discovery">The UDP service for peer discovery.</param>
@@ -50,7 +34,22 @@ public class CBDDCNode : ICBDDCNode
}
/// <summary>
/// Starts all node components (Server, Discovery, Orchestrator).
/// Gets the Sync Server instance.
/// </summary>
public ISyncServer Server { get; }
/// <summary>
/// Gets the Discovery Service instance.
/// </summary>
public IDiscoveryService Discovery { get; }
/// <summary>
/// Gets the Synchronization Orchestrator instance.
/// </summary>
public ISyncOrchestrator Orchestrator { get; }
/// <summary>
/// Starts all node components (Server, Discovery, Orchestrator).
/// </summary>
public async Task Start()
{
@@ -66,7 +65,7 @@ public class CBDDCNode : ICBDDCNode
}
/// <summary>
/// Stops all node components.
/// Stops all node components.
/// </summary>
public async Task Stop()
{
@@ -82,7 +81,7 @@ public class CBDDCNode : ICBDDCNode
}
/// <summary>
/// Gets the address information of this node.
/// Gets the address information of this node.
/// </summary>
public NodeAddress Address
{
@@ -93,12 +92,11 @@ public class CBDDCNode : ICBDDCNode
{
// If the server is listening on "Any" (0.0.0.0), we cannot advertise that as a connectable address.
// We must resolve the actual machine IP address that peers can reach.
if (Equals(ep.Address, System.Net.IPAddress.Any) || Equals(ep.Address, System.Net.IPAddress.IPv6Any))
{
if (Equals(ep.Address, IPAddress.Any) || Equals(ep.Address, IPAddress.IPv6Any))
return new NodeAddress(GetLocalIpAddress(), ep.Port);
}
return new NodeAddress(ep.Address.ToString(), ep.Port);
}
return new NodeAddress("Unknown", 0);
}
}
@@ -107,20 +105,17 @@ public class CBDDCNode : ICBDDCNode
{
try
{
var interfaces = System.Net.NetworkInformation.NetworkInterface.GetAllNetworkInterfaces()
.Where(i => i.OperationalStatus == System.Net.NetworkInformation.OperationalStatus.Up
&& i.NetworkInterfaceType != System.Net.NetworkInformation.NetworkInterfaceType.Loopback);
var interfaces = NetworkInterface.GetAllNetworkInterfaces()
.Where(i => i.OperationalStatus == OperationalStatus.Up
&& i.NetworkInterfaceType != NetworkInterfaceType.Loopback);
foreach (var i in interfaces)
{
var props = i.GetIPProperties();
var ipInfo = props.UnicastAddresses
.FirstOrDefault(u => u.Address.AddressFamily == System.Net.Sockets.AddressFamily.InterNetwork); // Prefer IPv4
.FirstOrDefault(u => u.Address.AddressFamily == AddressFamily.InterNetwork); // Prefer IPv4
if (ipInfo != null)
{
return ipInfo.Address.ToString();
}
if (ipInfo != null) return ipInfo.Address.ToString();
}
return "127.0.0.1";
@@ -133,28 +128,32 @@ public class CBDDCNode : ICBDDCNode
}
}
public class NodeAddress
{
/// <summary>
/// Gets the host portion of the node address.
/// </summary>
public string Host { get; }
/// <summary>
/// Gets the port portion of the node address.
/// </summary>
public int Port { get; }
/// <summary>
/// Initializes a new instance of the <see cref="NodeAddress"/> class.
/// </summary>
/// <param name="host">The host name or IP address.</param>
/// <param name="port">The port number.</param>
public NodeAddress(string host, int port)
{
Host = host;
Port = port;
}
/// <inheritdoc />
public override string ToString() => $"{Host}:{Port}";
}
public class NodeAddress
{
/// <summary>
/// Initializes a new instance of the <see cref="NodeAddress" /> class.
/// </summary>
/// <param name="host">The host name or IP address.</param>
/// <param name="port">The port number.</param>
public NodeAddress(string host, int port)
{
Host = host;
Port = port;
}
/// <summary>
/// Gets the host portion of the node address.
/// </summary>
public string Host { get; }
/// <summary>
/// Gets the port portion of the node address.
/// </summary>
public int Port { get; }
/// <inheritdoc />
public override string ToString()
{
return $"{Host}:{Port}";
}
}

15
src/ZB.MOM.WW.CBDDC.Network/CBDDCNodeService.cs
View File

@@ -1,22 +1,19 @@
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Serilog.Context;
using System;
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Hosted service that automatically starts and stops the CBDDC node.
/// Hosted service that automatically starts and stops the CBDDC node.
/// </summary>
public class CBDDCNodeService : IHostedService
{
private readonly ICBDDCNode _node;
private readonly ILogger<CBDDCNodeService> _logger;
private readonly ICBDDCNode _node;
/// <summary>
/// Initializes a new instance of the <see cref="CBDDCNodeService"/> class.
/// Initializes a new instance of the <see cref="CBDDCNodeService" /> class.
/// </summary>
/// <param name="node">The CBDDC node to manage.</param>
/// <param name="logger">The logger instance.</param>
@@ -27,7 +24,7 @@ public class CBDDCNodeService : IHostedService
}
/// <summary>
/// Starts the managed CBDDC node.
/// Starts the managed CBDDC node.
/// </summary>
/// <param name="cancellationToken">A token used to cancel startup.</param>
/// <returns>A task that represents the asynchronous start operation.</returns>
@@ -60,7 +57,7 @@ public class CBDDCNodeService : IHostedService
}
/// <summary>
/// Stops the managed CBDDC node.
/// Stops the managed CBDDC node.
/// </summary>
/// <param name="cancellationToken">A token used to cancel shutdown.</param>
/// <returns>A task that represents the asynchronous stop operation.</returns>
@@ -82,4 +79,4 @@ public class CBDDCNodeService : IHostedService
// Don't rethrow during shutdown to avoid breaking the shutdown process
}
}
}
}

8
src/ZB.MOM.WW.CBDDC.Network/CBDDCServiceCollectionExtensions.cs
View File

@@ -8,15 +8,15 @@ using ZB.MOM.WW.CBDDC.Core.Sync;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Provides extension methods for registering core CBDDC services.
/// Provides extension methods for registering core CBDDC services.
/// </summary>
public static class CBDDCServiceCollectionExtensions
{
/// <summary>
/// Registers core CBDDC service dependencies.
/// Registers core CBDDC service dependencies.
/// </summary>
/// <param name="services">The service collection to update.</param>
/// <returns>The same <see cref="IServiceCollection"/> instance for chaining.</returns>
/// <returns>The same <see cref="IServiceCollection" /> instance for chaining.</returns>
public static IServiceCollection AddCBDDCCore(this IServiceCollection services)
{
ArgumentNullException.ThrowIfNull(services);
@@ -29,4 +29,4 @@ public static class CBDDCServiceCollectionExtensions
return services;
}
}
}

55
src/ZB.MOM.WW.CBDDC.Network/CompositeDiscoveryService.cs
View File

@@ -1,38 +1,33 @@
using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core.Storage;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core.Storage;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Composite discovery service that combines UDP LAN discovery with persistent remote peers from the peerConfigurationStore.
/// Periodically refreshes the remote peer list and merges with actively discovered LAN peers.
///
/// Remote peer configurations are stored in a synchronized collection that is automatically
/// replicated across all nodes in the cluster. Any node that adds a remote peer will have
/// it synchronized to all other nodes automatically.
/// Composite discovery service that combines UDP LAN discovery with persistent remote peers from the
/// peerConfigurationStore.
/// Periodically refreshes the remote peer list and merges with actively discovered LAN peers.
/// Remote peer configurations are stored in a synchronized collection that is automatically
/// replicated across all nodes in the cluster. Any node that adds a remote peer will have
/// it synchronized to all other nodes automatically.
/// </summary>
public class CompositeDiscoveryService : IDiscoveryService
{
private readonly IDiscoveryService _udpDiscovery;
private readonly IPeerConfigurationStore _peerConfigurationStore;
private readonly ILogger<CompositeDiscoveryService> _logger;
private readonly TimeSpan _refreshInterval;
private const string RemotePeersCollectionName = "_system_remote_peers";
private readonly ILogger<CompositeDiscoveryService> _logger;
private readonly IPeerConfigurationStore _peerConfigurationStore;
private readonly TimeSpan _refreshInterval;
private readonly ConcurrentDictionary<string, PeerNode> _remotePeers = new();
private readonly object _startStopLock = new();
private readonly IDiscoveryService _udpDiscovery;
private CancellationTokenSource? _cts;
private readonly ConcurrentDictionary<string, PeerNode> _remotePeers = new();
private readonly object _startStopLock = new object();
/// <summary>
/// Initializes a new instance of the CompositeDiscoveryService class.
/// Initializes a new instance of the CompositeDiscoveryService class.
/// </summary>
/// <param name="udpDiscovery">UDP-based LAN discovery service.</param>
/// <param name="peerConfigurationStore">Database instance for accessing the synchronized remote peers collection.</param>
@@ -45,13 +40,14 @@ public class CompositeDiscoveryService : IDiscoveryService
TimeSpan? refreshInterval = null)
{
_udpDiscovery = udpDiscovery ?? throw new ArgumentNullException(nameof(udpDiscovery));
_peerConfigurationStore = peerConfigurationStore ?? throw new ArgumentNullException(nameof(peerConfigurationStore));
_peerConfigurationStore =
peerConfigurationStore ?? throw new ArgumentNullException(nameof(peerConfigurationStore));
_logger = logger ?? NullLogger<CompositeDiscoveryService>.Instance;
_refreshInterval = refreshInterval ?? TimeSpan.FromMinutes(5);
}
/// <summary>
/// Gets the currently active peers from LAN discovery and configured remote peers.
/// Gets the currently active peers from LAN discovery and configured remote peers.
/// </summary>
/// <returns>A sequence of active peer nodes.</returns>
public IEnumerable<PeerNode> GetActivePeers()
@@ -64,7 +60,7 @@ public class CompositeDiscoveryService : IDiscoveryService
}
/// <summary>
/// Starts peer discovery and the remote peer refresh loop.
/// Starts peer discovery and the remote peer refresh loop.
/// </summary>
/// <returns>A task that represents the asynchronous start operation.</returns>
public async Task Start()
@@ -76,6 +72,7 @@ public class CompositeDiscoveryService : IDiscoveryService
_logger.LogWarning("Composite discovery service already started");
return;
}
_cts = new CancellationTokenSource();
}
@@ -103,7 +100,7 @@ public class CompositeDiscoveryService : IDiscoveryService
}
/// <summary>
/// Stops peer discovery and the remote peer refresh loop.
/// Stops peer discovery and the remote peer refresh loop.
/// </summary>
/// <returns>A task that represents the asynchronous stop operation.</returns>
public async Task Stop()
@@ -143,7 +140,6 @@ public class CompositeDiscoveryService : IDiscoveryService
private async Task RefreshLoopAsync(CancellationToken cancellationToken)
{
while (!cancellationToken.IsCancellationRequested)
{
try
{
await Task.Delay(_refreshInterval, cancellationToken);
@@ -158,7 +154,6 @@ public class CompositeDiscoveryService : IDiscoveryService
{
_logger.LogError(ex, "Error during remote peer refresh");
}
}
}
private async Task RefreshRemotePeersAsync()
@@ -178,18 +173,18 @@ public class CompositeDiscoveryService : IDiscoveryService
config.NodeId,
config.Address,
now, // LastSeen is now for persistent peers (always considered active)
config.Type,
NodeRole.Member // Remote peers are always members, never gateways
config.Type // Remote peers are always members, never gateways
);
_remotePeers[config.NodeId] = peerNode;
}
_logger.LogInformation("Refreshed remote peers: {Count} enabled peers loaded from synchronized collection", _remotePeers.Count);
_logger.LogInformation("Refreshed remote peers: {Count} enabled peers loaded from synchronized collection",
_remotePeers.Count);
}
catch (Exception ex)
{
_logger.LogError(ex, "Failed to refresh remote peers from database");
}
}
}
}

64
src/ZB.MOM.WW.CBDDC.Network/CompressionHelper.cs
View File

@@ -1,18 +1,16 @@
using System;
using System.IO;
using System.IO.Compression;
namespace ZB.MOM.WW.CBDDC.Network;
public static class CompressionHelper
{
public const int THRESHOLD = 1024; // 1KB
/// <summary>
/// Gets a value indicating whether Brotli compression is supported on the current target framework.
/// </summary>
public static bool IsBrotliSupported
{
public static class CompressionHelper
{
public const int THRESHOLD = 1024; // 1KB
/// <summary>
/// Gets a value indicating whether Brotli compression is supported on the current target framework.
/// </summary>
public static bool IsBrotliSupported
{
get
{
#if NET6_0_OR_GREATER
@@ -20,16 +18,16 @@ public static class CompressionHelper
#else
return false;
#endif
}
}
/// <summary>
/// Compresses the specified data when Brotli is supported and the payload exceeds the threshold.
/// </summary>
/// <param name="data">The input data to compress.</param>
/// <returns>The compressed payload, or the original payload if compression is skipped.</returns>
public static byte[] Compress(byte[] data)
{
}
}
/// <summary>
/// Compresses the specified data when Brotli is supported and the payload exceeds the threshold.
/// </summary>
/// <param name="data">The input data to compress.</param>
/// <returns>The compressed payload, or the original payload if compression is skipped.</returns>
public static byte[] Compress(byte[] data)
{
if (data.Length < THRESHOLD || !IsBrotliSupported) return data;
#if NET6_0_OR_GREATER
@@ -38,19 +36,20 @@ public static class CompressionHelper
{
brotli.Write(data, 0, data.Length);
}
return output.ToArray();
#else
return data;
#endif
}
/// <summary>
/// Decompresses Brotli-compressed data.
/// </summary>
/// <param name="compressedData">The compressed payload.</param>
/// <returns>The decompressed payload.</returns>
public static byte[] Decompress(byte[] compressedData)
{
#endif
}
/// <summary>
/// Decompresses Brotli-compressed data.
/// </summary>
/// <param name="compressedData">The compressed payload.</param>
/// <returns>The decompressed payload.</returns>
public static byte[] Decompress(byte[] compressedData)
{
#if NET6_0_OR_GREATER
using var input = new MemoryStream(compressedData);
using var output = new MemoryStream();
@@ -58,9 +57,10 @@ public static class CompressionHelper
{
brotli.CopyTo(output);
}
return output.ToArray();
#else
throw new NotSupportedException("Brotli decompression not supported on this platform.");
#endif
}
}
}

69
src/ZB.MOM.WW.CBDDC.Network/ICBDDCNode.cs
View File

@@ -1,35 +1,36 @@
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Network
{
public interface ICBDDCNode
{
/// <summary>
/// Gets the node address.
/// </summary>
NodeAddress Address { get; }
/// <summary>
/// Gets the discovery service.
/// </summary>
IDiscoveryService Discovery { get; }
/// <summary>
/// Gets the synchronization orchestrator.
/// </summary>
ISyncOrchestrator Orchestrator { get; }
/// <summary>
/// Gets the synchronization server.
/// </summary>
ISyncServer Server { get; }
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Starts the node services.
/// </summary>
/// <returns>A task that represents the asynchronous start operation.</returns>
Task Start();
/// <summary>
/// Stops the node services.
/// </summary>
/// <returns>A task that represents the asynchronous stop operation.</returns>
Task Stop();
}
}
public interface ICBDDCNode
{
/// <summary>
/// Gets the node address.
/// </summary>
NodeAddress Address { get; }
/// <summary>
/// Gets the discovery service.
/// </summary>
IDiscoveryService Discovery { get; }
/// <summary>
/// Gets the synchronization orchestrator.
/// </summary>
ISyncOrchestrator Orchestrator { get; }
/// <summary>
/// Gets the synchronization server.
/// </summary>
ISyncServer Server { get; }
/// <summary>
/// Starts the node services.
/// </summary>
/// <returns>A task that represents the asynchronous start operation.</returns>
Task Start();
/// <summary>
/// Stops the node services.
/// </summary>
/// <returns>A task that represents the asynchronous stop operation.</returns>
Task Stop();
}

47
src/ZB.MOM.WW.CBDDC.Network/IDiscoveryService.cs
View File

@@ -1,30 +1,27 @@
using ZB.MOM.WW.CBDDC.Core.Network;
using System.Collections.Generic;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Network
using ZB.MOM.WW.CBDDC.Core.Network;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Defines peer discovery operations.
/// </summary>
public interface IDiscoveryService
{
/// <summary>
/// Defines peer discovery operations.
/// Gets the currently active peers.
/// </summary>
public interface IDiscoveryService
{
/// <summary>
/// Gets the currently active peers.
/// </summary>
/// <returns>The active peer nodes.</returns>
IEnumerable<PeerNode> GetActivePeers();
/// <returns>The active peer nodes.</returns>
IEnumerable<PeerNode> GetActivePeers();
/// <summary>
/// Starts the discovery service.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Start();
/// <summary>
/// Starts the discovery service.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Start();
/// <summary>
/// Stops the discovery service.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Stop();
}
}
/// <summary>
/// Stops the discovery service.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Stop();
}

8
src/ZB.MOM.WW.CBDDC.Network/IOplogPruneCutoffCalculator.cs
View File

@@ -1,16 +1,14 @@
using System.Threading;
using System.Threading.Tasks;
using ZB.MOM.WW.CBDDC.Core.Network;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Calculates the effective oplog prune cutoff for maintenance.
/// Calculates the effective oplog prune cutoff for maintenance.
/// </summary>
public interface IOplogPruneCutoffCalculator
{
/// <summary>
/// Calculates the effective prune cutoff for the provided node configuration.
/// Calculates the effective prune cutoff for the provided node configuration.
/// </summary>
/// <param name="configuration">The local node configuration.</param>
/// <param name="cancellationToken">The cancellation token.</param>
@@ -18,4 +16,4 @@ public interface IOplogPruneCutoffCalculator
Task<OplogPruneCutoffDecision> CalculateEffectiveCutoffAsync(
PeerNodeConfiguration configuration,
CancellationToken cancellationToken = default);
}
}

33
src/ZB.MOM.WW.CBDDC.Network/ISyncOrchestrator.cs
View File

@@ -1,22 +1,19 @@
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Network
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Defines lifecycle operations for synchronization orchestration.
/// </summary>
public interface ISyncOrchestrator
{
/// <summary>
/// Defines lifecycle operations for synchronization orchestration.
/// Starts synchronization orchestration.
/// </summary>
public interface ISyncOrchestrator
{
/// <summary>
/// Starts synchronization orchestration.
/// </summary>
/// <returns>A task that represents the asynchronous start operation.</returns>
Task Start();
/// <returns>A task that represents the asynchronous start operation.</returns>
Task Start();
/// <summary>
/// Stops synchronization orchestration.
/// </summary>
/// <returns>A task that represents the asynchronous stop operation.</returns>
Task Stop();
}
}
/// <summary>
/// Stops synchronization orchestration.
/// </summary>
/// <returns>A task that represents the asynchronous stop operation.</returns>
Task Stop();
}

42
src/ZB.MOM.WW.CBDDC.Network/ISyncServer.cs
View File

@@ -1,31 +1,33 @@
using System.Net;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Defines the contract for a server that supports starting, stopping, and reporting its listening network endpoint for
/// synchronization operations.
/// </summary>
/// <remarks>Implementations of this interface are expected to provide asynchronous methods for starting and
/// stopping the server. The listening endpoint may be null if the server is not currently active or has not been
/// started.</remarks>
using System.Net;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Defines the contract for a server that supports starting, stopping, and reporting its listening network endpoint
/// for
/// synchronization operations.
/// </summary>
/// <remarks>
/// Implementations of this interface are expected to provide asynchronous methods for starting and
/// stopping the server. The listening endpoint may be null if the server is not currently active or has not been
/// started.
/// </remarks>
public interface ISyncServer
{
/// <summary>
/// Starts the synchronization server.
/// Gets the network endpoint currently used by the server for listening.
/// </summary>
IPEndPoint? ListeningEndpoint { get; }
/// <summary>
/// Starts the synchronization server.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Start();
/// <summary>
/// Stops the synchronization server.
/// Stops the synchronization server.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
Task Stop();
/// <summary>
/// Gets the network endpoint currently used by the server for listening.
/// </summary>
IPEndPoint? ListeningEndpoint { get; }
}
}

87
src/ZB.MOM.WW.CBDDC.Network/Leadership/BullyLeaderElectionService.cs
View File

@@ -1,48 +1,26 @@
using System;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Core.Network;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.CBDDC.Core.Network;
namespace ZB.MOM.WW.CBDDC.Network.Leadership;
/// <summary>
/// Implements the Bully algorithm for leader election.
/// The node with the lexicographically smallest NodeId becomes the cloud gateway (leader).
/// Elections run periodically (every 5 seconds) to adapt to cluster changes.
/// Implements the Bully algorithm for leader election.
/// The node with the lexicographically smallest NodeId becomes the cloud gateway (leader).
/// Elections run periodically (every 5 seconds) to adapt to cluster changes.
/// </summary>
public class BullyLeaderElectionService : ILeaderElectionService
{
private readonly IDiscoveryService _discoveryService;
private readonly IPeerNodeConfigurationProvider _configProvider;
private readonly ILogger<BullyLeaderElectionService> _logger;
private readonly IDiscoveryService _discoveryService;
private readonly TimeSpan _electionInterval;
private readonly ILogger<BullyLeaderElectionService> _logger;
private CancellationTokenSource? _cts;
private string? _localNodeId;
private string? _currentGatewayNodeId;
private bool _isCloudGateway;
/// <summary>
/// Gets a value indicating whether this node is currently the cloud gateway leader.
/// </summary>
public bool IsCloudGateway => _isCloudGateway;
/// <summary>
/// Gets the current gateway node identifier.
/// </summary>
public string? CurrentGatewayNodeId => _currentGatewayNodeId;
/// <summary>
/// Occurs when leadership changes.
/// </summary>
public event EventHandler<LeadershipChangedEventArgs>? LeadershipChanged;
/// <summary>
/// Initializes a new instance of the BullyLeaderElectionService class.
/// Initializes a new instance of the BullyLeaderElectionService class.
/// </summary>
/// <param name="discoveryService">Service providing active peer information.</param>
/// <param name="configProvider">Provider for local node configuration.</param>
@@ -61,7 +39,22 @@ public class BullyLeaderElectionService : ILeaderElectionService
}
/// <summary>
/// Starts the leader election loop.
/// Gets a value indicating whether this node is currently the cloud gateway leader.
/// </summary>
public bool IsCloudGateway { get; private set; }
/// <summary>
/// Gets the current gateway node identifier.
/// </summary>
public string? CurrentGatewayNodeId { get; private set; }
/// <summary>
/// Occurs when leadership changes.
/// </summary>
public event EventHandler<LeadershipChangedEventArgs>? LeadershipChanged;
/// <summary>
/// Starts the leader election loop.
/// </summary>
/// <returns>A task that represents the asynchronous start operation.</returns>
public async Task Start()
@@ -82,7 +75,7 @@ public class BullyLeaderElectionService : ILeaderElectionService
}
/// <summary>
/// Stops the leader election loop.
/// Stops the leader election loop.
/// </summary>
/// <returns>A task that represents the asynchronous stop operation.</returns>
public Task Stop()
@@ -100,7 +93,6 @@ public class BullyLeaderElectionService : ILeaderElectionService
private async Task ElectionLoopAsync(CancellationToken cancellationToken)
{
while (!cancellationToken.IsCancellationRequested)
{
try
{
await Task.Delay(_electionInterval, cancellationToken);
@@ -115,7 +107,6 @@ public class BullyLeaderElectionService : ILeaderElectionService
{
_logger.LogError(ex, "Error during leader election");
}
}
}
private void RunElection()
@@ -132,35 +123,31 @@ public class BullyLeaderElectionService : ILeaderElectionService
lanPeers.Add(_localNodeId);
// Bully algorithm: smallest NodeId wins (lexicographic comparison)
var newLeader = lanPeers.OrderBy(id => id, StringComparer.Ordinal).FirstOrDefault();
string? newLeader = lanPeers.OrderBy(id => id, StringComparer.Ordinal).FirstOrDefault();
if (newLeader == null)
{
// No peers available, local node is leader by default
newLeader = _localNodeId;
}
// Check if leadership changed
if (newLeader != _currentGatewayNodeId)
if (newLeader != CurrentGatewayNodeId)
{
var wasLeader = _isCloudGateway;
_currentGatewayNodeId = newLeader;
_isCloudGateway = newLeader == _localNodeId;
bool wasLeader = IsCloudGateway;
CurrentGatewayNodeId = newLeader;
IsCloudGateway = newLeader == _localNodeId;
if (wasLeader != _isCloudGateway)
if (wasLeader != IsCloudGateway)
{
if (_isCloudGateway)
{
_logger.LogInformation("🔐 This node is now the CLOUD GATEWAY (Leader) - Will sync with remote cloud nodes");
}
if (IsCloudGateway)
_logger.LogInformation(
"🔐 This node is now the CLOUD GATEWAY (Leader) - Will sync with remote cloud nodes");
else
{
_logger.LogInformation("👤 This node is now a MEMBER - Cloud sync handled by gateway: {Gateway}", _currentGatewayNodeId);
}
_logger.LogInformation("👤 This node is now a MEMBER - Cloud sync handled by gateway: {Gateway}",
CurrentGatewayNodeId);
// Raise event
LeadershipChanged?.Invoke(this, new LeadershipChangedEventArgs(_currentGatewayNodeId, _isCloudGateway));
LeadershipChanged?.Invoke(this, new LeadershipChangedEventArgs(CurrentGatewayNodeId, IsCloudGateway));
}
}
}
}
}

52
src/ZB.MOM.WW.CBDDC.Network/Leadership/ILeaderElectionService.cs
View File

@@ -1,65 +1,65 @@
using System;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Network.Leadership;
/// <summary>
/// Event arguments for leadership change events.
/// Event arguments for leadership change events.
/// </summary>
public class LeadershipChangedEventArgs : EventArgs
{
/// <summary>
/// Gets the NodeId of the current cloud gateway (leader).
/// Null if no leader is elected.
/// Initializes a new instance of the LeadershipChangedEventArgs class.
/// </summary>
public string? CurrentGatewayNodeId { get; }
/// <summary>
/// Gets whether the local node is now the cloud gateway.
/// </summary>
public bool IsLocalNodeGateway { get; }
/// <summary>
/// Initializes a new instance of the LeadershipChangedEventArgs class.
/// </summary>
/// <param name="currentGatewayNodeId">The NodeId of the current gateway node, or <see langword="null"/> when none is elected.</param>
/// <param name="currentGatewayNodeId">
/// The NodeId of the current gateway node, or <see langword="null" /> when none is
/// elected.
/// </param>
/// <param name="isLocalNodeGateway">A value indicating whether the local node is the gateway.</param>
public LeadershipChangedEventArgs(string? currentGatewayNodeId, bool isLocalNodeGateway)
{
CurrentGatewayNodeId = currentGatewayNodeId;
IsLocalNodeGateway = isLocalNodeGateway;
}
/// <summary>
/// Gets the NodeId of the current cloud gateway (leader).
/// Null if no leader is elected.
/// </summary>
public string? CurrentGatewayNodeId { get; }
/// <summary>
/// Gets whether the local node is now the cloud gateway.
/// </summary>
public bool IsLocalNodeGateway { get; }
}
/// <summary>
/// Service for managing leader election in a distributed cluster.
/// Uses the Bully algorithm where the node with the lexicographically smallest NodeId becomes the leader.
/// Only the leader (Cloud Gateway) synchronizes with remote cloud nodes.
/// Service for managing leader election in a distributed cluster.
/// Uses the Bully algorithm where the node with the lexicographically smallest NodeId becomes the leader.
/// Only the leader (Cloud Gateway) synchronizes with remote cloud nodes.
/// </summary>
public interface ILeaderElectionService
{
/// <summary>
/// Gets whether the local node is currently the cloud gateway (leader).
/// Gets whether the local node is currently the cloud gateway (leader).
/// </summary>
bool IsCloudGateway { get; }
/// <summary>
/// Gets the NodeId of the current cloud gateway, or null if no gateway is elected.
/// Gets the NodeId of the current cloud gateway, or null if no gateway is elected.
/// </summary>
string? CurrentGatewayNodeId { get; }
/// <summary>
/// Event raised when leadership changes.
/// Event raised when leadership changes.
/// </summary>
event EventHandler<LeadershipChangedEventArgs>? LeadershipChanged;
/// <summary>
/// Starts the leader election service.
/// Starts the leader election service.
/// </summary>
Task Start();
/// <summary>
/// Stops the leader election service.
/// Stops the leader election service.
/// </summary>
Task Stop();
}
}

71
src/ZB.MOM.WW.CBDDC.Network/OplogPruneCutoffCalculator.cs
View File

@@ -1,8 +1,3 @@
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core.Storage;
@@ -10,7 +5,7 @@ using ZB.MOM.WW.CBDDC.Core.Storage;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Default implementation for effective oplog prune cutoff calculation.
/// Default implementation for effective oplog prune cutoff calculation.
/// </summary>
public class OplogPruneCutoffCalculator : IOplogPruneCutoffCalculator
{
@@ -18,7 +13,7 @@ public class OplogPruneCutoffCalculator : IOplogPruneCutoffCalculator
private readonly IPeerOplogConfirmationStore? _peerOplogConfirmationStore;
/// <summary>
/// Initializes a new instance of the <see cref="OplogPruneCutoffCalculator"/> class.
/// Initializes a new instance of the <see cref="OplogPruneCutoffCalculator" /> class.
/// </summary>
/// <param name="oplogStore">The oplog store.</param>
/// <param name="peerOplogConfirmationStore">The optional peer confirmation store.</param>
@@ -39,23 +34,19 @@ public class OplogPruneCutoffCalculator : IOplogPruneCutoffCalculator
var retentionCutoff = BuildRetentionCutoff(configuration);
if (_peerOplogConfirmationStore == null)
{
return OplogPruneCutoffDecision.WithCutoff(
retentionCutoff,
confirmationCutoff: null,
effectiveCutoff: retentionCutoff,
reason: "Confirmation tracking is not configured.");
}
null,
retentionCutoff,
"Confirmation tracking is not configured.");
var relevantSources = await GetRelevantSourceNodesAsync(cancellationToken);
if (relevantSources.Count == 0)
{
return OplogPruneCutoffDecision.WithCutoff(
retentionCutoff,
confirmationCutoff: null,
effectiveCutoff: retentionCutoff,
reason: "No local non-default oplog/vector-clock sources were found.");
}
null,
retentionCutoff,
"No local non-default oplog/vector-clock sources were found.");
var activeTrackedPeers = (await _peerOplogConfirmationStore.GetActiveTrackedPeersAsync(cancellationToken))
.Where(peerNodeId => !string.IsNullOrWhiteSpace(peerNodeId))
@@ -63,19 +54,18 @@ public class OplogPruneCutoffCalculator : IOplogPruneCutoffCalculator
.ToList();
if (activeTrackedPeers.Count == 0)
{
return OplogPruneCutoffDecision.WithCutoff(
retentionCutoff,
confirmationCutoff: null,
effectiveCutoff: retentionCutoff,
reason: "No active tracked peers found for confirmation gating.");
}
null,
retentionCutoff,
"No active tracked peers found for confirmation gating.");
HlcTimestamp? confirmationCutoff = null;
foreach (var peerNodeId in activeTrackedPeers)
foreach (string peerNodeId in activeTrackedPeers)
{
var confirmationsForPeer = (await _peerOplogConfirmationStore.GetConfirmationsForPeerAsync(peerNodeId, cancellationToken))
var confirmationsForPeer =
(await _peerOplogConfirmationStore.GetConfirmationsForPeerAsync(peerNodeId, cancellationToken))
.Where(confirmation => confirmation.IsActive)
.Where(confirmation => !string.IsNullOrWhiteSpace(confirmation.SourceNodeId))
.GroupBy(confirmation => confirmation.SourceNodeId, StringComparer.Ordinal)
@@ -87,30 +77,25 @@ public class OplogPruneCutoffCalculator : IOplogPruneCutoffCalculator
.Last(),
StringComparer.Ordinal);
foreach (var sourceNodeId in relevantSources)
foreach (string sourceNodeId in relevantSources)
{
if (!confirmationsForPeer.TryGetValue(sourceNodeId, out var confirmedTimestamp) || confirmedTimestamp == default)
{
if (!confirmationsForPeer.TryGetValue(sourceNodeId, out var confirmedTimestamp) ||
confirmedTimestamp == default)
return OplogPruneCutoffDecision.NoCutoff(
retentionCutoff,
$"Active tracked peer '{peerNodeId}' is missing confirmation for source '{sourceNodeId}'.");
}
if (!confirmationCutoff.HasValue || confirmedTimestamp < confirmationCutoff.Value)
{
confirmationCutoff = confirmedTimestamp;
}
}
}
if (!confirmationCutoff.HasValue)
{
return OplogPruneCutoffDecision.WithCutoff(
retentionCutoff,
confirmationCutoff: null,
effectiveCutoff: retentionCutoff,
reason: "No confirmation cutoff could be determined.");
}
null,
retentionCutoff,
"No confirmation cutoff could be determined.");
var effectiveCutoff = retentionCutoff <= confirmationCutoff.Value
? retentionCutoff
@@ -124,7 +109,7 @@ public class OplogPruneCutoffCalculator : IOplogPruneCutoffCalculator
private static HlcTimestamp BuildRetentionCutoff(PeerNodeConfiguration configuration)
{
var retentionTimestamp = DateTimeOffset.UtcNow
long retentionTimestamp = DateTimeOffset.UtcNow
.AddHours(-configuration.OplogRetentionHours)
.ToUnixTimeMilliseconds();
@@ -135,18 +120,12 @@ public class OplogPruneCutoffCalculator : IOplogPruneCutoffCalculator
{
var localVectorClock = await _oplogStore.GetVectorClockAsync(cancellationToken);
var sourceNodes = new HashSet<string>(StringComparer.Ordinal);
foreach (var sourceNodeId in localVectorClock.NodeIds)
foreach (string sourceNodeId in localVectorClock.NodeIds)
{
if (string.IsNullOrWhiteSpace(sourceNodeId))
{
continue;
}
if (string.IsNullOrWhiteSpace(sourceNodeId)) continue;
var timestamp = localVectorClock.GetTimestamp(sourceNodeId);
if (timestamp == default)
{
continue;
}
if (timestamp == default) continue;
sourceNodes.Add(sourceNodeId);
}
@@ -161,4 +140,4 @@ public class OplogPruneCutoffCalculator : IOplogPruneCutoffCalculator
confirmation.ConfirmedLogic,
confirmation.SourceNodeId ?? string.Empty);
}
}
}

38
src/ZB.MOM.WW.CBDDC.Network/OplogPruneCutoffDecision.cs
View File

@@ -3,7 +3,7 @@ using ZB.MOM.WW.CBDDC.Core;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Represents the prune cutoff decision for an oplog maintenance cycle.
/// Represents the prune cutoff decision for an oplog maintenance cycle.
/// </summary>
public sealed class OplogPruneCutoffDecision
{
@@ -22,32 +22,32 @@ public sealed class OplogPruneCutoffDecision
}
/// <summary>
/// Gets a value indicating whether pruning is allowed for this decision.
/// Gets a value indicating whether pruning is allowed for this decision.
/// </summary>
public bool HasCutoff { get; }
/// <summary>
/// Gets the retention-based cutoff.
/// Gets the retention-based cutoff.
/// </summary>
public HlcTimestamp RetentionCutoff { get; }
/// <summary>
/// Gets the confirmation-based cutoff, when available.
/// Gets the confirmation-based cutoff, when available.
/// </summary>
public HlcTimestamp? ConfirmationCutoff { get; }
/// <summary>
/// Gets the effective cutoff to use for pruning when <see cref="HasCutoff"/> is true.
/// Gets the effective cutoff to use for pruning when <see cref="HasCutoff" /> is true.
/// </summary>
public HlcTimestamp? EffectiveCutoff { get; }
/// <summary>
/// Gets the explanatory reason for skip/special handling decisions.
/// Gets the explanatory reason for skip/special handling decisions.
/// </summary>
public string Reason { get; }
/// <summary>
/// Creates a prune-allowed decision with the provided cutoffs.
/// Creates a prune-allowed decision with the provided cutoffs.
/// </summary>
/// <param name="retentionCutoff">The cutoff derived from retention policy.</param>
/// <param name="confirmationCutoff">The cutoff derived from peer confirmations, if available.</param>
@@ -60,25 +60,25 @@ public sealed class OplogPruneCutoffDecision
string reason = "")
{
return new OplogPruneCutoffDecision(
hasCutoff: true,
retentionCutoff: retentionCutoff,
confirmationCutoff: confirmationCutoff,
effectiveCutoff: effectiveCutoff,
reason: reason);
true,
retentionCutoff,
confirmationCutoff,
effectiveCutoff,
reason);
}
/// <summary>
/// Creates a prune-blocked decision.
/// Creates a prune-blocked decision.
/// </summary>
/// <param name="retentionCutoff">The cutoff derived from retention policy.</param>
/// <param name="reason">The explanatory reason associated with the decision.</param>
public static OplogPruneCutoffDecision NoCutoff(HlcTimestamp retentionCutoff, string reason)
{
return new OplogPruneCutoffDecision(
hasCutoff: false,
retentionCutoff: retentionCutoff,
confirmationCutoff: null,
effectiveCutoff: null,
reason: reason);
false,
retentionCutoff,
null,
null,
reason);
}
}
}

60
src/ZB.MOM.WW.CBDDC.Network/PeerDbNetworkExtensions.cs
View File

@@ -1,57 +1,55 @@
using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Core.Network; // For IMeshNetwork if we implement it
using ZB.MOM.WW.CBDDC.Core.Storage;
using ZB.MOM.WW.CBDDC.Network.Security;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Hosting;
using System;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Network.Security;
using ZB.MOM.WW.CBDDC.Network.Telemetry;
// For IMeshNetwork if we implement it
namespace ZB.MOM.WW.CBDDC.Network;
public static class CBDDCNetworkExtensions
{
/// <summary>
/// Adds CBDDC network services to the service collection.
/// </summary>
/// <typeparam name="TPeerNodeConfigurationProvider">The peer node configuration provider implementation type.</typeparam>
/// <param name="services">The service collection to register services into.</param>
/// <param name="useHostedService">If true, registers CBDDCNodeService as IHostedService to automatically start/stop the node.</param>
public static IServiceCollection AddCBDDCNetwork<TPeerNodeConfigurationProvider>(
this IServiceCollection services,
bool useHostedService = true)
/// <summary>
/// Adds CBDDC network services to the service collection.
/// </summary>
/// <typeparam name="TPeerNodeConfigurationProvider">The peer node configuration provider implementation type.</typeparam>
/// <param name="services">The service collection to register services into.</param>
/// <param name="useHostedService">
/// If true, registers CBDDCNodeService as IHostedService to automatically start/stop the
/// node.
/// </param>
public static IServiceCollection AddCBDDCNetwork<TPeerNodeConfigurationProvider>(
this IServiceCollection services,
bool useHostedService = true)
where TPeerNodeConfigurationProvider : class, IPeerNodeConfigurationProvider
{
services.TryAddSingleton<IPeerNodeConfigurationProvider, TPeerNodeConfigurationProvider>();
services.TryAddSingleton<IAuthenticator, ClusterKeyAuthenticator>();
services.TryAddSingleton<IAuthenticator, ClusterKeyAuthenticator>();
services.TryAddSingleton<IPeerHandshakeService, SecureHandshakeService>();
services.TryAddSingleton<IDiscoveryService, UdpDiscoveryService>();
services.TryAddSingleton<ZB.MOM.WW.CBDDC.Network.Telemetry.INetworkTelemetryService>(sp =>
services.TryAddSingleton<INetworkTelemetryService>(sp =>
{
var logger = sp.GetRequiredService<ILogger<ZB.MOM.WW.CBDDC.Network.Telemetry.NetworkTelemetryService>>();
var path = System.IO.Path.Combine(System.AppContext.BaseDirectory, "cbddc_metrics.bin");
return new ZB.MOM.WW.CBDDC.Network.Telemetry.NetworkTelemetryService(logger, path);
var logger = sp.GetRequiredService<ILogger<NetworkTelemetryService>>();
string path = Path.Combine(AppContext.BaseDirectory, "cbddc_metrics.bin");
return new NetworkTelemetryService(logger, path);
});
services.TryAddSingleton<ISyncServer, TcpSyncServer>();
services.TryAddSingleton<IOplogPruneCutoffCalculator, OplogPruneCutoffCalculator>();
services.TryAddSingleton<ISyncOrchestrator, SyncOrchestrator>();
services.TryAddSingleton<ISyncServer, TcpSyncServer>();
services.TryAddSingleton<IOplogPruneCutoffCalculator, OplogPruneCutoffCalculator>();
services.TryAddSingleton<ISyncOrchestrator, SyncOrchestrator>();
services.TryAddSingleton<ICBDDCNode, CBDDCNode>();
// Optionally register hosted service for automatic node lifecycle management
if (useHostedService)
{
services.AddHostedService<CBDDCNodeService>();
}
if (useHostedService) services.AddHostedService<CBDDCNodeService>();
return services;
}
}
}

479
src/ZB.MOM.WW.CBDDC.Network/Protocol/ProtocolHandler.cs
View File

@@ -1,259 +1,252 @@
using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;
using Google.Protobuf;
using Microsoft.Extensions.Logging;
using ZB.MOM.WW.CBDDC.Network.Proto;
using ZB.MOM.WW.CBDDC.Network.Security;
using ZB.MOM.WW.CBDDC.Network.Telemetry;
namespace ZB.MOM.WW.CBDDC.Network.Protocol
namespace ZB.MOM.WW.CBDDC.Network.Protocol;
/// <summary>
/// Handles the low-level framing, compression, encryption, and serialization of CBDDC messages.
/// Encapsulates the wire format: [Length (4)] [Type (1)] [Compression (1)] [Payload (N)]
/// </summary>
internal class ProtocolHandler
{
private readonly ILogger<ProtocolHandler> _logger;
private readonly SemaphoreSlim _readLock = new(1, 1);
private readonly INetworkTelemetryService? _telemetry;
private readonly SemaphoreSlim _writeLock = new(1, 1);
/// <summary>
/// Handles the low-level framing, compression, encryption, and serialization of CBDDC messages.
/// Encapsulates the wire format: [Length (4)] [Type (1)] [Compression (1)] [Payload (N)]
/// Initializes a new instance of the <see cref="ProtocolHandler" /> class.
/// </summary>
internal class ProtocolHandler
{
private readonly ILogger<ProtocolHandler> _logger;
private readonly INetworkTelemetryService? _telemetry;
private readonly SemaphoreSlim _writeLock = new SemaphoreSlim(1, 1);
private readonly SemaphoreSlim _readLock = new SemaphoreSlim(1, 1);
/// <summary>
/// Initializes a new instance of the <see cref="ProtocolHandler"/> class.
/// </summary>
/// <param name="logger">The logger used for protocol diagnostics.</param>
/// <param name="telemetry">An optional telemetry service used to record network metrics.</param>
public ProtocolHandler(ILogger<ProtocolHandler> logger, INetworkTelemetryService? telemetry = null)
{
_logger = logger;
_telemetry = telemetry;
}
/// <summary>
/// Initializes a new instance of the <see cref="ProtocolHandler"/> class using a non-generic logger.
/// </summary>
/// <param name="logger">The logger used for protocol diagnostics.</param>
/// <param name="telemetry">An optional telemetry service used to record network metrics.</param>
internal ProtocolHandler(ILogger logger, INetworkTelemetryService? telemetry = null)
: this(new ForwardingLogger(logger), telemetry)
{
}
/// <summary>
/// Serializes and sends a protocol message to the provided stream.
/// </summary>
/// <param name="stream">The destination stream.</param>
/// <param name="type">The protocol message type.</param>
/// <param name="message">The message payload to serialize.</param>
/// <param name="useCompression">Whether payload compression should be attempted.</param>
/// <param name="cipherState">Optional cipher state used to encrypt outgoing payloads.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>A task that represents the asynchronous send operation.</returns>
public async Task SendMessageAsync(Stream stream, MessageType type, IMessage message, bool useCompression, CipherState? cipherState, CancellationToken token = default)
{
if (stream == null) throw new ArgumentNullException(nameof(stream));
/// <param name="logger">The logger used for protocol diagnostics.</param>
/// <param name="telemetry">An optional telemetry service used to record network metrics.</param>
public ProtocolHandler(ILogger<ProtocolHandler> logger, INetworkTelemetryService? telemetry = null)
{
_logger = logger;
_telemetry = telemetry;
}
// 1. Serialize
byte[] payloadBytes = message.ToByteArray();
int originalSize = payloadBytes.Length;
byte compressionFlag = 0x00;
/// <summary>
/// Initializes a new instance of the <see cref="ProtocolHandler" /> class using a non-generic logger.
/// </summary>
/// <param name="logger">The logger used for protocol diagnostics.</param>
/// <param name="telemetry">An optional telemetry service used to record network metrics.</param>
internal ProtocolHandler(ILogger logger, INetworkTelemetryService? telemetry = null)
: this(new ForwardingLogger(logger), telemetry)
{
}
// 2. Compress (inner payload)
if (useCompression && payloadBytes.Length > CompressionHelper.THRESHOLD && type != MessageType.SecureEnv)
{
// Measure Compression Time
// using var _ = _telemetry?.StartMetric(MetricType.CompressionTime); // Oops, MetricType.CompressionTime not defined? Wait, user asked for "Compression Ratio".
// User asked for "performance della compressione brotli (% media di compressione)".
// That usually means ratio. But time is also good?
// Plan said: "MetricType: CompressionRatio, EncryptionTime..."
// byte[] compressed; // Removed unused variable
// using (_telemetry?.StartMetric(MetricType.CompressionTime)) // Let's stick to Time if relevant? NO, MetricType only has Ratio.
// Ah I see MetricType enum: CompressionRatio, EncryptionTime, DecryptionTime, RoundTripTime.
// So for compression we only record Ratio.
payloadBytes = CompressionHelper.Compress(payloadBytes);
compressionFlag = 0x01; // Brotli
if (_telemetry != null && originalSize > 0)
{
double ratio = (double)payloadBytes.Length / originalSize;
_telemetry.RecordValue(MetricType.CompressionRatio, ratio);
}
}
/// <summary>
/// Serializes and sends a protocol message to the provided stream.
/// </summary>
/// <param name="stream">The destination stream.</param>
/// <param name="type">The protocol message type.</param>
/// <param name="message">The message payload to serialize.</param>
/// <param name="useCompression">Whether payload compression should be attempted.</param>
/// <param name="cipherState">Optional cipher state used to encrypt outgoing payloads.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>A task that represents the asynchronous send operation.</returns>
public async Task SendMessageAsync(Stream stream, MessageType type, IMessage message, bool useCompression,
CipherState? cipherState, CancellationToken token = default)
{
if (stream == null) throw new ArgumentNullException(nameof(stream));
// 3. Encrypt
if (cipherState != null)
// 1. Serialize
byte[] payloadBytes = message.ToByteArray();
int originalSize = payloadBytes.Length;
byte compressionFlag = 0x00;
// 2. Compress (inner payload)
if (useCompression && payloadBytes.Length > CompressionHelper.THRESHOLD && type != MessageType.SecureEnv)
{
// Measure Compression Time
// using var _ = _telemetry?.StartMetric(MetricType.CompressionTime); // Oops, MetricType.CompressionTime not defined? Wait, user asked for "Compression Ratio".
// User asked for "performance della compressione brotli (% media di compressione)".
// That usually means ratio. But time is also good?
// Plan said: "MetricType: CompressionRatio, EncryptionTime..."
// byte[] compressed; // Removed unused variable
// using (_telemetry?.StartMetric(MetricType.CompressionTime)) // Let's stick to Time if relevant? NO, MetricType only has Ratio.
// Ah I see MetricType enum: CompressionRatio, EncryptionTime, DecryptionTime, RoundTripTime.
// So for compression we only record Ratio.
payloadBytes = CompressionHelper.Compress(payloadBytes);
compressionFlag = 0x01; // Brotli
if (_telemetry != null && originalSize > 0)
{
using (_telemetry?.StartMetric(MetricType.EncryptionTime))
{
// Inner data: [Type (1)] [Compression (1)] [Payload (N)]
var dataToEncrypt = new byte[2 + payloadBytes.Length];
dataToEncrypt[0] = (byte)type;
dataToEncrypt[1] = compressionFlag;
Buffer.BlockCopy(payloadBytes, 0, dataToEncrypt, 2, payloadBytes.Length);
var (ciphertext, iv, tag) = CryptoHelper.Encrypt(dataToEncrypt, cipherState.EncryptKey);
var env = new SecureEnvelope
{
Ciphertext = ByteString.CopyFrom(ciphertext),
Nonce = ByteString.CopyFrom(iv),
AuthTag = ByteString.CopyFrom(tag)
};
payloadBytes = env.ToByteArray();
type = MessageType.SecureEnv;
compressionFlag = 0x00; // Outer envelope is not compressed
}
}
// 4. Thread-Safe Write
await _writeLock.WaitAsync(token);
try
{
_logger.LogDebug("Sending Message {Type}, OrgSize: {Org}, WireSize: {Wire}", type, originalSize, payloadBytes.Length);
// Framing: [Length (4)] [Type (1)] [Compression (1)] [Payload (N)]
var lengthBytes = BitConverter.GetBytes(payloadBytes.Length);
await stream.WriteAsync(lengthBytes, 0, 4, token);
stream.WriteByte((byte)type);
stream.WriteByte(compressionFlag);
await stream.WriteAsync(payloadBytes, 0, payloadBytes.Length, token);
await stream.FlushAsync(token);
}
finally
{
_writeLock.Release();
}
}
/// <summary>
/// Reads and decodes the next protocol message from the provided stream.
/// </summary>
/// <param name="stream">The source stream.</param>
/// <param name="cipherState">Optional cipher state used to decrypt incoming payloads.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>A tuple containing the decoded message type and payload bytes.</returns>
public async Task<(MessageType, byte[])> ReadMessageAsync(Stream stream, CipherState? cipherState, CancellationToken token = default)
{
await _readLock.WaitAsync(token);
try
{
var lenBuf = new byte[4];
int read = await ReadExactAsync(stream, lenBuf, 0, 4, token);
if (read == 0) return (MessageType.Unknown, null!);
int length = BitConverter.ToInt32(lenBuf, 0);
int typeByte = stream.ReadByte();
if (typeByte == -1) throw new EndOfStreamException("Connection closed abruptly (type byte)");
int compByte = stream.ReadByte();
if (compByte == -1) throw new EndOfStreamException("Connection closed abruptly (comp byte)");
var payload = new byte[length];
await ReadExactAsync(stream, payload, 0, length, token);
var msgType = (MessageType)typeByte;
// Handle Secure Envelope
if (msgType == MessageType.SecureEnv)
{
if (cipherState == null) throw new InvalidOperationException("Received encrypted message but no cipher state established");
byte[] decrypted;
using (_telemetry?.StartMetric(MetricType.DecryptionTime))
{
var env = SecureEnvelope.Parser.ParseFrom(payload);
decrypted = CryptoHelper.Decrypt(
env.Ciphertext.ToByteArray(),
env.Nonce.ToByteArray(),
env.AuthTag.ToByteArray(),
cipherState.DecryptKey);
}
if (decrypted.Length < 2) throw new InvalidDataException("Decrypted payload too short");
msgType = (MessageType)decrypted[0];
int innerComp = decrypted[1];
var innerPayload = new byte[decrypted.Length - 2];
Buffer.BlockCopy(decrypted, 2, innerPayload, 0, innerPayload.Length);
if (innerComp == 0x01)
{
innerPayload = CompressionHelper.Decompress(innerPayload);
}
return (msgType, innerPayload);
}
// Handle Unencrypted Compression
if (compByte == 0x01)
{
payload = CompressionHelper.Decompress(payload);
}
_logger.LogDebug("Read Message {Type}, Size: {Size}", msgType, payload.Length);
return (msgType, payload);
}
finally
{
_readLock.Release();
double ratio = (double)payloadBytes.Length / originalSize;
_telemetry.RecordValue(MetricType.CompressionRatio, ratio);
}
}
private async Task<int> ReadExactAsync(Stream stream, byte[] buffer, int offset, int count, CancellationToken token)
{
int total = 0;
while (total < count)
{
int read = await stream.ReadAsync(buffer, offset + total, count - total, token);
if (read == 0) return 0; // EOF
total += read;
}
return total;
}
private sealed class ForwardingLogger : ILogger<ProtocolHandler>
{
private readonly ILogger _inner;
/// <summary>
/// Initializes a new instance of the <see cref="ForwardingLogger"/> class.
/// </summary>
/// <param name="inner">The underlying logger instance.</param>
public ForwardingLogger(ILogger inner)
{
_inner = inner ?? throw new ArgumentNullException(nameof(inner));
}
/// <inheritdoc />
public IDisposable? BeginScope<TState>(TState state) where TState : notnull
{
return _inner.BeginScope(state);
}
/// <inheritdoc />
public bool IsEnabled(LogLevel logLevel)
{
return _inner.IsEnabled(logLevel);
}
/// <inheritdoc />
public void Log<TState>(
LogLevel logLevel,
EventId eventId,
TState state,
Exception? exception,
Func<TState, Exception?, string> formatter)
{
_inner.Log(logLevel, eventId, state, exception, formatter);
}
}
}
}
// 3. Encrypt
if (cipherState != null)
using (_telemetry?.StartMetric(MetricType.EncryptionTime))
{
// Inner data: [Type (1)] [Compression (1)] [Payload (N)]
var dataToEncrypt = new byte[2 + payloadBytes.Length];
dataToEncrypt[0] = (byte)type;
dataToEncrypt[1] = compressionFlag;
Buffer.BlockCopy(payloadBytes, 0, dataToEncrypt, 2, payloadBytes.Length);
(byte[] ciphertext, byte[] iv, byte[] tag) =
CryptoHelper.Encrypt(dataToEncrypt, cipherState.EncryptKey);
var env = new SecureEnvelope
{
Ciphertext = ByteString.CopyFrom(ciphertext),
Nonce = ByteString.CopyFrom(iv),
AuthTag = ByteString.CopyFrom(tag)
};
payloadBytes = env.ToByteArray();
type = MessageType.SecureEnv;
compressionFlag = 0x00; // Outer envelope is not compressed
}
// 4. Thread-Safe Write
await _writeLock.WaitAsync(token);
try
{
_logger.LogDebug("Sending Message {Type}, OrgSize: {Org}, WireSize: {Wire}", type, originalSize,
payloadBytes.Length);
// Framing: [Length (4)] [Type (1)] [Compression (1)] [Payload (N)]
byte[] lengthBytes = BitConverter.GetBytes(payloadBytes.Length);
await stream.WriteAsync(lengthBytes, 0, 4, token);
stream.WriteByte((byte)type);
stream.WriteByte(compressionFlag);
await stream.WriteAsync(payloadBytes, 0, payloadBytes.Length, token);
await stream.FlushAsync(token);
}
finally
{
_writeLock.Release();
}
}
/// <summary>
/// Reads and decodes the next protocol message from the provided stream.
/// </summary>
/// <param name="stream">The source stream.</param>
/// <param name="cipherState">Optional cipher state used to decrypt incoming payloads.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>A tuple containing the decoded message type and payload bytes.</returns>
public async Task<(MessageType, byte[])> ReadMessageAsync(Stream stream, CipherState? cipherState,
CancellationToken token = default)
{
await _readLock.WaitAsync(token);
try
{
var lenBuf = new byte[4];
int read = await ReadExactAsync(stream, lenBuf, 0, 4, token);
if (read == 0) return (MessageType.Unknown, null!);
var length = BitConverter.ToInt32(lenBuf, 0);
int typeByte = stream.ReadByte();
if (typeByte == -1) throw new EndOfStreamException("Connection closed abruptly (type byte)");
int compByte = stream.ReadByte();
if (compByte == -1) throw new EndOfStreamException("Connection closed abruptly (comp byte)");
var payload = new byte[length];
await ReadExactAsync(stream, payload, 0, length, token);
var msgType = (MessageType)typeByte;
// Handle Secure Envelope
if (msgType == MessageType.SecureEnv)
{
if (cipherState == null)
throw new InvalidOperationException("Received encrypted message but no cipher state established");
byte[] decrypted;
using (_telemetry?.StartMetric(MetricType.DecryptionTime))
{
var env = SecureEnvelope.Parser.ParseFrom(payload);
decrypted = CryptoHelper.Decrypt(
env.Ciphertext.ToByteArray(),
env.Nonce.ToByteArray(),
env.AuthTag.ToByteArray(),
cipherState.DecryptKey);
}
if (decrypted.Length < 2) throw new InvalidDataException("Decrypted payload too short");
msgType = (MessageType)decrypted[0];
int innerComp = decrypted[1];
var innerPayload = new byte[decrypted.Length - 2];
Buffer.BlockCopy(decrypted, 2, innerPayload, 0, innerPayload.Length);
if (innerComp == 0x01) innerPayload = CompressionHelper.Decompress(innerPayload);
return (msgType, innerPayload);
}
// Handle Unencrypted Compression
if (compByte == 0x01) payload = CompressionHelper.Decompress(payload);
_logger.LogDebug("Read Message {Type}, Size: {Size}", msgType, payload.Length);
return (msgType, payload);
}
finally
{
_readLock.Release();
}
}
private async Task<int> ReadExactAsync(Stream stream, byte[] buffer, int offset, int count, CancellationToken token)
{
var total = 0;
while (total < count)
{
int read = await stream.ReadAsync(buffer, offset + total, count - total, token);
if (read == 0) return 0; // EOF
total += read;
}
return total;
}
private sealed class ForwardingLogger : ILogger<ProtocolHandler>
{
private readonly ILogger _inner;
/// <summary>
/// Initializes a new instance of the <see cref="ForwardingLogger" /> class.
/// </summary>
/// <param name="inner">The underlying logger instance.</param>
public ForwardingLogger(ILogger inner)
{
_inner = inner ?? throw new ArgumentNullException(nameof(inner));
}
/// <inheritdoc />
public IDisposable? BeginScope<TState>(TState state) where TState : notnull
{
return _inner.BeginScope(state);
}
/// <inheritdoc />
public bool IsEnabled(LogLevel logLevel)
{
return _inner.IsEnabled(logLevel);
}
/// <inheritdoc />
public void Log<TState>(
LogLevel logLevel,
EventId eventId,
TState state,
Exception? exception,
Func<TState, Exception?, string> formatter)
{
_inner.Log(logLevel, eventId, state, exception, formatter);
}
}
}

3
src/ZB.MOM.WW.CBDDC.Network/README.md
View File

@@ -48,12 +48,15 @@ node.Start();
## Features
### Automatic Discovery
Nodes broadcast their presence via UDP and automatically connect to peers on the same network.
### Secure Synchronization
All nodes must share the same authentication token to sync data.
### Scalable Gossip
Updates propagate exponentially - each node tells multiple peers, ensuring fast network-wide propagation.
## Documentation

29
src/ZB.MOM.WW.CBDDC.Network/Security/ClusterKeyAuthenticator.cs
View File

@@ -1,20 +1,19 @@
using ZB.MOM.WW.CBDDC.Core.Network;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using System.Security.Cryptography;
using System.Text;
using ZB.MOM.WW.CBDDC.Core.Network;
namespace ZB.MOM.WW.CBDDC.Network.Security;
/// <summary>
/// Authenticator implementation that uses a shared secret (pre-shared key) to validate nodes.
/// Both nodes must possess the same key to successfully handshake.
/// Authenticator implementation that uses a shared secret (pre-shared key) to validate nodes.
/// Both nodes must possess the same key to successfully handshake.
/// </summary>
public class ClusterKeyAuthenticator : IAuthenticator
{
private readonly IPeerNodeConfigurationProvider _peerNodeConfigurationProvider;
/// <summary>
/// Initializes a new instance of the <see cref="ClusterKeyAuthenticator"/> class.
/// Initializes a new instance of the <see cref="ClusterKeyAuthenticator" /> class.
/// </summary>
/// <param name="peerNodeConfigurationProvider">The provider for peer node configuration.</param>
public ClusterKeyAuthenticator(IPeerNodeConfigurationProvider peerNodeConfigurationProvider)
@@ -23,11 +22,11 @@ public class ClusterKeyAuthenticator : IAuthenticator
}
/// <inheritdoc />
public async Task<bool> ValidateAsync(string nodeId, string token)
{
var config = await _peerNodeConfigurationProvider.GetConfiguration();
var configuredHash = SHA256.HashData(Encoding.UTF8.GetBytes(config.AuthToken ?? string.Empty));
var presentedHash = SHA256.HashData(Encoding.UTF8.GetBytes(token ?? string.Empty));
return CryptographicOperations.FixedTimeEquals(configuredHash, presentedHash);
}
}
public async Task<bool> ValidateAsync(string nodeId, string token)
{
var config = await _peerNodeConfigurationProvider.GetConfiguration();
byte[] configuredHash = SHA256.HashData(Encoding.UTF8.GetBytes(config.AuthToken ?? string.Empty));
byte[] presentedHash = SHA256.HashData(Encoding.UTF8.GetBytes(token ?? string.Empty));
return CryptographicOperations.FixedTimeEquals(configuredHash, presentedHash);
}
}

66
src/ZB.MOM.WW.CBDDC.Network/Security/CryptoHelper.cs
View File

@@ -1,30 +1,28 @@
using System;
using System.IO;
using System.Security.Cryptography;
namespace ZB.MOM.WW.CBDDC.Network.Security;
public static class CryptoHelper
{
public static class CryptoHelper
{
private const int KeySize = 32; // 256 bits
private const int BlockSize = 16; // 128 bits
private const int MacSize = 32; // 256 bits (HMACSHA256)
/// <summary>
/// Encrypts plaintext and computes an authentication tag.
/// </summary>
/// <param name="plaintext">The plaintext bytes to encrypt.</param>
/// <param name="key">The encryption and HMAC key.</param>
/// <returns>The ciphertext, IV, and authentication tag.</returns>
public static (byte[] ciphertext, byte[] iv, byte[] tag) Encrypt(byte[] plaintext, byte[] key)
{
private const int BlockSize = 16; // 128 bits
private const int MacSize = 32; // 256 bits (HMACSHA256)
/// <summary>
/// Encrypts plaintext and computes an authentication tag.
/// </summary>
/// <param name="plaintext">The plaintext bytes to encrypt.</param>
/// <param name="key">The encryption and HMAC key.</param>
/// <returns>The ciphertext, IV, and authentication tag.</returns>
public static (byte[] ciphertext, byte[] iv, byte[] tag) Encrypt(byte[] plaintext, byte[] key)
{
using var aes = Aes.Create();
aes.Key = key;
aes.GenerateIV();
var iv = aes.IV;
byte[] iv = aes.IV;
using var encryptor = aes.CreateEncryptor();
var ciphertext = encryptor.TransformFinalBlock(plaintext, 0, plaintext.Length);
byte[] ciphertext = encryptor.TransformFinalBlock(plaintext, 0, plaintext.Length);
// Compute HMAC
using var hmac = new HMACSHA256(key);
@@ -32,32 +30,30 @@ public static class CryptoHelper
var toSign = new byte[iv.Length + ciphertext.Length];
Buffer.BlockCopy(iv, 0, toSign, 0, iv.Length);
Buffer.BlockCopy(ciphertext, 0, toSign, iv.Length, ciphertext.Length);
var tag = hmac.ComputeHash(toSign);
byte[] tag = hmac.ComputeHash(toSign);
return (ciphertext, iv, tag);
}
/// <summary>
/// Verifies and decrypts ciphertext.
/// </summary>
/// <param name="ciphertext">The encrypted bytes.</param>
/// <param name="iv">The initialization vector used during encryption.</param>
/// <param name="tag">The authentication tag for integrity verification.</param>
/// <param name="key">The encryption and HMAC key.</param>
/// <returns>The decrypted plaintext bytes.</returns>
public static byte[] Decrypt(byte[] ciphertext, byte[] iv, byte[] tag, byte[] key)
{
return (ciphertext, iv, tag);
}
/// <summary>
/// Verifies and decrypts ciphertext.
/// </summary>
/// <param name="ciphertext">The encrypted bytes.</param>
/// <param name="iv">The initialization vector used during encryption.</param>
/// <param name="tag">The authentication tag for integrity verification.</param>
/// <param name="key">The encryption and HMAC key.</param>
/// <returns>The decrypted plaintext bytes.</returns>
public static byte[] Decrypt(byte[] ciphertext, byte[] iv, byte[] tag, byte[] key)
{
// Verify HMAC
using var hmac = new HMACSHA256(key);
var toVerify = new byte[iv.Length + ciphertext.Length];
Buffer.BlockCopy(iv, 0, toVerify, 0, iv.Length);
Buffer.BlockCopy(ciphertext, 0, toVerify, iv.Length, ciphertext.Length);
var computedTag = hmac.ComputeHash(toVerify);
byte[] computedTag = hmac.ComputeHash(toVerify);
if (!FixedTimeEquals(tag, computedTag))
{
throw new CryptographicException("Authentication failed (HMAC mismatch)");
}
using var aes = Aes.Create();
aes.Key = key;
@@ -78,4 +74,4 @@ public static class CryptoHelper
return res == 0;
#endif
}
}
}

12
src/ZB.MOM.WW.CBDDC.Network/Security/IAuthenticator.cs
View File

@@ -1,14 +1,12 @@
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Network.Security;
namespace ZB.MOM.WW.CBDDC.Network.Security;
public interface IAuthenticator
{
/// <summary>
/// Validates an authentication token for a node identifier.
/// Validates an authentication token for a node identifier.
/// </summary>
/// <param name="nodeId">The node identifier to validate.</param>
/// <param name="token">The authentication token to validate.</param>
/// <returns><see langword="true"/> if the token is valid for the node; otherwise <see langword="false"/>.</returns>
/// <returns><see langword="true" /> if the token is valid for the node; otherwise <see langword="false" />.</returns>
Task<bool> ValidateAsync(string nodeId, string token);
}
}

33
src/ZB.MOM.WW.CBDDC.Network/Security/IPeerHandshakeService.cs
View File

@@ -1,36 +1,25 @@
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Network.Security;
namespace ZB.MOM.WW.CBDDC.Network.Security;
public interface IPeerHandshakeService
{
/// <summary>
/// Performs a handshake to establishing identity and optional security context.
/// Performs a handshake to establishing identity and optional security context.
/// </summary>
/// <param name="stream">The transport stream used for handshake message exchange.</param>
/// <param name="isInitiator">A value indicating whether the caller initiated the connection.</param>
/// <param name="myNodeId">The local node identifier.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>A CipherState if encryption is established, or null if plaintext.</returns>
Task<CipherState?> HandshakeAsync(System.IO.Stream stream, bool isInitiator, string myNodeId, CancellationToken token);
Task<CipherState?> HandshakeAsync(Stream stream, bool isInitiator, string myNodeId, CancellationToken token);
}
public class CipherState
{
/// <summary>
/// Gets the key used to encrypt outgoing messages.
/// </summary>
public byte[] EncryptKey { get; }
/// <summary>
/// Gets the key used to decrypt incoming messages.
/// </summary>
public byte[] DecryptKey { get; }
// For simplicity using IV chaining or explicit IVs.
// We'll store just the keys here and let the encryption helper handle IVs.
/// <summary>
/// Initializes a new instance of the <see cref="CipherState"/> class.
/// Initializes a new instance of the <see cref="CipherState" /> class.
/// </summary>
/// <param name="encryptKey">The key used for encrypting outgoing payloads.</param>
/// <param name="decryptKey">The key used for decrypting incoming payloads.</param>
@@ -39,4 +28,14 @@ public class CipherState
EncryptKey = encryptKey;
DecryptKey = decryptKey;
}
}
/// <summary>
/// Gets the key used to encrypt outgoing messages.
/// </summary>
public byte[] EncryptKey { get; }
/// <summary>
/// Gets the key used to decrypt incoming messages.
/// </summary>
public byte[] DecryptKey { get; }
}

31
src/ZB.MOM.WW.CBDDC.Network/Security/NoOpHandshakeService.cs
View File

@@ -1,29 +1,32 @@
using System.IO;
using System.Threading;
using System.Threading.Tasks;
namespace ZB.MOM.WW.CBDDC.Network.Security;
/// <summary>
/// Provides a no-operation implementation of the peer handshake service that performs no handshake and always returns
/// null.
/// Provides a no-operation implementation of the peer handshake service that performs no handshake and always returns
/// null.
/// </summary>
/// <remarks>This class can be used in scenarios where a handshake is not required or for testing purposes. All
/// handshake attempts using this service will result in no cipher state being established.</remarks>
/// <remarks>
/// This class can be used in scenarios where a handshake is not required or for testing purposes. All
/// handshake attempts using this service will result in no cipher state being established.
/// </remarks>
public class NoOpHandshakeService : IPeerHandshakeService
{
/// <summary>
/// Performs a handshake over the specified stream to establish a secure communication channel between two nodes
/// asynchronously.
/// Performs a handshake over the specified stream to establish a secure communication channel between two nodes
/// asynchronously.
/// </summary>
/// <param name="stream">The stream used for exchanging handshake messages between nodes. Must be readable and writable.</param>
/// <param name="isInitiator">true to initiate the handshake as the local node; otherwise, false to respond as the remote node.</param>
/// <param name="isInitiator">
/// true to initiate the handshake as the local node; otherwise, false to respond as the remote
/// node.
/// </param>
/// <param name="myNodeId">The unique identifier of the local node participating in the handshake. Cannot be null.</param>
/// <param name="token">A cancellation token that can be used to cancel the handshake operation.</param>
/// <returns>A task that represents the asynchronous handshake operation. The task result contains a CipherState if the
/// handshake succeeds; otherwise, null.</returns>
/// <returns>
/// A task that represents the asynchronous handshake operation. The task result contains a CipherState if the
/// handshake succeeds; otherwise, null.
/// </returns>
public Task<CipherState?> HandshakeAsync(Stream stream, bool isInitiator, string myNodeId, CancellationToken token)
{
return Task.FromResult<CipherState?>(null);
}
}
}

121
src/ZB.MOM.WW.CBDDC.Network/Security/SecureHandshakeService.cs
View File

@@ -1,8 +1,4 @@
using System;
using System.IO;
using System.Security.Cryptography;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
namespace ZB.MOM.WW.CBDDC.Network.Security;
@@ -12,7 +8,7 @@ public class SecureHandshakeService : IPeerHandshakeService
private readonly ILogger<SecureHandshakeService>? _logger;
/// <summary>
/// Initializes a new instance of the <see cref="SecureHandshakeService"/> class.
/// Initializes a new instance of the <see cref="SecureHandshakeService" /> class.
/// </summary>
/// <param name="logger">The optional logger instance.</param>
public SecureHandshakeService(ILogger<SecureHandshakeService>? logger = null)
@@ -26,44 +22,42 @@ public class SecureHandshakeService : IPeerHandshakeService
// Both derive shared secret -> Split into SendKey/RecvKey using HKDF
/// <summary>
/// Performs a secure key exchange handshake over the provided stream.
/// Performs a secure key exchange handshake over the provided stream.
/// </summary>
/// <param name="stream">The transport stream used for the handshake.</param>
/// <param name="isInitiator">A value indicating whether the local node initiated the handshake.</param>
/// <param name="myNodeId">The local node identifier.</param>
/// <param name="token">A token used to cancel the handshake.</param>
/// <returns>
/// A task that returns the negotiated <see cref="CipherState"/>, or <see langword="null"/> if unavailable.
/// A task that returns the negotiated <see cref="CipherState" />, or <see langword="null" /> if unavailable.
/// </returns>
public async Task<CipherState?> HandshakeAsync(Stream stream, bool isInitiator, string myNodeId, CancellationToken token)
public async Task<CipherState?> HandshakeAsync(Stream stream, bool isInitiator, string myNodeId,
CancellationToken token)
{
#if NET6_0_OR_GREATER
using var ecdh = ECDiffieHellman.Create();
ecdh.KeySize = 256;
// 1. ExportAsync & Send Public Key
var myPublicKey = ecdh.ExportSubjectPublicKeyInfo();
var lenBytes = BitConverter.GetBytes(myPublicKey.Length);
await stream.WriteAsync(lenBytes, 0, 4, token);
await stream.WriteAsync(myPublicKey, 0, myPublicKey.Length, token);
await stream.FlushAsync(token); // CRITICAL: Ensure data is sent immediately
// 2. Receive Peer Public Key
var peerLenBuf = new byte[4];
await ReadExactAsync(stream, peerLenBuf, 0, 4, token);
int peerLen = BitConverter.ToInt32(peerLenBuf, 0);
using var ecdh = ECDiffieHellman.Create();
ecdh.KeySize = 256;
// 1. ExportAsync & Send Public Key
byte[] myPublicKey = ecdh.ExportSubjectPublicKeyInfo();
byte[] lenBytes = BitConverter.GetBytes(myPublicKey.Length);
await stream.WriteAsync(lenBytes, 0, 4, token);
await stream.WriteAsync(myPublicKey, 0, myPublicKey.Length, token);
await stream.FlushAsync(token); // CRITICAL: Ensure data is sent immediately
// 2. Receive Peer Public Key
var peerLenBuf = new byte[4];
await ReadExactAsync(stream, peerLenBuf, 0, 4, token);
var peerLen = BitConverter.ToInt32(peerLenBuf, 0);
// Validate peer key length to prevent DoS
if (peerLen <= 0 || peerLen > 10000)
{
throw new InvalidOperationException($"Invalid peer key length: {peerLen}");
}
var peerKeyBytes = new byte[peerLen];
await ReadExactAsync(stream, peerKeyBytes, 0, peerLen, token);
// 3. Import Peer Key & Derive Shared Secret
using var peerEcdh = ECDiffieHellman.Create();
if (peerLen <= 0 || peerLen > 10000) throw new InvalidOperationException($"Invalid peer key length: {peerLen}");
var peerKeyBytes = new byte[peerLen];
await ReadExactAsync(stream, peerKeyBytes, 0, peerLen, token);
// 3. Import Peer Key & Derive Shared Secret
using var peerEcdh = ECDiffieHellman.Create();
peerEcdh.ImportSubjectPublicKeyInfo(peerKeyBytes, out _);
byte[] sharedSecret = ecdh.DeriveKeyMaterial(peerEcdh.PublicKey);
@@ -74,39 +68,40 @@ public class SecureHandshakeService : IPeerHandshakeService
using var sha = SHA256.Create();
var k1Input = new byte[sharedSecret.Length + 1];
Buffer.BlockCopy(sharedSecret, 0, k1Input, 0, sharedSecret.Length);
k1Input[sharedSecret.Length] = 0; // "0"
var key1 = sha.ComputeHash(k1Input);
var k1Input = new byte[sharedSecret.Length + 1];
Buffer.BlockCopy(sharedSecret, 0, k1Input, 0, sharedSecret.Length);
k1Input[sharedSecret.Length] = 0; // "0"
byte[] key1 = sha.ComputeHash(k1Input);
var k2Input = new byte[sharedSecret.Length + 1];
Buffer.BlockCopy(sharedSecret, 0, k2Input, 0, sharedSecret.Length);
k2Input[sharedSecret.Length] = 1; // "1"
var key2 = sha.ComputeHash(k2Input);
var k2Input = new byte[sharedSecret.Length + 1];
Buffer.BlockCopy(sharedSecret, 0, k2Input, 0, sharedSecret.Length);
k2Input[sharedSecret.Length] = 1; // "1"
byte[] key2 = sha.ComputeHash(k2Input);
// If initiator: Encrypt with Key1, Decrypt with Key2
// If responder: Encrypt with Key2, Decrypt with Key1
var encryptKey = isInitiator ? key1 : key2;
var decryptKey = isInitiator ? key2 : key1;
return new CipherState(encryptKey, decryptKey);
#else
// For netstandard2.0, standard ECDH import is broken/hard without external libs.
// Returning null or throwing.
throw new PlatformNotSupportedException("Secure handshake requires .NET 6.0+");
#endif
}
private async Task<int> ReadExactAsync(Stream stream, byte[] buffer, int offset, int count, CancellationToken token)
{
int total = 0;
while (total < count)
{
int read = await stream.ReadAsync(buffer, offset + total, count - total, token);
if (read == 0) throw new EndOfStreamException();
total += read;
}
return total;
}
}
byte[] encryptKey = isInitiator ? key1 : key2;
byte[] decryptKey = isInitiator ? key2 : key1;
return new CipherState(encryptKey, decryptKey);
#else
// For netstandard2.0, standard ECDH import is broken/hard without external libs.
// Returning null or throwing.
throw new PlatformNotSupportedException("Secure handshake requires .NET 6.0+");
#endif
}
private async Task<int> ReadExactAsync(Stream stream, byte[] buffer, int offset, int count, CancellationToken token)
{
var total = 0;
while (total < count)
{
int read = await stream.ReadAsync(buffer, offset + total, count - total, token);
if (read == 0) throw new EndOfStreamException();
total += read;
}
return total;
}
}

1008
src/ZB.MOM.WW.CBDDC.Network/SyncOrchestrator.cs
View File

File diff suppressed because it is too large Load Diff

576
src/ZB.MOM.WW.CBDDC.Network/TcpPeerClient.cs
View File

@@ -1,44 +1,60 @@
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Sockets;
using System.Threading;
using System.Threading.Tasks;
using Google.Protobuf;
using System.Text.Json;
using Microsoft.Extensions.Logging;
using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Network.Proto;
using ZB.MOM.WW.CBDDC.Network.Security;
using ZB.MOM.WW.CBDDC.Network.Protocol;
using ZB.MOM.WW.CBDDC.Network.Security;
using ZB.MOM.WW.CBDDC.Network.Telemetry;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Represents a TCP client connection to a remote peer for synchronization.
/// Represents a TCP client connection to a remote peer for synchronization.
/// </summary>
public class TcpPeerClient : IDisposable
{
private readonly TcpClient _client;
private readonly string _peerAddress;
private readonly ILogger<TcpPeerClient> _logger;
private readonly IPeerHandshakeService? _handshakeService;
private NetworkStream? _stream;
private CipherState? _cipherState;
private readonly object _connectionLock = new object();
private bool _disposed = false;
public class TcpPeerClient : IDisposable
{
private const int ConnectionTimeoutMs = 5000;
private const int OperationTimeoutMs = 30000;
private readonly ProtocolHandler _protocol;
/// <summary>
/// Gets a value indicating whether the client currently has an active connection.
/// </summary>
public bool IsConnected
{
private const int OperationTimeoutMs = 30000;
private readonly TcpClient _client;
private readonly object _connectionLock = new();
private readonly IPeerHandshakeService? _handshakeService;
private readonly ILogger<TcpPeerClient> _logger;
private readonly string _peerAddress;
private readonly ProtocolHandler _protocol;
private readonly INetworkTelemetryService? _telemetry;
private CipherState? _cipherState;
private bool _disposed;
private List<string> _remoteInterests = new();
private NetworkStream? _stream;
private bool _useCompression; // Negotiated after handshake
/// <summary>
/// Initializes a new instance of the <see cref="TcpPeerClient" /> class.
/// </summary>
/// <param name="peerAddress">The remote peer address in <c>host:port</c> format.</param>
/// <param name="logger">The logger used for connection and protocol events.</param>
/// <param name="handshakeService">The optional handshake service used to establish secure sessions.</param>
/// <param name="telemetry">The optional telemetry service for network metrics.</param>
public TcpPeerClient(string peerAddress, ILogger<TcpPeerClient> logger,
IPeerHandshakeService? handshakeService = null, INetworkTelemetryService? telemetry = null)
{
_client = new TcpClient();
_peerAddress = peerAddress;
_logger = logger;
_handshakeService = handshakeService;
_telemetry = telemetry;
_protocol = new ProtocolHandler(logger, telemetry);
}
/// <summary>
/// Gets a value indicating whether the client currently has an active connection.
/// </summary>
public bool IsConnected
{
get
{
lock (_connectionLock)
@@ -46,89 +62,97 @@ public class TcpPeerClient : IDisposable
return _client != null && _client.Connected && _stream != null && !_disposed;
}
}
}
/// <summary>
/// Gets a value indicating whether the handshake with the remote peer has completed successfully.
/// </summary>
public bool HasHandshaked { get; private set; }
private readonly INetworkTelemetryService? _telemetry;
/// <summary>
/// Initializes a new instance of the <see cref="TcpPeerClient"/> class.
/// </summary>
/// <param name="peerAddress">The remote peer address in <c>host:port</c> format.</param>
/// <param name="logger">The logger used for connection and protocol events.</param>
/// <param name="handshakeService">The optional handshake service used to establish secure sessions.</param>
/// <param name="telemetry">The optional telemetry service for network metrics.</param>
public TcpPeerClient(string peerAddress, ILogger<TcpPeerClient> logger, IPeerHandshakeService? handshakeService = null, INetworkTelemetryService? telemetry = null)
{
_client = new TcpClient();
_peerAddress = peerAddress;
_logger = logger;
_handshakeService = handshakeService;
_telemetry = telemetry;
_protocol = new ProtocolHandler(logger, telemetry);
}
/// <summary>
/// Connects to the configured remote peer.
/// </summary>
/// <param name="token">A token used to cancel the connection attempt.</param>
/// <returns>A task that represents the asynchronous connect operation.</returns>
public async Task ConnectAsync(CancellationToken token)
{
}
/// <summary>
/// Gets a value indicating whether the handshake with the remote peer has completed successfully.
/// </summary>
public bool HasHandshaked { get; private set; }
/// <summary>
/// Gets the list of collections the remote peer is interested in.
/// </summary>
public IReadOnlyList<string> RemoteInterests => _remoteInterests.AsReadOnly();
/// <summary>
/// Releases resources used by the peer client.
/// </summary>
public void Dispose()
{
lock (_connectionLock)
{
if (_disposed)
{
throw new ObjectDisposedException(nameof(TcpPeerClient));
}
if (_disposed) return;
_disposed = true;
}
try
{
_stream?.Dispose();
}
catch (Exception ex)
{
_logger.LogWarning(ex, "Error disposing network stream");
}
try
{
_client?.Dispose();
}
catch (Exception ex)
{
_logger.LogWarning(ex, "Error disposing TCP client");
}
_logger.LogDebug("Disposed connection to peer: {Address}", _peerAddress);
}
/// <summary>
/// Connects to the configured remote peer.
/// </summary>
/// <param name="token">A token used to cancel the connection attempt.</param>
/// <returns>A task that represents the asynchronous connect operation.</returns>
public async Task ConnectAsync(CancellationToken token)
{
lock (_connectionLock)
{
if (_disposed) throw new ObjectDisposedException(nameof(TcpPeerClient));
if (IsConnected) return;
}
var parts = _peerAddress.Split(':');
string[] parts = _peerAddress.Split(':');
if (parts.Length != 2)
{
throw new ArgumentException($"Invalid address format: {_peerAddress}. Expected format: host:port");
}
if (!int.TryParse(parts[1], out int port) || port <= 0 || port > 65535)
{
throw new ArgumentException($"Invalid port number: {parts[1]}");
}
// Connect with timeout
using var timeoutCts = new CancellationTokenSource(ConnectionTimeoutMs);
using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(token, timeoutCts.Token);
using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(token, timeoutCts.Token);
try
{
await _client.ConnectAsync(parts[0], port);
await _client.ConnectAsync(parts[0], port);
lock (_connectionLock)
{
if (_disposed)
{
throw new ObjectDisposedException(nameof(TcpPeerClient));
}
_stream = _client.GetStream();
// CRITICAL for Android: Disable Nagle's algorithm to prevent buffering delays
// This ensures immediate packet transmission for handshake data
_client.NoDelay = true;
// Configure TCP keepalive
_client.Client.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.KeepAlive, true);
// Set read/write timeouts
if (_disposed) throw new ObjectDisposedException(nameof(TcpPeerClient));
_stream = _client.GetStream();
// CRITICAL for Android: Disable Nagle's algorithm to prevent buffering delays
// This ensures immediate packet transmission for handshake data
_client.NoDelay = true;
// Configure TCP keepalive
_client.Client.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.KeepAlive, true);
// Set read/write timeouts
_stream.ReadTimeout = OperationTimeoutMs;
_stream.WriteTimeout = OperationTimeoutMs;
}
}
_logger.LogDebug("Connected to peer: {Address} (NoDelay=true for immediate send)", _peerAddress);
}
catch (OperationCanceledException) when (timeoutCts.IsCancellationRequested)
@@ -138,13 +162,7 @@ public class TcpPeerClient : IDisposable
}
/// <summary>
/// Gets the list of collections the remote peer is interested in.
/// </summary>
public System.Collections.Generic.IReadOnlyList<string> RemoteInterests => _remoteInterests.AsReadOnly();
private List<string> _remoteInterests = new();
/// <summary>
/// Performs authentication handshake with the remote peer.
/// Performs authentication handshake with the remote peer.
/// </summary>
/// <param name="myNodeId">The local node identifier.</param>
/// <param name="authToken">The authentication token.</param>
@@ -155,46 +173,38 @@ public class TcpPeerClient : IDisposable
return await HandshakeAsync(myNodeId, authToken, null, token);
}
/// <summary>
/// Performs authentication handshake with the remote peer, including collection interests.
/// </summary>
/// <param name="myNodeId">The local node identifier.</param>
/// <param name="authToken">The authentication token.</param>
/// <param name="interestingCollections">Optional collection names this node is interested in receiving.</param>
/// <param name="token">Cancellation token.</param>
/// <returns><see langword="true"/> if handshake was accepted; otherwise <see langword="false"/>.</returns>
public async Task<bool> HandshakeAsync(string myNodeId, string authToken, IEnumerable<string>? interestingCollections, CancellationToken token)
{
/// <summary>
/// Performs authentication handshake with the remote peer, including collection interests.
/// </summary>
/// <param name="myNodeId">The local node identifier.</param>
/// <param name="authToken">The authentication token.</param>
/// <param name="interestingCollections">Optional collection names this node is interested in receiving.</param>
/// <param name="token">Cancellation token.</param>
/// <returns><see langword="true" /> if handshake was accepted; otherwise <see langword="false" />.</returns>
public async Task<bool> HandshakeAsync(string myNodeId, string authToken,
IEnumerable<string>? interestingCollections, CancellationToken token)
{
if (HasHandshaked) return true;
if (_handshakeService != null)
{
// Perform secure handshake if service is available
// We assume we are initiator here
_cipherState = await _handshakeService.HandshakeAsync(_stream!, true, myNodeId, token);
}
var req = new HandshakeRequest { NodeId = myNodeId, AuthToken = authToken ?? "" };
if (interestingCollections != null)
{
foreach (var coll in interestingCollections)
{
foreach (string coll in interestingCollections)
req.InterestingCollections.Add(coll);
}
}
if (CompressionHelper.IsBrotliSupported)
{
req.SupportedCompression.Add("brotli");
}
if (CompressionHelper.IsBrotliSupported) req.SupportedCompression.Add("brotli");
_logger.LogDebug("Sending HandshakeReq to {Address}", _peerAddress);
await _protocol.SendMessageAsync(_stream!, MessageType.HandshakeReq, req, false, _cipherState, token);
var (type, payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
_logger.LogDebug("Received Handshake response type: {Type}", type);
(var type, byte[] payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
_logger.LogDebug("Received Handshake response type: {Type}", type);
if (type != MessageType.HandshakeRes) return false;
var res = HandshakeResponse.Parser.ParseFrom(payload);
@@ -213,18 +223,19 @@ public class TcpPeerClient : IDisposable
return res.Accepted;
}
/// <summary>
/// Retrieves the remote peer's latest HLC timestamp.
/// </summary>
/// <param name="token">Cancellation token.</param>
/// <returns>The latest remote hybrid logical clock timestamp.</returns>
public async Task<HlcTimestamp> GetClockAsync(CancellationToken token)
{
/// <summary>
/// Retrieves the remote peer's latest HLC timestamp.
/// </summary>
/// <param name="token">Cancellation token.</param>
/// <returns>The latest remote hybrid logical clock timestamp.</returns>
public async Task<HlcTimestamp> GetClockAsync(CancellationToken token)
{
using (_telemetry?.StartMetric(MetricType.RoundTripTime))
{
await _protocol.SendMessageAsync(_stream!, MessageType.GetClockReq, new GetClockRequest(), _useCompression, _cipherState, token);
await _protocol.SendMessageAsync(_stream!, MessageType.GetClockReq, new GetClockRequest(), _useCompression,
_cipherState, token);
var (type, payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
(var type, byte[] payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
if (type != MessageType.ClockRes) throw new Exception("Unexpected response");
var res = ClockResponse.Parser.ParseFrom(payload);
@@ -232,69 +243,67 @@ public class TcpPeerClient : IDisposable
}
}
/// <summary>
/// Retrieves the remote peer's vector clock (latest timestamp per node).
/// </summary>
/// <param name="token">Cancellation token.</param>
/// <returns>The remote vector clock.</returns>
public async Task<VectorClock> GetVectorClockAsync(CancellationToken token)
{
/// <summary>
/// Retrieves the remote peer's vector clock (latest timestamp per node).
/// </summary>
/// <param name="token">Cancellation token.</param>
/// <returns>The remote vector clock.</returns>
public async Task<VectorClock> GetVectorClockAsync(CancellationToken token)
{
using (_telemetry?.StartMetric(MetricType.RoundTripTime))
{
await _protocol.SendMessageAsync(_stream!, MessageType.GetVectorClockReq, new GetVectorClockRequest(), _useCompression, _cipherState, token);
await _protocol.SendMessageAsync(_stream!, MessageType.GetVectorClockReq, new GetVectorClockRequest(),
_useCompression, _cipherState, token);
var (type, payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
(var type, byte[] payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
if (type != MessageType.VectorClockRes) throw new Exception("Unexpected response");
var res = VectorClockResponse.Parser.ParseFrom(payload);
var vectorClock = new VectorClock();
foreach (var entry in res.Entries)
{
vectorClock.SetTimestamp(entry.NodeId, new HlcTimestamp(entry.HlcWall, entry.HlcLogic, entry.NodeId));
}
return vectorClock;
}
}
/// <summary>
/// Pulls oplog changes from the remote peer since the specified timestamp.
/// </summary>
/// <param name="since">The starting timestamp for requested changes.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>The list of oplog entries returned by the remote peer.</returns>
public async Task<List<OplogEntry>> PullChangesAsync(HlcTimestamp since, CancellationToken token)
{
return await PullChangesAsync(since, null, token);
}
/// <summary>
/// Pulls oplog changes from the remote peer since the specified timestamp, filtered by collections.
/// </summary>
/// <param name="since">The starting timestamp for requested changes.</param>
/// <param name="collections">Optional collection names used to filter the returned entries.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>The list of oplog entries returned by the remote peer.</returns>
public async Task<List<OplogEntry>> PullChangesAsync(HlcTimestamp since, IEnumerable<string>? collections, CancellationToken token)
{
var req = new PullChangesRequest
{
SinceWall = since.PhysicalTime,
SinceLogic = since.LogicalCounter,
// Empty SinceNode indicates a global pull (not source-node filtered).
SinceNode = string.Empty
};
if (collections != null)
{
foreach (var coll in collections)
{
req.Collections.Add(coll);
}
}
await _protocol.SendMessageAsync(_stream!, MessageType.PullChangesReq, req, _useCompression, _cipherState, token);
/// <summary>
/// Pulls oplog changes from the remote peer since the specified timestamp.
/// </summary>
/// <param name="since">The starting timestamp for requested changes.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>The list of oplog entries returned by the remote peer.</returns>
public async Task<List<OplogEntry>> PullChangesAsync(HlcTimestamp since, CancellationToken token)
{
return await PullChangesAsync(since, null, token);
}
var (type, payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
/// <summary>
/// Pulls oplog changes from the remote peer since the specified timestamp, filtered by collections.
/// </summary>
/// <param name="since">The starting timestamp for requested changes.</param>
/// <param name="collections">Optional collection names used to filter the returned entries.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>The list of oplog entries returned by the remote peer.</returns>
public async Task<List<OplogEntry>> PullChangesAsync(HlcTimestamp since, IEnumerable<string>? collections,
CancellationToken token)
{
var req = new PullChangesRequest
{
SinceWall = since.PhysicalTime,
SinceLogic = since.LogicalCounter,
// Empty SinceNode indicates a global pull (not source-node filtered).
SinceNode = string.Empty
};
if (collections != null)
foreach (string coll in collections)
req.Collections.Add(coll);
await _protocol.SendMessageAsync(_stream!, MessageType.PullChangesReq, req, _useCompression, _cipherState,
token);
(var type, byte[] payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
if (type != MessageType.ChangeSetRes) throw new Exception("Unexpected response");
var res = ChangeSetResponse.Parser.ParseFrom(payload);
@@ -303,35 +312,38 @@ public class TcpPeerClient : IDisposable
e.Collection,
e.Key,
ParseOp(e.Operation),
string.IsNullOrEmpty(e.JsonData) ? default : System.Text.Json.JsonSerializer.Deserialize<System.Text.Json.JsonElement>(e.JsonData),
string.IsNullOrEmpty(e.JsonData) ? default : JsonSerializer.Deserialize<JsonElement>(e.JsonData),
new HlcTimestamp(e.HlcWall, e.HlcLogic, e.HlcNode),
e.PreviousHash,
e.Hash // Pass the received hash to preserve integrity reference
)).ToList();
}
/// <summary>
/// Pulls oplog changes for a specific node from the remote peer since the specified timestamp.
/// </summary>
/// <param name="nodeId">The node identifier to filter changes by.</param>
/// <param name="since">The starting timestamp for requested changes.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>The list of oplog entries returned by the remote peer.</returns>
public async Task<List<OplogEntry>> PullChangesFromNodeAsync(string nodeId, HlcTimestamp since, CancellationToken token)
{
return await PullChangesFromNodeAsync(nodeId, since, null, token);
}
/// <summary>
/// Pulls oplog changes for a specific node from the remote peer since the specified timestamp, filtered by collections.
/// </summary>
/// <param name="nodeId">The node identifier to filter changes by.</param>
/// <param name="since">The starting timestamp for requested changes.</param>
/// <param name="collections">Optional collection names used to filter the returned entries.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>The list of oplog entries returned by the remote peer.</returns>
public async Task<List<OplogEntry>> PullChangesFromNodeAsync(string nodeId, HlcTimestamp since, IEnumerable<string>? collections, CancellationToken token)
{
/// <summary>
/// Pulls oplog changes for a specific node from the remote peer since the specified timestamp.
/// </summary>
/// <param name="nodeId">The node identifier to filter changes by.</param>
/// <param name="since">The starting timestamp for requested changes.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>The list of oplog entries returned by the remote peer.</returns>
public async Task<List<OplogEntry>> PullChangesFromNodeAsync(string nodeId, HlcTimestamp since,
CancellationToken token)
{
return await PullChangesFromNodeAsync(nodeId, since, null, token);
}
/// <summary>
/// Pulls oplog changes for a specific node from the remote peer since the specified timestamp, filtered by
/// collections.
/// </summary>
/// <param name="nodeId">The node identifier to filter changes by.</param>
/// <param name="since">The starting timestamp for requested changes.</param>
/// <param name="collections">Optional collection names used to filter the returned entries.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>The list of oplog entries returned by the remote peer.</returns>
public async Task<List<OplogEntry>> PullChangesFromNodeAsync(string nodeId, HlcTimestamp since,
IEnumerable<string>? collections, CancellationToken token)
{
var req = new PullChangesRequest
{
SinceNode = nodeId,
@@ -339,15 +351,13 @@ public class TcpPeerClient : IDisposable
SinceLogic = since.LogicalCounter
};
if (collections != null)
{
foreach (var coll in collections)
{
foreach (string coll in collections)
req.Collections.Add(coll);
}
}
await _protocol.SendMessageAsync(_stream!, MessageType.PullChangesReq, req, _useCompression, _cipherState, token);
var (type, payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
await _protocol.SendMessageAsync(_stream!, MessageType.PullChangesReq, req, _useCompression, _cipherState,
token);
(var type, byte[] payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
if (type != MessageType.ChangeSetRes) throw new Exception("Unexpected response");
var res = ChangeSetResponse.Parser.ParseFrom(payload);
@@ -356,26 +366,28 @@ public class TcpPeerClient : IDisposable
e.Collection,
e.Key,
ParseOp(e.Operation),
string.IsNullOrEmpty(e.JsonData) ? default : System.Text.Json.JsonSerializer.Deserialize<System.Text.Json.JsonElement>(e.JsonData),
string.IsNullOrEmpty(e.JsonData) ? default : JsonSerializer.Deserialize<JsonElement>(e.JsonData),
new HlcTimestamp(e.HlcWall, e.HlcLogic, e.HlcNode),
e.PreviousHash,
e.Hash
)).ToList();
}
/// <summary>
/// Retrieves a range of oplog entries connecting two hashes (Gap Recovery).
/// </summary>
/// <param name="startHash">The starting hash in the chain.</param>
/// <param name="endHash">The ending hash in the chain.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>The chain entries connecting the requested hash range.</returns>
public virtual async Task<List<OplogEntry>> GetChainRangeAsync(string startHash, string endHash, CancellationToken token)
{
/// <summary>
/// Retrieves a range of oplog entries connecting two hashes (Gap Recovery).
/// </summary>
/// <param name="startHash">The starting hash in the chain.</param>
/// <param name="endHash">The ending hash in the chain.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>The chain entries connecting the requested hash range.</returns>
public virtual async Task<List<OplogEntry>> GetChainRangeAsync(string startHash, string endHash,
CancellationToken token)
{
var req = new GetChainRangeRequest { StartHash = startHash, EndHash = endHash };
await _protocol.SendMessageAsync(_stream!, MessageType.GetChainRangeReq, req, _useCompression, _cipherState, token);
await _protocol.SendMessageAsync(_stream!, MessageType.GetChainRangeReq, req, _useCompression, _cipherState,
token);
var (type, payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
(var type, byte[] payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
if (type != MessageType.ChainRangeRes) throw new Exception($"Unexpected response for ChainRange: {type}");
var res = ChainRangeResponse.Parser.ParseFrom(payload);
@@ -386,27 +398,26 @@ public class TcpPeerClient : IDisposable
e.Collection,
e.Key,
ParseOp(e.Operation),
string.IsNullOrEmpty(e.JsonData) ? default : System.Text.Json.JsonSerializer.Deserialize<System.Text.Json.JsonElement>(e.JsonData),
string.IsNullOrEmpty(e.JsonData) ? default : JsonSerializer.Deserialize<JsonElement>(e.JsonData),
new HlcTimestamp(e.HlcWall, e.HlcLogic, e.HlcNode),
e.PreviousHash,
e.Hash
)).ToList();
}
/// <summary>
/// Pushes local oplog changes to the remote peer.
/// </summary>
/// <param name="entries">The oplog entries to push.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>A task that represents the asynchronous push operation.</returns>
public async Task PushChangesAsync(IEnumerable<OplogEntry> entries, CancellationToken token)
{
/// <summary>
/// Pushes local oplog changes to the remote peer.
/// </summary>
/// <param name="entries">The oplog entries to push.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>A task that represents the asynchronous push operation.</returns>
public async Task PushChangesAsync(IEnumerable<OplogEntry> entries, CancellationToken token)
{
var req = new PushChangesRequest();
var entryList = entries.ToList();
if (entryList.Count == 0) return;
foreach (var e in entryList)
{
req.Entries.Add(new ProtoOplogEntry
{
Collection = e.Collection,
@@ -419,11 +430,11 @@ public class TcpPeerClient : IDisposable
Hash = e.Hash,
PreviousHash = e.PreviousHash
});
}
await _protocol.SendMessageAsync(_stream!, MessageType.PushChangesReq, req, _useCompression, _cipherState, token);
await _protocol.SendMessageAsync(_stream!, MessageType.PushChangesReq, req, _useCompression, _cipherState,
token);
var (type, payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
(var type, byte[] payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
if (type != MessageType.AckRes) throw new Exception("Push failed");
var res = AckResponse.Parser.ParseFrom(payload);
@@ -431,72 +442,43 @@ public class TcpPeerClient : IDisposable
if (!res.Success) throw new Exception("Push failed");
}
private bool _useCompression = false; // Negotiated after handshake
private OperationType ParseOp(string op) => Enum.TryParse<OperationType>(op, out var val) ? val : OperationType.Put;
/// <summary>
/// Downloads a full snapshot from the remote peer to the provided destination stream.
/// </summary>
/// <param name="destination">The stream that receives snapshot bytes.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>A task that represents the asynchronous snapshot transfer operation.</returns>
public async Task GetSnapshotAsync(Stream destination, CancellationToken token)
{
await _protocol.SendMessageAsync(_stream!, MessageType.GetSnapshotReq, new GetSnapshotRequest(), _useCompression, _cipherState, token);
private OperationType ParseOp(string op)
{
return Enum.TryParse<OperationType>(op, out var val) ? val : OperationType.Put;
}
/// <summary>
/// Downloads a full snapshot from the remote peer to the provided destination stream.
/// </summary>
/// <param name="destination">The stream that receives snapshot bytes.</param>
/// <param name="token">Cancellation token.</param>
/// <returns>A task that represents the asynchronous snapshot transfer operation.</returns>
public async Task GetSnapshotAsync(Stream destination, CancellationToken token)
{
await _protocol.SendMessageAsync(_stream!, MessageType.GetSnapshotReq, new GetSnapshotRequest(),
_useCompression, _cipherState, token);
while (true)
{
var (type, payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
if (type != MessageType.SnapshotChunkMsg) throw new Exception($"Unexpected message type during snapshot: {type}");
var chunk = SnapshotChunk.Parser.ParseFrom(payload);
if (chunk.Data.Length > 0)
{
await destination.WriteAsync(chunk.Data.ToByteArray(), 0, chunk.Data.Length, token);
}
{
(var type, byte[] payload) = await _protocol.ReadMessageAsync(_stream!, _cipherState, token);
if (type != MessageType.SnapshotChunkMsg)
throw new Exception($"Unexpected message type during snapshot: {type}");
var chunk = SnapshotChunk.Parser.ParseFrom(payload);
if (chunk.Data.Length > 0)
await destination.WriteAsync(chunk.Data.ToByteArray(), 0, chunk.Data.Length, token);
if (chunk.IsLast) break;
}
}
/// <summary>
/// Releases resources used by the peer client.
/// </summary>
public void Dispose()
{
lock (_connectionLock)
{
if (_disposed) return;
_disposed = true;
}
try
{
_stream?.Dispose();
}
catch (Exception ex)
{
_logger.LogWarning(ex, "Error disposing network stream");
}
try
{
_client?.Dispose();
}
catch (Exception ex)
{
_logger.LogWarning(ex, "Error disposing TCP client");
}
_logger.LogDebug("Disposed connection to peer: {Address}", _peerAddress);
}
}
public class SnapshotRequiredException : Exception
{
/// <summary>
/// Initializes a new instance of the <see cref="SnapshotRequiredException"/> class.
/// </summary>
public SnapshotRequiredException() : base("Peer requires a full snapshot sync.") { }
}
public class SnapshotRequiredException : Exception
{
/// <summary>
/// Initializes a new instance of the <see cref="SnapshotRequiredException" /> class.
/// </summary>
public SnapshotRequiredException() : base("Peer requires a full snapshot sync.")
{
}
}

301
src/ZB.MOM.WW.CBDDC.Network/TcpSyncServer.cs
View File

@@ -1,69 +1,67 @@
using System.Net;
using System.Net.Sockets;
using System.Text.Json;
using Google.Protobuf;
using Microsoft.Extensions.Logging;
using Serilog.Context;
using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core.Storage;
using ZB.MOM.WW.CBDDC.Network.Proto;
using ZB.MOM.WW.CBDDC.Network.Security;
using ZB.MOM.WW.CBDDC.Network.Protocol;
using ZB.MOM.WW.CBDDC.Network.Security;
using ZB.MOM.WW.CBDDC.Network.Telemetry;
using Google.Protobuf;
using Microsoft.Extensions.Logging;
using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Net.Sockets;
using System.Threading;
using System.Threading.Tasks;
using Serilog.Context;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// TCP server that handles incoming synchronization requests from remote peers.
/// TCP server that handles incoming synchronization requests from remote peers.
/// </summary>
internal class TcpSyncServer : ISyncServer
{
private readonly IOplogStore _oplogStore;
private readonly IDocumentStore _documentStore;
private readonly ISnapshotService _snapshotStore;
private readonly ILogger<TcpSyncServer> _logger;
private readonly IPeerNodeConfigurationProvider _configProvider;
private CancellationTokenSource? _cts;
private TcpListener? _listener;
private readonly object _startStopLock = new object();
private int _activeConnections = 0;
internal int MaxConnections = 100;
internal class TcpSyncServer : ISyncServer
{
private const int ClientOperationTimeoutMs = 60000;
private readonly IAuthenticator _authenticator;
private readonly IPeerNodeConfigurationProvider _configProvider;
private readonly IDocumentStore _documentStore;
private readonly IPeerHandshakeService _handshakeService;
private readonly ILogger<TcpSyncServer> _logger;
private readonly IOplogStore _oplogStore;
private readonly ISnapshotService _snapshotStore;
private readonly object _startStopLock = new();
private readonly INetworkTelemetryService? _telemetry;
private int _activeConnections;
private CancellationTokenSource? _cts;
private TcpListener? _listener;
internal int MaxConnections = 100;
/// <summary>
/// Initializes a new instance of the TcpSyncServer class with the specified peer oplogStore, configuration provider,
/// logger, and authenticator.
/// Initializes a new instance of the TcpSyncServer class with the specified peer oplogStore, configuration provider,
/// logger, and authenticator.
/// </summary>
/// <remarks>The server automatically restarts when the configuration provided by
/// peerNodeConfigurationProvider changes. This ensures that configuration updates are applied without requiring
/// manual intervention.</remarks>
/// <param name="oplogStore">The peer oplogStore used to manage and persist peer information for the server.</param>
/// <param name="documentStore">The document store used to read and apply synchronized documents.</param>
/// <param name="snapshotStore">The snapshot store used to create and manage database snapshots for synchronization.</param>
/// <param name="peerNodeConfigurationProvider">The provider that supplies configuration settings for the peer node and notifies the server of configuration
/// changes.</param>
/// <param name="logger">The logger used to record informational and error messages for the server instance.</param>
/// <param name="authenticator">The authenticator responsible for validating peer connections to the server.</param>
/// <param name="handshakeService">The service used to perform secure handshake (optional).</param>
/// <param name="telemetry">The optional telemetry service used to record network performance metrics.</param>
public TcpSyncServer(
IOplogStore oplogStore,
IDocumentStore documentStore,
/// <remarks>
/// The server automatically restarts when the configuration provided by
/// peerNodeConfigurationProvider changes. This ensures that configuration updates are applied without requiring
/// manual intervention.
/// </remarks>
/// <param name="oplogStore">The peer oplogStore used to manage and persist peer information for the server.</param>
/// <param name="documentStore">The document store used to read and apply synchronized documents.</param>
/// <param name="snapshotStore">The snapshot store used to create and manage database snapshots for synchronization.</param>
/// <param name="peerNodeConfigurationProvider">
/// The provider that supplies configuration settings for the peer node and notifies the server of configuration
/// changes.
/// </param>
/// <param name="logger">The logger used to record informational and error messages for the server instance.</param>
/// <param name="authenticator">The authenticator responsible for validating peer connections to the server.</param>
/// <param name="handshakeService">The service used to perform secure handshake (optional).</param>
/// <param name="telemetry">The optional telemetry service used to record network performance metrics.</param>
public TcpSyncServer(
IOplogStore oplogStore,
IDocumentStore documentStore,
ISnapshotService snapshotStore,
IPeerNodeConfigurationProvider peerNodeConfigurationProvider,
ILogger<TcpSyncServer> logger,
IPeerNodeConfigurationProvider peerNodeConfigurationProvider,
ILogger<TcpSyncServer> logger,
IAuthenticator authenticator,
IPeerHandshakeService handshakeService,
INetworkTelemetryService? telemetry = null)
@@ -85,10 +83,17 @@ internal class TcpSyncServer : ISyncServer
}
/// <summary>
/// Starts the TCP synchronization server and begins listening for incoming connections asynchronously.
/// Gets the port on which the server is listening.
/// </summary>
/// <remarks>If the server is already running, this method returns immediately without starting a new
/// listener. The server will listen on the TCP port specified in the current configuration.</remarks>
public int? ListeningPort => ListeningEndpoint?.Port;
/// <summary>
/// Starts the TCP synchronization server and begins listening for incoming connections asynchronously.
/// </summary>
/// <remarks>
/// If the server is already running, this method returns immediately without starting a new
/// listener. The server will listen on the TCP port specified in the current configuration.
/// </remarks>
/// <returns>A task that represents the asynchronous start operation.</returns>
public async Task Start()
{
@@ -101,6 +106,7 @@ internal class TcpSyncServer : ISyncServer
_logger.LogWarning("TCP Sync Server already started");
return;
}
_cts = new CancellationTokenSource();
}
@@ -126,31 +132,33 @@ internal class TcpSyncServer : ISyncServer
}
/// <summary>
/// Stops the listener and cancels any pending operations.
/// Stops the listener and cancels any pending operations.
/// </summary>
/// <remarks>After calling this method, the listener will no longer accept new connections or process
/// requests. This method is safe to call multiple times; subsequent calls have no effect if the listener is already
/// stopped.</remarks>
/// <remarks>
/// After calling this method, the listener will no longer accept new connections or process
/// requests. This method is safe to call multiple times; subsequent calls have no effect if the listener is already
/// stopped.
/// </remarks>
/// <returns>A task that represents the asynchronous stop operation.</returns>
public async Task Stop()
{
CancellationTokenSource? ctsToDispose = null;
TcpListener? listenerToStop = null;
TcpListener? listenerToStop = null;
lock (_startStopLock)
{
if (_cts == null)
{
_logger.LogWarning("TCP Sync Server already stopped or never started");
return;
}
}
ctsToDispose = _cts;
listenerToStop = _listener;
_cts = null;
_listener = null;
}
}
try
{
ctsToDispose.Cancel();
@@ -162,32 +170,26 @@ internal class TcpSyncServer : ISyncServer
finally
{
ctsToDispose.Dispose();
}
listenerToStop?.Stop();
}
listenerToStop?.Stop();
await Task.CompletedTask;
}
/// <summary>
/// Gets the full local endpoint on which the server is listening.
/// Gets the full local endpoint on which the server is listening.
/// </summary>
public IPEndPoint? ListeningEndpoint => _listener?.LocalEndpoint as IPEndPoint;
/// <summary>
/// Gets the port on which the server is listening.
/// </summary>
public int? ListeningPort => ListeningEndpoint?.Port;
private async Task ListenAsync(CancellationToken token)
{
while (!token.IsCancellationRequested)
{
try
{
if (_listener == null) break;
var client = await _listener.AcceptTcpClientAsync();
var client = await _listener.AcceptTcpClientAsync();
if (_activeConnections >= MaxConnections)
{
_logger.LogWarning("Max connections reached ({Max}). Rejecting client.", MaxConnections);
@@ -197,7 +199,7 @@ internal class TcpSyncServer : ISyncServer
Interlocked.Increment(ref _activeConnections);
_ = Task.Run(async () =>
_ = Task.Run(async () =>
{
try
{
@@ -209,46 +211,47 @@ internal class TcpSyncServer : ISyncServer
}
}, token);
}
catch (ObjectDisposedException) { break; }
catch (ObjectDisposedException)
{
break;
}
catch (Exception ex)
{
_logger.LogError(ex, "TCP Accept Error");
}
}
}
private async Task HandleClientAsync(TcpClient client, CancellationToken token)
{
var remoteEp = client.Client.RemoteEndPoint;
using var operationContext = LogContext.PushProperty("OperationId", Guid.NewGuid().ToString("N"));
using var endpointContext = LogContext.PushProperty("RemoteEndpoint", remoteEp?.ToString() ?? "unknown");
_logger.LogDebug("Client Connected: {Endpoint}", remoteEp);
private async Task HandleClientAsync(TcpClient client, CancellationToken token)
{
var remoteEp = client.Client.RemoteEndPoint;
using var operationContext = LogContext.PushProperty("OperationId", Guid.NewGuid().ToString("N"));
using var endpointContext = LogContext.PushProperty("RemoteEndpoint", remoteEp?.ToString() ?? "unknown");
_logger.LogDebug("Client Connected: {Endpoint}", remoteEp);
try
{
using (client)
using (var stream = client.GetStream())
{
// CRITICAL for Android: Disable Nagle's algorithm for immediate packet send
client.NoDelay = true;
// Configure TCP keepalive
client.Client.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.KeepAlive, true);
// Set stream timeouts
client.NoDelay = true;
// Configure TCP keepalive
client.Client.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.KeepAlive, true);
// Set stream timeouts
stream.ReadTimeout = ClientOperationTimeoutMs;
stream.WriteTimeout = ClientOperationTimeoutMs;
var protocol = new ProtocolHandler(_logger, _telemetry);
bool useCompression = false;
stream.WriteTimeout = ClientOperationTimeoutMs;
var protocol = new ProtocolHandler(_logger, _telemetry);
var useCompression = false;
CipherState? cipherState = null;
List<string> remoteInterests = new();
// Perform Secure Handshake (if service is available)
var config = await _configProvider.GetConfiguration();
if (_handshakeService != null)
{
try
{
// We are NOT initiator
@@ -261,40 +264,39 @@ internal class TcpSyncServer : ISyncServer
_logger.LogError(ex, "Secure Handshake failed check logic");
return;
}
}
while (client.Connected && !token.IsCancellationRequested)
{
// Re-fetch config if needed, though usually stable
config = await _configProvider.GetConfiguration();
var (type, payload) = await protocol.ReadMessageAsync(stream, cipherState, token);
(var type, byte[] payload) = await protocol.ReadMessageAsync(stream, cipherState, token);
if (type == MessageType.Unknown) break; // EOF or Error
// Handshake Loop
if (type == MessageType.HandshakeReq)
{
var hReq = HandshakeRequest.Parser.ParseFrom(payload);
_logger.LogDebug("Received HandshakeReq from Node {NodeId}", hReq.NodeId);
// Track remote peer interests
remoteInterests = hReq.InterestingCollections.ToList();
_logger.LogDebug("Received HandshakeReq from Node {NodeId}", hReq.NodeId);
// Track remote peer interests
remoteInterests = hReq.InterestingCollections.ToList();
bool valid = await _authenticator.ValidateAsync(hReq.NodeId, hReq.AuthToken);
if (!valid)
{
_logger.LogWarning("Authentication failed for Node {NodeId}", hReq.NodeId);
await protocol.SendMessageAsync(stream, MessageType.HandshakeRes, new HandshakeResponse { NodeId = config.NodeId, Accepted = false }, false, cipherState, token);
await protocol.SendMessageAsync(stream, MessageType.HandshakeRes,
new HandshakeResponse { NodeId = config.NodeId, Accepted = false }, false, cipherState,
token);
return;
}
var hRes = new HandshakeResponse { NodeId = config.NodeId, Accepted = true };
// Include local interests from IDocumentStore in response for push filtering
foreach (var coll in _documentStore.InterestedCollection)
{
var hRes = new HandshakeResponse { NodeId = config.NodeId, Accepted = true };
// Include local interests from IDocumentStore in response for push filtering
foreach (string coll in _documentStore.InterestedCollection)
hRes.InterestingCollections.Add(coll);
}
if (CompressionHelper.IsBrotliSupported && hReq.SupportedCompression.Contains("brotli"))
{
@@ -302,12 +304,13 @@ internal class TcpSyncServer : ISyncServer
useCompression = true;
}
await protocol.SendMessageAsync(stream, MessageType.HandshakeRes, hRes, false, cipherState, token);
await protocol.SendMessageAsync(stream, MessageType.HandshakeRes, hRes, false, cipherState,
token);
continue;
}
IMessage? response = null;
MessageType resType = MessageType.Unknown;
var resType = MessageType.Unknown;
switch (type)
{
@@ -325,7 +328,7 @@ internal class TcpSyncServer : ISyncServer
case MessageType.GetVectorClockReq:
var vectorClock = await _oplogStore.GetVectorClockAsync(token);
var vcRes = new VectorClockResponse();
foreach (var nodeId in vectorClock.NodeIds)
foreach (string nodeId in vectorClock.NodeIds)
{
var ts = vectorClock.GetTimestamp(nodeId);
vcRes.Entries.Add(new VectorClockEntry
@@ -335,23 +338,23 @@ internal class TcpSyncServer : ISyncServer
HlcLogic = ts.LogicalCounter
});
}
response = vcRes;
resType = MessageType.VectorClockRes;
break;
case MessageType.PullChangesReq:
var pReq = PullChangesRequest.Parser.ParseFrom(payload);
var since = new HlcTimestamp(pReq.SinceWall, pReq.SinceLogic, pReq.SinceNode);
// Use collection filter from request
var filter = pReq.Collections.Any() ? pReq.Collections : null;
var oplog = string.IsNullOrWhiteSpace(pReq.SinceNode)
? await _oplogStore.GetOplogAfterAsync(since, filter, token)
: await _oplogStore.GetOplogForNodeAfterAsync(pReq.SinceNode, since, filter, token);
case MessageType.PullChangesReq:
var pReq = PullChangesRequest.Parser.ParseFrom(payload);
var since = new HlcTimestamp(pReq.SinceWall, pReq.SinceLogic, pReq.SinceNode);
// Use collection filter from request
var filter = pReq.Collections.Any() ? pReq.Collections : null;
var oplog = string.IsNullOrWhiteSpace(pReq.SinceNode)
? await _oplogStore.GetOplogAfterAsync(since, filter, token)
: await _oplogStore.GetOplogForNodeAfterAsync(pReq.SinceNode, since, filter, token);
var csRes = new ChangeSetResponse();
foreach (var e in oplog)
{
csRes.Entries.Add(new ProtoOplogEntry
{
Collection = e.Collection,
@@ -364,7 +367,6 @@ internal class TcpSyncServer : ISyncServer
Hash = e.Hash,
PreviousHash = e.PreviousHash
});
}
response = csRes;
resType = MessageType.ChangeSetRes;
break;
@@ -375,10 +377,12 @@ internal class TcpSyncServer : ISyncServer
e.Collection,
e.Key,
(OperationType)Enum.Parse(typeof(OperationType), e.Operation),
string.IsNullOrEmpty(e.JsonData) ? (System.Text.Json.JsonElement?)null : System.Text.Json.JsonSerializer.Deserialize<System.Text.Json.JsonElement>(e.JsonData),
string.IsNullOrEmpty(e.JsonData)
? null
: JsonSerializer.Deserialize<JsonElement>(e.JsonData),
new HlcTimestamp(e.HlcWall, e.HlcLogic, e.HlcNode),
e.PreviousHash, // Restore PreviousHash
e.Hash // Restore Hash
e.Hash // Restore Hash
));
await _oplogStore.ApplyBatchAsync(entries, token);
@@ -389,18 +393,15 @@ internal class TcpSyncServer : ISyncServer
case MessageType.GetChainRangeReq:
var rangeReq = GetChainRangeRequest.Parser.ParseFrom(payload);
var rangeEntries = await _oplogStore.GetChainRangeAsync(rangeReq.StartHash, rangeReq.EndHash, token);
var rangeRes = new ChainRangeResponse();
var rangeEntries =
await _oplogStore.GetChainRangeAsync(rangeReq.StartHash, rangeReq.EndHash, token);
var rangeRes = new ChainRangeResponse();
if (!rangeEntries.Any() && rangeReq.StartHash != rangeReq.EndHash)
{
// Gap cannot be filled (likely pruned or unknown branch)
rangeRes.SnapshotRequired = true;
}
else
{
foreach (var e in rangeEntries)
{
rangeRes.Entries.Add(new ProtoOplogEntry
{
Collection = e.Collection,
@@ -413,52 +414,52 @@ internal class TcpSyncServer : ISyncServer
Hash = e.Hash,
PreviousHash = e.PreviousHash
});
}
}
response = rangeRes;
resType = MessageType.ChainRangeRes;
break;
case MessageType.GetSnapshotReq:
_logger.LogInformation("Processing GetSnapshotReq from {Endpoint}", remoteEp);
var tempFile = Path.GetTempFileName();
try
string tempFile = Path.GetTempFileName();
try
{
// Create backup
using (var fs = File.Create(tempFile))
{
await _snapshotStore.CreateSnapshotAsync(fs, token);
}
}
using (var fs = File.OpenRead(tempFile))
{
byte[] buffer = new byte[80 * 1024]; // 80KB chunks
var buffer = new byte[80 * 1024]; // 80KB chunks
int bytesRead;
while ((bytesRead = await fs.ReadAsync(buffer, 0, buffer.Length, token)) > 0)
{
var chunk = new SnapshotChunk
{
var chunk = new SnapshotChunk
{
Data = ByteString.CopyFrom(buffer, 0, bytesRead),
IsLast = false
IsLast = false
};
await protocol.SendMessageAsync(stream, MessageType.SnapshotChunkMsg, chunk, false, cipherState, token);
}
// Send End of Snapshot
await protocol.SendMessageAsync(stream, MessageType.SnapshotChunkMsg, new SnapshotChunk { IsLast = true }, false, cipherState, token);
await protocol.SendMessageAsync(stream, MessageType.SnapshotChunkMsg, chunk,
false, cipherState, token);
}
// Send End of Snapshot
await protocol.SendMessageAsync(stream, MessageType.SnapshotChunkMsg,
new SnapshotChunk { IsLast = true }, false, cipherState, token);
}
}
finally
{
if (File.Exists(tempFile)) File.Delete(tempFile);
}
break;
}
if (response != null)
{
await protocol.SendMessageAsync(stream, resType, response, useCompression, cipherState, token);
}
}
}
}
@@ -471,4 +472,4 @@ internal class TcpSyncServer : ISyncServer
_logger.LogDebug("Client Disconnected: {Endpoint}", remoteEp);
}
}
}
}

49
src/ZB.MOM.WW.CBDDC.Network/Telemetry/INetworkTelemetryService.cs
View File

@@ -1,39 +1,38 @@
using System;
using System.Diagnostics;
namespace ZB.MOM.WW.CBDDC.Network.Telemetry;
using System.Diagnostics;
namespace ZB.MOM.WW.CBDDC.Network.Telemetry;
public interface INetworkTelemetryService
{
/// <summary>
/// Records a metric value for the specified metric type.
/// Records a metric value for the specified metric type.
/// </summary>
/// <param name="type">The metric type to record.</param>
/// <param name="value">The metric value.</param>
void RecordValue(MetricType type, double value);
/// <summary>
/// Starts timing a metric for the specified metric type.
/// Starts timing a metric for the specified metric type.
/// </summary>
/// <param name="type">The metric type to time.</param>
/// <returns>A timer that records elapsed time when disposed.</returns>
MetricTimer StartMetric(MetricType type);
/// <summary>
/// Gets a snapshot of all recorded metric values.
/// Gets a snapshot of all recorded metric values.
/// </summary>
/// <returns>A dictionary of metric values grouped by metric type and bucket.</returns>
System.Collections.Generic.Dictionary<MetricType, System.Collections.Generic.Dictionary<int, double>> GetSnapshot();
Dictionary<MetricType, Dictionary<int, double>> GetSnapshot();
}
public readonly struct MetricTimer : IDisposable
{
private readonly INetworkTelemetryService _service;
private readonly MetricType _type;
private readonly long _startTimestamp;
private readonly INetworkTelemetryService _service;
private readonly MetricType _type;
private readonly long _startTimestamp;
/// <summary>
/// Initializes a new metric timer.
/// Initializes a new metric timer.
/// </summary>
/// <param name="service">The telemetry service that receives the recorded value.</param>
/// <param name="type">The metric type being timed.</param>
@@ -45,16 +44,16 @@ public readonly struct MetricTimer : IDisposable
}
/// <summary>
/// Stops timing and records the elapsed duration.
/// Stops timing and records the elapsed duration.
/// </summary>
public void Dispose()
{
var elapsed = Stopwatch.GetTimestamp() - _startTimestamp;
// Convert ticks to milliseconds? Or keep as ticks?
// Plan said "latency", usually ms.
// Stopwatch.Frequency depends on hardware.
// Let's store MS representation.
double ms = (double)elapsed * 1000 / Stopwatch.Frequency;
_service.RecordValue(_type, ms);
}
}
long elapsed = Stopwatch.GetTimestamp() - _startTimestamp;
// Convert ticks to milliseconds? Or keep as ticks?
// Plan said "latency", usually ms.
// Stopwatch.Frequency depends on hardware.
// Let's store MS representation.
double ms = (double)elapsed * 1000 / Stopwatch.Frequency;
_service.RecordValue(_type, ms);
}
}

2
src/ZB.MOM.WW.CBDDC.Network/Telemetry/MetricType.cs
View File

@@ -6,4 +6,4 @@ public enum MetricType
EncryptionTime = 1,
DecryptionTime = 2,
RoundTripTime = 3
}
}

326
src/ZB.MOM.WW.CBDDC.Network/Telemetry/NetworkTelemetryService.cs
View File

@@ -1,101 +1,99 @@
using System;
using System.Buffers;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading;
using System.Threading.Channels;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
namespace ZB.MOM.WW.CBDDC.Network.Telemetry;
public class NetworkTelemetryService : INetworkTelemetryService, IDisposable
{
private readonly Channel<(MetricType Type, double Value)> _metricChannel;
private readonly CancellationTokenSource _cts;
private readonly ILogger<NetworkTelemetryService> _logger;
private readonly string _persistencePath;
// Aggregation State
// We keep 30m of history with 1s resolution = 1800 buckets.
private const int MaxHistorySeconds = 1800;
private readonly object _lock = new object();
private readonly MetricBucket[] _history;
private int _headIndex = 0; // Points to current second
private long _currentSecondTimestamp; // Unix timestamp of current bucket
public class NetworkTelemetryService : INetworkTelemetryService, IDisposable
{
// Aggregation State
// We keep 30m of history with 1s resolution = 1800 buckets.
private const int MaxHistorySeconds = 1800;
// Rolling Averages (Last calculated)
private readonly Dictionary<string, double> _averages = new Dictionary<string, double>();
private readonly Dictionary<string, double> _averages = new();
private readonly CancellationTokenSource _cts;
private readonly MetricBucket[] _history;
/// <summary>
/// Initializes a new instance of the <see cref="NetworkTelemetryService"/> class.
/// </summary>
/// <param name="logger">The logger used to report telemetry processing and persistence errors.</param>
/// <param name="persistencePath">The file path where persisted telemetry snapshots are written.</param>
public NetworkTelemetryService(ILogger<NetworkTelemetryService> logger, string persistencePath)
{
private readonly object _lock = new();
private readonly ILogger<NetworkTelemetryService> _logger;
private readonly Channel<(MetricType Type, double Value)> _metricChannel;
private readonly string _persistencePath;
private long _currentSecondTimestamp; // Unix timestamp of current bucket
private int _headIndex; // Points to current second
/// <summary>
/// Initializes a new instance of the <see cref="NetworkTelemetryService" /> class.
/// </summary>
/// <param name="logger">The logger used to report telemetry processing and persistence errors.</param>
/// <param name="persistencePath">The file path where persisted telemetry snapshots are written.</param>
public NetworkTelemetryService(ILogger<NetworkTelemetryService> logger, string persistencePath)
{
_logger = logger;
_persistencePath = persistencePath;
_metricChannel = Channel.CreateUnbounded<(MetricType, double)>(new UnboundedChannelOptions
{
SingleReader = true,
SingleWriter = false
SingleWriter = false
});
_cts = new CancellationTokenSource();
_history = new MetricBucket[MaxHistorySeconds];
for (int i = 0; i < MaxHistorySeconds; i++) _history[i] = new MetricBucket();
_cts = new CancellationTokenSource();
_history = new MetricBucket[MaxHistorySeconds];
for (var i = 0; i < MaxHistorySeconds; i++) _history[i] = new MetricBucket();
_currentSecondTimestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
_currentSecondTimestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
_ = Task.Run(ProcessMetricsLoop);
_ = Task.Run(PersistenceLoop);
}
/// <summary>
/// Records a metric value for the specified metric type.
/// </summary>
/// <param name="type">The metric category to update.</param>
/// <param name="value">The metric value to record.</param>
public void RecordValue(MetricType type, double value)
{
_metricChannel.Writer.TryWrite((type, value));
}
/// <summary>
/// Starts a timer for the specified metric type.
/// </summary>
/// <param name="type">The metric category to time.</param>
/// <returns>A metric timer that records elapsed time when disposed.</returns>
public MetricTimer StartMetric(MetricType type)
{
return new MetricTimer(this, type);
}
/// <summary>
/// Gets a point-in-time snapshot of rolling averages for each metric type.
/// </summary>
/// <returns>A dictionary keyed by metric type containing average values by window size in seconds.</returns>
public Dictionary<MetricType, Dictionary<int, double>> GetSnapshot()
{
/// <summary>
/// Releases resources used by the telemetry service.
/// </summary>
public void Dispose()
{
_cts.Cancel();
_cts.Dispose();
}
/// <summary>
/// Records a metric value for the specified metric type.
/// </summary>
/// <param name="type">The metric category to update.</param>
/// <param name="value">The metric value to record.</param>
public void RecordValue(MetricType type, double value)
{
_metricChannel.Writer.TryWrite((type, value));
}
/// <summary>
/// Starts a timer for the specified metric type.
/// </summary>
/// <param name="type">The metric category to time.</param>
/// <returns>A metric timer that records elapsed time when disposed.</returns>
public MetricTimer StartMetric(MetricType type)
{
return new MetricTimer(this, type);
}
/// <summary>
/// Gets a point-in-time snapshot of rolling averages for each metric type.
/// </summary>
/// <returns>A dictionary keyed by metric type containing average values by window size in seconds.</returns>
public Dictionary<MetricType, Dictionary<int, double>> GetSnapshot()
{
var snapshot = new Dictionary<MetricType, Dictionary<int, double>>();
var windows = new[] { 60, 300, 600, 1800 };
var windows = new[] { 60, 300, 600, 1800 };
lock (_lock)
{
foreach (var type in Enum.GetValues(typeof(MetricType)).Cast<MetricType>())
{
var typeDict = new Dictionary<int, double>();
foreach (var w in windows)
{
typeDict[w] = CalculateAverage(type, w);
}
foreach (int w in windows) typeDict[w] = CalculateAverage(type, w);
snapshot[type] = typeDict;
}
}
return snapshot;
}
@@ -103,29 +101,26 @@ public class NetworkTelemetryService : INetworkTelemetryService, IDisposable
{
var reader = _metricChannel.Reader;
while (!_cts.IsCancellationRequested)
{
try
{
if (await reader.WaitToReadAsync(_cts.Token))
{
while (reader.TryRead(out var item))
{
AddMetricToCurrentBucket(item.Type, item.Value);
}
}
}
catch (OperationCanceledException) { break; }
catch (OperationCanceledException)
{
break;
}
catch (Exception ex)
{
_logger.LogError(ex, "Error processing metrics");
}
}
}
private void AddMetricToCurrentBucket(MetricType type, double value)
{
long now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
long now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
lock (_lock)
{
// Rotate bucket if second changed
@@ -133,11 +128,12 @@ public class NetworkTelemetryService : INetworkTelemetryService, IDisposable
{
long diff = now - _currentSecondTimestamp;
// Move head forward, clearing buckets in between if gap > 1s
for (int i = 0; i < diff && i < MaxHistorySeconds; i++)
for (var i = 0; i < diff && i < MaxHistorySeconds; i++)
{
_headIndex = (_headIndex + 1) % MaxHistorySeconds;
_history[_headIndex].Reset();
}
_currentSecondTimestamp = now;
}
@@ -148,18 +144,19 @@ public class NetworkTelemetryService : INetworkTelemetryService, IDisposable
private async Task PersistenceLoop()
{
while (!_cts.IsCancellationRequested)
{
try
{
await Task.Delay(TimeSpan.FromMinutes(1), _cts.Token);
CalculateAndPersist();
}
catch (OperationCanceledException) { break; }
catch (OperationCanceledException)
{
break;
}
catch (Exception ex)
{
_logger.LogError(ex, "Error persisting metrics");
}
}
}
private void CalculateAndPersist()
@@ -167,117 +164,116 @@ public class NetworkTelemetryService : INetworkTelemetryService, IDisposable
lock (_lock)
{
// Calculate averages
var windows = new[] { 60, 300, 600, 1800 }; // 1m, 5m, 10m, 30m
var windows = new[] { 60, 300, 600, 1800 }; // 1m, 5m, 10m, 30m
using var fs = new FileStream(_persistencePath, FileMode.Create, FileAccess.Write);
using var bw = new BinaryWriter(fs);
// Header
using var bw = new BinaryWriter(fs);
// Header
bw.Write((byte)1); // Version
bw.Write(DateTimeOffset.UtcNow.ToUnixTimeSeconds()); // Timestamp
bw.Write(DateTimeOffset.UtcNow.ToUnixTimeSeconds()); // Timestamp
foreach (var type in Enum.GetValues(typeof(MetricType)).Cast<MetricType>())
{
bw.Write((int)type);
foreach (var w in windows)
foreach (int w in windows)
{
double avg = CalculateAverage(type, w);
bw.Write(w); // Window Seconds
bw.Write(avg); // Average Value
bw.Write(w); // Window Seconds
bw.Write(avg); // Average Value
}
}
}
}
/// <summary>
/// Forces immediate calculation and persistence of telemetry data.
/// </summary>
internal void ForcePersist()
{
CalculateAndPersist();
}
/// <summary>
/// Forces immediate calculation and persistence of telemetry data.
/// </summary>
internal void ForcePersist()
{
CalculateAndPersist();
}
private double CalculateAverage(MetricType type, int seconds)
{
// Go backwards from head
double sum = 0;
int count = 0;
int scanned = 0;
int idx = _headIndex;
var count = 0;
var scanned = 0;
int idx = _headIndex;
while (scanned < seconds && scanned < MaxHistorySeconds)
{
var bucket = _history[idx];
sum += bucket.GetSum(type);
count += bucket.GetCount(type);
count += bucket.GetCount(type);
idx--;
if (idx < 0) idx = MaxHistorySeconds - 1;
scanned++;
}
return count == 0 ? 0 : sum / count;
}
}
/// <summary>
/// Releases resources used by the telemetry service.
/// </summary>
public void Dispose()
{
_cts.Cancel();
_cts.Dispose();
return count == 0 ? 0 : sum / count;
}
}
internal class MetricBucket
{
internal class MetricBucket
{
private readonly int[] _counts;
// Simple lock-free or locked accumulation? Global lock handles it for now.
// Storing Sum and Count for each type
private readonly double[] _sums;
private readonly int[] _counts;
/// <summary>
/// Initializes a new instance of the <see cref="MetricBucket"/> class.
/// </summary>
public MetricBucket()
{
var typeCount = Enum.GetValues(typeof(MetricType)).Length;
_sums = new double[typeCount];
_counts = new int[typeCount];
}
/// <summary>
/// Clears all accumulated metric sums and counts in this bucket.
/// </summary>
public void Reset()
{
Array.Clear(_sums, 0, _sums.Length);
Array.Clear(_counts, 0, _counts.Length);
}
/// <summary>
/// Adds a metric value to the bucket.
/// </summary>
/// <param name="type">The metric category to update.</param>
/// <param name="value">The value to accumulate.</param>
public void Add(MetricType type, double value)
{
int idx = (int)type;
_sums[idx] += value;
_counts[idx]++;
}
/// <summary>
/// Gets the accumulated sum for a metric type.
/// </summary>
/// <param name="type">The metric category to read.</param>
/// <returns>The accumulated sum for the specified metric type.</returns>
public double GetSum(MetricType type) => _sums[(int)type];
/// <summary>
/// Gets the accumulated count for a metric type.
/// </summary>
/// <param name="type">The metric category to read.</param>
/// <returns>The accumulated sample count for the specified metric type.</returns>
public int GetCount(MetricType type) => _counts[(int)type];
}
/// <summary>
/// Initializes a new instance of the <see cref="MetricBucket" /> class.
/// </summary>
public MetricBucket()
{
int typeCount = Enum.GetValues(typeof(MetricType)).Length;
_sums = new double[typeCount];
_counts = new int[typeCount];
}
/// <summary>
/// Clears all accumulated metric sums and counts in this bucket.
/// </summary>
public void Reset()
{
Array.Clear(_sums, 0, _sums.Length);
Array.Clear(_counts, 0, _counts.Length);
}
/// <summary>
/// Adds a metric value to the bucket.
/// </summary>
/// <param name="type">The metric category to update.</param>
/// <param name="value">The value to accumulate.</param>
public void Add(MetricType type, double value)
{
var idx = (int)type;
_sums[idx] += value;
_counts[idx]++;
}
/// <summary>
/// Gets the accumulated sum for a metric type.
/// </summary>
/// <param name="type">The metric category to read.</param>
/// <returns>The accumulated sum for the specified metric type.</returns>
public double GetSum(MetricType type)
{
return _sums[(int)type];
}
/// <summary>
/// Gets the accumulated count for a metric type.
/// </summary>
/// <param name="type">The metric category to read.</param>
/// <returns>The accumulated sample count for the specified metric type.</returns>
public int GetCount(MetricType type)
{
return _counts[(int)type];
}
}

317
src/ZB.MOM.WW.CBDDC.Network/UdpDiscoveryService.cs
View File

@@ -1,52 +1,49 @@
using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Sockets;
using System.Text;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
using ZB.MOM.WW.CBDDC.Core.Storage;
using System.Collections.Concurrent;
using System.Net;
using System.Net.Sockets;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.Extensions.Logging;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Core.Storage;
namespace ZB.MOM.WW.CBDDC.Network;
/// <summary>
/// Provides UDP-based peer discovery for the CBDDC network.
/// Broadcasts presence beacons and listens for other nodes on the local network.
/// Provides UDP-based peer discovery for the CBDDC network.
/// Broadcasts presence beacons and listens for other nodes on the local network.
/// </summary>
internal class UdpDiscoveryService : IDiscoveryService
{
private const int DiscoveryPort = 25000;
private readonly ILogger<UdpDiscoveryService> _logger;
private readonly IPeerNodeConfigurationProvider _configProvider;
private readonly IDocumentStore _documentStore;
private CancellationTokenSource? _cts;
private readonly ConcurrentDictionary<string, PeerNode> _activePeers = new();
private readonly object _startStopLock = new object();
/// <summary>
/// Initializes a new instance of the <see cref="UdpDiscoveryService"/> class.
/// </summary>
/// <param name="peerNodeConfigurationProvider">Provider for peer node configuration.</param>
/// <param name="documentStore">Document store used to obtain collection interests.</param>
/// <param name="logger">Logger for discovery service events.</param>
public UdpDiscoveryService(
IPeerNodeConfigurationProvider peerNodeConfigurationProvider,
IDocumentStore documentStore,
ILogger<UdpDiscoveryService> logger)
{
_configProvider = peerNodeConfigurationProvider ?? throw new ArgumentNullException(nameof(peerNodeConfigurationProvider));
_documentStore = documentStore ?? throw new ArgumentNullException(nameof(documentStore));
_logger = logger;
internal class UdpDiscoveryService : IDiscoveryService
{
private const int DiscoveryPort = 25000;
private readonly ConcurrentDictionary<string, PeerNode> _activePeers = new();
private readonly IPeerNodeConfigurationProvider _configProvider;
private readonly IDocumentStore _documentStore;
private readonly ILogger<UdpDiscoveryService> _logger;
private readonly object _startStopLock = new();
private CancellationTokenSource? _cts;
/// <summary>
/// Initializes a new instance of the <see cref="UdpDiscoveryService" /> class.
/// </summary>
/// <param name="peerNodeConfigurationProvider">Provider for peer node configuration.</param>
/// <param name="documentStore">Document store used to obtain collection interests.</param>
/// <param name="logger">Logger for discovery service events.</param>
public UdpDiscoveryService(
IPeerNodeConfigurationProvider peerNodeConfigurationProvider,
IDocumentStore documentStore,
ILogger<UdpDiscoveryService> logger)
{
_configProvider = peerNodeConfigurationProvider ??
throw new ArgumentNullException(nameof(peerNodeConfigurationProvider));
_documentStore = documentStore ?? throw new ArgumentNullException(nameof(documentStore));
_logger = logger;
}
/// <summary>
/// Starts the discovery service, initiating listener, broadcaster, and cleanup tasks.
/// Starts the discovery service, initiating listener, broadcaster, and cleanup tasks.
/// </summary>
public async Task Start()
{
@@ -57,11 +54,12 @@ internal class UdpDiscoveryService : IDiscoveryService
_logger.LogWarning("UDP Discovery Service already started");
return;
}
_cts = new CancellationTokenSource();
}
var token = _cts.Token;
var token = _cts.Token;
_ = Task.Run(async () =>
{
try
@@ -72,8 +70,8 @@ internal class UdpDiscoveryService : IDiscoveryService
{
_logger.LogError(ex, "UDP Listen task failed");
}
}, token);
}, token);
_ = Task.Run(async () =>
{
try
@@ -84,8 +82,8 @@ internal class UdpDiscoveryService : IDiscoveryService
{
_logger.LogError(ex, "UDP Broadcast task failed");
}
}, token);
}, token);
_ = Task.Run(async () =>
{
try
@@ -101,75 +99,26 @@ internal class UdpDiscoveryService : IDiscoveryService
await Task.CompletedTask;
}
// ... Stop ...
private async Task CleanupAsync(CancellationToken token)
/// <summary>
/// Stops the discovery service.
/// </summary>
/// <returns>A task that completes when stop processing has finished.</returns>
public async Task Stop()
{
while (!token.IsCancellationRequested)
{
try
{
await Task.Delay(10000, token); // Check every 10s
var now = DateTimeOffset.UtcNow;
var expired = new List<string>();
CancellationTokenSource? ctsToDispose = null;
foreach (var pair in _activePeers)
{
// Expiry: 15 seconds (broadcast is every 5s, so 3 missed beats = dead)
if ((now - pair.Value.LastSeen).TotalSeconds > 15)
{
expired.Add(pair.Key);
}
}
foreach (var id in expired)
{
if (_activePeers.TryRemove(id, out var removed))
{
_logger.LogInformation("Peer Expired: {NodeId} at {Endpoint}", removed.NodeId, removed.Address);
}
}
}
catch (OperationCanceledException) { break; }
catch (Exception ex)
{
_logger.LogError(ex, "Cleanup Loop Error");
}
}
}
// ... Listen ...
private void HandleBeacon(DiscoveryBeacon beacon, IPAddress address)
{
var peerId = beacon.NodeId;
var endpoint = $"{address}:{beacon.TcpPort}";
var peer = new PeerNode(peerId, endpoint, DateTimeOffset.UtcNow, interestingCollections: beacon.InterestingCollections);
_activePeers.AddOrUpdate(peerId, peer, (key, old) => peer);
}
/// <summary>
/// Stops the discovery service.
/// </summary>
/// <returns>A task that completes when stop processing has finished.</returns>
public async Task Stop()
{
CancellationTokenSource? ctsToDispose = null;
lock (_startStopLock)
{
if (_cts == null)
{
_logger.LogWarning("UDP Discovery Service already stopped or never started");
return;
}
}
ctsToDispose = _cts;
_cts = null;
}
}
try
{
ctsToDispose.Cancel();
@@ -181,16 +130,62 @@ internal class UdpDiscoveryService : IDiscoveryService
finally
{
ctsToDispose.Dispose();
}
await Task.CompletedTask;
}
/// <summary>
/// Gets the currently active peers discovered on the network.
/// </summary>
/// <returns>The collection of active peers.</returns>
public IEnumerable<PeerNode> GetActivePeers() => _activePeers.Values;
}
await Task.CompletedTask;
}
/// <summary>
/// Gets the currently active peers discovered on the network.
/// </summary>
/// <returns>The collection of active peers.</returns>
public IEnumerable<PeerNode> GetActivePeers()
{
return _activePeers.Values;
}
// ... Stop ...
private async Task CleanupAsync(CancellationToken token)
{
while (!token.IsCancellationRequested)
try
{
await Task.Delay(10000, token); // Check every 10s
var now = DateTimeOffset.UtcNow;
var expired = new List<string>();
foreach (var pair in _activePeers)
// Expiry: 15 seconds (broadcast is every 5s, so 3 missed beats = dead)
if ((now - pair.Value.LastSeen).TotalSeconds > 15)
expired.Add(pair.Key);
foreach (string id in expired)
if (_activePeers.TryRemove(id, out var removed))
_logger.LogInformation("Peer Expired: {NodeId} at {Endpoint}", removed.NodeId, removed.Address);
}
catch (OperationCanceledException)
{
break;
}
catch (Exception ex)
{
_logger.LogError(ex, "Cleanup Loop Error");
}
}
// ... Listen ...
private void HandleBeacon(DiscoveryBeacon beacon, IPAddress address)
{
string peerId = beacon.NodeId;
var endpoint = $"{address}:{beacon.TcpPort}";
var peer = new PeerNode(peerId, endpoint, DateTimeOffset.UtcNow,
interestingCollections: beacon.InterestingCollections);
_activePeers.AddOrUpdate(peerId, peer, (key, old) => peer);
}
private async Task ListenAsync(CancellationToken token)
{
@@ -201,28 +196,25 @@ internal class UdpDiscoveryService : IDiscoveryService
_logger.LogInformation("UDP Discovery Listening on port {Port}", DiscoveryPort);
while (!token.IsCancellationRequested)
{
try
{
var result = await udp.ReceiveAsync();
var json = Encoding.UTF8.GetString(result.Buffer);
string json = Encoding.UTF8.GetString(result.Buffer);
try
{
var config = await _configProvider.GetConfiguration();
var _nodeId = config.NodeId;
var localClusterHash = ComputeClusterHash(config.AuthToken);
string _nodeId = config.NodeId;
string localClusterHash = ComputeClusterHash(config.AuthToken);
var beacon = JsonSerializer.Deserialize<DiscoveryBeacon>(json);
var beacon = JsonSerializer.Deserialize<DiscoveryBeacon>(json);
if (beacon != null && beacon.NodeId != _nodeId)
{
// Filter by ClusterHash to reduce congestion from different clusters
if (!string.Equals(beacon.ClusterHash, localClusterHash, StringComparison.Ordinal))
{
// Optional: Log trace if needed, but keeping it silent avoids flooding logs during congestion
continue;
}
continue;
HandleBeacon(beacon, result.RemoteEndPoint.Address);
}
@@ -232,12 +224,14 @@ internal class UdpDiscoveryService : IDiscoveryService
_logger.LogWarning(ex, "Failed to parse beacon from {Address}", result.RemoteEndPoint.Address);
}
}
catch (ObjectDisposedException) { break; }
catch (ObjectDisposedException)
{
break;
}
catch (Exception ex)
{
_logger.LogError(ex, "UDP Listener Error");
}
}
}
private async Task BroadcastAsync(CancellationToken token)
@@ -252,18 +246,18 @@ internal class UdpDiscoveryService : IDiscoveryService
try
{
// Re-fetch config each time in case it changes (though usually static)
var conf = await _configProvider.GetConfiguration();
var beacon = new DiscoveryBeacon
{
NodeId = conf.NodeId,
var conf = await _configProvider.GetConfiguration();
var beacon = new DiscoveryBeacon
{
NodeId = conf.NodeId,
TcpPort = conf.TcpPort,
ClusterHash = ComputeClusterHash(conf.AuthToken),
InterestingCollections = _documentStore.InterestedCollection.ToList()
};
var json = JsonSerializer.Serialize(beacon);
var bytes = Encoding.UTF8.GetBytes(json);
string json = JsonSerializer.Serialize(beacon);
byte[] bytes = Encoding.UTF8.GetBytes(json);
await udp.SendAsync(bytes, bytes.Length, endpoint);
}
@@ -279,39 +273,38 @@ internal class UdpDiscoveryService : IDiscoveryService
private string ComputeClusterHash(string authToken)
{
if (string.IsNullOrEmpty(authToken)) return "";
using var sha256 = System.Security.Cryptography.SHA256.Create();
var bytes = Encoding.UTF8.GetBytes(authToken);
var hash = sha256.ComputeHash(bytes);
using var sha256 = SHA256.Create();
byte[] bytes = Encoding.UTF8.GetBytes(authToken);
byte[] hash = sha256.ComputeHash(bytes);
// Return first 8 chars (4 bytes hex) is enough for filtering
return BitConverter.ToString(hash).Replace("-", "").Substring(0, 8);
}
private class DiscoveryBeacon
{
/// <summary>
/// Gets or sets the broadcasting node identifier.
/// </summary>
[JsonPropertyName("node_id")]
public string NodeId { get; set; } = "";
private class DiscoveryBeacon
{
/// <summary>
/// Gets or sets the broadcasting node identifier.
/// </summary>
[System.Text.Json.Serialization.JsonPropertyName("node_id")]
public string NodeId { get; set; } = "";
/// <summary>
/// Gets or sets the TCP port used by the broadcasting node.
/// </summary>
[System.Text.Json.Serialization.JsonPropertyName("tcp_port")]
public int TcpPort { get; set; }
/// <summary>
/// Gets or sets the cluster hash used for discovery filtering.
/// </summary>
[System.Text.Json.Serialization.JsonPropertyName("cluster_hash")]
public string ClusterHash { get; set; } = "";
/// <summary>
/// Gets or sets the collections the node is interested in.
/// </summary>
[System.Text.Json.Serialization.JsonPropertyName("interests")]
public List<string> InterestingCollections { get; set; } = new();
}
}
/// <summary>
/// Gets or sets the TCP port used by the broadcasting node.
/// </summary>
[JsonPropertyName("tcp_port")]
public int TcpPort { get; set; }
/// <summary>
/// Gets or sets the cluster hash used for discovery filtering.
/// </summary>
[JsonPropertyName("cluster_hash")]
public string ClusterHash { get; set; } = "";
/// <summary>
/// Gets or sets the collections the node is interested in.
/// </summary>
[JsonPropertyName("interests")]
public List<string> InterestingCollections { get; set; } = new();
}
}

86
src/ZB.MOM.WW.CBDDC.Network/ZB.MOM.WW.CBDDC.Network.csproj
View File

@@ -1,52 +1,52 @@
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<ProjectReference Include="..\ZB.MOM.WW.CBDDC.Core\ZB.MOM.WW.CBDDC.Core.csproj" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\ZB.MOM.WW.CBDDC.Core\ZB.MOM.WW.CBDDC.Core.csproj"/>
</ItemGroup>
<ItemGroup>
<PackageReference Include="Google.Protobuf" Version="3.25.1" />
<PackageReference Include="Grpc.Tools" Version="2.76.0">
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>
<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="8.0.0" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" />
<PackageReference Include="Serilog" Version="4.2.0" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Google.Protobuf" Version="3.25.1"/>
<PackageReference Include="Grpc.Tools" Version="2.76.0">
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>
<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="8.0.0"/>
<PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="8.0.0"/>
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0"/>
<PackageReference Include="Serilog" Version="4.2.0"/>
</ItemGroup>
<ItemGroup>
<Protobuf Include="sync.proto" GrpcServices="None" />
</ItemGroup>
<ItemGroup>
<Protobuf Include="sync.proto" GrpcServices="None"/>
</ItemGroup>
<PropertyGroup>
<AssemblyName>ZB.MOM.WW.CBDDC.Network</AssemblyName>
<RootNamespace>ZB.MOM.WW.CBDDC.Network</RootNamespace>
<PackageId>ZB.MOM.WW.CBDDC.Network</PackageId>
<TargetFramework>net10.0</TargetFramework>
<LangVersion>latest</LangVersion>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<Version>1.0.3</Version>
<Authors>MrDevRobot</Authors>
<Description>Networking layer (TCP/UDP/Gossip) for CBDDC.</Description>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageTags>p2p;mesh;network;gossip;lan;udp;tcp;discovery</PackageTags>
<PackageProjectUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</PackageProjectUrl>
<RepositoryUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup>
<PropertyGroup>
<AssemblyName>ZB.MOM.WW.CBDDC.Network</AssemblyName>
<RootNamespace>ZB.MOM.WW.CBDDC.Network</RootNamespace>
<PackageId>ZB.MOM.WW.CBDDC.Network</PackageId>
<TargetFramework>net10.0</TargetFramework>
<LangVersion>latest</LangVersion>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<Version>1.0.3</Version>
<Authors>MrDevRobot</Authors>
<Description>Networking layer (TCP/UDP/Gossip) for CBDDC.</Description>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageTags>p2p;mesh;network;gossip;lan;udp;tcp;discovery</PackageTags>
<PackageProjectUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</PackageProjectUrl>
<RepositoryUrl>https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup>
<ItemGroup>
<None Include="README.md" Pack="true" PackagePath="\" />
</ItemGroup>
<ItemGroup>
<None Include="README.md" Pack="true" PackagePath="\"/>
</ItemGroup>
<ItemGroup>
<AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
<_Parameter1>ZB.MOM.WW.CBDDC.Network.Tests</_Parameter1>
</AssemblyAttribute>
</ItemGroup>
<ItemGroup>
<AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
<_Parameter1>ZB.MOM.WW.CBDDC.Network.Tests</_Parameter1>
</AssemblyAttribute>
</ItemGroup>
</Project>

50
src/ZB.MOM.WW.CBDDC.Persistence/BLite/BLiteDocumentMetadataStore.cs
View File

@@ -1,13 +1,13 @@
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Core.Storage;
using ZB.MOM.WW.CBDDC.Persistence.BLite.Entities;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
namespace ZB.MOM.WW.CBDDC.Persistence.BLite;
/// <summary>
/// BLite implementation of document metadata storage for sync tracking.
/// BLite implementation of document metadata storage for sync tracking.
/// </summary>
/// <typeparam name="TDbContext">The type of CBDDCDocumentDbContext.</typeparam>
public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore where TDbContext : CBDDCDocumentDbContext
@@ -16,18 +16,20 @@ public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore wher
private readonly ILogger<BLiteDocumentMetadataStore<TDbContext>> _logger;
/// <summary>
/// Initializes a new instance of the <see cref="BLiteDocumentMetadataStore{TDbContext}"/> class.
/// Initializes a new instance of the <see cref="BLiteDocumentMetadataStore{TDbContext}" /> class.
/// </summary>
/// <param name="context">The BLite document database context.</param>
/// <param name="logger">The optional logger instance.</param>
public BLiteDocumentMetadataStore(TDbContext context, ILogger<BLiteDocumentMetadataStore<TDbContext>>? logger = null)
public BLiteDocumentMetadataStore(TDbContext context,
ILogger<BLiteDocumentMetadataStore<TDbContext>>? logger = null)
{
_context = context ?? throw new ArgumentNullException(nameof(context));
_logger = logger ?? NullLogger<BLiteDocumentMetadataStore<TDbContext>>.Instance;
}
/// <inheritdoc />
public override async Task<DocumentMetadata?> GetMetadataAsync(string collection, string key, CancellationToken cancellationToken = default)
public override async Task<DocumentMetadata?> GetMetadataAsync(string collection, string key,
CancellationToken cancellationToken = default)
{
var entity = _context.DocumentMetadatas
.Find(m => m.Collection == collection && m.Key == key)
@@ -37,7 +39,8 @@ public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore wher
}
/// <inheritdoc />
public override async Task<IEnumerable<DocumentMetadata>> GetMetadataByCollectionAsync(string collection, CancellationToken cancellationToken = default)
public override async Task<IEnumerable<DocumentMetadata>> GetMetadataByCollectionAsync(string collection,
CancellationToken cancellationToken = default)
{
return _context.DocumentMetadatas
.Find(m => m.Collection == collection)
@@ -46,7 +49,8 @@ public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore wher
}
/// <inheritdoc />
public override async Task UpsertMetadataAsync(DocumentMetadata metadata, CancellationToken cancellationToken = default)
public override async Task UpsertMetadataAsync(DocumentMetadata metadata,
CancellationToken cancellationToken = default)
{
var existing = _context.DocumentMetadatas
.Find(m => m.Collection == metadata.Collection && m.Key == metadata.Key)
@@ -69,7 +73,8 @@ public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore wher
}
/// <inheritdoc />
public override async Task UpsertMetadataBatchAsync(IEnumerable<DocumentMetadata> metadatas, CancellationToken cancellationToken = default)
public override async Task UpsertMetadataBatchAsync(IEnumerable<DocumentMetadata> metadatas,
CancellationToken cancellationToken = default)
{
foreach (var metadata in metadatas)
{
@@ -95,7 +100,8 @@ public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore wher
}
/// <inheritdoc />
public override async Task MarkDeletedAsync(string collection, string key, HlcTimestamp timestamp, CancellationToken cancellationToken = default)
public override async Task MarkDeletedAsync(string collection, string key, HlcTimestamp timestamp,
CancellationToken cancellationToken = default)
{
var existing = _context.DocumentMetadatas
.Find(m => m.Collection == collection && m.Key == key)
@@ -127,11 +133,12 @@ public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore wher
}
/// <inheritdoc />
public override async Task<IEnumerable<DocumentMetadata>> GetMetadataAfterAsync(HlcTimestamp since, IEnumerable<string>? collections = null, CancellationToken cancellationToken = default)
public override async Task<IEnumerable<DocumentMetadata>> GetMetadataAfterAsync(HlcTimestamp since,
IEnumerable<string>? collections = null, CancellationToken cancellationToken = default)
{
var query = _context.DocumentMetadatas.AsQueryable()
.Where(m => (m.HlcPhysicalTime > since.PhysicalTime) ||
(m.HlcPhysicalTime == since.PhysicalTime && m.HlcLogicalCounter > since.LogicalCounter));
.Where(m => m.HlcPhysicalTime > since.PhysicalTime ||
(m.HlcPhysicalTime == since.PhysicalTime && m.HlcLogicalCounter > since.LogicalCounter));
if (collections != null)
{
@@ -161,17 +168,16 @@ public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore wher
}
/// <inheritdoc />
public override async Task ImportAsync(IEnumerable<DocumentMetadata> items, CancellationToken cancellationToken = default)
public override async Task ImportAsync(IEnumerable<DocumentMetadata> items,
CancellationToken cancellationToken = default)
{
foreach (var item in items)
{
await _context.DocumentMetadatas.InsertAsync(ToEntity(item));
}
foreach (var item in items) await _context.DocumentMetadatas.InsertAsync(ToEntity(item));
await _context.SaveChangesAsync(cancellationToken);
}
/// <inheritdoc />
public override async Task MergeAsync(IEnumerable<DocumentMetadata> items, CancellationToken cancellationToken = default)
public override async Task MergeAsync(IEnumerable<DocumentMetadata> items,
CancellationToken cancellationToken = default)
{
foreach (var item in items)
{
@@ -186,7 +192,8 @@ public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore wher
else
{
// Update only if incoming is newer
var existingTs = new HlcTimestamp(existing.HlcPhysicalTime, existing.HlcLogicalCounter, existing.HlcNodeId);
var existingTs = new HlcTimestamp(existing.HlcPhysicalTime, existing.HlcLogicalCounter,
existing.HlcNodeId);
if (item.UpdatedAt.CompareTo(existingTs) > 0)
{
existing.HlcPhysicalTime = item.UpdatedAt.PhysicalTime;
@@ -197,6 +204,7 @@ public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore wher
}
}
}
await _context.SaveChangesAsync(cancellationToken);
}
@@ -227,4 +235,4 @@ public class BLiteDocumentMetadataStore<TDbContext> : DocumentMetadataStore wher
}
#endregion
}
}

59
src/ZB.MOM.WW.CBDDC.Persistence/BLite/BLiteDocumentStore.README.md
View File

@@ -2,7 +2,8 @@
## Overview
`BLiteDocumentStore<TDbContext>` is an abstract base class that simplifies creating document stores for CBDDC with BLite persistence. It handles all Oplog management internally, so you only need to implement entity-to-JSON mapping methods.
`BLiteDocumentStore<TDbContext>` is an abstract base class that simplifies creating document stores for CBDDC with BLite
persistence. It handles all Oplog management internally, so you only need to implement entity-to-JSON mapping methods.
## Key Features
@@ -11,23 +12,24 @@
- ? **No CDC Events Needed** - Direct Oplog management eliminates event loops
- ? **Simple API** - Only 4 abstract methods to implement
## Architecture
```
User Code ? SampleDocumentStore (extends BLiteDocumentStore)
?
BLiteDocumentStore
??? _context.Users / TodoLists (read/write entities)
??? _context.OplogEntries (write oplog directly)
Remote Sync ? OplogStore.ApplyBatchAsync()
?
BLiteDocumentStore.PutDocumentAsync(fromSync=true)
??? _context.Users / TodoLists (write only)
??? _context.OplogEntries (skip - already exists)
```
**Key Advantage**: No circular dependency! `BLiteDocumentStore` writes directly to `CBDDCDocumentDbContext.OplogEntries` collection.
## Architecture
```
User Code ? SampleDocumentStore (extends BLiteDocumentStore)
?
BLiteDocumentStore
??? _context.Users / TodoLists (read/write entities)
??? _context.OplogEntries (write oplog directly)
Remote Sync ? OplogStore.ApplyBatchAsync()
?
BLiteDocumentStore.PutDocumentAsync(fromSync=true)
??? _context.Users / TodoLists (write only)
??? _context.OplogEntries (skip - already exists)
```
**Key Advantage**: No circular dependency! `BLiteDocumentStore` writes directly to `CBDDCDocumentDbContext.OplogEntries`
collection.
## Implementation Example
@@ -129,15 +131,15 @@ public class SampleDocumentStore : BLiteDocumentStore<SampleDbContext>
## Usage in Application
### Setup (DI Container)
```csharp
services.AddSingleton<SampleDbContext>(sp =>
new SampleDbContext("data/sample.blite"));
// No OplogStore dependency needed!
services.AddSingleton<IDocumentStore, SampleDocumentStore>();
services.AddSingleton<IOplogStore, BLiteOplogStore<SampleDbContext>>();
### Setup (DI Container)
```csharp
services.AddSingleton<SampleDbContext>(sp =>
new SampleDbContext("data/sample.blite"));
// No OplogStore dependency needed!
services.AddSingleton<IDocumentStore, SampleDocumentStore>();
services.AddSingleton<IOplogStore, BLiteOplogStore<SampleDbContext>>();
```
### Local Changes (User operations)
@@ -180,6 +182,7 @@ using (documentStore.BeginRemoteSync()) // ? Suppresses Oplog creation
## Migration from Old CDC-based Approach
### Before (with CDC Events)
```csharp
// SampleDocumentStore subscribes to BLite CDC
// CDC emits events ? OplogCoordinator creates Oplog
@@ -187,6 +190,7 @@ using (documentStore.BeginRemoteSync()) // ? Suppresses Oplog creation
```
### After (with BLiteDocumentStore)
```csharp
// Direct Oplog management in DocumentStore
// AsyncLocal flag prevents duplicates during sync
@@ -203,6 +207,7 @@ using (documentStore.BeginRemoteSync()) // ? Suppresses Oplog creation
## Next Steps
After implementing your DocumentStore:
1. Remove CDC subscriptions from your code
2. Remove `OplogCoordinator` from DI (no longer needed)
3. Test local operations create Oplog entries

523
src/ZB.MOM.WW.CBDDC.Persistence/BLite/BLiteDocumentStore.cs
View File

@@ -1,56 +1,50 @@
using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Linq;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;
using BLite.Core.CDC;
using BLite.Core.Collections;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.CBDDC.Core;
using ZB.MOM.WW.CBDDC.Core.Network;
using ZB.MOM.WW.CBDDC.Core.Storage;
using ZB.MOM.WW.CBDDC.Core.Sync;
using ZB.MOM.WW.CBDDC.Persistence.BLite.Entities;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using BLiteOperationType = BLite.Core.Transactions.OperationType;
namespace ZB.MOM.WW.CBDDC.Persistence.BLite;
/// <summary>
/// Abstract base class for BLite-based document stores.
/// Handles Oplog creation internally - subclasses only implement entity mapping.
/// </summary>
/// <typeparam name="TDbContext">The BLite DbContext type.</typeparam>
namespace ZB.MOM.WW.CBDDC.Persistence.BLite;
/// <summary>
/// Abstract base class for BLite-based document stores.
/// Handles Oplog creation internally - subclasses only implement entity mapping.
/// </summary>
/// <typeparam name="TDbContext">The BLite DbContext type.</typeparam>
public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposable
where TDbContext : CBDDCDocumentDbContext
{
protected readonly TDbContext _context;
private readonly List<IDisposable> _cdcWatchers = new();
private readonly object _clockLock = new();
protected readonly IPeerNodeConfigurationProvider _configProvider;
protected readonly IConflictResolver _conflictResolver;
protected readonly IVectorClockService _vectorClock;
protected readonly TDbContext _context;
protected readonly ILogger<BLiteDocumentStore<TDbContext>> _logger;
private readonly HashSet<string> _registeredCollections = new();
/// <summary>
/// Semaphore used to suppress CDC-triggered OplogEntry creation during remote sync.
/// CurrentCount == 0 ? sync in progress, CDC must skip.
/// CurrentCount == 1 ? no sync, CDC creates OplogEntry.
/// Semaphore used to suppress CDC-triggered OplogEntry creation during remote sync.
/// CurrentCount == 0 ? sync in progress, CDC must skip.
/// CurrentCount == 1 ? no sync, CDC creates OplogEntry.
/// </summary>
private readonly SemaphoreSlim _remoteSyncGuard = new SemaphoreSlim(1, 1);
private readonly ConcurrentDictionary<string, int> _suppressedCdcEvents = new(StringComparer.Ordinal);
private readonly SemaphoreSlim _remoteSyncGuard = new(1, 1);
private readonly List<IDisposable> _cdcWatchers = new();
private readonly HashSet<string> _registeredCollections = new();
private readonly ConcurrentDictionary<string, int> _suppressedCdcEvents = new(StringComparer.Ordinal);
protected readonly IVectorClockService _vectorClock;
// HLC state for generating timestamps for local changes
private long _lastPhysicalTime;
private int _logicalCounter;
private readonly object _clockLock = new object();
/// <summary>
/// Initializes a new instance of the <see cref="BLiteDocumentStore{TDbContext}"/> class.
/// Initializes a new instance of the <see cref="BLiteDocumentStore{TDbContext}" /> class.
/// </summary>
/// <param name="context">The BLite database context.</param>
/// <param name="configProvider">The peer node configuration provider.</param>
@@ -74,17 +68,29 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
_logicalCounter = 0;
}
/// <summary>
/// Releases managed resources used by this document store.
/// </summary>
public virtual void Dispose()
{
foreach (var watcher in _cdcWatchers)
try
{
watcher.Dispose();
}
catch
{
}
_cdcWatchers.Clear();
_remoteSyncGuard.Dispose();
}
private static ILogger<BLiteDocumentStore<TDbContext>> CreateTypedLogger(ILogger? logger)
{
if (logger is null)
{
return NullLogger<BLiteDocumentStore<TDbContext>>.Instance;
}
if (logger is null) return NullLogger<BLiteDocumentStore<TDbContext>>.Instance;
if (logger is ILogger<BLiteDocumentStore<TDbContext>> typedLogger)
{
return typedLogger;
}
if (logger is ILogger<BLiteDocumentStore<TDbContext>> typedLogger) return typedLogger;
return new ForwardingLogger(logger);
}
@@ -94,7 +100,7 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
private readonly ILogger _inner;
/// <summary>
/// Initializes a new instance of the <see cref="ForwardingLogger"/> class.
/// Initializes a new instance of the <see cref="ForwardingLogger" /> class.
/// </summary>
/// <param name="inner">The underlying logger instance.</param>
public ForwardingLogger(ILogger inner)
@@ -135,35 +141,26 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
private void RegisterSuppressedCdcEvent(string collection, string key, OperationType operationType)
{
var suppressionKey = BuildSuppressionKey(collection, key, operationType);
string suppressionKey = BuildSuppressionKey(collection, key, operationType);
_suppressedCdcEvents.AddOrUpdate(suppressionKey, 1, (_, current) => current + 1);
}
private bool TryConsumeSuppressedCdcEvent(string collection, string key, OperationType operationType)
{
var suppressionKey = BuildSuppressionKey(collection, key, operationType);
string suppressionKey = BuildSuppressionKey(collection, key, operationType);
while (true)
{
if (!_suppressedCdcEvents.TryGetValue(suppressionKey, out var current))
{
return false;
}
if (!_suppressedCdcEvents.TryGetValue(suppressionKey, out int current)) return false;
if (current <= 1)
{
return _suppressedCdcEvents.TryRemove(suppressionKey, out _);
}
if (current <= 1) return _suppressedCdcEvents.TryRemove(suppressionKey, out _);
if (_suppressedCdcEvents.TryUpdate(suppressionKey, current - 1, current))
{
return true;
}
if (_suppressedCdcEvents.TryUpdate(suppressionKey, current - 1, current)) return true;
}
}
/// <summary>
/// Registers a BLite collection for CDC tracking.
/// Call in subclass constructor for each collection to sync.
/// Registers a BLite collection for CDC tracking.
/// Call in subclass constructor for each collection to sync.
/// </summary>
/// <typeparam name="TEntity">The entity type.</typeparam>
/// <param name="collectionName">The logical collection name used in Oplog.</param>
@@ -177,14 +174,14 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
{
_registeredCollections.Add(collectionName);
var watcher = collection.Watch(capturePayload: true)
var watcher = collection.Watch(true)
.Subscribe(new CdcObserver<TEntity>(collectionName, keySelector, this));
_cdcWatchers.Add(watcher);
}
/// <summary>
/// Generic CDC observer. Forwards BLite change events to OnLocalChangeDetectedAsync.
/// Automatically skips events when remote sync is in progress.
/// Generic CDC observer. Forwards BLite change events to OnLocalChangeDetectedAsync.
/// Automatically skips events when remote sync is in progress.
/// </summary>
private class CdcObserver<TEntity> : IObserver<ChangeStreamEvent<string, TEntity>>
where TEntity : class
@@ -194,7 +191,7 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
private readonly BLiteDocumentStore<TDbContext> _store;
/// <summary>
/// Initializes a new instance of the <see cref="CdcObserver{TEntity}"/> class.
/// Initializes a new instance of the <see cref="CdcObserver{TEntity}" /> class.
/// </summary>
/// <param name="collectionName">The logical collection name.</param>
/// <param name="keySelector">The key selector for observed entities.</param>
@@ -210,23 +207,20 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
}
/// <summary>
/// Handles a change stream event from BLite CDC.
/// Handles a change stream event from BLite CDC.
/// </summary>
/// <param name="changeEvent">The change event payload.</param>
public void OnNext(ChangeStreamEvent<string, TEntity> changeEvent)
{
var operationType = changeEvent.Type == BLiteOperationType.Delete ? OperationType.Delete : OperationType.Put;
var operationType = changeEvent.Type == BLiteOperationType.Delete
? OperationType.Delete
: OperationType.Put;
var entityId = changeEvent.DocumentId?.ToString() ?? "";
string entityId = changeEvent.DocumentId ?? "";
if (operationType == OperationType.Put && changeEvent.Entity != null)
{
entityId = _keySelector(changeEvent.Entity);
}
if (_store.TryConsumeSuppressedCdcEvent(_collectionName, entityId, operationType))
{
return;
}
if (_store.TryConsumeSuppressedCdcEvent(_collectionName, entityId, operationType)) return;
if (_store._remoteSyncGuard.CurrentCount == 0) return;
@@ -238,22 +232,26 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
else if (changeEvent.Entity != null)
{
var content = JsonSerializer.SerializeToElement(changeEvent.Entity);
var key = _keySelector(changeEvent.Entity);
string key = _keySelector(changeEvent.Entity);
_store.OnLocalChangeDetectedAsync(_collectionName, key, OperationType.Put, content)
.GetAwaiter().GetResult();
}
}
/// <summary>
/// Handles CDC observer errors.
/// Handles CDC observer errors.
/// </summary>
/// <param name="error">The observed exception.</param>
public void OnError(Exception error) { }
public void OnError(Exception error)
{
}
/// <summary>
/// Handles completion of the CDC stream.
/// Handles completion of the CDC stream.
/// </summary>
public void OnCompleted() { }
public void OnCompleted()
{
}
}
#endregion
@@ -261,8 +259,8 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
#region Abstract Methods - Implemented by subclass
/// <summary>
/// Applies JSON content to a single entity (insert or update) and commits changes.
/// Called for single-document operations.
/// Applies JSON content to a single entity (insert or update) and commits changes.
/// Called for single-document operations.
/// </summary>
/// <param name="collection">The logical collection name.</param>
/// <param name="key">The document key.</param>
@@ -272,16 +270,17 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
string collection, string key, JsonElement content, CancellationToken cancellationToken);
/// <summary>
/// Applies JSON content to multiple entities (insert or update) with a single commit.
/// Called for batch operations. Must commit all changes in a single SaveChanges.
/// Applies JSON content to multiple entities (insert or update) with a single commit.
/// Called for batch operations. Must commit all changes in a single SaveChanges.
/// </summary>
/// <param name="documents">The documents to apply in one batch.</param>
/// <param name="cancellationToken">The cancellation token.</param>
protected abstract Task ApplyContentToEntitiesBatchAsync(
IEnumerable<(string Collection, string Key, JsonElement Content)> documents, CancellationToken cancellationToken);
IEnumerable<(string Collection, string Key, JsonElement Content)> documents,
CancellationToken cancellationToken);
/// <summary>
/// Reads an entity from the DbContext and returns it as JsonElement.
/// Reads an entity from the DbContext and returns it as JsonElement.
/// </summary>
/// <param name="collection">The logical collection name.</param>
/// <param name="key">The document key.</param>
@@ -290,7 +289,7 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
string collection, string key, CancellationToken cancellationToken);
/// <summary>
/// Removes a single entity from the DbContext and commits changes.
/// Removes a single entity from the DbContext and commits changes.
/// </summary>
/// <param name="collection">The logical collection name.</param>
/// <param name="key">The document key.</param>
@@ -299,7 +298,7 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
string collection, string key, CancellationToken cancellationToken);
/// <summary>
/// Removes multiple entities from the DbContext with a single commit.
/// Removes multiple entities from the DbContext with a single commit.
/// </summary>
/// <param name="documents">The documents to remove in one batch.</param>
/// <param name="cancellationToken">The cancellation token.</param>
@@ -307,45 +306,47 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
IEnumerable<(string Collection, string Key)> documents, CancellationToken cancellationToken);
/// <summary>
/// Reads all entities from a collection as JsonElements.
/// Reads all entities from a collection as JsonElements.
/// </summary>
/// <param name="collection">The logical collection name.</param>
/// <param name="cancellationToken">The cancellation token.</param>
protected abstract Task<IEnumerable<(string Key, JsonElement Content)>> GetAllEntitiesAsJsonAsync(
string collection, CancellationToken cancellationToken);
#endregion
#endregion
#region IDocumentStore Implementation
/// <summary>
/// Returns the collections registered via WatchCollection.
/// Returns the collections registered via WatchCollection.
/// </summary>
public IEnumerable<string> InterestedCollection => _registeredCollections;
/// <summary>
/// Gets a document by collection and key.
/// Gets a document by collection and key.
/// </summary>
/// <param name="collection">The logical collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The matching document, or <see langword="null"/> when not found.</returns>
public async Task<Document?> GetDocumentAsync(string collection, string key, CancellationToken cancellationToken = default)
/// <returns>The matching document, or <see langword="null" /> when not found.</returns>
public async Task<Document?> GetDocumentAsync(string collection, string key,
CancellationToken cancellationToken = default)
{
var content = await GetEntityAsJsonAsync(collection, key, cancellationToken);
if (content == null) return null;
var timestamp = new HlcTimestamp(0, 0, ""); // Will be populated from metadata if needed
return new Document(collection, key, content.Value, timestamp, false);
}
/// <summary>
/// Gets all documents for a collection.
/// Gets all documents for a collection.
/// </summary>
/// <param name="collection">The logical collection name.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The documents in the specified collection.</returns>
public async Task<IEnumerable<Document>> GetDocumentsByCollectionAsync(string collection, CancellationToken cancellationToken = default)
public async Task<IEnumerable<Document>> GetDocumentsByCollectionAsync(string collection,
CancellationToken cancellationToken = default)
{
var entities = await GetAllEntitiesAsJsonAsync(collection, cancellationToken);
var timestamp = new HlcTimestamp(0, 0, "");
@@ -353,31 +354,30 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
}
/// <summary>
/// Gets documents for the specified collection and key pairs.
/// Gets documents for the specified collection and key pairs.
/// </summary>
/// <param name="documentKeys">The collection and key pairs to resolve.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The documents that were found.</returns>
public async Task<IEnumerable<Document>> GetDocumentsAsync(List<(string Collection, string Key)> documentKeys, CancellationToken cancellationToken)
public async Task<IEnumerable<Document>> GetDocumentsAsync(List<(string Collection, string Key)> documentKeys,
CancellationToken cancellationToken)
{
var documents = new List<Document>();
foreach (var (collection, key) in documentKeys)
{
var doc = await GetDocumentAsync(collection, key, cancellationToken);
if (doc != null)
{
documents.Add(doc);
}
foreach ((string collection, string key) in documentKeys)
{
var doc = await GetDocumentAsync(collection, key, cancellationToken);
if (doc != null) documents.Add(doc);
}
return documents;
}
/// <summary>
/// Inserts or updates a single document.
/// Inserts or updates a single document.
/// </summary>
/// <param name="document">The document to persist.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns><see langword="true"/> when the operation succeeds.</returns>
/// <returns><see langword="true" /> when the operation succeeds.</returns>
public async Task<bool> PutDocumentAsync(Document document, CancellationToken cancellationToken = default)
{
await _remoteSyncGuard.WaitAsync(cancellationToken);
@@ -389,6 +389,7 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
{
_remoteSyncGuard.Release();
}
return true;
}
@@ -399,21 +400,20 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
}
/// <summary>
/// Updates a batch of documents.
/// Updates a batch of documents.
/// </summary>
/// <param name="documents">The documents to update.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns><see langword="true"/> when the operation succeeds.</returns>
public async Task<bool> UpdateBatchDocumentsAsync(IEnumerable<Document> documents, CancellationToken cancellationToken = default)
/// <returns><see langword="true" /> when the operation succeeds.</returns>
public async Task<bool> UpdateBatchDocumentsAsync(IEnumerable<Document> documents,
CancellationToken cancellationToken = default)
{
var documentList = documents.ToList();
await _remoteSyncGuard.WaitAsync(cancellationToken);
try
{
foreach (var document in documentList)
{
RegisterSuppressedCdcEvent(document.Collection, document.Key, OperationType.Put);
}
await ApplyContentToEntitiesBatchAsync(
documentList.Select(d => (d.Collection, d.Key, d.Content)), cancellationToken);
@@ -422,25 +422,25 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
{
_remoteSyncGuard.Release();
}
return true;
}
/// <summary>
/// Inserts a batch of documents.
/// Inserts a batch of documents.
/// </summary>
/// <param name="documents">The documents to insert.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns><see langword="true"/> when the operation succeeds.</returns>
public async Task<bool> InsertBatchDocumentsAsync(IEnumerable<Document> documents, CancellationToken cancellationToken = default)
/// <returns><see langword="true" /> when the operation succeeds.</returns>
public async Task<bool> InsertBatchDocumentsAsync(IEnumerable<Document> documents,
CancellationToken cancellationToken = default)
{
var documentList = documents.ToList();
await _remoteSyncGuard.WaitAsync(cancellationToken);
try
{
foreach (var document in documentList)
{
RegisterSuppressedCdcEvent(document.Collection, document.Key, OperationType.Put);
}
await ApplyContentToEntitiesBatchAsync(
documentList.Select(d => (d.Collection, d.Key, d.Content)), cancellationToken);
@@ -449,17 +449,19 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
{
_remoteSyncGuard.Release();
}
return true;
}
/// <summary>
/// Deletes a single document.
/// Deletes a single document.
/// </summary>
/// <param name="collection">The logical collection name.</param>
/// <param name="key">The document key.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns><see langword="true"/> when the operation succeeds.</returns>
public async Task<bool> DeleteDocumentAsync(string collection, string key, CancellationToken cancellationToken = default)
/// <returns><see langword="true" /> when the operation succeeds.</returns>
public async Task<bool> DeleteDocumentAsync(string collection, string key,
CancellationToken cancellationToken = default)
{
await _remoteSyncGuard.WaitAsync(cancellationToken);
try
@@ -470,6 +472,7 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
{
_remoteSyncGuard.Release();
}
return true;
}
@@ -480,25 +483,22 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
}
/// <summary>
/// Deletes a batch of documents by composite keys.
/// Deletes a batch of documents by composite keys.
/// </summary>
/// <param name="documentKeys">The document keys in collection/key format.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns><see langword="true"/> when the operation succeeds.</returns>
public async Task<bool> DeleteBatchDocumentsAsync(IEnumerable<string> documentKeys, CancellationToken cancellationToken = default)
/// <returns><see langword="true" /> when the operation succeeds.</returns>
public async Task<bool> DeleteBatchDocumentsAsync(IEnumerable<string> documentKeys,
CancellationToken cancellationToken = default)
{
var parsedKeys = new List<(string Collection, string Key)>();
foreach (var key in documentKeys)
foreach (string key in documentKeys)
{
var parts = key.Split('/');
string[] parts = key.Split('/');
if (parts.Length == 2)
{
parsedKeys.Add((parts[0], parts[1]));
}
else
{
_logger.LogWarning("Invalid document key format: {Key}", key);
}
}
if (parsedKeys.Count == 0) return true;
@@ -506,10 +506,8 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
await _remoteSyncGuard.WaitAsync(cancellationToken);
try
{
foreach (var (collection, key) in parsedKeys)
{
foreach ((string collection, string key) in parsedKeys)
RegisterSuppressedCdcEvent(collection, key, OperationType.Delete);
}
await RemoveEntitiesBatchAsync(parsedKeys, cancellationToken);
}
@@ -517,11 +515,12 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
{
_remoteSyncGuard.Release();
}
return true;
}
/// <summary>
/// Merges an incoming document with the current stored document.
/// Merges an incoming document with the current stored document.
/// </summary>
/// <param name="incoming">The incoming document.</param>
/// <param name="cancellationToken">The cancellation token.</param>
@@ -553,46 +552,44 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
}
return existing;
}
#endregion
}
#endregion
#region ISnapshotable Implementation
/// <summary>
/// Removes all tracked documents from registered collections.
/// Removes all tracked documents from registered collections.
/// </summary>
/// <param name="cancellationToken">The cancellation token.</param>
public async Task DropAsync(CancellationToken cancellationToken = default)
{
foreach (var collection in InterestedCollection)
foreach (string collection in InterestedCollection)
{
var entities = await GetAllEntitiesAsJsonAsync(collection, cancellationToken);
foreach (var (key, _) in entities)
{
await RemoveEntityAsync(collection, key, cancellationToken);
}
var entities = await GetAllEntitiesAsJsonAsync(collection, cancellationToken);
foreach ((string key, var _) in entities) await RemoveEntityAsync(collection, key, cancellationToken);
}
}
/// <summary>
/// Exports all tracked documents from registered collections.
/// Exports all tracked documents from registered collections.
/// </summary>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The exported documents.</returns>
public async Task<IEnumerable<Document>> ExportAsync(CancellationToken cancellationToken = default)
{
var documents = new List<Document>();
foreach (var collection in InterestedCollection)
{
var collectionDocs = await GetDocumentsByCollectionAsync(collection, cancellationToken);
documents.AddRange(collectionDocs);
foreach (string collection in InterestedCollection)
{
var collectionDocs = await GetDocumentsByCollectionAsync(collection, cancellationToken);
documents.AddRange(collectionDocs);
}
return documents;
}
/// <summary>
/// Imports a batch of documents.
/// Imports a batch of documents.
/// </summary>
/// <param name="items">The documents to import.</param>
/// <param name="cancellationToken">The cancellation token.</param>
@@ -603,9 +600,7 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
try
{
foreach (var document in documents)
{
RegisterSuppressedCdcEvent(document.Collection, document.Key, OperationType.Put);
}
await ApplyContentToEntitiesBatchAsync(
documents.Select(d => (d.Collection, d.Key, d.Content)), cancellationToken);
@@ -617,7 +612,7 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
}
/// <summary>
/// Merges a batch of incoming documents.
/// Merges a batch of incoming documents.
/// </summary>
/// <param name="items">The incoming documents.</param>
/// <param name="cancellationToken">The cancellation token.</param>
@@ -625,32 +620,29 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
{
// Acquire guard to prevent Oplog creation during merge
await _remoteSyncGuard.WaitAsync(cancellationToken);
try
{
foreach (var document in items)
{
await MergeAsync(document, cancellationToken);
}
}
finally
{
_remoteSyncGuard.Release();
}
}
#endregion
#region Oplog Management
/// <summary>
/// Returns true if a remote sync operation is in progress (guard acquired).
/// CDC listeners should check this before creating OplogEntry.
/// </summary>
protected bool IsRemoteSyncInProgress => _remoteSyncGuard.CurrentCount == 0;
try
{
foreach (var document in items) await MergeAsync(document, cancellationToken);
}
finally
{
_remoteSyncGuard.Release();
}
}
#endregion
#region Oplog Management
/// <summary>
/// Called by subclass CDC listeners when a local change is detected.
/// Creates OplogEntry + DocumentMetadata only if no remote sync is in progress.
/// Returns true if a remote sync operation is in progress (guard acquired).
/// CDC listeners should check this before creating OplogEntry.
/// </summary>
protected bool IsRemoteSyncInProgress => _remoteSyncGuard.CurrentCount == 0;
/// <summary>
/// Called by subclass CDC listeners when a local change is detected.
/// Creates OplogEntry + DocumentMetadata only if no remote sync is in progress.
/// </summary>
/// <param name="collection">The logical collection name.</param>
/// <param name="key">The document key.</param>
@@ -661,90 +653,90 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
string collection,
string key,
OperationType operationType,
JsonElement? content,
CancellationToken cancellationToken = default)
{
if (IsRemoteSyncInProgress) return;
await CreateOplogEntryAsync(collection, key, operationType, content, cancellationToken);
}
private HlcTimestamp GenerateTimestamp(string nodeId)
{
lock (_clockLock)
{
var now = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
JsonElement? content,
CancellationToken cancellationToken = default)
{
if (IsRemoteSyncInProgress) return;
if (now > _lastPhysicalTime)
{
_lastPhysicalTime = now;
_logicalCounter = 0;
}
else
{
_logicalCounter++;
await CreateOplogEntryAsync(collection, key, operationType, content, cancellationToken);
}
private HlcTimestamp GenerateTimestamp(string nodeId)
{
lock (_clockLock)
{
long now = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
if (now > _lastPhysicalTime)
{
_lastPhysicalTime = now;
_logicalCounter = 0;
}
else
{
_logicalCounter++;
}
return new HlcTimestamp(_lastPhysicalTime, _logicalCounter, nodeId);
}
}
private async Task CreateOplogEntryAsync(
return new HlcTimestamp(_lastPhysicalTime, _logicalCounter, nodeId);
}
}
private async Task CreateOplogEntryAsync(
string collection,
string key,
OperationType operationType,
JsonElement? content,
CancellationToken cancellationToken)
{
var config = await _configProvider.GetConfiguration();
var nodeId = config.NodeId;
// Get last hash from OplogEntries collection directly
var lastEntry = _context.OplogEntries
.Find(e => e.TimestampNodeId == nodeId)
.OrderByDescending(e => e.TimestampPhysicalTime)
.ThenByDescending(e => e.TimestampLogicalCounter)
.FirstOrDefault();
var previousHash = lastEntry?.Hash ?? string.Empty;
var timestamp = GenerateTimestamp(nodeId);
var oplogEntry = new OplogEntry(
collection,
key,
operationType,
content,
timestamp,
previousHash);
// Write directly to OplogEntries collection
await _context.OplogEntries.InsertAsync(oplogEntry.ToEntity());
// Write DocumentMetadata for sync tracking
var docMetadata = EntityMappers.CreateDocumentMetadata(
JsonElement? content,
CancellationToken cancellationToken)
{
var config = await _configProvider.GetConfiguration();
string nodeId = config.NodeId;
// Get last hash from OplogEntries collection directly
var lastEntry = _context.OplogEntries
.Find(e => e.TimestampNodeId == nodeId)
.OrderByDescending(e => e.TimestampPhysicalTime)
.ThenByDescending(e => e.TimestampLogicalCounter)
.FirstOrDefault();
string previousHash = lastEntry?.Hash ?? string.Empty;
var timestamp = GenerateTimestamp(nodeId);
var oplogEntry = new OplogEntry(
collection,
key,
operationType,
content,
timestamp,
previousHash);
// Write directly to OplogEntries collection
await _context.OplogEntries.InsertAsync(oplogEntry.ToEntity());
// Write DocumentMetadata for sync tracking
var docMetadata = EntityMappers.CreateDocumentMetadata(
collection,
key,
timestamp,
isDeleted: operationType == OperationType.Delete);
var existingMetadata = _context.DocumentMetadatas
.Find(m => m.Collection == collection && m.Key == key)
.FirstOrDefault();
if (existingMetadata != null)
{
// Update existing metadata
existingMetadata.HlcPhysicalTime = timestamp.PhysicalTime;
existingMetadata.HlcLogicalCounter = timestamp.LogicalCounter;
existingMetadata.HlcNodeId = timestamp.NodeId;
existingMetadata.IsDeleted = operationType == OperationType.Delete;
await _context.DocumentMetadatas.UpdateAsync(existingMetadata);
}
else
{
await _context.DocumentMetadatas.InsertAsync(docMetadata);
}
operationType == OperationType.Delete);
var existingMetadata = _context.DocumentMetadatas
.Find(m => m.Collection == collection && m.Key == key)
.FirstOrDefault();
if (existingMetadata != null)
{
// Update existing metadata
existingMetadata.HlcPhysicalTime = timestamp.PhysicalTime;
existingMetadata.HlcLogicalCounter = timestamp.LogicalCounter;
existingMetadata.HlcNodeId = timestamp.NodeId;
existingMetadata.IsDeleted = operationType == OperationType.Delete;
await _context.DocumentMetadatas.UpdateAsync(existingMetadata);
}
else
{
await _context.DocumentMetadatas.InsertAsync(docMetadata);
}
await _context.SaveChangesAsync(cancellationToken);
// Notify VectorClockService so sync sees local changes
@@ -753,24 +745,24 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
_logger.LogDebug(
"Created Oplog entry: {Operation} {Collection}/{Key} at {Timestamp} (hash: {Hash})",
operationType, collection, key, timestamp, oplogEntry.Hash);
}
/// <summary>
/// Marks the start of remote sync operations (suppresses CDC-triggered Oplog creation).
/// Use in using statement: using (store.BeginRemoteSync()) { ... }
/// </summary>
public IDisposable BeginRemoteSync()
{
_remoteSyncGuard.Wait();
return new RemoteSyncScope(_remoteSyncGuard);
}
}
/// <summary>
/// Marks the start of remote sync operations (suppresses CDC-triggered Oplog creation).
/// Use in using statement: using (store.BeginRemoteSync()) { ... }
/// </summary>
public IDisposable BeginRemoteSync()
{
_remoteSyncGuard.Wait();
return new RemoteSyncScope(_remoteSyncGuard);
}
private class RemoteSyncScope : IDisposable
{
private readonly SemaphoreSlim _guard;
/// <summary>
/// Initializes a new instance of the <see cref="RemoteSyncScope"/> class.
/// Initializes a new instance of the <see cref="RemoteSyncScope" /> class.
/// </summary>
/// <param name="guard">The semaphore guarding remote sync operations.</param>
public RemoteSyncScope(SemaphoreSlim guard)
@@ -779,26 +771,13 @@ public abstract class BLiteDocumentStore<TDbContext> : IDocumentStore, IDisposab
}
/// <summary>
/// Releases the remote sync guard.
/// Releases the remote sync guard.
/// </summary>
public void Dispose()
{
_guard.Release();
}
}
}
#endregion
/// <summary>
/// Releases managed resources used by this document store.
/// </summary>
public virtual void Dispose()
{
foreach (var watcher in _cdcWatchers)
{
try { watcher.Dispose(); } catch { }
}
_cdcWatchers.Clear();
_remoteSyncGuard.Dispose();
}
}
}

Some files were not shown because too many files have changed in this diff Show More