gerdur-core 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.0.4 - 2026-08-31
+
+### Added
+
+- `resolveDownloadUrls(tracks, qualities)` — resolve download URLs for a whole album/playlist in **one** `media.deezer.com/v1/get_url` POST (`track_tokens[]` + an ordered `formats[]` fallback), instead of one request per track re-tried per quality. ~19× faster URL resolution for a 14-track album. Returns one `ResolvedUrl | null` per input track, in order. `formatName(quality)` is also exported.
+- `httpAgent` / `httpsAgent` — the shared keep-alive connection pools are now exported so downstream apps can hand them to `got`/`undici` and reuse the same sockets for downloads. `getBuffer` / `getJson` / `getText` are exported too.
+
+### Changed
+
+- **Shared HTTP agents are tuned and bounded**: `keepAlive`, `maxSockets: 64` (was the Node default of `Infinity`), `maxFreeSockets: 16`, `scheduling: 'lifo'`, 30 s keep-alive. Caps a pathological fan-out from opening hundreds of sockets to `api.deezer.com`, while leaving generous headroom over the converter's concurrency.
+- **In-flight request coalescing** in the API layer: concurrent identical gateway / public-API calls (e.g. every track of one album asking for the same album info while tagging) now share a single request instead of each missing the still-empty cache and hitting the wire.
+
+## 1.0.3 - 2026-08-30
+
+### Changed
+
+- `getTrackDownloadUrl`: when `media.deezer.com/v1/get_url` returns 403/429/5xx (throttling or a stale license token), re-authenticate and retry with exponential backoff (up to 3×); if it still fails, fall through to the token-free legacy CDN instead of throwing.
+
 ## 1.0.2 - 2026-08-30
 
 ### Fixed

package/dist/api/request.js

@@ -6,6 +6,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestPublicApi = exports.requestGet = exports.requestLight = exports.request = void 0;
 const request_1 = __importDefault(require("../lib/request"));
 const cache_1 = __importDefault(require("./cache"));
