stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Merge branch 'main' of https://git.stella-ops.org/stella-ops.org/git.stella-ops.org

Browse Source
This commit is contained in:
StellaOps Bot
2026-01-06 21:03:06 +02:00
parent 8cb2bc677a 4789027317
commit 05833e0af2
841 changed files with 15706 additions and 68106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
src/__Libraries/StellaOps.HybridLogicalClock/HlcClockSkewException.cs
View File

@@ -1,71 +1,49 @@
// <copyright file="HlcClockSkewException.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>
// -----------------------------------------------------------------------------
// 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 exceeds the configured tolerance.
/// Exception thrown when clock skew between nodes exceeds the configured threshold.
/// </summary>
/// <remarks>
/// <para>
/// This exception indicates that a remote timestamp differs from the local
/// physical clock by more than the configured maximum skew tolerance.
/// This typically indicates:
/// </para>
/// <list type="bullet">
/// <item><description>NTP synchronization failure on one or more nodes</description></item>
/// <item><description>Malicious/corrupted remote timestamp</description></item>
/// <item><description>Overly aggressive skew tolerance configuration</description></item>
/// </list>
/// 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>
/// Initializes a new instance of the <see cref="HlcClockSkewException"/> class.
/// The actual skew detected between clocks.
/// </summary>
/// <param name="observedSkew">The observed clock skew.</param>
/// <param name="maxAllowedSkew">The maximum allowed skew.</param>
public HlcClockSkewException(TimeSpan observedSkew, TimeSpan maxAllowedSkew)
: base($"Clock skew of {observedSkew.TotalMilliseconds:F0}ms exceeds maximum allowed {maxAllowedSkew.TotalMilliseconds:F0}ms")
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")
{
ObservedSkew = observedSkew;
ActualSkew = actualSkew;
MaxAllowedSkew = maxAllowedSkew;
}
/// <summary>
/// Initializes a new instance of the <see cref="HlcClockSkewException"/> class.
/// Creates a new clock skew exception with inner exception.
/// </summary>
/// <param name="message">The error message.</param>
public HlcClockSkewException(string message)
: base(message)
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;
}
/// <summary>
/// Initializes a new instance of the <see cref="HlcClockSkewException"/> class.
/// </summary>
/// <param name="message">The error message.</param>
/// <param name="innerException">The inner exception.</param>
public HlcClockSkewException(string message, Exception innerException)
: base(message, innerException)
{
}
/// <summary>
/// Initializes a new instance of the <see cref="HlcClockSkewException"/> class.
/// </summary>
public HlcClockSkewException()
{
}
/// <summary>
/// Gets the observed clock skew.
/// </summary>
public TimeSpan ObservedSkew { get; }
/// <summary>
/// Gets the maximum allowed clock skew.
/// </summary>
public TimeSpan MaxAllowedSkew { get; }
}

154
src/__Libraries/StellaOps.HybridLogicalClock/HlcServiceCollectionExtensions.cs
View File

