Code-review 2026-05-20 sweep #2: re-review at a020350, resolve 48 findings

Second re-review pass at commit a020350 caught 48 new findings — including
one High-severity regression I introduced in the prior sweep — and fixed
them all in one parallel wave.

High (1)
- Client.Python-018: prior sweep set `license = "Proprietary"` in
  pyproject.toml. setuptools >= 77 enforces PEP 639 and rejects the
  string (it must be a valid SPDX expression), so `pip wheel .` and
  `pip install -e .` both fail before any source compiles. Tests
  still pass because pytest bypasses the build backend via
  `pythonpath`. Dropped the invalid license string, kept the
  `License :: Other/Proprietary License` classifier, and added
  `tests/test_packaging.py` so a future regression of the same shape
  is caught in CI.

Mediums (6)
- Worker-023: `HeartbeatStuckCeiling` (default 75s = 5x HeartbeatGrace)
  on WorkerPipeSessionOptions bounds the in-flight-command watchdog
  suppression so a truly stuck COM call still triggers StaHung
  instead of permanently defeating the watchdog.
- Client.Rust-018: reverted Rust's `latencyMs` split so the
  cross-language bench comparison is apples-to-apples again;
  `failureLatencyMs` kept as Rust-only enrichment.
- Client.Java-021: applied Client.Java-002's terminal-state
  serialisation pattern to DeployEventStream so close() arriving
  after queue-overflow can't erase the overflow exception.
- IntegrationTests-017: teardown-parity test now uses a two-window
  stability check after UnAdvise instead of strict equality against
  the pre-UnAdvise count (which raced against in-flight events).
- IntegrationTests-019: new RecordingTestOutputHelper wraps every
  log sink the WriteSecured live test owns (worker stdout/stderr,
  gateway logs, direct WriteLine) so the credential is proven
  absent from the full output buffer, not just the diagnostic
  message.
- Tests-020: added MxAccessGatewayServiceConstraintTests coverage
  for the previously-uncovered Write2Bulk and WriteSecured2Bulk
  arms of WriteBulkConstraintPlan.SetPayload.

Lows (41 — highlights)
- Server: Galaxy glob cache eviction is race-free (Server-024);
  GalaxyRepositoryGrpcService takes IGalaxyRepository (Server-025);
  AlarmsOptions validated at startup (Server-026); Authorization.md
  Constraint Enforcement snippet/prose enumerate the bulk write/read
  family (Server-027); bulk-read-commands and bulk-write-commands
  capability tokens added to OpenSession (Server-029);
  NotWiredAlarmRpcDispatcher XML doc and missing scope-resolver and
  state-machine tests cleaned up (023, 028).
- Worker: AlarmCommandHandler now invokes the same STA-affinity
  guard the poll path uses, at every command entry (Worker-024);
  RunAsync null-checks the runtime-session factory result
  (Worker-025).
- Worker.Tests: shared LiveMxAccessOptInVariableName lives on
  GatewayContractInfo (Worker.Tests-025); MxAccessSession.CreateForTesting
  rejects production sinks (Worker.Tests-026); FakeRuntimeSession's
  CancelCommandReturnValue serialised under lock (Worker.Tests-027);
  Probes namespace lifted to MxGateway.Worker.Tests.Probes
  (Worker.Tests-029); cancel-envelope sequence numbers monotonised
  (Worker.Tests-030); docs/GatewayTesting.md gains a "Dev-rig Probes"
  section (Worker.Tests-028).
- Tests: ManualTimeProvider consolidated into one TestSupport/ copy
  (Tests-021); SessionManagerBulkTests adds a mid-flight cancellation
  test backed by a TaskCompletionSource fake (Tests-022); companion
  FakeWorkerProcess.WaitForExitAsync no longer fakes its exit signal
  (Tests-023); constraint plan reply-count divergence pinned
  (Tests-024).
- IntegrationTests: TryGetSession chain carries [MaybeNullWhen(false)]
  end-to-end (IntegrationTests-018); abnormal-exit keyword set
  tightened to pipe-disconnected/end-of-stream and the test now
  asserts streamTask.IsFaulted (020, 021).
- Client.Dotnet: bench commands added to isLongRunning so the
  default 30s wall-clock budget doesn't kill them (015);
  BenchStreamEventsAsync observes the inner stream task on every
  exit path (016).
