scadalink-design/lmxproxy/docs/requirements/Component-Configuration.md

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.