Joseph Doherty
178 lines
11 KiB
Markdown
178 lines
11 KiB
Markdown
# 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
|
|
|
|
```json
|
|
{
|
|
"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,
|
|
"DefaultLeaseSeconds": 1800,
|
|
"LeaseSweepIntervalSeconds": 30,
|
|
"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,
|
|
"MaxGrpcMessageBytes": 16777216
|
|
},
|
|
"Galaxy": {
|
|
"ConnectionString": "Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;",
|
|
"CommandTimeoutSeconds": 60,
|
|
"DashboardRefreshIntervalSeconds": 30
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
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:DefaultLeaseSeconds` | `1800` | Initial session lease and refresh duration. Unary client activity extends the lease by this duration. |
|
|
| `MxGateway:Sessions:LeaseSweepIntervalSeconds` | `30` | Hosted monitor interval for closing expired leases. Active event-stream subscribers keep a session from expiring while the stream remains attached. |
|
|
| `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` faults the session on public stream queue overflow. `DisconnectSubscriber` disconnects only the slow stream. |
|
|
|
|
`QueueCapacity` must be greater than zero. With `FailFast`, queue overflow
|
|
faults the affected worker or session instead of silently dropping MXAccess
|
|
events. With `DisconnectSubscriber`, public gRPC stream overflow terminates only
|
|
the affected stream while the MXAccess session remains active.
|
|
|
|
## 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`. |
|
|
| `MxGateway:Protocol:MaxGrpcMessageBytes` | `16777216` | Public gRPC max send and receive message size in bytes. The same default is used by official clients. The validator allows values from `1024` through `268435456`. |
|
|
|
|
The protocol option is exposed for diagnostics and explicit deployment
|
|
configuration, not for compatibility negotiation. A mismatch fails validation
|
|
at startup.
|
|
|
|
## Galaxy Options
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `MxGateway:Galaxy:ConnectionString` | `Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;` | SQL Server connection string for the Galaxy Repository (`ZB`) used by the `GalaxyRepository` browse RPCs. Override in production via `MxGateway__Galaxy__ConnectionString`. |
|
|
| `MxGateway:Galaxy:CommandTimeoutSeconds` | `60` | Per-command SQL timeout for all Galaxy browse RPCs. |
|
|
| `MxGateway:Galaxy:DashboardRefreshIntervalSeconds` | `30` | Interval between background refreshes of the dashboard Galaxy summary cache. SQL is hit at most once per interval regardless of dashboard render rate. |
|
|
|
|
See [Galaxy Repository Browse](./GalaxyRepository.md) for the RPC surface and
|
|
behavior.
|
|
|
|
## Related Documentation
|
|
|
|
- [Gateway Process Detailed Design](./gateway-process-design.md)
|
|
- [Gateway Dashboard Detailed Design](./gateway-dashboard-design.md)
|
|
- [Worker Process Launcher](./WorkerProcessLauncher.md)
|
|
- [Worker Frame Protocol](./WorkerFrameProtocol.md)
|
|
- [Galaxy Repository Browse](./GalaxyRepository.md)
|