react-native-audio-browser 0.2.0-next.18 → 0.2.0-next.19

package/lib/commonjs/web/http/followMediaRedirect.js

@@ -0,0 +1,219 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.followMediaRedirect = followMediaRedirect;
+/**
+ * Resolves a media URL that is authenticated by a header.
+ *
+ * Shaka only routes manifest requests through its networking engine, where a
+ * request filter can attach headers. A progressive file is played by assigning
+ * `mediaElement.src`, and a media element cannot send custom headers — so such
+ * a URL is unplayable that way. Following the redirect here yields the signed,
+ * public URL these endpoints hand back, which needs no auth of its own.
+ *
+ * Best effort and bounded: anything that fails — including taking too long, see
+ * {@link PROBE_TIMEOUT_MS} — falls back to the original URL, so the load fails
+ * or succeeds on its own terms rather than ours. It must never be the reason a
+ * load hangs: `load()` awaits this before Shaka sees the URL at all.
+ *
+ * Gated, because the probe is not free: a HEAD at a third-party stream host
+ * costs a CORS preflight, and most will refuse it, so an app that never
+ * authenticates its media would pay a round trip on every play for a result it
+ * always discards. It runs only for headers that look like media credentials
+ * ({@link isMediaAuth}), on media a media element actually has to play
+ * ({@link isManifestUrl}), and never on a URL the browser resolves locally.
+ */
+
+/** URLs the browser resolves locally; there is no redirect to follow. */
+const isLocalUrl = url => /^(file|blob|data|mediasource):/i.test(url);
+
+/**
+ * Extensions Shaka types as a manifest, from its own `EXTENSIONS_TO_MIME_TYPES_`
+ * map: HLS, DASH and Smooth Streaming.
+ */
+const MANIFEST_EXTENSIONS = new Set(['m3u8', 'mpd', 'ism']);
+
+/**
+ * Whether Shaka will parse this as a manifest rather than hand it to the media
+ * element — in which case the probe has nothing to offer and something to cost.
+ *
+ * A manifest goes through Shaka's networking engine, where the request filter
+ * attaches the headers to the manifest, its segments and any key requests. The
+ * probe cannot improve on that, and it actively breaks it: on a cross-origin
+ * redirect the probe clears the headers, so the segments that Android still
+ * authenticates would go out bare and 401. So this is a correctness fix as much
+ * as it is one fewer round trip.
+ *
+ * Extension-based, and therefore partial — Shaka guesses the same way
+ * (`NetworkingUtils.getExtension`), but plenty of HLS endpoints have no
+ * extension at all. Those still get probed, which is the status quo rather than
+ * a regression. Nothing on `Track` carries a MIME type to do better with.
+ */
+const isManifestUrl = url => {
+  const path = url.split(/[?#]/)[0] ?? '';
+  const filename = path.slice(path.lastIndexOf('/') + 1);
+  const pieces = filename.split('.');
+  return pieces.length > 1 && MANIFEST_EXTENSIONS.has(pieces[pieces.length - 1].toLowerCase());
+};
+/**
+ * How long the probe may take before the original URL is played instead.
+ *
+ * The same 8s the Android media client allows a connect or a read
+ * (`MediaFactory.mediaHttpClient`), which is generous for a HEAD but errs the
+ * safe way: a slow-but-working auth endpoint should not be abandoned, since
+ * giving up means playing a URL that will 401.
+ */
+const PROBE_TIMEOUT_MS = 8_000;
+
+/**
+ * `AbortSignal.timeout` where it exists (Safari 16+, Chrome 103+, Node 17.3+),
+ * else a hand-rolled equivalent, else nothing — an environment with neither
+ * still gets the deadline below, just without cancelling the request.
+ */
+const timeoutSignal = ms => {
+  if (typeof AbortSignal === 'undefined') return undefined;
+  if (typeof AbortSignal.timeout === 'function') return AbortSignal.timeout(ms);
+  if (typeof AbortController === 'undefined') return undefined;
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), ms);
+  return controller.signal;
+};
+
+/**
+ * The probe, with a deadline. `load()` awaits this before Shaka is asked to
+ * play anything, so an unreachable host would otherwise stall the load
+ * indefinitely — no audio, and no error to show for it.
+ *
+ * Two mechanisms, each with its own job: the signal cancels the request, so a
+ * dead host does not hold a connection open behind us, and the race bounds *us*
+ * even where the fetch implementation ignores the signal. Whichever fires, the
+ * caller treats it as any other probe failure and plays the original URL.
+ */
+const fetchWithDeadline = async (doFetch, url, headers, timeoutMs) => {
+  let timer;
+  try {
+    return await Promise.race([doFetch(url, {
+      method: 'HEAD',
+      headers,
+      redirect: 'follow',
+      signal: timeoutSignal(timeoutMs)
+    }), new Promise((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error(`Media redirect probe timed out (${timeoutMs}ms)`)), timeoutMs);
+    })]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+};
+
+/**
+ * Whether these headers look like a media credential — the only thing the
+ * probe can fix, and the only thing worth a preflight.
+ *
+ * A header the `media` layer set is media-specific by construction. Otherwise
+ * only `Authorization` counts: an app authenticating one API for browse and
+ * media alike puts it on the shared `request` layer, and that is the common
+ * shape. Shared plumbing that also rides browse requests — an `X-Client-Version`
+ * — is not a credential and must not trigger the probe.
+ *
+ * The residual case is a shared layer carrying a custom auth header, say
+ * `X-Api-Key`, for media that needs it: move it to the `media` layer and the
+ * probe runs.
+ */
+const isMediaAuth = (headers, mediaLayerHeaders) => mediaLayerHeaders || Object.keys(headers).some(key => key.toLowerCase() === 'authorization');
+/**
+ * Origin of an http(s) URL, or undefined when it cannot be determined.
+ *
+ * Relative URLs are resolved against the document, because that is what the
+ * probe's own `fetch` does — a `src` of `/api/authed/7` is a request to the
+ * page's origin, so the credential went there. Without this a relative `src`
+ * has no origin, never matches the absolute URL the response reports, and the
+ * headers are dropped from every load that uses one.
+ *
+ * Parsed rather than pattern-matched so the comparison normalizes the way
+ * Android's `CrossOriginHeaderStripper.sameOrigin` does: `URL.host` omits a
+ * default port, so `https://a.com` and `https://a.com:443` are one origin, and
+ * it excludes userinfo, so `https://user@a.com` is not a third.
+ */
+const originOf = url => {
+  try {
+    const base = typeof location === 'undefined' ? undefined : location.href;
+    const {
+      protocol,
+      host
+    } = new URL(url, base);
+    if (protocol !== 'http:' && protocol !== 'https:') return undefined;
+    return `${protocol}//${host}`;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Whether the redirect left the origin the credential was addressed to.
+ *
+ * Only when both origins are known and differ. An origin we could not work out
+ * — a relative URL with no document base, outside a browser — is not evidence
+ * of a hop, and treating it as one is how the headers went missing before.
+ */
+const leftTheOrigin = (from, to) => {
+  const origin = originOf(from);
+  return origin !== undefined && originOf(to) !== origin;
+};
+async function followMediaRedirect(url, headers, {
+  fetchImpl,
+  mediaLayerHeaders = false,
+  timeoutMs = PROBE_TIMEOUT_MS
+} = {}) {
+  if (!headers || Object.keys(headers).length === 0) return {
+    src: url,
+    headers
+  };
+  if (!isMediaAuth(headers, mediaLayerHeaders)) return {
+    src: url,
+    headers
+  };
+  if (isManifestUrl(url)) return {
+    src: url,
+    headers
+  };
+  if (isLocalUrl(url)) return {
+    src: url,
+    headers
+  };
+  const doFetch = fetchImpl ?? globalThis.fetch;
+  if (typeof doFetch !== 'function') return {
+    src: url,
+    headers
+  };
+  try {
+    // HEAD walks the chain without tripping download counting, which keys off
+    // ranged GETs. Deadlined, because the load waits on it.
+    const response = await fetchWithDeadline(doFetch, url, headers, timeoutMs);
+    const src = response.url || url;
+
+    // The status belongs to the *last* hop, so it only speaks for the
+    // authenticating endpoint when there was no redirect. Once one has
+    // happened, hop one authenticated and handed us its target, and a refusal
+    // past that is routinely about the method rather than the credential:
+    // presigned S3 and GCS URLs sign it — SigV4's canonical request opens with
+    // HTTPMethod, GCS V4's with HTTP_VERB — so a URL signed for GET answers a
+    // HEAD with 403. Keep the signed URL, which is the whole point of the walk,
+    // and let a real error surface through the player.
+    if (!response.ok && src === url) return {
+      src: url,
+      headers
+    };
+    return {
+      src,
+      headers: leftTheOrigin(url, src) ? undefined : headers
+    };
+  } catch {
+    return {
+      src: url,
+      headers
+    };
+  }
+}
+//# sourceMappingURL=followMediaRedirect.js.map

package/lib/commonjs/web/http/followMediaRedirect.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isLocalUrl","url","test","MANIFEST_EXTENSIONS","Set","isManifestUrl","path","split","filename","slice","lastIndexOf","pieces","length","has","toLowerCase","PROBE_TIMEOUT_MS","timeoutSignal","ms","AbortSignal","undefined","timeout","AbortController","controller","setTimeout","abort","signal","fetchWithDeadline","doFetch","headers","timeoutMs","timer","Promise","race","method","redirect","_resolve","reject","Error","clearTimeout","isMediaAuth","mediaLayerHeaders","Object","keys","some","key","originOf","base","location","href","protocol","host","URL","leftTheOrigin","from","to","origin","followMediaRedirect","fetchImpl","src","globalThis","fetch","response","ok"],"sourceRoot":"../../../../src","sources":["web/http/followMediaRedirect.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/web/NativeAudioBrowser.js

@@ -6,6 +6,7 @@ import { classifyTrackNavigation } from './browser/classifyTrackNavigation';
 import { FavoriteManager } from './browser/FavoriteManager';
 import { NavigationErrorManager } from './browser/NavigationErrorManager';
 import { SearchManager } from './browser/SearchManager';
+import { followMediaRedirect } from './http/followMediaRedirect';
 import { HttpClient } from './http/HttpClient';
 import { RequestConfigBuilder } from './http/RequestConfigBuilder';
 import { NowPlayingManager } from './player/NowPlayingManager';
@@ -41,7 +42,6 @@ export class NativeAudioBrowser extends QueuePlayer {
   // Managers
 
   // Player state
-  currentLoadId = 0;
   progressTimer = new PlaybackTimer();
   intervalTimer = new PlaybackTimer();
   _online = typeof navigator !== 'undefined' ? navigator.onLine : true;
@@ -208,6 +208,13 @@ export class NativeAudioBrowser extends QueuePlayer {
       this.onPlaybackError({
         error: newState.error
       });
+    } else if (oldState.state === 'error') {
+      // Leaving the error state clears it, as it does natively. The getter
+      // already reads undefined — consumers subscribe to the event, so without
+      // this a stale error outlives the next successful load.
+      this.onPlaybackError({
+        error: undefined
+      });
     }
   }
   /**
@@ -452,68 +459,98 @@ export class NativeAudioBrowser extends QueuePlayer {
    * Supports the transform callback for URL manipulation.
    * Mirrors Android's MediaFactory.getMediaRequestConfig behavior.
    */
-  async resolveMediaUrl(src) {
+  async resolveMediaRequest(src, track) {
+    // The *resolved* request layer, not `configuration.request`: a
+    // resolver-only config would otherwise reach media with no baseUrl and no
+    // headers. Browse, search and browse artwork all read it this way too.
+    //
+    // Caught, because unlike those three this one cannot fail the load: a
+    // resolver hiccup — a token refresh timing out — would otherwise take down
+    // a track whose `src` is already absolute and public and needed no layer at
+    // all. Native degrades the same way, `getMediaRequestConfig` returning null
+    // and the original URL playing on.
+    let request;
+    try {
+      request = await this.browserManager.resolvedRequestConfig();
+    } catch (e) {
+      console.error('Failed to resolve the request layer for media', e);
+    }
     const {
-      request,
       media
     } = this.browserManager.configuration;
-    return RequestConfigBuilder.resolveMediaUrl(src, request, media);
+    return RequestConfigBuilder.resolveMediaRequest(src, request, media, track);
   }
 
   /**
-   * Reload from the queue's own entry, whose `src` is still unresolved —
-   * `current` holds the resolved track, and re-feeding it into `load()` would
-   * re-resolve the resolved URL (double-applying a `transform`) and replace
-   * the queue entry with it.
+   * The queue's own entry, so the queue stays the source of truth for what is
+   * playing. `current` preserves the track as queued — the resolved URL is
+   * passed to `load()` separately — so either is safe to re-feed.
    */
-  reloadCurrent() {
+  trackToReload() {
     const index = this.queue.currentIndex;
-    const sourceTrack = index !== undefined ? this.queue.getTrack(index) : undefined;
-    if (sourceTrack) {
-      this.load(sourceTrack);
-    } else {
-      super.reloadCurrent();
-    }
+    const queued = index !== undefined ? this.queue.getTrack(index) : undefined;
+    // The queue entry wins, so it stays the source of truth for what is
+    // playing; `current` is the fallback for a player loaded without one.
+    return queued ?? super.trackToReload();
   }
-  load(track, callback) {
-    const element = this.requireElement();
-
-    // Clear now playing override when track changes (matches Android's PlayerListener.onMediaItemTransition)
-    this.nowPlayingManager.clearNowPlayingOverride();
 
-    // Match Android: load() modifies the queue.
-    // If queue is empty, add the track. If queue has items, replace at currentIndex.
+  /**
+   * Makes `track` the queue's current entry, emitting the change.
+   *
+   * Matches Android, where `load()` modifies the queue: an empty queue takes
+   * the track as its only entry, a populated one has its current entry
+   * replaced.
+   */
+  syncQueueTo(track) {
     if (this.queue.length === 0) {
       this.queue.setTracks([track]);
       this.queue.currentIndex = 0;
       this.emitQueueChanged();
-    } else if (this.queue.currentIndex !== undefined && this.queue.getTrack(this.queue.currentIndex) !== track) {
+      return;
+    }
+    if (this.queue.currentIndex !== undefined && this.queue.getTrack(this.queue.currentIndex) !== track) {
       this.queue.replaceTrack(this.queue.currentIndex, track);
       this.emitQueueChanged();
     }
+  }
+
+  /**
+   * Everything native does in its media-item transition, all of it before any
+   * network work: announce the new track, publish its now-playing metadata,
+   * cut the outgoing one, and report `loading`.
+   *
+   * Android's `onMediaItemTransition` fires at `prepare()` and does exactly
+   * this, with its LOADING following from `onEvents`; resolution happens later
+   * still, inside `TransformingDataSource.open()`. Doing it here rather than
+   * after the URL resolves is what gives the resolution window a state, and
+   * keeps `activeTrack` ahead of `loading` — the order a consumer that reads
+   * `getActiveTrack()` on the loading edge depends on.
+   */
+  transitionTo(track) {
+    const element = this.requireElement();
     const lastTrack = this.current;
     const lastPosition = element.currentTime;
     const lastIndex = this.queue.lastIndex;
     const currentIndex = this.queue.currentIndex;
 
-    // Set loading flag early so seekTo() calls during async URL resolution
-    // are captured as pending seeks rather than silently dropped
-    this._loadInProgress = true;
-    this._pendingSeek = undefined;
+    // A re-prepare of the item already current is not a transition, and must
+    // not be announced as one: ExoPlayer's `prepare()` does not re-fire
+    // `onMediaItemTransition` for an unchanged media item, so a consumer that
+    // resets on a track change would have its UI wiped by every retry. The
+    // `lastTrack === track` payload was the tell.
+    const isTransition = this.current !== track;
 
-    // Resolve the media URL before loading (async but we don't await)
-    const loadId = ++this.currentLoadId;
-    const doLoad = async () => {
-      const resolvedTrack = track.src ? {
-        ...track,
-        src: await this.resolveMediaUrl(track.src)
-      } : track;
-
-      // A newer load() was called while resolving — discard this stale result
-      if (loadId !== this.currentLoadId) {
-        return;
-      }
-      super.load(resolvedTrack, loadedTrack => {
+    // `current` first, so `getActiveTrack()` already reads the new track inside
+    // a handler and so `getNowPlaying()` publishes the new track's metadata. It
+    // also stops `getActiveTrackIndex()` — which moved with the queue already,
+    // synchronously — from disagreeing with it for the length of the
+    // resolution.
+    this.current = track;
+
+    // Separately guarded: a throwing consumer handler must not skip the
+    // publish, and neither may fail the load.
+    if (isTransition) {
+      try {
         this.onPlaybackActiveTrackChanged({
           lastTrack,
           lastPosition,
@@ -521,24 +558,100 @@ export class NativeAudioBrowser extends QueuePlayer {
           index: currentIndex,
           track
         });
-
-        // Update now playing metadata
+      } catch (error) {
+        console.error('Failed to announce the active track change:', error);
+      }
+      try {
+        // Once, here: duration reaches the media session through
+        // `updateProgress()` on each tick, so only metadata needs publishing.
+        // Android publishes from the same transition handler that announces.
         const nowPlaying = this.getNowPlaying();
         if (nowPlaying) {
           this.publishNowPlaying(nowPlaying);
         }
+      } catch (error) {
+        console.error('Failed to publish now-playing metadata:', error);
+      }
+    }
+
+    // Stop the outgoing track now rather than when Shaka eventually gets a URL.
+    // Announcing the new track while the old one is still audible is worse than
+    // the silence, and native has no such window — prepare() cuts the old item
+    // at the moment it announces. This adds no teardown: `player.load()`
+    // already unloads first (shaka player.js:1757-1762). It only moves when.
+    // Verified in a real browser to emit no `pause`, so no state comes of it.
+    this.requirePlayer().unload().catch(error => console.error('Failed to unload the previous track:', error));
+
+    // Loading covers the resolution too. Shaka dispatches its own `loading`
+    // once `player.load()` is called — after resolution — and the state setter
+    // drops that as a no-op. The `buffering` that follows is Shaka's to report.
+    this.dispatch({
+      type: 'trackLoading'
+    });
+  }
+  load(track, callback) {
+    // Before the queue is touched, so a load before `setupPlayer()` throws
+    // rather than half-applying.
+    this.requireElement();
 
+    // Clear now playing override when track changes (matches Android's PlayerListener.onMediaItemTransition)
+    this.nowPlayingManager.clearNowPlayingOverride();
+    this.syncQueueTo(track);
+
+    // Begun here, at the call, so a newer load supersedes this one immediately
+    // rather than once its own URL has resolved. Both continuations below carry
+    // it, as does `super.load()`.
+    const attempt = this.beginLoadAttempt();
+
+    // Loading ends being stopped. `dispatch()` drops every event while
+    // `_isStopped`, to keep Shaka's teardown noise off the stopped state, so
+    // the `trackLoading` in `transitionTo` would be swallowed on the stop → play
+    // path and the resolution window would report nothing. `super.load()` clears
+    // this too, but only after the URL resolves.
+    this._isStopped = false;
+
+    // Set loading flag early so seekTo() calls during async URL resolution
+    // are captured as pending seeks rather than silently dropped
+    this._loadInProgress = true;
+    this._pendingSeek = undefined;
+    this.transitionTo(track);
+
+    // Resolve the media URL before loading (async but we don't await)
+    const doLoad = async () => {
+      const resolvedRequest = track.src ? await this.resolveMediaRequest(track.src, track) : undefined;
+      // Web-only, and forced: a progressive file plays via `mediaElement.src`,
+      // which cannot carry headers. Native sends them with the media request
+      // and follows the redirect inline, so it needs none of this.
+      const resolvedMedia = resolvedRequest ? await followMediaRedirect(resolvedRequest.path ?? track.src, resolvedRequest.headers, {
+        mediaLayerHeaders: resolvedRequest.mediaLayerHeaders
+      }) : undefined;
+
+      // Something took over while the URL was resolving — discard this result
+      if (!attempt.isCurrent) return;
+      super.load(track, loadedTrack => {
         // Call the provided callback if any
         if (callback) {
           callback(loadedTrack);
         }
+      }, {
+        headers: resolvedMedia?.headers,
+        src: resolvedMedia?.src,
+        attempt
       });
     };
 
     // Execute async load without blocking, with error handling
     doLoad().catch(error => {
-      // Only the active load may surface a resolution failure.
-      if (loadId !== this.currentLoadId) return;
+      // A backstop with no reachable trigger today, kept because an unhandled
+      // rejection would be worse than a dead branch. Every await inside
+      // `doLoad` catches internally; `shaka.Player.load` is `async`, so it
+      // rejects rather than throwing and its rejection is handled against the
+      // attempt inside `Player.load`; and `this.player` is only ever assigned,
+      // so `requirePlayer()` cannot start succeeding and then fail mid-load.
+      //
+      // No attempt check either, for the same reason it would be dead: nothing
+      // awaits between the guard above and `super.load()`, so the attempt
+      // cannot have changed. Add an await there and this needs the check back.
       this._loadInProgress = false;
       this._pendingSeek = undefined;
       console.error('Error loading track:', error);
@@ -701,10 +814,8 @@ export class NativeAudioBrowser extends QueuePlayer {
     this.clearSleepTimerIfFading();
   }
   stop() {
-    // Invalidate any in-flight load: its post-await continuation would call
-    // super.load(), whose first line re-arms the player (_isStopped = false)
-    // and revives the state out of Stopped.
-    this.currentLoadId++;
+    // `Player.stop()` cancels the load attempt, so an in-flight load's
+    // continuation cannot re-arm the player and revive it out of Stopped.
     super.stop();
     this.clearSleepTimerIfFading();
   }
@@ -730,11 +841,13 @@ export class NativeAudioBrowser extends QueuePlayer {
       this.sleepTimer.clear();
       this.pause();
       this.onSleepTimerChanged(null);
-      return;
+      // Nothing is loading, so the caller must still report the end — the
+      // element has stopped and its own `pause` is swallowed as end-of-track.
+      return false;
     }
 
     // Otherwise proceed with normal track end behavior
-    super.onTrackEnded();
+    return super.onTrackEnded();
   }
 
   // MARK: Queue management