react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.20

package/src/web/browser/sections.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest'
+import type { ResolvedTrack, Track } from '../../types'
+import { flattenSections, normalizePage, sectionContaining } from './sections'
+
+const track = (src: string): Track => ({ title: src, src })
+
+describe('normalizePage', () => {
+  it('wraps plain children into one untitled section', () => {
+    const page: ResolvedTrack = {
+      path: '/p',
+      title: 'P',
+      children: [track('a'), track('b')]
+    }
+    const normalized = normalizePage(page)
+    expect(normalized.sections).toEqual([
+      { children: [track('a'), track('b')] }
+    ])
+    expect(normalized.children).toBeUndefined()
+  })
+
+  it('prefers sections when present and strips children', () => {
+    const page: ResolvedTrack = {
+      path: '/p',
+      title: 'P',
+      sections: [{ title: 'S', children: [track('a')] }],
+      children: [track('zzz')]
+    }
+    const normalized = normalizePage(page)
+    expect(normalized.sections).toEqual([
+      { title: 'S', children: [track('a')] }
+    ])
+    expect(normalized.children).toBeUndefined()
+  })
+
+  it('leaves a childless page without sections', () => {
+    expect(normalizePage({ path: '/p', title: 'P' }).sections).toBeUndefined()
+  })
+})
+
+describe('flattenSections', () => {
+  it('concatenates children in section order', () => {
+    const flat = flattenSections([
+      { title: 'A', children: [track('a1'), track('a2')] },
+      { children: [track('b1')] }
+    ])
+    expect(flat.map((t) => t.src)).toEqual(['a1', 'a2', 'b1'])
+  })
+})
+
+describe('sectionContaining', () => {
+  const sections = [
+    { title: 'First', children: [track('dup'), track('x')] },
+    { title: 'Second', children: [track('y'), track('dup'), track('z')] }
+  ]
+
+  it('falls back to the first section containing the identity', () => {
+    const scoped = sectionContaining(sections, 'dup', undefined)
+    expect(scoped?.tracks.map((t) => t.src)).toEqual(['dup', 'x'])
+    expect(scoped?.tappedOffset).toBeUndefined()
+  })
+
+  it('pins the tapped section via the flat index', () => {
+    // Flat index 3 = second section, offset 1.
+    const scoped = sectionContaining(sections, 'dup', 3)
+    expect(scoped?.tracks.map((t) => t.src)).toEqual(['y', 'dup', 'z'])
+    expect(scoped?.tappedOffset).toBe(1)
+  })
+
+  it('ignores a stale index whose child no longer matches', () => {
+    const scoped = sectionContaining(sections, 'dup', 1)
+    expect(scoped?.tracks.map((t) => t.src)).toEqual(['dup', 'x'])
+    expect(scoped?.tappedOffset).toBeUndefined()
+  })
+
+  it('ignores an out-of-range index', () => {
+    const scoped = sectionContaining(sections, 'dup', 99)
+    expect(scoped?.tracks.map((t) => t.src)).toEqual(['dup', 'x'])
+  })
+
+  it('returns undefined for a vanished identity', () => {
+    expect(sectionContaining(sections, 'gone', 0)).toBeUndefined()
+  })
+
+  it('pins the exact copy of a within-section duplicate', () => {
+    const playlist = [
+      { children: [track('a'), track('b'), track('a'), track('c')] }
+    ]
+    const scoped = sectionContaining(playlist, 'a', 2)
+    expect(scoped?.tappedOffset).toBe(2)
+  })
+})

package/src/web/browser/sections.ts

