feat: add offline recovery timer with 10 s polling

When a NETWORK_ERROR or TIMEOUT is encountered, pause the normal
refresh schedule and start a 10-second polling loop that retries
until connectivity is restored, then resume the configured interval.

- Add recoveryTimer / recoveryActive module state
- startRecoveryTimer(): pause normal refresh, begin 10 s retry loop
- _scheduleNextRecovery(): recursive setTimeout; clean gap after each attempt
- clearRecoveryTimer(): stop recovery, restore normal setInterval
- Guard resetTimer() with `if (recoveryActive) return` to prevent
  competing timers during config changes while offline
- Extend _getState() with recoveryTimerActive / refreshTimerActive
  flags and expose lifecycle helpers for test-only use
- Add 7 unit tests covering timer lifecycle, idempotency, and
  auto-stop on reconnect (vi.useFakeTimers)

Author: euxx

src/extension.js

@@ -22,6 +22,10 @@ let deactivated = false;
 let isOffline = false;
 /** @type {Date | null} */
 let offlineSince = null;
+/** @type {NodeJS.Timeout | undefined} */
+let recoveryTimer;
+/** @type {boolean} */
+let recoveryActive = false;
 
 /**
  * @param {vscode.ExtensionContext} context
@@ -58,6 +62,7 @@ function deactivate() {
   offlineSince = null;
   statusBarItem?.hide();
   clearTimer();
+  clearRecoveryTimer();
 }
 
 // ---------------------------------------------------------------------------
@@ -104,6 +109,7 @@ async function refresh(promptSignIn = false, isManual = false) {
     lastUpdatedAt = new Date();
     isOffline = false;
     offlineSince = null;
+    clearRecoveryTimer();
     updateStatusBar(data);
   } catch (err) {
     const code = err?.code;
@@ -112,6 +118,7 @@ async function refresh(promptSignIn = false, isManual = false) {
     if (code !== 'NETWORK_ERROR' && code !== 'TIMEOUT') {
       isOffline = false;
       offlineSince = null;
+      clearRecoveryTimer();
     }
 
     if (code === 'AUTH') {
@@ -135,6 +142,7 @@ async function refresh(promptSignIn = false, isManual = false) {
       if (!isOffline) {
         isOffline = true;
         offlineSince = new Date();
+        startRecoveryTimer();
       }
       if (lastData) {
         updateStatusBar(lastData);
@@ -300,6 +308,7 @@ function renderStatus({ text, tooltip, command = undefined, color = undefined })
 // ---------------------------------------------------------------------------
 
 function resetTimer() {
+  if (recoveryActive) return; // recovery mode owns the schedule; don't create a competing timer
   clearTimer();
   const { refreshIntervalMinutes } = getConfig();
   const n = Number(refreshIntervalMinutes);
@@ -314,6 +323,42 @@ function clearTimer() {
   }
 }
 
+const RECOVERY_INTERVAL_MS = 10 * 1000; // 10 s
+
+function startRecoveryTimer() {
+  if (recoveryActive) return; // already running
+  clearTimer(); // pause normal refresh while in recovery mode
+  recoveryActive = true;
+  _scheduleNextRecovery();
+}
+
+/** Schedule one recovery attempt after RECOVERY_INTERVAL_MS.
+ *  After the attempt completes (success, error, or timeout), reschedules itself
+ *  if still in recovery mode — giving a clean 10 s gap after every outcome.
+ */
+function _scheduleNextRecovery() {
+  recoveryTimer = setTimeout(async () => {
+    recoveryTimer = undefined; // this timeout has fired
+    if (!recoveryActive) return; // clearRecoveryTimer() was called while we were waiting
+    if (!isOffline) {
+      clearRecoveryTimer();
+      return;
+    }
+    await refresh().catch(() => {}); // refresh() handles errors internally; .catch prevents stuck recovery on unexpected throw
+    if (recoveryActive) _scheduleNextRecovery(); // still offline → retry in 10 s
+  }, RECOVERY_INTERVAL_MS);
+}
+
+function clearRecoveryTimer() {
+  if (!recoveryActive) return;
+  recoveryActive = false;
+  if (recoveryTimer) {
+    clearTimeout(recoveryTimer);
+    recoveryTimer = undefined;
+  }
+  if (!deactivated) resetTimer(); // restore normal refresh schedule
+}
+
 // ---------------------------------------------------------------------------
 // Config helper
 // ---------------------------------------------------------------------------
