Gateway Configuration

This document describes every option bound under the MxGateway configuration section by GatewayOptions.

The gateway binds configuration at startup and validates it with GatewayOptionsValidator. Startup fails before the server listens when required paths, timeouts, queue sizes, enum values, or protocol values are invalid.

Configuration Shape

{
  "MxGateway": {
    "Authentication": {
      "Mode": "ApiKey",
      "SqlitePath": "C:\\ProgramData\\MxGateway\\gateway-auth.db",
      "PepperSecretName": "MxGateway:ApiKeyPepper",
      "RunMigrationsOnStartup": true
    },
    "Worker": {
      "ExecutablePath": "src\\MxGateway.Worker\\bin\\x86\\Release\\MxGateway.Worker.exe",
      "WorkingDirectory": null,
      "RequiredArchitecture": "X86",
      "StartupTimeoutSeconds": 30,
      "StartupProbeRetryAttempts": 3,
      "StartupProbeRetryDelayMilliseconds": 250,
      "PipeConnectAttemptTimeoutMilliseconds": 2000,
      "ShutdownTimeoutSeconds": 10,
      "HeartbeatIntervalSeconds": 5,
      "HeartbeatGraceSeconds": 15,
      "MaxMessageBytes": 16777216
    },
    "Sessions": {
      "DefaultCommandTimeoutSeconds": 30,
      "MaxSessions": 64,
      "MaxPendingCommandsPerSession": 128,
      "AllowMultipleEventSubscribers": false
    },
    "Events": {
      "QueueCapacity": 10000,
      "BackpressurePolicy": "FailFast"
    },
    "Dashboard": {
      "Enabled": true,
      "PathBase": "/dashboard",
      "RequireAdminScope": true,
      "AllowAnonymousLocalhost": true,
      "SnapshotIntervalMilliseconds": 1000,
      "RecentFaultLimit": 100,
      "RecentSessionLimit": 200,
      "ShowTagValues": false
    },
    "Protocol": {
      "WorkerProtocolVersion": 1
    }
  }
}

Environment variables use the normal .NET double-underscore form. For example, MxGateway__Sessions__MaxSessions=20 overrides MxGateway:Sessions:MaxSessions.

Authentication Options

Option	Default	Description
`MxGateway:Authentication:Mode`	`ApiKey`	Selects public gRPC authentication. Supported values are `ApiKey` and `Disabled`. `Disabled` bypasses API-key verification and is for local development only.
`MxGateway:Authentication:SqlitePath`	`C:\ProgramData\MxGateway\gateway-auth.db`	SQLite database path for API-key records and audit rows when API-key authentication is enabled.
`MxGateway:Authentication:PepperSecretName`	`MxGateway:ApiKeyPepper`	Configuration key used to read the HMAC pepper for API-key secret hashing. The dashboard effective configuration redacts this value.
`MxGateway:Authentication:RunMigrationsOnStartup`	`true`	Runs SQLite auth schema migrations at gateway startup when API-key authentication is enabled.

When Mode is ApiKey, SqlitePath and PepperSecretName must be present. SqlitePath must be a valid filesystem path.

Worker Options

Option	Default	Description
`MxGateway:Worker:ExecutablePath`	`src\MxGateway.Worker\bin\x86\Release\MxGateway.Worker.exe`	Path to the x86 worker executable launched for each gateway session. The path must be valid and point to a `.exe` file.
`MxGateway:Worker:WorkingDirectory`	`null`	Optional working directory for the worker process. When set, it must be a valid filesystem path.
`MxGateway:Worker:RequiredArchitecture`	`X86`	Required Portable Executable architecture for the worker. Supported values are `X86` and `X64`; MXAccess parity uses `X86`.
`MxGateway:Worker:StartupTimeoutSeconds`	`30`	Total startup budget for process launch, startup probe, pipe connect, handshake, and worker readiness.
`MxGateway:Worker:StartupProbeRetryAttempts`	`3`	Number of retry attempts for transient worker startup probe failures before pipe connection and handshake continue.
`MxGateway:Worker:StartupProbeRetryDelayMilliseconds`	`250`	Delay between transient startup probe retry attempts.
`MxGateway:Worker:PipeConnectAttemptTimeoutMilliseconds`	`2000`	Per-attempt timeout used by the worker named-pipe connect retry path. The overall pipe connection still stays under the startup budget.
`MxGateway:Worker:ShutdownTimeoutSeconds`	`10`	Grace period for worker shutdown before the gateway treats shutdown as failed and may kill the worker process tree.
`MxGateway:Worker:HeartbeatIntervalSeconds`	`5`	Worker heartbeat send interval and gateway heartbeat check cadence input.
`MxGateway:Worker:HeartbeatGraceSeconds`	`15`	Maximum age of the last worker heartbeat before the gateway faults the worker. This must be greater than or equal to `HeartbeatIntervalSeconds`.
`MxGateway:Worker:MaxMessageBytes`	`16777216`	Maximum worker IPC frame payload size in bytes. The validator allows values from `1024` through `268435456`.

