fix(alarms): fetch/poll ceilings; truncation-semantics docs; log-format conformance

src/ZB.MOM.WW.MxGateway.Server/Configuration/AlarmsOptions.cs

@@ -49,22 +49,26 @@ public sealed class AlarmsOptions
     /// <summary>
     ///     Cadence at which the worker's STA polls the AVEVA alarm consumer
     ///     (<c>GetXmlCurrentAlarms2</c>) for the current active-alarm snapshot.
-    ///     Default 500 ms; must be at least 100 ms. Every poll is a COM call
-    ///     plus an XML parse on the STA that also serves reads and writes, so
-    ///     driving it below 100 ms starves the command path. Conveyed to the
-    ///     worker through the <c>MXGATEWAY_ALARM_POLL_INTERVAL_MS</c>
-    ///     environment variable.
+    ///     Default 500 ms; must be between 100 ms and 3,600,000 ms (one hour).
+    ///     Every poll is a COM call plus an XML parse on the STA that also
+    ///     serves reads and writes, so driving it below 100 ms starves the
+    ///     command path; above an hour the cadence stops being a cadence and
+    ///     silently disables alarm polling. Conveyed to the worker through the
+    ///     <c>MXGATEWAY_ALARM_POLL_INTERVAL_MS</c> environment variable.
     /// </summary>
     public int PollIntervalMilliseconds { get; init; } = 500;
 
     /// <summary>
     ///     Cap the worker passes to <c>GetXmlCurrentAlarms2</c>'s
-    ///     <c>maxAlmCnt</c> argument. Default 1024; must be at least 64. A
-    ///     fetch that comes back holding exactly this many records is treated
-    ///     as truncated: the worker keeps the alarms the capped fetch could
-    ///     not mention in its snapshot rather than letting their absence read
-    ///     as a clear. Raise it on galaxies whose steady-state active-alarm
-    ///     count approaches the cap. Conveyed to the worker through the
+    ///     <c>maxAlmCnt</c> argument. Default 1024; must be between 64 and
+    ///     65,536 — the worker is a 32-bit process that materializes each
+    ///     fetch as one BSTR plus a full XmlDocument, so an unbounded cap
+    ///     faults the STA rather than merely slowing it. A fetch that comes
+    ///     back holding exactly this many records is treated as truncated: the
+    ///     worker keeps the alarms the capped fetch could not mention in its
+    ///     snapshot rather than letting their absence read as a clear. Raise it
+    ///     on galaxies whose steady-state active-alarm count approaches the
+    ///     cap. Conveyed to the worker through the
     ///     <c>MXGATEWAY_ALARM_MAX_ALARMS_PER_FETCH</c> environment variable.
     /// </summary>
     public int MaxAlarmsPerFetch { get; init; } = 1024;

src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayOptionsValidator.cs

@@ -427,23 +427,35 @@ public sealed class GatewayOptionsValidator : OptionsValidatorBase<GatewayOption
     private static readonly string[] ValidAlarmFallbackModes = ["Auto", "ForceAlarmManager", "ForceSubtag"];
 
     private const int MinimumAlarmPollIntervalMilliseconds = 100;
+
+    // One hour. Above this the cadence stops being a cadence: int.MaxValue
+    // milliseconds is ~24 days, which silently disables alarm polling instead
+    // of reporting the misconfiguration.
+    private const int MaximumAlarmPollIntervalMilliseconds = 3_600_000;
+
     private const int MinimumMaxAlarmsPerFetch = 64;
 
+    // The worker is a 32-bit process and materializes each fetch as one BSTR
+    // plus a full XmlDocument over it, so an unbounded cap is an out-of-memory
+    // fault on the STA rather than a slow poll.
+    private const int MaximumMaxAlarmsPerFetch = 65_536;
+
     private static void ValidateAlarms(AlarmsOptions options, ValidationBuilder builder)
     {
         // Validated regardless of Enabled: both values are stamped onto every
         // worker launch environment, so a bad value is a misconfiguration even
         // before the central monitor is switched on.
-        if (options.PollIntervalMilliseconds < MinimumAlarmPollIntervalMilliseconds)
+        if (options.PollIntervalMilliseconds is < MinimumAlarmPollIntervalMilliseconds
+            or > MaximumAlarmPollIntervalMilliseconds)
         {
             builder.Add(
-                $"MxGateway:Alarms:PollIntervalMilliseconds must be greater than or equal to {MinimumAlarmPollIntervalMilliseconds}.");
+                $"MxGateway:Alarms:PollIntervalMilliseconds must be between {MinimumAlarmPollIntervalMilliseconds} and {MaximumAlarmPollIntervalMilliseconds}.");
         }
 
-        if (options.MaxAlarmsPerFetch < MinimumMaxAlarmsPerFetch)
+        if (options.MaxAlarmsPerFetch is < MinimumMaxAlarmsPerFetch or > MaximumMaxAlarmsPerFetch)
         {
             builder.Add(
-                $"MxGateway:Alarms:MaxAlarmsPerFetch must be greater than or equal to {MinimumMaxAlarmsPerFetch}.");
+                $"MxGateway:Alarms:MaxAlarmsPerFetch must be between {MinimumMaxAlarmsPerFetch} and {MaximumMaxAlarmsPerFetch}.");
         }
 
         if (!options.Enabled)

src/ZB.MOM.WW.MxGateway.Server/appsettings.json

@@ -86,7 +86,9 @@
       "Enabled": true,
       "SubscriptionExpression": "\\\\DESKTOP-6JL3KKO\\Galaxy!DEV",
       "DefaultArea": "",
-      "ReconcileIntervalSeconds": 30
+      "ReconcileIntervalSeconds": 30,
+      "PollIntervalMilliseconds": 500,
+      "MaxAlarmsPerFetch": 1024
     }
   }
 }