@xiboplayer/xmr 0.6.4 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/xmr",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "XMR WebSocket client for real-time Xibo CMS commands",
   "type": "module",
   "main": "./src/index.js",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@xibosignage/xibo-communication-framework": "^0.0.6",
-    "@xiboplayer/utils": "0.6.4"
+    "@xiboplayer/utils": "0.6.5"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/src/test-utils.js

@@ -89,7 +89,7 @@ export function createMockPlayer() {
     refreshDataConnectors: vi.fn(),
     reportGeoLocation: vi.fn(() => Promise.resolve()),
     requestGeoLocation: vi.fn(() => Promise.resolve({ latitude: 41.3851, longitude: 2.1734 })),
-    updateStatus: vi.fn()
+    emit: vi.fn()
   };
 }
 

package/src/xmr-wrapper.js

@@ -4,6 +4,10 @@
  * Integrates the official @xibosignage/xibo-communication-framework
  * to enable real-time push commands from CMS via WebSocket.
  *
+ * Connection lifecycle is delegated to the framework, which has a
+ * built-in 60s health-check interval that reconnects automatically.
+ * This wrapper only routes events to player callbacks.
+ *
  * Supported commands:
  * - collectNow: Trigger immediate XMDS collection cycle
  * - screenShot/screenshot: Capture and upload screenshot