@@ -0,0 +1,72 @@
+import type { ResolvedTrack, Section, Track } from '../../types'
+import { getTrackIdentity } from '../../utils/getTrackIdentity'
+
+/**
+ * Normalizes a resolved page to the canonical sectioned shape (ADR 0010):
+ * `sections` wins when present; plain `children` is authoring sugar for one
+ * untitled section. The output never carries `children` — there is exactly
+ * one structure downstream code hydrates, transforms, and scopes against.
+ */
+export function normalizePage(content: ResolvedTrack): ResolvedTrack {
+  const { children, sections, ...rest } = content
+  const normalized =
+    sections ?? (children !== undefined ? [{ children }] : undefined)
+  return { ...rest, sections: normalized }
+}
+
+/**
+ * The page's children concatenated in section order — the flattening that
+ * defines the contextual `__index` positions (ADR 0009/0010) and the flat
+ * views (tabs, search) of a sectioned page.
+ */
+export function flattenSections(sections: Section[] | undefined): Track[] {
+  return sections?.flatMap((section) => section.children) ?? []
+}
+
+/**
+ * The page's tracks as one flat list, normalizing first — the flat view
+ * (tabs, search) of a page in either authored shape. Mirrors the native
+ * `flattenedChildren` accessors.
+ */
+export function flattenedChildren(page: ResolvedTrack): Track[] {
+  return flattenSections(normalizePage(page).sections)
+}
+
+/**
+ * The section of the page containing the playable `trackId` (a track
+ * identity: id when non-blank, else src), or undefined when not found.
+ *
+ * `tappedIndex` — the flat page position stamped into the contextual URL —
+ * is a tie-breaker, never an identifier: when the child at that position
+ * still carries the tapped identity, it pins which section (and which copy,
+ * via `tappedOffset`) was tapped; when it doesn't (the list shifted),
+ * resolution falls back to the first section containing the identity. A
+ * stale index can therefore never select a different track — at worst a
+ * different copy of the same one.
+ */
+export function sectionContaining(
+  sections: Section[],
+  trackId: string,
+  tappedIndex: number | undefined
+): { tracks: Track[]; tappedOffset?: number } | undefined {
+  if (tappedIndex !== undefined && tappedIndex >= 0) {
+    let start = 0
+    for (const section of sections) {
+      const offset = tappedIndex - start
+      if (offset < section.children.length) {
+        const tapped = section.children[offset]
+        if (tapped && getTrackIdentity(tapped) === trackId) {
+          return { tracks: section.children, tappedOffset: offset }
+        }
+        break
+      }
+      start += section.children.length
+    }
+  }
+  for (const section of sections) {
+    if (section.children.some((track) => getTrackIdentity(track) === trackId)) {
+      return { tracks: section.children }
+    }
+  }
+  return undefined
+}

