refactor: unify HA Discovery retry state into a single map

HaDiscovery tracked TREEXML retry plumbing across two parallel Maps
(_treeWatchdogs and _treeRetryState) keyed identically on networkId,
with three near-duplicate cleanup helpers and a keepAttempts boolean
toggle that smelled of squashed operations.

Collapse to a single _treeRequestState Map whose value is
{ attempts, watchdogHandle, retryHandle }. The cleanup helpers reduce
to one parameterised _clearTimer and a _clearTreeState entry-killer;
the boolean parameter goes away. handleTreeStart's "successful response"
path is now a single _clearTreeState call, which both releases timers
and resets the attempts counter for any future failure.

Drop the typeof === 'function' guards in BridgeInitializationService
around haDiscovery.handleCommandError and haDiscovery.stop — both are
part of the class contract and the bridge holds a locally constructed
instance, so the guards traded clarity for hypothetical safety. The
test mock is updated to match the contract.

Behaviour unchanged; full suite (1172 tests) passes.

Bumps to 1.8.3.

Author: dougrathbone

homeassistant-addon/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to the C-Gate Web Bridge Home Assistant add-on will be docum
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.3] - 2026-05-04
+
+### Refactor
+- **HA Discovery retry state**: collapsed the parallel `_treeWatchdogs` and `_treeRetryState` Maps in `HaDiscovery` into a single `_treeRequestState` Map (`networkId -> { attempts, watchdogHandle, retryHandle }`), eliminating duplicate lookups, an awkward `keepAttempts` boolean parameter, and three near-duplicate cleanup helpers. Behaviour is unchanged.
+- Removed unnecessary `typeof === 'function'` guards around `haDiscovery.handleCommandError` and `haDiscovery.stop` calls in `BridgeInitializationService`; the methods are part of the class contract and the bridge holds a locally constructed instance.
+
 ## [1.8.2] - 2026-05-04
 
 ### Fixed

homeassistant-addon/config.yaml

@@ -1,5 +1,5 @@
 name: "C-Gate Web Bridge"
