eyevinn-channel-engine 5.1.2 → 5.2.0

package/engine/server.ts

@@ -29,10 +29,39 @@ const eventStreams = {};
 const DefaultDummySubtitleEndpointPath = "/dummyUrl"
 const DefaultSubtitleSpliceEndpointPath = "/sliceUrl"
 
+// Configuration for SGAI HLS-interstitial ad breaks. Config surface only for
+// now (issue #367): this describes when/where a channel may open an ad break
+// and which slate to fall back to. No interstitial tags are emitted from this
+// config yet — that lands in a follow-up (#368). Defaults to disabled.
+export interface AdBreakOpts {
+  // Master enable/disable flag for interstitial ad breaks on the channel.
+  // When false (the default) no ad-break plumbing is active.
+  enabled: boolean;
+  // URL of the ad-serving endpoint queried to fill an interstitial break.
+  // Required and validated (must be an absolute http/https URL) when enabled.
+  adServerUri?: string;
+  // Optional slate reference shown while the break is being resolved. Reuses
+  // the existing slate shape (uri/repetitions/duration); when omitted the
+  // channel/engine slate configuration is used.
+  slate?: SlateOpts;
+}
+
+// Shared slate reference shape, mirroring the loosely-typed `channel.slate`
+// object already consumed by the session plumbing (slateUri/slateRepetitions/
+// slateDuration).
+export interface SlateOpts {
+  uri: string;
+  repetitions?: number;
+  duration?: number;
+}
+
 export interface ChannelEngineOpts {
   defaultSlateUri?: string;
   slateRepetitions?: number;
   slateDuration?: number;
+  // Default ad-break configuration applied to channels that do not carry their
+  // own per-channel `adBreak`. Defaults to disabled when unset.
+  adBreak?: AdBreakOpts;
   redisUrl?: string;
   memcachedUrl?: string;
   sharedStoreCacheTTL?: number;
@@ -66,6 +95,35 @@ export interface ChannelEngineOpts {
   sessionEventStream?: boolean;
   sessionHealthKey?: string;
   rollingPDT?: boolean;
+  event?: boolean;
+  // Allowlist of query-parameter names permitted to be forwarded to the asset
+  // manager's getNextVod() request (issue #377). Only parameters whose name is
+  // present in this list may be passed through; all others are ignored. This
+  // issue only establishes the config surface — the actual pass-through is wired
+  // up in follow-ups (#378/#379/#380). Defaults to no allowlist (an empty list),
+  // i.e. no pass-through, when omitted.
+  customVodRequestParams?: string[];
+  // Base stream-switch polling interval in milliseconds (default 3000).
+  // This is the cadence at which the global StreamSwitchLoop calls
+  // updateStreamSwitchAsync() to evaluate live-schedule switches.
+  streamSwitchTimeIntervalMs?: number;
+  // Polling interval in milliseconds used while an event is ongoing (default 3000).
+  // "Ongoing event": the switcher is on a live stream (stream_switcher.js
+  // `this.streamTypeLive === true`) and the current scheduleObj is within its
+  // window, i.e. now >= scheduleObj.start_time && now < scheduleObj.end_time.
+  // A slower/less-frequent poll is acceptable in this steady state.
+  // NOTE: config surface only for now; the polling cadence still uses the base
+  // interval. Wire-up lands in the follow-up (#366).
+  streamSwitchOngoingEventIntervalMs?: number;
+  // Polling interval in milliseconds used when an event is near its end (default 1000).
+  // "Near end of event": an ongoing event whose remaining time is within the
+  // end-of-event guard window used by the switcher, i.e.
+  // scheduleObj.end_time - now <= 10000 (the 10000ms guard in
+  // stream_switcher.js ~L200). A faster poll here reduces switch latency at the
+  // boundary. Derived from that guard rather than a new unrelated constant.
+  // NOTE: config surface only for now; the polling cadence still uses the base
+  // interval. Wire-up lands in the follow-up (#366).
+  streamSwitchNearEndEventIntervalMs?: number;
 }
 
 interface StreamerOpts {
@@ -82,6 +140,12 @@ export interface VodRequest {
   sessionId: string;
   category?: string;
   playlistId: string;
+  // Optional custom pass-through parameters forwarded to the asset manager's
+  // getNextVod() (issue #378). Sourced from per-session state populated by the
+  // master-manifest request handler (wired up in #379) and filtered against the
+  // customVodRequestParams allowlist (#377). Optional and defaults to absent so
+  // existing IAssetManager implementations are unaffected.
+  customParams?: { [key: string]: string };
 }
 
 export interface VodResponseMetadata {
@@ -137,6 +201,10 @@ export interface Channel {
   audioTracks?: AudioTracks[];
   subtitleTracks?: SubtitleTracks[];
   closedCaptions?: ClosedCaptions[];
+  slate?: SlateOpts;
+  // Per-channel ad-break configuration. Overrides the engine-level `adBreak`
+  // default when present. Defaults to disabled when neither is set.
+  adBreak?: AdBreakOpts;
 }
 
 export interface ClosedCaptions {
@@ -196,6 +264,7 @@ export class ChannelEngine {
   private alwaysMapBandwidthByNearest: boolean;
   private defaultSlateUri?: string;
   private slateDuration?: number;
+  private adBreak?: AdBreakOpts;
   private assetMgr: IAssetManager;
   private streamSwitchManager?: any;
   private slateRepetitions?: number;
@@ -204,6 +273,8 @@ export class ChannelEngine {
   private serverStartTime: number;
   private instanceId: string;
   private streamSwitchTimeIntervalMs: number;
+  private streamSwitchOngoingEventIntervalMs: number;
+  private streamSwitchNearEndEventIntervalMs: number;
   private sessionStore: any;
   private sessionLiveStore: any;
   private streamerOpts: StreamerOpts;
@@ -214,7 +285,50 @@ export class ChannelEngine {
   private sessionResetKey: string = "";
   private sessionEventStream: boolean = false;
   private sessionHealthKey: string = "";
-  
+  // Allowlist of query-parameter names permitted to be forwarded to
+  // getNextVod() (issue #377). Config surface only — defaults to an empty list
+  // (no pass-through) when the option is omitted. Consumed in follow-ups
+  // (#378/#379/#380).
+  private customVodRequestParams: string[] = [];
+
+  // Validate and normalize an ad-break configuration (issue #367).
+  // Returns a config that is always defined and disabled-by-default:
+  //   - undefined/omitted            -> { enabled: false }
+  //   - { enabled: false, ... }      -> { enabled: false } (endpoint ignored)
+  //   - { enabled: true, adServerUri } -> validated, with the slate reference
+  //                                       (if any) carried through
+  // Throws when an enabled break is missing a syntactically valid absolute
+  // http(s) ad-serving endpoint URL. `scope` is only used for error context.
+  private static normalizeAdBreak(adBreak: AdBreakOpts | undefined, scope: string): AdBreakOpts {
+    if (!adBreak || !adBreak.enabled) {
+      return { enabled: false };
+    }
+    if (!adBreak.adServerUri) {
+      throw new Error(`Ad-break configuration (${scope}) is enabled but no adServerUri was provided`);
+    }
+    let parsed: URL;
+    try {
+      parsed = new URL(adBreak.adServerUri);
+    } catch (err) {
+      throw new Error(`Ad-break configuration (${scope}) has an invalid adServerUri: ${adBreak.adServerUri}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error(`Ad-break configuration (${scope}) adServerUri must be an http(s) URL: ${adBreak.adServerUri}`);
+    }
+    const normalized: AdBreakOpts = {
+      enabled: true,
+      adServerUri: adBreak.adServerUri
+    };
+    if (adBreak.slate && adBreak.slate.uri) {
+      normalized.slate = {
+        uri: adBreak.slate.uri,
+        repetitions: adBreak.slate.repetitions || 10,
+        duration: adBreak.slate.duration || 4000
+      };
+    }
+    return normalized;
+  }
+
   constructor(assetMgr: IAssetManager, options?: ChannelEngineOpts) {
     this.options = options;
     if (options && options.adCopyMgrUri) {
@@ -257,12 +371,23 @@ export class ChannelEngine {
       this.slateRepetitions = options.slateRepetitions || 10;
       this.slateDuration = options.slateDuration || 4000;
     }
+    // Ad-break config surface (issue #367). Validate and normalize the
+    // engine-level default; disabled when unset. Throws on an enabled break
+    // that lacks a valid ad-serving endpoint URL.
+    this.adBreak = ChannelEngine.normalizeAdBreak(options && options.adBreak, "engine");
     if (options && options.streamSwitchManager) {
       this.streamSwitchManager = options.streamSwitchManager;
     }
     if (options && options.autoCreateSession !== undefined) {
       this.autoCreateSession = options.autoCreateSession;
     }
+    // Custom VOD request-parameter allowlist (issue #377). Config surface only —
+    // stored on the instance so follow-ups (#378/#379/#380) can consume it.
+    // Defaults to an empty list (no pass-through) when omitted.
+    this.customVodRequestParams =
+      options && Array.isArray(options.customVodRequestParams)
+        ? options.customVodRequestParams
+        : [];
     this.assetMgr = assetMgr;
     this.monitorTimer = {};
     this.server = fastify;
@@ -276,7 +401,27 @@ export class ChannelEngine {
     this.serverStartTime = Date.now();
     this.instanceId = uuidv4();
 
-    this.streamSwitchTimeIntervalMs = 3000;
+    // Base stream-switch polling interval (ms). Configurable via options,
+    // defaults to the previously-hardcoded 3000ms. See ChannelEngineOpts.
+    this.streamSwitchTimeIntervalMs =
+      options && options.streamSwitchTimeIntervalMs !== undefined
+        ? options.streamSwitchTimeIntervalMs
+        : 3000;
+    // Polling interval (ms) while an event is ongoing. See "ongoing event"
+    // definition in ChannelEngineOpts. Defaults to the base interval (3000ms).
+    // Config surface only for now — not yet applied to the loop cadence (#366).
+    this.streamSwitchOngoingEventIntervalMs =
+      options && options.streamSwitchOngoingEventIntervalMs !== undefined
+        ? options.streamSwitchOngoingEventIntervalMs
+        : 3000;
+    // Polling interval (ms) when an event is near its end. See "near end of
+    // event" definition in ChannelEngineOpts, derived from the 10000ms
+    // end-of-event guard in stream_switcher.js. Defaults to a faster 1000ms.
+    // Config surface only for now — not yet applied to the loop cadence (#366).
+    this.streamSwitchNearEndEventIntervalMs =
+      options && options.streamSwitchNearEndEventIntervalMs !== undefined
+        ? options.streamSwitchNearEndEventIntervalMs
+        : 1000;
 
     this.sessionStore = {
       sessionStateStore: new SessionStateStore({
@@ -422,10 +567,15 @@ export class ChannelEngine {
           const ts_1 = Date.now();
           await this.updateStreamSwitchAsync()
           const ts_2 = Date.now();
-          const  interval = (timeIntervalMs - (ts_2 - ts_1)) < 0 ? minIntervalMs : (timeIntervalMs - (ts_2 - ts_1)); 
+          // Adaptive cadence: back off while all active channels are mid-event and
+          // speed up as any channel nears its end. The poll loop is global but event
+          // state is per-channel, so we take the MINIMUM interval required across all
+          // channels — never under-polling a channel that needs responsiveness.
+          const desiredIntervalMs = this.computeStreamSwitchIntervalMs(timeIntervalMs);
+          const  interval = (desiredIntervalMs - (ts_2 - ts_1)) < 0 ? minIntervalMs : (desiredIntervalMs - (ts_2 - ts_1));
           const tickInterval = await WTG.getWaitTime(interval);
           await timer(tickInterval)
-          debug(`StreamSwitchLoop waited for all channels. Next tick in: ${tickInterval}ms`)
+          debug(`StreamSwitchLoop waited for all channels. Next tick in: ${tickInterval}ms (desired base=${desiredIntervalMs}ms)`)
         } catch (err) {
           console.error(err)
           debug(`StreamSwitchLoop iteration failed. Trying Again in 1000ms!`);
@@ -438,6 +588,41 @@ export class ChannelEngine {
     }
   }
 
+  // Compute the desired next poll interval for the global StreamSwitchLoop from the
+  // aggregated per-channel event state. Because the loop is global but event state is
+  // per-channel, the result is the MINIMUM interval any channel requires so we never
+  // under-poll a channel that needs responsiveness:
+  //   - a channel that is near-end contributes the fast near-end interval;
+  //   - a channel that is mid-event but not near-end contributes the slower ongoing
+  //     interval;
+  //   - a channel with no ongoing event contributes the base interval.
+  // The loop uses the minimum across all channels. When no channel reports an ongoing
+  // event (no schedule / no ongoing event) this falls back to the base interval,
+  // keeping behavior identical to today.
+  computeStreamSwitchIntervalMs(baseIntervalMs) {
+    const channels = Object.keys(sessionSwitchers);
+    let desiredMs = baseIntervalMs;
+    for (const channel of channels) {
+      const switcher = sessionSwitchers[channel];
+      if (!switcher || typeof switcher.getEventPollingState !== "function") {
+        continue;
+      }
+      const state = switcher.getEventPollingState();
+      let channelMs;
+      if (state.nearEnd) {
+        channelMs = this.streamSwitchNearEndEventIntervalMs;
+      } else if (state.midEvent) {
+        channelMs = this.streamSwitchOngoingEventIntervalMs;
+      } else {
+        channelMs = baseIntervalMs;
+      }
+      if (channelMs < desiredMs) {
+        desiredMs = channelMs;
+      }
+    }
+    return desiredMs;
+  }
+
   async updateStreamSwitchAsync() {
     const channels = Object.keys(sessionSwitchers);
     const getSwitchStatusAndPerformSwitch = async (channel) => {
@@ -455,7 +640,7 @@ export class ChannelEngine {
           }
           switcherStatus[channel] = status;
         } catch (err) {
-          throw new Error (err);
+          throw err instanceof Error ? err : new Error(String(err));
         }
        } else {
         debug(`Tried to switch stream on a non-existing channel=[${channel}]. Switching Ignored!)`);
@@ -465,7 +650,7 @@ export class ChannelEngine {
       await Promise.all(channels.map(channel => getSwitchStatusAndPerformSwitch(channel)));
     } catch (err) {
       debug('Problem occured when updating streamSwitchers');
-      throw new Error (err);
+      throw err instanceof Error ? err : new Error(String(err));
     }
 
   }
@@ -499,9 +684,11 @@ export class ChannelEngine {
         slateUri: channel.slate && channel.slate.uri ? channel.slate.uri : this.defaultSlateUri,
         slateRepetitions: channel.slate && channel.slate.repetitions ? channel.slate.repetitions : this.slateRepetitions,
         slateDuration: channel.slate && channel.slate.duration ? channel.slate.duration : this.slateDuration,
+        adBreak: channel.adBreak ? ChannelEngine.normalizeAdBreak(channel.adBreak, `channel ${channel.id}`) : this.adBreak,
         cloudWatchMetrics: this.logCloudWatchMetrics,
         sessionEventStream: options.sessionEventStream,
-        rollingPDT: options.rollingPDT
+        rollingPDT: options.rollingPDT,
+        event: options.event
       }, this.sessionStore);
 
       sessionsLive[channel.id] = new SessionLive({
@@ -762,7 +949,22 @@ export class ChannelEngine {
     if (session) {
       const eventStream = new EventStream(session);
       eventStreams[session.sessionId] = eventStream;
-  
+
+      // Plumb allowlisted master.m3u8 query params into the session so the next
+      // _getNextVod() call includes them (#379). Sessions are persistent (created
+      // once in updateChannelsAsync and reused), so scope custom params per request:
+      // set them on every master-manifest request — using an empty object when the
+      // allowlist is unset or no allowlisted params are present — so a later request
+      // without them doesn't inherit a previous request's values. Non-allowlisted
+      // params are ignored.
+      const customParams: { [key: string]: string } = {};
+      for (const key of this.customVodRequestParams) {
+        if (request.query[key] !== undefined) {
+          customParams[key] = request.query[key];
+        }
+      }
+      session.setCustomParams(customParams);
+
       let filter;
       if (request.query['filter']) {
         debug(`Applying filter on master manifest ${request.query['filter']}`);