package/src/web/http/RequestConfigBuilder.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from 'vitest'
-import type { RequestConfig, TransformableRequestConfig } from '../../types'
+import type {
+  RequestConfig,
+  Track,
+  TransformableRequestConfig
+} from '../../types'
 import { RequestConfigBuilder } from './RequestConfigBuilder'
 
 /**
@@ -48,6 +52,29 @@ describe('RequestConfigBuilder.applyLayer — sync/async transform composition',
     expect(out.query).toEqual({ stage: 'sync' })
   })
 
+  it('falls back to the base when a transform throws', async () => {
+    const layer: TransformableRequestConfig = {
+      transform: async () => {
+        throw new Error('boom')
+      }
+    }
+    const out = await RequestConfigBuilder.applyLayer(base, layer)
+    expect(out).toEqual(base)
+  })
+
+  it('falls back to the base when the sync stage throws after the async one', async () => {
+    const layer: TransformableRequestConfig = {
+      transform: async (req) => ({ ...req, headers: { a: '1' } }),
+      transformSync: () => {
+        throw new Error('boom')
+      }
+    }
+    const out = await RequestConfigBuilder.applyLayer(base, layer)
+    // the layer's input, not the half-applied config — matches native's single
+    // catch around the pair
+    expect(out).toEqual(base)
+  })
+
   it('falls back to a static field merge when no transform is set', async () => {
     const layer: TransformableRequestConfig = {
       baseUrl: 'https://override.example.com'
@@ -57,3 +84,216 @@ describe('RequestConfigBuilder.applyLayer — sync/async transform composition',
     expect(out.path).toBe('/p')
   })
 })
+
+/**
+ * A media request needs more than its URL. The layers resolve headers (and a
+ * user agent) alongside it, and native applies them to the AVURLAsset /
+ * ExoPlayer DataSpec — so a resolver that returned only the URL left web unable
+ * to play media that authenticated fine on iOS and Android.
+ */
+describe('RequestConfigBuilder.resolveMediaRequest', () => {
+  const src = 'https://cdn.example.com/track.m3u8'
+
+  it('keeps the headers a media transform resolves', async () => {
+    const media = {
+      transform: async (req: RequestConfig) => ({
+        ...req,
+        headers: { ...req.headers, Authorization: 'Bearer token' }
+      })
+    }
+
+    const out = await RequestConfigBuilder.resolveMediaRequest(
+      src,
+      undefined,
+      media
+    )
+
+    expect(out.path).toBe(src)
+    expect(out.headers).toEqual({ Authorization: 'Bearer token' })
+  })
+
+  it('keeps the headers of a static media config', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(src, undefined, {
+      headers: { 'X-Api-Key': 'k' }
+    })
+
+    expect(out.headers).toEqual({ 'X-Api-Key': 'k' })
+  })
+
+  it('merges the shared request layer under the media layer', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(
+      src,
+      { headers: { 'User-Agent': 'shared', 'X-Shared': 'yes' } },
+      { headers: { 'User-Agent': 'media' } }
+    )
+
+    expect(out.headers).toEqual({
+      'User-Agent': 'media',
+      'X-Shared': 'yes'
+    })
+  })
+
+  it('folds baseUrl into the resolved path', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(
+      '/track.m3u8',
+      undefined,
+      { baseUrl: 'https://cdn.example.com' }
+    )
+
+    expect(out.path).toBe('https://cdn.example.com/track.m3u8')
+    expect(out.baseUrl).toBeUndefined()
+  })
+
+  it('carries the media config query onto the resolved url', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(src, undefined, {
+      query: { token: 'abc' }
+    })
+
+    expect(out.path).toBe(`${src}?token=abc`)
+    // cleared so the resolved url can't be rebuilt and double-append it
+    expect(out.query).toBeUndefined()
+  })
+
+  it('appends query to a url that already has one', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(
+      'https://cdn.example.com/track.m3u8?v=2',
+      undefined,
+      { query: { token: 'abc' } }
+    )
+
+    expect(out.path).toBe('https://cdn.example.com/track.m3u8?v=2&token=abc')
+  })
+
+  it('falls back to the original src when a transform throws', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(src, undefined, {
+      transform: async () => {
+        throw new Error('boom')
+      }
+    })
+
+    expect(out.path).toBe(src)
+    expect(out.headers).toBeUndefined()
+  })
+
+  it('keeps the shared layer when the media transform throws', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(
+      '/track.mp3',
+      {
+        baseUrl: 'https://api.example.com',
+        headers: { Authorization: 'Bearer token' }
+      },
+      {
+        transform: async () => {
+          throw new Error('boom')
+        }
+      }
+    )
+
+    // the media layer is skipped, the ladder under it stands — dropping it too
+    // would play a relative url with no credential
+    expect(out.path).toBe('https://api.example.com/track.mp3')
+    expect(out.headers).toEqual({ Authorization: 'Bearer token' })
+  })
+})
+
+/**
+ * `media.resolve(track)` is the final, most-specific layer — the shape native
+ * runs (Android `applyMediaResolve`, iOS `applyMediaResolveLayer`) and the one
+ * the public docs promise. Web ignored it entirely until these landed, so a
+ * config minting per-track signed URLs played on both native platforms and
+ * silently played the unsigned src on web.
+ */
+describe('RequestConfigBuilder.resolveMediaRequest — media.resolve', () => {
+  const src = '/track.mp3'
+  const track: Track = { id: '7', title: 'Track 7', src }
+
+  it('lets the resolver replace the url', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(
+      src,
+      undefined,
+      { resolve: async (t) => ({ path: `/signed/${t.id}.mp3` }) },
+      track
+    )
+
+    expect(out.path).toBe('/signed/7.mp3')
+  })
+
+  it('runs after the media transform, and wins over it', async () => {
+    const order: string[] = []
+    const out = await RequestConfigBuilder.resolveMediaRequest(
+      src,
+      undefined,
+      {
+        transform: async (req) => {
+          order.push('transform')
+          return { ...req, path: '/unsigned.mp3', headers: { A: 'transform' } }
+        },
+        resolve: async () => {
+          order.push('resolve')
+          return { path: '/signed.mp3', headers: { A: 'resolve' } }
+        }
+      },
+      track
+    )
+
+    expect(order).toEqual(['transform', 'resolve'])
+    expect(out.path).toBe('/signed.mp3')
+    expect(out.headers).toEqual({ A: 'resolve' })
+  })
+
+  it('merges resolveSync over resolve, and both over the layers', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(
+      src,
+      { headers: { 'X-Shared': 'yes' } },
+      {
+        headers: { 'X-Media': 'yes' },
+        resolve: async () => ({ headers: { Authorization: 'async' } }),
+        resolveSync: () => ({ headers: { Authorization: 'sync' } })
+      },
+      track
+    )
+
+    expect(out.headers).toEqual({
+      'X-Shared': 'yes',
+      'X-Media': 'yes',
+      'Authorization': 'sync'
+    })
+  })
+
+  it('reports the resolver contribution as a media-layer header', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(
+      src,
+      { headers: { 'X-Client-Version': '1.2.3' } },
+      { resolve: async () => ({ headers: { 'X-Api-Key': 'k' } }) },
+      track
+    )
+
+    // per-track and media-specific, so the web redirect probe should run
+    expect(out.mediaLayerHeaders).toBe(true)
+  })
+
+  it('keeps the layers when the resolver throws', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(
+      src,
+      { baseUrl: 'https://api.example.com', headers: { 'X-Shared': 'yes' } },
+      {
+        resolve: async () => {
+          throw new Error('boom')
+        }
+      },
+      track
+    )
+
+    // native loses the per-track shaping, not the layers under it
+    expect(out.path).toBe('https://api.example.com/track.mp3')
+    expect(out.headers).toEqual({ 'X-Shared': 'yes' })
+  })
+
+  it('skips the resolver when there is no track', async () => {
+    const out = await RequestConfigBuilder.resolveMediaRequest(src, undefined, {
+      resolve: async () => ({ path: '/signed.mp3' })
+    })
+
+    expect(out.path).toBe(src)
+  })
+})