@@ -358,5 +403,15 @@ module.exports = {
     if ('lastData' in s) lastData = s.lastData;
     if ('lastUpdatedAt' in s) lastUpdatedAt = s.lastUpdatedAt;
   },
-  _getState: () => ({ isOffline, offlineSince }),
+  _getState: () => ({
+    isOffline,
+    offlineSince,
+    recoveryTimerActive: recoveryActive,
+    refreshTimerActive: !!refreshTimer,
+  }),
+  // Test-only: directly invoke timer lifecycle.
+  _startRecoveryTimer: startRecoveryTimer,
+  _clearRecoveryTimer: clearRecoveryTimer,
+  _resetTimer: resetTimer,
+  _clearTimer: clearTimer,
 };

tests/extension.test.js

@@ -1,6 +1,17 @@
 'use strict';
 
-const { formatTimestamp, getConfig, buildTooltip, computeIsStale, _setState, _getState } = require('../src/extension');
+const {
+  formatTimestamp,
+  getConfig,
+  buildTooltip,
+  computeIsStale,
+  _setState,
+  _getState,
+  _startRecoveryTimer,
+  _clearRecoveryTimer,
+  _resetTimer,
+  _clearTimer,
+} = require('../src/extension');
 
 // ---------------------------------------------------------------------------
 // formatTimestamp
@@ -218,3 +229,75 @@ describe('offline state transitions', () => {
     expect(computeIsStale(isOffline, offlineSince)).toBe(true);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Recovery timer lifecycle
+// ---------------------------------------------------------------------------
+
+describe('recovery timer', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    // Reset all state and ensure no timer is running.
+    _setState({ isOffline: false, offlineSince: null, lastData: null, lastUpdatedAt: null });
+    _clearRecoveryTimer(); // may call resetTimer internally
+    _clearTimer(); // ensure normal refresh timer is also cleared
+  });
+
+  afterEach(() => {
+    _clearRecoveryTimer(); // may call resetTimer internally
+    _clearTimer(); // clear any refreshTimer left by resetTimer()
+    vi.useRealTimers();
+  });
+
+  it('startRecoveryTimer pauses the normal refresh timer (refreshTimerActive = false)', () => {
+    _startRecoveryTimer();
+    expect(_getState().refreshTimerActive).toBe(false);
+  });
+
+  it('calling startRecoveryTimer twice does not create a second timer', () => {
+    _startRecoveryTimer();
+    const spy = vi.spyOn(global, 'setTimeout');
+    _startRecoveryTimer();
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it('clearRecoveryTimer sets recoveryTimerActive = false', () => {
+    _startRecoveryTimer();
+    _clearRecoveryTimer();
+    expect(_getState().recoveryTimerActive).toBe(false);
+  });
+
+  it('clearRecoveryTimer restores the normal refresh timer (refreshTimerActive = true)', () => {
+    _startRecoveryTimer();
+    _clearRecoveryTimer();
+    expect(_getState().refreshTimerActive).toBe(true);
+  });
+
+  it('clearRecoveryTimer when no timer is active is a no-op', () => {
+    expect(() => _clearRecoveryTimer()).not.toThrow();
+    expect(_getState().recoveryTimerActive).toBe(false);
+  });
+
+  it('resetTimer is a no-op while recovery mode is active (no competing timer)', () => {
+    _startRecoveryTimer();
+    expect(_getState().refreshTimerActive).toBe(false);
+    // Simulate onDidChangeConfiguration calling resetTimer while offline.
+    _resetTimer();
+    // Should still have only the recovery timer — no competing normal refresh timer.
+    expect(_getState().refreshTimerActive).toBe(false);
+    expect(_getState().recoveryTimerActive).toBe(true);
+  });
+
+  it('timer callback stops recovery and restores normal timer when back online', async () => {
+    // isOffline is already false (default) — simulates connection restored before first tick.
+    _startRecoveryTimer();
+    expect(_getState().recoveryTimerActive).toBe(true);
+
+    // Advance past the 10 s interval; the callback runs, sees !isOffline, stops recovery.
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(_getState().recoveryTimerActive).toBe(false);
+    expect(_getState().refreshTimerActive).toBe(true);
+  });
+});