Commit Graph

1126 Commits

Author SHA1 Message Date
Joseph Doherty ebbfaa4c03 docs(tests): IntegrationTests-033 resolved: Write2 live smoke passed on windev (#212)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 2m2s
ci / java (push) Failing after 4m44s
ci / portable (push) Failing after 9m25s
Ran the Write2 live smoke on windev against origin/main 04a40f2c (x86 Release
worker, item TestChildObject.TestInt). It passed: Ok, hresult 0, and a matching
OnWriteComplete. MXAccess reported SecurityError/1008 on the completion, which
is the Galaxy refusing an unauthenticated write; plain Write got the same
status and the value did not change. Corrected the test comment that said the
reply meant the write succeeded.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 20:26:33 -05:00
Joseph Doherty 04a40f2c1a docs(deploy): vd03 API-key pepper moved into the service environment (#171)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m50s
ci / java (push) Failing after 4m55s
ci / portable (push) Failing after 11m17s
Record of the 2026-11-12 config-only change on wonder-app-vd03: MxGateway__ApiKeyPepper
added to the MxAccessGw AppEnvironmentExtra block (same value, sha256 prefix match),
removed from Server\appsettings.json; authenticated round-trip with a pre-change key,
ScadaBridge MxGateway link unchanged. Runbook and configuration doc now say where the
pepper lives on each wonder box.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-12 19:49:42 -05:00
Joseph Doherty 447070a532 chore(clients/dotnet): bump Contracts + Client 0.3.0 -> 0.4.0 for publish (#227)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Failing after 1m34s
ci / java (push) Failing after 2m33s
ci / portable (push) Failing after 3m39s
Ships the opt-in stream-attached acknowledgement (afd504d5) so OtOpcUa
can adopt it (lmxopcua#877). Published to the Gitea feed 2026-11-12.
2026-11-12 07:32:01 -05:00
Joseph Doherty afd504d5ae feat(events): opt-in stream-attached acknowledgement on StreamEvents (#227)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m28s
ci / java (push) Failing after 2m21s
ci / portable (push) Failing after 3m33s
A fresh StreamEvents is never replayed, so an initial value published before
the gateway registers the stream's subscriber is lost (lmxopcua#865 —
slow-changing ScanState). Clients had nothing deterministic to wait on.

Contract (additive, proto3):
- StreamEventsRequest.emit_stream_attached = 3 (bool, default false)
- MxEvent.stream_attached = 15 (optional StreamAttached)
- message StreamAttached { uint64 live_after_sequence = 1; }
- OpenSessionReply capability "stream-events-attached-ack"
  (GatewayCapabilities.StreamEventsAttachedAck)

When requested, EventStreamService yields the sentinel as the FIRST message,
after AttachEventSubscriber/AttachEventSubscriberWithReplay has returned, so
receipt implies registration; refused attaches never see it. It precedes the
ReplayGap sentinel and replay on a resume. Shape mirrors ReplayGap: family
UNSPECIFIED, no body, worker_sequence 0.

Opt-in rather than always-on: ScadaBridge's MxGateway adapter stores every
streamed event's worker_sequence as its resume cursor, so an unrequested
sentinel would reset it to 0. Default wire behaviour is unchanged.

.NET client: StreamEventsAsync/StreamEventItemsAsync(after, emitStreamAttached),
MxEventStreamItem.IsStreamAttached, MxGatewaySession.SupportsStreamAttachedAck,
and OpenEventStreamAsync -> MxGatewayEventStream (awaits the sentinel, with
attach timeout; refuses older gateways).

Regenerated Contracts/Generated, the client protoset, Go and Python bindings
(also picks up comment-only drift already on main), synced the Rust vendored
proto and set emit_stream_attached in the Rust StreamEventsRequest literals.
No package versions bumped.

Tests: ordering (sentinel first, then events), race proof (event fanned right
after the sentinel is delivered — mutation-checked: fails when the sentinel is
yielded before registration), resume-with-gap order, refused attach emits no
sentinel, default emits none, contract field numbers, capability, and .NET
client wire tests (await, no-capability, older gateway, timeout).
2026-11-12 07:27:17 -05:00
Joseph Doherty 892bdc1a19 fix(worker): wnwrap alarm DATE+TIME are UTC; stop re-applying GMTOFFSET (#226)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m26s
ci / java (push) Successful in 2m28s
ci / portable (push) Failing after 3m38s
QueryActiveAlarms / alarm transitions reported every wnwrap alarm late by
the record's GMTOFFSET-DSTADJUST: ParseTransitionTimestampUtc treated the
XML DATE+TIME as producer-local and added the offset, but the fields are
already UTC. DEV evidence: RuntimeAlert raise EventTimeUtc 2026-07-28
20:02:46.830 (EventTimeUTCOffsetMins -300) surfaced as 2026-07-29
01:02:46.830Z. The 2026-05-01 probe capture (TIME 13:26:14.709,
GMTOFFSET 240) was committed at 09:44 EDT, so its TIME is UTC too.

GMTOFFSET/DSTADJUST are no longer read. Tests updated + #226 regressions.
2026-11-12 07:20:44 -05:00
Joseph Doherty 2b13564e04 feat(ldap): pin the LDAP server certificate by SHA-256 thumbprint (#180)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m26s
ci / java (push) Successful in 2m15s
ci / portable (push) Failing after 4m19s
New optional MxGateway:Ldap:ServerCertificateThumbprintSha256 (hex SHA-256
of the DER cert; case/colon/dash/space-insensitive; comma/semicolon-separated
string or array, so a rotation can carry old + new). When set, the dashboard's
shared LDAP provider gets a RemoteCertificateValidationCallback via
LdapOptions.ServerCertificateValidationCallback (Auth 0.4.1) that accepts the
server certificate iff its thumbprint matches a pin, ignoring chain/name
errors only then. Unset keeps default OS trust-store validation untouched.

The callback is an init-only, code-only property, so the ILdapAuthService
registration from AddZbLdapAuth is replaced with one built from the bound
options plus the callback. Pins are read straight from configuration because
the binder silently binds the scalar form onto a list as empty.

GatewayOptionsValidator rejects a pin that is not 64 hex chars after
normalization and any pin with Transport=None; the Production hard stops are
unchanged. Pins are shown on the Settings page. Docs: GatewayConfiguration.md,
glauth.md.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-10 11:52:14 -05:00
Joseph Doherty 9c6ac0cdbc test(integration): live Write2 round-trip with timestamp (#212, IntegrationTests-033)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m28s
ci / java (push) Successful in 2m15s
ci / portable (push) Failing after 4m20s
Opt-in [LiveMxAccessFact] mirroring the Write round-trip: Register/AddItem/
Advise, then Write2 with a VT_DATE timestamp value; asserts Ok + Write2 kind
and a matching OnWriteComplete. Skips without the live MXAccess env.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-10 11:02:22 -05:00
Joseph Doherty 53562ddc17 fix(worker): unregister-first shutdown cleanup order, guarded + logged (#175, R21-K10)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m32s
ci / java (push) Successful in 2m21s
ci / portable (push) Failing after 4m30s
ShutdownGracefully now Unregisters every server handle first (MXAccess drops its
items and advise subscriptions with it). Only for a server whose Unregister fails
does the UnAdvise -> RemoveItem fallback run. Each step is guarded, logged at Debug,
and the method is idempotent. #176 (AuthenticateUser cache) is unaffected.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-10 04:26:55 -05:00
Joseph Doherty ace12f81ad build(deps): bump ZB.MOM.WW.Auth 0.3.0 -> 0.4.1 (scadaproj#5)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m27s
ci / java (push) Successful in 2m44s
ci / portable (push) Failing after 4m59s
Auth 0.4.1 (BindMode stays ServiceAccount; empty password now refused in the library too; Username canonicalised from UserNameAttribute). No API breaks, no test changes needed.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 18:16:27 -05:00
Joseph Doherty e1656f214b build(deps): bump ZB.MOM.WW.Theme 0.4.1 -> 0.5.0 (scadaproj#9)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m27s
ci / java (push) Successful in 2m30s
ci / portable (push) Failing after 5m10s
Mobile shell fix: closed navigation no longer hides page content.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:48:16 -05:00
Joseph Doherty 7a7ef3b89f fix(config): align GatewayConfigPathRules with Secrets-005 (symlinks, drive-relative, device/loopback/local-share spellings) (scadaproj#52)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m30s
ci / java (push) Successful in 2m17s
ci / portable (push) Failing after 4m20s
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:40:32 -05:00
Joseph Doherty 477fa55998 feat(deploy): on-box NSSM upgrade/rollback and new-box install scripts, runbook updated (mxaccessgw#220)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m26s
ci / java (push) Successful in 2m12s
ci / portable (push) Failing after 4m11s
Add scripts/deploy/Upgrade-MxGatewayService.ps1 (preflight, stop with STOP_PENDING handling,
backup, Server+Worker swap, start, /health/ready + SHA verify, auto/manual rollback,
one-gateway guard, never touches the NSSM env block) and Install-MxGatewayService.ps1
(service install, restart/recovery settings, env block). Both support -DryRun/-WhatIf.
Dry-run validated on macOS pwsh against a fake layout; untested on a real box.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:10:26 -05:00
Joseph Doherty 259d375022 feat(audit): stamp CorrelationId on dashboard API-key admin audit events (mxaccessgw#213)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m29s
ci / java (push) Successful in 2m13s
ci / portable (push) Failing after 4m12s
CanonicalForwardingApiKeyAuditStore now derives CorrelationId from the ambient
request: Activity.Current trace id, else the HTTP request TraceIdentifier
(GUID used verbatim, otherwise hashed to a stable GUID) via an optional
IHttpContextAccessor. The CLI path has neither and stays null. Auth library
unchanged (option b).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:04:03 -05:00
Joseph Doherty fccc21ba8e feat(events): distinguish ResourceExhausted causes with an mxgw-reason trailer (mxaccessgw#216)
Event-queue overflow, alarm-feed overflow, subscriber cap, session limit and
oversized commands all surfaced as ResourceExhausted. The status code is
unchanged; the gateway now attaches a machine-readable `mxgw-reason` trailer
(constants in Contracts ResourceExhaustedReasons). The .NET client maps
ResourceExhausted to MxGatewayResourceExhaustedException (an
MxGatewayException subclass; additive) exposing Reason/IsOverflow/
IsSubscriberLimit. Documented in docs/ClientBehaviorFixtures.md; the other
clients get a doc note only.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 15:02:24 -05:00
Joseph Doherty 716c845fc7 build(server): bump Microsoft.Data.Sqlite to 10.0.13 with SQLitePCLRaw.lib.e_sqlite3 2.1.13 (mxaccessgw#225)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m28s
ci / java (push) Successful in 2m8s
ci / portable (push) Failing after 4m9s
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 14:21:21 -05:00
Joseph Doherty de86f8b80e ci: make the windev CI lock exclusive, stop the scheduled double run, isolate test secrets stores (mxaccessgw#150)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m34s
ci / java (push) Successful in 2m37s
ci / portable (push) Failing after 5m0s
Diagnosis of the retained Windows-nightly failures (119 scheduled nightlies, 28 red; job logs from
the Gitea API, C:\build\mxaccessgw-ci\ci.log and the windev System log, read-only):

- Checkout (#148, run 827, 2026-09-22): the windev "atomic mkdir" lock was not exclusive.
  New-Item -ItemType Directory checks for the directory and then calls CreateDirectory, which
  succeeds on an existing directory; a pwsh race harness had both contenders take it in 1900 of
  2000 simultaneous rounds. A scheduled run starts windows-x86 and nightly-windev in the same
  second, both bootstraps got in, and the nightly's checkout died on .git/index.lock.
  Fix: the bootstrap (and a standalone windev-worker-ci.ps1) holds an exclusive FileShare.None
  handle on C:\build\mxaccessgw-ci.ci-lock instead (0 of 1000 double acquisitions in the same
  harness). The OS drops it if the holder dies, so a killed run leaves no stale lock, and a holder
  removes a leftover .git\index.lock, which can only be debris from a killed git.
- windows-x86 no longer runs on the schedule: nightly-windev's live mode already runs the same
  Worker build + tests first, so the scheduled copy only doubled the load and created the race.
- Host resources (#128/#129/#131-#135/#138, 2026-07-24..08-03): windev's System log has
  Resource-Exhaustion-Detector event 2004 (low virtual memory) every few minutes from 2026-07-23
  until an unexpected shutdown/hard reset on 2026-08-03; OOM in MSBuild/csc/protoc,
  csc 0xC0000142, PowerShell dying before its first log line and SSH kex resets all fall in that
  window and stop after the reset. Host-side; windev-worker-ci.ps1 now logs free commit, physical
  memory, disk and testhost count at start and on failure so the next one is correlatable.
- SSH "No route to host" (#144, 2026-09-16): windev was down (unexpected shutdown 00:58, back 05:50).
- Dashboard host build (#143, run 817): two host-building test classes failed at the same instant
  in SqliteSecretsStoreMigrator with "cannot start a transaction within a transaction" -- parallel
  classes migrating the one per-process secrets store. Tests now build the gateway through
  TestSupport/TestGatewayHost, which gives each host its own store; TestGatewayHostTests guards it.
- Gateway E2E "Worker pipe disconnected" (#142/#145/#146/#147) and handshaking-to-ready (#141) were
  the fake-worker partial-frame cancellation and readiness-race defects fixed in #153 (d779daf6):
  7 gateway-suite failures in 51 windev runs before it, 0 in 28 since. The Worker watchdog and
  burst-coalescing failures (#126/#127/#139) last failed before 50322bac / 7da52b65 (Aug 2026).
- 2026-10-15..20 was the NU1903 package-audit restore failure, fixed in fb20997.

Docs: GatewayTesting.md (lock, host-resource triage) and scripts/ci/README.md.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:36:34 -05:00
Joseph Doherty 09b3ecddf2 test: pump-idle signal for DashboardSnapshotFeed; fold private wait helpers into Eventually (mxaccessgw#223)
The MxGateway.Tests part of #223 (the Worker.Tests items are handled separately).

- DashboardSnapshotFeed gains two internal test seams: WhenIdleGateClosedAsync, a
  TCS-backed signal that completes once no pump generation is accepting subscribers,
  and IsPumpIdle (no live generation and the latest pump has exited). The TCS is created
  lazily by a waiter, so production never allocates it.
- WatchAsync_WhenAJoinerLeavesWhileAnOldGenerationLingers_LeavesNoPumpRunning drops both
  150 ms real sleeps: it waits on the idle-gate signal for the joiner's unsubscribe, and
  asserts IsPumpIdle before the orphan-push check, which is then immediate. Reverting the
  per-generation idle check to the old global "list is empty" check now fails the test
  (5 s TimeoutException on the gate), where before the sleep simply elapsed.
- Eventually.WaitUntilAsync/WaitForAsync take an optional description (defaulting to the
  condition's source text via CallerArgumentExpression) for the timeout message, and gain an
  async-condition overload. The hand-rolled polling loops in EventStreamServiceTests,
  GatewaySessionDashboardMirrorTests, DashboardEventBroadcasterTests and
  AlarmsPageTruncationBannerTests now delegate to it, keeping their timeouts and messages.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:36:34 -05:00
Joseph Doherty 22964e192b feat(gateway,worker): configurable worker watchdog grace; heartbeat settings in effective config and Settings page (mxaccessgw#224)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m24s
ci / java (push) Successful in 2m15s
ci / portable (push) Failing after 4m17s
- New MxGateway:Worker:WorkerHeartbeatGraceSeconds (default 15), exported as
  MXGATEWAY_WORKER_HEARTBEAT_GRACE_MS and read by WorkerPipeSessionOptions.FromEnvironment
  (a grace the ceiling does not exceed falls back to the default so the worker
  still starts). Validation now checks WorkerHeartbeatStuckCeilingSeconds against
  the configured grace; the copied WorkerWatchdogGraceSeconds constant is gone.
- EffectiveWorkerConfiguration and the dashboard Settings page now show the worker
  heartbeat send interval, watchdog grace and stuck ceiling (render test added).
- Docs updated.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:29:10 -05:00
Joseph Doherty 381e772766 test(worker): assert FakeRuntimeSession release wait, bound live-probe waits (mxaccessgw#223)
FakeRuntimeSession ignored the bool from releaseDispatch.Wait(safety net); it now
faults the dispatch with a TimeoutException when nothing released it. The four
skip-gated live probe files' unbounded done.Wait() calls are bounded (10 min) and
assert, with the probe thread made background so a wedged COM call cannot hang
the test host. (Worker.Tests part only; gateway part tracked separately.)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:29:10 -05:00
Joseph Doherty 2e52f9f5e8 feat(gateway,worker): configurable worker heartbeat send interval and stuck ceiling (mxaccessgw#218)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m32s
ci / java (push) Successful in 2m57s
ci / portable (push) Failing after 5m1s
The worker's heartbeat send interval (5 s) and its own STA-watchdog stuck
ceiling (75 s) were compile-time defaults the gateway never reached, and
nothing checked that the gateway's HeartbeatGraceSeconds exceeded the real send
interval, so a misconfigured grace could kill healthy workers.

- New MxGateway:Worker options WorkerHeartbeatSendIntervalSeconds (default 5)
  and WorkerHeartbeatStuckCeilingSeconds (default 75), exported by
  WorkerProcessLauncher as MXGATEWAY_WORKER_HEARTBEAT_SEND_INTERVAL_MS and
  MXGATEWAY_WORKER_HEARTBEAT_STUCK_CEILING_MS, the same env-var path the other
  worker settings use.
- The worker's production WorkerPipeSession reads them through
  WorkerPipeSessionOptions.FromEnvironment; a missing/invalid value, or a
  ceiling not above the worker's 15 s watchdog grace, keeps the default rather
  than failing the worker.
- Startup validation: HeartbeatGraceSeconds > WorkerHeartbeatSendIntervalSeconds;
  send interval > 0; worker ceiling > 15 s; both at most 86400 s.
- Docs: GatewayConfiguration, WorkerProcessLauncher (env table now also lists
  the previously missing MXGATEWAY_ALARM_ACK_CLIENT_NAME), worker design doc.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:24:05 -05:00
Joseph Doherty 29d9510b4e perf(worker): batch frames skip per-frame TCS; stream the alarm-poll XML (mxaccessgw#177)
R21-K12: WorkerFrameWriter.WriteBatchAsync allocated a TaskCompletionSource
(plus its Task) per frame on the event drain hot path. PendingFrame now holds
its terminal state itself (Interlocked pending/succeeded/faulted/canceled) and
only single-frame WriteAsync frames, which race their completion against the
write lock, get a TCS. A batch caller reads each frame's outcome after its own
drain pass: every frame a pass claims is terminal before that pass releases the
lock, so nothing is left to await. First-failure-in-batch-order, tombstoning,
claim/cancel interlock and flush coalescing are unchanged.

R21-K13: WnWrapAlarmConsumer.ParseSnapshotXml streams the GetXmlCurrentAlarms2
payload with an XmlTextReader (same defaults XmlDocument.LoadXml uses:
Normalization off, DTDs parsed, no resolver; Significant whitespace only)
instead of building a full XmlDocument every 500 ms poll.

Behaviour is pinned by new tests: batch first-failure ordering (own drain and
drained by another lock holder), batch cancellation tombstoning, batch flush
failure, and a differential test running the replaced XmlDocument parser as an
oracle over a 48-payload corpus (CRLF, CDATA, entities, DTD, namespaces,
nesting, malformed). Mutation checks on windev: 8 of 8 injected regressions
(whitespace, normalization, DTD, namespace, CDATA, batch last-failure, batch
ignored failures, ignored tombstone) fail the new tests.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:24:05 -05:00
Joseph Doherty 7d44ecd62d refactor(worker): dedupe CreateEnvelope overloads and WorkerPipeClient constructors (mxaccessgw#185)
WorkerPipeSession had seven CreateEnvelope overloads that each forwarded to a
matching CreateBaseEnvelope overload; they are now one overload per body type
that stamps the header and sets the body. WorkerPipeClient's six chained
constructors collapse to one with optional arguments (null attempt timeout =
env/default, null session factory = production WorkerPipeSession). Adds
constructor-validation tests.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:24:05 -05:00
Joseph Doherty 2a91e2b083 refactor(rust-cli): split mxgw-cli main.rs by command group (mxaccessgw#203)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m27s
ci / java (push) Successful in 2m3s
ci / portable (push) Failing after 4m10s
Pure move: cli definition, per-group handlers (session, bulk, bench, events,
galaxy, smoke, batch) and shared output/parse/connect helpers now live in
their own modules. No behaviour or CLI surface change; --help of all 33
commands is byte-identical, clippy clean, tests unchanged.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:17:16 -05:00
Joseph Doherty bc28e1436b fix(dashboard): apply reconnect delay when the snapshot watch completes cleanly (mxaccessgw#222)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:12:40 -05:00
Joseph Doherty b47a168a2c test: assert the result of timed SemaphoreSlim.WaitAsync in GatewaySessionTests (mxaccessgw#221)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m30s
ci / java (push) Successful in 2m24s
ci / portable (push) Failing after 4m24s
The two start-gate waits in GatewaySessionTests ignored the bool from
WaitAsync(timeout), so a wait that timed out let the task run on
un-synchronised and the race test could pass without racing. Both now
Assert.True the result. Every other timed semaphore wait in the Tests
project was already checked (the #205 lease helper, the new CountSignal)
or is token-only.

Mutation check: with Release(n-1) and a 200 ms gate wait, the original
code passes (vacuous) while the fixed code fails with "Timed out at the
start gate."

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:10:05 -05:00
Joseph Doherty 82d29beafd test: fake time for dashboard snapshot publisher; signal-based waits (mxaccessgw#205)
DashboardSnapshotPublisher takes an optional TimeProvider (default
TimeProvider.System) driving the idle poll, the reconnect delay and, via
BoundedHubSend, the send timeout. Its tests now run on a fake clock with
exact assertions (reconnect gap == delay, 25 idle polls pull nothing, a
wedged send is abandoned at the fake send timeout).

DashboardSnapshotFeed has no time dependence, so no seam was added; its
tests lose the 100 ms sleep and poll loops in favour of CountSignal
signals. The Task.Delay(25) poll copies in the alarm-monitor tests and
several 5-10 ms poll loops now share TestSupport/Eventually.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:10:04 -05:00
Joseph Doherty 0c0c7b86f2 test(worker): pin the MxStatusDetailText table (mxaccessgw#178)
ci / windows-x86 (push) Successful in 1m34s
ci / nightly-windev (push) Has been skipped
ci / java (push) Successful in 2m41s
ci / portable (push) Failing after 4m37s
The detail-code-to-text table had no direct tests; only three codes were
covered incidentally through MxStatusProxyConverterTests. The new
MxStatusDetailTextTests pins every known code's text, checks codes
outside the table (including the gaps inside it and the int extremes)
map to empty, sweeps -16..20000 to assert the table holds exactly the
pinned codes, and checks every text is non-blank, trimmed and distinct.
(mxaccessgw#178)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:01:58 -05:00
Joseph Doherty d9c60a78eb feat(worker): log exception messages and per-command start/end (mxaccessgw#184)
R21-O3: WorkerApplication.Run's failure lines logged only the exception
type. Each now also carries exception_message, scrubbed by the new
WorkerLogRedactor.RedactMessage: the value of any name=value / name: value
pair whose name looks sensitive and any mxgw_ API key token are replaced,
line breaks are flattened and the text is capped at 512 characters. The
AppDomain unhandled-exception hook stays type-only, since an exception
from an arbitrary thread can carry command values.

R21-O7: StaCommandDispatcher.ExecuteQueuedCommandAsync logs
WorkerCommandStarted (correlation id, method, queued_ms) and
WorkerCommandCompleted (status, HRESULT, elapsed_ms) when a CommandLogger
is set. IWorkerLogger has no Debug level, so the lines are opt-in through
MXGATEWAY_WORKER_LOG_COMMANDS=1|true (WorkerCommandLogging), which the
worker inherits from the gateway process environment. No payloads or
diagnostic messages are logged. Docs updated. (mxaccessgw#184)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:01:58 -05:00
Joseph Doherty f49b7a0cc1 fix(worker): exit 5 on gateway death, dedicated exit 8 on event-queue overflow (mxaccessgw#186)
A frame read that hits end of stream means the gateway closed its end of
the pipe (usually because it died). WorkerApplication mapped every
WorkerFrameProtocolException to ProtocolViolation (6); EndOfStream now
exits as PipeConnectionFailed (5), alongside the IOException a broken
pipe raises.

Event-queue overflow exited as the generic UnexpectedFailure (1). The
event drain loop now unwinds with WorkerEventQueueFaultException carrying
the fault category, and QueueOverflow exits with the new
WorkerExitCode.EventQueueOverflow (8). Other categories keep exit 1.

The gateway does not decode worker exit codes (it only logs the number),
so no gateway change is needed. WorkerBootstrap.md and
MxAccessWorkerInstanceDesign.md updated. (mxaccessgw#186)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:01:58 -05:00
Joseph Doherty cf575bfca8 fix(worker): reply WorkerUnavailable to commands that race shutdown (mxaccessgw#182)
TryStartCommandTask returned silently when the session had stopped
accepting commands, so a command racing shutdown got no reply and no log
and the gateway's correlation wait ran to its timeout. The message loop
now answers such a command with a WorkerUnavailable reply (the status the
STA dispatcher already uses during shutdown) and logs
WorkerCommandRejectedShuttingDown. New test
CommandAfterShutdown_RepliesWorkerUnavailable (mxaccessgw#182)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:01:58 -05:00
Joseph Doherty 0609e810f4 test: fake-time hosted-service wiring tests, drop a real-clock sleep (mxaccessgw#205)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m19s
ci / java (push) Successful in 2m27s
ci / portable (push) Failing after 5m9s
R21-O32: SessionLeaseMonitorHostedService gets FakeTimeProvider tests (no sweep
before the interval, one sweep per interval with the clock's now, a failing
sweep does not stop the loop, interval floor, stop ends the loop), and
OrphanWorkerCleanupHostedService gets startup tests (sweeps once, failure
swallowed) plus a registration-order test (orphan cleanup before the session
hosted services). TickObservingTimeProvider gains WaitForWatchedTimersAsync so
Advance never races a service that has not armed its timer yet.

R21-O29: the 250 ms negative-assertion sleep in the stopping-WorkerClient test
is replaced by disposing the client and awaiting the pipe read-ahead to EOF.
Remaining real-clock sleeps (dashboard feed/publisher, alarm monitor tests)
need TimeProvider seams in production code and are left open.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:58:07 -05:00
Joseph Doherty 8c21678cb4 feat(health): worker-exe presence and bounded Galaxy SQL readiness checks (mxaccessgw#206)
Adds WorkerExecutableHealthCheck (configured worker .exe exists) and
GalaxySqlHealthCheck (IGalaxyRepository.TestConnectionAsync bounded by a 5 s
TimeProvider-driven timeout). Both are tagged ready only, never live, so an
outage takes the node out of rotation without triggering a restart; sessions
stay on the active tier so zero sessions is still healthy for Overview.

Registrations move into AddGatewayHealthChecks() so the tier tagging is
unit-tested. LDAP is not added (sign-in already surfaces bind failures).
docs/Diagnostics.md lists the two new checks.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:58:07 -05:00
Joseph Doherty b5d11e5869 fix(worker): heartbeat check loop honours the injected TimeProvider (mxaccessgw#217)
HeartbeatLoopAsync waited with a plain Task.Delay, so heartbeat grace/stuck
detection could not be driven with a fake clock. It now uses
Task.Delay(interval, _timeProvider, ct).

Adds fake-time tests (grace boundary then fault; in-flight command within the
stuck ceiling) built on a new TickObservingTimeProvider, and replaces the
150 ms real-clock sleep in the within-ceiling negative test (mxaccessgw#205).
Both new tests fail without the fix.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:58:07 -05:00
Joseph Doherty 21bab1a982 docs(claude): wonder remote exec is deployment-only since 2026-09-28, not disabled
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m23s
ci / java (push) Successful in 2m14s
ci / portable (push) Failing after 4m15s
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:45:14 -05:00
Joseph Doherty 2f6e480a41 docs(runbooks): deploy/upgrade runbook for the NSSM-wrapped gateway service (mxaccessgw#207)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:43:52 -05:00
Joseph Doherty f77062f097 feat(dashboard): show heartbeat, event-channel and replay-byte-cap options on Settings (mxaccessgw#219)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:42:12 -05:00
Joseph Doherty 07badd139e fix(gateway): bound the session replay ring by bytes as well as count (mxaccessgw#172)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m26s
ci / java (push) Successful in 2m28s
ci / portable (push) Failing after 4m48s
The replay ring was bounded only by ReplayBufferCapacity (1024 events) and
ReplayRetentionSeconds. Event size is unbounded up to the worker frame size,
so a burst of large-array events could pin gigabytes per session while the
count looked small.

New MxGateway:Events:ReplayBufferMaxBytes (default 64 MiB, 0 disables) caps
the summed serialized size (MxEvent.CalculateSize, measured only when the cap
is on). Over the cap the oldest entries are evicted, exactly like the count
cap, so a resuming subscriber sees the existing ReplayGap path; an event bigger
than the whole cap is not retained. Every eviction (count, age or byte) now
clears its slot, so an evicted event is released immediately instead of
staying referenced until the slot is reused.

The 64 MiB default is a judgement call: it never binds for scalar traffic
(1024 x a few hundred bytes) and only trims large-array bursts.

Tests: SessionEventDistributorTests byte-cap eviction, single oversized event,
cap 0 = count only (the first two fail with the cap enforcement removed);
validator rejects a negative value. Docs: GatewayConfiguration.md, Sessions.md,
DesignDecisions.md; appsettings.json carries the key.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:39:49 -05:00
Joseph Doherty 7b21f304e9 fix(gateway): split the heartbeat check interval from the send interval; expose the two fixed worker-client timeouts (mxaccessgw#192)
R21-O14: MxGateway:Worker:HeartbeatIntervalSeconds was documented as the
worker heartbeat send interval, but it never reached the worker (which sends
on its own fixed 5 s) and only set the gateway's HeartbeatCheckInterval. It is
renamed HeartbeatCheckIntervalSeconds (default 5, unchanged). The old key stays
as a deprecated alias with the same meaning so existing appsettings keep
working; setting both is a validation error. The grace-vs-interval check now
compares against the resolved check interval.

R21-O15: WorkerClientOptions.EventChannelFullModeTimeout and
HeartbeatStuckCeiling were always their compile-time defaults. They are now
MxGateway:Worker:EventChannelFullModeTimeoutMilliseconds (default 5000, > 0)
and HeartbeatStuckCeilingSeconds (default 75, >= HeartbeatGraceSeconds). The
factory's mapping moved into SessionWorkerClientFactory.CreateWorkerClientOptions
so every field is set from configuration and is testable. The effective-config
record shows the resolved check interval and both new values.

Docs: GatewayConfiguration.md, GatewayProcessDesign.md sample,
MxAccessWorkerInstanceDesign.md heartbeat section; appsettings.json uses the
new keys.

Tests: CreateWorkerClientOptions mapping + defaults (fail under a mutated
mapping), alias honoured, both-keys conflict, and bounds for the new options.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:39:49 -05:00
Joseph Doherty 101bda7073 fix(gateway): wake the worker-ready wait on a state-change signal instead of a 25 ms poll (mxaccessgw#189)
GetReadyWorkerClientAsync re-read the session and worker states every 25 ms
until the WorkerReadyWaitTimeoutMs deadline. It now waits on two
TaskCompletionSource signals - one completed by every GatewaySession _state /
_workerClient write, one by every WorkerClient _state write - and re-evaluates
only when one fires or the remaining budget elapses. Both signals are captured
under the lock before the state is evaluated, so a transition between the
evaluation and the await is not lost.

IWorkerClient gains GetStateChangedSignal(), a default interface member that
returns null; a client without a signal (the test fakes) is re-read on the old
25 ms interval, so the fakes need no change. The production WorkerClient always
publishes one. Default behaviour (WorkerReadyWaitTimeoutMs = 0, fail fast) is
unchanged.

Regression tests (SessionManagerTests): ...WakesWithoutPollTimer and
...FailsFastWithoutPollTimer never advance the FakeTimeProvider, so they hang
and fail against the poll loop; WorkerClientTests.GetStateChangedSignal_
CompletesOnEachTransition pins the worker-side signal.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:39:49 -05:00
Joseph Doherty 11d8f76c5f fix(gateway): GatewaySession implements IAsyncDisposable; drop dead KillWorker(string) (mxaccessgw#191)
R21-O12: GatewaySession already owned an async DisposeAsync teardown but did not
declare IAsyncDisposable, so anything holding it as IAsyncDisposable (or a DI
container) could not find the teardown. Declaring it changes no call site;
the existing await-using sites bound to the same method by pattern.

R21-O13: KillWorker(string) had no callers and was an ungated kill that
bypassed _closeLock. Deleted it; docs/Sessions.md and the test comments now
name KillWorkerWithCloseGateAsync, the real kill path.

Regression test: GatewaySessionTests.GatewaySession_ImplementsIAsyncDisposable
(fails before the interface is declared).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:39:49 -05:00
Joseph Doherty d56353bf08 fix(gateway): remove the orphaned mxgateway.retries.attempted instrument (mxaccessgw#215)
The launcher's Polly startup-probe pipeline was its only recorder and was
removed in mxaccessgw#188, so the counter, the RetryAttempted method and the
snapshot's RetryAttempts / RetryAttemptsByArea fields carried a permanent
zero. No dashboard page or in-repo alert rule references them. Metrics.md
drops the row and the snapshot shape (which also gains the missing
AlarmProviderSwitchCount field).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:39:49 -05:00
Joseph Doherty f829df8087 docs(worker): ReadBulk timeout comments describe one shared deadline (mxaccessgw#179)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m25s
ci / java (push) Successful in 2m16s
ci / portable (push) Failing after 4m31s
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:32:13 -05:00
Joseph Doherty 9906d7e57c docs(worker): state that residual events are discarded after WorkerShutdown (mxaccessgw#183)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:31:56 -05:00
Joseph Doherty ad7d2cbef0 docs(clients): add slow-consumer/backpressure comparison table (mxaccessgw#204)
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:31:32 -05:00
Joseph Doherty 7c377cac7b docs(config): complete the Configuration Shape JSON block (mxaccessgw#209)
Add Dashboard DisableLogin/AutoLoginUser/CookieName, Alarms:Fallback and Tls,
matching the option classes and the per-option tables below the block.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:30:42 -05:00
Joseph Doherty e69cd0321e fix(dashboard): close three low hub/page races (mxaccessgw#174)
D11: BrowsePage search CTS is cancelled+disposed exactly once under a lock.
D12: the hub refreshes the cached health status before seeding a new connection.
D13: DashboardEventBroadcaster gains DisposeAsync that awaits the pumps (bounded).

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:30:04 -05:00
Joseph Doherty f3a452810e fix(dashboard): validate __Host- cookie vs RequireHttpsCookie; surface login flags (mxaccessgw#196)
O19: reject a __Host- CookieName with RequireHttpsCookie=false at startup.
O20: project DisableLogin, AutoLoginUser, RequireHttpsCookie and CookieName into
EffectiveDashboardConfiguration and show them on the Settings page.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:28:21 -05:00
Joseph Doherty 417b9e5a19 feat(apikey): add --pepper-stdin and warn on --pepper (mxaccessgw#194)
--pepper on the command line lands in shell history and the process list.
Add --pepper-stdin (first stdin line), warn on stderr when --pepper is used,
and reject both together. Documented in GatewayProcessDesign.md.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 12:27:37 -05:00
Joseph Doherty be0d585f8c fix(server): cap Serilog file-sink retention and size (mxaccessgw#208)
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m31s
ci / java (push) Successful in 2m46s
ci / portable (push) Failing after 5m16s
Set retainedFileCountLimit=30, fileSizeLimitBytes=50 MiB and rollOnFileSizeLimit=true on the
file sink in appsettings.json and appsettings.Development.json; document under a new Logging
section in docs/GatewayConfiguration.md; add a guard test over the shipped config.
2026-11-09 12:10:20 -05:00
Joseph Doherty 0d156b56cc refactor(server): SparseArrayExpander throws a domain exception, mapped to InvalidArgument in the gRPC layer (mxaccessgw#190)
Adds SparseArrayException so the Sessions layer no longer throws Grpc.Core.RpcException;
MxAccessGatewayService.MapException maps it to StatusCode.InvalidArgument (client-visible
behaviour unchanged). Adds a service-level mapping test.
2026-11-09 12:10:20 -05:00