+/**
+ * In-flight request coalescing (single-flight).
+ *
+ * The LRU only helps *after* a response lands. During a batch download the
+ * pipeline fires many identical metadata calls at once — e.g. tagging 14 tracks
+ * of one album triggers 14 concurrent `album/<id>` lookups — and every one of
+ * them misses the still-empty cache and hits the network. Here a second caller
+ * for a key already in flight awaits the same promise instead, so the wire sees
+ * exactly one request. Entries are removed as soon as they settle; the LRU takes
+ * over from there.
+ */
+const inFlight = new Map();
+const coalesce = (cacheKey, fetcher) => {
+    const cached = cache_1.default.get(cacheKey);
+    if (cached) {
+        return Promise.resolve(cached);
+    }
+    const pending = inFlight.get(cacheKey);
+    if (pending) {
+        return pending;
+    }
+    const promise = (async () => {
+        try {
+            return await fetcher();
+        }
+        finally {
+            inFlight.delete(cacheKey);
+        }
+    })();
+    inFlight.set(cacheKey, promise);
+    return promise;
+};
 /**
  * Make POST requests to deezer api
  * @param {Object} body post body
@@ -13,17 +45,14 @@ const cache_1 = __importDefault(require("./cache"));
  */
 const request = async (body, method) => {
     const cacheKey = method + ':' + Object.entries(body).join(':');
-    const cache = cache_1.default.get(cacheKey);
-    if (cache) {
-        return cache;
-    }
-    const { data: { error, results }, } = await request_1.default.post('/gateway.php', body, { params: { method } });
-    if (Object.keys(results).length > 0) {
-        cache_1.default.set(cacheKey, results);
-        return results;
-    }
-    const errorMessage = Object.entries(error).join(', ');
-    throw new Error(errorMessage);
+    return coalesce(cacheKey, async () => {
+        const { data: { error, results }, } = await request_1.default.post('/gateway.php', body, { params: { method } });
+        if (Object.keys(results).length > 0) {
+            cache_1.default.set(cacheKey, results);
+            return results;
+        }
+        throw new Error(Object.entries(error).join(', '));
+    });
 };
 exports.request = request;
 /**
@@ -33,19 +62,16 @@ exports.request = request;
  */
 const requestLight = async (body, method) => {
     const cacheKey = method + ':' + Object.entries(body).join(':');
-    const cache = cache_1.default.get(cacheKey);
-    if (cache) {
-        return cache;
-    }
-    const { data: { error, results }, } = await request_1.default.post('https://www.deezer.com/ajax/gw-light.php', body, {
-        params: { method, api_version: '1.0' },
+    return coalesce(cacheKey, async () => {
+        const { data: { error, results }, } = await request_1.default.post('https://www.deezer.com/ajax/gw-light.php', body, {
+            params: { method, api_version: '1.0' },
+        });
+        if (Object.keys(results).length > 0) {
+            cache_1.default.set(cacheKey, results);
+            return results;
+        }
+        throw new Error(Object.entries(error).join(', '));
     });
-    if (Object.keys(results).length > 0) {
-        cache_1.default.set(cacheKey, results);
-        return results;
-    }
-    const errorMessage = Object.entries(error).join(', ');
-    throw new Error(errorMessage);
 };
 exports.requestLight = requestLight;
 /**
@@ -55,17 +81,14 @@ exports.requestLight = requestLight;
  */
 const requestGet = async (method, params = {}, key = 'get_request') => {
     const cacheKey = method + key;
-    const cache = cache_1.default.get(cacheKey);
-    if (cache) {
-        return cache;
-    }
-    const { data: { error, results }, } = await request_1.default.get('/gateway.php', { params: { method, ...params } });
-    if (Object.keys(results).length > 0) {
-        cache_1.default.set(cacheKey, results);
-        return results;
-    }
-    const errorMessage = Object.entries(error).join(', ');
-    throw new Error(errorMessage);
+    return coalesce(cacheKey, async () => {
+        const { data: { error, results }, } = await request_1.default.get('/gateway.php', { params: { method, ...params } });
+        if (Object.keys(results).length > 0) {
+            cache_1.default.set(cacheKey, results);
+            return results;
+        }
+        throw new Error(Object.entries(error).join(', '));
+    });
 };
 exports.requestGet = requestGet;
 /**
@@ -73,16 +96,14 @@ exports.requestGet = requestGet;
  * @param {String} slug endpoint
  */
 const requestPublicApi = async (slug) => {
-    const cache = cache_1.default.get(slug);
-    if (cache) {
-        return cache;
-    }
-    const { data } = await request_1.default.get('https://api.deezer.com' + slug);
-    if (data.error) {
-        const errorMessage = Object.entries(data.error).join(', ');
-        throw new Error(errorMessage);
-    }
-    cache_1.default.set(slug, data);
-    return data;
+    return coalesce(slug, async () => {
+        const { data } = await request_1.default.get('https://api.deezer.com' + slug);
+        if (data.error) {
+            const errorMessage = Object.entries(data.error).join(', ');
+            throw new Error(errorMessage);
+        }
+        cache_1.default.set(slug, data);
+        return data;
+    });
 };
 exports.requestPublicApi = requestPublicApi;

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from './api';
 export * from './converter';
 export * from './lib/decrypt';
 export * from './lib/get-url';
+export { httpAgent, httpsAgent, getBuffer, getJson, getText } from './lib/http';
 export * from './metadata-writer';

package/dist/index.js

@@ -14,11 +14,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initDeezerApi = void 0;
+exports.getText = exports.getJson = exports.getBuffer = exports.httpsAgent = exports.httpAgent = exports.initDeezerApi = void 0;
 var request_1 = require("./lib/request");
 Object.defineProperty(exports, "initDeezerApi", { enumerable: true, get: function () { return request_1.initDeezerApi; } });
 __exportStar(require("./api"), exports);
 __exportStar(require("./converter"), exports);
 __exportStar(require("./lib/decrypt"), exports);
 __exportStar(require("./lib/get-url"), exports);
+var http_1 = require("./lib/http");
+Object.defineProperty(exports, "httpAgent", { enumerable: true, get: function () { return http_1.httpAgent; } });
+Object.defineProperty(exports, "httpsAgent", { enumerable: true, get: function () { return http_1.httpsAgent; } });
+Object.defineProperty(exports, "getBuffer", { enumerable: true, get: function () { return http_1.getBuffer; } });
+Object.defineProperty(exports, "getJson", { enumerable: true, get: function () { return http_1.getJson; } });
+Object.defineProperty(exports, "getText", { enumerable: true, get: function () { return http_1.getText; } });
 __exportStar(require("./metadata-writer"), exports);

package/dist/lib/get-url.d.ts

@@ -13,6 +13,8 @@ export declare class ExpiredTrackToken extends Error {
     readonly sngId: string;
     constructor(sngId: string);
 }
+/** quality code -> the `format` string the media API expects */
+export declare const formatName: (quality: number) => string;
 /**
  * @param track Track info json returned from `getTrackInfo`
  * @param quality 1 = 128kbps, 3 = 320kbps and 9 = flac (around 1411kbps)
@@ -22,3 +24,22 @@ export declare const getTrackDownloadUrl: (track: trackType, quality: number) =>
     isEncrypted: boolean;
     fileSize: number;
 } | null>;
+export interface ResolvedUrl {
+    trackUrl: string;
+    isEncrypted: boolean;
+    fileSize: number;
+    /** the format Deezer actually returned, e.g. `'FLAC'` */
+    format: string;
+}
+/**
+ * Resolve download URLs for many tracks in a **single** `get_url` request.
+ *
+ * `qualities` is an ordered preference list (e.g. `[9, 3, 1]`): Deezer returns
+ * the best each track is licensed for, so there is no per-quality retry. The
+ * result has one entry per input track, in order; `null` for a track that is
+ * geo-blocked, unavailable, or errored.
+ *
+ * @param tracks    from `getTrackInfo` / `parseInfo` (needs `TRACK_TOKEN`, `SNG_ID`, `FILESIZE_*`)
+ * @param qualities preference order — 9 = FLAC, 3 = MP3 320, 1 = MP3 128
+ */
+export declare const resolveDownloadUrls: (tracks: trackType[], qualities?: number[]) => Promise<(ResolvedUrl | null)[]>;

package/dist/lib/get-url.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTrackDownloadUrl = exports.ExpiredTrackToken = exports.GeoBlocked = exports.WrongLicense = void 0;
+exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.formatName = exports.ExpiredTrackToken = exports.GeoBlocked = exports.WrongLicense = void 0;
+const delay_1 = __importDefault(require("delay"));
 const decrypt_1 = require("../lib/decrypt");
 const http_1 = require("../lib/http");
 const request_1 = __importDefault(require("../lib/request"));
@@ -64,36 +65,69 @@ const dzAuthenticate = async () => {
     };
     return user_data;
 };
