Joseph Doherty
63 lines
2.1 KiB
Markdown
63 lines
2.1 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.
|
|
|
|
## 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.
|
|
|
|
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/MxGateway.Tests/MxGateway.Tests.csproj --filter WorkerProcessLauncherTests
|
|
```
|
|
|
|
Run the gateway build because the launcher is part of `MxGateway.Server`:
|
|
|
|
```bash
|
|
dotnet build src/MxGateway.Server/MxGateway.Server.csproj
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- [Gateway Process Detailed Design](./gateway-process-design.md)
|
|
- [Worker Frame Protocol](./WorkerFrameProtocol.md)
|