package/src/web/http/RequestConfigBuilder.ts

@@ -56,6 +56,29 @@ function applyImageQueryParams(
   return { ...config, query }
 }
 
+/** Whether `after` carries a header `before` had not already set identically. */
+function addsHeaders(
+  before: Record<string, string> | undefined,
+  after: Record<string, string> | undefined
+): boolean {
+  if (!after) return false
+  return Object.entries(after).some(([key, value]) => before?.[key] !== value)
+}
+
+export interface ResolvedMediaRequest extends RequestConfig {
+  /**
+   * Whether the `media` layer set a header the shared `request` layer had not
+   * already set identically. A media-specific header is the signal that media
+   * is separately authenticated, which is what the web redirect probe gates
+   * on.
+   *
+   * By value, not by declaration: a media layer re-declaring a shared header
+   * with the same value reads as no contribution, which is what keeps an
+   * identity transform from tripping the probe.
+   */
+  mediaLayerHeaders: boolean
+}
+
 /**
  * Builds and merges request configurations.
  * Mirrors Android's RequestConfigBuilder.kt
@@ -98,7 +121,9 @@ export const RequestConfigBuilder = {
    * A layer with a transform wins completely — it receives the base (plus route
    * params) and its result replaces the base; the layer's own static fields are
    * ignored. A layer without a transform merges its static fields over the base.
-   * `path` is carried from the base — only a transform may change it.
+   * `path` is carried from the base — only a transform may change it. A
+   * throwing transform falls back to the base, so the layer is skipped and the
+   * ladder continues.
    *
    * Mirrors native's BrowserManager.applyLayer so web resolves the shared
    * `request` → `<kind>` → route chain identically across platforms.
@@ -113,10 +138,24 @@ export const RequestConfigBuilder = {
     // its result replaces it. When both are set they run as a pipeline — async
     // first, then sync (mirrors native applyLayer).
     if (layer.transform || layer.transformSync) {
-      let cfg = base
-      if (layer.transform) cfg = await layer.transform(cfg, params)
-      if (layer.transformSync) cfg = layer.transformSync(cfg, params)
-      return cfg
+      try {
+        let cfg = base
+        if (layer.transform) cfg = await layer.transform(cfg, params)
+        if (layer.transformSync) cfg = layer.transformSync(cfg, params)
+        return cfg
+      } catch (e) {
+        // A throwing transform costs its own layer, not the ladder: the layers
+        // under it stand, so a relative path still gets the shared `baseUrl`
+        // and a media request keeps the shared credential. One catch around
+        // the pair, as native has it, so a sync stage that throws after a
+        // successful async one also falls back to the layer's input rather
+        // than to a half-applied config.
+        console.error(
+          'Failed to apply transform function, using base config',
+          e
+        )
+        return base
+      }
     }
     return {
       method: layer.method ?? base.method,
@@ -171,38 +210,115 @@ export const RequestConfigBuilder = {
   },
 
   /**
-   * Resolves a media URL using the media configuration.
-   * Creates a RequestConfig with the track's src as the path, then builds the URL.
-   * Supports the transform callback for URL manipulation.
+   * Resolves a media request from the layered configuration, returning the
+   * whole request rather than just its URL.
+   *
+   * The layers resolve headers (and a user agent) alongside the URL, and the
+   * media request needs all of them: native applies them to the AVURLAsset /
+   * ExoPlayer DataSpec, so web has to apply them to Shaka's requests or the
+   * same configuration authenticates on iOS and Android but 401s here.
    *
-   * The shared `request` layer is applied first (its transform runs for media
-   * too, per the documented contract — e.g. a dynamic baseUrl), then the media
-   * transform / static fields on top. Mirrors native's resolveMediaUrl,
-   * including its best-effort behaviour: if a transform throws, fall back to the
-   * original `src` rather than failing the load.
+   * The resolved URL is returned in `path`, with `baseUrl` already folded into
+   * it. Best-effort throughout, but at two levels: a throwing transform or
+   * resolver costs only its own layer (see {@link applyLayer}), and the catch
+   * here is the backstop for anything left — a malformed `baseUrl` reaching
+   * `buildUrl`, say — which falls back to the bare `src`.
+   *
+   * The chain is `request` → `media` → `media.resolve(track)`, matching
+   * native's. See {@link applyMediaResolve} for why the per-track resolver goes
+   * last.
    *
    * @param src The track's src value (may be relative or absolute)
    * @param requestConfig The shared request configuration (applied first)
    * @param mediaConfig The media request configuration
-   * @returns The resolved absolute URL
+   * @param track The track being loaded, for `media.resolve`; without it the
+   *   per-track layer is skipped and the static layers stand
+   * @returns The resolved request, its URL in `path`
    */
