react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.31

package/ios/Browser/PageResolver.swift

@@ -0,0 +1,227 @@
+import Foundation
+import NitroModules
+import os.log
+
+/// Turns a path into its page: matches the route, resolves its source (callback, config or
+/// static content), then normalizes and stamps the result (contextual paths, browse-time
+/// artwork). Also resolves the tabs and search routes.
+@MainActor
+final class PageResolver {
+  /// Internal path used for the default/root browse source
+  static let defaultRoutePath = "__default__"
+
+  /// Internal path used for navigation tabs
+  static let tabsRoutePath = "__tabs__"
+
+  /// Internal path used for search
+  static let searchRoutePath = "__search__"
+
+  let logger = Logger(subsystem: "com.audiobrowser", category: "PageResolver")
+  private let router = SimpleRouter()
+  private let requests: RequestPipeline
+
+  private var config: BrowserConfig {
+    requests.config
+  }
+
+  nonisolated init(requests: RequestPipeline) {
+    self.requests = requests
+  }
+
+  /// The page at `path`, uncached and without favorites hydrated.
+  func resolve(_ path: String) async throws -> ResolvedTrack {
+    // Match an explicit route (or the '*' default). With no match, fall back to
+    // the implicit default: fetch the path via the request + browse config.
+    let routeEntry = (config.routes).flatMap { findBestRouteMatch(path: path, routes: $0) }
+
+    let resolvedTrack: ResolvedTrack = if let (entry, routeMatch) = routeEntry {
+      try await resolveRouteEntry(entry, path: path, params: routeMatch.params)
+    } else {
+      // Implicit default — no route config, just request → browse → fetch path.
+      try await requests.fetchPage(
+        nil, path: path, params: ["path": path],
+      )
+    }
+
+    // Normalize to the canonical sectioned shape (children sugar → one
+    // untitled section — ADR 0010), then validate and transform. The output
+    // never carries `children`.
+    if let sections = resolvedTrack.normalizedSections {
+      // Dev diagnostic (ADR 0011) — before the blocks are folded, while each
+      // level is still attributable. Every page passes here whatever its
+      // source, and only on a cache miss. No-op outside debug builds.
+      InertStyleDiagnostic.warn(path: path, pageStyle: resolvedTrack.style, sections: sections)
+      let transformed = try await transformSections(
+        sections, parentPath: path, routeEntry: routeEntry?.0,
+      )
+      return resolvedTrack.copying(sections: transformed, children: .some(nil))
+    }
+
+    return resolvedTrack
+  }
+
+  /// The tabs: the `__tabs__` route's page, flattened. Nil when there is no such route.
+  func tabs() async throws -> [Track]? {
+    guard let tabsEntry = config.routes?.first(where: { $0.path == Self.tabsRoutePath }) else { return nil }
+    let resolved = try await resolveRouteEntry(tabsEntry, path: Self.tabsRoutePath, params: [:])
+    // Tabs are a flat list, not a page: a sectioned tabs source flattens.
+    return resolved.flattenedChildren ?? []
+  }
+
+  /// The `__search__` route's results for `params`, unhydrated.
+  func search(_ params: SearchParams) async throws -> [Track] {
+    guard let searchEntry = config.routes?.first(where: { $0.path == Self.searchRoutePath }) else {
+      throw BrowserError.contentNotFound(path: Self.searchRoutePath)
+    }
+    if let callback = searchEntry.searchCallback {
+      return try await callback(params).await().await()
+    }
+    if let searchConfig = searchEntry.searchConfig {
+      return try await requests.fetchSearch(searchConfig, params: params)
+    }
+    throw BrowserError.contentNotFound(path: Self.searchRoutePath)
+  }
+
+  /// The query params a structured search sends: `q` plus whichever filters are
+  /// set. Mirrors Android's `executeSearchApiRequest` and the web stub.
+  ///
+  /// Single source of truth for "what distinguishes one search from another" —
+  /// the request sends exactly this, and the cache keys on exactly this, so a
+  /// field added here can't be forgotten in one place and silently serve one
+  /// search's results for another.
+  static func searchQueryParams(_ params: SearchParams) -> [String: String] {
+    var query: [String: String] = ["q": params.query]
+    if let mode = params.mode { query["mode"] = mode.stringValue }
+    if params.reference == .my { query["reference"] = "my" }
+    if let genre = params.genre { query["genre"] = genre }
+    if let artist = params.artist { query["artist"] = artist }
+    if let album = params.album { query["album"] = album }
+    if let title = params.title { query["title"] = title }
+    if let playlist = params.playlist { query["playlist"] = playlist }
+    return query
+  }
+
+  // MARK: - Route Resolution
+
+  private func findBestRouteMatch(
+    path: String,
+    routes: [NativeRouteEntry],
+  ) -> (NativeRouteEntry, RouteMatch)? {
+    // Filter out special routes
+    let browseRoutes = routes.filter {
+      $0.path != Self.tabsRoutePath &&
+        $0.path != Self.searchRoutePath &&
+        $0.path != Self.defaultRoutePath
+    }
+
+    // Try to find a matching route
+    if let match = router.findBestMatch(path: path, routes: browseRoutes) {
+      return match
+    }
+
+    // Fall back to __default__ if present
+    if let defaultRoute = routes.first(where: { $0.path == Self.defaultRoutePath }) {
+      return (defaultRoute, RouteMatch(params: ["path": path]))
+    }
+
+    return nil
+  }
+
+  private func resolveRouteEntry(
+    _ entry: NativeRouteEntry,
+    path: String,
+    params: [String: String],
+  ) async throws -> ResolvedTrack {
+    // Priority: callback > config > static
+    if let callback = entry.browseCallback {
+      let callbackParam = BrowserSourceCallbackParam(path: path, routeParams: params)
+      // BrowserSourceCallback may return a BrowseResult synchronously or via a
+      // Promise. Nitro flattens (ResolvedTrack | BrowseError) | Promise<BrowseResult>
+      // into a 3-arm variant: sync track, sync error, or a Promise resolving to a
+      // BrowseResult (which is itself a ResolvedTrack | BrowseError variant).
+      switch try await callback(callbackParam).await() {
+      case let .first(resolvedTrack):
+        return resolvedTrack
+      case let .second(browseError):
+        throw BrowserError.callbackError(browseError.error)
+      case let .third(promise):
+        switch try await promise.await() {
+        case let .first(resolvedTrack):
+          return resolvedTrack
+        case let .second(browseError):
+          throw BrowserError.callbackError(browseError.error)
+        }
+      }
+    }
+
+    if let browseConfig = entry.browseConfig {
+      return try await requests.fetchPage(
+        browseConfig, path: path, params: params,
+      )
+    }
+
+    if let staticContent = entry.browseStatic {
+      return staticContent
+    }
+
+    throw BrowserError.contentNotFound(path: path)
+  }
+
+  // MARK: - Stamping
+
+  private func transformSections(
+    _ sections: [Section],
+    parentPath: String,
+    routeEntry: NativeRouteEntry?,
+  ) async throws -> [Section] {
+    // The contextual index is the flat page position — children concatenated
+    // in section order (ADR 0009/0010).
+    var flatIndex = 0
+    var pageTracks: [[Track]] = []
+    for section in sections {
+      var tracks: [Track] = []
+      for track in section.children {
+        let index = flatIndex
+        flatIndex += 1
+        if track.path == nil, track.src == nil {
+          throw BrowserError.invalidConfiguration(
+            "Track must have either 'path' or 'src' for stable identification: \(track.title)",
+          )
+        }
+        if track.src != nil, track.path == nil {
+          // src != nil guarantees a non-nil identity (id when non-blank, else src).
+          // The flat page position rides along as a duplicate-identity tie-breaker.
+          let contextualPath = BrowserPathHelper.build(
+            parentPath: parentPath, trackId: track.identity!, index: index,
+          )
+          tracks.append(track.copying(path: contextualPath))
+        } else {
+          tracks.append(track)
+        }
+      }
+      pageTracks.append(tracks)
+    }
+
+    // Every track's browse-time artwork (no size context) resolves at once.
+    let artworkConfig = routeEntry?.artwork ?? config.artwork
+    let artworkLoads = pageTracks.map { tracks in
+      tracks.map { track in
+        Task<ImageSource?, Never> { @MainActor in
+          await self.requests.resolveArtworkUrl(track: track, perRouteConfig: artworkConfig)
+        }
+      }
+    }
+
+    var transformed: [Section] = []
+    for sectionIndex in sections.indices {
+      var children: [Track] = []
+      for trackIndex in pageTracks[sectionIndex].indices {
+        let track = pageTracks[sectionIndex][trackIndex]
+        let artwork = await artworkLoads[sectionIndex][trackIndex].value
+        children.append(artwork.map { track.copying(artworkSource: $0) } ?? track)
+      }
+      transformed.append(sections[sectionIndex].copying(children: children))
+    }
+    return transformed
+  }
+}

