Joseph Doherty
90 lines
3.7 KiB
Markdown
90 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` 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.
|
|
|
|
Startup probing uses a bounded Polly retry policy. The gateway starts the worker
|
|
process once, then retries only transient startup-probe failures while the
|
|
process remains alive. The policy is configured by
|
|
`WorkerOptions.StartupProbeRetryAttempts` and
|
|
`WorkerOptions.StartupProbeRetryDelayMilliseconds`; the retry counter is
|
|
recorded as `mxgateway.retries.attempted` with `area=worker_startup`.
|
|
|
|
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)
|