@@ -1,127 +1,127 @@
// <copyright file="HlcServiceCollectionExtensions.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>
// -----------------------------------------------------------------------------
// 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;
using Microsoft.Extensions.Options;
namespace StellaOps.HybridLogicalClock;
/// <summary>
/// Extension methods for registering HLC services with dependency injection.
/// Extension methods for configuring HLC services in DI container.
/// </summary>
public static class HlcServiceCollectionExtensions
{
/// <summary>
/// Adds Hybrid Logical Clock services to the service collection.
/// Adds HLC services with in-memory state storage (for development/testing).
/// </summary>
/// <param name="services">The service collection.</param>
/// <param name="configureOptions">Optional action to configure HLC options.</param>
/// <returns>The service collection for chaining.</returns>
/// <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,
Action<HlcOptions>? configureOptions = null)
string nodeId,
TimeSpan? maxClockSkew = null)
{
ArgumentNullException.ThrowIfNull(services);
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
// Register options
if (configureOptions is not null)
{
services.Configure(configureOptions);
}
services.AddOptions<HlcOptions>()
.ValidateDataAnnotations()
.ValidateOnStart();
// Register Dapper type handler
HlcTimestampTypeHandler.Register();
// Register TimeProvider if not already registered
services.TryAddSingleton(TimeProvider.System);
services.TryAddSingleton<IHlcStateStore, InMemoryHlcStateStore>();
// Register state store based on configuration
services.AddSingleton<IHlcStateStore>(sp =>
{
var options = sp.GetRequiredService<IOptions<HlcOptions>>().Value;
if (options.UseInMemoryStore)
{
return new InMemoryHlcStateStore();
}
if (!string.IsNullOrEmpty(options.PostgresConnectionString))
{
var logger = sp.GetService<ILogger<PostgresHlcStateStore>>();
return new PostgresHlcStateStore(
options.PostgresConnectionString,
options.PostgresSchema,
logger);
}
// Default to in-memory if no connection string
return new InMemoryHlcStateStore();
});
// Register the clock
services.AddSingleton<IHybridLogicalClock>(sp =>
{
var options = sp.GetRequiredService<IOptions<HlcOptions>>().Value;
var timeProvider = sp.GetRequiredService<TimeProvider>();
var stateStore = sp.GetRequiredService<IHlcStateStore>();
var logger = sp.GetService<ILogger<HybridLogicalClock>>();
var logger = sp.GetRequiredService<ILogger<HybridLogicalClock>>();
var clock = new HybridLogicalClock(
return new HybridLogicalClock(
timeProvider,
options.GetEffectiveNodeId(),
nodeId,
stateStore,
options.MaxClockSkew,
logger);
return clock;
logger,
maxClockSkew);
});
return services;
}
/// <summary>
/// Adds Hybrid Logical Clock services with a specific node ID.
/// Adds HLC services with custom state storage.
/// </summary>
/// <param name="services">The service collection.</param>
/// <param name="nodeId">The node identifier.</param>
/// <returns>The service collection for chaining.</returns>
public static IServiceCollection AddHybridLogicalClock(
/// <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)
string nodeId,
TimeSpan? maxClockSkew = null)
where TStateStore : class, IHlcStateStore
{
ArgumentNullException.ThrowIfNull(services);
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
return services.AddHybridLogicalClock(options =>
services.TryAddSingleton(TimeProvider.System);
services.TryAddSingleton<IHlcStateStore, TStateStore>();
services.AddSingleton<IHybridLogicalClock>(sp =>
{
options.NodeId = nodeId;
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>
/// Initializes the HLC clock from persistent state.
/// Should be called during application startup.
/// Adds HLC services with factory-based state storage.
/// </summary>
/// <param name="serviceProvider">The service provider.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>A task representing the async operation.</returns>
public static async Task InitializeHlcAsync(
this IServiceProvider serviceProvider,
CancellationToken ct = default)
/// <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(serviceProvider);
ArgumentNullException.ThrowIfNull(services);
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
ArgumentNullException.ThrowIfNull(stateStoreFactory);
var clock = serviceProvider.GetRequiredService<IHybridLogicalClock>();
services.TryAddSingleton(TimeProvider.System);
services.TryAddSingleton(stateStoreFactory);
if (clock is HybridLogicalClock hlc)
services.AddSingleton<IHybridLogicalClock>(sp =>
{
await hlc.InitializeAsync(ct).ConfigureAwait(false);
}
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;
}
}

244
src/__Libraries/StellaOps.HybridLogicalClock/HlcTimestamp.cs
View File

@@ -1,10 +1,11 @@
// <copyright file="HlcTimestamp.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>
// -----------------------------------------------------------------------------
// HlcTimestamp.cs
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
// Task: HLC-002 - Implement HlcTimestamp record with comparison, parsing, serialization
// -----------------------------------------------------------------------------
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using System.Text.Json.Serialization;
using System.Text.RegularExpressions;
namespace StellaOps.HybridLogicalClock;
@@ -13,23 +14,17 @@ namespace StellaOps.HybridLogicalClock;
/// across distributed nodes even under clock skew.
/// </summary>
/// <remarks>
/// <para>
/// HLC combines the benefits of physical time (human-readable, bounded drift)
/// with logical clocks (guaranteed causality, no rollback). The timestamp
/// consists of three components:
/// </para>
/// <list type="bullet">
/// <item><description>PhysicalTime: Unix milliseconds UTC, advances with wall clock</description></item>
/// <item><description>NodeId: Unique identifier for the generating node</description></item>
/// <item><description>LogicalCounter: Increments when events occur at same physical time</description></item>
/// </list>
/// <para>
/// Total ordering is defined as: (PhysicalTime, LogicalCounter, NodeId)
/// </para>
/// 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) &lt; timestamp(B)
/// 3. Skew tolerance: Works correctly even when node clocks differ
/// </remarks>
[JsonConverter(typeof(HlcTimestampJsonConverter))]
public readonly record struct HlcTimestamp : IComparable<HlcTimestamp>, IComparable
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>
@@ -46,110 +41,100 @@ public readonly record struct HlcTimestamp : IComparable<HlcTimestamp>, ICompara
public required int LogicalCounter { get; init; }
/// <summary>
/// Gets the physical time as a <see cref="DateTimeOffset"/>.
/// Creates an HLC timestamp from the current wall-clock time.
/// </summary>
[JsonIgnore]
public DateTimeOffset PhysicalDateTime =>
/// <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>
/// Gets a zero/uninitialized timestamp.
/// String representation for storage and sorting.
/// Format: "1704067200000-scheduler-east-1-000042"
/// </summary>
public static HlcTimestamp Zero => new()
{
PhysicalTime = 0,
NodeId = string.Empty,
LogicalCounter = 0
};
/// <summary>
/// String representation for storage: "0001704067200000-scheduler-east-1-000042".
/// Format: {PhysicalTime:D13}-{NodeId}-{LogicalCounter:D6}
/// </summary>
/// <returns>A sortable string representation.</returns>
public string ToSortableString()
{
return string.Create(
CultureInfo.InvariantCulture,
$"{PhysicalTime:D13}-{NodeId}-{LogicalCounter:D6}");
}
/// <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">The sortable string to parse.</param>
/// <returns>The parsed <see cref="HlcTimestamp"/>.</returns>
/// <exception cref="ArgumentNullException">Thrown when value is null.</exception>
/// <exception cref="FormatException">Thrown when value is not in valid format.</exception>
/// <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)
{
ArgumentNullException.ThrowIfNull(value);
ArgumentException.ThrowIfNullOrWhiteSpace(value);
if (!TryParse(value, out var result))
var match = ParseRegex.Match(value);
if (!match.Success)
{
throw new FormatException($"Invalid HLC timestamp format: '{value}'");
throw new FormatException(
$"Invalid HLC timestamp format: '{value}'. Expected format: '{{physicalTime13}}-{{nodeId}}-{{counter6}}'");
}
return result;
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">The sortable string to parse.</param>
/// <param name="result">The parsed timestamp if successful.</param>
/// <returns>True if parsing succeeded; otherwise false.</returns>
public static bool TryParse(
[NotNullWhen(true)] string? value,
out HlcTimestamp result)
/// <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.IsNullOrEmpty(value))
{
if (string.IsNullOrWhiteSpace(value))
return false;
}
// Format: {PhysicalTime:D13}-{NodeId}-{LogicalCounter:D6}
// Example: 0001704067200000-scheduler-east-1-000042
// The NodeId can contain hyphens, so we parse from both ends
var firstDash = value.IndexOf('-', StringComparison.Ordinal);
if (firstDash < 1)
{
var match = ParseRegex.Match(value);
if (!match.Success)
return false;
}
var lastDash = value.LastIndexOf('-');
if (lastDash <= firstDash || lastDash >= value.Length - 1)
{
if (!long.TryParse(match.Groups[1].Value, CultureInfo.InvariantCulture, out var physicalTime))
return false;
}
var physicalTimeStr = value[..firstDash];
var nodeId = value[(firstDash + 1)..lastDash];
var counterStr = value[(lastDash + 1)..];
if (!long.TryParse(physicalTimeStr, NumberStyles.None, CultureInfo.InvariantCulture, out var physicalTime))
{
if (!int.TryParse(match.Groups[3].Value, CultureInfo.InvariantCulture, out var logicalCounter))
return false;
}
if (string.IsNullOrEmpty(nodeId))
{
return false;
}
if (!int.TryParse(counterStr, NumberStyles.None, CultureInfo.InvariantCulture, out var counter))
{
return false;
}
result = new HlcTimestamp
{
PhysicalTime = physicalTime,
NodeId = nodeId,
LogicalCounter = counter
NodeId = match.Groups[2].Value,
LogicalCounter = logicalCounter
};
return true;
@@ -157,64 +142,63 @@ public readonly record struct HlcTimestamp : IComparable<HlcTimestamp>, ICompara
/// <summary>
/// Compare for total ordering.
/// Order: (PhysicalTime, LogicalCounter, NodeId).
/// </summary>
/// <param name="other">The other timestamp to compare.</param>
/// <returns>Comparison result.</returns>
/// <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;
}
if (physicalCompare != 0) return physicalCompare;
// Secondary: logical counter
var counterCompare = LogicalCounter.CompareTo(other.LogicalCounter);
if (counterCompare != 0)
{
return counterCompare;
}
if (counterCompare != 0) return counterCompare;
// Tertiary: node ID (for stable tie-breaking)
return string.Compare(NodeId, other.NodeId, StringComparison.Ordinal);
}
/// <inheritdoc/>
public int CompareTo(object? obj)
{
if (obj is null)
{
return 1;
}
if (obj is HlcTimestamp other)
{
return CompareTo(other);
}
throw new ArgumentException($"Object must be of type {nameof(HlcTimestamp)}", nameof(obj));
}
/// <summary>
/// Returns true if this timestamp is causally before the other.
/// </summary>
public bool IsBefore(HlcTimestamp other) => CompareTo(other) < 0;
/// <summary>
/// Less than operator.
/// 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;
/// <summary>
/// Less than or equal operator.
/// </summary>
public static bool operator <=(HlcTimestamp left, HlcTimestamp right) => left.CompareTo(right) <= 0;
/// <summary>
/// Greater than operator.
/// </summary>
public static bool operator >(HlcTimestamp left, HlcTimestamp right) => left.CompareTo(right) > 0;
/// <summary>
/// Greater than or equal operator.
/// </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;
/// <inheritdoc/>

169
src/__Libraries/StellaOps.HybridLogicalClock/HlcTimestampJsonConverter.cs
View File

@@ -1,6 +1,8 @@
// <copyright file="HlcTimestampJsonConverter.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>
// -----------------------------------------------------------------------------
// 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;
@@ -8,53 +10,166 @@ using System.Text.Json.Serialization;
namespace StellaOps.HybridLogicalClock;
/// <summary>
/// JSON converter for <see cref="HlcTimestamp"/> using sortable string format.
/// JSON converter for HlcTimestamp using the sortable string format.
/// </summary>
/// <remarks>
/// <para>
/// Serializes to and deserializes from the sortable string format:
/// "{PhysicalTime:D13}-{NodeId}-{LogicalCounter:D6}"
/// </para>
/// <para>
/// Example: "0001704067200000-scheduler-east-1-000042"
/// </para>
/// 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)
public override HlcTimestamp Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
if (reader.TokenType == JsonTokenType.Null)
{
return HlcTimestamp.Zero;
throw new JsonException("Cannot convert null value to HlcTimestamp");
}
if (reader.TokenType != JsonTokenType.String)
{
throw new JsonException($"Expected string token for HlcTimestamp, got {reader.TokenType}");
throw new JsonException($"Expected string but got {reader.TokenType}");
}
var value = reader.GetString();
if (!HlcTimestamp.TryParse(value, out var result))
if (string.IsNullOrWhiteSpace(value))
{
throw new JsonException($"Invalid HlcTimestamp format: '{value}'");
throw new JsonException("Cannot convert empty string to HlcTimestamp");
}
return result;
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)
public override void Write(Utf8JsonWriter writer, HlcTimestamp value, JsonSerializerOptions options)
{
ArgumentNullException.ThrowIfNull(writer);
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();
}
}

