Code-review 2026-05-20 sweep: re-review at 1cd51bb, resolve 72 findings across all 11 modules

Re-reviewed every module/client against the 10-category checklist (REVIEW-PROCESS.md) at commit 1cd51bb, filed 72 new findings, and fixed them in three priority waves (3 High, 17 Medium, 52 Low). Highs - Server-017: enumerate AcknowledgeAlarm / QueryActiveAlarms in GatewayGrpcScopeResolver so non-admin keys can use them; document the mapping in docs/Authorization.md; add interceptor tests. - Client.Java-013: add the five missing bulk-method stubs to the CLI FakeSession so the test module compiles on a clean tree. - Client.Rust-013: fix the clippy::doc_lazy_continuation regression in generated tonic code by reformatting the ReadBulkCommand proto comment and scoping a #![allow(...)] to the generated submodules. Mediums (highlights) - Server: unify GatewaySession state-lock discipline (-015) and make DisposeAsync race-safe against in-flight CloseAsync (-016); add constraint-enforcement test coverage for the bulk-plan path (-021). - Worker: introduce StaRuntimeShutdownException so RunAlarmPollLoop can distinguish graceful shutdown from a real STA-affinity violation (-016); have the watchdog skip StaHung while CurrentCommandCorrelationId is non-empty so a legitimate slow ReadBulk no longer self-faults (-017). - Tests: add per-method round-trip + cancellation coverage for the 11 GatewaySession bulk methods (-013); replace the real TCP probe in GalaxyHierarchyCacheTests with an IGalaxyRepository fake (-016). - IntegrationTests: drive the StreamEvents writer in the live Write test and assert OnWriteComplete (-012); add live tests for Unadvise/RemoveItem/Unregister ordering, WriteSecured, and abnormal worker exit (-014). - Worker.Tests: replace MxAccessSession reflection with an internal CreateForTesting factory (-016); cover WorkerCancel and unexpected-body envelope branches (-017). - Client.Java: cancel MxEventStream when close() races beforeStart() (-014); return a CancellingCompletableFuture that actually forwards cancellation through .thenApply chains (-015). - Client.Python: drop the silent localhost-plaintext downgrade in the CLI; require explicit --plaintext (-013). - Client.Rust: stop bench-read-bulk from polluting success-latency histograms with failed-call durations (-015); add coverage for the five MalformedReply paths, the bulk-write helpers, the Error::Unavailable mapping, and the unary-fault path (-016). - Contracts: extend docs/Contracts.md with the bulk read/write command family (-009). Lows (highlights) - Server: cap GalaxyGlobMatcher.RegexCache; align WorkerAlarmRpcDispatcher missing-session handling; drop the duplicate dashboard @page routes; refresh IAlarmRpcDispatcher XML doc. - Worker: surface SetXmlAlarmQuery COM failures; remove dead subscriptionExpression / ExecutingCommand arms; preserve factory-supplied runtime sessions; split MxAlarmSnapshot.cs into three files. - Tests: dispose the WebApplication in seven test classes; rebuild FakeWorkerProcess.WaitForExitAsync against a real TaskCompletion source; switch the heartbeat-expires test to ManualTimeProvider; add InvariantCulture to the remaining DateTimeOffset.Parse sites; document GalaxyFilterInputSafetyTests in GatewayTesting.md. - IntegrationTests: comment fixes, RecordingServerStreamWriter IDisposable, class-level [Trait], single-source ZB default connection string. - Worker.Tests: replace silent-return gating with LiveMxAccessFact so absent env vars SKIP not pass; PascalCase rename of probe [Fact]s; deterministic deadline test; new frame-protocol error tests; ComputeTransitions diff-coverage; relocate dev-rig probes to Probes/. - Contracts: add round-trip coverage and per-field redaction / Galaxy-identifier comments to the protos. - Client.Dotnet: introduce clients/dotnet/Directory.Build.props so TreatWarningsAsErrors / analysers apply; document DiscoverHierarchyOptions and IMxGatewayCliClient; require typed bulk-read handles in CLI; surface AcknowledgeAlarm transport faults through Translate(). - Client.Go: kill dead code in alarms_test / fakeGalaxyServer / runWriteBulkVariant; document the six new subcommands in writeUsage; drain galaxy-watch events on limit; switch io.EOF comparisons to errors.Is. - Client.Java: shared shutdown helpers + new shutdownTimeout option; regex-based credential redaction; Long.toUnsignedString for uint64 sequence; doc fixes. - Client.Python: combine duplicate imports; add coverage for _percentile / bench-read-bulk / MAX_AGGREGATE_EVENTS / _api_key_from_env; populate pyproject metadata and ship py.typed. - Client.Rust: expose next_correlation_id() so CLI ping/close stop hard-coding correlation IDs; resync RustClientDesign.md with the current Session / Error surface and CLI subcommand set. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-20 09:46:47 -04:00
parent 1cd51bbda3
commit a0203503a7
122 changed files with 8723 additions and 757 deletions
@@ -3,6 +3,12 @@ using MxGateway.Contracts.Proto.Galaxy;

 namespace MxGateway.Client.Cli;

