Joseph Doherty
ff397b27be
WorkerProcessStartedProbe only checks HasExited and throws a non-retryable WorkerProcessLaunchException, so StartupProbeRetryAttempts and StartupProbeRetryDelayMilliseconds configured a Polly retry that no shipped probe could trigger. Real readiness is WorkerClient's WorkerReady handshake under the same StartupTimeoutSeconds budget, so the probe now runs once and the two options, their validation, the Polly pipeline (and the server's now unused Polly.Core reference) and their docs are removed. A stale value in configuration is ignored by the binder. Tests: WorkerProcessLauncherTests.LaunchAsync_WhenStartupProbeFails_DoesNotRetryTheProbe, WorkerOptions_HasNoStartupProbeRetryOptions (both fail on the old code).
88 lines
3.7 KiB
Markdown
88 lines
3.7 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 all six values:
|
|
|
|
| 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 |
|
|
|
|
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` runs once. The default probe
|
|
only verifies that the worker did not exit immediately; a worker that has
|
|
already exited cannot be recovered by waiting, so the probe is not retried.
|
|
Real readiness is the pipe connection, hello, and `WorkerReady` handshake that
|
|
`WorkerClient` performs after the launch, under the same
|
|
`WorkerOptions.StartupTimeoutSeconds` budget. (The former
|
|
`StartupProbeRetryAttempts` / `StartupProbeRetryDelayMilliseconds` options were
|
|
removed because no shipped probe could ever produce a retryable failure; a
|
|
stale value in configuration is ignored by the binder.)
|
|
|
|
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)
|