683aea0fbe
Generate high-level requirements and 10 component documents derived from source code and protocol specs. Uses lmxproxy_updates.md (v2 TypedValue/QualityCode) as the source of truth, with v1 string-based encoding documented as legacy context. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
123 lines
5.1 KiB
Markdown
123 lines
5.1 KiB
Markdown
# Component: Configuration
|
||
|
||
## Purpose
|
||
|
||
Defines the `appsettings.json` structure, configuration binding, and startup validation for the LmxProxy Host service.
|
||
|
||
## Location
|
||
|
||
- `src/ZB.MOM.WW.LmxProxy.Host/Configuration/LmxProxyConfiguration.cs` — root configuration class.
|
||
- `src/ZB.MOM.WW.LmxProxy.Host/Configuration/ConfigurationValidator.cs` — validation logic.
|
||
- `src/ZB.MOM.WW.LmxProxy.Host/appsettings.json` — default configuration file.
|
||
|
||
## Responsibilities
|
||
|
||
- Define all configurable settings as strongly-typed classes.
|
||
- Bind `appsettings.json` sections to configuration objects via `Microsoft.Extensions.Configuration`.
|
||
- Validate all settings at startup, failing fast on invalid values.
|
||
- Support environment variable overrides.
|
||
|
||
## 1. Configuration Structure
|
||
|
||
### 1.1 Root: LmxProxyConfiguration
|
||
|
||
| Setting | Type | Default | Description |
|
||
|---------|------|---------|-------------|
|
||
| GrpcPort | int | 50051 | gRPC server listen port |
|
||
| ApiKeyConfigFile | string | `apikeys.json` | Path to API key configuration file |
|
||
| Subscription | SubscriptionConfiguration | — | Subscription channel settings |
|
||
| ServiceRecovery | ServiceRecoveryConfiguration | — | Windows SCM recovery settings |
|
||
| Connection | ConnectionConfiguration | — | MxAccess connection settings |
|
||
| Tls | TlsConfiguration | — | TLS/SSL settings |
|
||
| WebServer | WebServerConfiguration | — | Status web server settings |
|
||
|
||
### 1.2 ConnectionConfiguration
|
||
|
||
| Setting | Type | Default | Description |
|
||
|---------|------|---------|-------------|
|
||
| MonitorIntervalSeconds | int | 5 | Auto-reconnect check interval |
|
||
| ConnectionTimeoutSeconds | int | 30 | Initial connection timeout |
|
||
| ReadTimeoutSeconds | int | 5 | Per-read operation timeout |
|
||
| WriteTimeoutSeconds | int | 5 | Per-write operation timeout |
|
||
| MaxConcurrentOperations | int | 10 | Semaphore limit for concurrent MxAccess operations |
|
||
| AutoReconnect | bool | true | Enable auto-reconnect loop |
|
||
| NodeName | string? | null | MxAccess node name (optional) |
|
||
| GalaxyName | string? | null | MxAccess galaxy name (optional) |
|
||
|
||
### 1.3 SubscriptionConfiguration
|
||
|
||
| Setting | Type | Default | Description |
|
||
|---------|------|---------|-------------|
|
||
| ChannelCapacity | int | 1000 | Per-client subscription buffer size |
|
||
| ChannelFullMode | string | `DropOldest` | Backpressure strategy: `DropOldest`, `DropNewest`, `Wait` |
|
||
|
||
### 1.4 TlsConfiguration
|
||
|
||
| Setting | Type | Default | Description |
|
||
|---------|------|---------|-------------|
|
||
| Enabled | bool | false | Enable TLS on gRPC server |
|
||
| ServerCertificatePath | string | `certs/server.crt` | PEM server certificate |
|
||
| ServerKeyPath | string | `certs/server.key` | PEM server private key |
|
||
| ClientCaCertificatePath | string | `certs/ca.crt` | CA certificate for mTLS |
|
||
| RequireClientCertificate | bool | false | Require client certificates |
|
||
| CheckCertificateRevocation | bool | false | Enable CRL checking |
|
||
|
||
### 1.5 WebServerConfiguration
|
||
|
||
| Setting | Type | Default | Description |
|
||
|---------|------|---------|-------------|
|
||
| Enabled | bool | true | Enable status web server |
|
||
| Port | int | 8080 | HTTP listen port |
|
||
| Prefix | string? | null | Custom URL prefix (defaults to `http://+:{Port}/`) |
|
||
|
||
### 1.6 ServiceRecoveryConfiguration
|
||
|
||
| Setting | Type | Default | Description |
|
||
|---------|------|---------|-------------|
|
||
| FirstFailureDelayMinutes | int | 1 | Restart delay after first failure |
|
||
| SecondFailureDelayMinutes | int | 5 | Restart delay after second failure |
|
||
| SubsequentFailureDelayMinutes | int | 10 | Restart delay after subsequent failures |
|
||
| ResetPeriodDays | int | 1 | Days before failure count resets |
|
||
|
||
## 2. Validation
|
||
|
||
`ConfigurationValidator.ValidateAndLog()` runs at startup and checks:
|
||
|
||
- **GrpcPort**: Must be 1–65535.
|
||
- **Connection**: All timeout values > 0. NodeName and GalaxyName ≤ 255 characters.
|
||
- **Subscription**: ChannelCapacity 0–100000. ChannelFullMode must be one of `DropOldest`, `DropNewest`, `Wait`.
|
||
- **ServiceRecovery**: All failure delay values ≥ 0. ResetPeriodDays > 0.
|
||
- **TLS**: If enabled, validates certificate file paths exist.
|
||
|
||
Validation errors are logged and cause the service to throw `InvalidOperationException`, preventing startup.
|
||
|
||
## 3. Configuration Sources
|
||
|
||
Configuration is loaded via `Microsoft.Extensions.Configuration.ConfigurationBuilder`:
|
||
1. `appsettings.json` (required).
|
||
2. Environment variables (override any JSON setting).
|
||
|
||
## 4. Serilog Configuration
|
||
|
||
Logging is configured in the `Serilog` section of `appsettings.json`:
|
||
|
||
| Setting | Value |
|
||
|---------|-------|
|
||
| Console sink | ANSI theme, custom template with HH:mm:ss timestamp |
|
||
| File sink | `logs/lmxproxy-.txt`, daily rolling, 30 files retained |
|
||
| Default level | Information |
|
||
| Override: Microsoft | Warning |
|
||
| Override: System | Warning |
|
||
| Override: Grpc | Information |
|
||
| Enrichment | FromLogContext, WithMachineName, WithThreadId |
|
||
|
||
## Dependencies
|
||
|
||
- **Microsoft.Extensions.Configuration** — configuration binding.
|
||
- **Serilog.Settings.Configuration** — Serilog configuration from appsettings.
|
||
|
||
## Interactions
|
||
|
||
- **ServiceHost** (Program.cs) loads and validates configuration at startup.
|
||
- All other components receive their settings from the bound configuration objects.
|