+/// <summary>
+/// Minimal transport surface the CLI talks to. Exposes only the gateway and
+/// Galaxy Repository RPCs the CLI needs so tests can substitute an in-process
+/// fake without standing up a real gRPC channel. The production binding is a
+/// thin adapter over <see cref="MxGatewayClient"/> and <see cref="GalaxyRepositoryClient"/>.
+/// </summary>
 public interface IMxGatewayCliClient : IAsyncDisposable
 {
    /// <summary>
@@ -635,7 +635,7 @@ public static class MxGatewayClientCli
                    }),
                    cancellationToken)
                .ConfigureAwait(false);
-            int serverHandle = registerReply.Register?.ServerHandle ?? registerReply.ReturnValue.Int32Value;
+            int serverHandle = RequireRegisterServerHandle(registerReply);

            SubscribeBulkCommand subscribe = new() { ServerHandle = serverHandle };
            subscribe.TagAddresses.Add(tags);
@@ -893,7 +893,7 @@ public static class MxGatewayClientCli
                    }),
                    cancellationToken)
                .ConfigureAwait(false);
-            int serverHandle = registerReply.Register?.ServerHandle ?? registerReply.ReturnValue.Int32Value;
+            int serverHandle = RequireRegisterServerHandle(registerReply);

            SubscribeBulkCommand subscribe = new() { ServerHandle = serverHandle };
            subscribe.TagAddresses.Add(tags);
@@ -941,11 +941,16 @@ public static class MxGatewayClientCli
                        continue;
                    }

-                    if (firstSteadyEventUtc is null)
+                    // Guarded by latencyLock so parallel sessions can't tear a 64-bit
+                    // DateTime? read or stomp an already-set firstSteadyEventUtc with
+                    // a later timestamp from a slower-to-start session. The lock is
+                    // already held by the latency append a few lines below, so the
+                    // extra cost is one uncontended lock acquisition per event.
+                    lock (latencyLock)
                    {
-                        firstSteadyEventUtc = nowUtc;
+                        firstSteadyEventUtc ??= nowUtc;
+                        lastSteadyEventUtc = nowUtc;
                    }
-                    lastSteadyEventUtc = nowUtc;
                    Interlocked.Increment(ref steadyEvents);
                    if (mxEvent.Family == MxEventFamily.OnDataChange)
                    {
@@ -1258,7 +1263,7 @@ public static class MxGatewayClientCli
                        Kind = MxCommandKind.Register,
                        Register = new RegisterCommand { ClientName = arguments.GetOptional("client-name") ?? "mxgw-dotnet-smoke" },
                    },
-                    reply => reply.Register?.ServerHandle ?? reply.ReturnValue.Int32Value,
+                    RequireRegisterServerHandle,
                    commandReplies,
                    cancellationToken)
                .ConfigureAwait(false);
@@ -1276,7 +1281,7 @@ public static class MxGatewayClientCli
                            ItemDefinition = arguments.GetRequired("item"),
                        },
                    },
-                    reply => reply.AddItem?.ItemHandle ?? reply.ReturnValue.Int32Value,
+                    RequireAddItemItemHandle,
                    commandReplies,
                    cancellationToken)
                .ConfigureAwait(false);
@@ -1408,6 +1413,41 @@ public static class MxGatewayClientCli
        return reply;
    }

+    /// <summary>
+    /// Returns the server handle from a successful <c>register</c> reply, or throws
+    /// <see cref="MxGatewayException"/> when the typed <see cref="MxCommandReply.Register"/>
+    /// payload is absent. Mirrors the SDK-level <see cref="MxGatewaySession.RegisterAsync"/>
+    /// contract: a successful reply without the typed payload is a gateway protocol
+    /// error, not a license to fall through to <c>ReturnValue.Int32Value</c> (which is 0
+    /// when the reply carries no return value).
+    /// </summary>
+    private static int RequireRegisterServerHandle(MxCommandReply reply)
+    {
+        return reply.Register?.ServerHandle
+            ?? throw CreateMissingPayloadException(reply, "register");
+    }
+
+    /// <summary>
+    /// Returns the item handle from a successful <c>add_item</c> reply, or throws
+    /// <see cref="MxGatewayException"/> when the typed <see cref="MxCommandReply.AddItem"/>
+    /// payload is absent. See <see cref="RequireRegisterServerHandle"/> for the rationale.
+    /// </summary>
+    private static int RequireAddItemItemHandle(MxCommandReply reply)
+    {
+        return reply.AddItem?.ItemHandle
+            ?? throw CreateMissingPayloadException(reply, "add_item");
+    }
+
+    private static MxGatewayException CreateMissingPayloadException(
+        MxCommandReply reply,
+        string expectedPayload)
+    {
+        return new MxGatewayException(
+            $"Gateway reply for command kind={reply.Kind} reported success but is missing "
+            + $"the required '{expectedPayload}' payload; cannot resolve a handle. "
+            + $"session={reply.SessionId}; correlation={reply.CorrelationId}");
+    }
+
    private static MxCommandRequest CreateCommandRequest(
        string sessionId,
        MxCommand command)