22964e192b
- 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
94 lines
4.3 KiB
Markdown
94 lines
4.3 KiB
Markdown
# Worker Process Launcher
|
||
|
||
The gateway uses `WorkerProcessLauncher` to validate and start one worker
|
||
process for a gateway session. The launcher owns process start semantics only;
|
||
pipe handshaking and `WorkerReady` validation remain part of the worker client
|
||
startup path.
|
||
|
||
## Launch Inputs
|
||
|
||
`WorkerProcessLaunchRequest` carries the per-session bootstrap values:
|
||
|
||
- `SessionId`,
|
||
- `PipeName`,
|
||
- `ProtocolVersion`,
|
||
- `Nonce`,
|
||
- optional `PipeReservation` cleanup handle.
|
||
|
||
The launcher passes `SessionId`, `PipeName`, and `ProtocolVersion` as command
|
||
line arguments:
|
||
|
||
```text
|
||
--session-id <sessionId> --pipe-name <pipeName> --protocol-version <version>
|
||
```
|
||
|
||
The launcher sets the nonce through the `MXGATEWAY_WORKER_NONCE` environment
|
||
variable. The nonce is not included in `WorkerProcessCommandLine` so logs and
|
||
diagnostics can report the launch command without exposing the secret.
|
||
|
||
All launch-variable names live in the shared Contracts
|
||
`WorkerLaunchEnvironment` class and are consumed by both the launcher and the
|
||
worker. The launcher always exports every value below:
|
||
|
||
| Environment variable | Gateway source | Worker default when missing/invalid |
|
||
|---|---|---|
|
||
| `MXGATEWAY_WORKER_NONCE` | `WorkerProcessLaunchRequest.Nonce` | None; bootstrap fails because the nonce is required |
|
||
| `MXGATEWAY_WORKER_PIPE_CONNECT_ATTEMPT_TIMEOUT_MS` | `MxGateway:Worker:PipeConnectAttemptTimeoutMilliseconds` | `2000` ms |
|
||
| `MXGATEWAY_WORKER_WRITE_COMPLETION_WAIT_MS` | `MxGateway:Worker:WriteCompletionWaitMilliseconds` | `1500` ms |
|
||
| `MXGATEWAY_EVENT_QUEUE_CAPACITY` | `MxGateway:Worker:EventQueueCapacity` | `10000` events |
|
||
| `MXGATEWAY_ALARM_POLL_INTERVAL_MS` | `MxGateway:Alarms:PollIntervalMilliseconds` | `500` ms |
|
||
| `MXGATEWAY_ALARM_MAX_ALARMS_PER_FETCH` | `MxGateway:Alarms:MaxAlarmsPerFetch` | `1024` alarms |
|
||
| `MXGATEWAY_ALARM_ACK_CLIENT_NAME` | `MxGateway:Alarms:AckClientName` | `MxGateway` |
|
||
| `MXGATEWAY_WORKER_HEARTBEAT_SEND_INTERVAL_MS` | `MxGateway:Worker:WorkerHeartbeatSendIntervalSeconds` (× 1000) | `5000` ms |
|
||
| `MXGATEWAY_WORKER_HEARTBEAT_GRACE_MS` | `MxGateway:Worker:WorkerHeartbeatGraceSeconds` (× 1000) | `15000` ms (also kept when the ceiling is not above it) |
|
||
| `MXGATEWAY_WORKER_HEARTBEAT_STUCK_CEILING_MS` | `MxGateway:Worker:WorkerHeartbeatStuckCeilingSeconds` (× 1000) | `75000` ms (also kept when the value is not above the worker's watchdog grace) |
|
||
|
||
The write-completion wait applies to the four single-item write variants:
|
||
`Write`, `Write2`, `WriteSecured`, and `WriteSecured2`. Bulk writes report COM
|
||
acceptance per entry and do not wait for `OnWriteComplete` rows.
|
||
|
||
## Validation And Cleanup
|
||
|
||
Before starting the process, the launcher validates that the configured worker
|
||
path exists, has a `.exe` extension, contains a valid Windows Portable
|
||
Executable header, and matches the configured `RequiredArchitecture`.
|
||
|
||
After the process starts, `IWorkerStartupProbe` waits for startup readiness.
|
||
The default probe only verifies that the worker did not exit immediately. The
|
||
worker client replaces this probe when pipe connection, hello, and
|
||
`WorkerReady` handling are implemented.
|
||
|
||
The startup probe runs once, bounded by `WorkerOptions.StartupTimeoutSeconds`;
|
||
it is not retried. The default probe only checks that the process is still
|
||
alive, which cannot change on a retry, so the former
|
||
`StartupProbeRetryAttempts` / `StartupProbeRetryDelayMilliseconds` options were
|
||
removed (mxaccessgw#188). Stale keys in existing configuration are ignored by
|
||
the binder. The worker pipe connect and handshake have their own retry loop.
|
||
|
||
The worker uses the exported pipe-attempt value inside its own bounded Polly
|
||
retry loop.
|
||
|
||
If startup fails or exceeds `WorkerOptions.StartupTimeoutSeconds`, the launcher
|
||
kills the worker process tree, disposes the process handle, disposes the
|
||
optional pipe reservation, records a worker kill metric, and reports a
|
||
`WorkerProcessLaunchException`.
|
||
|
||
## Verification
|
||
|
||
Run the focused launcher tests after changing process launch behavior:
|
||
|
||
```bash
|
||
dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter WorkerProcessLauncherTests
|
||
```
|
||
|
||
Run the gateway build because the launcher is part of `ZB.MOM.WW.MxGateway.Server`:
|
||
|
||
```bash
|
||
dotnet build src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj
|
||
```
|
||
|
||
## Related Documentation
|
||
|
||
- [Gateway Process Detailed Design](./GatewayProcessDesign.md)
|
||
- [Worker Frame Protocol](./WorkerFrameProtocol.md)
|