feat(server): add MxGateway:Sessions:WorkerReadyWaitTimeoutMs (default off)

Adds WorkerReadyWaitTimeoutMs to SessionOptions (default 0 = disabled), validates >= 0 in GatewayOptionsValidator, documents it in GatewayConfiguration.md, and adds validator + default-value tests. No wait/poll logic is implemented here (that is Task 8).
2026-06-16 16:38:31 -04:00
parent 1cfad83c06
commit ea17528767
5 changed files with 57 additions and 1 deletions
@@ -185,6 +185,10 @@ public sealed class GatewayOptionsValidator : OptionsValidatorBase<GatewayOption
            options.DetachGraceSeconds,
            "MxGateway:Sessions:DetachGraceSeconds must be zero or greater (0 disables detach-grace retention).",
            builder);
+        AddIfNegative(
+            options.WorkerReadyWaitTimeoutMs,
+            "MxGateway:Sessions:WorkerReadyWaitTimeoutMs must be greater than or equal to zero.",
+            builder);

        // NOTE: We intentionally do NOT reject !AllowMultipleEventSubscribers &&
        // MaxEventSubscribersPerSession > 1 as a hard validation error here. The default
@@ -56,4 +56,15 @@ public sealed class SessionOptions
    /// effectively 1 when it is <see langword="false"/>. Must be greater than zero.
    /// </summary>
    public int MaxEventSubscribersPerSession { get; init; } = 8;
+
+    /// <summary>
+    ///     Gets the bounded time, in milliseconds, the gateway will wait for a worker client
+    ///     to reach <c>Ready</c> when the session itself is already <c>Ready</c> but the worker
+    ///     state has transiently diverged (e.g. <c>Handshaking</c> after a heartbeat blip).
+    ///     The wait applies only to transient worker states; terminal states
+    ///     (<c>Faulted</c>/<c>Closing</c>/<c>Closed</c>/no worker) fail fast immediately.
+    ///     A value of <c>0</c> (the default) disables the wait — the gateway keeps the original
+    ///     fail-fast behavior. Must be greater than or equal to zero.
+    /// </summary>
+    public int WorkerReadyWaitTimeoutMs { get; init; }
 }