From 37aadf72b38d8bd6b71f37ffb86b4cc4e73ab763 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Sun, 14 Jun 2026 02:33:14 -0400 Subject: [PATCH] docs(alarms): clarify resolver cancellation contract; mark design doc superseded MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C6b: IAlarmWatchListResolver.ResolveAsync doc now notes that while discovery being unavailable never throws, a triggered cancellation token still propagates. C7: annotate the original design doc where it drifted from the shipped code — metric names / unimplemented watch-list gauges, and the proto-type location (gateway proto, not worker proto). --- .../2026-06-13-alarm-subtag-fallback-design.md | 16 +++++++++++++++- .../Alarms/IAlarmWatchListResolver.cs | 6 ++++-- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/plans/2026-06-13-alarm-subtag-fallback-design.md b/docs/plans/2026-06-13-alarm-subtag-fallback-design.md index a1382b1..6981af1 100644 --- a/docs/plans/2026-06-13-alarm-subtag-fallback-design.md +++ b/docs/plans/2026-06-13-alarm-subtag-fallback-design.md @@ -1,7 +1,10 @@ # Alarm Subtag-Monitoring Fallback — Design **Date:** 2026-06-13 -**Status:** Approved (brainstorming), ready for implementation planning +**Status:** Superseded by implementation (merged to `main`). This is the original +brainstorming design; a few details below were refined during implementation — +see the inline **Superseded** notes. The shipped behaviour is documented in +`docs/AlarmClientDiscovery.md`, the client READMEs, and the contracts. **Branch:** `feat/alarm-subtag-fallback` ## Problem @@ -162,6 +165,11 @@ reconcile cadence and pushes an updated watch-list when the model changes. **`mxaccess_worker.proto`:** +> **Superseded:** these additions shipped in `mxaccess_gateway.proto`, not +> `mxaccess_worker.proto` — the worker imports the gateway proto and the alarm +> commands/events live there (`AlarmSubtagTarget`, +> `OnAlarmProviderModeChangedEvent`, the extended subscribe command). + - Extend the alarm-subscribe command with: `AlarmProviderMode forced_mode` (`UNSPECIFIED` = auto), `int32 consecutive_failure_threshold`, `int32 failback_probe_interval_seconds`, `int32 failback_stable_probes`, and @@ -240,6 +248,12 @@ to `/hubs/alarms`, (c) update metrics, (d) force a reconcile. - `mxgateway_alarm_provider_switch_total{from,to,reason}` (counter) - `mxgateway_alarm_fallback_watchlist_size` (gauge) +> **Superseded:** the shipped meter names are `mxgateway.alarms.provider_mode` +> (gauge) and `mxgateway.alarms.provider_switches{from,to,reason}` (counter, +> `reason` bounded to `failover`/`failback`/`unknown`). The watch-list-size / +> watch-list-empty gauges were not implemented; an empty watch-list is surfaced +> via a warning log and the feed's degraded `ProviderStatus` instead. + ## Configuration ```jsonc diff --git a/src/ZB.MOM.WW.MxGateway.Server/Alarms/IAlarmWatchListResolver.cs b/src/ZB.MOM.WW.MxGateway.Server/Alarms/IAlarmWatchListResolver.cs index 7581d5c..196b2b8 100644 --- a/src/ZB.MOM.WW.MxGateway.Server/Alarms/IAlarmWatchListResolver.cs +++ b/src/ZB.MOM.WW.MxGateway.Server/Alarms/IAlarmWatchListResolver.cs @@ -19,8 +19,10 @@ public interface IAlarmWatchListResolver /// Token to cancel the asynchronous operation. /// /// The resolved watch-list, possibly empty. - /// Discovery being unavailable never throws; the caller decides what to do - /// with an empty list. + /// Discovery being unavailable never throws — it yields an empty (or + /// config-only) list and the caller decides what to do with it. Cancellation + /// is the one exception: a triggered + /// still propagates an . /// Task> ResolveAsync( AlarmsOptions options,