-  async resolveMediaUrl(
+  async resolveMediaRequest(
     src: string,
     requestConfig: TransformableRequestConfig | undefined,
-    mediaConfig: MediaRequestConfig | undefined
-  ): Promise<string> {
+    mediaConfig: MediaRequestConfig | undefined,
+    track?: Track
+  ): Promise<ResolvedMediaRequest> {
     try {
-      const config = await this.applyLayers({ path: src }, [
-        requestConfig,
-        mediaConfig
-      ])
-      return BrowserPathHelper.buildUrl(config.baseUrl, config.path ?? src)
+      // The layers are applied one at a time rather than through `applyLayers`
+      // so the media layer's own header contribution stays visible; each
+      // transform still runs exactly once.
+      const shared = await this.applyLayer({ path: src }, requestConfig)
+      const layered = await this.applyLayer(shared, mediaConfig)
+      const config = await this.applyMediaResolve(layered, mediaConfig, track)
+      // buildUrl folds in baseUrl *and* appends `query`; both are cleared on
+      // the way out so the resolved url can't be rebuilt and double-applied.
+      return {
+        ...config,
+        baseUrl: undefined,
+        query: undefined,
+        path: this.buildUrl({ ...config, path: config.path ?? src }),
+        mediaLayerHeaders: addsHeaders(shared.headers, config.headers)
+      }
     } catch (e) {
       console.error('Failed to resolve media URL, using original src', e)
-      return BrowserPathHelper.buildUrl(undefined, src)
+      return {
+        path: BrowserPathHelper.buildUrl(undefined, src),
+        mediaLayerHeaders: false
+      }
     }
   },
 
+  /**
+   * Applies `media.resolve(track)` / `media.resolveSync(track)` as the final,
+   * most-specific layer over an already request+media-layered config. A no-op
+   * without a track or a resolver, so the layers stand on their own.
+   *
+   * Last, not first: native runs the media layer's transform and then lets the
+   * per-track resolver win over the result (Android `applyMediaResolve`, iOS
+   * `applyMediaResolveLayer`), so a resolver minting a signed URL is not
+   * overwritten by the static layer that shaped the unsigned one. Override-wins
+   * on every field, `path` included — replacing the URL outright is the point.
+   *
+   * A throwing resolver falls back to the layered config, as native does: the
+   * per-track shaping is lost, the layers under it are not.
+   */
+  async applyMediaResolve(
+    layered: RequestConfig,
+    mediaConfig: MediaRequestConfig | undefined,
+    track: Track | undefined
+  ): Promise<RequestConfig> {
+    if (!track || !mediaConfig) return layered
+    if (!mediaConfig.resolve && !mediaConfig.resolveSync) return layered
+
+    try {
+      const resolved = await this.composeResolved(mediaConfig, track)
+      return resolved ? this.mergeConfig(layered, resolved) : layered
+    } catch (e) {
+      console.error('Failed to apply media.resolve, using layered config', e)
+      return layered
+    }
+  },
+
+  /**
+   * Runs a config's per-track resolvers and composes their output: async
+   * `resolve` first, then `resolveSync` merged over it, sync winning.
+   * `undefined` when neither is set or neither produced a config.
+   *
+   * Media and artwork share the pairing, so it lives here rather than in both
+   * — the same reason native has `composeResolved`. Errors are the callers' to
+   * handle: the two paths differ on what a throwing resolver costs.
+   */
+  async composeResolved(
+    config: Pick<MediaRequestConfig, 'resolve' | 'resolveSync'>,
+    track: Track
+  ): Promise<RequestConfig | undefined> {
+    let resolved: RequestConfig | undefined
+    if (config.resolve) resolved = await config.resolve(track)
+    if (config.resolveSync) {
+      const sync = config.resolveSync(track)
+      resolved = resolved ? this.mergeConfig(resolved, sync) : sync
+    }
+    return resolved
+  },
+
   /**
    * Resolves an artwork URL and creates an ImageSource.
    * Matches Android's artwork URL transformation behavior.
@@ -297,16 +413,7 @@ export const RequestConfigBuilder = {
 
       // Step 1: Per-track resolution — async `resolve` first, then `resolveSync`
       // merged over it (mirrors native).
-      let resolvedConfig: RequestConfig | undefined
-      if (artworkConfig.resolve) {
-        resolvedConfig = await artworkConfig.resolve(track)
-      }
-      if (artworkConfig.resolveSync) {
-        const r = artworkConfig.resolveSync(track)
-        resolvedConfig = resolvedConfig
-          ? this.mergeConfig(resolvedConfig, r)
-          : r
-      }
+      const resolvedConfig = await this.composeResolved(artworkConfig, track)
       // If a resolver ran but produced nothing and there's no artwork URL, no artwork
       if (
         (artworkConfig.resolve || artworkConfig.resolveSync) &&