207
src/__Libraries/StellaOps.HybridLogicalClock/HlcTimestampTypeHandler.cs
View File

@@ -1,59 +1,212 @@
// <copyright file="HlcTimestampTypeHandler.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>
// -----------------------------------------------------------------------------
// HlcTimestampTypeHandler.cs
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
// Task: HLC-007 - Add HlcTimestampTypeHandler for Npgsql/Dapper
// -----------------------------------------------------------------------------
using System.Data;
using Dapper;
using Npgsql;
using NpgsqlTypes;
namespace StellaOps.HybridLogicalClock;
/// <summary>
/// Dapper type handler for <see cref="HlcTimestamp"/>.
/// Npgsql type handler for HlcTimestamp stored as TEXT in sortable string format.
/// </summary>
/// <remarks>
/// <para>
/// Maps HlcTimestamp to/from TEXT column using sortable string format.
/// Register with: <c>SqlMapper.AddTypeHandler(new HlcTimestampTypeHandler());</c>
/// This handler allows HlcTimestamp to be used directly in Npgsql queries:
/// <code>
/// cmd.Parameters.AddWithValue("@hlc", hlcTimestamp);
/// var hlc = reader.GetFieldValue&lt;HlcTimestamp&gt;(0);
/// </code>
/// </para>
/// <para>
/// Register with Npgsql using:
/// <code>
/// NpgsqlConnection.GlobalTypeMapper.AddTypeInfoResolverFactory(new HlcTimestampTypeHandlerResolverFactory());
/// </code>
/// </para>
/// </remarks>
public sealed class HlcTimestampTypeHandler : SqlMapper.TypeHandler<HlcTimestamp>
public static class HlcTimestampNpgsqlExtensions
{
/// <summary>
/// Gets the singleton instance of the type handler.
/// Adds an HlcTimestamp parameter to the command.
/// </summary>
public static HlcTimestampTypeHandler Instance { get; } = new();
/// <summary>
/// Registers this type handler with Dapper.
/// Should be called once at application startup.
/// </summary>
public static void Register()
/// <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)
{
SqlMapper.AddTypeHandler(Instance);
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 null or DBNull)
if (value is string str)
{
return HlcTimestamp.Zero;
return HlcTimestamp.Parse(str);
}
if (value is string strValue)
{
return HlcTimestamp.Parse(strValue);
}
throw new DataException($"Cannot convert {value.GetType().Name} to HlcTimestamp");
throw new DataException($"Cannot convert {value?.GetType().Name ?? "null"} to HlcTimestamp");
}
/// <inheritdoc/>
public override void SetValue(IDbDataParameter parameter, HlcTimestamp value)
{
ArgumentNullException.ThrowIfNull(parameter);
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;
}
}
}