+const MEDIA_MAX_RETRIES = 3;
+/** quality code -> the `format` string the media API expects */
+const formatName = (quality) => {
+    switch (quality) {
+        case 9:
+            return 'FLAC';
+        case 3:
+            return 'MP3_320';
+        case 1:
+            return 'MP3_128';
+        default:
+            throw new Error(`Unknown quality ${quality}`);
+    }
+};
+exports.formatName = formatName;
+/** POST media.deezer.com/v1/get_url with re-auth + exponential-backoff retry on 403/429/5xx. */
+const mediaGetUrl = async (track_tokens, formats, attempt = 0) => {
+    var _a;
+    const user = user_data ? user_data : await dzAuthenticate();
+    try {
+        const { data } = await request_1.default.post('https://media.deezer.com/v1/get_url', {
+            license_token: user.license_token,
+            media: [{ type: 'FULL', formats }],
+            track_tokens,
+        });
+        return { data: (_a = data.data) !== null && _a !== void 0 ? _a : [], country: user.country };
+    }
+    catch (err) {
+        const status = err instanceof http_1.HttpStatusError ? err.statusCode : 0;
+        if ((status === 403 || status === 429 || status >= 500) && attempt < MEDIA_MAX_RETRIES) {
+            user_data = null;
+            await (0, delay_1.default)(500 * 2 ** attempt + Math.floor(Math.random() * 250));
+            return mediaGetUrl(track_tokens, formats, attempt + 1);
+        }
+        throw err;
+    }
+};
+/** Parse one `data[i]` entry from a get_url response into a source URL (or null / throw). */
+const parseMediaEntry = (entry, token, country) => {
+    var _a, _b;
+    if (entry === null || entry === void 0 ? void 0 : entry.errors) {
+        const { code } = entry.errors[0];
+        if (code === 2002)
+            throw new GeoBlocked(country);
+        if (code === 2000 || code === 2001)
+            throw new ExpiredTrackToken(token);
+        throw new Error(Object.entries(entry.errors[0]).join(', '));
+    }
+    const media = (_a = entry === null || entry === void 0 ? void 0 : entry.media) === null || _a === void 0 ? void 0 : _a[0];
+    if (!((_b = media === null || media === void 0 ? void 0 : media.sources) === null || _b === void 0 ? void 0 : _b.length))
+        return null;
+    return { url: media.sources[0].url, format: media.format };
+};
 const getTrackUrlFromServer = async (track_token, format) => {
+    var _a, _b;
     const user = user_data ? user_data : await dzAuthenticate();
     if ((format === 'FLAC' && !user.can_stream_lossless) || (format === 'MP3_320' && !user.can_stream_hq)) {
         throw new WrongLicense(format);
     }
-    const { data } = await request_1.default.post('https://media.deezer.com/v1/get_url', {
-        license_token: user.license_token,
-        media: [
-            {
-                type: 'FULL',
-                formats: [{ format, cipher: 'BF_CBC_STRIPE' }],
-            },
-        ],
-        track_tokens: [track_token],
-    });
-    if (data.data.length > 0) {
-        if (data.data[0].errors) {
-            const { code } = data.data[0].errors[0];
-            if (code === 2002) {
-                throw new GeoBlocked(user.country);
-            }
-            // 2000: invalid/expired token · 2001: token has no rights on this song
-            if (code === 2000 || code === 2001) {
-                throw new ExpiredTrackToken(track_token);
-            }
-            throw new Error(Object.entries(data.data[0].errors[0]).join(', '));
-        }
-        return data.data[0].media.length > 0 ? data.data[0].media[0].sources[0].url : null;
-    }
-    return null;
+    const { data, country } = await mediaGetUrl([track_token], [{ format, cipher: 'BF_CBC_STRIPE' }]);
+    if (!data.length)
+        return null;
+    return (_b = (_a = parseMediaEntry(data[0], track_token, country)) === null || _a === void 0 ? void 0 : _a.url) !== null && _b !== void 0 ? _b : null;
 };
 /**
  * @param track Track info json returned from `getTrackInfo`
@@ -103,20 +137,8 @@ const getTrackDownloadUrl = async (track, quality) => {
     let wrongLicense = null;
     let geoBlocked = null;
     let expiredToken = null;
-    let formatName;
-    switch (quality) {
-        case 9:
-            formatName = 'FLAC';
-            break;
-        case 3:
-            formatName = 'MP3_320';
-            break;
-        case 1:
-            formatName = 'MP3_128';
-            break;
-        default:
-            throw new Error(`Unknown quality ${quality}`);
-    }
+    let mediaBlocked = null;
+    const format = (0, exports.formatName)(quality);
     // Track tokens last ~1 hour. If it's already stale, skip the doomed media API
     // call and go straight to the token-free fallback below.
     const tokenStale = Boolean(track.TRACK_TOKEN_EXPIRE && track.TRACK_TOKEN_EXPIRE * 1000 < Date.now());
@@ -126,7 +148,7 @@ const getTrackDownloadUrl = async (track, quality) => {
     else {
         // Get URL with the official API
         try {
-            const url = await getTrackUrlFromServer(track.TRACK_TOKEN, formatName);
+            const url = await getTrackUrlFromServer(track.TRACK_TOKEN, format);
             if (url) {
                 return {
                     trackUrl: url,
@@ -145,6 +167,10 @@ const getTrackDownloadUrl = async (track, quality) => {
             else if (err instanceof ExpiredTrackToken) {
                 expiredToken = err;
             }
+            else if (err instanceof http_1.HttpStatusError && (err.statusCode === 403 || err.statusCode === 429)) {
+                // media API is throttling this account — try the token-free legacy CDN below
+                mediaBlocked = err;
+            }
             else {
                 throw err;
             }
@@ -172,6 +198,9 @@ const getTrackDownloadUrl = async (track, quality) => {
     if (expiredToken) {
         throw expiredToken;
     }
+    if (mediaBlocked) {
+        throw mediaBlocked;
+    }
     return null;
 };
 exports.getTrackDownloadUrl = getTrackDownloadUrl;
@@ -184,3 +213,42 @@ const testUrl = async (url) => {
         return 0;
     }
 };
+const QUALITY_OF_FORMAT = { FLAC: 9, MP3_320: 3, MP3_128: 1, MP3_256: 3, MP3_64: 1 };
+/**
+ * Resolve download URLs for many tracks in a **single** `get_url` request.
+ *
+ * `qualities` is an ordered preference list (e.g. `[9, 3, 1]`): Deezer returns
+ * the best each track is licensed for, so there is no per-quality retry. The
+ * result has one entry per input track, in order; `null` for a track that is
+ * geo-blocked, unavailable, or errored.
+ *
+ * @param tracks    from `getTrackInfo` / `parseInfo` (needs `TRACK_TOKEN`, `SNG_ID`, `FILESIZE_*`)
+ * @param qualities preference order — 9 = FLAC, 3 = MP3 320, 1 = MP3 128
+ */
+const resolveDownloadUrls = async (tracks, qualities = [9, 3, 1]) => {
+    if (!tracks.length)
+        return [];
+    const formats = qualities.map((q) => ({ format: (0, exports.formatName)(q), cipher: 'BF_CBC_STRIPE' }));
+    const { data, country } = await mediaGetUrl(tracks.map((t) => t.TRACK_TOKEN), formats);
+    return tracks.map((track, i) => {
+        var _a;
+        let parsed;
+        try {
+            parsed = parseMediaEntry(data[i], track.TRACK_TOKEN, country);
+        }
+        catch {
+            // per-track error (geo-block, no rights, expired token) — skip this one
+            return null;
+        }
+        if (!parsed)
+            return null;
+        const q = (_a = QUALITY_OF_FORMAT[parsed.format]) !== null && _a !== void 0 ? _a : qualities[0];
+        return {
+            trackUrl: parsed.url,
+            isEncrypted: parsed.url.includes('/mobile/') || parsed.url.includes('/media/'),
+            fileSize: getTrackFileSize(track, q),
+            format: parsed.format,
+        };
+    });
+};
+exports.resolveDownloadUrls = resolveDownloadUrls;

