@ciphore/radiocli 0.2.3 → 0.2.5

package/dist/providers/radio-browser.js

@@ -1,7 +1,12 @@
+import { resolveSrv } from 'node:dns/promises';
+import { randomUUID } from 'node:crypto';
+import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
 import { z } from 'zod';
 import { ProviderCache } from './cache.js';
+import { abortable, DiscoverySessions } from './discovery-session.js';
 import { userAgent } from '../version.js';
 import { safeExternalHttpUrl, safeMediaTarget, sanitizeTerminalText } from '../safety.js';
+import { allowsDirectDnsFallback, fetchHttpsWithSystemResolver, networkPolicy, withExternalResponse } from '../platform/network.js';
 const stationSchema = z.object({
     stationuuid: z.string(),
     name: z.string().default('Untitled station'),
@@ -46,13 +51,19 @@ const locationSchema = z
 })
     .passthrough();
 const geoAtlasLimit = 100_000;
+const geoAtlasMaxBytes = 32 * 1024 * 1024;
 const geoAtlasMaxAgeMs = 6 * 60 * 60 * 1000;
-// The atlas is much larger than ordinary directory responses. A single shared
-// 20-second deadline used to give each of four mirrors roughly five seconds to
-// connect, download, and parse up to 100k rows. Use a size-aware per-attempt
-// budget while retaining an overall bound and stale-cache fallback.
+// The atlas is much larger than ordinary directory responses. Give each live,
+// discovered server enough time to connect, download, and parse up to 100k rows
+// while retaining an overall bound and stale-cache fallback.
 const geoAtlasAttemptTimeoutMs = 30_000;
 const geoAtlasTotalTimeoutMs = 75_000;
