@xiboplayer/sync 0.3.7 → 0.4.1

package/README.md

@@ -9,6 +9,7 @@ BroadcastChannel-based lead/follower synchronization:
 - **Lead election** — automatic leader selection among browser tabs/windows
 - **Synchronized playback** — video start coordinated across displays
 - **Layout sync** — all displays transition to the same layout simultaneously
+- **Stats/logs delegation** — follower tabs delegate proof-of-play stats and log submission to the sync lead via BroadcastChannel, avoiding duplicate CMS traffic in video wall setups
 
 Designed for video wall setups where multiple screens show synchronized content.
 

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@xiboplayer/sync",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "description": "Multi-display synchronization for Xibo Player",
   "type": "module",
   "main": "src/sync-manager.js",
   "exports": {
     ".": "./src/sync-manager.js"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@xiboplayer/utils": "0.4.1"
+  },
   "devDependencies": {
     "vitest": "^2.0.0"
   },

package/src/sync-manager.js

@@ -29,6 +29,8 @@
  * @property {boolean} isLead - Whether this display is the leader
  */
 
+import { createLogger } from '@xiboplayer/utils';
+
 const CHANNEL_NAME = 'xibo-sync';
 const HEARTBEAT_INTERVAL = 5000;   // Send heartbeat every 5s
 const FOLLOWER_TIMEOUT = 15000;    // Consider follower offline after 15s silence