-version: "1.8.2"
+version: "1.8.3"
 slug: cgateweb
 description: "Bridge between Clipsal C-Bus systems and MQTT/Home Assistant"
 url: "https://github.com/dougrathbone/cgateweb"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cgateweb",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "Node.js bridge connecting Clipsal C-Bus automation systems to MQTT for Home Assistant integration",
   "keywords": [
     "cbus",

src/bridgeInitializationService.js

@@ -309,7 +309,7 @@ class BridgeInitializationService {
      * that fail because C-Gate hasn't finished loading networks at startup.
      */
     handleCommandError(code, statusData) {
-        if (this.bridge.haDiscovery && typeof this.bridge.haDiscovery.handleCommandError === 'function') {
+        if (this.bridge.haDiscovery) {
             this.bridge.haDiscovery.handleCommandError(code, statusData);
         }
 
@@ -344,9 +344,7 @@ class BridgeInitializationService {
         this.bridge.labelLoader.unwatch();
 
         if (this.bridge.haDiscovery) {
-            if (typeof this.bridge.haDiscovery.stop === 'function') {
-                this.bridge.haDiscovery.stop();
-            }
+            this.bridge.haDiscovery.stop();
             this.bridge.haDiscovery.removeAllListeners?.();
             this.bridge.haDiscovery = null;
             this.bridge.commandResponseProcessor.haDiscovery = null;

src/haDiscovery.js

@@ -72,11 +72,11 @@ class HaDiscovery {
 
         // C-Gate accepts TCP connections on the command port before its project
         // networks are loaded. Initial TREEXML can therefore return 401 "Network
-        // not found" until C-Gate finishes startup. These maps drive a
+        // not found" until C-Gate finishes startup. This map drives a
         // per-network retry loop with exponential backoff so HA Discovery
         // recovers automatically without restarting the bridge.
-        this._treeWatchdogs = new Map();   // networkId -> timeoutHandle
-        this._treeRetryState = new Map();  // networkId -> { attempts, retryHandle }
+        // networkId -> { attempts, watchdogHandle, retryHandle }
+        this._treeRequestState = new Map();
         this._maxTreeRetryAttempts = 8;
         this._treeRetryInitialDelayMs = 2000;
         this._treeRetryMaxDelayMs = 60000;
@@ -157,9 +157,11 @@ class HaDiscovery {
 
     queueTreeRequest(networkId) {
         const normalizedNetwork = String(networkId);
+        const state = this._getOrCreateTreeState(normalizedNetwork);
 
-        // Cancel any pending retry timer — we're sending a fresh request now.
-        this._cancelTreeRetry(normalizedNetwork, /* keepAttempts */ true);
+        // Sending a fresh request: clear any pending retry but keep the
+        // attempts counter so backoff continues if this attempt also fails.
+        this._clearTimer(state, 'retryHandle');
 
         this.logger.info(`Requesting TreeXML for network ${normalizedNetwork}...`);
 
@@ -168,40 +170,45 @@ class HaDiscovery {
             this.pendingTreeNetworks.push(normalizedNetwork);
         }
 
-        this._armTreeWatchdog(normalizedNetwork);
-        this._sendCommand(`${CGATE_CMD_TREEXML} ${normalizedNetwork}${NEWLINE}`);
-    }
+        this._clearTimer(state, 'watchdogHandle');
+        state.watchdogHandle = this._setTimer(this._treeRequestTimeoutMs, () => {
+            state.watchdogHandle = null;
+            this._handleTreeRequestFailure(normalizedNetwork, 'no response within timeout');
+        });
 
-    _armTreeWatchdog(networkId) {
-        this._cancelTreeWatchdog(networkId);
-        const handle = setTimeout(() => {
-            this._treeWatchdogs.delete(networkId);
-            this._handleTreeRequestFailure(networkId, 'no response within timeout');
-        }, this._treeRequestTimeoutMs);
-        if (typeof handle.unref === 'function') handle.unref();
-        this._treeWatchdogs.set(networkId, handle);
+        this._sendCommand(`${CGATE_CMD_TREEXML} ${normalizedNetwork}${NEWLINE}`);
     }
 
-    _cancelTreeWatchdog(networkId) {
-        const handle = this._treeWatchdogs.get(networkId);
-        if (handle) {
-            clearTimeout(handle);
-            this._treeWatchdogs.delete(networkId);
+    _getOrCreateTreeState(networkId) {
+        let state = this._treeRequestState.get(networkId);
+        if (!state) {
+            state = { attempts: 0, watchdogHandle: null, retryHandle: null };
+            this._treeRequestState.set(networkId, state);
         }
+        return state;
     }
 
-    _cancelTreeRetry(networkId, keepAttempts = false) {
-        const state = this._treeRetryState.get(networkId);
+    _clearTreeState(networkId) {
+        const state = this._treeRequestState.get(networkId);
         if (!state) return;
-        if (state.retryHandle) {
-            clearTimeout(state.retryHandle);
-            state.retryHandle = null;
-        }
-        if (!keepAttempts) {
-            this._treeRetryState.delete(networkId);
+        this._clearTimer(state, 'watchdogHandle');
+        this._clearTimer(state, 'retryHandle');
+        this._treeRequestState.delete(networkId);
+    }
+
+    _clearTimer(state, key) {
+        if (state[key]) {
+            clearTimeout(state[key]);
+            state[key] = null;
         }
     }
 
+    _setTimer(delayMs, fn) {
+        const handle = setTimeout(fn, delayMs);
+        if (typeof handle.unref === 'function') handle.unref();
+        return handle;
+    }
+
     /**
      * Receives a 4xx/5xx C-Gate command error and, if it indicates that an
      * in-flight TreeXML request failed because the network isn't loaded yet,
@@ -220,12 +227,13 @@ class HaDiscovery {
         if (this.pendingTreeNetworks.length === 0) return;
 
         const failedNetwork = this.pendingTreeNetworks.shift();
-        this._cancelTreeWatchdog(failedNetwork);
+        const state = this._treeRequestState.get(failedNetwork);
+        if (state) this._clearTimer(state, 'watchdogHandle');
         this._handleTreeRequestFailure(failedNetwork, '401 Network not found');
     }
 
     _handleTreeRequestFailure(networkId, reason) {
-        const state = this._treeRetryState.get(networkId) || { attempts: 0, retryHandle: null };
+        const state = this._getOrCreateTreeState(networkId);
         state.attempts += 1;
 
         if (state.attempts > this._maxTreeRetryAttempts) {
@@ -234,7 +242,7 @@ class HaDiscovery {
                 `Auto-discovery for this network is paused. ` +
                 `Verify the network is configured and reachable in C-Gate, then restart the bridge or publish to cbus/write/${networkId}///gettree to retry.`
             );
-            this._treeRetryState.delete(networkId);
+            this._clearTreeState(networkId);
             return;
         }
 
@@ -249,27 +257,20 @@ class HaDiscovery {
             `This typically means C-Gate is still loading networks at startup.`
         );
 
-        if (state.retryHandle) clearTimeout(state.retryHandle);
-        state.retryHandle = setTimeout(() => {
+        this._clearTimer(state, 'retryHandle');
+        state.retryHandle = this._setTimer(delay, () => {
             state.retryHandle = null;
             this.queueTreeRequest(networkId);
-        }, delay);
-        if (typeof state.retryHandle.unref === 'function') state.retryHandle.unref();
-        this._treeRetryState.set(networkId, state);
+        });
     }
 
     /**
      * Cancels all retry timers and watchdogs. Call on bridge shutdown.
      */
     stop() {
-        for (const handle of this._treeWatchdogs.values()) {
-            clearTimeout(handle);
-        }
-        this._treeWatchdogs.clear();
-        for (const state of this._treeRetryState.values()) {
-            if (state.retryHandle) clearTimeout(state.retryHandle);
+        for (const networkId of [...this._treeRequestState.keys()]) {
+            this._clearTreeState(networkId);
         }
-        this._treeRetryState.clear();
     }
 
     handleTreeStart(_statusData) {
@@ -280,10 +281,10 @@ class HaDiscovery {
         const nextNetwork = this.pendingTreeNetworks.shift() || this.treeNetwork || 'unknown';
         const networkKey = String(nextNetwork);
 
-        // The request succeeded — cancel watchdog and any pending retry so a
-        // late retry doesn't issue a redundant TREEXML.
-        this._cancelTreeWatchdog(networkKey);
-        this._cancelTreeRetry(networkKey);
+        // The request succeeded — drop watchdog and any pending retry so a
+        // late retry doesn't issue a redundant TREEXML, and reset the attempts
+        // counter for any future failure on this network.
+        this._clearTreeState(networkKey);
 
         this.activeTreeSession = {
             network: networkKey,

tests/bridgeInitializationService.test.js

@@ -58,7 +58,9 @@ describe('BridgeInitializationService', () => {
         HaDiscovery.mockClear();
         HaDiscovery.mockImplementation(() => ({
             trigger: jest.fn(),
-            updateLabels: jest.fn()
+            updateLabels: jest.fn(),
+            handleCommandError: jest.fn(),
+            stop: jest.fn()
         }));
     });
 

tests/haDiscovery.test.js

@@ -602,6 +602,9 @@ describe('HaDiscovery', () => {
             const errMsg = 'Bad object or device ID: Network not found';
 
             // 8 retries permitted; the 9th failure exhausts the budget.
+            // runOnlyPendingTimers fires just the scheduled retry (which
+            // arms a fresh watchdog) — the next handleCommandError cancels
+            // that watchdog before it can fire and double-count attempts.
             for (let i = 1; i <= 8; i++) {
                 haDiscovery.handleCommandError('401', errMsg);
                 jest.runOnlyPendingTimers();
@@ -637,8 +640,7 @@ describe('HaDiscovery', () => {
             haDiscovery.handleTreeEnd('end');
 
             // Watchdog and retry state should now be cleared.
-            expect(haDiscovery._treeWatchdogs.size).toBe(0);
-            expect(haDiscovery._treeRetryState.size).toBe(0);
+            expect(haDiscovery._treeRequestState.size).toBe(0);
 
             // Advance time well past any potential retry — no extra commands.
             const callsBefore = mockSendCommandFn.mock.calls.length;
@@ -666,11 +668,10 @@ describe('HaDiscovery', () => {
         it('stop() clears all retry timers and watchdogs', () => {
             haDiscovery.trigger();
             haDiscovery.handleCommandError('401', 'Bad object or device ID: Network not found');
-            expect(haDiscovery._treeRetryState.size).toBe(1);
+            expect(haDiscovery._treeRequestState.size).toBe(1);
 
             haDiscovery.stop();
-            expect(haDiscovery._treeWatchdogs.size).toBe(0);
-            expect(haDiscovery._treeRetryState.size).toBe(0);
+            expect(haDiscovery._treeRequestState.size).toBe(0);
 
             const callsBefore = mockSendCommandFn.mock.calls.length;
             jest.advanceTimersByTime(120000);