@gcorevideo/player 2.28.36 → 2.30.0

package/lib/plugins/token-refresh/TokenRefreshPlugin.js

@@ -0,0 +1,318 @@
+import { $, CorePlugin, Events } from '@clappr/core';
+import HLSJS from 'hls.js';
+import { trace } from '@gcorevideo/utils';
+import { CLAPPR_VERSION } from '../../build.js';
+const T = 'plugins.token_refresh';
+/**
+ * Matches the `/{token}/{expires}/` segment in a Gcore protected-content URL.
+ * Token is base64url (letters, digits, `-`, `_`); expires is a ≥10-digit Unix timestamp.
+ */
+const TOKEN_SEGMENT_RE = /\/([A-Za-z0-9_-]{6,})\/(1\d{9,})\//;
+function extractTokenState(url) {
+    const m = url.match(TOKEN_SEGMENT_RE);
+    if (!m)
+        return null;
+    return { token: m[1], expires: parseInt(m[2], 10) };
+}
+/** Replaces the exact `/{oldToken}/{oldExpires}/` segment in a URL. */
+function rewriteUrl(url, from, to) {
+    const oldPart = `/${from.token}/${from.expires}/`;
+    const newPart = `/${to.token}/${to.expires}/`;
+    return url.includes(oldPart) ? url.replace(oldPart, newPart) : url;
+}
+/**
+ * Normalises a URL by removing the `/{token}/{expires}/` segment so two URLs
+ * for the same stream with different token pairs compare equal.
+ * Returns `null` for unparseable input.
+ */
+function streamKey(url) {
+    try {
+        const u = new URL(url);
+        return u.origin + u.pathname.replace(TOKEN_SEGMENT_RE, '/');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns a custom hls.js loader class that transparently rewrites the
+ * token/expires path segments in every request URL.
+ *
+ * The returned class extends the default hls.js XhrLoader so all native
+ * hls.js behaviour (retry, timeout, range requests …) is preserved.
+ */
+function createTokenRewritingLoader(getOriginal, getCurrent) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const DefaultLoader = HLSJS.DefaultConfig.loader;
+    return class TokenRewritingLoader extends DefaultLoader {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        load(context, config, callbacks) {
+            const original = getOriginal();
+            const current = getCurrent();
+            if (original && current && context.url) {
+                context.url = rewriteUrl(context.url, original, current);
+            }
+            super.load(context, config, callbacks);
+        }
+    };
+}
+/**
+ * `PLUGIN` — automatic token refresh for Gcore protected-content streams.
+ *
+ * Supports all three playback engines:
+ *
+ * | Engine | Mechanism | Interruption |
+ * |--------|-----------|--------------|
+ * | **hls.js** | Custom loader rewrites every request URL | None |
+ * | **dash.js** | `addRequestInterceptor` rewrites every request URL | None |
+ * | **Native `<video>`** (Safari ≤ iOS 14.4) | Source reload + seek restore | Brief |
+ *
+ * @public
+ * @remarks
+ * Register the plugin once before creating any player instance:
+ * ```ts
+ * import { Player, TokenRefreshPlugin } from '@gcorevideo/player'
+ * Player.registerPlugin(TokenRefreshPlugin)
+ * ```
+ *
+ * Then pass `tokenRefresh` in `PlayerConfig`:
+ * ```ts
+ * const player = new Player({
+ *   sources: [{ source: initialUrl, mimeType: 'application/x-mpegURL' }],
+ *   tokenRefresh: {
+ *     getToken: () => fetch('https://…/token').then(r => r.json()),
+ *     ipBound: false,
+ *     refreshLeadSeconds: 5,
+ *     onTokenRefreshed: (data) => console.log('new token expires', data.expires),
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * Safari native — opt-in Service Worker for fully seamless refresh:
+ * ```js
+ * // Register token-refresh-sw.js (see example/ directory)
+ * // and omit tokenRefresh config — the SW handles rewriting.
+ * ```
+ */
+export class TokenRefreshPlugin extends CorePlugin {
+    /** @internal */
+    static get type() {
+        return 'core';
+    }
+    /** @internal */
+    get name() {
+        return 'token_refresh';
+    }
+    /** @internal */
+    get supportedVersion() {
+        return { min: CLAPPR_VERSION };
+    }
+    /** Token state extracted from the currently-managed source URL */
+    originalState = null;
+    /** Latest token state (updated after each refresh) */
+    currentState = null;
+    /** Scheduled refresh timer handle */
+    refreshTimer = null;
+    /** Playback time (seconds) to restore after a native-video source reload */
+    savedPosition = null;
+    /** True when using native HTML5 Video playback (no request interception) */
+    isNativePlayback = false;
+    /** Set in destroy(); short-circuits late timer callbacks and getToken() resolutions */
+    destroyed = false;
+    /** @internal */
+    bindEvents() {
+        this.listenTo(this.core, Events.CORE_CONTAINERS_CREATED, this.onContainersCreated);
+    }
+    /** @internal */
+    destroy() {
+        this.destroyed = true;
+        this.clearTimer();
+        super.destroy();
+    }
+    onContainersCreated() {
+        const container = this.core.containers[0];
+        if (!container)
+            return;
+        const playbackName = container.playback.name;
+        const src = container.playback.options?.src ?? '';
+        trace(`${T} onContainersCreated`, { playbackName, src: src.slice(0, 80) });
+        this.isNativePlayback = playbackName !== 'hls' && playbackName !== 'dash';
+        const state = extractTokenState(src);
+        if (!state) {
+            // Active source has no token pattern — drop any refresh state we were
+            // holding for a previous stream (e.g. SourceController rotated away).
+            if (this.originalState) {
+                trace(`${T} active source has no token pattern — clearing refresh state`);
+                this.clearTimer();
+                this.originalState = null;
+                this.currentState = null;
+            }
+            return;
+        }
+        // Adopt the new token state if this is the first source we see, or if
+        // the stream has changed (SourceController rotated, consumer called
+        // player.load() with a different stream, or the plugin itself reloaded
+        // with a refreshed URL in the native path).
+        const isNewStream = !this.originalState ||
+            state.token !== this.originalState.token ||
+            state.expires !== this.originalState.expires;
+        if (isNewStream) {
+            trace(`${T} adopting source token state`, {
+                token: state.token.slice(0, 8) + '…',
+                expires: new Date(state.expires * 1000).toISOString(),
+            });
+            this.originalState = { ...state };
+            this.currentState = { ...state };
+            this.scheduleRefresh();
+        }
+        // Inject the appropriate interception mechanism for this playback engine.
+        switch (playbackName) {
+            case 'hls':
+                this.injectHlsLoader(container);
+                break;
+            case 'dash':
+                this.injectDashInterceptor(container);
+                break;
+            default:
+                // Native HTML5 Video — no request hooks available.
+                // Seek restore after a token-triggered reload.
+                this.listenToOnce(this.core, Events.CORE_ACTIVE_CONTAINER_CHANGED, this.onActiveContainerChangedForNative);
+                break;
+        }
+    }
+    injectHlsLoader(container) {
+        const getOriginal = () => this.originalState;
+        const getCurrent = () => this.currentState;
+        const TokenLoader = createTokenRewritingLoader(getOriginal, getCurrent);
+        $.extend(true, container.playback.options, {
+            playback: {
+                hlsjsConfig: {
+                    loader: TokenLoader,
+                },
+            },
+        });
+        trace(`${T} HLS custom loader injected`);
+    }
+    injectDashInterceptor(container) {
+        $.extend(true, container.playback.options, {
+            dash: {
+                requestInterceptor: (request) => {
+                    if (this.originalState && this.currentState) {
+                        request.url = rewriteUrl(request.url, this.originalState, this.currentState);
+                    }
+                    return Promise.resolve(request);
+                },
+            },
+        });
+        trace(`${T} DASH request interceptor injected`);
+    }
+    async reloadNativeSource(data) {
+        const container = this.core.activeContainer;
+        const playback = container?.playback;
+        if (!playback)
+            return;
+        // SourceController (or any other actor) may have switched the active
+        // playback to hls/dash while getToken() was in flight. Those engines
+        // have their own request-interception path; a native reload would
+        // undo the switch.
+        if (playback.name === 'hls' || playback.name === 'dash') {
+            trace(`${T} skipping native reload — active playback is ${playback.name}`);
+            return;
+        }
+        if (!this.isNativePlayback) {
+            trace(`${T} skipping native reload — no longer in native playback mode`);
+            return;
+        }
+        // Verify the URL we're about to load belongs to the same stream that's
+        // currently active. If SourceController rotated to a different stream
+        // during the getToken() await, the refreshed URL would silently swap
+        // us back, undoing SourceController's decision.
+        const currentSrc = playback.options?.src ?? '';
+        const newUrl = this.opts.ipBound ? data.url_ip : data.url;
+        const activeKey = streamKey(currentSrc);
+        const nextKey = streamKey(newUrl);
+        if (!activeKey || !nextKey || activeKey !== nextKey) {
+            trace(`${T} skipping native reload — active source differs from refresh URL`, {
+                activeKey,
+                nextKey,
+            });
+            return;
+        }
+        // Capture current playback position before tearing down the container.
+        const mediaEl = playback.el;
+        const currentTime = mediaEl?.currentTime ?? 0;
+        this.savedPosition = currentTime > 0 ? currentTime : null;
+        trace(`${T} native reload`, { newUrl: newUrl.slice(0, 80), savedPosition: this.savedPosition });
+        // core.load() destroys and recreates all containers.
+        this.core.load([{ source: newUrl, mimeType: this.core.options.mimeType ?? 'application/x-mpegURL' }]);
+    }
+    onActiveContainerChangedForNative() {
+        if (this.savedPosition === null)
+            return;
+        const pos = this.savedPosition;
+        this.savedPosition = null;
+        // Wait for the new container to be fully ready before seeking.
+        const container = this.core.activeContainer;
+        if (!container)
+            return;
+        this.listenToOnce(container, Events.CONTAINER_READY, () => {
+            trace(`${T} native: restoring position`, { pos });
+            container.seek(pos);
+            container.play();
+        });
+    }
+    scheduleRefresh() {
+        this.clearTimer();
+        if (this.destroyed || !this.currentState)
+            return;
+        const leadMs = (this.opts.refreshLeadSeconds ?? 5) * 1000;
+        const msUntilRefresh = this.currentState.expires * 1000 - Date.now() - leadMs;
+        trace(`${T} next refresh in`, {
+            seconds: Math.round(msUntilRefresh / 1000),
+            expires: new Date(this.currentState.expires * 1000).toISOString(),
+        });
+        this.refreshTimer = setTimeout(() => this.performRefresh(), Math.max(msUntilRefresh, 1000));
+    }
+    async performRefresh() {
+        trace(`${T} fetching new token`);
+        try {
+            const data = await this.opts.getToken();
+            // Plugin may have been destroyed while getToken() was in flight; drop the result.
+            if (this.destroyed)
+                return;
+            const newToken = this.opts.ipBound ? data.token_ip : data.token;
+            const newState = { token: newToken, expires: data.expires };
+            if (this.isNativePlayback) {
+                // Must reload source because the <video> element has no request hook.
+                await this.reloadNativeSource(data);
+            }
+            // originalState is never changed after init — it holds the token that was
+            // baked into every URL in the initial manifest. hls.js/dash.js always
+            // produces request URLs based on that manifest, so every segment URL
+            // still contains the original token regardless of how many refreshes
+            // have already happened. The loader replaces original→current on each
+            // request, so updating only currentState is sufficient.
+            this.currentState = newState;
+            this.opts.onTokenRefreshed?.(data);
+            trace(`${T} token refreshed`, {
+                token: newToken.slice(0, 8) + '…',
+                expires: new Date(data.expires * 1000).toISOString(),
+            });
+        }
+        catch (err) {
+            trace(`${T} token refresh failed`, { err });
+        }
+        // Always reschedule, even after an error (will retry near next expiry).
+        this.scheduleRefresh();
+    }
+    get opts() {
+        return this.options.tokenRefresh;
+    }
+    clearTimer() {
+        if (this.refreshTimer !== null) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+}

package/lib/plugins/token-refresh/index.d.ts

@@ -0,0 +1,2 @@
+export { TokenRefreshPlugin, type TokenRefreshOptions, type TokenResponse, } from './TokenRefreshPlugin.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/plugins/token-refresh/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/token-refresh/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACnB,MAAM,yBAAyB,CAAA"}

package/lib/plugins/token-refresh/index.js

@@ -0,0 +1 @@
+export { TokenRefreshPlugin, } from './TokenRefreshPlugin.js';

package/lib/utils/mediaSources.d.ts

@@ -1,7 +1,11 @@
 import type { PlayerMediaSource, PlayerMediaSourceDesc, TransportPreference } from '../types';
+export declare const MIME_TYPES_HLS: string[];
+export declare const MIME_TYPE_HLS: string;
+export declare const MIME_TYPE_DASH = "application/dash+xml";
 export declare function buildMediaSourcesList(sources: PlayerMediaSourceDesc[], priorityTransport?: TransportPreference): PlayerMediaSourceDesc[];
 export declare function unwrapSource(s: PlayerMediaSource): string;
 export declare function wrapSource(s: PlayerMediaSource): PlayerMediaSourceDesc;
+export declare function guessMimeType(s: string): string | undefined;
 export declare function isDashSource(source: string, mimeType?: string): boolean;
 export declare function isHlsSource(source: string, mimeType?: string): boolean;
 //# sourceMappingURL=mediaSources.d.ts.map

package/lib/utils/mediaSources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mediaSources.d.ts","sourceRoot":"","sources":["../../src/utils/mediaSources.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,UAAU,CAAA;AAIjB,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,qBAAqB,EAAE,EAChC,iBAAiB,GAAE,mBAA4B,GAC9C,qBAAqB,EAAE,CAqCzB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAEzD;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,iBAAiB,GAAG,qBAAqB,CAEtE;AAYD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,WAK7D;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,WAO5D"}
+{"version":3,"file":"mediaSources.d.ts","sourceRoot":"","sources":["../../src/utils/mediaSources.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,UAAU,CAAA;AAGjB,eAAO,MAAM,cAAc,UAA6D,CAAA;AACxF,eAAO,MAAM,aAAa,QAAoB,CAAA;AAC9C,eAAO,MAAM,cAAc,yBAAyB,CAAA;AAGpD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,qBAAqB,EAAE,EAChC,iBAAiB,GAAE,mBAA4B,GAC9C,qBAAqB,EAAE,CAqCzB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAEzD;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,iBAAiB,GAAG,qBAAqB,CAEtE;AAGD,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO3D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,WAK7D;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,WAO5D"}

package/lib/utils/mediaSources.js

@@ -1,5 +1,8 @@
 import { Loader } from '@clappr/core';
 import { trace } from '@gcorevideo/utils';
+export const MIME_TYPES_HLS = ['application/x-mpegurl', 'application/vnd.apple.mpegurl'];
+export const MIME_TYPE_HLS = MIME_TYPES_HLS[0];
+export const MIME_TYPE_DASH = 'application/dash+xml';
 // TODO rewrite using the Playback classes and canPlay static methods
 export function buildMediaSourcesList(sources, priorityTransport = 'dash') {
     const playbacks = Loader.registeredPlaybacks;
@@ -40,24 +43,23 @@ export function unwrapSource(s) {
 export function wrapSource(s) {
     return typeof s === 'string' ? { source: s, mimeType: guessMimeType(s) } : s;
 }
-function guessMimeType(s) {
+export function guessMimeType(s) {
     if (s.endsWith('.mpd')) {
-        return 'application/dash+xml';
+        return MIME_TYPE_DASH;
     }
     if (s.endsWith('.m3u8')) {
-        // return 'application/vnd.apple.mpegurl'
-        return 'application/x-mpegurl';
+        return MIME_TYPE_HLS;
     }
 }
 export function isDashSource(source, mimeType) {
     if (mimeType) {
-        return mimeType === 'application/dash+xml'; // TODO consider video/mp4
+        return mimeType === MIME_TYPE_DASH; // TODO consider video/mp4
     }
     return source.endsWith('.mpd');
 }
 export function isHlsSource(source, mimeType) {
     if (mimeType) {
-        return ['application/vnd.apple.mpegurl', 'application/x-mpegurl'].includes(mimeType.toLowerCase());
+        return MIME_TYPES_HLS.includes(mimeType.toLowerCase());
     }
     return source.endsWith('.m3u8');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcorevideo/player",
-  "version": "2.28.36",
+  "version": "2.30.0",
   "description": "Gcore JavaScript video player",
   "main": "dist/index.js",
   "type": "module",

package/src/Player.ts

@@ -278,6 +278,18 @@ export class Player {
     this.player?.load(ms, ms[0].mimeType ?? '')
   }
 
+  /**
+   * Returns a registered core plugin instance by name, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const tokenRefresh = player.getPlugin('token_refresh') as TokenRefreshPlugin | null
+   * ```
+   */
+  getPlugin(name: string) {
+    return this.player?.core.getPlugin(name) ?? null
+  }
+
   /**
    * Mutes the sound of the video.
    */

package/src/index.plugins.ts

@@ -36,4 +36,5 @@ export * from './plugins/telemetry/Telemetry.js'
 export * from './plugins/thumbnails/Thumbnails.js'
 // _ vast-ads
 // _ video360
+export * from './plugins/token-refresh/index.js'
 export * from './plugins/volume-fade/VolumeFade.js'

package/src/playback/dash-playback/DashPlayback.ts

@@ -30,11 +30,10 @@ import {
   QualityLevel,
   TimePosition,
   TimeValue,
-  VTTCueInfo,
 } from '../../playback.types.js'
 import { isDashSource } from '../../utils/mediaSources.js'
 import { BasePlayback } from '../BasePlayback.js'
-import { PlaybackEvents } from '../types.js'
+import { PlaybackEvents, VTTCueInfo } from '../types.js'
 import { AudioTrack } from '@clappr/core/types/base/playback/playback.js'
 
 const AUTO = -1
@@ -244,6 +243,7 @@ export default class DashPlayback extends BasePlayback {
     this._dash.initialize()
 
     if (this.options.dash) {
+      const { requestInterceptor, ...dashSettings } = this.options.dash as Record<string, unknown>
       const settings = $.extend(
         true,
         {
@@ -258,9 +258,13 @@ export default class DashPlayback extends BasePlayback {
             },
           },
         },
-        this.options.dash,
+        dashSettings,
       )
       this._dash.updateSettings(settings)
+
+      if (typeof requestInterceptor === 'function') {
+        this._dash.addRequestInterceptor(requestInterceptor as Parameters<typeof this._dash.addRequestInterceptor>[0])
+      }
     }
 
     this._dash.attachView(this.el as HTMLMediaElement)

package/src/playback/hls-playback/HlsPlayback.ts

@@ -26,7 +26,6 @@ import {
   PlayerComponentType,
   QualityLevel,
   TimePosition,
-  VTTCueInfo,
 } from '../../playback.types.js'
 import { PlaybackType } from '../../types.js'
 import { isHlsSource } from '../../utils/mediaSources.js'
@@ -35,6 +34,7 @@ import { BasePlayback } from '../BasePlayback.js'
 
 import { CLAPPR_VERSION } from '../../build.js'
 import { AudioTrack } from '@clappr/core/types/base/playback/playback.js'
+import { VTTCueInfo } from '../types.js'
 
 const { now } = Utils
 

package/src/playback/types.ts

@@ -6,3 +6,13 @@ export enum PlaybackEvents {
    */
   PLAYBACK_RATE_CHANGED = 'playback:rate-changed',
 }
+
+/**
+ * @internal
+ */
+export type VTTCueInfo = {
+  id: string
+  start: number
+  end: number
+  text: string
+}

package/src/playback.types.ts

@@ -145,9 +145,3 @@ export interface PlaybackError {
   }
 }
 
-export type VTTCueInfo = {
-  id: string
-  start: number
-  end: number
-  text: string
-}