Issue #3: add gateway configuration and validation

2026-04-26 16:11:30 -04:00
parent 16c18954b6
commit 91ea71b0b7
26 changed files with 657 additions and 1 deletions
@@ -0,0 +1,7 @@
+namespace MxGateway.Server.Configuration;
+
+public enum AuthenticationMode
+{
+    ApiKey,
+    Disabled
+}
@@ -0,0 +1,12 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class AuthenticationOptions
+{
+    public AuthenticationMode Mode { get; init; } = AuthenticationMode.ApiKey;
+
+    public string SqlitePath { get; init; } = @"C:\ProgramData\MxGateway\gateway-auth.db";
+
+    public string PepperSecretName { get; init; } = "MxGateway:ApiKeyPepper";
+
+    public bool RunMigrationsOnStartup { get; init; } = true;
+}
@@ -0,0 +1,20 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class DashboardOptions
+{
+    public bool Enabled { get; init; } = true;
+
+    public string PathBase { get; init; } = "/dashboard";
+
+    public bool RequireAdminScope { get; init; } = true;
+
+    public bool AllowAnonymousLocalhost { get; init; }
+
+    public int SnapshotIntervalMilliseconds { get; init; } = 1_000;
+
+    public int RecentFaultLimit { get; init; } = 100;
+
+    public int RecentSessionLimit { get; init; } = 200;
+
+    public bool ShowTagValues { get; init; }
+}
@@ -0,0 +1,7 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveAuthenticationConfiguration(
+    string Mode,
+    string SqlitePath,
+    string PepperSecretName,
+    bool RunMigrationsOnStartup);
@@ -0,0 +1,11 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveDashboardConfiguration(
+    bool Enabled,
+    string PathBase,
+    bool RequireAdminScope,
+    bool AllowAnonymousLocalhost,
+    int SnapshotIntervalMilliseconds,
+    int RecentFaultLimit,
+    int RecentSessionLimit,
+    bool ShowTagValues);
@@ -0,0 +1,5 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveEventConfiguration(
+    int QueueCapacity,
+    string BackpressurePolicy);
@@ -0,0 +1,9 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveGatewayConfiguration(
+    EffectiveAuthenticationConfiguration Authentication,
+    EffectiveWorkerConfiguration Worker,
+    EffectiveSessionConfiguration Sessions,
+    EffectiveEventConfiguration Events,
+    EffectiveDashboardConfiguration Dashboard,
+    EffectiveProtocolConfiguration Protocol);
@@ -0,0 +1,3 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveProtocolConfiguration(uint WorkerProtocolVersion);
@@ -0,0 +1,6 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveSessionConfiguration(
+    int DefaultCommandTimeoutSeconds,
+    int MaxSessions,
+    bool AllowMultipleEventSubscribers);
@@ -0,0 +1,11 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed record EffectiveWorkerConfiguration(
+    string ExecutablePath,
+    string? WorkingDirectory,
+    string RequiredArchitecture,
+    int StartupTimeoutSeconds,
+    int ShutdownTimeoutSeconds,
+    int HeartbeatIntervalSeconds,
+    int HeartbeatGraceSeconds,
+    int MaxMessageBytes);
@@ -0,0 +1,6 @@
+namespace MxGateway.Server.Configuration;
+
+public enum EventBackpressurePolicy
+{
+    FailFast
+}
@@ -0,0 +1,8 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class EventOptions
+{
+    public int QueueCapacity { get; init; } = 10_000;
+
+    public EventBackpressurePolicy BackpressurePolicy { get; init; } = EventBackpressurePolicy.FailFast;
+}
@@ -0,0 +1,46 @@
+using Microsoft.Extensions.Options;
+
+namespace MxGateway.Server.Configuration;
+
+public sealed class GatewayConfigurationProvider(IOptions<GatewayOptions> options) : IGatewayConfigurationProvider
+{
+    public const string RedactedValue = "[redacted]";
+
+    public EffectiveGatewayConfiguration GetEffectiveConfiguration()
+    {
+        GatewayOptions value = options.Value;
+
+        return new EffectiveGatewayConfiguration(
+            Authentication: new EffectiveAuthenticationConfiguration(
+                Mode: value.Authentication.Mode.ToString(),
+                SqlitePath: value.Authentication.SqlitePath,
+                PepperSecretName: RedactedValue,
+                RunMigrationsOnStartup: value.Authentication.RunMigrationsOnStartup),
+            Worker: new EffectiveWorkerConfiguration(
+                ExecutablePath: value.Worker.ExecutablePath,
+                WorkingDirectory: value.Worker.WorkingDirectory,
+                RequiredArchitecture: value.Worker.RequiredArchitecture.ToString(),
+                StartupTimeoutSeconds: value.Worker.StartupTimeoutSeconds,
+                ShutdownTimeoutSeconds: value.Worker.ShutdownTimeoutSeconds,
+                HeartbeatIntervalSeconds: value.Worker.HeartbeatIntervalSeconds,
+                HeartbeatGraceSeconds: value.Worker.HeartbeatGraceSeconds,
+                MaxMessageBytes: value.Worker.MaxMessageBytes),
+            Sessions: new EffectiveSessionConfiguration(
+                DefaultCommandTimeoutSeconds: value.Sessions.DefaultCommandTimeoutSeconds,
+                MaxSessions: value.Sessions.MaxSessions,
+                AllowMultipleEventSubscribers: value.Sessions.AllowMultipleEventSubscribers),
+            Events: new EffectiveEventConfiguration(
+                QueueCapacity: value.Events.QueueCapacity,
+                BackpressurePolicy: value.Events.BackpressurePolicy.ToString()),
+            Dashboard: new EffectiveDashboardConfiguration(
+                Enabled: value.Dashboard.Enabled,
+                PathBase: value.Dashboard.PathBase,
+                RequireAdminScope: value.Dashboard.RequireAdminScope,
+                AllowAnonymousLocalhost: value.Dashboard.AllowAnonymousLocalhost,
+                SnapshotIntervalMilliseconds: value.Dashboard.SnapshotIntervalMilliseconds,
+                RecentFaultLimit: value.Dashboard.RecentFaultLimit,
+                RecentSessionLimit: value.Dashboard.RecentSessionLimit,
+                ShowTagValues: value.Dashboard.ShowTagValues),
+            Protocol: new EffectiveProtocolConfiguration(value.Protocol.WorkerProtocolVersion));
+    }
+}
@@ -0,0 +1,19 @@
+using Microsoft.Extensions.Options;
+
+namespace MxGateway.Server.Configuration;
+
+public static class GatewayConfigurationServiceCollectionExtensions
+{
+    public static IServiceCollection AddGatewayConfiguration(this IServiceCollection services)
+    {
+        services
+            .AddOptions<GatewayOptions>()
+            .BindConfiguration(GatewayOptions.SectionName)
+            .ValidateOnStart();
+
+        services.AddSingleton<IValidateOptions<GatewayOptions>, GatewayOptionsValidator>();
+        services.AddSingleton<IGatewayConfigurationProvider, GatewayConfigurationProvider>();
+
+        return services;
+    }
+}
@@ -0,0 +1,18 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class GatewayOptions
+{
+    public const string SectionName = "MxGateway";
+
+    public AuthenticationOptions Authentication { get; init; } = new();
+
+    public WorkerOptions Worker { get; init; } = new();
+
+    public SessionOptions Sessions { get; init; } = new();
+
+    public EventOptions Events { get; init; } = new();
+
+    public DashboardOptions Dashboard { get; init; } = new();
+
+    public ProtocolOptions Protocol { get; init; } = new();
+}
@@ -0,0 +1,210 @@
+using Microsoft.Extensions.Options;
+using MxGateway.Contracts;
+
+namespace MxGateway.Server.Configuration;
+
+public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
+{
+    private const int MinimumMaxMessageBytes = 1024;
+    private const int MaximumMaxMessageBytes = 256 * 1024 * 1024;
+
+    public ValidateOptionsResult Validate(string? name, GatewayOptions options)
+    {
+        List<string> failures = [];
+
+        ValidateAuthentication(options.Authentication, failures);
+        ValidateWorker(options.Worker, failures);
+        ValidateSessions(options.Sessions, failures);
+        ValidateEvents(options.Events, failures);
+        ValidateDashboard(options.Dashboard, failures);
+        ValidateProtocol(options.Protocol, failures);
+
+        return failures.Count == 0
+            ? ValidateOptionsResult.Success
+            : ValidateOptionsResult.Fail(failures);
+    }
+
+    private static void ValidateAuthentication(AuthenticationOptions options, List<string> failures)
+    {
+        if (!Enum.IsDefined(options.Mode))
+        {
+            failures.Add("MxGateway:Authentication:Mode must be a supported authentication mode.");
+            return;
+        }
+
+        if (options.Mode == AuthenticationMode.ApiKey)
+        {
+            AddIfBlank(
+                options.SqlitePath,
+                "MxGateway:Authentication:SqlitePath is required when API-key authentication is enabled.",
+                failures);
+            AddIfInvalidPath(
+                options.SqlitePath,
+                "MxGateway:Authentication:SqlitePath must be a valid filesystem path.",
+                failures);
+            AddIfBlank(
+                options.PepperSecretName,
+                "MxGateway:Authentication:PepperSecretName is required when API-key authentication is enabled.",
+                failures);
+        }
+    }
+
+    private static void ValidateWorker(WorkerOptions options, List<string> failures)
+    {
+        AddIfBlank(options.ExecutablePath, "MxGateway:Worker:ExecutablePath is required.", failures);
+        AddIfInvalidPath(
+            options.ExecutablePath,
+            "MxGateway:Worker:ExecutablePath must be a valid filesystem path.",
+            failures);
+
+        if (!string.IsNullOrWhiteSpace(options.ExecutablePath)
+            && !string.Equals(Path.GetExtension(options.ExecutablePath), ".exe", StringComparison.OrdinalIgnoreCase))
+        {
+            failures.Add("MxGateway:Worker:ExecutablePath must point to a .exe file.");
+        }
+
+        if (!string.IsNullOrWhiteSpace(options.WorkingDirectory))
+        {
+            AddIfInvalidPath(
+                options.WorkingDirectory,
+                "MxGateway:Worker:WorkingDirectory must be a valid filesystem path.",
+                failures);
+        }
+
+        if (!Enum.IsDefined(options.RequiredArchitecture))
+        {
+            failures.Add("MxGateway:Worker:RequiredArchitecture must be a supported worker architecture.");
+        }
+
+        AddIfNotPositive(
+            options.StartupTimeoutSeconds,
+            "MxGateway:Worker:StartupTimeoutSeconds must be greater than zero.",
+            failures);
+        AddIfNotPositive(
+            options.ShutdownTimeoutSeconds,
+            "MxGateway:Worker:ShutdownTimeoutSeconds must be greater than zero.",
+            failures);
+        AddIfNotPositive(
+            options.HeartbeatIntervalSeconds,
+            "MxGateway:Worker:HeartbeatIntervalSeconds must be greater than zero.",
+            failures);
+        AddIfNotPositive(
+            options.HeartbeatGraceSeconds,
+            "MxGateway:Worker:HeartbeatGraceSeconds must be greater than zero.",
+            failures);
+
+        if (options.HeartbeatGraceSeconds < options.HeartbeatIntervalSeconds)
+        {
+            failures.Add(
+                "MxGateway:Worker:HeartbeatGraceSeconds must be greater than or equal to HeartbeatIntervalSeconds.");
+        }
+
+        if (options.MaxMessageBytes is < MinimumMaxMessageBytes or > MaximumMaxMessageBytes)
+        {
+            failures.Add(
+                $"MxGateway:Worker:MaxMessageBytes must be between {MinimumMaxMessageBytes} and {MaximumMaxMessageBytes}.");
+        }
+    }
+
+    private static void ValidateSessions(SessionOptions options, List<string> failures)
+    {
+        AddIfNotPositive(
+            options.DefaultCommandTimeoutSeconds,
+            "MxGateway:Sessions:DefaultCommandTimeoutSeconds must be greater than zero.",
+            failures);
+        AddIfNotPositive(options.MaxSessions, "MxGateway:Sessions:MaxSessions must be greater than zero.", failures);
+    }
+
+    private static void ValidateEvents(EventOptions options, List<string> failures)
+    {
+        AddIfNotPositive(options.QueueCapacity, "MxGateway:Events:QueueCapacity must be greater than zero.", failures);
+
+        if (!Enum.IsDefined(options.BackpressurePolicy))
+        {
+            failures.Add("MxGateway:Events:BackpressurePolicy must be a supported backpressure policy.");
+        }
+    }
+
+    private static void ValidateDashboard(DashboardOptions options, List<string> failures)
+    {
+        if (options.Enabled)
+        {
+            AddIfBlank(options.PathBase, "MxGateway:Dashboard:PathBase is required when the dashboard is enabled.", failures);
+            if (!string.IsNullOrWhiteSpace(options.PathBase) && !options.PathBase.StartsWith('/'))
+            {
+                failures.Add("MxGateway:Dashboard:PathBase must start with '/'.");
+            }
+        }
+
+        AddIfNotPositive(
+            options.SnapshotIntervalMilliseconds,
+            "MxGateway:Dashboard:SnapshotIntervalMilliseconds must be greater than zero.",
+            failures);
+        AddIfNegative(
+            options.RecentFaultLimit,
+            "MxGateway:Dashboard:RecentFaultLimit must be greater than or equal to zero.",
+            failures);
+        AddIfNegative(
+            options.RecentSessionLimit,
+            "MxGateway:Dashboard:RecentSessionLimit must be greater than or equal to zero.",
+            failures);
+    }
+
+    private static void ValidateProtocol(ProtocolOptions options, List<string> failures)
+    {
+        if (options.WorkerProtocolVersion != GatewayContractInfo.WorkerProtocolVersion)
+        {
+            failures.Add(
+                $"MxGateway:Protocol:WorkerProtocolVersion must be {GatewayContractInfo.WorkerProtocolVersion}.");
+        }
+    }
+
+    private static void AddIfBlank(string? value, string message, List<string> failures)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            failures.Add(message);
+        }
+    }
+
+    private static void AddIfNotPositive(int value, string message, List<string> failures)
+    {
+        if (value <= 0)
+        {
+            failures.Add(message);
+        }
+    }
+
+    private static void AddIfNegative(int value, string message, List<string> failures)
+    {
+        if (value < 0)
+        {
+            failures.Add(message);
+        }
+    }
+
+    private static void AddIfInvalidPath(string? value, string message, List<string> failures)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return;
+        }
+
+        try
+        {
+            _ = Path.GetFullPath(value);
+        }
+        catch (ArgumentException)
+        {
+            failures.Add(message);
+        }
+        catch (NotSupportedException)
+        {
+            failures.Add(message);
+        }
+        catch (PathTooLongException)
+        {
+            failures.Add(message);
+        }
+    }
+}
@@ -0,0 +1,6 @@
+namespace MxGateway.Server.Configuration;
+
+public interface IGatewayConfigurationProvider
+{
+    EffectiveGatewayConfiguration GetEffectiveConfiguration();
+}
@@ -0,0 +1,8 @@
+using MxGateway.Contracts;
+
+namespace MxGateway.Server.Configuration;
+
+public sealed class ProtocolOptions
+{
+    public uint WorkerProtocolVersion { get; init; } = GatewayContractInfo.WorkerProtocolVersion;
+}
@@ -0,0 +1,10 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class SessionOptions
+{
+    public int DefaultCommandTimeoutSeconds { get; init; } = 30;
+
+    public int MaxSessions { get; init; } = 64;
+
+    public bool AllowMultipleEventSubscribers { get; init; }
+}
@@ -0,0 +1,7 @@
+namespace MxGateway.Server.Configuration;
+
+public enum WorkerArchitecture
+{
+    X86,
+    X64
+}
@@ -0,0 +1,21 @@
+namespace MxGateway.Server.Configuration;
+
+public sealed class WorkerOptions
+{
+    public string ExecutablePath { get; init; } =
+        @"src\MxGateway.Worker\bin\x86\Release\MxGateway.Worker.exe";
+
+    public string? WorkingDirectory { get; init; }
+
+    public WorkerArchitecture RequiredArchitecture { get; init; } = WorkerArchitecture.X86;
+
+    public int StartupTimeoutSeconds { get; init; } = 30;
+
+    public int ShutdownTimeoutSeconds { get; init; } = 10;
+
+    public int HeartbeatIntervalSeconds { get; init; } = 5;
+
+    public int HeartbeatGraceSeconds { get; init; } = 15;
+
+    public int MaxMessageBytes { get; init; } = 16 * 1024 * 1024;
+}