- Client.Go: parseValue wraps strconv errors with flag context and
  %w (017); bench loops honour ctx.Done() (018); galaxy-watch parses
  RFC3339Nano with fractional seconds (019); runStreamEvents installs
  signal.NotifyContext like runGalaxyWatch (020); five new CLI-level
  table-driven tests cover the bulk/bench subcommands (021).
- Client.Java: toCompletable Javadoc rewritten to match the actual
  cancellation contract Client.Java-015 established (022); stream-events
  text path uses Long.toUnsignedString for worker_sequence (023);
  bench-read-bulk no longer pollutes success-latency histogram with
  failure durations (024); --shutdown-timeout CLI option propagates
  through to ClientOptions (025); seven new MxGatewayCliTests cover
  the bulk and bench commands (026).
- Client.Python: mxgateway_cli ships its own py.typed marker (019);
  wheel-build smoke test added under tests/test_packaging.py (020);
  README documents the Galaxy CLI parity gap explicitly (021).
- Client.Rust: RustClientDesign.md signatures match session.rs and
  document the AsRef<str> read_bulk genericism (019);
  next_correlation_id re-exported at the crate root, with a
  property-style doc contract and an explicit disclaimer that the
  literal textual format is not part of the contract (020).
- Contracts: BulkWriteResult comment names the actual
  IConstraintEnforcer mechanism instead of "tag-allowlist filter"
  (014); BulkReadResult gains explicit per-arm payload-population
  documentation for the success vs failure cases (015).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-05-20 10:28:54 -04:00