package/ios/Browser/RequestLayer.swift

@@ -0,0 +1,90 @@
+import Foundation
+
+/// A request config's fields: the Nitro `RequestConfig` in the app, a plain struct in tests.
+protocol RequestFields {
+  associatedtype Method
+  var method: Method? { get }
+  var path: String? { get }
+  var baseUrl: String? { get }
+  var headers: [String: String]? { get }
+  var query: [String: String]? { get }
+  var body: String? { get }
+  var contentType: String? { get }
+  var userAgent: String? { get }
+
+  init(
+    method: Method?,
+    path: String?,
+    baseUrl: String?,
+    headers: [String: String]?,
+    query: [String: String]?,
+    body: String?,
+    contentType: String?,
+    userAgent: String?,
+  )
+}
+
+/// How Request-Config Layers compose, least specific first, each over the one before. The one
+/// implementation of these rules; Android and the web stub follow the same ones.
+enum RequestLayer {
+  /// `override` over `base`, field by field; headers and query merge by key.
+  static func merge<C: RequestFields>(_ base: C, _ override: C) -> C {
+    C(
+      method: override.method ?? base.method,
+      path: override.path ?? base.path,
+      baseUrl: override.baseUrl ?? base.baseUrl,
+      headers: mergeDicts(base.headers, override.headers),
+      query: mergeDicts(base.query, override.query),
+      body: override.body ?? base.body,
+      contentType: override.contentType ?? base.contentType,
+      userAgent: override.userAgent ?? base.userAgent,
+    )
+  }
+
+  /// A layer's static fields over `base`, keeping the base's path: only a transform may change
+  /// the path.
+  static func applyStatic<C: RequestFields>(_ layer: C, to base: C) -> C {
+    let merged = merge(base, layer)
+    return C(
+      method: merged.method, path: base.path, baseUrl: merged.baseUrl, headers: merged.headers,
+      query: merged.query, body: merged.body, contentType: merged.contentType, userAgent: merged.userAgent,
+    )
+  }
+
+  /// Applies one layer: its transforms, when it has any, win completely, each handed the result
+  /// of the one before; otherwise its static fields apply over `base`.
+  nonisolated(nonsending) static func apply<C: RequestFields>(
+    _ layer: C,
+    transforms: [nonisolated(nonsending)(C) async throws -> C],
+    to base: C,
+  ) async throws -> C {
+    guard !transforms.isEmpty else { return applyStatic(layer, to: base) }
+    var result = base
+    for transform in transforms {
+      result = try await transform(result)
+    }
+    return result
+  }
+
+  /// The configs a `resolve` (async) and `resolveSync` produced, the sync one winning; nil when
+  /// neither produced one.
+  static func mergeResolved<C: RequestFields>(async asyncResolved: C?, sync syncResolved: C?) -> C? {
+    guard let asyncResolved else { return syncResolved }
+    guard let syncResolved else { return asyncResolved }
+    return merge(asyncResolved, syncResolved)
+  }
+
+  /// The URL a config addresses: base URL, then path (or `defaultPath`), then query.
+  static func buildUrl(_ config: some RequestFields, defaultPath: String = "") -> String {
+    let url = BrowserPathHelper.buildUrl(baseUrl: config.baseUrl, path: config.path ?? defaultPath)
+    guard let query = config.query, !query.isEmpty else { return url }
+    return BrowserPathHelper.appendQuery(query, to: url)
+  }
+
+  /// `override`'s keys over `base`'s; nil only when both are nil.
+  static func mergeDicts(_ base: [String: String]?, _ override: [String: String]?) -> [String: String]? {
+    guard let base else { return override }
+    guard let override else { return base }
+    return base.merging(override) { _, new in new }
+  }
+}