@xiboplayer/sync 0.4.0 → 0.4.3

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,6 +1,6 @@
 {
   "name": "@xiboplayer/sync",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "description": "Multi-display synchronization for Xibo Player",
   "type": "module",
   "main": "src/sync-manager.js",
@@ -8,7 +8,7 @@
     ".": "./src/sync-manager.js"
   },
   "dependencies": {
-    "@xiboplayer/utils": "0.4.0"
+    "@xiboplayer/utils": "0.4.3"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/src/sync-manager.js

@@ -44,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;
@@ -56,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;
@@ -226,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 */
@@ -269,6 +311,38 @@ export class SyncManager {
         }
         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:
         this._log.warn( 'Unknown message type:', msg.type);
     }

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');
+    });
+  });
 });