eyevinn-channel-engine 5.1.2 → 5.2.0

package/dist/engine/server.js

@@ -43,6 +43,7 @@ class ChannelEngine {
     alwaysMapBandwidthByNearest;
     defaultSlateUri;
     slateDuration;
+    adBreak;
     assetMgr;
     streamSwitchManager;
     slateRepetitions;
@@ -51,6 +52,8 @@ class ChannelEngine {
     serverStartTime;
     instanceId;
     streamSwitchTimeIntervalMs;
+    streamSwitchOngoingEventIntervalMs;
+    streamSwitchNearEndEventIntervalMs;
     sessionStore;
     sessionLiveStore;
     streamerOpts;
@@ -61,6 +64,49 @@ class ChannelEngine {
     sessionResetKey = "";
     sessionEventStream = false;
     sessionHealthKey = "";
+    // 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).
+    customVodRequestParams = [];
+    // 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.
+    static normalizeAdBreak(adBreak, scope) {
+        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;
+        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 = {
+            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, options) {
         this.options = options;
         if (options && options.adCopyMgrUri) {
@@ -101,12 +147,23 @@ 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;
@@ -117,7 +174,27 @@ class ChannelEngine {
         this.server.options('*', preflight.handler);
         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({
                 redisUrl: options.redisUrl,
@@ -255,10 +332,15 @@ 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);
@@ -271,6 +353,42 @@ class ChannelEngine {
             StreamSwitchLoop(this.streamSwitchTimeIntervalMs);
         }
     }
+    // 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) => {
@@ -289,7 +407,7 @@ class ChannelEngine {
                     switcherStatus[channel] = status;
                 }
                 catch (err) {
-                    throw new Error(err);
+                    throw err instanceof Error ? err : new Error(String(err));
                 }
             }
             else {
@@ -301,7 +419,7 @@ class ChannelEngine {
         }
         catch (err) {
             debug('Problem occured when updating streamSwitchers');
-            throw new Error(err);
+            throw err instanceof Error ? err : new Error(String(err));
         }
     }
     async updateChannelsAsync(channelMgr, options) {
@@ -333,9 +451,11 @@ 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({
                 sessionId: channel.id,
@@ -572,6 +692,20 @@ 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 = {};
+            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']}`);

package/dist/engine/session.d.ts

@@ -1,148 +1 @@
-export = Session;
-declare class Session {
-    /**
-     *
-     * config: {
-     *   startWithId,
-     * }
-     *
-     */
-    constructor(assetManager: any, config: any, sessionStore: any);
-    _assetManager: any;
-    _sessionId: any;
-    _sessionStateStore: any;
-    _playheadStateStore: any;
-    _instanceId: any;
-    currentMetadata: {};
-    _events: any[];
-    averageSegmentDuration: any;
-    use_demuxed_audio: boolean;
-    use_vtt_subtitles: any;
-    dummySubtitleEndpoint: any;
-    subtitleSliceEndpoint: any;
-    cloudWatchLogging: boolean;
-    playheadDiffThreshold: any;
-    maxTickInterval: any;
-    maxTickIntervalIsDefault: boolean;
-    diffCompensationRate: any;
-    diffCompensation: any;
-    timePositionOffset: number;
-    prevVodMediaSeq: {
-        video: any;
-        audio: any;
-        subtitle: any;
-    };
-    prevMediaSeqOffset: {
-        video: any;
-        audio: any;
-        subtitle: any;
-    };
-    waitingForNextVod: boolean;
-    leaderIsSettingNextVod: boolean;
-    isSwitchingBackToV2L: boolean;
-    switchDataForSession: {
-        mediaSeq: any;
-        discSeq: any;
-        mediaSeqOffset: any;
-        transitionSegments: any;
-        audioSeq: any;
-        discAudioSeq: any;
-        audioSeqOffset: any;
-        transitionAudioSegments: any;
-        reloadBehind: any;
-    };
-    isAllowedToClearVodCache: boolean;
-    alwaysNewSegments: any;
-    alwaysMapBandwidthByNearest: any;
-    partialStoreHLSVod: any;
-    currentPlayheadRef: any;
-    disableLegacyMasterManifestFormat: any;
-    rollingPDT: any;
-    _category: any;
-    startWithId: any;
-    _sessionProfile: any;
-    _audioTracks: any;
-    _subtitleTracks: any;
-    _closedCaptions: any;
-    _noSessionDataTags: any;
-    _sessionEventStream: any;
-    slateUri: any;
-    slateRepetitions: any;
-    slateDuration: any;
-    disabledPlayhead: boolean;
-    targetDurationPadding: any;
-    forceTargetDuration: any;
-    initAsync(): Promise<void>;
-    _sessionState: any;
-    _playheadState: any;
-    get sessionId(): any;
-    startPlayheadAsync(): Promise<void>;
-    restartPlayheadAsync(): Promise<void>;
-    stopPlayheadAsync(): Promise<void>;
-    getStatusAsync(): Promise<{
-        sessionId: any;
-        playhead: {
-            state: any;
-            tickMs: any;
-            mediaSeq: any;
-        };
-        slateInserted: any;
-    } | {
-        sessionId: any;
-    }>;
-    resetAsync(id: any): Promise<void>;
-    getSessionState(): Promise<any>;
-    getTruncatedVodSegments(vodUri: any, duration: any): Promise<any>;
-    getTruncatedVodAudioSegments(vodUri: any, duration: any): Promise<any>;
-    setCurrentMediaSequenceSegments(segments: any, mSeqOffset: any, reloadBehind: any, audioSegments: any, aSeqOffset: any): Promise<void>;
-    getCurrentMediaSequenceSegments(opts: any): Promise<any>;
-    getCurrentAudioSequenceSegments(opts: any): Promise<any>;
-    setCurrentMediaAndDiscSequenceCount(_mediaSeq: any, _discSeq: any, _audioSeq: any, _discAudioSeq: any): Promise<void>;
-    getCurrentMediaAndDiscSequenceCount(): Promise<{
-        mediaSeq: any;
-        discSeq: any;
-        vodMediaSeqVideo: any;
-    }>;
-    getCurrentMediaManifestAsync(bw: any, playbackSessionId: any): Promise<any>;
-    getCurrentAudioManifestAsync(audioGroupId: any, audioLanguage: any, playbackSessionId: any): Promise<any>;
-    getCurrentSubtitleManifestAsync(subtitleGroupId: any, subtitleLanguage: any, playbackSessionId: any): Promise<any>;
-    incrementAsync(): Promise<any>;
-    getMediaManifestAsync(bw: any, opts: any): Promise<any>;
-    getAudioManifestAsync(audioGroupId: any, audioLanguage: any, opts: any): Promise<any>;
-    getMasterManifestAsync(filter: any): Promise<string>;
-    getAudioGroupsAndLangs(): Promise<{}>;
-    getSubtitleGroupsAndLangs(): Promise<{}>;
-    consumeEvent(): any;
-    produceEvent(event: any): void;
-    hasPlayhead(): boolean;
-    _insertSlate(currentVod: any): Promise<any>;
-    _tickAsync(): Promise<void>;
-    _lastTickState: {
-        sessionState: any;
-        isLeader: any;
-        currentVod: any;
-    };
-    _getNextVod(): Promise<any>;
-    _loadSlate(afterVod: any, reps: any, unixTs: any): Promise<any>;
-    _truncateVod(vodResponse: any): Promise<any>;
-    _truncateSlate(afterVod: any, requestedDuration: any, vodUri: any, unixTs: any): Promise<any>;
-    _fillGap(afterVod: any, desiredDuration: any, unixTs: any): Promise<any>;
-    _getNextVodById(id: any): Promise<any>;
-    _getFirstDuration(manifest: any): Promise<any>;
-    _getCurrentDeltaTime(): Promise<any>;
-    _getCurrentPlayheadPosition(): Promise<any>;
-    _getAudioPlayheadPosition(seqIdx: any): Promise<any>;
-    _getSubtitlePlayheadPosition(seqIdx: any): Promise<any>;
-    _getLastDuration(manifest: any): Promise<any>;
-    _getPlayheadDiffCompensationValue(diffMs: any, thresholdMs: any): number;
-    _isOldVod(refTs: any, vodDur: any): boolean;
-    _determineExtraMediaIncrement(_extraType: any, _currentPosVideo: any, _extraSeqFinalIndex: any, _vodMediaSeqExtra: any, _getExtraPlayheadPositionAsyncFn: any): Promise<{
-        increment: number;
-        position: number;
-        diff: string;
-    }>;
-    _getM3u8File(variantType: any, variantKey: any, playbackSessionId: any): Promise<any>;
-    _getCurrentVodData(dataName: any, variantType: any, vod: any): any;
-    _logCurrentPlayheadPositions(playheadPosVideoMs: any, playheadAudio: any, playheadSubtitle: any): void;
-    _logAllPlayheadPositions: (sessionId: any, vod: any) => void;
-}
+export {};