@@ -35,61 +39,40 @@ export class XmrWrapper {
     this.player = player;
     this.xmr = null;
     this.connected = false;
-    this.reconnectAttempts = 0;
-    this.maxReconnectAttempts = 10;
-    this.reconnectDelay = 5000; // 5 seconds
-    this.lastXmrUrl = null;
-    this.lastCmsKey = null;
-    this.reconnectTimer = null;
-    this.intentionalShutdown = false;
   }
 
   /**
-   * Initialize and start XMR connection
+   * Initialize and start XMR connection.
+   *
+   * Creates a single Xmr instance and lets the framework manage
+   * reconnection via its internal 60s health-check timer.
+   * Calling start() again on an already-running instance is safe —
+   * the framework skips if already connected to the same URL.
+   *
    * @param {string} xmrUrl - WebSocket URL (ws:// or wss://)
    * @param {string} cmsKey - CMS authentication key
    * @returns {Promise<boolean>} Success status
    */
   async start(xmrUrl, cmsKey) {
     try {
-      log.info('Initializing connection to:', xmrUrl);
-
-      // Clear intentional shutdown flag (we're starting again)
-      this.intentionalShutdown = false;
-
-      // Save connection details for reconnection
-      this.lastXmrUrl = xmrUrl;
-      this.lastCmsKey = cmsKey;
-
-      // Cancel any pending reconnect attempts
-      if (this.reconnectTimer) {
-        clearTimeout(this.reconnectTimer);
-        this.reconnectTimer = null;
-      }
-
-      // Create XMR instance with channel ID (or reuse if already exists)
+      // Reuse existing instance — the framework handles reconnection.
+      // Only create a new instance on first call or after stop().
       if (!this.xmr) {
+        log.info('Initializing connection to:', xmrUrl);
         const channel = this.config.xmrChannel || `player-${this.config.hardwareKey}`;
         this.xmr = new Xmr(channel);
-        // Setup event handlers before connecting (only once)
         this.setupEventHandlers();
+        await this.xmr.init();
       }
 
-      // Initialize and connect
-      await this.xmr.init();
       await this.xmr.start(xmrUrl, cmsKey);
-
       this.connected = true;
-      this.reconnectAttempts = 0;
       log.info('Connected successfully');
 
       return true;
     } catch (error) {
       log.warn('Failed to start:', error.message);
-      log.info('Continuing in polling mode (XMDS only)');
-
-      // Schedule reconnection attempt
-      this.scheduleReconnect(xmrUrl, cmsKey);
+      log.info('Framework will retry automatically every 60s');
 
       return false;
     }
@@ -105,21 +88,13 @@ export class XmrWrapper {
     this.xmr.on('connected', () => {
       log.info('WebSocket connected');
       this.connected = true;
-      this.reconnectAttempts = 0;
-      this.player.updateStatus?.('XMR connected');
+      this.player.emit?.('xmr-status', { connected: true });
     });
 
     this.xmr.on('disconnected', () => {
-      log.warn('WebSocket disconnected');
+      log.warn('WebSocket disconnected (framework will reconnect)');
       this.connected = false;
-      this.player.updateStatus?.('XMR disconnected (polling mode)');
-
-      // Attempt to reconnect if we have the connection details
-      // BUT not if this was an intentional shutdown
-      if (this.lastXmrUrl && this.lastCmsKey && !this.intentionalShutdown) {
-        log.info('Connection lost, scheduling reconnection...');
-        this.scheduleReconnect(this.lastXmrUrl, this.lastCmsKey);
-      }
+      this.player.emit?.('xmr-status', { connected: false });
     });
 
     this.xmr.on('error', (error) => {
@@ -151,8 +126,6 @@ export class XmrWrapper {
     // CMS command: License Check (no-op for Linux clients)
     this.xmr.on('licenceCheck', () => {
       log.debug('Received licenceCheck (no-op for Linux client)');
-      // Linux clients always report valid license
-      // No action needed - clientType: "linux" bypasses commercial license
     });
 
     // CMS command: Change Layout
@@ -220,7 +193,6 @@ export class XmrWrapper {
       const commandCode = data?.commandCode || data;
       log.info('Received commandAction command:', commandCode);
       try {
-        // Use local commands from RegisterDisplay (stored on player), not XMR payload commands
         const localCommands = this.player.displayCommands || data?.commands;
         await this.player.executeCommand(commandCode, localCommands);
         log.debug('commandAction completed successfully');
@@ -279,7 +251,6 @@ export class XmrWrapper {
     this.xmr.on('criteriaUpdate', async (data) => {
       log.info('Received criteriaUpdate command:', data);
       try {
-        // Trigger immediate collection to get updated display criteria
         await this.player.collect();
         log.debug('criteriaUpdate completed successfully');
       } catch (error) {
@@ -296,7 +267,6 @@ export class XmrWrapper {
         const hasCoordinates = data && data.latitude != null && data.longitude != null;
 
         if (hasCoordinates) {
-          // CMS is pushing coordinates to us
           if (this.player.reportGeoLocation) {
             this.player.reportGeoLocation(data);
             log.debug('currentGeoLocation: coordinates applied');
@@ -304,7 +274,6 @@ export class XmrWrapper {
             log.warn('Geo location reporting not implemented in player');
           }
         } else {
-          // CMS is asking us to report our location via browser API
           if (this.player.requestGeoLocation) {
             await this.player.requestGeoLocation();
             log.debug('currentGeoLocation: browser location requested');
@@ -319,50 +288,17 @@ export class XmrWrapper {
   }
 
   /**
-   * Schedule reconnection attempt
-   */
-  scheduleReconnect(xmrUrl, cmsKey) {
-    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
-      log.warn('Max reconnection attempts reached, giving up');
-      log.info('Will retry on next collection cycle');
-      return;
-    }
-
-    // Cancel any existing reconnect timer
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-    }
-
-    this.reconnectAttempts++;
-    const delay = this.reconnectDelay * this.reconnectAttempts;
-
-    log.debug(`Scheduling reconnect attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts} in ${delay}ms`);
-
-    this.reconnectTimer = setTimeout(() => {
-      log.debug('Attempting to reconnect...');
-      this.reconnectTimer = null;
-      this.start(xmrUrl, cmsKey);
-    }, delay);
-  }
-
-  /**
-   * Stop XMR connection
+   * Stop XMR connection and clean up the framework instance.
+   * The framework's internal 60s timer is cleared when the instance
+   * is discarded, so no reconnection will occur after stop().
    */
   async stop() {
-    // Mark as intentional shutdown to prevent reconnection
-    this.intentionalShutdown = true;
-
-    // Cancel any pending reconnect attempts
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-
     if (!this.xmr) return;
 
     try {
       await this.xmr.stop();
       this.connected = false;
+      this.xmr = null;
       log.info('Stopped');
     } catch (error) {
       log.error('Error stopping:', error);

package/src/xmr-wrapper.test.js

@@ -1,8 +1,8 @@
 /**
  * XmrWrapper Tests
  *
- * Comprehensive testing for XMR WebSocket integration
- * Tests connection lifecycle, all CMS commands, reconnection logic, and error handling
+ * Tests connection lifecycle, all CMS commands, and error handling.
+ * Reconnection is delegated to the framework's built-in 60s health-check.
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
@@ -84,13 +84,6 @@ describe('XmrWrapper', () => {
       expect(wrapper.connected).toBe(false);
       expect(wrapper.xmr).toBeNull();
     });
-
-    it('should initialize reconnection properties', () => {
-      expect(wrapper.reconnectAttempts).toBe(0);
-      expect(wrapper.maxReconnectAttempts).toBe(10);
-      expect(wrapper.reconnectDelay).toBe(5000);
-      expect(wrapper.reconnectTimer).toBeNull();
-    });
   });
 
   describe('start(xmrUrl, cmsKey)', () => {
@@ -102,27 +95,27 @@ describe('XmrWrapper', () => {
       expect(wrapper.xmr).toBeDefined();
       expect(wrapper.xmr.init).toHaveBeenCalled();
       expect(wrapper.xmr.start).toHaveBeenCalledWith('wss://test.xmr.com', 'cms-key-123');
-      expect(wrapper.reconnectAttempts).toBe(0);
     });
 
-    it('should save connection details for reconnection', async () => {
+    it('should reuse existing xmr instance on subsequent start() calls', async () => {
+      await wrapper.start('wss://test.xmr.com', 'cms-key-123');
+      const firstInstance = wrapper.xmr;
+
       await wrapper.start('wss://test.xmr.com', 'cms-key-123');
 
-      expect(wrapper.lastXmrUrl).toBe('wss://test.xmr.com');
-      expect(wrapper.lastCmsKey).toBe('cms-key-123');
+      expect(wrapper.xmr).toBe(firstInstance);
+      expect(firstInstance.init).toHaveBeenCalledTimes(1);
+      expect(firstInstance.start).toHaveBeenCalledTimes(2);
     });
 
-    it('should reuse existing xmr instance on reconnect', async () => {
+    it('should create new instance after stop()', async () => {
       await wrapper.start('wss://test.xmr.com', 'cms-key-123');
       const firstInstance = wrapper.xmr;
 
-      // Simulate disconnect
-      wrapper.connected = false;
-
+      await wrapper.stop();
       await wrapper.start('wss://test.xmr.com', 'cms-key-123');
-      const secondInstance = wrapper.xmr;
 
-      expect(firstInstance).toBe(secondInstance);
+      expect(wrapper.xmr).not.toBe(firstInstance);
     });
 
     it('should use custom xmrChannel if provided', async () => {
@@ -144,40 +137,18 @@ describe('XmrWrapper', () => {
     });
 
     it('should handle connection failure gracefully', async () => {
-      const newWrapper = new XmrWrapper(mockConfig, mockPlayer);
-      await newWrapper.start('wss://test.xmr.com', 'cms-key-123');
-
-      // Make start fail by replacing the start method
-      if (newWrapper.xmr) {
-        newWrapper.xmr.start = vi.fn(() => Promise.reject(new Error('Connection failed')));
-        newWrapper.connected = false;
-
-        const result = await newWrapper.start('wss://test.xmr.com', 'cms-key-123');
-        expect(result).toBe(false);
-      }
-    });
-
-    it('should schedule reconnect on failure', async () => {
-      const newWrapper = new XmrWrapper(mockConfig, mockPlayer);
-      await newWrapper.start('wss://test.xmr.com', 'cms-key-123');
+      // Hook setupEventHandlers to patch the freshly-created Xmr instance
+      // (init is an instance property, so prototype patching doesn't work)
+      const origSetup = wrapper.setupEventHandlers.bind(wrapper);
+      wrapper.setupEventHandlers = function() {
+        origSetup.call(this);
+        this.xmr.init = vi.fn(() => Promise.reject(new Error('Connection failed')));
+      };
 
-      // Simulate failure and check reconnect
-      if (newWrapper.xmr) {
-        newWrapper.xmr.start = vi.fn(() => Promise.reject(new Error('Connection failed')));
-        newWrapper.connected = false;
-
-        await newWrapper.start('wss://test.xmr.com', 'cms-key-123');
-        expect(newWrapper.reconnectTimer).toBeDefined();
-      }
-    });
-
-    it('should cancel pending reconnect timer on new start', async () => {
-      wrapper.reconnectTimer = setTimeout(() => {}, 5000);
-      const timerId = wrapper.reconnectTimer;
-
-      await wrapper.start('wss://test.xmr.com', 'cms-key-123');
+      const result = await wrapper.start('wss://test.xmr.com', 'cms-key-123');
+      expect(result).toBe(false);
 
-      expect(wrapper.reconnectTimer).toBeNull();
+      wrapper.setupEventHandlers = origSetup;
     });
   });
 
@@ -194,8 +165,7 @@ describe('XmrWrapper', () => {
         xmrInstance.simulateCommand('connected');
 
         expect(wrapper.connected).toBe(true);
-        expect(wrapper.reconnectAttempts).toBe(0);
-        expect(mockPlayer.updateStatus).toHaveBeenCalledWith('XMR connected');
+        expect(mockPlayer.emit).toHaveBeenCalledWith('xmr-status', { connected: true });
       });
 
       it('should handle disconnected event', () => {
@@ -204,15 +174,7 @@ describe('XmrWrapper', () => {
         xmrInstance.simulateCommand('disconnected');
 
         expect(wrapper.connected).toBe(false);
-        expect(mockPlayer.updateStatus).toHaveBeenCalledWith('XMR disconnected (polling mode)');
-      });
-
-      it('should schedule reconnect on disconnect', () => {
-        wrapper.connected = true;
-
-        xmrInstance.simulateCommand('disconnected');
-
-        expect(wrapper.reconnectTimer).toBeDefined();
+        expect(mockPlayer.emit).toHaveBeenCalledWith('xmr-status', { connected: false });
       });
 
       it('should handle error event', () => {
@@ -591,69 +553,17 @@ describe('XmrWrapper', () => {
     });
   });
 
-  describe('Reconnection Logic', () => {
-    it('should schedule reconnect with exponential backoff', async () => {
-      const newWrapper = new XmrWrapper(mockConfig, mockPlayer);
-      await newWrapper.start('wss://test.xmr.com', 'cms-key-123');
-
-      // Make subsequent starts fail
-      if (newWrapper.xmr) {
-        newWrapper.xmr.start = vi.fn(() => Promise.reject(new Error('Connection failed')));
-        newWrapper.connected = false;
-
-        // First reconnect attempt
-        await newWrapper.start('wss://test.xmr.com', 'cms-key-123');
-        expect(newWrapper.reconnectAttempts).toBe(1);
-
-        // Second reconnect attempt (should have longer delay)
-        await newWrapper.start('wss://test.xmr.com', 'cms-key-123');
-        expect(newWrapper.reconnectAttempts).toBe(2);
-      }
-    });
-
-    it('should stop reconnecting after max attempts', async () => {
-      wrapper.reconnectAttempts = wrapper.maxReconnectAttempts;
-
-      wrapper.scheduleReconnect('wss://test.xmr.com', 'cms-key-123');
-
-      expect(wrapper.reconnectTimer).toBeNull();
-    });
-
-    it('should cancel existing timer before scheduling new reconnect', () => {
-      wrapper.reconnectTimer = setTimeout(() => {}, 5000);
-      const firstTimer = wrapper.reconnectTimer;
-
-      wrapper.scheduleReconnect('wss://test.xmr.com', 'cms-key-123');
-
-      expect(wrapper.reconnectTimer).not.toBe(firstTimer);
-    });
-
-    it('should reset reconnect attempts on successful connection', async () => {
-      wrapper.reconnectAttempts = 5;
-
-      await wrapper.start('wss://test.xmr.com', 'cms-key-123');
-
-      expect(wrapper.reconnectAttempts).toBe(0);
-    });
-  });
-
   describe('stop()', () => {
-    it('should stop XMR connection', async () => {
+    it('should stop XMR connection and null out instance', async () => {
       await wrapper.start('wss://test.xmr.com', 'cms-key-123');
+      const xmrRef = wrapper.xmr;
       wrapper.connected = true;
 
       await wrapper.stop();
 
-      expect(wrapper.xmr.stop).toHaveBeenCalled();
+      expect(xmrRef.stop).toHaveBeenCalled();
       expect(wrapper.connected).toBe(false);
-    });
-
-    it('should cancel pending reconnect timer', async () => {
-      wrapper.reconnectTimer = setTimeout(() => {}, 5000);
-
-      await wrapper.stop();
-
-      expect(wrapper.reconnectTimer).toBeNull();
+      expect(wrapper.xmr).toBeNull();
     });
 
     it('should handle stop when not started', async () => {
@@ -662,7 +572,7 @@ describe('XmrWrapper', () => {
 
     it('should handle stop errors gracefully', async () => {
       await wrapper.start('wss://test.xmr.com', 'cms-key-123');
-      wrapper.xmr.stop.mockRejectedValue(new Error('Stop failed'));
+      wrapper.xmr.stop = vi.fn(() => Promise.reject(new Error('Stop failed')));
       const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
 
       await wrapper.stop();
@@ -773,25 +683,11 @@ describe('XmrWrapper', () => {
   });
 
   describe('Memory Management', () => {
-    it('should clean up timers on stop', async () => {
-      wrapper.reconnectTimer = setTimeout(() => {}, 5000);
-
-      await wrapper.stop();
-
-      expect(wrapper.reconnectTimer).toBeNull();
-    });
-
-    it('should allow garbage collection after stop', async () => {
+    it('should null out xmr instance on stop', async () => {
       await wrapper.start('wss://test.xmr.com', 'cms-key-123');
       await wrapper.stop();
 
-      // The disconnected event handler may schedule a reconnect,
-      // but stop() should cancel it
-      // Allow up to a small window for async cleanup
-      await vi.runAllTimersAsync();
-
-      // After all timers run and stop completes, timer should be null
-      expect(wrapper.reconnectTimer).toBeNull();
+      expect(wrapper.xmr).toBeNull();
     });
   });
 });