dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add LmxProxy requirements documentation with v2 protocol as authoritative design

Browse Source 
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>
This commit is contained in:
Joseph Doherty
2026-03-21 22:38:11 -04:00
parent 970d0a5cb3
commit 683aea0fbe
12 changed files with 1702 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
lmxproxy/docs/requirements/Component-Configuration.md Normal file
View File

@@ -0,0 +1,122 @@
# 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.