mxaccessgw/docs/WorkerProcessLauncher.md

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:

--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:

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:

dotnet build src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj

Related Documentation

• Gateway Process Detailed Design
• Worker Frame Protocol