279
src/__Libraries/StellaOps.HybridLogicalClock/HybridLogicalClock.cs
View File

@@ -1,68 +1,67 @@
// <copyright file="HybridLogicalClock.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>
// -----------------------------------------------------------------------------
// 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;
using Microsoft.Extensions.Logging.Abstractions;
namespace StellaOps.HybridLogicalClock;
/// <summary>
/// Default implementation of <see cref="IHybridLogicalClock"/>.
/// Implementation of Hybrid Logical Clock algorithm for deterministic,
/// monotonic timestamp generation across distributed nodes.
/// </summary>
/// <remarks>
/// <para>
/// Implements the Hybrid Logical Clock algorithm which combines physical time
/// with logical counters to provide:
/// 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>
/// <list type="bullet">
/// <item><description>Monotonicity: timestamps always increase</description></item>
/// <item><description>Causality: if A happens-before B, then HLC(A) &lt; HLC(B)</description></item>
/// <item><description>Bounded drift: physical component stays close to wall clock</description></item>
/// </list>
/// <para>
/// Thread-safety is guaranteed via internal locking.
/// 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 readonly object _lock = new();
private long _lastPhysicalTime;
private int _logicalCounter;
/// <summary>
/// Initializes a new instance of the <see cref="HybridLogicalClock"/> class.
/// </summary>
/// <param name="timeProvider">Time provider for physical clock.</param>
/// <param name="nodeId">Unique identifier for this node.</param>
/// <param name="stateStore">Persistent state store.</param>
/// <param name="maxClockSkew">Maximum allowed clock skew (default: 1 minute).</param>
/// <param name="logger">Optional logger.</param>
public HybridLogicalClock(
TimeProvider timeProvider,
string nodeId,
IHlcStateStore stateStore,
TimeSpan? maxClockSkew = null,
ILogger<HybridLogicalClock>? logger = null)
{
ArgumentNullException.ThrowIfNull(timeProvider);
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
ArgumentNullException.ThrowIfNull(stateStore);
_timeProvider = timeProvider;
NodeId = nodeId;
_stateStore = stateStore;
_maxClockSkew = maxClockSkew ?? TimeSpan.FromMinutes(1);
_logger = logger ?? NullLogger<HybridLogicalClock>.Instance;
}
private readonly object _lock = new();
/// <inheritdoc/>
public string NodeId { get; }
public string NodeId => _nodeId;
/// <inheritdoc/>
public HlcTimestamp Current
@@ -74,13 +73,92 @@ public sealed class HybridLogicalClock : IHybridLogicalClock
return new HlcTimestamp
{
PhysicalTime = _lastPhysicalTime,
NodeId = NodeId,
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()
{
@@ -92,22 +170,23 @@ public sealed class HybridLogicalClock : IHybridLogicalClock
if (physicalNow > _lastPhysicalTime)
{
// Physical clock advanced - reset counter
// Physical time advanced - reset counter
_lastPhysicalTime = physicalNow;
_logicalCounter = 0;
}
else
{
// Same or earlier physical time - increment counter
// This handles clock regression gracefully
// Physical time hasn't advanced - increment counter
_logicalCounter++;
// Check for counter overflow (unlikely but handle it)
if (_logicalCounter < 0)
{
_logger.LogWarning(
"HLC logical counter overflow detected, advancing physical time. NodeId={NodeId}",
NodeId);
"HLC counter overflow for node {NodeId}, forcing time advance",
_nodeId);
// Force time advance to next millisecond
_lastPhysicalTime++;
_logicalCounter = 0;
}
@@ -116,7 +195,7 @@ public sealed class HybridLogicalClock : IHybridLogicalClock
timestamp = new HlcTimestamp
{
PhysicalTime = _lastPhysicalTime,
NodeId = NodeId,
NodeId = _nodeId,
LogicalCounter = _logicalCounter
};
}
@@ -141,54 +220,45 @@ public sealed class HybridLogicalClock : IHybridLogicalClock
if (skew > _maxClockSkew)
{
_logger.LogError(
"Clock skew exceeded: observed={ObservedMs}ms, max={MaxMs}ms, remote={RemoteNodeId}",
skew.TotalMilliseconds,
_maxClockSkew.TotalMilliseconds,
remote.NodeId);
"Clock skew of {Skew} from node {RemoteNode} exceeds threshold {MaxSkew}",
skew,
remote.NodeId,
_maxClockSkew);
throw new HlcClockSkewException(skew, _maxClockSkew);
}
var prevPhysicalTime = _lastPhysicalTime;
var maxPhysical = Math.Max(Math.Max(prevPhysicalTime, remote.PhysicalTime), physicalNow);
// Find maximum physical time
var maxPhysical = Math.Max(Math.Max(_lastPhysicalTime, remote.PhysicalTime), physicalNow);
if (maxPhysical == prevPhysicalTime && maxPhysical == remote.PhysicalTime)
// 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 == prevPhysicalTime)
else if (maxPhysical == _lastPhysicalTime)
{
// Local was max - increment local counter
// Our time is max - just increment our counter
_logicalCounter++;
}
else if (maxPhysical == remote.PhysicalTime)
{
// Remote was max - take remote counter and increment
// Remote time is max - take their counter and increment
_logicalCounter = remote.LogicalCounter + 1;
}
else
{
// Physical clock advanced - reset counter
// Physical clock is max - reset counter
_logicalCounter = 0;
}
_lastPhysicalTime = maxPhysical;
// Check for counter overflow
if (_logicalCounter < 0)
{
_logger.LogWarning(
"HLC logical counter overflow on receive, advancing physical time. NodeId={NodeId}",
NodeId);
_lastPhysicalTime++;
_logicalCounter = 0;
}
timestamp = new HlcTimestamp
{
PhysicalTime = _lastPhysicalTime,
NodeId = NodeId,
NodeId = _nodeId,
LogicalCounter = _logicalCounter
};
}
@@ -196,77 +266,28 @@ public sealed class HybridLogicalClock : IHybridLogicalClock
// Persist state asynchronously
_ = PersistStateAsync(timestamp);
_logger.LogDebug(
"HLC receive from {RemoteNode}: {RemoteTimestamp} -> {LocalTimestamp}",
remote.NodeId,
remote,
timestamp);
return timestamp;
}
/// <summary>
/// Initialize clock state from persistent store.
/// Should be called once during startup.
/// </summary>
/// <param name="ct">Cancellation token.</param>
/// <returns>True if state was recovered; false if starting fresh.</returns>
public async Task<bool> InitializeAsync(CancellationToken ct = default)
{
var persisted = await _stateStore.LoadAsync(NodeId, ct).ConfigureAwait(false);
if (persisted is { } state)
{
lock (_lock)
{
// Ensure we never go backward
var physicalNow = _timeProvider.GetUtcNow().ToUnixTimeMilliseconds();
_lastPhysicalTime = Math.Max(state.PhysicalTime, physicalNow);
if (_lastPhysicalTime == state.PhysicalTime)
{
// Same physical time - continue from persisted counter + 1
_logicalCounter = state.LogicalCounter + 1;
}
else
{
// Physical time advanced - reset counter
_logicalCounter = 0;
}
}
_logger.LogInformation(
"HLC state recovered: PhysicalTime={PhysicalTime}, Counter={Counter}, NodeId={NodeId}",
_lastPhysicalTime,
_logicalCounter,
NodeId);
return true;
}
lock (_lock)
{
_lastPhysicalTime = _timeProvider.GetUtcNow().ToUnixTimeMilliseconds();
_logicalCounter = 0;
}
_logger.LogInformation(
"HLC initialized fresh: PhysicalTime={PhysicalTime}, NodeId={NodeId}",
_lastPhysicalTime,
NodeId);
return false;
}
private async Task PersistStateAsync(HlcTimestamp timestamp)
{
try
{
await _stateStore.SaveAsync(timestamp).ConfigureAwait(false);
await _stateStore.SaveAsync(timestamp);
}
catch (Exception ex)
{
// Fire-and-forget with error logging
// Clock continues operating; state will be recovered on next successful save
_logger.LogWarning(
ex,
"Failed to persist HLC state: NodeId={NodeId}, PhysicalTime={PhysicalTime}",
NodeId,
timestamp.PhysicalTime);
"Failed to persist HLC state for node {NodeId}: {Timestamp}",
_nodeId,
timestamp);
}
}
}