parent a0203503a7
commit 1aafd6bde4
74 changed files with 3349 additions and 395 deletions
@@ -857,6 +857,10 @@ public final class MxGatewayCli implements Callable<Integer> {
try {
List<BulkReadResult> results = session.readBulk(serverHandle, tags, timeoutMs);
long elapsed = System.nanoTime() - callStart;
// Only record successful-call latencies — including failed-call
// durations would pollute the p50/p95/p99 percentile summary
// (Client.Java-024, mirrors Client.Rust-015). The cross-language
// bench matrix expects success-only latency histograms.
if (latencyCount >= latenciesNanos.length) {
long[] grown = new long[latenciesNanos.length * 2];
System.arraycopy(latenciesNanos, 0, grown, 0, latencyCount);
@@ -871,13 +875,9 @@ public final class MxGatewayCli implements Callable<Integer> {
}
}
} catch (Exception ex) {
long elapsed = System.nanoTime() - callStart;
if (latencyCount >= latenciesNanos.length) {
long[] grown = new long[latenciesNanos.length * 2];
System.arraycopy(latenciesNanos, 0, grown, 0, latencyCount);
latenciesNanos = grown;
}
latenciesNanos[latencyCount++] = elapsed;
// Failed-call duration is intentionally NOT recorded into
// the success-latency histogram — only count the failure so
// the failedCalls JSON field reflects it.
failed++;
}
}
@@ -1051,7 +1051,13 @@ public final class MxGatewayCli implements Callable<Integer> {
if (json) {
client.out().println(protoJson(event));
} else {
client.out().printf("%d %s%n", event.getWorkerSequence(), event.getFamily());
// worker_sequence is a proto uint64 — print as unsigned so
// values past 2^63 do not render as negative signed longs.
// JSON path goes through JsonFormat which already does this.
client.out().printf(
"%s %s%n",
Long.toUnsignedString(event.getWorkerSequence()),
event.getFamily());
}
count++;
if (limit > 0 && count >= limit) {
@@ -1134,6 +1140,12 @@ public final class MxGatewayCli implements Callable<Integer> {
@Option(names = "--timeout", defaultValue = "30s", description = "Per-call timeout.")
String timeout;
@Option(
names = "--shutdown-timeout",
description =
"Channel shutdown timeout (e.g. 10s, 500ms). When unset, the library default applies.")
String shutdownTimeout;
/**
* Returns this options object unchanged.
*
@@ -1173,15 +1185,35 @@ public final class MxGatewayCli implements Callable<Integer> {
return parseDuration(timeout);
}
/**
* Resolves the effective channel-shutdown timeout from the
* {@code --shutdown-timeout} option, or {@code null} when the user did
* not pass one (in which case the {@link MxGatewayClientOptions}
* default applies). Computed on each call so there is no stale cached
* state.
*
* @return the resolved shutdown timeout, or {@code null} when unset
*/
Duration resolvedShutdownTimeout() {
if (shutdownTimeout == null || shutdownTimeout.isBlank()) {
return null;
}
return parseDuration(shutdownTimeout);
}
MxGatewayClientOptions toClientOptions() {
return MxGatewayClientOptions.builder()
MxGatewayClientOptions.Builder builder = MxGatewayClientOptions.builder()
.endpoint(endpoint)
.apiKey(resolvedApiKey())
.plaintext(plaintext)
.caCertificatePath(caFile)
.serverNameOverride(serverNameOverride)
.callTimeout(resolvedTimeout())
.build();
.callTimeout(resolvedTimeout());
Duration resolvedShutdownTimeout = resolvedShutdownTimeout();
if (resolvedShutdownTimeout != null) {
builder.shutdownTimeout(resolvedShutdownTimeout);
}
return builder.build();
}
Map<String, Object> redactedJsonMap() {
@@ -1193,6 +1225,8 @@ public final class MxGatewayCli implements Callable<Integer> {
values.put("caFile", caFile == null ? "" : caFile.toString());
values.put("serverNameOverride", serverNameOverride);
values.put("timeout", timeout);
Duration resolvedShutdownTimeout = resolvedShutdownTimeout();
values.put("shutdownTimeout", resolvedShutdownTimeout == null ? "" : resolvedShutdownTimeout.toString());
return values;
}
}
@@ -149,6 +149,21 @@ final class MxGatewayCliTests {
assertFalse(text.contains("seq=-1"), "must not render as signed -1");
}
@Test
void streamEventsWorkerSequenceRendersAsUnsignedForHighUint64() {
// Client.Java-023 regression: stream-events text output now uses
// Long.toUnsignedString to format the proto uint64 worker_sequence
// field, mirroring the Client.Java-020 fix for DeployEvent.sequence.
long highUnsigned = -1L; // bit-pattern for 2^64 - 1, i.e. 18446744073709551615 unsigned
String text = String.format(
"%s %s",
Long.toUnsignedString(highUnsigned),
"MX_EVENT_FAMILY_DATA_CHANGE");
assertTrue(text.startsWith("18446744073709551615 "), "expected unsigned rendering, got: " + text);
assertFalse(text.startsWith("-1 "), "must not render as signed -1");
}
@Test
void unsubscribeBulkCommandPrintsResults() {
CliRun run = execute(
@@ -168,6 +183,209 @@ final class MxGatewayCliTests {
assertTrue(run.output().contains("\"wasSuccessful\":true"));
}
// ---- Client.Java-026: CLI-level coverage for bulk subcommands ----
@Test
void readBulkCommandForwardsTimeoutAndPrintsResults() {
FakeClientFactory factory = new FakeClientFactory();
CliRun run = execute(
factory,
"read-bulk",
"--session-id",
"session-cli",
"--server-handle",
"42",
"--items",
"TestMachine_001.TestChangingInt,TestMachine_002.TestChangingInt",
"--timeout-ms",
"750",
"--json");
assertEquals(0, run.exitCode());
assertEquals(750, factory.client.session.lastReadBulkTimeoutMs);
assertEquals(2, factory.client.session.lastReadBulkItems.size());
assertTrue(run.output().contains("\"command\":\"read-bulk\""));
assertTrue(run.output().contains("\"tagAddress\":\"TestMachine_001.TestChangingInt\""));
assertTrue(run.output().contains("\"itemHandle\":200"));
assertTrue(run.output().contains("\"wasCached\":true"));
assertTrue(run.output().contains("\"quality\":192"));
}
@Test
void writeBulkCommandParsesTypedValuesAndPrintsResults() {
FakeClientFactory factory = new FakeClientFactory();
CliRun run = execute(
factory,
"write-bulk",
"--session-id",
"session-cli",
"--server-handle",
"42",
"--item-handles",
"100,101",
"--type",
"int32",
"--values",
"111,222",
"--user-id",
"5",
"--json");
assertEquals(0, run.exitCode());
assertEquals(2, factory.client.session.lastWriteBulkEntries.size());
assertEquals(111, factory.client.session.lastWriteBulkEntries.get(0).getValue().getInt32Value());
assertEquals(222, factory.client.session.lastWriteBulkEntries.get(1).getValue().getInt32Value());
assertEquals(5, factory.client.session.lastWriteBulkEntries.get(0).getUserId());
assertTrue(run.output().contains("\"command\":\"write-bulk\""));
assertTrue(run.output().contains("\"itemHandle\":100"));
assertTrue(run.output().contains("\"wasSuccessful\":true"));
}
@Test
void write2BulkCommandForwardsTimestampAndPrintsResults() {
FakeClientFactory factory = new FakeClientFactory();
CliRun run = execute(
factory,
"write2-bulk",
"--session-id",
"session-cli",
"--server-handle",
"42",
"--item-handles",
"100",
"--type",
"string",
"--values",
"hello",
"--timestamp",
"2026-05-20T00:00:00Z",
"--json");
assertEquals(0, run.exitCode());
assertEquals(1, factory.client.session.lastWrite2BulkEntries.size());
assertEquals(
"hello",
factory.client.session.lastWrite2BulkEntries.get(0).getValue().getStringValue());
assertTrue(
factory.client.session.lastWrite2BulkEntries.get(0).hasTimestampValue(),
"expected timestampValue to be forwarded");
assertTrue(run.output().contains("\"command\":\"write2-bulk\""));
assertTrue(run.output().contains("\"itemHandle\":100"));
assertTrue(run.output().contains("\"wasSuccessful\":true"));
}
@Test
void writeSecuredBulkCommandForwardsUserIdsAndPrintsResults() {
FakeClientFactory factory = new FakeClientFactory();
CliRun run = execute(
factory,
"write-secured-bulk",
"--session-id",
"session-cli",
"--server-handle",
"42",
"--item-handles",
"100",
"--type",
"int32",
"--values",
"9",
"--current-user-id",
"7",
"--verifier-user-id",
"8",
"--json");
assertEquals(0, run.exitCode());
assertEquals(1, factory.client.session.lastWriteSecuredBulkEntries.size());
assertEquals(7, factory.client.session.lastWriteSecuredBulkEntries.get(0).getCurrentUserId());
assertEquals(8, factory.client.session.lastWriteSecuredBulkEntries.get(0).getVerifierUserId());
assertEquals(9, factory.client.session.lastWriteSecuredBulkEntries.get(0).getValue().getInt32Value());
assertTrue(run.output().contains("\"command\":\"write-secured-bulk\""));
assertTrue(run.output().contains("\"wasSuccessful\":true"));
}
@Test
void writeSecured2BulkCommandForwardsTimestampAndUserIdsAndPrintsResults() {
FakeClientFactory factory = new FakeClientFactory();
CliRun run = execute(
factory,
"write-secured2-bulk",
"--session-id",
"session-cli",
"--server-handle",
"42",
"--item-handles",
"100",
"--type",
"string",
"--values",
"value",
"--timestamp",
"2026-05-20T00:00:00Z",
"--current-user-id",
"7",
"--verifier-user-id",
"8",
"--json");
assertEquals(0, run.exitCode());
assertEquals(1, factory.client.session.lastWriteSecured2BulkEntries.size());
assertEquals(7, factory.client.session.lastWriteSecured2BulkEntries.get(0).getCurrentUserId());
assertEquals(8, factory.client.session.lastWriteSecured2BulkEntries.get(0).getVerifierUserId());
assertTrue(
factory.client.session.lastWriteSecured2BulkEntries.get(0).hasTimestampValue(),
"expected timestampValue to be forwarded");
assertTrue(run.output().contains("\"command\":\"write-secured2-bulk\""));
assertTrue(run.output().contains("\"wasSuccessful\":true"));
}
@Test
void benchReadBulkCommandEmitsJsonSchemaKeys() {
// Short bench window (1 s steady, 0 s warmup) keeps the test fast; we assert
// the JSON schema rather than numeric values so the cross-language matrix
// (.NET / Go / Rust / Python) and the Java path agree on the output shape.
FakeClientFactory factory = new FakeClientFactory();
CliRun run = execute(
factory,
"bench-read-bulk",
"--duration-seconds",
"1",
"--warmup-seconds",
"0",
"--bulk-size",
"2",
"--tag-start",
"1",
"--tag-prefix",
"TestMachine_",
"--tag-attribute",
"TestChangingInt",
"--timeout-ms",
"100",
"--json");
assertEquals(0, run.exitCode());
String output = run.output();
assertTrue(output.contains("\"language\":\"java\""), output);
assertTrue(output.contains("\"command\":\"bench-read-bulk\""), output);
assertTrue(output.contains("\"bulkSize\":2"), output);
assertTrue(output.contains("\"durationSeconds\":1"), output);
assertTrue(output.contains("\"warmupSeconds\":0"), output);
assertTrue(output.contains("\"totalCalls\":"), output);
assertTrue(output.contains("\"successfulCalls\":"), output);
assertTrue(output.contains("\"failedCalls\":"), output);
assertTrue(output.contains("\"callsPerSecond\":"), output);
assertTrue(output.contains("\"latencyMs\":"), output);
assertTrue(output.contains("\"p50\":"), output);
assertTrue(output.contains("\"p95\":"), output);
assertTrue(output.contains("\"p99\":"), output);
assertTrue(output.contains("\"tags\":"), output);
// Bench tag synthesis: TestMachine_001.TestChangingInt, TestMachine_002.TestChangingInt.
assertTrue(output.contains("TestMachine_001.TestChangingInt"), output);
assertTrue(output.contains("TestMachine_002.TestChangingInt"), output);
}
private static CliRun execute(MxGatewayCli.MxGatewayCliClientFactory factory, String... args) {
StringWriter output = new StringWriter();
StringWriter errors = new StringWriter();
@@ -322,29 +540,89 @@ final class MxGatewayCliTests {
return results;
}
// Recorded so tests can assert the CLI forwarded the parsed options through to
// the session interface. The bulk subcommands return at least one result so the
// JSON output assertions exercise the *Map serialisers in MxGatewayCli.
private int lastReadBulkTimeoutMs;
private List<String> lastReadBulkItems = new ArrayList<>();
private List<WriteBulkEntry> lastWriteBulkEntries = new ArrayList<>();
private List<Write2BulkEntry> lastWrite2BulkEntries = new ArrayList<>();
private List<WriteSecuredBulkEntry> lastWriteSecuredBulkEntries = new ArrayList<>();
private List<WriteSecured2BulkEntry> lastWriteSecured2BulkEntries = new ArrayList<>();
@Override
public List<BulkReadResult> readBulk(int serverHandle, List<String> items, int timeoutMs) {
return new ArrayList<>();
lastReadBulkTimeoutMs = timeoutMs;
lastReadBulkItems = items;
List<BulkReadResult> results = new ArrayList<>();
for (int index = 0; index < items.size(); index++) {
results.add(BulkReadResult.newBuilder()
.setServerHandle(serverHandle)
.setTagAddress(items.get(index))
.setItemHandle(200 + index)
.setWasSuccessful(true)
.setWasCached(index % 2 == 0)
.setQuality(192)
.build());
}
return results;
}
@Override
public List<BulkWriteResult> writeBulk(int serverHandle, List<WriteBulkEntry> entries) {
return new ArrayList<>();
lastWriteBulkEntries = entries;
List<BulkWriteResult> results = new ArrayList<>();
for (WriteBulkEntry entry : entries) {
results.add(BulkWriteResult.newBuilder()
.setServerHandle(serverHandle)
.setItemHandle(entry.getItemHandle())
.setWasSuccessful(true)
.build());
}
return results;
}
@Override
public List<BulkWriteResult> write2Bulk(int serverHandle, List<Write2BulkEntry> entries) {
return new ArrayList<>();
lastWrite2BulkEntries = entries;
List<BulkWriteResult> results = new ArrayList<>();
for (Write2BulkEntry entry : entries) {
results.add(BulkWriteResult.newBuilder()
.setServerHandle(serverHandle)
.setItemHandle(entry.getItemHandle())
.setWasSuccessful(true)
.build());
}
return results;
}
@Override
public List<BulkWriteResult> writeSecuredBulk(int serverHandle, List<WriteSecuredBulkEntry> entries) {
return new ArrayList<>();
lastWriteSecuredBulkEntries = entries;
List<BulkWriteResult> results = new ArrayList<>();
for (WriteSecuredBulkEntry entry : entries) {
results.add(BulkWriteResult.newBuilder()
.setServerHandle(serverHandle)
.setItemHandle(entry.getItemHandle())
.setWasSuccessful(true)
.build());
}
return results;
}
@Override
public List<BulkWriteResult> writeSecured2Bulk(int serverHandle, List<WriteSecured2BulkEntry> entries) {
return new ArrayList<>();
lastWriteSecured2BulkEntries = entries;
List<BulkWriteResult> results = new ArrayList<>();
for (WriteSecured2BulkEntry entry : entries) {
results.add(BulkWriteResult.newBuilder()
.setServerHandle(serverHandle)
.setItemHandle(entry.getItemHandle())
.setWasSuccessful(true)
.build());
}
return results;
}
@Override