StartupProbeRetryAttempts, StartupProbeRetryDelayMilliseconds, PipeConnectAttemptTimeoutMilliseconds, timeout values, heartbeat values, and MaxMessageBytes must be positive. MaxMessageBytes is intentionally bounded to avoid accidental large allocations from malformed or oversized frames.

Session Options

Option	Default	Description
`MxGateway:Sessions:DefaultCommandTimeoutSeconds`	`30`	Default timeout used while the gateway waits for a worker command reply when an open-session request does not provide a positive command timeout.
`MxGateway:Sessions:MaxSessions`	`64`	Maximum number of concurrently open gateway sessions. Session opens reserve a slot atomically before worker creation.
`MxGateway:Sessions:MaxPendingCommandsPerSession`	`128`	Maximum number of pending worker commands for one session. Excess commands fail fast instead of queueing indefinitely.
`MxGateway:Sessions:AllowMultipleEventSubscribers`	`false`	Controls whether multiple `StreamEvents` subscribers may attach to one session. `true` is rejected until event fan-out is implemented.

All numeric session options must be greater than zero. The current event stream implementation supports one active subscriber per session; this preserves event ordering and avoids competing consumers.

Event Options

Option	Default	Description
`MxGateway:Events:QueueCapacity`	`10000`	Capacity for bounded per-session event queues used by the gateway worker event channel and the public gRPC event stream queue.
`MxGateway:Events:BackpressurePolicy`	`FailFast`	Event backpressure behavior. `FailFast` is the only supported value.

QueueCapacity must be greater than zero. With FailFast, queue overflow faults the affected worker or session instead of silently dropping MXAccess events.

Dashboard Options

Option	Default	Description
`MxGateway:Dashboard:Enabled`	`true`	Enables Blazor Server dashboard route mapping.
`MxGateway:Dashboard:PathBase`	`/dashboard`	Base path for dashboard routes. When the dashboard is enabled, this value is required and must start with `/`.
`MxGateway:Dashboard:RequireAdminScope`	`true`	Requires API keys used for dashboard login to carry the `admin` scope.
`MxGateway:Dashboard:AllowAnonymousLocalhost`	`true`	Allows loopback dashboard requests to bypass the dashboard cookie requirement for local development. Remote requests still require dashboard authentication.
`MxGateway:Dashboard:SnapshotIntervalMilliseconds`	`1000`	Dashboard snapshot refresh interval used by realtime Blazor pages.
`MxGateway:Dashboard:RecentFaultLimit`	`100`	Maximum number of fault summaries projected into each dashboard snapshot.
`MxGateway:Dashboard:RecentSessionLimit`	`200`	Maximum number of session summaries projected into each dashboard snapshot.
`MxGateway:Dashboard:ShowTagValues`	`false`	Reserved display control for tag values. The dashboard does not show full tag values by default.

SnapshotIntervalMilliseconds must be greater than zero. RecentFaultLimit and RecentSessionLimit must be greater than or equal to zero.

Protocol Options

Option	Default	Description
`MxGateway:Protocol:WorkerProtocolVersion`	`1`	Worker IPC protocol version expected by the gateway and worker. This must match `GatewayContractInfo.WorkerProtocolVersion`.

The protocol option is exposed for diagnostics and explicit deployment configuration, not for compatibility negotiation. A mismatch fails validation at startup.

8.6 KiB Raw Blame History