85
src/__Libraries/StellaOps.HybridLogicalClock/IHybridLogicalClock.cs
View File

@@ -1,21 +1,19 @@
// <copyright file="IHybridLogicalClock.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>
// -----------------------------------------------------------------------------
// 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.
/// Hybrid Logical Clock for monotonic timestamp generation across distributed nodes.
/// </summary>
/// <remarks>
/// <para>
/// Implementations must guarantee:
/// </para>
/// <list type="number">
/// <item><description>Successive Tick() calls return strictly increasing timestamps</description></item>
/// <item><description>Receive() merges remote timestamp maintaining causality</description></item>
/// <item><description>Clock state survives restarts via persistence</description></item>
/// </list>
/// 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
{
@@ -23,43 +21,62 @@ public interface IHybridLogicalClock
/// Generate next timestamp for local event.
/// </summary>
/// <remarks>
/// <para>Algorithm:</para>
/// <list type="number">
/// <item><description>l' = l (save previous logical time)</description></item>
/// <item><description>l = max(l, physical_clock())</description></item>
/// <item><description>if l == l': c = c + 1 else: c = 0</description></item>
/// <item><description>return (l, node_id, c)</description></item>
/// </list>
/// This should be called for every event that needs ordering:
/// - Job enqueue
/// - State transitions
/// - Audit log entries
/// </remarks>
/// <returns>A new monotonically increasing timestamp.</returns>
/// <returns>New monotonically increasing HLC timestamp</returns>
HlcTimestamp Tick();
/// <summary>
/// Update clock on receiving remote timestamp, return merged result.
/// </summary>
/// <remarks>
/// <para>Algorithm:</para>
/// <list type="number">
/// <item><description>l' = l (save previous)</description></item>
/// <item><description>l = max(l', m_l, physical_clock())</description></item>
/// <item><description>Update c based on which max was chosen</description></item>
/// <item><description>return (l, node_id, c)</description></item>
/// </list>
/// Called when receiving a message from another node to ensure
/// causal ordering is maintained across the distributed system.
/// </remarks>
/// <param name="remote">The remote timestamp to merge.</param>
/// <returns>A new timestamp incorporating the remote causality.</returns>
/// <exception cref="HlcClockSkewException">
/// Thrown when the remote timestamp differs from physical clock by more than max skew tolerance.
/// </exception>
/// <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>
/// Gets the current clock state (for persistence/recovery).
/// Current clock state (for persistence/recovery).
/// </summary>
HlcTimestamp Current { get; }
/// <summary>
/// Gets the node identifier for this clock instance.
/// 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);
}

41
src/__Libraries/StellaOps.HybridLogicalClock/InMemoryHlcStateStore.cs
View File

@@ -1,41 +1,47 @@
// <copyright file="InMemoryHlcStateStore.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>
// -----------------------------------------------------------------------------
// 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 <see cref="IHlcStateStore"/> for testing and development.
/// In-memory implementation of HLC state store for testing and development.
/// </summary>
/// <remarks>
/// <para>
/// State is lost on process restart. Use <see cref="PostgresHlcStateStore"/> for production.
/// </para>
/// 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> _store = new(StringComparer.Ordinal);
private readonly ConcurrentDictionary<string, HlcTimestamp> _states = new(StringComparer.Ordinal);
/// <inheritdoc/>
public Task<HlcTimestamp?> LoadAsync(string nodeId, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(nodeId);
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
ct.ThrowIfCancellationRequested();
return Task.FromResult<HlcTimestamp?>(
_store.TryGetValue(nodeId, out var timestamp) ? timestamp : null);
return Task.FromResult(
_states.TryGetValue(nodeId, out var timestamp)
? timestamp
: (HlcTimestamp?)null);
}
/// <inheritdoc/>
public Task SaveAsync(HlcTimestamp timestamp, CancellationToken ct = default)
{
_store.AddOrUpdate(
ct.ThrowIfCancellationRequested();
_states.AddOrUpdate(
timestamp.NodeId,
timestamp,
(_, existing) =>
{
// Only update if new timestamp is greater (prevents regression on concurrent saves)
// Only update if new timestamp is greater (maintain monotonicity)
return timestamp > existing ? timestamp : existing;
});
@@ -43,12 +49,13 @@ public sealed class InMemoryHlcStateStore : IHlcStateStore
}
/// <summary>
/// Clear all stored state (for testing).
/// Gets all stored states (for testing/debugging).
/// </summary>
public void Clear() => _store.Clear();
public IReadOnlyDictionary<string, HlcTimestamp> GetAllStates() =>
new Dictionary<string, HlcTimestamp>(_states);
/// <summary>
/// Gets the count of stored entries (for testing).
/// Clears all stored states (for testing).
/// </summary>
public int Count => _store.Count;
public void Clear() => _states.Clear();
}

