docs consolidation and others
This commit is contained in:
master
@@ -0,0 +1,49 @@
|
||||
// -----------------------------------------------------------------------------
|
||||
// HlcClockSkewException.cs
|
||||
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
|
||||
// Task: HLC-003 - Clock skew exception
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
namespace StellaOps.HybridLogicalClock;
|
||||
|
||||
/// <summary>
|
||||
/// Exception thrown when clock skew between nodes exceeds the configured threshold.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Clock skew indicates that two nodes have significantly different wall-clock times,
|
||||
/// which could indicate NTP misconfiguration or network partitioning issues.
|
||||
/// </remarks>
|
||||
public sealed class HlcClockSkewException : Exception
|
||||
{
|
||||
/// <summary>
|
||||
/// The actual skew detected between clocks.
|
||||
/// </summary>
|
||||
public TimeSpan ActualSkew { get; }
|
||||
|
||||
/// <summary>
|
||||
/// The maximum skew threshold that was configured.
|
||||
/// </summary>
|
||||
public TimeSpan MaxAllowedSkew { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Creates a new clock skew exception.
|
||||
/// </summary>
|
||||
/// <param name="actualSkew">The actual skew detected</param>
|
||||
/// <param name="maxAllowedSkew">The configured maximum skew</param>
|
||||
public HlcClockSkewException(TimeSpan actualSkew, TimeSpan maxAllowedSkew)
|
||||
: base($"Clock skew of {actualSkew.TotalSeconds:F1}s exceeds maximum allowed skew of {maxAllowedSkew.TotalSeconds:F1}s")
|
||||
{
|
||||
ActualSkew = actualSkew;
|
||||
MaxAllowedSkew = maxAllowedSkew;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a new clock skew exception with inner exception.
|
||||
/// </summary>
|
||||
public HlcClockSkewException(TimeSpan actualSkew, TimeSpan maxAllowedSkew, Exception innerException)
|
||||
: base($"Clock skew of {actualSkew.TotalSeconds:F1}s exceeds maximum allowed skew of {maxAllowedSkew.TotalSeconds:F1}s", innerException)
|
||||
{
|
||||
ActualSkew = actualSkew;
|
||||
MaxAllowedSkew = maxAllowedSkew;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,127 @@
|
||||
// -----------------------------------------------------------------------------
|
||||
// HlcServiceCollectionExtensions.cs
|
||||
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
|
||||
// Task: HLC-011 - Create HlcServiceCollectionExtensions for DI registration
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using Microsoft.Extensions.DependencyInjection.Extensions;
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
namespace StellaOps.HybridLogicalClock;
|
||||
|
||||
/// <summary>
|
||||
/// Extension methods for configuring HLC services in DI container.
|
||||
/// </summary>
|
||||
public static class HlcServiceCollectionExtensions
|
||||
{
|
||||
/// <summary>
|
||||
/// Adds HLC services with in-memory state storage (for development/testing).
|
||||
/// </summary>
|
||||
/// <param name="services">Service collection</param>
|
||||
/// <param name="nodeId">Unique node identifier</param>
|
||||
/// <param name="maxClockSkew">Maximum allowed clock skew (default: 1 minute)</param>
|
||||
/// <returns>Service collection for chaining</returns>
|
||||
public static IServiceCollection AddHybridLogicalClock(
|
||||
this IServiceCollection services,
|
||||
string nodeId,
|
||||
TimeSpan? maxClockSkew = null)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(services);
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
|
||||
|
||||
services.TryAddSingleton(TimeProvider.System);
|
||||
services.TryAddSingleton<IHlcStateStore, InMemoryHlcStateStore>();
|
||||
|
||||
services.AddSingleton<IHybridLogicalClock>(sp =>
|
||||
{
|
||||
var timeProvider = sp.GetRequiredService<TimeProvider>();
|
||||
var stateStore = sp.GetRequiredService<IHlcStateStore>();
|
||||
var logger = sp.GetRequiredService<ILogger<HybridLogicalClock>>();
|
||||
|
||||
return new HybridLogicalClock(
|
||||
timeProvider,
|
||||
nodeId,
|
||||
stateStore,
|
||||
logger,
|
||||
maxClockSkew);
|
||||
});
|
||||
|
||||
return services;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Adds HLC services with custom state storage.
|
||||
/// </summary>
|
||||
/// <typeparam name="TStateStore">State store implementation type</typeparam>
|
||||
/// <param name="services">Service collection</param>
|
||||
/// <param name="nodeId">Unique node identifier</param>
|
||||
/// <param name="maxClockSkew">Maximum allowed clock skew (default: 1 minute)</param>
|
||||
/// <returns>Service collection for chaining</returns>
|
||||
public static IServiceCollection AddHybridLogicalClock<TStateStore>(
|
||||
this IServiceCollection services,
|
||||
string nodeId,
|
||||
TimeSpan? maxClockSkew = null)
|
||||
where TStateStore : class, IHlcStateStore
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(services);
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
|
||||
|
||||
services.TryAddSingleton(TimeProvider.System);
|
||||
services.TryAddSingleton<IHlcStateStore, TStateStore>();
|
||||
|
||||
services.AddSingleton<IHybridLogicalClock>(sp =>
|
||||
{
|
||||
var timeProvider = sp.GetRequiredService<TimeProvider>();
|
||||
var stateStore = sp.GetRequiredService<IHlcStateStore>();
|
||||
var logger = sp.GetRequiredService<ILogger<HybridLogicalClock>>();
|
||||
|
||||
return new HybridLogicalClock(
|
||||
timeProvider,
|
||||
nodeId,
|
||||
stateStore,
|
||||
logger,
|
||||
maxClockSkew);
|
||||
});
|
||||
|
||||
return services;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Adds HLC services with factory-based state storage.
|
||||
/// </summary>
|
||||
/// <param name="services">Service collection</param>
|
||||
/// <param name="nodeId">Unique node identifier</param>
|
||||
/// <param name="stateStoreFactory">Factory function to create state store</param>
|
||||
/// <param name="maxClockSkew">Maximum allowed clock skew (default: 1 minute)</param>
|
||||
/// <returns>Service collection for chaining</returns>
|
||||
public static IServiceCollection AddHybridLogicalClock(
|
||||
this IServiceCollection services,
|
||||
string nodeId,
|
||||
Func<IServiceProvider, IHlcStateStore> stateStoreFactory,
|
||||
TimeSpan? maxClockSkew = null)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(services);
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
|
||||
ArgumentNullException.ThrowIfNull(stateStoreFactory);
|
||||
|
||||
services.TryAddSingleton(TimeProvider.System);
|
||||
services.TryAddSingleton(stateStoreFactory);
|
||||
|
||||
services.AddSingleton<IHybridLogicalClock>(sp =>
|
||||
{
|
||||
var timeProvider = sp.GetRequiredService<TimeProvider>();
|
||||
var stateStore = sp.GetRequiredService<IHlcStateStore>();
|
||||
var logger = sp.GetRequiredService<ILogger<HybridLogicalClock>>();
|
||||
|
||||
return new HybridLogicalClock(
|
||||
timeProvider,
|
||||
nodeId,
|
||||
stateStore,
|
||||
logger,
|
||||
maxClockSkew);
|
||||
});
|
||||
|
||||
return services;
|
||||
}
|
||||
}
|
||||
206
src/__Libraries/StellaOps.HybridLogicalClock/HlcTimestamp.cs
Normal file
206
src/__Libraries/StellaOps.HybridLogicalClock/HlcTimestamp.cs
Normal file
@@ -0,0 +1,206 @@
|
||||
// -----------------------------------------------------------------------------
|
||||
// HlcTimestamp.cs
|
||||
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
|
||||
// Task: HLC-002 - Implement HlcTimestamp record with comparison, parsing, serialization
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
using System.Globalization;
|
||||
using System.Text.RegularExpressions;
|
||||
|
||||
namespace StellaOps.HybridLogicalClock;
|
||||
|
||||
/// <summary>
|
||||
/// Hybrid Logical Clock timestamp providing monotonic, causally-ordered time
|
||||
/// across distributed nodes even under clock skew.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// HLC timestamps combine physical (wall-clock) time with a logical counter to ensure:
|
||||
/// 1. Monotonicity: Timestamps always increase within a node
|
||||
/// 2. Causal ordering: If event A happens-before event B, timestamp(A) < timestamp(B)
|
||||
/// 3. Skew tolerance: Works correctly even when node clocks differ
|
||||
/// </remarks>
|
||||
public readonly record struct HlcTimestamp : IComparable<HlcTimestamp>
|
||||
{
|
||||
private static readonly Regex ParseRegex = new(
|
||||
@"^(\d{13})-(.+)-(\d{6})$",
|
||||
RegexOptions.Compiled | RegexOptions.CultureInvariant);
|
||||
|
||||
/// <summary>
|
||||
/// Physical time component (Unix milliseconds UTC).
|
||||
/// </summary>
|
||||
public required long PhysicalTime { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Unique node identifier (e.g., "scheduler-east-1").
|
||||
/// </summary>
|
||||
public required string NodeId { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Logical counter for events at same physical time.
|
||||
/// </summary>
|
||||
public required int LogicalCounter { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Creates an HLC timestamp from the current wall-clock time.
|
||||
/// </summary>
|
||||
/// <param name="nodeId">Node identifier for this timestamp</param>
|
||||
/// <param name="timeProvider">Time provider for wall-clock time</param>
|
||||
/// <returns>New HLC timestamp with counter set to 0</returns>
|
||||
public static HlcTimestamp Now(string nodeId, TimeProvider timeProvider)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
|
||||
ArgumentNullException.ThrowIfNull(timeProvider);
|
||||
|
||||
return new HlcTimestamp
|
||||
{
|
||||
PhysicalTime = timeProvider.GetUtcNow().ToUnixTimeMilliseconds(),
|
||||
NodeId = nodeId,
|
||||
LogicalCounter = 0
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the timestamp as a DateTimeOffset.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Note: This only reflects the physical time component.
|
||||
/// The logical counter is not represented in DateTimeOffset.
|
||||
/// </remarks>
|
||||
public DateTimeOffset ToDateTimeOffset() =>
|
||||
DateTimeOffset.FromUnixTimeMilliseconds(PhysicalTime);
|
||||
|
||||
/// <summary>
|
||||
/// String representation for storage and sorting.
|
||||
/// Format: "1704067200000-scheduler-east-1-000042"
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The format ensures lexicographic ordering matches logical ordering:
|
||||
/// - 13-digit physical time (zero-padded) sorts chronologically
|
||||
/// - Node ID provides tie-breaking for concurrent events
|
||||
/// - 6-digit counter (zero-padded) handles same-millisecond events
|
||||
/// </remarks>
|
||||
public string ToSortableString() =>
|
||||
string.Create(CultureInfo.InvariantCulture, $"{PhysicalTime:D13}-{NodeId}-{LogicalCounter:D6}");
|
||||
|
||||
/// <summary>
|
||||
/// Parse from sortable string format.
|
||||
/// </summary>
|
||||
/// <param name="value">String in format "1704067200000-nodeid-000042"</param>
|
||||
/// <returns>Parsed HLC timestamp</returns>
|
||||
/// <exception cref="FormatException">If the string format is invalid</exception>
|
||||
public static HlcTimestamp Parse(string value)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(value);
|
||||
|
||||
var match = ParseRegex.Match(value);
|
||||
if (!match.Success)
|
||||
{
|
||||
throw new FormatException(
|
||||
$"Invalid HLC timestamp format: '{value}'. Expected format: '{{physicalTime13}}-{{nodeId}}-{{counter6}}'");
|
||||
}
|
||||
|
||||
return new HlcTimestamp
|
||||
{
|
||||
PhysicalTime = long.Parse(match.Groups[1].Value, CultureInfo.InvariantCulture),
|
||||
NodeId = match.Groups[2].Value,
|
||||
LogicalCounter = int.Parse(match.Groups[3].Value, CultureInfo.InvariantCulture)
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Try to parse from sortable string format.
|
||||
/// </summary>
|
||||
/// <param name="value">String to parse</param>
|
||||
/// <param name="result">Parsed timestamp if successful</param>
|
||||
/// <returns>True if parsing succeeded</returns>
|
||||
public static bool TryParse(string? value, out HlcTimestamp result)
|
||||
{
|
||||
result = default;
|
||||
|
||||
if (string.IsNullOrWhiteSpace(value))
|
||||
return false;
|
||||
|
||||
var match = ParseRegex.Match(value);
|
||||
if (!match.Success)
|
||||
return false;
|
||||
|
||||
if (!long.TryParse(match.Groups[1].Value, CultureInfo.InvariantCulture, out var physicalTime))
|
||||
return false;
|
||||
|
||||
if (!int.TryParse(match.Groups[3].Value, CultureInfo.InvariantCulture, out var logicalCounter))
|
||||
return false;
|
||||
|
||||
result = new HlcTimestamp
|
||||
{
|
||||
PhysicalTime = physicalTime,
|
||||
NodeId = match.Groups[2].Value,
|
||||
LogicalCounter = logicalCounter
|
||||
};
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Compare for total ordering.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Ordering is:
|
||||
/// 1. Primary: Physical time (earlier times first)
|
||||
/// 2. Secondary: Logical counter (lower counters first)
|
||||
/// 3. Tertiary: Node ID (lexicographic, for stable tie-breaking)
|
||||
/// </remarks>
|
||||
public int CompareTo(HlcTimestamp other)
|
||||
{
|
||||
// Primary: physical time
|
||||
var physicalCompare = PhysicalTime.CompareTo(other.PhysicalTime);
|
||||
if (physicalCompare != 0) return physicalCompare;
|
||||
|
||||
// Secondary: logical counter
|
||||
var counterCompare = LogicalCounter.CompareTo(other.LogicalCounter);
|
||||
if (counterCompare != 0) return counterCompare;
|
||||
|
||||
// Tertiary: node ID (for stable tie-breaking)
|
||||
return string.Compare(NodeId, other.NodeId, StringComparison.Ordinal);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Returns true if this timestamp is causally before the other.
|
||||
/// </summary>
|
||||
public bool IsBefore(HlcTimestamp other) => CompareTo(other) < 0;
|
||||
|
||||
/// <summary>
|
||||
/// Returns true if this timestamp is causally after the other.
|
||||
/// </summary>
|
||||
public bool IsAfter(HlcTimestamp other) => CompareTo(other) > 0;
|
||||
|
||||
/// <summary>
|
||||
/// Returns true if this timestamp is causally concurrent with the other
|
||||
/// (same physical time and counter, different nodes).
|
||||
/// </summary>
|
||||
public bool IsConcurrent(HlcTimestamp other) =>
|
||||
PhysicalTime == other.PhysicalTime &&
|
||||
LogicalCounter == other.LogicalCounter &&
|
||||
!string.Equals(NodeId, other.NodeId, StringComparison.Ordinal);
|
||||
|
||||
/// <summary>
|
||||
/// Creates a new timestamp with incremented counter (same physical time and node).
|
||||
/// </summary>
|
||||
public HlcTimestamp Increment() => this with { LogicalCounter = LogicalCounter + 1 };
|
||||
|
||||
/// <summary>
|
||||
/// Creates a new timestamp with specified physical time and reset counter.
|
||||
/// </summary>
|
||||
public HlcTimestamp WithPhysicalTime(long physicalTime) =>
|
||||
this with { PhysicalTime = physicalTime, LogicalCounter = 0 };
|
||||
|
||||
/// <summary>
|
||||
/// Comparison operators for convenience.
|
||||
/// </summary>
|
||||
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;
|
||||
|
||||
/// <inheritdoc/>
|
||||
public override string ToString() => ToSortableString();
|
||||
}
|
||||
@@ -0,0 +1,175 @@
|
||||
// -----------------------------------------------------------------------------
|
||||
// HlcTimestampJsonConverter.cs
|
||||
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
|
||||
// Task: HLC-006 - Add HlcTimestampJsonConverter for System.Text.Json serialization
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
using System.Text.Json;
|
||||
using System.Text.Json.Serialization;
|
||||
|
||||
namespace StellaOps.HybridLogicalClock;
|
||||
|
||||
/// <summary>
|
||||
/// JSON converter for HlcTimestamp using the sortable string format.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Serializes HlcTimestamp to/from the sortable string format (e.g., "1704067200000-scheduler-east-1-000042").
|
||||
/// This format is both human-readable and lexicographically sortable.
|
||||
/// </remarks>
|
||||
public sealed class HlcTimestampJsonConverter : JsonConverter<HlcTimestamp>
|
||||
{
|
||||
/// <inheritdoc/>
|
||||
public override HlcTimestamp Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
|
||||
{
|
||||
if (reader.TokenType == JsonTokenType.Null)
|
||||
{
|
||||
throw new JsonException("Cannot convert null value to HlcTimestamp");
|
||||
}
|
||||
|
||||
if (reader.TokenType != JsonTokenType.String)
|
||||
{
|
||||
throw new JsonException($"Expected string but got {reader.TokenType}");
|
||||
}
|
||||
|
||||
var value = reader.GetString();
|
||||
if (string.IsNullOrWhiteSpace(value))
|
||||
{
|
||||
throw new JsonException("Cannot convert empty string to HlcTimestamp");
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
return HlcTimestamp.Parse(value);
|
||||
}
|
||||
catch (FormatException ex)
|
||||
{
|
||||
throw new JsonException($"Invalid HlcTimestamp format: {value}", ex);
|
||||
}
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public override void Write(Utf8JsonWriter writer, HlcTimestamp value, JsonSerializerOptions options)
|
||||
{
|
||||
writer.WriteStringValue(value.ToSortableString());
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// JSON converter for nullable HlcTimestamp.
|
||||
/// </summary>
|
||||
public sealed class NullableHlcTimestampJsonConverter : JsonConverter<HlcTimestamp?>
|
||||
{
|
||||
private readonly HlcTimestampJsonConverter _inner = new();
|
||||
|
||||
/// <inheritdoc/>
|
||||
public override HlcTimestamp? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
|
||||
{
|
||||
if (reader.TokenType == JsonTokenType.Null)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
return _inner.Read(ref reader, typeof(HlcTimestamp), options);
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public override void Write(Utf8JsonWriter writer, HlcTimestamp? value, JsonSerializerOptions options)
|
||||
{
|
||||
if (!value.HasValue)
|
||||
{
|
||||
writer.WriteNullValue();
|
||||
return;
|
||||
}
|
||||
|
||||
_inner.Write(writer, value.Value, options);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// JSON converter for HlcTimestamp using object format with individual properties.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Alternative converter that serializes HlcTimestamp as an object:
|
||||
/// <code>
|
||||
/// {
|
||||
/// "physicalTime": 1704067200000,
|
||||
/// "nodeId": "scheduler-east-1",
|
||||
/// "logicalCounter": 42
|
||||
/// }
|
||||
/// </code>
|
||||
/// Use this when you need to query individual fields in JSON storage.
|
||||
/// </remarks>
|
||||
public sealed class HlcTimestampObjectJsonConverter : JsonConverter<HlcTimestamp>
|
||||
{
|
||||
/// <inheritdoc/>
|
||||
public override HlcTimestamp Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
|
||||
{
|
||||
if (reader.TokenType != JsonTokenType.StartObject)
|
||||
{
|
||||
throw new JsonException($"Expected StartObject but got {reader.TokenType}");
|
||||
}
|
||||
|
||||
long? physicalTime = null;
|
||||
string? nodeId = null;
|
||||
int? logicalCounter = null;
|
||||
|
||||
while (reader.Read())
|
||||
{
|
||||
if (reader.TokenType == JsonTokenType.EndObject)
|
||||
{
|
||||
break;
|
||||
}
|
||||
|
||||
if (reader.TokenType != JsonTokenType.PropertyName)
|
||||
{
|
||||
throw new JsonException($"Expected PropertyName but got {reader.TokenType}");
|
||||
}
|
||||
|
||||
var propertyName = reader.GetString();
|
||||
reader.Read();
|
||||
|
||||
switch (propertyName)
|
||||
{
|
||||
case "physicalTime":
|
||||
case "PhysicalTime":
|
||||
physicalTime = reader.GetInt64();
|
||||
break;
|
||||
case "nodeId":
|
||||
case "NodeId":
|
||||
nodeId = reader.GetString();
|
||||
break;
|
||||
case "logicalCounter":
|
||||
case "LogicalCounter":
|
||||
logicalCounter = reader.GetInt32();
|
||||
break;
|
||||
default:
|
||||
reader.Skip();
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
if (!physicalTime.HasValue)
|
||||
throw new JsonException("Missing required property 'physicalTime'");
|
||||
if (string.IsNullOrEmpty(nodeId))
|
||||
throw new JsonException("Missing required property 'nodeId'");
|
||||
if (!logicalCounter.HasValue)
|
||||
throw new JsonException("Missing required property 'logicalCounter'");
|
||||
|
||||
return new HlcTimestamp
|
||||
{
|
||||
PhysicalTime = physicalTime.Value,
|
||||
NodeId = nodeId,
|
||||
LogicalCounter = logicalCounter.Value
|
||||
};
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public override void Write(Utf8JsonWriter writer, HlcTimestamp value, JsonSerializerOptions options)
|
||||
{
|
||||
writer.WriteStartObject();
|
||||
writer.WriteNumber("physicalTime", value.PhysicalTime);
|
||||
writer.WriteString("nodeId", value.NodeId);
|
||||
writer.WriteNumber("logicalCounter", value.LogicalCounter);
|
||||
writer.WriteEndObject();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,212 @@
|
||||
// -----------------------------------------------------------------------------
|
||||
// HlcTimestampTypeHandler.cs
|
||||
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
|
||||
// Task: HLC-007 - Add HlcTimestampTypeHandler for Npgsql/Dapper
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
using System.Data;
|
||||
using Npgsql;
|
||||
using NpgsqlTypes;
|
||||
|
||||
namespace StellaOps.HybridLogicalClock;
|
||||
|
||||
/// <summary>
|
||||
/// Npgsql type handler for HlcTimestamp stored as TEXT in sortable string format.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This handler allows HlcTimestamp to be used directly in Npgsql queries:
|
||||
/// <code>
|
||||
/// cmd.Parameters.AddWithValue("@hlc", hlcTimestamp);
|
||||
/// var hlc = reader.GetFieldValue<HlcTimestamp>(0);
|
||||
/// </code>
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Register with Npgsql using:
|
||||
/// <code>
|
||||
/// NpgsqlConnection.GlobalTypeMapper.AddTypeInfoResolverFactory(new HlcTimestampTypeHandlerResolverFactory());
|
||||
/// </code>
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class HlcTimestampNpgsqlExtensions
|
||||
{
|
||||
/// <summary>
|
||||
/// Adds an HlcTimestamp parameter to the command.
|
||||
/// </summary>
|
||||
/// <param name="cmd">The Npgsql command</param>
|
||||
/// <param name="parameterName">Parameter name (with or without @)</param>
|
||||
/// <param name="value">HLC timestamp value</param>
|
||||
/// <returns>The added parameter</returns>
|
||||
public static NpgsqlParameter AddHlcTimestamp(
|
||||
this NpgsqlCommand cmd,
|
||||
string parameterName,
|
||||
HlcTimestamp value)
|
||||
{
|
||||
var param = new NpgsqlParameter(parameterName, NpgsqlDbType.Text)
|
||||
{
|
||||
Value = value.ToSortableString()
|
||||
};
|
||||
cmd.Parameters.Add(param);
|
||||
return param;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Adds a nullable HlcTimestamp parameter to the command.
|
||||
/// </summary>
|
||||
/// <param name="cmd">The Npgsql command</param>
|
||||
/// <param name="parameterName">Parameter name (with or without @)</param>
|
||||
/// <param name="value">HLC timestamp value (nullable)</param>
|
||||
/// <returns>The added parameter</returns>
|
||||
public static NpgsqlParameter AddHlcTimestamp(
|
||||
this NpgsqlCommand cmd,
|
||||
string parameterName,
|
||||
HlcTimestamp? value)
|
||||
{
|
||||
var param = new NpgsqlParameter(parameterName, NpgsqlDbType.Text)
|
||||
{
|
||||
Value = value.HasValue ? value.Value.ToSortableString() : DBNull.Value
|
||||
};
|
||||
cmd.Parameters.Add(param);
|
||||
return param;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets an HlcTimestamp value from the reader.
|
||||
/// </summary>
|
||||
/// <param name="reader">The data reader</param>
|
||||
/// <param name="ordinal">Column ordinal</param>
|
||||
/// <returns>Parsed HLC timestamp</returns>
|
||||
public static HlcTimestamp GetHlcTimestamp(this NpgsqlDataReader reader, int ordinal)
|
||||
{
|
||||
var value = reader.GetString(ordinal);
|
||||
return HlcTimestamp.Parse(value);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets a nullable HlcTimestamp value from the reader.
|
||||
/// </summary>
|
||||
/// <param name="reader">The data reader</param>
|
||||
/// <param name="ordinal">Column ordinal</param>
|
||||
/// <returns>Parsed HLC timestamp or null</returns>
|
||||
public static HlcTimestamp? GetHlcTimestampOrNull(this NpgsqlDataReader reader, int ordinal)
|
||||
{
|
||||
if (reader.IsDBNull(ordinal))
|
||||
return null;
|
||||
|
||||
var value = reader.GetString(ordinal);
|
||||
return HlcTimestamp.Parse(value);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets an HlcTimestamp value from the reader by column name.
|
||||
/// </summary>
|
||||
/// <param name="reader">The data reader</param>
|
||||
/// <param name="columnName">Column name</param>
|
||||
/// <returns>Parsed HLC timestamp</returns>
|
||||
public static HlcTimestamp GetHlcTimestamp(this NpgsqlDataReader reader, string columnName)
|
||||
{
|
||||
var ordinal = reader.GetOrdinal(columnName);
|
||||
return reader.GetHlcTimestamp(ordinal);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets a nullable HlcTimestamp value from the reader by column name.
|
||||
/// </summary>
|
||||
/// <param name="reader">The data reader</param>
|
||||
/// <param name="columnName">Column name</param>
|
||||
/// <returns>Parsed HLC timestamp or null</returns>
|
||||
public static HlcTimestamp? GetHlcTimestampOrNull(this NpgsqlDataReader reader, string columnName)
|
||||
{
|
||||
var ordinal = reader.GetOrdinal(columnName);
|
||||
return reader.GetHlcTimestampOrNull(ordinal);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Dapper type handler for HlcTimestamp.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Register with Dapper using:
|
||||
/// <code>
|
||||
/// SqlMapper.AddTypeHandler(new HlcTimestampDapperHandler());
|
||||
/// </code>
|
||||
/// </remarks>
|
||||
public sealed class HlcTimestampDapperHandler : Dapper.SqlMapper.TypeHandler<HlcTimestamp>
|
||||
{
|
||||
/// <inheritdoc/>
|
||||
public override HlcTimestamp Parse(object value)
|
||||
{
|
||||
if (value is string str)
|
||||
{
|
||||
return HlcTimestamp.Parse(str);
|
||||
}
|
||||
|
||||
throw new DataException($"Cannot convert {value?.GetType().Name ?? "null"} to HlcTimestamp");
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public override void SetValue(IDbDataParameter parameter, HlcTimestamp value)
|
||||
{
|
||||
parameter.DbType = DbType.String;
|
||||
parameter.Value = value.ToSortableString();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Dapper type handler for nullable HlcTimestamp.
|
||||
/// </summary>
|
||||
public sealed class NullableHlcTimestampDapperHandler : Dapper.SqlMapper.TypeHandler<HlcTimestamp?>
|
||||
{
|
||||
/// <inheritdoc/>
|
||||
public override HlcTimestamp? Parse(object value)
|
||||
{
|
||||
if (value is null or DBNull)
|
||||
return null;
|
||||
|
||||
if (value is string str)
|
||||
{
|
||||
return HlcTimestamp.Parse(str);
|
||||
}
|
||||
|
||||
throw new DataException($"Cannot convert {value.GetType().Name} to HlcTimestamp?");
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public override void SetValue(IDbDataParameter parameter, HlcTimestamp? value)
|
||||
{
|
||||
parameter.DbType = DbType.String;
|
||||
parameter.Value = value.HasValue ? value.Value.ToSortableString() : DBNull.Value;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Extension methods for registering HLC type handlers.
|
||||
/// </summary>
|
||||
public static class HlcTypeHandlerRegistration
|
||||
{
|
||||
private static bool _dapperHandlersRegistered;
|
||||
private static readonly object _lock = new();
|
||||
|
||||
/// <summary>
|
||||
/// Registers Dapper type handlers for HlcTimestamp.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// This method is idempotent and can be called multiple times safely.
|
||||
/// </remarks>
|
||||
public static void RegisterDapperHandlers()
|
||||
{
|
||||
if (_dapperHandlersRegistered)
|
||||
return;
|
||||
|
||||
lock (_lock)
|
||||
{
|
||||
if (_dapperHandlersRegistered)
|
||||
return;
|
||||
|
||||
Dapper.SqlMapper.AddTypeHandler(new HlcTimestampDapperHandler());
|
||||
Dapper.SqlMapper.AddTypeHandler(new NullableHlcTimestampDapperHandler());
|
||||
|
||||
_dapperHandlersRegistered = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,293 @@
|
||||
// -----------------------------------------------------------------------------
|
||||
// HybridLogicalClock.cs
|
||||
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
|
||||
// Task: HLC-003 - Implement HybridLogicalClock class with Tick/Receive/Current
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
namespace StellaOps.HybridLogicalClock;
|
||||
|
||||
/// <summary>
|
||||
/// Implementation of Hybrid Logical Clock algorithm for deterministic,
|
||||
/// monotonic timestamp generation across distributed nodes.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// The HLC algorithm combines physical (wall-clock) time with a logical counter:
|
||||
/// - Physical time provides approximate real-time ordering
|
||||
/// - Logical counter ensures monotonicity when physical time doesn't advance
|
||||
/// - Node ID provides stable tie-breaking for concurrent events
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// On local event or send:
|
||||
/// <code>
|
||||
/// l' = l
|
||||
/// l = max(l, physical_clock())
|
||||
/// if l == l':
|
||||
/// c = c + 1
|
||||
/// else:
|
||||
/// c = 0
|
||||
/// return (l, node_id, c)
|
||||
/// </code>
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// On receive(m_l, m_c):
|
||||
/// <code>
|
||||
/// l' = l
|
||||
/// l = max(l', m_l, physical_clock())
|
||||
/// if l == l' == m_l:
|
||||
/// c = max(c, m_c) + 1
|
||||
/// elif l == l':
|
||||
/// c = c + 1
|
||||
/// elif l == m_l:
|
||||
/// c = m_c + 1
|
||||
/// else:
|
||||
/// c = 0
|
||||
/// return (l, node_id, c)
|
||||
/// </code>
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class HybridLogicalClock : IHybridLogicalClock
|
||||
{
|
||||
private readonly TimeProvider _timeProvider;
|
||||
private readonly string _nodeId;
|
||||
private readonly IHlcStateStore _stateStore;
|
||||
private readonly TimeSpan _maxClockSkew;
|
||||
private readonly ILogger<HybridLogicalClock> _logger;
|
||||
|
||||
private long _lastPhysicalTime;
|
||||
private int _logicalCounter;
|
||||
private readonly object _lock = new();
|
||||
|
||||
/// <inheritdoc/>
|
||||
public string NodeId => _nodeId;
|
||||
|
||||
/// <inheritdoc/>
|
||||
public HlcTimestamp Current
|
||||
{
|
||||
get
|
||||
{
|
||||
lock (_lock)
|
||||
{
|
||||
return new HlcTimestamp
|
||||
{
|
||||
PhysicalTime = _lastPhysicalTime,
|
||||
NodeId = _nodeId,
|
||||
LogicalCounter = _logicalCounter
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a new Hybrid Logical Clock instance.
|
||||
/// </summary>
|
||||
/// <param name="timeProvider">Time provider for wall-clock time</param>
|
||||
/// <param name="nodeId">Unique identifier for this node (e.g., "scheduler-east-1")</param>
|
||||
/// <param name="stateStore">Persistent storage for clock state</param>
|
||||
/// <param name="logger">Logger for diagnostics</param>
|
||||
/// <param name="maxClockSkew">Maximum allowed clock skew (default: 1 minute)</param>
|
||||
public HybridLogicalClock(
|
||||
TimeProvider timeProvider,
|
||||
string nodeId,
|
||||
IHlcStateStore stateStore,
|
||||
ILogger<HybridLogicalClock> logger,
|
||||
TimeSpan? maxClockSkew = null)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(timeProvider);
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
|
||||
ArgumentNullException.ThrowIfNull(stateStore);
|
||||
ArgumentNullException.ThrowIfNull(logger);
|
||||
|
||||
_timeProvider = timeProvider;
|
||||
_nodeId = nodeId;
|
||||
_stateStore = stateStore;
|
||||
_logger = logger;
|
||||
_maxClockSkew = maxClockSkew ?? TimeSpan.FromMinutes(1);
|
||||
|
||||
// Initialize to current physical time
|
||||
_lastPhysicalTime = _timeProvider.GetUtcNow().ToUnixTimeMilliseconds();
|
||||
_logicalCounter = 0;
|
||||
|
||||
_logger.LogInformation(
|
||||
"HLC initialized for node {NodeId} with max skew {MaxSkew}",
|
||||
_nodeId,
|
||||
_maxClockSkew);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Initialize clock from persisted state (call during startup).
|
||||
/// </summary>
|
||||
/// <param name="ct">Cancellation token</param>
|
||||
/// <returns>True if state was recovered, false if starting fresh</returns>
|
||||
public async Task<bool> InitializeFromStateAsync(CancellationToken ct = default)
|
||||
{
|
||||
var persistedState = await _stateStore.LoadAsync(_nodeId, ct);
|
||||
|
||||
if (persistedState.HasValue)
|
||||
{
|
||||
lock (_lock)
|
||||
{
|
||||
// Ensure we start at least at the persisted time
|
||||
var physicalNow = _timeProvider.GetUtcNow().ToUnixTimeMilliseconds();
|
||||
_lastPhysicalTime = Math.Max(physicalNow, persistedState.Value.PhysicalTime);
|
||||
|
||||
// If we're at the same physical time as persisted, increment counter
|
||||
if (_lastPhysicalTime == persistedState.Value.PhysicalTime)
|
||||
{
|
||||
_logicalCounter = persistedState.Value.LogicalCounter + 1;
|
||||
}
|
||||
else
|
||||
{
|
||||
_logicalCounter = 0;
|
||||
}
|
||||
}
|
||||
|
||||
_logger.LogInformation(
|
||||
"HLC for node {NodeId} recovered from persisted state: {Timestamp}",
|
||||
_nodeId,
|
||||
persistedState.Value);
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
_logger.LogInformation(
|
||||
"HLC for node {NodeId} starting fresh (no persisted state)",
|
||||
_nodeId);
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public HlcTimestamp Tick()
|
||||
{
|
||||
HlcTimestamp timestamp;
|
||||
|
||||
lock (_lock)
|
||||
{
|
||||
var physicalNow = _timeProvider.GetUtcNow().ToUnixTimeMilliseconds();
|
||||
|
||||
if (physicalNow > _lastPhysicalTime)
|
||||
{
|
||||
// Physical time advanced - reset counter
|
||||
_lastPhysicalTime = physicalNow;
|
||||
_logicalCounter = 0;
|
||||
}
|
||||
else
|
||||
{
|
||||
// Physical time hasn't advanced - increment counter
|
||||
_logicalCounter++;
|
||||
|
||||
// Check for counter overflow (unlikely but handle it)
|
||||
if (_logicalCounter < 0)
|
||||
{
|
||||
_logger.LogWarning(
|
||||
"HLC counter overflow for node {NodeId}, forcing time advance",
|
||||
_nodeId);
|
||||
|
||||
// Force time advance to next millisecond
|
||||
_lastPhysicalTime++;
|
||||
_logicalCounter = 0;
|
||||
}
|
||||
}
|
||||
|
||||
timestamp = new HlcTimestamp
|
||||
{
|
||||
PhysicalTime = _lastPhysicalTime,
|
||||
NodeId = _nodeId,
|
||||
LogicalCounter = _logicalCounter
|
||||
};
|
||||
}
|
||||
|
||||
// Persist state asynchronously (fire-and-forget with error logging)
|
||||
_ = PersistStateAsync(timestamp);
|
||||
|
||||
return timestamp;
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public HlcTimestamp Receive(HlcTimestamp remote)
|
||||
{
|
||||
HlcTimestamp timestamp;
|
||||
|
||||
lock (_lock)
|
||||
{
|
||||
var physicalNow = _timeProvider.GetUtcNow().ToUnixTimeMilliseconds();
|
||||
|
||||
// Validate clock skew
|
||||
var skew = TimeSpan.FromMilliseconds(Math.Abs(remote.PhysicalTime - physicalNow));
|
||||
if (skew > _maxClockSkew)
|
||||
{
|
||||
_logger.LogError(
|
||||
"Clock skew of {Skew} from node {RemoteNode} exceeds threshold {MaxSkew}",
|
||||
skew,
|
||||
remote.NodeId,
|
||||
_maxClockSkew);
|
||||
|
||||
throw new HlcClockSkewException(skew, _maxClockSkew);
|
||||
}
|
||||
|
||||
// Find maximum physical time
|
||||
var maxPhysical = Math.Max(Math.Max(_lastPhysicalTime, remote.PhysicalTime), physicalNow);
|
||||
|
||||
// Apply HLC receive algorithm
|
||||
if (maxPhysical == _lastPhysicalTime && maxPhysical == remote.PhysicalTime)
|
||||
{
|
||||
// All three equal - take max counter and increment
|
||||
_logicalCounter = Math.Max(_logicalCounter, remote.LogicalCounter) + 1;
|
||||
}
|
||||
else if (maxPhysical == _lastPhysicalTime)
|
||||
{
|
||||
// Our time is max - just increment our counter
|
||||
_logicalCounter++;
|
||||
}
|
||||
else if (maxPhysical == remote.PhysicalTime)
|
||||
{
|
||||
// Remote time is max - take their counter and increment
|
||||
_logicalCounter = remote.LogicalCounter + 1;
|
||||
}
|
||||
else
|
||||
{
|
||||
// Physical clock is max - reset counter
|
||||
_logicalCounter = 0;
|
||||
}
|
||||
|
||||
_lastPhysicalTime = maxPhysical;
|
||||
|
||||
timestamp = new HlcTimestamp
|
||||
{
|
||||
PhysicalTime = _lastPhysicalTime,
|
||||
NodeId = _nodeId,
|
||||
LogicalCounter = _logicalCounter
|
||||
};
|
||||
}
|
||||
|
||||
// Persist state asynchronously
|
||||
_ = PersistStateAsync(timestamp);
|
||||
|
||||
_logger.LogDebug(
|
||||
"HLC receive from {RemoteNode}: {RemoteTimestamp} -> {LocalTimestamp}",
|
||||
remote.NodeId,
|
||||
remote,
|
||||
timestamp);
|
||||
|
||||
return timestamp;
|
||||
}
|
||||
|
||||
private async Task PersistStateAsync(HlcTimestamp timestamp)
|
||||
{
|
||||
try
|
||||
{
|
||||
await _stateStore.SaveAsync(timestamp);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
_logger.LogWarning(
|
||||
ex,
|
||||
"Failed to persist HLC state for node {NodeId}: {Timestamp}",
|
||||
_nodeId,
|
||||
timestamp);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,82 @@
|
||||
// -----------------------------------------------------------------------------
|
||||
// IHybridLogicalClock.cs
|
||||
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
|
||||
// Task: HLC-003 - Define HLC interface
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
namespace StellaOps.HybridLogicalClock;
|
||||
|
||||
/// <summary>
|
||||
/// Hybrid Logical Clock for monotonic timestamp generation across distributed nodes.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// HLC combines physical (wall-clock) time with logical counters to provide:
|
||||
/// - Monotonic timestamps even under clock skew
|
||||
/// - Causal ordering guarantees across distributed nodes
|
||||
/// - Deterministic tie-breaking for concurrent events
|
||||
/// </remarks>
|
||||
public interface IHybridLogicalClock
|
||||
{
|
||||
/// <summary>
|
||||
/// Generate next timestamp for local event.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// This should be called for every event that needs ordering:
|
||||
/// - Job enqueue
|
||||
/// - State transitions
|
||||
/// - Audit log entries
|
||||
/// </remarks>
|
||||
/// <returns>New monotonically increasing HLC timestamp</returns>
|
||||
HlcTimestamp Tick();
|
||||
|
||||
/// <summary>
|
||||
/// Update clock on receiving remote timestamp, return merged result.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Called when receiving a message from another node to ensure
|
||||
/// causal ordering is maintained across the distributed system.
|
||||
/// </remarks>
|
||||
/// <param name="remote">Timestamp from remote node</param>
|
||||
/// <returns>New timestamp that is greater than both local clock and remote timestamp</returns>
|
||||
/// <exception cref="HlcClockSkewException">If clock skew exceeds configured threshold</exception>
|
||||
HlcTimestamp Receive(HlcTimestamp remote);
|
||||
|
||||
/// <summary>
|
||||
/// Current clock state (for persistence/recovery).
|
||||
/// </summary>
|
||||
HlcTimestamp Current { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Node identifier for this clock instance.
|
||||
/// </summary>
|
||||
string NodeId { get; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Persistent storage for HLC state (survives restarts).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Implementations should ensure atomic updates to prevent state loss
|
||||
/// during concurrent access or node failures.
|
||||
/// </remarks>
|
||||
public interface IHlcStateStore
|
||||
{
|
||||
/// <summary>
|
||||
/// Load last persisted HLC state for node.
|
||||
/// </summary>
|
||||
/// <param name="nodeId">Node identifier to load state for</param>
|
||||
/// <param name="ct">Cancellation token</param>
|
||||
/// <returns>Last persisted timestamp, or null if no state exists</returns>
|
||||
Task<HlcTimestamp?> LoadAsync(string nodeId, CancellationToken ct = default);
|
||||
|
||||
/// <summary>
|
||||
/// Persist HLC state.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Called after each tick to ensure state survives restarts.
|
||||
/// Implementations may batch or debounce writes for performance.
|
||||
/// </remarks>
|
||||
/// <param name="timestamp">Current timestamp to persist</param>
|
||||
/// <param name="ct">Cancellation token</param>
|
||||
Task SaveAsync(HlcTimestamp timestamp, CancellationToken ct = default);
|
||||
}
|
||||
@@ -0,0 +1,61 @@
|
||||
// -----------------------------------------------------------------------------
|
||||
// InMemoryHlcStateStore.cs
|
||||
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
|
||||
// Task: HLC-004 - Implement IHlcStateStore interface and InMemoryHlcStateStore
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
using System.Collections.Concurrent;
|
||||
|
||||
namespace StellaOps.HybridLogicalClock;
|
||||
|
||||
/// <summary>
|
||||
/// In-memory implementation of HLC state store for testing and development.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// This implementation does not survive process restarts. Use PostgresHlcStateStore
|
||||
/// for production deployments requiring persistence.
|
||||
/// </remarks>
|
||||
public sealed class InMemoryHlcStateStore : IHlcStateStore
|
||||
{
|
||||
private readonly ConcurrentDictionary<string, HlcTimestamp> _states = new(StringComparer.Ordinal);
|
||||
|
||||
/// <inheritdoc/>
|
||||
public Task<HlcTimestamp?> LoadAsync(string nodeId, CancellationToken ct = default)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
|
||||
ct.ThrowIfCancellationRequested();
|
||||
|
||||
return Task.FromResult(
|
||||
_states.TryGetValue(nodeId, out var timestamp)
|
||||
? timestamp
|
||||
: (HlcTimestamp?)null);
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public Task SaveAsync(HlcTimestamp timestamp, CancellationToken ct = default)
|
||||
{
|
||||
ct.ThrowIfCancellationRequested();
|
||||
|
||||
_states.AddOrUpdate(
|
||||
timestamp.NodeId,
|
||||
timestamp,
|
||||
(_, existing) =>
|
||||
{
|
||||
// Only update if new timestamp is greater (maintain monotonicity)
|
||||
return timestamp > existing ? timestamp : existing;
|
||||
});
|
||||
|
||||
return Task.CompletedTask;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets all stored states (for testing/debugging).
|
||||
/// </summary>
|
||||
public IReadOnlyDictionary<string, HlcTimestamp> GetAllStates() =>
|
||||
new Dictionary<string, HlcTimestamp>(_states);
|
||||
|
||||
/// <summary>
|
||||
/// Clears all stored states (for testing).
|
||||
/// </summary>
|
||||
public void Clear() => _states.Clear();
|
||||
}
|
||||
@@ -0,0 +1,228 @@
|
||||
// -----------------------------------------------------------------------------
|
||||
// PostgresHlcStateStore.cs
|
||||
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
|
||||
// Task: HLC-005 - Implement PostgresHlcStateStore with atomic update semantics
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
using Microsoft.Extensions.Logging;
|
||||
using Npgsql;
|
||||
|
||||
namespace StellaOps.HybridLogicalClock;
|
||||
|
||||
/// <summary>
|
||||
/// PostgreSQL implementation of HLC state store for production deployments.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Uses atomic upsert with conditional update to ensure:
|
||||
/// - State is never rolled back (only forward updates accepted)
|
||||
/// - Concurrent saves from same node are handled correctly
|
||||
/// - Node restarts resume from persisted state
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Required schema:
|
||||
/// <code>
|
||||
/// CREATE TABLE scheduler.hlc_state (
|
||||
/// node_id TEXT PRIMARY KEY,
|
||||
/// physical_time BIGINT NOT NULL,
|
||||
/// logical_counter INT NOT NULL,
|
||||
/// updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
/// );
|
||||
/// </code>
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class PostgresHlcStateStore : IHlcStateStore
|
||||
{
|
||||
private readonly NpgsqlDataSource _dataSource;
|
||||
private readonly ILogger<PostgresHlcStateStore> _logger;
|
||||
private readonly string _schema;
|
||||
private readonly string _tableName;
|
||||
|
||||
/// <summary>
|
||||
/// Creates a new PostgreSQL HLC state store.
|
||||
/// </summary>
|
||||
/// <param name="dataSource">Npgsql data source</param>
|
||||
/// <param name="logger">Logger</param>
|
||||
/// <param name="schema">Database schema (default: "scheduler")</param>
|
||||
/// <param name="tableName">Table name (default: "hlc_state")</param>
|
||||
public PostgresHlcStateStore(
|
||||
NpgsqlDataSource dataSource,
|
||||
ILogger<PostgresHlcStateStore> logger,
|
||||
string schema = "scheduler",
|
||||
string tableName = "hlc_state")
|
||||
{
|
||||
_dataSource = dataSource ?? throw new ArgumentNullException(nameof(dataSource));
|
||||
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
|
||||
_schema = schema;
|
||||
_tableName = tableName;
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public async Task<HlcTimestamp?> LoadAsync(string nodeId, CancellationToken ct = default)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
|
||||
|
||||
var sql = $"""
|
||||
SELECT physical_time, logical_counter
|
||||
FROM {_schema}.{_tableName}
|
||||
WHERE node_id = @node_id
|
||||
""";
|
||||
|
||||
await using var connection = await _dataSource.OpenConnectionAsync(ct);
|
||||
await using var cmd = new NpgsqlCommand(sql, connection);
|
||||
cmd.Parameters.AddWithValue("node_id", nodeId);
|
||||
|
||||
await using var reader = await cmd.ExecuteReaderAsync(ct);
|
||||
|
||||
if (!await reader.ReadAsync(ct))
|
||||
{
|
||||
_logger.LogDebug("No HLC state found for node {NodeId}", nodeId);
|
||||
return null;
|
||||
}
|
||||
|
||||
var physicalTime = reader.GetInt64(0);
|
||||
var logicalCounter = reader.GetInt32(1);
|
||||
|
||||
var timestamp = new HlcTimestamp
|
||||
{
|
||||
PhysicalTime = physicalTime,
|
||||
NodeId = nodeId,
|
||||
LogicalCounter = logicalCounter
|
||||
};
|
||||
|
||||
_logger.LogDebug("Loaded HLC state for node {NodeId}: {Timestamp}", nodeId, timestamp);
|
||||
|
||||
return timestamp;
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public async Task SaveAsync(HlcTimestamp timestamp, CancellationToken ct = default)
|
||||
{
|
||||
// Atomic upsert with conditional update (only update if new state is greater)
|
||||
var sql = $"""
|
||||
INSERT INTO {_schema}.{_tableName} (node_id, physical_time, logical_counter, updated_at)
|
||||
VALUES (@node_id, @physical_time, @logical_counter, NOW())
|
||||
ON CONFLICT (node_id) DO UPDATE SET
|
||||
physical_time = EXCLUDED.physical_time,
|
||||
logical_counter = EXCLUDED.logical_counter,
|
||||
updated_at = NOW()
|
||||
WHERE
|
||||
-- Only update if new timestamp is greater (maintains monotonicity)
|
||||
EXCLUDED.physical_time > {_schema}.{_tableName}.physical_time
|
||||
OR (
|
||||
EXCLUDED.physical_time = {_schema}.{_tableName}.physical_time
|
||||
AND EXCLUDED.logical_counter > {_schema}.{_tableName}.logical_counter
|
||||
)
|
||||
""";
|
||||
|
||||
await using var connection = await _dataSource.OpenConnectionAsync(ct);
|
||||
await using var cmd = new NpgsqlCommand(sql, connection);
|
||||
cmd.Parameters.AddWithValue("node_id", timestamp.NodeId);
|
||||
cmd.Parameters.AddWithValue("physical_time", timestamp.PhysicalTime);
|
||||
cmd.Parameters.AddWithValue("logical_counter", timestamp.LogicalCounter);
|
||||
|
||||
var rowsAffected = await cmd.ExecuteNonQueryAsync(ct);
|
||||
|
||||
if (rowsAffected > 0)
|
||||
{
|
||||
_logger.LogDebug("Saved HLC state for node {NodeId}: {Timestamp}", timestamp.NodeId, timestamp);
|
||||
}
|
||||
else
|
||||
{
|
||||
_logger.LogDebug(
|
||||
"HLC state not updated for node {NodeId}: {Timestamp} (existing state is newer)",
|
||||
timestamp.NodeId,
|
||||
timestamp);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Ensures the HLC state table exists in the database.
|
||||
/// </summary>
|
||||
/// <param name="ct">Cancellation token</param>
|
||||
public async Task EnsureTableExistsAsync(CancellationToken ct = default)
|
||||
{
|
||||
var sql = $"""
|
||||
CREATE SCHEMA IF NOT EXISTS {_schema};
|
||||
|
||||
CREATE TABLE IF NOT EXISTS {_schema}.{_tableName} (
|
||||
node_id TEXT PRIMARY KEY,
|
||||
physical_time BIGINT NOT NULL,
|
||||
logical_counter INT NOT NULL,
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_{_tableName}_updated
|
||||
ON {_schema}.{_tableName}(updated_at DESC);
|
||||
""";
|
||||
|
||||
await using var connection = await _dataSource.OpenConnectionAsync(ct);
|
||||
await using var cmd = new NpgsqlCommand(sql, connection);
|
||||
await cmd.ExecuteNonQueryAsync(ct);
|
||||
|
||||
_logger.LogInformation("Ensured HLC state table exists: {Schema}.{Table}", _schema, _tableName);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets all stored states (for monitoring/debugging).
|
||||
/// </summary>
|
||||
/// <param name="ct">Cancellation token</param>
|
||||
/// <returns>Dictionary of node IDs to their HLC states</returns>
|
||||
public async Task<IReadOnlyDictionary<string, HlcTimestamp>> GetAllStatesAsync(CancellationToken ct = default)
|
||||
{
|
||||
var sql = $"""
|
||||
SELECT node_id, physical_time, logical_counter
|
||||
FROM {_schema}.{_tableName}
|
||||
ORDER BY updated_at DESC
|
||||
""";
|
||||
|
||||
await using var connection = await _dataSource.OpenConnectionAsync(ct);
|
||||
await using var cmd = new NpgsqlCommand(sql, connection);
|
||||
|
||||
var results = new Dictionary<string, HlcTimestamp>(StringComparer.Ordinal);
|
||||
|
||||
await using var reader = await cmd.ExecuteReaderAsync(ct);
|
||||
while (await reader.ReadAsync(ct))
|
||||
{
|
||||
var nodeId = reader.GetString(0);
|
||||
results[nodeId] = new HlcTimestamp
|
||||
{
|
||||
NodeId = nodeId,
|
||||
PhysicalTime = reader.GetInt64(1),
|
||||
LogicalCounter = reader.GetInt32(2)
|
||||
};
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Deletes stale HLC states for nodes that haven't updated in the specified duration.
|
||||
/// </summary>
|
||||
/// <param name="staleDuration">Duration after which a state is considered stale</param>
|
||||
/// <param name="ct">Cancellation token</param>
|
||||
/// <returns>Number of deleted states</returns>
|
||||
public async Task<int> CleanupStaleStatesAsync(TimeSpan staleDuration, CancellationToken ct = default)
|
||||
{
|
||||
var sql = $"""
|
||||
DELETE FROM {_schema}.{_tableName}
|
||||
WHERE updated_at < NOW() - @stale_interval
|
||||
""";
|
||||
|
||||
await using var connection = await _dataSource.OpenConnectionAsync(ct);
|
||||
await using var cmd = new NpgsqlCommand(sql, connection);
|
||||
cmd.Parameters.AddWithValue("stale_interval", staleDuration);
|
||||
|
||||
var rowsDeleted = await cmd.ExecuteNonQueryAsync(ct);
|
||||
|
||||
if (rowsDeleted > 0)
|
||||
{
|
||||
_logger.LogInformation(
|
||||
"Cleaned up {Count} stale HLC states (older than {StaleDuration})",
|
||||
rowsDeleted,
|
||||
staleDuration);
|
||||
}
|
||||
|
||||
return rowsDeleted;
|
||||
}
|
||||
}
|
||||
367
src/__Libraries/StellaOps.HybridLogicalClock/README.md
Normal file
367
src/__Libraries/StellaOps.HybridLogicalClock/README.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# StellaOps.HybridLogicalClock
|
||||
|
||||
A Hybrid Logical Clock (HLC) library for deterministic, monotonic job ordering across distributed nodes. HLC combines physical (wall-clock) time with logical counters to provide causally-ordered timestamps even under clock skew.
|
||||
|
||||
## Overview
|
||||
|
||||
### Problem Statement
|
||||
|
||||
Distributed systems face challenges with event ordering:
|
||||
- Wall-clock timestamps are susceptible to clock skew between nodes
|
||||
- Logical clocks alone don't provide real-time context
|
||||
- Concurrent events from different nodes need deterministic tie-breaking
|
||||
|
||||
### Solution
|
||||
|
||||
HLC addresses these by combining:
|
||||
- **Physical time** (Unix milliseconds UTC) for real-time context
|
||||
- **Logical counter** for events at the same millisecond
|
||||
- **Node ID** for deterministic tie-breaking across nodes
|
||||
|
||||
## Installation
|
||||
|
||||
Reference the project in your `.csproj`:
|
||||
|
||||
```xml
|
||||
<ProjectReference Include="..\__Libraries\StellaOps.HybridLogicalClock\StellaOps.HybridLogicalClock.csproj" />
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```csharp
|
||||
using StellaOps.HybridLogicalClock;
|
||||
|
||||
// Create a clock instance
|
||||
var clock = new HybridLogicalClock(
|
||||
TimeProvider.System,
|
||||
nodeId: "scheduler-east-1",
|
||||
stateStore: new InMemoryHlcStateStore(),
|
||||
logger: logger);
|
||||
|
||||
// Generate timestamps for local events
|
||||
var ts1 = clock.Tick(); // e.g., 1704067200000-scheduler-east-1-000000
|
||||
var ts2 = clock.Tick(); // e.g., 1704067200000-scheduler-east-1-000001
|
||||
|
||||
// Timestamps are always monotonically increasing
|
||||
Debug.Assert(ts2 > ts1);
|
||||
|
||||
// When receiving a message from another node
|
||||
var remoteTs = HlcTimestamp.Parse("1704067200100-scheduler-west-1-000005");
|
||||
var mergedTs = clock.Receive(remoteTs); // Merges clocks, returns new timestamp > both
|
||||
```
|
||||
|
||||
### Dependency Injection
|
||||
|
||||
```csharp
|
||||
// Program.cs or Startup.cs
|
||||
|
||||
// Option 1: In-memory state (development/testing)
|
||||
services.AddHybridLogicalClock(
|
||||
nodeId: Environment.MachineName,
|
||||
maxClockSkew: TimeSpan.FromMinutes(1));
|
||||
|
||||
// Option 2: PostgreSQL persistence (production)
|
||||
services.AddHybridLogicalClock<PostgresHlcStateStore>(
|
||||
nodeId: Environment.MachineName,
|
||||
maxClockSkew: TimeSpan.FromMinutes(1));
|
||||
|
||||
// Option 3: Custom state store factory
|
||||
services.AddHybridLogicalClock(
|
||||
nodeId: Environment.MachineName,
|
||||
stateStoreFactory: sp => new PostgresHlcStateStore(
|
||||
sp.GetRequiredService<NpgsqlDataSource>(),
|
||||
sp.GetRequiredService<ILogger<PostgresHlcStateStore>>()),
|
||||
maxClockSkew: TimeSpan.FromMinutes(1));
|
||||
```
|
||||
|
||||
Then inject the clock:
|
||||
|
||||
```csharp
|
||||
public class JobScheduler(IHybridLogicalClock clock)
|
||||
{
|
||||
public void EnqueueJob(Job job)
|
||||
{
|
||||
job.EnqueuedAt = clock.Tick();
|
||||
// Jobs are now globally ordered across all scheduler nodes
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Core Types
|
||||
|
||||
### HlcTimestamp
|
||||
|
||||
A readonly record struct representing an HLC timestamp:
|
||||
|
||||
```csharp
|
||||
public readonly record struct HlcTimestamp : IComparable<HlcTimestamp>
|
||||
{
|
||||
public required long PhysicalTime { get; init; } // Unix milliseconds UTC
|
||||
public required string NodeId { get; init; } // e.g., "scheduler-east-1"
|
||||
public required int LogicalCounter { get; init; } // Events at same millisecond
|
||||
}
|
||||
```
|
||||
|
||||
**Key Methods:**
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `ToSortableString()` | Returns `"1704067200000-scheduler-east-1-000042"` |
|
||||
| `Parse(string)` | Parses from sortable string format |
|
||||
| `TryParse(string, out HlcTimestamp)` | Safe parsing without exceptions |
|
||||
| `ToDateTimeOffset()` | Converts physical time to DateTimeOffset |
|
||||
| `CompareTo(HlcTimestamp)` | Total ordering comparison |
|
||||
| `IsBefore(HlcTimestamp)` | Returns true if causally before |
|
||||
| `IsAfter(HlcTimestamp)` | Returns true if causally after |
|
||||
| `IsConcurrent(HlcTimestamp)` | True if same time/counter, different nodes |
|
||||
|
||||
**Comparison Operators:**
|
||||
|
||||
```csharp
|
||||
if (ts1 < ts2) { /* ts1 happened before ts2 */ }
|
||||
if (ts1 > ts2) { /* ts1 happened after ts2 */ }
|
||||
if (ts1 <= ts2) { /* ts1 happened at or before ts2 */ }
|
||||
if (ts1 >= ts2) { /* ts1 happened at or after ts2 */ }
|
||||
```
|
||||
|
||||
### IHybridLogicalClock
|
||||
|
||||
The main clock interface:
|
||||
|
||||
```csharp
|
||||
public interface IHybridLogicalClock
|
||||
{
|
||||
HlcTimestamp Tick(); // Generate timestamp for local event
|
||||
HlcTimestamp Receive(HlcTimestamp remote); // Merge with remote timestamp
|
||||
HlcTimestamp Current { get; } // Current clock state
|
||||
string NodeId { get; } // This node's identifier
|
||||
}
|
||||
```
|
||||
|
||||
### IHlcStateStore
|
||||
|
||||
Persistence interface for clock state:
|
||||
|
||||
```csharp
|
||||
public interface IHlcStateStore
|
||||
{
|
||||
Task<HlcTimestamp?> LoadAsync(string nodeId, CancellationToken ct = default);
|
||||
Task SaveAsync(HlcTimestamp timestamp, CancellationToken ct = default);
|
||||
}
|
||||
```
|
||||
|
||||
**Implementations:**
|
||||
- `InMemoryHlcStateStore` - For development and testing
|
||||
- `PostgresHlcStateStore` - For production with durable persistence
|
||||
|
||||
## Persistence
|
||||
|
||||
### PostgreSQL Schema
|
||||
|
||||
```sql
|
||||
CREATE TABLE scheduler.hlc_state (
|
||||
node_id TEXT PRIMARY KEY,
|
||||
physical_time BIGINT NOT NULL,
|
||||
logical_counter INT NOT NULL,
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_hlc_state_updated ON scheduler.hlc_state(updated_at DESC);
|
||||
```
|
||||
|
||||
### PostgresHlcStateStore
|
||||
|
||||
Uses atomic upsert with conditional update to maintain monotonicity:
|
||||
|
||||
```csharp
|
||||
var stateStore = new PostgresHlcStateStore(
|
||||
dataSource,
|
||||
logger,
|
||||
schemaName: "scheduler", // default
|
||||
tableName: "hlc_state" // default
|
||||
);
|
||||
```
|
||||
|
||||
## Serialization
|
||||
|
||||
### JSON (System.Text.Json)
|
||||
|
||||
Two converters are provided:
|
||||
|
||||
1. **String format** (default) - Compact, sortable:
|
||||
```json
|
||||
"1704067200000-scheduler-east-1-000042"
|
||||
```
|
||||
|
||||
2. **Object format** - Explicit properties:
|
||||
```json
|
||||
{
|
||||
"physicalTime": 1704067200000,
|
||||
"nodeId": "scheduler-east-1",
|
||||
"logicalCounter": 42
|
||||
}
|
||||
```
|
||||
|
||||
Register converters:
|
||||
|
||||
```csharp
|
||||
var options = new JsonSerializerOptions();
|
||||
options.Converters.Add(new HlcTimestampJsonConverter()); // String format
|
||||
// or
|
||||
options.Converters.Add(new HlcTimestampObjectJsonConverter()); // Object format
|
||||
```
|
||||
|
||||
### Database (Npgsql/Dapper)
|
||||
|
||||
Extension methods for reading/writing HLC timestamps:
|
||||
|
||||
```csharp
|
||||
// NpgsqlCommand extension
|
||||
await using var cmd = dataSource.CreateCommand();
|
||||
cmd.CommandText = "INSERT INTO events (timestamp) VALUES (@ts)";
|
||||
cmd.AddHlcTimestamp("ts", timestamp);
|
||||
await cmd.ExecuteNonQueryAsync();
|
||||
|
||||
// NpgsqlDataReader extension
|
||||
await using var reader = await cmd.ExecuteReaderAsync();
|
||||
var ts = reader.GetHlcTimestamp("timestamp");
|
||||
var nullableTs = reader.GetHlcTimestampOrNull("timestamp");
|
||||
```
|
||||
|
||||
Dapper type handlers:
|
||||
|
||||
```csharp
|
||||
// Register handlers at startup
|
||||
HlcTypeHandlerRegistration.Register(services);
|
||||
|
||||
// Then use normally with Dapper
|
||||
var results = await connection.QueryAsync<MyEntity>(
|
||||
"SELECT * FROM events WHERE timestamp > @since",
|
||||
new { since = sinceTimestamp });
|
||||
```
|
||||
|
||||
## Clock Skew Handling
|
||||
|
||||
The clock detects and rejects excessive clock skew:
|
||||
|
||||
```csharp
|
||||
var clock = new HybridLogicalClock(
|
||||
timeProvider,
|
||||
nodeId,
|
||||
stateStore,
|
||||
logger,
|
||||
maxClockSkew: TimeSpan.FromMinutes(1)); // Default: 1 minute
|
||||
|
||||
try
|
||||
{
|
||||
var merged = clock.Receive(remoteTimestamp);
|
||||
}
|
||||
catch (HlcClockSkewException ex)
|
||||
{
|
||||
// Remote clock differs by more than maxClockSkew
|
||||
logger.LogWarning(
|
||||
"Clock skew detected: {Actual} exceeds threshold {Max}",
|
||||
ex.ActualSkew, ex.MaxAllowedSkew);
|
||||
}
|
||||
```
|
||||
|
||||
## Recovery from Restart
|
||||
|
||||
After a node restart, initialize the clock from persisted state:
|
||||
|
||||
```csharp
|
||||
var clock = new HybridLogicalClock(timeProvider, nodeId, stateStore, logger);
|
||||
|
||||
// Load last persisted state
|
||||
bool recovered = await clock.InitializeFromStateAsync();
|
||||
if (recovered)
|
||||
{
|
||||
logger.LogInformation("Clock recovered from state: {Current}", clock.Current);
|
||||
}
|
||||
|
||||
// First tick after restart is guaranteed > last persisted tick
|
||||
var ts = clock.Tick();
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### FakeTimeProvider
|
||||
|
||||
For deterministic testing, use a fake time provider:
|
||||
|
||||
```csharp
|
||||
public class FakeTimeProvider : TimeProvider
|
||||
{
|
||||
private DateTimeOffset _now = DateTimeOffset.UtcNow;
|
||||
|
||||
public override DateTimeOffset GetUtcNow() => _now;
|
||||
|
||||
public void SetUtcNow(DateTimeOffset value) => _now = value;
|
||||
public void Advance(TimeSpan duration) => _now = _now.Add(duration);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Tick_Advances_Counter()
|
||||
{
|
||||
var timeProvider = new FakeTimeProvider();
|
||||
var clock = new HybridLogicalClock(timeProvider, "test", new InMemoryHlcStateStore(), logger);
|
||||
|
||||
var ts1 = clock.Tick();
|
||||
var ts2 = clock.Tick();
|
||||
|
||||
Assert.Equal(0, ts1.LogicalCounter);
|
||||
Assert.Equal(1, ts2.LogicalCounter);
|
||||
}
|
||||
```
|
||||
|
||||
## Algorithm
|
||||
|
||||
### On Local Event (Tick)
|
||||
|
||||
```
|
||||
l' = l
|
||||
l = max(l, physical_clock())
|
||||
if l == l':
|
||||
c = c + 1
|
||||
else:
|
||||
c = 0
|
||||
return (l, node_id, c)
|
||||
```
|
||||
|
||||
### On Receive
|
||||
|
||||
```
|
||||
l' = l
|
||||
l = max(l', m_l, physical_clock())
|
||||
if l == l' == m_l:
|
||||
c = max(c, m_c) + 1
|
||||
elif l == l':
|
||||
c = c + 1
|
||||
elif l == m_l:
|
||||
c = m_c + 1
|
||||
else:
|
||||
c = 0
|
||||
return (l, node_id, c)
|
||||
```
|
||||
|
||||
## Performance
|
||||
|
||||
Benchmarks on typical hardware:
|
||||
|
||||
| Operation | Throughput |
|
||||
|-----------|------------|
|
||||
| Tick (single-thread) | > 100,000/sec |
|
||||
| Tick (multi-thread) | > 50,000/sec |
|
||||
| Receive | > 50,000/sec |
|
||||
| Parse | > 500,000/sec |
|
||||
| ToSortableString | > 500,000/sec |
|
||||
| CompareTo | > 10,000,000/sec |
|
||||
|
||||
Memory: `HlcTimestamp` is a value type (struct) with minimal allocation.
|
||||
|
||||
## References
|
||||
|
||||
- [Logical Physical Clocks and Consistent Snapshots in Globally Distributed Databases](https://cse.buffalo.edu/tech-reports/2014-04.pdf) - Kulkarni et al.
|
||||
- [Time, Clocks, and the Ordering of Events in a Distributed System](https://lamport.azurewebsites.net/pubs/time-clocks.pdf) - Lamport
|
||||
@@ -0,0 +1,18 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<Nullable>enable</Nullable>
|
||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||
<Description>Hybrid Logical Clock library for deterministic, monotonic job ordering across distributed nodes</Description>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="Dapper" />
|
||||
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
|
||||
<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
|
||||
<PackageReference Include="Npgsql" />
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
Reference in New Issue
Block a user