@@ -42,6 +44,10 @@ export class SyncManager {
    * @param {Function} [options.onLayoutChange] - Called when lead requests layout change
    * @param {Function} [options.onLayoutShow] - Called when lead gives show signal
    * @param {Function} [options.onVideoStart] - Called when lead gives video start signal
+   * @param {Function} [options.onStatsReport] - (Lead) Called when follower sends stats
+   * @param {Function} [options.onLogsReport] - (Lead) Called when follower sends logs
+   * @param {Function} [options.onStatsAck] - (Follower) Called when lead confirms stats submission
+   * @param {Function} [options.onLogsAck] - (Follower) Called when lead confirms logs submission
    */
   constructor(options) {
     this.displayId = options.displayId;
@@ -54,6 +60,10 @@ export class SyncManager {
     this.onLayoutChange = options.onLayoutChange || (() => {});
     this.onLayoutShow = options.onLayoutShow || (() => {});
     this.onVideoStart = options.onVideoStart || (() => {});
+    this.onStatsReport = options.onStatsReport || null;
+    this.onLogsReport = options.onLogsReport || null;
+    this.onStatsAck = options.onStatsAck || null;
+    this.onLogsAck = options.onLogsAck || null;
 
     // State
     this.channel = null;
@@ -64,8 +74,9 @@ export class SyncManager {
     this._pendingLayoutId = null;    // Layout we're waiting for readiness on
     this._started = false;
 
-    // Log prefix for clarity in multi-tab console
+    // Logger with role prefix for clarity in multi-tab console
     this._tag = this.isLead ? '[Sync:LEAD]' : '[Sync:FOLLOW]';
+    this._log = createLogger(this.isLead ? 'Sync:LEAD' : 'Sync:FOLLOW');
   }
 
   /**
@@ -76,7 +87,7 @@ export class SyncManager {
     this._started = true;
 
     if (typeof BroadcastChannel === 'undefined') {
-      console.warn(this._tag, 'BroadcastChannel not available — sync disabled');
+      this._log.warn( 'BroadcastChannel not available — sync disabled');
       return;
     }
 
@@ -92,7 +103,7 @@ export class SyncManager {
       this._cleanupTimer = setInterval(() => this._cleanupStaleFollowers(), HEARTBEAT_INTERVAL);
     }
 
-    console.log(this._tag, 'Started. DisplayId:', this.displayId);
+    this._log.info( 'Started. DisplayId:', this.displayId);
   }
 
   /**
@@ -116,7 +127,7 @@ export class SyncManager {
     }
 
     this.followers.clear();
-    console.log(this._tag, 'Stopped');
+    this._log.info( 'Stopped');
   }
 
   // ── Lead API ──────────────────────────────────────────────────────
@@ -130,7 +141,7 @@ export class SyncManager {
    */
   async requestLayoutChange(layoutId) {
     if (!this.isLead) {
-      console.warn(this._tag, 'requestLayoutChange called on follower — ignoring');
+      this._log.warn( 'requestLayoutChange called on follower — ignoring');
       return;
     }
 
@@ -145,7 +156,7 @@ export class SyncManager {
 
     const showAt = Date.now() + this.switchDelay;
 
-    console.log(this._tag, `Requesting layout change: ${layoutId} (show at ${new Date(showAt).toISOString()}, ${this.followers.size} followers)`);
+    this._log.info( `Requesting layout change: ${layoutId} (show at ${new Date(showAt).toISOString()}, ${this.followers.size} followers)`);
 
     // Broadcast layout-change to all followers
     this._send({
@@ -167,7 +178,7 @@ export class SyncManager {
     }
 
     // Send show signal
-    console.log(this._tag, `Sending layout-show: ${layoutId}`);
+    this._log.info( `Sending layout-show: ${layoutId}`);
     this._send({
       type: 'layout-show',
       layoutId,
@@ -214,7 +225,7 @@ export class SyncManager {
   reportReady(layoutId) {
     layoutId = String(layoutId);
 
-    console.log(this._tag, `Reporting ready for layout ${layoutId}`);
+    this._log.info( `Reporting ready for layout ${layoutId}`);
 
     this._send({
       type: 'layout-ready',
@@ -223,6 +234,40 @@ export class SyncManager {
     });
   }
 
+  /**
+   * [Follower only] Delegate stats submission to the lead.
+   * Lead will submit on our behalf and send a stats-ack when done.
+   *
+   * @param {string} statsXml - Formatted stats XML to submit
+   */
+  reportStats(statsXml) {
+    if (this.isLead) return;
+
+    this._log.info('Delegating stats to lead');
+    this._send({
+      type: 'stats-report',
+      displayId: this.displayId,
+      statsXml,
+    });
+  }
+
+  /**
+   * [Follower only] Delegate logs submission to the lead.
+   * Lead will submit on our behalf and send a logs-ack when done.
+   *
+   * @param {string} logsXml - Formatted logs XML to submit
+   */
+  reportLogs(logsXml) {
+    if (this.isLead) return;
+
+    this._log.info('Delegating logs to lead');
+    this._send({
+      type: 'logs-report',
+      displayId: this.displayId,
+      logsXml,
+    });
+  }
+
   // ── Message handling ──────────────────────────────────────────────
 
   /** @private */
@@ -238,7 +283,7 @@ export class SyncManager {
       case 'layout-change':
         // Follower: lead is requesting a layout change
         if (!this.isLead) {
-          console.log(this._tag, `Layout change requested: ${msg.layoutId}`);
+          this._log.info( `Layout change requested: ${msg.layoutId}`);
           this.onLayoutChange(msg.layoutId, msg.showAt);
         }
         break;
@@ -253,7 +298,7 @@ export class SyncManager {
       case 'layout-show':
         // Follower: lead says show now
         if (!this.isLead) {
-          console.log(this._tag, `Layout show signal: ${msg.layoutId}`);
+          this._log.info( `Layout show signal: ${msg.layoutId}`);
           this.onLayoutShow(msg.layoutId);
         }
         break;
@@ -261,13 +306,45 @@ export class SyncManager {
       case 'video-start':
         // Follower: lead says start video
         if (!this.isLead) {
-          console.log(this._tag, `Video start signal: ${msg.layoutId} region ${msg.regionId}`);
+          this._log.info( `Video start signal: ${msg.layoutId} region ${msg.regionId}`);
           this.onVideoStart(msg.layoutId, msg.regionId);
         }
         break;
 
+      case 'stats-report':
+        // Lead: follower is delegating stats submission
+        if (this.isLead && this.onStatsReport) {
+          const statsAck = () => this._send({ type: 'stats-ack', displayId: this.displayId, targetDisplayId: msg.displayId });
+          this.onStatsReport(msg.displayId, msg.statsXml, statsAck);
+        }
+        break;
+
+      case 'logs-report':
+        // Lead: follower is delegating logs submission
+        if (this.isLead && this.onLogsReport) {
+          const logsAck = () => this._send({ type: 'logs-ack', displayId: this.displayId, targetDisplayId: msg.displayId });
+          this.onLogsReport(msg.displayId, msg.logsXml, logsAck);
+        }
+        break;
+
+      case 'stats-ack':
+        // Follower: lead confirmed stats were submitted for us
+        if (!this.isLead && msg.targetDisplayId === this.displayId && this.onStatsAck) {
+          this._log.info('Stats acknowledged by lead');
+          this.onStatsAck(msg.targetDisplayId);
+        }
+        break;
+
+      case 'logs-ack':
+        // Follower: lead confirmed logs were submitted for us
+        if (!this.isLead && msg.targetDisplayId === this.displayId && this.onLogsAck) {
+          this._log.info('Logs acknowledged by lead');
+          this.onLogsAck(msg.targetDisplayId);
+        }
+        break;
+
       default:
-        console.warn(this._tag, 'Unknown message type:', msg.type);
+        this._log.warn( 'Unknown message type:', msg.type);
     }
   }
 
@@ -284,7 +361,7 @@ export class SyncManager {
         readyLayoutId: null,
         role: msg.role || 'unknown',
       });
-      console.log(this._tag, `Follower joined: ${msg.displayId} (${this.followers.size} total)`);
+      this._log.info( `Follower joined: ${msg.displayId} (${this.followers.size} total)`);
     }
   }
 
@@ -304,12 +381,12 @@ export class SyncManager {
       follower.lastSeen = Date.now();
     }
 
-    console.log(this._tag, `Follower ${msg.displayId} ready for layout ${msg.layoutId}`);
+    this._log.info( `Follower ${msg.displayId} ready for layout ${msg.layoutId}`);
 
     // Check if all followers are now ready
     if (this._pendingLayoutId === msg.layoutId && this._readyResolve) {
       if (this._allFollowersReady(msg.layoutId)) {
-        console.log(this._tag, 'All followers ready');
+        this._log.info( 'All followers ready');
         this._readyResolve();
         this._readyResolve = null;
       }
@@ -348,7 +425,7 @@ export class SyncManager {
               notReady.push(id);
             }
           }
-          console.warn(this._tag, `Ready timeout — proceeding without: ${notReady.join(', ')}`);
+          this._log.warn( `Ready timeout — proceeding without: ${notReady.join(', ')}`);
           this._readyResolve = null;
           resolve();
         }
@@ -373,7 +450,7 @@ export class SyncManager {
     const now = Date.now();
     for (const [id, follower] of this.followers) {
       if (now - follower.lastSeen > FOLLOWER_TIMEOUT) {
-        console.log(this._tag, `Removing stale follower: ${id} (last seen ${Math.round((now - follower.lastSeen) / 1000)}s ago)`);
+        this._log.info( `Removing stale follower: ${id} (last seen ${Math.round((now - follower.lastSeen) / 1000)}s ago)`);
         this.followers.delete(id);
       }
     }
@@ -385,7 +462,7 @@ export class SyncManager {
     try {
       this.channel.postMessage(msg);
     } catch (e) {
-      console.error(this._tag, 'Failed to send:', e);
+      this._log.error( 'Failed to send:', e);
     }
   }
 

package/src/sync-manager.test.js

@@ -373,4 +373,104 @@ describe('SyncManager', () => {
       expect(lead.followers.size).toBe(0);
     });
   });
+
+  describe('Stats/Logs Delegation', () => {
+    it('follower receives stats-ack after lead calls ack()', () => {
+      const onStatsAck = vi.fn();
+      const onStatsReport = vi.fn((_id, _xml, ack) => ack());
+
+      lead = new SyncManager({
+        displayId: 'pwa-lead',
+        syncConfig: makeSyncConfig(true),
+        onStatsReport,
+      });
+      follower1 = new SyncManager({
+        displayId: 'pwa-f1',
+        syncConfig: makeSyncConfig(false),
+        onStatsAck,
+      });
+      lead.start();
+      follower1.start();
+
+      follower1.reportStats('<stats>test</stats>');
+
+      expect(onStatsReport).toHaveBeenCalledWith(
+        'pwa-f1',
+        '<stats>test</stats>',
+        expect.any(Function),
+      );
+      expect(onStatsAck).toHaveBeenCalledWith('pwa-f1');
+    });
+
+    it('no ack when lead does not call ack() (CMS failure)', () => {
+      const onStatsAck = vi.fn();
+      const onStatsReport = vi.fn((_id, _xml, _ack) => { /* no ack */ });
+
+      lead = new SyncManager({
+        displayId: 'pwa-lead',
+        syncConfig: makeSyncConfig(true),
+        onStatsReport,
+      });
+      follower1 = new SyncManager({
+        displayId: 'pwa-f1',
+        syncConfig: makeSyncConfig(false),
+        onStatsAck,
+      });
+      lead.start();
+      follower1.start();
+
+      follower1.reportStats('<stats>test</stats>');
+
+      expect(onStatsReport).toHaveBeenCalled();
+      expect(onStatsAck).not.toHaveBeenCalled();
+    });
+
+    it('lead ignores stats-report from itself (self-message guard)', () => {
+      const onStatsReport = vi.fn();
+
+      lead = new SyncManager({
+        displayId: 'pwa-lead',
+        syncConfig: makeSyncConfig(true),
+        onStatsReport,
+      });
+      lead.start();
+
+      // Simulate: lead sends a stats-report with its own displayId
+      // The _handleMessage guard should reject it (msg.displayId === this.displayId)
+      lead._send({
+        type: 'stats-report',
+        displayId: 'pwa-lead',
+        statsXml: '<stats>self</stats>',
+      });
+
+      expect(onStatsReport).not.toHaveBeenCalled();
+    });
+
+    it('logs delegation works same as stats', () => {
+      const onLogsAck = vi.fn();
+      const onLogsReport = vi.fn((_id, _xml, ack) => ack());
+
+      lead = new SyncManager({
+        displayId: 'pwa-lead',
+        syncConfig: makeSyncConfig(true),
+        onLogsReport,
+      });
+      follower1 = new SyncManager({
+        displayId: 'pwa-f1',
+        syncConfig: makeSyncConfig(false),
+        onLogsAck,
+      });
+      lead.start();
+      follower1.start();
+
+      follower1.reportLogs('<logs>test-logs</logs>');
+
+      expect(onLogsReport).toHaveBeenCalledWith(
+        'pwa-f1',
+        '<logs>test-logs</logs>',
+        expect.any(Function),
+      );
+      expect(onLogsAck).toHaveBeenCalledWith('pwa-f1');
+    });
+  });
 });