@xiboplayer/xmds 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/xmds",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "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.6.2"
+    "@xiboplayer/utils": "0.6.3"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/src/index.d.ts

@@ -36,4 +36,21 @@ export class XmdsClient {
   mediaInventory(inventoryXml: string): Promise<boolean>;
 }
 
+export class ProtocolDetector {
+  constructor(
+    cmsUrl: string,
+    RestClientClass: typeof RestClient,
+    XmdsClientClass: typeof XmdsClient,
+    options?: { probeTimeoutMs?: number }
+  );
+
+  protocol: 'rest' | 'xmds' | null;
+  lastProbeTime: number;
+
+  probe(): Promise<boolean>;
+  detect(config: any, forceProtocol?: 'rest' | 'xmds'): Promise<{ client: any; protocol: 'rest' | 'xmds' }>;
+  reprobe(config: any): Promise<{ client: any; protocol: 'rest' | 'xmds'; changed: boolean }>;
+  getProtocol(): 'rest' | 'xmds' | null;
+}
+
 export function parseScheduleResponse(data: any): any;

package/src/index.js

@@ -3,4 +3,5 @@ import pkg from '../package.json' with { type: 'json' };
 export const VERSION = pkg.version;
 export { RestClient } from './rest-client.js';
 export { XmdsClient } from './xmds-client.js';
+export { ProtocolDetector } from './protocol-detector.js';
 export { parseScheduleResponse } from './schedule-parser.js';

package/src/protocol-detector.js

@@ -0,0 +1,149 @@
+/**
+ * CMS Protocol Auto-Detector
+ *
+ * Probes the CMS to determine which communication protocol to use:
+ *   - REST/PlayerApiV2 — optimized JSON protocol (custom CMS image)
+ *   - SOAP/XMDS — universal XML protocol (any vanilla Xibo CMS)
+ *
+ * Detection logic:
+ *   1. GET {cmsUrl}/api/v2/player/health with a 3-second 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.
+ *
+ * @example
+ *   import { ProtocolDetector } from '@xiboplayer/xmds';
+ *   import { 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
+ *
+ *   // On connection errors, re-probe:
+ *   const newXmds = await detector.reprobe(config);
+ */
+
+import { createLogger } from '@xiboplayer/utils';
+
+const log = createLogger('Protocol');
+
+/** Default probe timeout in milliseconds */
+const PROBE_TIMEOUT_MS = 3000;
+
+export class ProtocolDetector {
+  /**
+   * @param {string} cmsUrl - CMS base URL
+   * @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
+   */
+  constructor(cmsUrl, RestClientClass, XmdsClientClass, options = {}) {
+    this.cmsUrl = cmsUrl;
+    this.RestClient = RestClientClass;
+    this.XmdsClient = XmdsClientClass;
+    this.probeTimeoutMs = options.probeTimeoutMs || PROBE_TIMEOUT_MS;
+
+    /** @type {'rest'|'xmds'|null} Detected protocol (null = not yet probed) */
+    this.protocol = null;
+
+    /** @type {number} Timestamp of last successful probe */
+    this.lastProbeTime = 0;
+  }
+
+  /**
+   * Probe the CMS health endpoint to determine protocol availability.
+   * @returns {Promise<boolean>} true if REST/PlayerApiV2 is available
+   */
+  async probe() {
+    const available = await this.RestClient.isAvailable(this.cmsUrl, {
+      maxRetries: 0,
+      timeoutMs: this.probeTimeoutMs,
+    });
+    this.lastProbeTime = Date.now();
+    return available;
+  }
+
+  /**
+   * 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.
+   *
+   * @param {Object} config - Player configuration (passed to client constructor)
+   * @param {string} [forceProtocol] - 'rest'|'xmds' to skip detection
+   * @returns {Promise<{client: any, protocol: 'rest'|'xmds'}>}
+   */
+  async detect(config, forceProtocol) {
+    if (forceProtocol === 'rest') {
+      this.protocol = 'rest';
+      log.info('Using REST transport (forced)');
+      return { client: new this.RestClient(config), protocol: 'rest' };
+    }
+
+    if (forceProtocol === 'xmds') {
+      this.protocol = 'xmds';
+      log.info('Using XMDS/SOAP transport (forced)');
+      return { client: new this.XmdsClient(config), protocol: 'xmds' };
+    }
+
+    // Auto-detect
+    log.info('Probing CMS for REST API availability...');
+    let isRest = false;
+    try {
+      isRest = await this.probe();
+    } catch (e) {
+      log.warn('REST probe failed:', e?.message || e);
+    }
+
+    if (isRest) {
+      this.protocol = 'rest';
+      log.info('REST transport detected — using PlayerApiV2');
+      return { client: new this.RestClient(config), protocol: 'rest' };
+    }
+
+    this.protocol = 'xmds';
+    log.info('REST unavailable — using XMDS/SOAP transport');
+    return { client: new this.XmdsClient(config), protocol: 'xmds' };
+  }
+
+  /**
+   * Re-probe the CMS and potentially switch protocols.
+   * Called on connection errors to check if the CMS was upgraded/downgraded.
+   *
+   * @param {Object} config - Player configuration
+   * @returns {Promise<{client: any, protocol: 'rest'|'xmds', changed: boolean}>}
+   */
+  async reprobe(config) {
+    const previousProtocol = this.protocol;
+
+    log.info('Re-probing CMS protocol...');
+    let isRest = false;
+    try {
+      isRest = await this.probe();
+    } catch (e) {
+      log.warn('Re-probe failed:', e?.message || e);
+    }
+
+    const newProtocol = isRest ? 'rest' : 'xmds';
+    const changed = newProtocol !== previousProtocol;
+
+    if (changed) {
+      log.info(`Protocol changed: ${previousProtocol} → ${newProtocol}`);
+      this.protocol = newProtocol;
+      const client = isRest ? new this.RestClient(config) : new this.XmdsClient(config);
+      return { client, protocol: newProtocol, changed: true };
+    }
+
+    log.info(`Protocol unchanged: ${newProtocol}`);
+    return { client: null, protocol: newProtocol, changed: false };
+  }
+
+  /**
+   * Get the currently detected protocol.
+   * @returns {'rest'|'xmds'|null}
+   */
+  getProtocol() {
+    return this.protocol;
+  }
+}

