@xiboplayer/xmds 0.7.17 → 0.7.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/xmds",
-  "version": "0.7.17",
+  "version": "0.7.19",
   "description": "XMDS SOAP client for Xibo CMS communication",
   "type": "module",
   "main": "./src/index.js",
@@ -12,7 +12,7 @@
     "./schedule-parser": "./src/schedule-parser.js"
   },
   "dependencies": {
-    "@xiboplayer/utils": "0.7.17"
+    "@xiboplayer/utils": "0.7.19"
   },
   "devDependencies": {
     "vitest": "^4.1.2"

package/src/protocol-detector.js

@@ -8,22 +8,30 @@
  *   - SOAP/XMDS — universal XML protocol (any vanilla Xibo CMS)
  *
  * Detection logic:
- *   1. GET {cmsUrl}${PLAYER_API}/health with a 3-second timeout
+ *   1. GET {cmsUrl}${PLAYER_API}/health with a generous timeout
  *   2. If 200 + valid JSON → REST
  *   3. If 404/error/timeout → SOAP (fallback)
  *
- * The detected protocol is cached and can be re-probed on connection errors.
+ * After a fallback to XMDS, the detector can run an automatic background
+ * re-probe loop with exponential backoff so the player promotes back to
+ * REST as soon as the CMS recovers. The re-probe loop also acts as a
+ * visibility signal: each failed probe emits a warning that names the
+ * next attempt, so it's obvious at a glance that the player is still
+ * running on the wrong transport.
  *
  * @example
- *   import { ProtocolDetector } from '@xiboplayer/xmds';
- *   import { RestClient, XmdsClient } from '@xiboplayer/xmds';
+ *   import { ProtocolDetector, RestClient, XmdsClient } from '@xiboplayer/xmds';
  *
  *   const detector = new ProtocolDetector(config.cmsUrl, RestClient, XmdsClient);
- *   const xmds = await detector.detect(config);
- *   // xmds is either a RestClient or XmdsClient instance
+ *   const { client, protocol } = await detector.detect(config);
+ *   let xmds = client;
  *
- *   // On connection errors, re-probe:
- *   const newXmds = await detector.reprobe(config);
+ *   if (protocol === 'xmds') {
+ *     detector.startAutoReprobe(config, (newClient) => {
+ *       // REST recovered — swap the live client pointer
+ *       xmds = newClient;
+ *     });
+ *   }
  */
 
 import { createLogger } from '@xiboplayer/utils';
@@ -31,8 +39,30 @@ import { assertCmsClient } from './cms-client.js';
 
 const log = createLogger('Protocol');
 
-/** Default probe timeout in milliseconds */
-const PROBE_TIMEOUT_MS = 3000;
+/**
+ * Default timeout for the FIRST probe at startup.
+ * Intentionally generous: a cold CMS has to warm up PHP-FPM workers,
+ * negotiate TLS, populate OpCache, and possibly fill MariaDB query plan
+ * caches. Empirically a healthy cold CMS can take 5-6 seconds on the
+ * very first request after a restart — the old 3000ms default was too
+ * tight and would lock the player into XMDS fallback on cold start.
+ */
+const FIRST_PROBE_TIMEOUT_MS = 10000;
+
+/**
+ * Default timeout for re-probes after fallback is engaged.
+ * Shorter than the first probe because by the time we're re-probing we
+ * already know the CMS was reachable at some point — either it's up
+ * now or it isn't.
+ */
+const REPROBE_TIMEOUT_MS = 5000;
+
+/** Starting delay before the first auto-reprobe after XMDS fallback. */
+const REPROBE_MIN_DELAY_MS = 5000;
+/** Ceiling delay for the backoff — we re-probe at least this often forever. */
+const REPROBE_MAX_DELAY_MS = 120000;
+/** Exponential factor applied after each failed reprobe. */
+const REPROBE_BACKOFF_FACTOR = 2;
 
 export class ProtocolDetector {
   /**
@@ -40,29 +70,50 @@ export class ProtocolDetector {
    * @param {typeof import('./rest-client.js').RestClient} RestClientClass - RestClient constructor
    * @param {typeof import('./xmds-client.js').XmdsClient} XmdsClientClass - XmdsClient constructor
    * @param {Object} [options]
-   * @param {number} [options.probeTimeoutMs=3000] - Timeout for health probe
+   * @param {number} [options.firstProbeTimeoutMs=10000] - Timeout for the initial probe
+   * @param {number} [options.reprobeTimeoutMs=5000] - Timeout for re-probes after fallback
+   * @param {number} [options.probeTimeoutMs] - Back-compat: sets BOTH first and reprobe timeouts to the same value
+   * @param {number} [options.reprobeMinDelayMs=5000] - Initial delay before the first auto-reprobe
+   * @param {number} [options.reprobeMaxDelayMs=120000] - Ceiling delay between auto-reprobes
    */
   constructor(cmsUrl, RestClientClass, XmdsClientClass, options = {}) {
     this.cmsUrl = cmsUrl;
     this.RestClient = RestClientClass;
     this.XmdsClient = XmdsClientClass;
-    this.probeTimeoutMs = options.probeTimeoutMs || PROBE_TIMEOUT_MS;
+
+    // Back-compat: if a single probeTimeoutMs is provided, use it for both
+    // first and reprobe. New callers should pass the split options.
+    const legacy = options.probeTimeoutMs;
+    this.firstProbeTimeoutMs = options.firstProbeTimeoutMs ?? legacy ?? FIRST_PROBE_TIMEOUT_MS;
+    this.reprobeTimeoutMs = options.reprobeTimeoutMs ?? legacy ?? REPROBE_TIMEOUT_MS;
+
+    this.reprobeMinDelayMs = options.reprobeMinDelayMs ?? REPROBE_MIN_DELAY_MS;
+    this.reprobeMaxDelayMs = options.reprobeMaxDelayMs ?? REPROBE_MAX_DELAY_MS;
 
     /** @type {'rest'|'xmds'|null} Detected protocol (null = not yet probed) */
     this.protocol = null;
 
-    /** @type {number} Timestamp of last successful probe */
+    /** @type {number} Timestamp of last probe attempt */
     this.lastProbeTime = 0;
+
+    /** @type {ReturnType<typeof setTimeout>|null} Scheduled auto-reprobe timer */
+    this._reprobeTimer = null;
+
+    /** @type {number} Current backoff delay (ms) — resets on successful probe or stop */
+    this._reprobeDelay = this.reprobeMinDelayMs;
   }
 
   /**
    * Probe the CMS health endpoint to determine protocol availability.
+   * @param {Object} [opts]
+   * @param {boolean} [opts.first=false] - Use the longer first-probe timeout
    * @returns {Promise<boolean>} true if REST/PlayerRestApi is available
    */
-  async probe() {
+  async probe(opts = {}) {
+    const timeoutMs = opts.first ? this.firstProbeTimeoutMs : this.reprobeTimeoutMs;
     const available = await this.RestClient.isAvailable(this.cmsUrl, {
       maxRetries: 0,
-      timeoutMs: this.probeTimeoutMs,
+      timeoutMs,
     });
     this.lastProbeTime = Date.now();
     return available;
@@ -70,8 +121,8 @@ export class ProtocolDetector {
 
   /**
    * Detect the best protocol and create the appropriate client.
-   * On first call, probes the CMS. On subsequent calls, returns the cached
-   * protocol unless reprobe() is called.
+   * On first call, probes the CMS with the generous first-probe timeout.
+   * On subsequent calls, returns the cached protocol unless reprobe() is called.
    *
    * @param {Object} config - Player configuration (passed to client constructor)
    * @param {string} [forceProtocol] - 'rest'|'xmds' to skip detection
@@ -95,10 +146,10 @@ export class ProtocolDetector {
     }
 
     // Auto-detect
-    log.info('Probing CMS for REST API availability...');
+    log.info(`Probing CMS for REST API availability (timeout ${this.firstProbeTimeoutMs}ms)...`);
     let isRest = false;
     try {
-      isRest = await this.probe();
+      isRest = await this.probe({ first: true });
     } catch (e) {
       log.warn('REST probe failed:', e?.message || e);
     }
@@ -112,15 +163,16 @@ export class ProtocolDetector {
     }
 
     this.protocol = 'xmds';
-    log.info('REST unavailable — using XMDS/SOAP transport');
+    log.warn('REST unavailable — falling back to XMDS/SOAP transport');
     const client = new this.XmdsClient(config);
     assertCmsClient(client, 'XmdsClient');
     return { client, protocol: 'xmds' };
   }
 
   /**
-   * Re-probe the CMS and potentially switch protocols.
-   * Called on connection errors to check if the CMS was upgraded/downgraded.
+   * Re-probe the CMS once and potentially switch protocols.
+   * Called either externally on connection errors, or internally by the
+   * auto-reprobe loop.
    *
    * @param {Object} config - Player configuration
    * @returns {Promise<{client: any, protocol: 'rest'|'xmds', changed: boolean}>}
@@ -128,10 +180,9 @@ export class ProtocolDetector {
   async reprobe(config) {
     const previousProtocol = this.protocol;
 
-    log.info('Re-probing CMS protocol...');
     let isRest = false;
     try {
-      isRest = await this.probe();
+      isRest = await this.probe({ first: false });
     } catch (e) {
       log.warn('Re-probe failed:', e?.message || e);
     }
@@ -147,10 +198,88 @@ export class ProtocolDetector {
       return { client, protocol: newProtocol, changed: true };
     }
 
-    log.info(`Protocol unchanged: ${newProtocol}`);
     return { client: null, protocol: newProtocol, changed: false };
   }
 
+  /**
+   * Start an automatic background re-probe loop while on XMDS fallback.
+   * Uses exponential backoff from reprobeMinDelayMs up to reprobeMaxDelayMs
+   * (defaults: 5s → 2min). Each failed reprobe logs a visibility warning
+   * that names the current fallback state and the next probe time, so an
+   * operator reading the log after any interval can see at a glance that
+   * the player is still running on the wrong transport.
+   *
+   * When a reprobe succeeds (detects REST is back), the callback is invoked
+   * with the new client and the loop stops. No-op if the current protocol
+   * is not 'xmds'.
+   *
+   * @param {Object} config - Player configuration passed to reprobe()
+   * @param {(client: any) => void} onRestPromoted - Called when REST recovers
+   */
+  startAutoReprobe(config, onRestPromoted) {
+    if (this.protocol !== 'xmds') {
+      // Only meaningful while in fallback
+      return;
+    }
+    // Cancel any existing timer before scheduling a fresh one
+    this.stopAutoReprobe();
+    this._reprobeDelay = this.reprobeMinDelayMs;
+
+    const schedule = () => {
+      const nextInMs = this._reprobeDelay;
+      this._reprobeTimer = setTimeout(async () => {
+        this._reprobeTimer = null;
+        let result;
+        try {
+          result = await this.reprobe(config);
+        } catch (e) {
+          log.warn('Auto-reprobe error:', e?.message || e);
+          result = { changed: false, protocol: 'xmds', client: null };
+        }
+
+        if (result.changed && result.protocol === 'rest') {
+          log.info('REST recovered — promoting back from XMDS fallback');
+          this._reprobeDelay = this.reprobeMinDelayMs;
+          try {
+            onRestPromoted(result.client);
+          } catch (e) {
+            log.warn('onRestPromoted callback threw:', e?.message || e);
+          }
+          return; // stop — we're back on REST
+        }
+
+        // Still on XMDS — back off and try again
+        const nextDelay = Math.min(
+          this._reprobeDelay * REPROBE_BACKOFF_FACTOR,
+          this.reprobeMaxDelayMs,
+        );
+        log.warn(
+          `Still on XMDS fallback — REST probe failed, next attempt in ${Math.round(nextDelay / 1000)}s`,
+        );
+        this._reprobeDelay = nextDelay;
+        schedule();
+      }, nextInMs);
+    };
+
+    log.info(
+      `Auto-reprobe scheduled — first attempt in ${Math.round(this._reprobeDelay / 1000)}s (backoff up to ${Math.round(this.reprobeMaxDelayMs / 1000)}s)`,
+    );
+    schedule();
+  }
+
+  /**
+   * Cancel any pending auto-reprobe timer. Safe to call multiple times.
+   * Call this when the player is shutting down, or when the protocol is
+   * swapped back to REST by an external caller.
+   */
+  stopAutoReprobe() {
+    if (this._reprobeTimer) {
+      clearTimeout(this._reprobeTimer);
+      this._reprobeTimer = null;
+    }
+    this._reprobeDelay = this.reprobeMinDelayMs;
+  }
+
   /**
    * Get the currently detected protocol.
    * @returns {'rest'|'xmds'|null}

package/src/protocol-detector.test.js

@@ -1,16 +1,22 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // Copyright (c) 2024-2026 Pau Aliagas <linuxnow@gmail.com>
+// @vitest-environment node
 /**
  * ProtocolDetector Tests
  *
  * Tests CMS protocol auto-detection logic:
- * - REST probing via RestClient.isAvailable()
+ * - REST probing via RestClient.isAvailable() with first/reprobe timeout split
  * - Fallback to XMDS/SOAP when REST is unavailable
  * - Forced protocol selection (bypass auto-detection)
  * - Re-probing on connection errors
+ * - Automatic background re-probe loop with exponential backoff
+ *
+ * Pinned to the node environment because this file only exercises JS
+ * logic + mocks — no DOM is needed, and jsdom's CJS require of
+ * @asamuzakjp/css-color has a top-level-await bug on current Node.
  */
 
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { ProtocolDetector } from './protocol-detector.js';
 import { CMS_CLIENT_METHODS } from './cms-client.js';
 
@@ -59,9 +65,10 @@ describe('ProtocolDetector', () => {
       expect(protocol).toBe('rest');
       expect(client.type).toBe('rest');
       expect(detector.getProtocol()).toBe('rest');
+      // detect() triggers a FIRST probe with the generous firstProbeTimeoutMs
       expect(MockRestClient.isAvailable).toHaveBeenCalledWith('https://cms.example.com', {
         maxRetries: 0,
-        timeoutMs: 3000,
+        timeoutMs: 10000,
       });
     });
 
@@ -117,9 +124,24 @@ describe('ProtocolDetector', () => {
       expect(client.config).toBe(config);
     });
 
-    it('should use custom probe timeout', async () => {
+    it('should use the generous first-probe timeout by default', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+
+      // detect() triggers the FIRST probe, which uses firstProbeTimeoutMs (10s)
+      // rather than the shorter reprobe timeout. A cold CMS needs headroom.
+      expect(MockRestClient.isAvailable).toHaveBeenCalledWith('https://cms.example.com', {
+        maxRetries: 0,
+        timeoutMs: 10000,
+      });
+    });
+
+    it('should honour back-compat probeTimeoutMs option', async () => {
       MockRestClient.isAvailable.mockResolvedValue(true);
 
+      // Single probeTimeoutMs sets BOTH first-probe and reprobe timeouts
       const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient, {
         probeTimeoutMs: 5000,
       });
@@ -131,6 +153,26 @@ describe('ProtocolDetector', () => {
       });
     });
 
+    it('should honour split firstProbeTimeoutMs and reprobeTimeoutMs', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(false);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient, {
+        firstProbeTimeoutMs: 15000,
+        reprobeTimeoutMs: 2000,
+      });
+      await detector.detect(config); // first probe → 15000
+      await detector.reprobe(config); // reprobe → 2000
+
+      expect(MockRestClient.isAvailable).toHaveBeenNthCalledWith(1, 'https://cms.example.com', {
+        maxRetries: 0,
+        timeoutMs: 15000,
+      });
+      expect(MockRestClient.isAvailable).toHaveBeenNthCalledWith(2, 'https://cms.example.com', {
+        maxRetries: 0,
+        timeoutMs: 2000,
+      });
+    });
+
     it('should record lastProbeTime after detection', async () => {
       MockRestClient.isAvailable.mockResolvedValue(true);
 
@@ -223,15 +265,27 @@ describe('ProtocolDetector', () => {
   // ── probe() ──────────────────────────────────────────────────────
 
   describe('probe()', () => {
-    it('should call RestClient.isAvailable with correct URL and timeout', async () => {
+    it('should default to the reprobe timeout (plain probe() = not first)', async () => {
       MockRestClient.isAvailable.mockResolvedValue(true);
       const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
       const result = await detector.probe();
 
       expect(result).toBe(true);
+      // Plain probe() with no { first: true } uses the shorter reprobe timeout
+      expect(MockRestClient.isAvailable).toHaveBeenCalledWith('https://cms.example.com', {
+        maxRetries: 0,
+        timeoutMs: 5000,
+      });
+    });
+
+    it('should use firstProbeTimeoutMs when called with { first: true }', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.probe({ first: true });
+
       expect(MockRestClient.isAvailable).toHaveBeenCalledWith('https://cms.example.com', {
         maxRetries: 0,
-        timeoutMs: 3000,
+        timeoutMs: 10000,
       });
     });
 
@@ -243,4 +297,124 @@ describe('ProtocolDetector', () => {
       expect(result).toBe(false);
     });
   });
+
+  // ── startAutoReprobe() / stopAutoReprobe() ───────────────────────
+
+  describe('startAutoReprobe()', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('should be a no-op when protocol is not xmds', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+      expect(detector.getProtocol()).toBe('rest');
+
+      const onPromoted = vi.fn();
+      detector.startAutoReprobe(config, onPromoted);
+
+      // No timer should be scheduled
+      expect(detector._reprobeTimer).toBeNull();
+      vi.advanceTimersByTime(60000);
+      expect(onPromoted).not.toHaveBeenCalled();
+    });
+
+    it('should promote back to REST and call onRestPromoted when probe succeeds', async () => {
+      MockRestClient.isAvailable.mockResolvedValueOnce(false); // initial detect → xmds
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+      expect(detector.getProtocol()).toBe('xmds');
+
+      MockRestClient.isAvailable.mockResolvedValueOnce(true); // reprobe → rest
+      const onPromoted = vi.fn();
+      detector.startAutoReprobe(config, onPromoted);
+
+      // First auto-reprobe fires after reprobeMinDelayMs (5s default)
+      await vi.advanceTimersByTimeAsync(5000);
+
+      expect(onPromoted).toHaveBeenCalledTimes(1);
+      expect(onPromoted).toHaveBeenCalledWith(expect.objectContaining({ type: 'rest' }));
+      expect(detector.getProtocol()).toBe('rest');
+      // Timer is cleared after a successful promotion
+      expect(detector._reprobeTimer).toBeNull();
+    });
+
+    it('should follow exponential backoff while REST stays unavailable', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(false); // always fails
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient, {
+        reprobeMinDelayMs: 1000,
+        reprobeMaxDelayMs: 8000,
+      });
+      await detector.detect(config);
+
+      const onPromoted = vi.fn();
+      detector.startAutoReprobe(config, onPromoted);
+
+      // 1st attempt at 1s
+      expect(MockRestClient.isAvailable).toHaveBeenCalledTimes(1); // from detect()
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(MockRestClient.isAvailable).toHaveBeenCalledTimes(2);
+
+      // 2nd attempt at 1 + 2 = 3s (doubled)
+      await vi.advanceTimersByTimeAsync(2000);
+      expect(MockRestClient.isAvailable).toHaveBeenCalledTimes(3);
+
+      // 3rd attempt at 3 + 4 = 7s
+      await vi.advanceTimersByTimeAsync(4000);
+      expect(MockRestClient.isAvailable).toHaveBeenCalledTimes(4);
+
+      // 4th attempt at 7 + 8 = 15s (capped at max)
+      await vi.advanceTimersByTimeAsync(8000);
+      expect(MockRestClient.isAvailable).toHaveBeenCalledTimes(5);
+
+      // 5th at +8s (still capped)
+      await vi.advanceTimersByTimeAsync(8000);
+      expect(MockRestClient.isAvailable).toHaveBeenCalledTimes(6);
+
+      expect(onPromoted).not.toHaveBeenCalled();
+      detector.stopAutoReprobe();
+    });
+
+    it('should cancel the pending timer when stopAutoReprobe is called', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(false);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+
+      const onPromoted = vi.fn();
+      detector.startAutoReprobe(config, onPromoted);
+      expect(detector._reprobeTimer).not.toBeNull();
+
+      detector.stopAutoReprobe();
+      expect(detector._reprobeTimer).toBeNull();
+
+      // Advancing the clock should trigger no further calls
+      const callsBefore = MockRestClient.isAvailable.mock.calls.length;
+      await vi.advanceTimersByTimeAsync(300000); // 5 minutes
+      expect(MockRestClient.isAvailable.mock.calls.length).toBe(callsBefore);
+      expect(onPromoted).not.toHaveBeenCalled();
+    });
+
+    it('should restart cleanly when startAutoReprobe is called twice', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(false);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient, {
+        reprobeMinDelayMs: 1000,
+        reprobeMaxDelayMs: 4000,
+      });
+      await detector.detect(config);
+
+      const onPromoted = vi.fn();
+      detector.startAutoReprobe(config, onPromoted);
+      // Advance once so delay doubles internally
+      await vi.advanceTimersByTimeAsync(1000);
+
+      // Restart — delay should reset to minimum
+      detector.startAutoReprobe(config, onPromoted);
+      expect(detector._reprobeDelay).toBe(1000);
+    });
+  });
 });

package/src/rest-client.js

@@ -250,7 +250,7 @@ export class RestClient {
       clientCode: this.config.clientCode || 400,
       operatingSystem: os,
       macAddress: this.config.macAddress || 'n/a',
-      xmrChannel: this.config.xmrChannel,
+      xmrChannel: this.config.xmrChannel || '',
       xmrPubKey: this.config.xmrPubKey || '',
     });