241
src/__Libraries/StellaOps.HybridLogicalClock/PostgresHlcStateStore.cs
View File

@@ -1,22 +1,26 @@
// <copyright file="PostgresHlcStateStore.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>
// -----------------------------------------------------------------------------
// PostgresHlcStateStore.cs
// Sprint: SPRINT_20260105_002_001_LB_hlc_core_library
// Task: HLC-005 - Implement PostgresHlcStateStore with atomic update semantics
// -----------------------------------------------------------------------------
using System.Globalization;
using Dapper;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using Npgsql;
namespace StellaOps.HybridLogicalClock;
/// <summary>
/// PostgreSQL implementation of <see cref="IHlcStateStore"/> with atomic update semantics.
/// PostgreSQL implementation of HLC state store for production deployments.
/// </summary>
/// <remarks>
/// <para>
/// Requires the following table (created via migration or manually):
/// 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,
@@ -25,147 +29,200 @@ namespace StellaOps.HybridLogicalClock;
/// updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
/// );
/// </code>
/// </para>
/// </remarks>
public sealed class PostgresHlcStateStore : IHlcStateStore
{
private readonly string _connectionString;
private readonly string _schema;
private readonly NpgsqlDataSource _dataSource;
private readonly ILogger<PostgresHlcStateStore> _logger;
private readonly string _schema;
private readonly string _tableName;
/// <summary>
/// Initializes a new instance of the <see cref="PostgresHlcStateStore"/> class.
/// Creates a new PostgreSQL HLC state store.
/// </summary>
/// <param name="connectionString">PostgreSQL connection string.</param>
/// <param name="schema">Schema name (default: "scheduler").</param>
/// <param name="logger">Optional logger.</param>
/// <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(
string connectionString,
NpgsqlDataSource dataSource,
ILogger<PostgresHlcStateStore> logger,
string schema = "scheduler",
ILogger<PostgresHlcStateStore>? logger = null)
string tableName = "hlc_state")
{
ArgumentException.ThrowIfNullOrWhiteSpace(connectionString);
ArgumentException.ThrowIfNullOrWhiteSpace(schema);
_connectionString = connectionString;
_dataSource = dataSource ?? throw new ArgumentNullException(nameof(dataSource));
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
_schema = schema;
_logger = logger ?? NullLogger<PostgresHlcStateStore>.Instance;
_tableName = tableName;
}
/// <inheritdoc/>
public async Task<HlcTimestamp?> LoadAsync(string nodeId, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(nodeId);
ArgumentException.ThrowIfNullOrWhiteSpace(nodeId);
var sql = string.Create(
CultureInfo.InvariantCulture,
$"""
var sql = $"""
SELECT physical_time, logical_counter
FROM {_schema}.hlc_state
WHERE node_id = @NodeId
""");
FROM {_schema}.{_tableName}
WHERE node_id = @node_id
""";
await using var connection = new NpgsqlConnection(_connectionString);
await connection.OpenAsync(ct).ConfigureAwait(false);
await using var connection = await _dataSource.OpenConnectionAsync(ct);
await using var cmd = new NpgsqlCommand(sql, connection);
cmd.Parameters.AddWithValue("node_id", nodeId);
var result = await connection.QuerySingleOrDefaultAsync<HlcStateRow>(
new CommandDefinition(
sql,
new { NodeId = nodeId },
cancellationToken: ct)).ConfigureAwait(false);
await using var reader = await cmd.ExecuteReaderAsync(ct);
if (result is null)
if (!await reader.ReadAsync(ct))
{
_logger.LogDebug("No HLC state found for node {NodeId}", nodeId);
return null;
}
return new HlcTimestamp
var physicalTime = reader.GetInt64(0);
var logicalCounter = reader.GetInt32(1);
var timestamp = new HlcTimestamp
{
PhysicalTime = result.physical_time,
PhysicalTime = physicalTime,
NodeId = nodeId,
LogicalCounter = result.logical_counter
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 monotonicity guarantee:
// Only update if new values are greater than existing
var sql = string.Create(
CultureInfo.InvariantCulture,
$"""
INSERT INTO {_schema}.hlc_state (node_id, physical_time, logical_counter, updated_at)
VALUES (@NodeId, @PhysicalTime, @LogicalCounter, NOW())
ON CONFLICT (node_id) DO UPDATE
SET physical_time = GREATEST({_schema}.hlc_state.physical_time, EXCLUDED.physical_time),
logical_counter = CASE
WHEN EXCLUDED.physical_time > {_schema}.hlc_state.physical_time THEN EXCLUDED.logical_counter
WHEN EXCLUDED.physical_time = {_schema}.hlc_state.physical_time
AND EXCLUDED.logical_counter > {_schema}.hlc_state.logical_counter THEN EXCLUDED.logical_counter
ELSE {_schema}.hlc_state.logical_counter
END,
// 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 = new NpgsqlConnection(_connectionString);
await connection.OpenAsync(ct).ConfigureAwait(false);
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);
try
var rowsAffected = await cmd.ExecuteNonQueryAsync(ct);
if (rowsAffected > 0)
{
await connection.ExecuteAsync(
new CommandDefinition(
sql,
new
{
timestamp.NodeId,
timestamp.PhysicalTime,
timestamp.LogicalCounter
},
cancellationToken: ct)).ConfigureAwait(false);
_logger.LogDebug("Saved HLC state for node {NodeId}: {Timestamp}", timestamp.NodeId, timestamp);
}
catch (NpgsqlException ex)
else
{
_logger.LogWarning(
ex,
"Failed to save HLC state to PostgreSQL: NodeId={NodeId}, PhysicalTime={PhysicalTime}",
_logger.LogDebug(
"HLC state not updated for node {NodeId}: {Timestamp} (existing state is newer)",
timestamp.NodeId,
timestamp.PhysicalTime);
throw;
timestamp);
}
}
/// <summary>
/// Ensure the HLC state table exists (for development/testing).
/// In production, use migrations.
/// Ensures the HLC state table exists in the database.
/// </summary>
/// <param name="ct">Cancellation token.</param>
/// <returns>A task representing the async operation.</returns>
/// <param name="ct">Cancellation token</param>
public async Task EnsureTableExistsAsync(CancellationToken ct = default)
{
var sql = string.Create(
CultureInfo.InvariantCulture,
$"""
var sql = $"""
CREATE SCHEMA IF NOT EXISTS {_schema};
CREATE TABLE IF NOT EXISTS {_schema}.hlc_state (
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_hlc_state_updated
ON {_schema}.hlc_state(updated_at DESC);
""");
CREATE INDEX IF NOT EXISTS idx_{_tableName}_updated
ON {_schema}.{_tableName}(updated_at DESC);
""";
await using var connection = new NpgsqlConnection(_connectionString);
await connection.OpenAsync(ct).ConfigureAwait(false);
await connection.ExecuteAsync(new CommandDefinition(sql, cancellationToken: ct)).ConfigureAwait(false);
await using var connection = await _dataSource.OpenConnectionAsync(ct);
await using var cmd = new NpgsqlCommand(sql, connection);
await cmd.ExecuteNonQueryAsync(ct);
_logger.LogInformation("HLC state table ensured in schema {Schema}", _schema);
_logger.LogInformation("Ensured HLC state table exists: {Schema}.{Table}", _schema, _tableName);
}
#pragma warning disable IDE1006 // Naming Styles - matches DB column names
private sealed record HlcStateRow(long physical_time, int logical_counter);
#pragma warning restore IDE1006
/// <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;
}
}

469
src/__Libraries/StellaOps.HybridLogicalClock/README.md
View File

@@ -1,30 +1,29 @@
# StellaOps.HybridLogicalClock
A Hybrid Logical Clock (HLC) implementation for deterministic, monotonic job ordering across distributed nodes. HLC combines physical time with logical counters to provide causally-ordered timestamps even under clock skew.
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
Traditional wall-clock timestamps are susceptible to clock skew across distributed nodes. HLC addresses this by combining:
### Problem Statement
- **Physical time**: Unix milliseconds UTC, advances with wall clock
- **Node ID**: Unique identifier for the generating node
- **Logical counter**: Increments when events occur at the same physical time
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
This provides:
- **Monotonicity**: Successive timestamps always increase
- **Causality**: If event A happens-before event B, then HLC(A) < HLC(B)
- **Bounded drift**: Physical component stays close to wall clock
### 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
```csharp
// In your Startup.cs or Program.cs
services.AddHybridLogicalClock(options =>
{
options.NodeId = "scheduler-east-1";
options.MaxClockSkew = TimeSpan.FromMinutes(1);
options.PostgresConnectionString = configuration.GetConnectionString("Default");
});
Reference the project in your `.csproj`:
```xml
<ProjectReference Include="..\__Libraries\StellaOps.HybridLogicalClock\StellaOps.HybridLogicalClock.csproj" />
```
## Quick Start
@@ -32,112 +31,118 @@ services.AddHybridLogicalClock(options =>
### Basic Usage
```csharp
public class JobScheduler
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)
{
private readonly IHybridLogicalClock _clock;
public JobScheduler(IHybridLogicalClock clock)
public void EnqueueJob(Job job)
{
_clock = clock;
}
public Job EnqueueJob(JobPayload payload)
{
// Generate monotonic timestamp for the job
var timestamp = _clock.Tick();
return new Job
{
Id = Guid.NewGuid(),
Timestamp = timestamp,
Payload = payload
};
job.EnqueuedAt = clock.Tick();
// Jobs are now globally ordered across all scheduler nodes
}
}
```
### Receiving Remote Timestamps
When processing messages from other nodes:
```csharp
public void ProcessRemoteMessage(Message message)
{
// Merge remote timestamp to maintain causality
var localTimestamp = _clock.Receive(message.Timestamp);
// Now localTimestamp > message.Timestamp is guaranteed
ProcessPayload(message.Payload, localTimestamp);
}
```
### Initialization from Persistent State
During application startup, initialize the clock from persisted state:
```csharp
var host = builder.Build();
// Initialize HLC from persistent state before starting
await host.Services.InitializeHlcAsync();
await host.RunAsync();
```
## API Reference
## Core Types
### HlcTimestamp
A readonly record struct representing an HLC timestamp.
A readonly record struct representing an HLC timestamp:
```csharp
public readonly record struct HlcTimestamp : IComparable<HlcTimestamp>
{
// Unix milliseconds UTC
public required long PhysicalTime { get; init; }
// Unique node identifier
public required string NodeId { get; init; }
// Logical counter for same-time events
public required int LogicalCounter { get; init; }
// Convert to sortable string: "0001704067200000-node-id-000042"
public string ToSortableString();
// Parse from sortable string
public static HlcTimestamp Parse(string value);
public static bool TryParse(string? value, out HlcTimestamp result);
// Get physical time as DateTimeOffset
public DateTimeOffset PhysicalDateTime { get; }
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 interface for HLC operations.
The main clock interface:
```csharp
public interface IHybridLogicalClock
{
// Generate next timestamp for local event
HlcTimestamp Tick();
// Merge with remote timestamp, return new local timestamp
HlcTimestamp Receive(HlcTimestamp remote);
// Current clock state
HlcTimestamp Current { get; }
// Node identifier
string NodeId { get; }
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
Interface for persisting clock state across restarts.
Persistence interface for clock state:
```csharp
public interface IHlcStateStore
@@ -147,42 +152,15 @@ public interface IHlcStateStore
}
```
Built-in implementations:
- `InMemoryHlcStateStore`: For testing (state lost on restart)
- `PostgresHlcStateStore`: Persists to PostgreSQL
**Implementations:**
- `InMemoryHlcStateStore` - For development and testing
- `PostgresHlcStateStore` - For production with durable persistence
## Configuration
## Persistence
### HlcOptions
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `NodeId` | string? | auto | Unique node identifier (e.g., "scheduler-east-1") |
| `MaxClockSkew` | TimeSpan | 1 minute | Maximum allowed difference from remote timestamps |
| `PostgresConnectionString` | string? | null | Connection string for PostgreSQL persistence |
| `PostgresSchema` | string | "scheduler" | PostgreSQL schema for HLC tables |
| `UseInMemoryStore` | bool | false | Force in-memory store (for testing) |
### Configuration via appsettings.json
```json
{
"HybridLogicalClock": {
"NodeId": "scheduler-east-1",
"MaxClockSkew": "00:01:00",
"PostgresConnectionString": "Host=localhost;Database=stellaops;Username=app",
"PostgresSchema": "scheduler"
}
}
```
## PostgreSQL Schema
Create the required table:
### PostgreSQL Schema
```sql
CREATE SCHEMA IF NOT EXISTS scheduler;
CREATE TABLE scheduler.hlc_state (
node_id TEXT PRIMARY KEY,
physical_time BIGINT NOT NULL,
@@ -193,128 +171,197 @@ CREATE TABLE scheduler.hlc_state (
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)
HlcTimestamp includes a built-in JSON converter that serializes to the sortable string format:
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 timestamp = clock.Tick();
var json = JsonSerializer.Serialize(timestamp);
// Output: "0001704067200000-scheduler-east-1-000042"
var parsed = JsonSerializer.Deserialize<HlcTimestamp>(json);
var options = new JsonSerializerOptions();
options.Converters.Add(new HlcTimestampJsonConverter()); // String format
// or
options.Converters.Add(new HlcTimestampObjectJsonConverter()); // Object format
```
### Dapper
### Database (Npgsql/Dapper)
Register the type handler for Dapper:
Extension methods for reading/writing HLC timestamps:
```csharp
HlcTimestampTypeHandler.Register();
// NpgsqlCommand extension
await using var cmd = dataSource.CreateCommand();
cmd.CommandText = "INSERT INTO events (timestamp) VALUES (@ts)";
cmd.AddHlcTimestamp("ts", timestamp);
await cmd.ExecuteNonQueryAsync();
// Now you can use HlcTimestamp in Dapper queries
var job = connection.QuerySingle<Job>(
"SELECT * FROM jobs WHERE timestamp > @Timestamp",
new { Timestamp = minTimestamp });
// NpgsqlDataReader extension
await using var reader = await cmd.ExecuteReaderAsync();
var ts = reader.GetHlcTimestamp("timestamp");
var nullableTs = reader.GetHlcTimestampOrNull("timestamp");
```
## Error Handling
### HlcClockSkewException
Thrown when a remote timestamp differs from local physical clock by more than `MaxClockSkew`:
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 localTs = clock.Receive(remoteTimestamp);
var merged = clock.Receive(remoteTimestamp);
}
catch (HlcClockSkewException ex)
{
logger.LogError(
"Clock skew exceeded: observed {ObservedMs}ms, max {MaxMs}ms",
ex.ObservedSkew.TotalMilliseconds,
ex.MaxSkew.TotalMilliseconds);
// Reject the message or alert operations
// 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
For unit tests, use FakeTimeProvider and InMemoryHlcStateStore:
### FakeTimeProvider
For deterministic testing, use a fake time provider:
```csharp
[Fact]
public void Tick_ReturnsMonotonicallyIncreasingTimestamps()
public class FakeTimeProvider : TimeProvider
{
var timeProvider = new FakeTimeProvider(DateTimeOffset.UtcNow);
var stateStore = new InMemoryHlcStateStore();
var clock = new HybridLogicalClock(timeProvider, "test-node", stateStore);
private DateTimeOffset _now = DateTimeOffset.UtcNow;
var t1 = clock.Tick();
var t2 = clock.Tick();
var t3 = clock.Tick();
public override DateTimeOffset GetUtcNow() => _now;
Assert.True(t1 < t2);
Assert.True(t2 < t3);
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 | Allocation |
|-----------|------------|------------|
| Tick | ~5M ops/sec | 0 bytes |
| Receive | ~3M ops/sec | 0 bytes |
| ToSortableString | ~10M ops/sec | 80 bytes |
| Parse | ~5M ops/sec | 48 bytes |
| 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 |
Run benchmarks:
```bash
cd src/__Libraries/StellaOps.HybridLogicalClock.Benchmarks
dotnet run -c Release
```
## Algorithm
The HLC algorithm (Lamport + Physical Clock Hybrid):
**On local event or send (Tick):**
```
l' = l # save previous logical time
l = max(l, physical_clock()) # advance to at least physical time
if l == l':
c = c + 1 # same physical time, increment counter
else:
c = 0 # new physical time, reset counter
return (l, node_id, c)
```
**On receive (Receive):**
```
l' = l
l = max(l', m_l, physical_clock())
if l == l' == m_l:
c = max(c, m_c) + 1 # all equal, take max counter + 1
elif l == l':
c = c + 1 # local was max, increment local counter
elif l == m_l:
c = m_c + 1 # remote was max, take remote counter + 1
else:
c = 0 # physical clock advanced, reset
return (l, node_id, c)
```
Memory: `HlcTimestamp` is a value type (struct) with minimal allocation.
## References
- [Logical Physical Clocks and Consistent Snapshots](https://cse.buffalo.edu/tech-reports/2014-04.pdf) - Original HLC paper
- [Time, Clocks, and the Ordering of Events](https://lamport.azurewebsites.net/pubs/time-clocks.pdf) - Lamport clocks
## License
AGPL-3.0-or-later
- [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

11
src/__Libraries/StellaOps.HybridLogicalClock/StellaOps.HybridLogicalClock.csproj
View File

@@ -4,18 +4,15 @@
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<LangVersion>preview</LangVersion>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<Description>Hybrid Logical Clock (HLC) implementation for deterministic, monotonic job ordering across distributed nodes.</Description>
<Description>Hybrid Logical Clock library for deterministic, monotonic job ordering across distributed nodes</Description>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
<PackageReference Include="Microsoft.Extensions.Options" />
<PackageReference Include="Microsoft.Extensions.Options.DataAnnotations" />
<PackageReference Include="Npgsql" />
<PackageReference Include="Dapper" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
<PackageReference Include="Npgsql" />
</ItemGroup>
</Project>