package/src/protocol-detector.test.js

@@ -0,0 +1,234 @@
+/**
+ * ProtocolDetector Tests
+ *
+ * Tests CMS protocol auto-detection logic:
+ * - REST probing via RestClient.isAvailable()
+ * - Fallback to XMDS/SOAP when REST is unavailable
+ * - Forced protocol selection (bypass auto-detection)
+ * - Re-probing on connection errors
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ProtocolDetector } from './protocol-detector.js';
+
+describe('ProtocolDetector', () => {
+  let MockRestClient;
+  let MockXmdsClient;
+  let config;
+
+  beforeEach(() => {
+    config = {
+      cmsUrl: 'https://cms.example.com',
+      cmsKey: 'test-key',
+      hardwareKey: 'test-hw',
+    };
+
+    MockRestClient = vi.fn(function (cfg) {
+      this.config = cfg;
+      this.type = 'rest';
+    });
+    MockRestClient.isAvailable = vi.fn();
+
+    MockXmdsClient = vi.fn(function (cfg) {
+      this.config = cfg;
+      this.type = 'xmds';
+    });
+  });
+
+  // ── detect() ─────────────────────────────────────────────────────
+
+  describe('detect()', () => {
+    it('should detect REST when health endpoint returns 200', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const { client, protocol } = await detector.detect(config);
+
+      expect(protocol).toBe('rest');
+      expect(client.type).toBe('rest');
+      expect(detector.getProtocol()).toBe('rest');
+      expect(MockRestClient.isAvailable).toHaveBeenCalledWith('https://cms.example.com', {
+        maxRetries: 0,
+        timeoutMs: 3000,
+      });
+    });
+
+    it('should fall back to XMDS when REST is unavailable', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(false);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const { client, protocol } = await detector.detect(config);
+
+      expect(protocol).toBe('xmds');
+      expect(client.type).toBe('xmds');
+      expect(detector.getProtocol()).toBe('xmds');
+    });
+
+    it('should fall back to XMDS when probe throws', async () => {
+      MockRestClient.isAvailable.mockRejectedValue(new Error('Network error'));
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      // probe() will throw, but detect() should handle it
+      // Actually, isAvailable catches internally and returns false
+      // Let's test the direct throw case by mocking probe
+      const { client, protocol } = await detector.detect(config);
+
+      expect(protocol).toBe('xmds');
+      expect(client.type).toBe('xmds');
+    });
+
+    it('should use forced REST protocol without probing', async () => {
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const { client, protocol } = await detector.detect(config, 'rest');
+
+      expect(protocol).toBe('rest');
+      expect(client.type).toBe('rest');
+      expect(MockRestClient.isAvailable).not.toHaveBeenCalled();
+    });
+
+    it('should use forced XMDS protocol without probing', async () => {
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const { client, protocol } = await detector.detect(config, 'xmds');
+
+      expect(protocol).toBe('xmds');
+      expect(client.type).toBe('xmds');
+      expect(MockRestClient.isAvailable).not.toHaveBeenCalled();
+    });
+
+    it('should pass config to client constructor', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const { client } = await detector.detect(config);
+
+      expect(MockRestClient).toHaveBeenCalledWith(config);
+      expect(client.config).toBe(config);
+    });
+
+    it('should use custom probe timeout', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient, {
+        probeTimeoutMs: 5000,
+      });
+      await detector.detect(config);
+
+      expect(MockRestClient.isAvailable).toHaveBeenCalledWith('https://cms.example.com', {
+        maxRetries: 0,
+        timeoutMs: 5000,
+      });
+    });
+
+    it('should record lastProbeTime after detection', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      expect(detector.lastProbeTime).toBe(0);
+
+      await detector.detect(config);
+
+      expect(detector.lastProbeTime).toBeGreaterThan(0);
+      expect(detector.lastProbeTime).toBeLessThanOrEqual(Date.now());
+    });
+  });
+
+  // ── reprobe() ────────────────────────────────────────────────────
+
+  describe('reprobe()', () => {
+    it('should detect protocol change from XMDS to REST', async () => {
+      MockRestClient.isAvailable.mockResolvedValueOnce(false); // initial detect
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+      expect(detector.getProtocol()).toBe('xmds');
+
+      MockRestClient.isAvailable.mockResolvedValueOnce(true); // reprobe
+      const { client, protocol, changed } = await detector.reprobe(config);
+
+      expect(changed).toBe(true);
+      expect(protocol).toBe('rest');
+      expect(client.type).toBe('rest');
+      expect(detector.getProtocol()).toBe('rest');
+    });
+
+    it('should detect protocol change from REST to XMDS', async () => {
+      MockRestClient.isAvailable.mockResolvedValueOnce(true); // initial detect
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+      expect(detector.getProtocol()).toBe('rest');
+
+      MockRestClient.isAvailable.mockResolvedValueOnce(false); // reprobe
+      const { client, protocol, changed } = await detector.reprobe(config);
+
+      expect(changed).toBe(true);
+      expect(protocol).toBe('xmds');
+      expect(client.type).toBe('xmds');
+      expect(detector.getProtocol()).toBe('xmds');
+    });
+
+    it('should return changed=false when protocol is unchanged', async () => {
+      MockRestClient.isAvailable.mockResolvedValueOnce(true); // initial detect
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+
+      MockRestClient.isAvailable.mockResolvedValueOnce(true); // reprobe (same)
+      const { client, protocol, changed } = await detector.reprobe(config);
+
+      expect(changed).toBe(false);
+      expect(protocol).toBe('rest');
+      expect(client).toBeNull(); // No new client when unchanged
+    });
+
+    it('should update lastProbeTime on reprobe', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+      const firstProbe = detector.lastProbeTime;
+
+      // Small delay to ensure different timestamp
+      await new Promise(r => setTimeout(r, 5));
+
+      await detector.reprobe(config);
+      expect(detector.lastProbeTime).toBeGreaterThanOrEqual(firstProbe);
+    });
+  });
+
+  // ── getProtocol() ────────────────────────────────────────────────
+
+  describe('getProtocol()', () => {
+    it('should return null before detection', () => {
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      expect(detector.getProtocol()).toBeNull();
+    });
+
+    it('should return detected protocol after detect()', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      await detector.detect(config);
+      expect(detector.getProtocol()).toBe('rest');
+    });
+  });
+
+  // ── probe() ──────────────────────────────────────────────────────
+
+  describe('probe()', () => {
+    it('should call RestClient.isAvailable with correct URL and timeout', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(true);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const result = await detector.probe();
+
+      expect(result).toBe(true);
+      expect(MockRestClient.isAvailable).toHaveBeenCalledWith('https://cms.example.com', {
+        maxRetries: 0,
+        timeoutMs: 3000,
+      });
+    });
+
+    it('should return false when REST is unavailable', async () => {
+      MockRestClient.isAvailable.mockResolvedValue(false);
+      const detector = new ProtocolDetector('https://cms.example.com', MockRestClient, MockXmdsClient);
+      const result = await detector.probe();
+
+      expect(result).toBe(false);
+    });
+  });
+});

package/src/rest-client.js

@@ -526,7 +526,13 @@ export class RestClient {
         (window.electronAPI?.isElectron || window.location.hostname === 'localhost');
       const base = isProxy ? '' : cmsUrl.replace(/\/+$/, '');
       const url = `${base}${PLAYER_API}/health`;
-      const response = await fetchWithRetry(url, { method: 'GET' }, retryOptions || { maxRetries: 0 });
+      const timeoutMs = retryOptions?.timeoutMs || 3000;
+      const fetchOptions = { method: 'GET' };
+      // Apply timeout via AbortSignal (short timeout avoids delaying startup)
+      if (typeof AbortSignal !== 'undefined' && AbortSignal.timeout) {
+        fetchOptions.signal = AbortSignal.timeout(timeoutMs);
+      }
+      const response = await fetchWithRetry(url, fetchOptions, retryOptions || { maxRetries: 0 });
       if (!response.ok) return false;
       const data = await response.json();
       return data.version === 2 && data.status === 'ok';