+const mirrorDiscoveryTimeoutMs = 750;
+const radioBrowserService = '_api._tcp.radio-browser.info';
+const radioBrowserApiSuffix = '.api.radio-browser.info';
+const nameResolutionErrorCodes = new Set(['EAI_AGAIN', 'ENOTFOUND', 'ESERVFAIL', 'ETIMEOUT', 'EREFUSED']);
+const maxDiscoveryRoundsPerPage = 4;
+const defaultRuntime = {};
 class ProviderUnavailableError extends Error {
     constructor(message, cause) {
         super(message, cause ? { cause } : undefined);
@@ -64,15 +75,23 @@ export function isProviderUnavailableError(error) {
 }
 export class RadioBrowserProvider {
     cache;
+    runtime;
     id = 'radio-browser';
     label = 'Radio Browser';
     baseUrls;
+    discoverMirrors;
     activeBaseUrl;
-    geoAtlasPromise = null;
+    geoAtlas = null;
+    geoAtlasLoad = null;
     geoAtlasLoadedAt = 0;
-    constructor(baseUrls = defaultRadioBrowserMirrors(), cache = new ProviderCache()) {
+    mirrorDiscoveryPromise = null;
+    discovery = new DiscoverySessions(state => state.bytes + state.seen.size * 128 + 1024);
+    pendingRequests = new Map();
+    constructor(baseUrls = undefined, cache = new ProviderCache(), runtime = defaultRuntime) {
         this.cache = cache;
-        this.baseUrls = baseUrls.map(url => url.replace(/\/$/, ''));
+        this.runtime = runtime;
+        this.discoverMirrors = baseUrls === undefined;
+        this.baseUrls = (baseUrls ?? defaultRadioBrowserMirrors()).map(url => url.replace(/\/$/, ''));
         this.activeBaseUrl = this.baseUrls[0] ?? 'https://all.api.radio-browser.info';
     }
     async health() {
@@ -95,16 +114,16 @@ export class RadioBrowserProvider {
             .sort((a, b) => b.stationCount - a.stationCount || a.name.localeCompare(b.name))
             .slice(0, limit);
     }
-    async popular(limit = 80) {
+    async popular(limit = 80, options = {}) {
         const rows = await this.request('/json/stations/search', {
             hidebroken: 'true',
             limit: String(limit),
             order: 'clickcount',
             reverse: 'true'
-        }, { maxAgeMs: 15 * 60 * 1000 });
+        }, { maxAgeMs: 15 * 60 * 1000, signal: options.signal });
         return this.normalizeStations(rows);
     }
-    async byCountry(countryCode, limit = 100, offset = 0) {
+    async byCountry(countryCode, limit = 100, offset = 0, options = {}) {
         const rows = await this.request('/json/stations/search', {
             countrycode: countryCode.toUpperCase(),
             hidebroken: 'true',
@@ -112,17 +131,115 @@ export class RadioBrowserProvider {
             offset: String(Math.max(0, offset)),
             order: 'clickcount',
             reverse: 'true'
-        }, { maxAgeMs: 30 * 60 * 1000 });
+        }, { maxAgeMs: 30 * 60 * 1000, signal: options.signal });
         return this.normalizeStations(rows);
     }
+    byCountryPage(countryCode, options = {}) {
+        const limit = pageLimit(options.limit, 100);
+        const country = countryCode.trim().toUpperCase();
+        return this.discovery.page(JSON.stringify(['country', country, limit]), options.cursor, () => ({
+            query: country, tokens: [], filters: {}, sources: [discoverySource('country', { countrycode: country })],
+            buffer: [], seen: new Set(), initialized: true, country: true, bytes: 0
+        }), state => this.discoveryPage(state, limit, options.signal), options.signal);
+    }
+    searchPage(query, options = {}) {
+        const trimmed = query.trim();
+        const limit = pageLimit(options.limit, trimmed ? 60 : 80);
+        const filters = searchFilters(options);
+        return this.discovery.page(JSON.stringify(['search', trimmed, filters, limit]), options.cursor, () => ({
+            query: trimmed, tokens: trimmed.split(/\s+/).filter(token => token.length > 2).slice(0, 4), filters,
+            sources: trimmed ? [discoverySource('name', { name: trimmed }), discoverySource('tag', { tag: trimmed })] : [discoverySource('popular', {})],
+            buffer: [], seen: new Set(), initialized: !trimmed, country: false, bytes: 0
+        }), state => this.discoveryPage(state, limit, options.signal), options.signal);
+    }
+    async discoveryPage(state, limit, signal) {
+        signal?.throwIfAborted();
+        let successfulRequests = 0;
+        let requestError;
+        const load = async (sources) => {
+            const results = await Promise.allSettled(sources.map(source => this.request('/json/stations/search', {
+                hidebroken: 'true', limit: String(limit), offset: String(source.consumed), order: 'clickcount', reverse: 'true',
+                ...searchFilterParams(state.filters), ...source.params
+            }, { maxAgeMs: state.country ? 30 * 60 * 1000 : 10 * 60 * 1000, signal })));
+            signal?.throwIfAborted();
+            let rawCount = 0;
+            for (const [index, result] of results.entries()) {
+                const source = sources[index];
+                if (result.status === 'rejected' || !Array.isArray(result.value)) {
+                    requestError = result.status === 'rejected' ? result.reason : new Error('Radio Browser returned an invalid station list.');
+                    source.status = 'unavailable';
+                    source.message = requestError instanceof Error ? requestError.message : String(requestError);
+                    continue;
+                }
+                successfulRequests += 1;
+                const rows = result.value;
+                source.status = 'available';
+                source.message = undefined;
+                source.consumed += rows.length;
+                source.exhausted = rows.length < limit;
+                rawCount += rows.length;
+                for (const station of this.normalizeStations(rows)) {
+                    const key = `${station.provider}:${station.id}`;
+                    if (state.seen.has(key))
+                        continue;
+                    state.seen.add(key);
+                    state.bytes += key.length * 2;
+                    if (filterStations([station], state.filters).length === 0)
+                        continue;
+                    state.buffer.push(station);
+                    state.bytes += JSON.stringify(station).length * 2;
+                }
+            }
+            return rawCount;
+        };
+        for (let round = 0; state.buffer.length < limit && round < maxDiscoveryRoundsPerPage; round += 1) {
+            const pending = state.sources.filter(source => !source.exhausted);
+            if (!pending.length)
+                break;
+            let rawCount = await load(pending);
+            if (!state.initialized) {
+                // Preserve the first-page broadening policy and relevance score. Each
+                // activated source subsequently keeps its own raw offset.
+                if (rawCount < Math.min(12, limit)) {
+                    const secondary = [discoverySource('country', { country: state.query }), discoverySource('language', { language: state.query })];
+                    state.sources.push(...secondary);
+                    rawCount += await load(secondary);
+                }
+                if (rawCount === 0 && state.tokens.length > 1) {
+                    const tokenSources = state.tokens.slice(0, 3).flatMap((token, index) => [
+                        discoverySource(`token-${index}-name`, { name: token }), discoverySource(`token-${index}-tag`, { tag: token })
+                    ]);
+                    state.sources.push(...tokenSources);
+                    await load(tokenSources);
+                }
+                state.initialized = true;
+            }
+            if (!state.country)
+                state.buffer.sort((left, right) => scoreStation(right, state.query, state.tokens) - scoreStation(left, state.query, state.tokens));
+            // Failures remain retryable on the next cursor; do not spend four full
+            // network deadlines retrying an unavailable source in a single call.
+            if (state.sources.some(source => source.status === 'unavailable'))
+                break;
+        }
+        if (!state.buffer.length && !successfulRequests && requestError)
+            throw requestError;
+        const items = state.buffer.splice(0, limit);
+        state.bytes -= items.reduce((sum, station) => sum + JSON.stringify(station).length * 2, 0);
+        return {
+            items,
+            exhausted: state.buffer.length === 0 && state.sources.every(source => source.exhausted),
+            sources: state.sources.map(({ params: _params, ...source }) => source)
+        };
+    }
     async byId(id) {
         const rows = await this.request(`/json/stations/byuuid/${encodeURIComponent(id)}`, {}, { maxAgeMs: 10 * 60 * 1000 });
         return this.normalizeStations(rows)[0] ?? null;
     }
     async search(query, options = {}) {
+        options.signal?.throwIfAborted();
         const trimmed = query.trim();
         if (!trimmed) {
-            return this.popular(options.limit ?? 80);
+            return this.popular(options.limit ?? 80, { signal: options.signal });
         }
         const limit = options.limit ?? 60;
         const offset = Math.max(0, options.offset ?? 0);
@@ -136,28 +253,32 @@ export class RadioBrowserProvider {
             reverse: 'true',
             ...(options.codec ? { codec: options.codec } : {}),
             ...(options.language ? { language: options.language } : {}),
-            ...(options.countryCode ? { countrycode: options.countryCode.toUpperCase() } : {})
+            ...(options.countryCode ? { countrycode: options.countryCode.toUpperCase() } : {}),
+            ...(options.minBitrate ? { bitrateMin: String(options.minBitrate) } : {})
         };
         const primary = await Promise.allSettled([
-            this.request('/json/stations/search', { ...baseParams, name: trimmed }, { maxAgeMs: 10 * 60 * 1000 }),
-            this.request('/json/stations/search', { ...baseParams, tag: trimmed }, { maxAgeMs: 10 * 60 * 1000 })
+            this.request('/json/stations/search', { ...baseParams, name: trimmed }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal }),
+            this.request('/json/stations/search', { ...baseParams, tag: trimmed }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal })
         ]);
+        options.signal?.throwIfAborted();
         let attempts = [...primary];
         let rows = fulfilledRows(primary);
         if (rows.length < Math.min(12, limit + offset)) {
             const secondary = await Promise.allSettled([
-                this.request('/json/stations/search', { ...baseParams, country: trimmed }, { maxAgeMs: 10 * 60 * 1000 }),
-                this.request('/json/stations/search', { ...baseParams, language: trimmed }, { maxAgeMs: 10 * 60 * 1000 })
+                this.request('/json/stations/search', { ...baseParams, country: trimmed }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal }),
+                this.request('/json/stations/search', { ...baseParams, language: trimmed }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal })
             ]);
+            options.signal?.throwIfAborted();
             attempts = [...attempts, ...secondary];
             rows.push(...fulfilledRows(secondary));
         }
         const tokens = trimmed.split(/\s+/).filter(token => token.length > 2).slice(0, 4);
         if (rows.length === 0 && tokens.length > 1) {
             const tokenResults = await Promise.allSettled(tokens.slice(0, 3).flatMap(token => [
-                this.request('/json/stations/search', { ...baseParams, name: token, limit: '25' }, { maxAgeMs: 10 * 60 * 1000 }),
-                this.request('/json/stations/search', { ...baseParams, tag: token, limit: '25' }, { maxAgeMs: 10 * 60 * 1000 })
+                this.request('/json/stations/search', { ...baseParams, name: token, limit: '25' }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal }),
+                this.request('/json/stations/search', { ...baseParams, tag: token, limit: '25' }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal })
             ]));