package/dist/lib/http.d.ts

@@ -1,6 +1,8 @@
 /// <reference types="node" />
 /// <reference types="node" />
-import { IncomingHttpHeaders } from 'http';
+/// <reference types="node" />
+import { Agent as HttpAgent, IncomingHttpHeaders } from 'http';
+import { Agent as HttpsAgent } from 'https';
 type HttpMethod = 'GET' | 'POST' | 'HEAD';
 type ResponseType = 'buffer' | 'json' | 'text';
 type QueryValue = string | number | boolean | null | undefined;
@@ -22,6 +24,8 @@ interface RequestDescriptor {
     timeout: number;
     url: string;
 }
+export declare const httpAgent: HttpAgent;
+export declare const httpsAgent: HttpsAgent;
 export interface HttpResponse<T> {
     config: RequestDescriptor;
     data: T;

package/dist/lib/http.js

@@ -1,11 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.headRequest = exports.getText = exports.getJson = exports.getBuffer = exports.HttpClient = exports.HttpStatusError = void 0;
+exports.headRequest = exports.getText = exports.getJson = exports.getBuffer = exports.HttpClient = exports.HttpStatusError = exports.httpsAgent = exports.httpAgent = void 0;
 const http_1 = require("http");
 const https_1 = require("https");
 const zlib_1 = require("zlib");
-const httpAgent = new http_1.Agent({ keepAlive: true });
-const httpsAgent = new https_1.Agent({ keepAlive: true });
+/**
+ * Shared keep-alive connection pools. Every request gerdur-core makes — gateway,
+ * media API, CDN HEAD probes — reuses these, so a batch of calls to the same host
+ * rides one handful of TCP+TLS connections instead of a fresh handshake each time.
+ *
+ * `maxSockets` is bounded (not the Node default of `Infinity`): the converter fans
+ * out at concurrency 10–25, so 64 is generous headroom while still capping a
+ * pathological fan-out that would otherwise open hundreds of sockets to
+ * `api.deezer.com` and get the account rate-limited. `scheduling: 'lifo'` keeps
+ * the hottest socket warm. Downstream apps can import these and hand them to
+ * `got`/`undici` so downloads share the same pool.
+ */
+const AGENT_OPTS = {
+    keepAlive: true,
+    keepAliveMsecs: 30000,
+    maxSockets: 64,
+    maxFreeSockets: 16,
+    scheduling: 'lifo',
+    timeout: 60000,
+};
+exports.httpAgent = new http_1.Agent(AGENT_OPTS);
+exports.httpsAgent = new https_1.Agent(AGENT_OPTS);
 class HttpStatusError extends Error {
     constructor(statusCode, headers, body) {
         super(`Request failed with status code ${statusCode}`);
@@ -86,7 +106,7 @@ const requestRaw = async (config, redirectCount = 0) => {
         const isHttps = requestUrl.protocol === 'https:';
         const requestFn = isHttps ? https_1.request : http_1.request;
         const req = requestFn({
-            agent: isHttps ? httpsAgent : httpAgent,
+            agent: isHttps ? exports.httpsAgent : exports.httpAgent,
             headers,
             hostname: requestUrl.hostname,
             method: config.method,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur-core",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Core module for gerdur.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",