+            options.signal?.throwIfAborted();
             attempts.push(...tokenResults);
             rows = fulfilledRows(tokenResults);
         }
@@ -170,11 +291,13 @@ export class RadioBrowserProvider {
             .sort((a, b) => scoreStation(b, trimmed, tokens) - scoreStation(a, trimmed, tokens))
             .slice(offset, offset + limit);
     }
-    async nearby(location, limit = 80) {
-        const stations = await this.geotaggedAtlas();
-        return nearestStations(stations, location, limit);
+    async nearby(location, limit = 80, options = {}) {
+        options.signal?.throwIfAborted();
+        const stations = await this.geotaggedAtlas(options.signal);
+        return nearestStations(stations, location, limit, options.signal);
     }
-    async resolve(station) {
+    async resolve(station, options = {}) {
+        options.signal?.throwIfAborted();
         if (station.provider !== this.id) {
             const streamUrl = station.streamUrl ? safeMediaTarget(station.streamUrl) : null;
             if (!streamUrl) {
@@ -185,13 +308,14 @@ export class RadioBrowserProvider {
         try {
             // Click URLs can rotate and the endpoint records directory engagement, so
             // do not reuse a day-old resolution from the general provider cache.
-            const result = clickResolveSchema.parse(await this.request(`/json/url/${encodeURIComponent(station.id)}`, {}, { timeoutMs: 6000 }));
+            const result = clickResolveSchema.parse(await this.request(`/json/url/${encodeURIComponent(station.id)}`, {}, { timeoutMs: 6000, signal: options.signal }));
             const resolvedUrl = result.url ? safeMediaTarget(result.url) : null;
             if (result.ok && resolvedUrl) {
                 return { url: resolvedUrl, name: sanitizeTerminalText(result.name) ?? station.name };
             }
         }
         catch {
+            options.signal?.throwIfAborted();
             // A directory outage should not discard a validated URL already supplied
             // with the station row.
         }
@@ -216,37 +340,33 @@ export class RadioBrowserProvider {
             return false;
         }
     }
-    async detectLocation() {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 5000);
+    async detectLocation(options = {}) {
+        options.signal?.throwIfAborted();
         try {
-            const response = await fetch('https://ipapi.co/json/', {
-                signal: controller.signal,
-                headers: { 'User-Agent': userAgent() }
+            return await withExternalResponse('https://ipapi.co/json/', {
+                timeoutMs: 5000,
+                init: { headers: { 'User-Agent': userAgent() }, signal: options.signal }
+            }, async (response) => {
+                if (!response.ok)
+                    return null;
+                const parsed = locationSchema.parse(await response.json());
+                if (typeof parsed.latitude !== 'number' || typeof parsed.longitude !== 'number')
+                    return null;
+                return {
+                    city: parsed.city,
+                    region: parsed.region,
+                    country: parsed.country_name,
+                    countryCode: parsed.country_code,
+                    latitude: parsed.latitude,
+                    longitude: parsed.longitude,
+                    source: 'ipapi.co'
+                };
             });
-            if (!response.ok) {
-                return null;
-            }
-            const parsed = locationSchema.parse(await response.json());
-            if (typeof parsed.latitude !== 'number' || typeof parsed.longitude !== 'number') {
-                return null;
-            }
-            return {
-                city: parsed.city,
-                region: parsed.region,
-                country: parsed.country_name,
-                countryCode: parsed.country_code,
-                latitude: parsed.latitude,
-                longitude: parsed.longitude,
-                source: 'ipapi.co'
-            };
         }
         catch {
+            options.signal?.throwIfAborted();
             return null;
         }
-        finally {
-            clearTimeout(timeout);
-        }
     }
     normalizeStations(rows) {
         return rows
@@ -277,22 +397,43 @@ export class RadioBrowserProvider {
             lastCheckedOk: row.lastcheckok === 1 || row.lastcheckok === true
         }));
     }
-    async geotaggedAtlas() {
+    async geotaggedAtlas(signal) {
+        signal?.throwIfAborted();
         const atlasExpired = this.geoAtlasLoadedAt > 0 && Date.now() - this.geoAtlasLoadedAt > geoAtlasMaxAgeMs;
-        if (!this.geoAtlasPromise || atlasExpired) {
-            this.geoAtlasPromise = this.loadGeotaggedAtlas()
-                .then(stations => {
+        if (this.geoAtlas && !atlasExpired)
+            return this.geoAtlas;
+        let load = this.geoAtlasLoad;
+        if (!load) {
+            const controller = new AbortController();
+            load = { controller, subscribers: 0, settled: false, promise: Promise.resolve([]) };
+            const created = load;
+            this.geoAtlasLoad = created;
+            created.promise = this.loadGeotaggedAtlas(controller.signal).then(stations => {
+                controller.signal.throwIfAborted();
+                this.geoAtlas = stations;
                 this.geoAtlasLoadedAt = Date.now();
                 return stations;
             })
-                .catch(error => {
-                this.geoAtlasPromise = null;
-                throw error;
+                .finally(() => {
+                created.settled = true;
+                if (this.geoAtlasLoad === created)
+                    this.geoAtlasLoad = null;
             });
         }
-        return this.geoAtlasPromise;
+        load.subscribers += 1;
+        try {
+            return await abortable(load.promise, signal);
+        }
+        finally {
+            load.subscribers -= 1;
+            if (load.subscribers === 0 && !load.settled) {
+                if (this.geoAtlasLoad === load)
+                    this.geoAtlasLoad = null;
+                load.controller.abort();
+            }
+        }
     }
-    async loadGeotaggedAtlas() {
+    async loadGeotaggedAtlas(signal) {
         const rows = await this.request('/json/stations/search', {
             hidebroken: 'true',
             has_geo_info: 'true',
@@ -301,23 +442,97 @@ export class RadioBrowserProvider {
         }, {
             maxAgeMs: geoAtlasMaxAgeMs,
             timeoutMs: geoAtlasTotalTimeoutMs,
-            attemptTimeoutMs: geoAtlasAttemptTimeoutMs
+            attemptTimeoutMs: geoAtlasAttemptTimeoutMs,
+            cacheOnly: networkPolicy().lowBandwidth,
+            signal
         });
-        return dedupeStations(this.normalizeStations(rows)).filter(hasValidCoordinates);
+        signal?.throwIfAborted();
+        if (!Array.isArray(rows) || rows.length > geoAtlasLimit)
+            throw new Error('Radio Browser atlas exceeded the supported row limit or returned an invalid response.');
+        // Normalize the full atlas in bounded chunks so keyboard and playback
+        // events can run between batches. Preserve the original row/dedup order.
+        const stations = [];
+        const seen = new Set();
+        let retainedBytes = 0;
+        const chunkSize = 250;
+        for (let offset = 0; offset < rows.length; offset += chunkSize) {
+            signal?.throwIfAborted();
+            for (const station of this.normalizeStations(rows.slice(offset, offset + chunkSize))) {
+                const key = `${station.provider}:${station.id}`;
+                // Dedupe before validating coordinates, matching ordinary normalization.
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                if (hasValidCoordinates(station)) {
+                    retainedBytes += JSON.stringify(station).length * 2 + 128;
+                    if (retainedBytes > geoAtlasMaxBytes)
+                        throw new Error('Radio Browser atlas exceeded the local memory budget. Use country or search discovery.');
+                    stations.push(station);
+                }
+            }
+            if (offset + chunkSize < rows.length)
+                await yieldToEventLoop();
+        }
+        return stations;
     }
     async request(path, params = {}, options = {}) {
+        options.signal?.throwIfAborted();
+        // Cacheable reads share work, but click/vote endpoints keep their effects.
+        // Cancellation belongs to each subscriber, never to cache identity.
+        const key = JSON.stringify([buildCacheKey(path, params), options.maxAgeMs, options.timeoutMs, options.attemptTimeoutMs, options.cacheOnly,
+            options.maxAgeMs ? undefined : randomUUID()]);
+        let pending = this.pendingRequests.get(key);
+        if (!pending) {
+            if (this.pendingRequests.size >= 64)
+                throw new ProviderUnavailableError('Radio Browser is busy. Retry after the current directory requests finish.');
+            const controller = new AbortController();
+            const operation = { controller, subscribers: 0, promise: Promise.resolve(undefined) };
+            operation.promise = this.performRequest(path, params, { ...options, signal: controller.signal }).finally(() => {
+                if (this.pendingRequests.get(key) === operation)
+                    this.pendingRequests.delete(key);
+            });
+            pending = operation;
+            this.pendingRequests.set(key, pending);
+        }
+        pending.subscribers += 1;
+        try {
+            return await abortable(pending.promise, options.signal);
+        }
+        finally {
+            pending.subscribers -= 1;
+            if (pending.subscribers === 0 && this.pendingRequests.get(key) === pending) {
+                this.pendingRequests.delete(key);
+                pending.controller.abort(new DOMException('Directory request has no active callers.', 'AbortError'));
+            }
+        }
+    }
+    async performRequest(path, params, options) {
+        options.signal?.throwIfAborted();
         const cacheKey = buildCacheKey(path, params);
         if (options.maxAgeMs) {
-            const cached = this.cache.get(cacheKey, options.maxAgeMs);
+            const cached = await abortable(this.cache.getAsync(cacheKey, options.maxAgeMs), options.signal);
+            options.signal?.throwIfAborted();
             if (cached) {
                 return cached;
             }
         }
+        const policy = networkPolicy();
+        if (policy.offline || options.cacheOnly) {
+            const stale = options.maxAgeMs ? await abortable(this.cache.getStaleAsync(cacheKey), options.signal) : null;
+            options.signal?.throwIfAborted();
+            if (stale !== null)
+                return stale;
+            throw new ProviderUnavailableError(policy.offline
+                ? `${this.label} is offline: no cached response is available.`
+                : `${this.label} is in low-bandwidth mode: no cached atlas is available. Disable RADIOCLI_LOW_BANDWIDTH to download it.`);
+        }
         let lastError = null;
-        const mirrors = preferActiveMirror(this.baseUrls, this.activeBaseUrl);
         const totalTimeoutMs = options.timeoutMs ?? 9000;
         const deadline = Date.now() + totalTimeoutMs;
+        const mirrors = preferActiveMirror(this.baseUrls, this.activeBaseUrl);
+        let discoveryAttempted = !this.discoverMirrors;
         for (let mirrorIndex = 0; mirrorIndex < mirrors.length; mirrorIndex += 1) {
+            options.signal?.throwIfAborted();
             const baseUrl = mirrors[mirrorIndex];
             const remainingMs = deadline - Date.now();
             if (remainingMs <= 0) {
@@ -328,16 +543,18 @@ export class RadioBrowserProvider {
                 url.searchParams.set(key, value);
             }
             try {
-                const mirrorsLeft = mirrors.length - mirrorIndex;
+                const mirrorsLeft = mirrors.length - mirrorIndex + (discoveryAttempted ? 0 : 1);
                 const fairShareTimeoutMs = Math.max(1, Math.floor(remainingMs / mirrorsLeft));
                 const attemptTimeoutMs = Math.max(1, Math.min(remainingMs, options.attemptTimeoutMs ?? fairShareTimeoutMs));
-                const value = await fetchJsonWithTimeout(url, attemptTimeoutMs);
+                const value = await fetchJsonWithTimeout(url, attemptTimeoutMs, this.runtime, options.signal);
+                options.signal?.throwIfAborted();
                 this.activeBaseUrl = baseUrl;
                 if (options.maxAgeMs) {
                     try {
-                        this.cache.set(cacheKey, value);
+                        await abortable(this.cache.setAsync(cacheKey, value), options.signal);
                     }
                     catch {
+                        options.signal?.throwIfAborted();
                         // A read-only or full cache directory must not turn live data into
                         // an apparent provider outage.
                     }
@@ -345,19 +562,45 @@ export class RadioBrowserProvider {
                 return value;
             }
             catch (error) {
+                options.signal?.throwIfAborted();
                 lastError = error instanceof Error ? error : new Error(String(error));
             }
+            if (!discoveryAttempted && mirrorIndex === mirrors.length - 1) {
+                discoveryAttempted = true;
+                const discoveryBudgetMs = Math.min(mirrorDiscoveryTimeoutMs, Math.max(1, deadline - Date.now()));
+                const discovered = await abortable(this.loadDiscoveredMirrors(discoveryBudgetMs), options.signal);
+                for (const baseUrl of discovered) {
+                    if (!mirrors.includes(baseUrl))
+                        mirrors.push(baseUrl);
+                }
+            }
         }
-        const stale = this.cache.getStale(cacheKey);
+        const stale = await abortable(this.cache.getStaleAsync(cacheKey), options.signal);
+        options.signal?.throwIfAborted();
         if (stale) {
             return stale;
         }
         throw new ProviderUnavailableError(`${this.label} unavailable: ${describeRequestError(lastError)}`, lastError ?? undefined);
     }
+    async loadDiscoveredMirrors(timeoutMs) {
+        const discovery = this.mirrorDiscoveryPromise ?? settleWithin(discoverRadioBrowserMirrors(this.runtime), timeoutMs, []);
+        this.mirrorDiscoveryPromise = discovery;
+        const mirrors = await discovery;
+        // Empty discovery commonly means a temporary DNS failure or timeout. Do
+        // not poison this provider instance for the remainder of the process.
+        if (mirrors.length === 0 && this.mirrorDiscoveryPromise === discovery)
+            this.mirrorDiscoveryPromise = null;
+        return mirrors;
+    }
 }
 function describeRequestError(error) {
     if (!error)
         return 'request failed';
+    const nestedCode = findErrorCode(error);
+    if (nestedCode === 'EAI_AGAIN')
+        return 'temporary DNS lookup failed (EAI_AGAIN)';
+    if (nestedCode && nameResolutionErrorCodes.has(nestedCode))
+        return `DNS lookup failed (${nestedCode})`;
     const cause = error.cause;
     if (cause && typeof cause === 'object') {
         const code = 'code' in cause && typeof cause.code === 'string' ? cause.code : null;
@@ -372,12 +615,7 @@ function describeRequestError(error) {
     return error.message || 'request failed';
 }
 function defaultRadioBrowserMirrors() {
-    return [
-        'https://all.api.radio-browser.info',
-        'https://de1.api.radio-browser.info',
-        'https://nl1.api.radio-browser.info',
-        'https://at1.api.radio-browser.info'
-    ];
+    return ['https://all.api.radio-browser.info'];
 }
 function preferActiveMirror(baseUrls, active) {
     return [active, ...baseUrls.filter(url => url !== active)];
@@ -386,28 +624,93 @@ function buildCacheKey(path, params) {
     const pairs = Object.entries(params).sort(([a], [b]) => a.localeCompare(b));
     return `${path}?${new URLSearchParams(pairs).toString()}`;
 }
-async function fetchJsonWithTimeout(url, timeoutMs) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const response = await fetch(url, {
-            signal: controller.signal,
-            headers: {
-                'User-Agent': userAgent(' (+https://radio-browser.info)'),
-                Accept: 'application/json'
-            }
-        });
+async function fetchJsonWithTimeout(url, timeoutMs, runtime, signal) {
+    const startedAt = Date.now();
+    const init = {
+        signal,
+        headers: {
+            'User-Agent': userAgent(' (+https://radio-browser.info)'),
+            Accept: 'application/json'
+        }
+    };
+    const consume = async (response) => {
         if (!response.ok) {
             throw new Error(`Radio Browser request failed: ${response.status} ${response.statusText}`);
         }
-        // Keep the abort timer alive while consuming the body as well as headers.
         return (await response.json());
+    };
+    try {
+        return await withExternalResponse(url, { timeoutMs, init }, consume);
     }
-    finally {
-        clearTimeout(timeout);
+    catch (error) {
+        signal?.throwIfAborted();
+        const remainingMs = timeoutMs - (Date.now() - startedAt);
+        if (remainingMs <= 0 ||
+            !isNameResolutionError(error) ||
+            !isRadioBrowserApiHostname(url.hostname) ||
+            !(runtime.allowsDirectDnsFallback ?? (target => allowsDirectDnsFallback(process.env, target)))(url)) {
+            throw error;
+        }
+        return withExternalResponse(url, {
+            timeoutMs: remainingMs,
+            init,
+            fetchImpl: runtime.fetchWithSystemResolver ?? fetchHttpsWithSystemResolver
+        }, consume);
     }
 }
-export function dedupeStations(stations) {
+async function discoverRadioBrowserMirrors(runtime) {
+    const records = await (runtime.resolveSrv ?? resolveSrv)(radioBrowserService);
+    return dedupeUrls(records
+        .filter(record => record.port === 443)
+        .sort((a, b) => a.priority - b.priority || b.weight - a.weight || a.name.localeCompare(b.name))
+        .flatMap(record => {
+        const hostname = record.name.replace(/\.$/, '').toLowerCase();
+        return isRadioBrowserApiHostname(hostname) ? [`https://${hostname}`] : [];
+    }));
+}
+function isRadioBrowserApiHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    return normalized === 'api.radio-browser.info' || normalized.endsWith(radioBrowserApiSuffix);
+}
+function isNameResolutionError(error) {
+    const code = findErrorCode(error);
+    return code !== null && nameResolutionErrorCodes.has(code);
+}
+function findErrorCode(error) {
+    const seen = new Set();
+    const pending = [error];
+    while (pending.length > 0) {
+        const value = pending.pop();
+        if (!value || seen.has(value))
+            continue;
+        seen.add(value);
+        if (typeof value === 'object') {
+            if ('code' in value && typeof value.code === 'string')
+                return value.code;
+            if ('cause' in value)
+                pending.push(value.cause);
+            if (value instanceof AggregateError)
+                pending.push(...value.errors);
+        }
+    }
+    return null;
+}
+function dedupeUrls(urls) {
+    return [...new Set(urls)];
+}
+function settleWithin(promise, timeoutMs, fallback) {
+    return new Promise(resolve => {
+        const timeout = setTimeout(() => resolve(fallback), timeoutMs);
+        promise.then(value => {
+            clearTimeout(timeout);
+            resolve(value);
+        }, () => {
+            clearTimeout(timeout);
+            resolve(fallback);
+        });
+    });
+}
+function dedupeStations(stations) {
     const seen = new Set();
     const deduped = [];
     for (const station of stations) {
@@ -459,12 +762,17 @@ function compareNearbyStations(a, b) {
     }
     return a.name.localeCompare(b.name);
 }
-function nearestStations(stations, location, limit) {
+async function nearestStations(stations, location, limit, signal) {
     const nearest = [];
     const boundedLimit = Math.max(0, Math.floor(limit));
     if (boundedLimit === 0)
         return nearest;
-    for (const station of stations) {
+    for (let index = 0; index < stations.length; index += 1) {
+        if (index > 0 && index % 500 === 0)
+            await yieldToEventLoop();
+        if (index % 500 === 0)
+            signal?.throwIfAborted();
+        const station = stations[index];
         if (!hasValidCoordinates(station))
             continue;
         const candidate = {
@@ -525,6 +833,27 @@ function scoreStation(station, query, tokens) {
     const exactScore = searchable.includes(loweredQuery) ? 12 : 0;
     return exactScore + tokenScore + Math.log10((station.clickCount ?? 0) + 1);
 }
+function discoverySource(source, params) {
+    return { provider: 'radio-browser', source, consumed: 0, exhausted: false, status: 'available', params };
+}
+function pageLimit(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1 || value > 1000)
+        throw new Error('Discovery page size must be between 1 and 1000.');
+    return value;
+}
+function searchFilters(options) {
+    return { codec: options.codec, language: options.language, countryCode: options.countryCode?.toUpperCase(), minBitrate: options.minBitrate };
+}
+function searchFilterParams(options) {
+    return {
+        ...(options.codec ? { codec: options.codec } : {}),
+        ...(options.language ? { language: options.language } : {}),
+        ...(options.countryCode ? { countrycode: options.countryCode.toUpperCase() } : {}),
+        ...(options.minBitrate ? { bitrateMin: String(options.minBitrate) } : {})
+    };
+}
 function filterStations(stations, options) {
     return stations.filter(station => {
         if (options.minBitrate && (station.bitrate ?? 0) < options.minBitrate) {