gerdur-core 2.13.3 → 2.14.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 2.14.0 - 2026-08-31
+
+Multi-tenant caching — for backends where many accounts share one process.
+
+### Added
+
+- **Shared gateway metadata cache.** Most gw payloads embed a per-account
+  `TRACK_TOKEN`, so each `Session` keeps its own cache. Five methods carry
+  nothing account-scoped — `album.getData`, `artist.getData`, `song.getLyrics`,
+  `album.getDiscography`, `playlist.getData` — and now go to a process-wide cache
+  **partitioned by country**, with a shared in-flight map so a concurrent burst
+  collapses into one request. Measured with 500 sessions reading the same album:
+  **500 gateway requests → 1**, and 1.8 MB of duplicated payload → one copy.
+  Track-bearing methods (`song.getData`, `playlist.getSongs`,
+  `song.getListByAlbum`, `song.getListData`, `episode.getData`, `mobile.*`,
+  `deezer.pageSearch`, `user_getInfo`, …) are never shared.
+- **`configureCache({shared: {maxSize, ttl}})`** — size the shared cache to your
+  catalogue. Default `{maxSize: 2000, ttl: 3_600_000}`.
+- **`cacheStats()`** → `{shared: {size, maxSize, hits, misses, inFlight}}` — for
+  a `/metrics` or health endpoint.
+- **`clearSharedCaches()`** — drops the shared cache; per-session caches are
+  untouched.
+- `__tests__/caches.ts` — offline tests pinning the isolation guarantees: no
+  cross-account token reuse, no cross-country bleed, in-flight entries released.
+- README: a **Running this on a server** section (stream don't buffer, decrypt is
+  on the event loop, size the cache, evict idle sessions).
+
+### Not done, deliberately
+
+- Memoising the initialised Blowfish key schedule per track was implemented,
+  measured and **reverted**: key setup is 39.7 µs against 33 ms to decrypt an
+  8 MiB file — **0.12%**, with break-even at ~10 KiB decrypted per key. Not worth
+  a cache or the public knob it would need.
+
 ## 2.13.3 - 2026-08-31
 
 ### Docs

package/README.md

@@ -55,6 +55,7 @@ the CLI and the file-writing layer on top.
   - [Tag MP3 / FLAC](#tag-mp3--flac)
   - [Enrichment (MusicBrainz + Cover Art Archive)](#enrichment)
   - [Use multiple accounts](#use-multiple-accounts)
+  - [Running this on a server](#running-this-on-a-server)
   - [HTTP helpers](#http-helpers)
 - [Errors](#errors)
 - [Types](#types)
@@ -604,6 +605,38 @@ and the raw channels (`gw`, `gwLight`, `gwGet`).
 in tests). The free `getTrackDownloadUrl` / `resolveDownloadUrls` /
 `streamTrackDownload` / `refreshTrackTokens` all take an optional `session`.
 
+**Caching across sessions.** Most gw payloads embed a per-account `TRACK_TOKEN`,
+so each `Session` has its own response cache. Five methods carry nothing
+account-scoped — `album.getData`, `artist.getData`, `song.getLyrics`,
+`album.getDiscography`, `playlist.getData` — and those go to a **process-wide
+cache partitioned by country**, so one copy serves every session and a
+concurrent burst collapses into one request. Measured with 500 sessions reading
+the same album: **500 gateway requests → 1**, and 1.8 MB of duplicated payload →
+one copy. Track lists (`song.getData`, `playlist.getSongs`, `song.getListByAlbum`,
+`episode.getData`, …) are never shared.
+
+```ts
+import {configureCache, cacheStats, clearSharedCaches} from 'gerdur-core';
+
+configureCache({shared: {maxSize: 20_000, ttl: 30 * 60_000}}); // once, at startup
+cacheStats(); // {shared: {size, maxSize, hits, misses, inFlight}} — for /metrics
+```
+
+### Running this on a server
+
+- **Stream, don't buffer.** `downloadTrackBuffer` / `getTrackBuffer` hold the
+  whole file (and `Buffer.concat` doubles it briefly) — fine for a script, a
+  memory bomb at concurrency. Use `streamTrackDownload` in a request path.
+- **Decryption runs on the event loop.** Blowfish costs ~33 ms per 8 MiB
+  (~243 MiB/s), so heavy concurrent traffic will compete with everything else in
+  the process. Put the decrypt in a worker if you saturate a core.
+- **Size the shared cache** to your catalogue with `configureCache`, and export
+  `cacheStats()` so you can see the hit rate.
+- **Evict idle sessions yourself.** `createSession` has no lifecycle — a session
+  per user, kept forever, keeps its cache forever.
+- `httpAgent` / `httpsAgent` are process-global (`maxSockets: 64`) and shared
+  between API calls and CDN downloads.
+
 ### HTTP helpers
 
 The zero-dependency HTTP client (`get`/`post`/`head`, redirects, gzip/br/deflate,
@@ -759,7 +792,8 @@ import type {
 <details>
 <summary><b>HTTP &amp; errors</b></summary>
 
-`getJson` · `getText` · `getBuffer` · `getStream` · `HttpClient` · `httpAgent` ·
+`configureCache` · `cacheStats` · `clearSharedCaches` · `getJson` · `getText` ·
+`getBuffer` · `getStream` · `HttpClient` · `httpAgent` ·
 `httpsAgent` · `HttpStatusError` · `DeezerError` · `GeoBlocked` · `WrongLicense`
 · `ExpiredTrackToken`
 </details>

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { initDeezerApi, createSession, defaultSession, Session, RETRY_POLICY, DE
 export type { SessionUserData } from './lib/session';
 export { DeezerError } from './lib/errors';
 export type { DeezerErrorPayload } from './lib/errors';
+export { configureCache, cacheStats, clearSharedCaches } from './lib/caches';
+export type { CacheOptions, CacheStats } from './lib/caches';
 export * from './api';
 export * from './converter';
 export * from './lib/decrypt';

package/dist/index.js

@@ -14,7 +14,7 @@ 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.getStream = exports.getText = exports.getJson = exports.getBuffer = exports.httpsAgent = exports.httpAgent = exports.DeezerError = exports.DEFAULT_ARL = exports.RETRY_POLICY = exports.Session = exports.defaultSession = exports.createSession = exports.initDeezerApi = void 0;
+exports.getStream = exports.getText = exports.getJson = exports.getBuffer = exports.httpsAgent = exports.httpAgent = exports.clearSharedCaches = exports.cacheStats = exports.configureCache = exports.DeezerError = exports.DEFAULT_ARL = exports.RETRY_POLICY = exports.Session = exports.defaultSession = exports.createSession = exports.initDeezerApi = void 0;
 require("./lib/session-augment"); // wires the download methods onto Session.prototype
 var session_1 = require("./lib/session");
 Object.defineProperty(exports, "initDeezerApi", { enumerable: true, get: function () { return session_1.initDeezerApi; } });
@@ -25,6 +25,10 @@ Object.defineProperty(exports, "RETRY_POLICY", { enumerable: true, get: function
 Object.defineProperty(exports, "DEFAULT_ARL", { enumerable: true, get: function () { return session_1.DEFAULT_ARL; } });
 var errors_1 = require("./lib/errors");
 Object.defineProperty(exports, "DeezerError", { enumerable: true, get: function () { return errors_1.DeezerError; } });
+var caches_1 = require("./lib/caches");
+Object.defineProperty(exports, "configureCache", { enumerable: true, get: function () { return caches_1.configureCache; } });
+Object.defineProperty(exports, "cacheStats", { enumerable: true, get: function () { return caches_1.cacheStats; } });
+Object.defineProperty(exports, "clearSharedCaches", { enumerable: true, get: function () { return caches_1.clearSharedCaches; } });
 __exportStar(require("./api"), exports);
 __exportStar(require("./converter"), exports);
 __exportStar(require("./lib/decrypt"), exports);

package/dist/lib/caches.d.ts

@@ -0,0 +1,59 @@
+/** An LRU that counts hits and misses and can be resized at runtime. */
+declare class CountingCache {
+    private lru;
+    private opts;
+    hits: number;
+    misses: number;
+    constructor(maxSize: number, ttl?: number);
+    get(key: string): any;
+    set(key: string, value: any): void;
+    clear(): void;
+    /** Resize / re-TTL. Drops the current contents (a new LRU is built). */
+    reconfigure(opts: {
+        maxSize?: number;
+        ttl?: number;
+    }): void;
+    get size(): number;
+    get maxSize(): number;
+}
+/**
+ * Account-independent gateway payloads, shared across every {@link Session}.
+ * Keyed by country + method + params — see `Session.gw`.
+ */
+export declare const sharedGatewayCache: CountingCache;
+/** In-flight requests for {@link sharedGatewayCache}, so concurrent sessions coalesce. */
+export declare const sharedInFlight: Map<string, Promise<any>>;
+export interface CacheOptions {
+    /**
+     * The shared gateway metadata cache. Default `{maxSize: 2000, ttl: 3_600_000}`.
+     * Raise `maxSize` for a large catalogue; entries are JSON payloads of a few KB.
+     */
+    shared?: {
+        maxSize?: number;
+        ttl?: number;
+    };
+}
+/**
+ * Resize the shared cache. Call once at startup — reconfiguring drops its
+ * contents.
+ *
+ * ```ts
+ * configureCache({shared: {maxSize: 20_000, ttl: 30 * 60_000}});
+ * ```
+ */
+export declare const configureCache: (options: CacheOptions) => void;
+/** Drop the shared cache. Per-session caches are untouched (`session.cache.clear()` for those). */
+export declare const clearSharedCaches: () => void;
+export interface CacheStats {
+    /** the shared account-independent gateway metadata cache */
+    shared: {
+        size: number;
+        maxSize: number;
+        hits: number;
+        misses: number;
+        inFlight: number;
+    };
+}
+/** A snapshot of shared-cache occupancy and hit rate — for metrics / health endpoints. */
+export declare const cacheStats: () => CacheStats;
+export {};

package/dist/lib/caches.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheStats = exports.clearSharedCaches = exports.configureCache = exports.sharedInFlight = exports.sharedGatewayCache = void 0;
+/**
+ * The process-wide cache for account-independent gateway metadata.
+ *
+ * Each {@link Session} keeps its own response cache because most gw payloads
+ * embed a per-account `TRACK_TOKEN`. A handful of methods carry nothing
+ * account-scoped, though — album, artist, lyrics, discography and playlist
+ * metadata are the same bytes for every account in a country. Caching those per
+ * session multiplies one payload by the number of logged-in accounts, which is
+ * fine for a script and wrong for a server.
+ *
+ * Holding them here means they are stored once, and — via {@link sharedInFlight}
+ * — a burst of sessions asking for the same album shares a single request
+ * instead of issuing one each. Measured at 500 sessions reading one album:
+ * **500 gateway requests → 1**, and 1.8 MB of duplicated payload → one copy.
+ *
+ * Tune with {@link configureCache}, inspect with {@link cacheStats}.
+ */
+const fast_lru_1 = __importDefault(require("./fast-lru"));
+/** An LRU that counts hits and misses and can be resized at runtime. */
+class CountingCache {
+    constructor(maxSize, ttl = 0) {
+        this.hits = 0;
+        this.misses = 0;
+        this.opts = { maxSize, ttl };
+        this.lru = new fast_lru_1.default(this.opts);
+    }
+    get(key) {
+        const value = this.lru.get(key);
+        if (value === undefined) {
+            this.misses++;
+        }
+        else {
+            this.hits++;
+        }
+        return value;
+    }
+    set(key, value) {
+        this.lru.set(key, value);
+    }
+    clear() {
+        this.lru.clear();
+    }
+    /** Resize / re-TTL. Drops the current contents (a new LRU is built). */
+    reconfigure(opts) {
+        var _a, _b;
+        this.opts = { maxSize: (_a = opts.maxSize) !== null && _a !== void 0 ? _a : this.opts.maxSize, ttl: (_b = opts.ttl) !== null && _b !== void 0 ? _b : this.opts.ttl };
+        this.lru = new fast_lru_1.default(this.opts);
+    }
+    get size() {
+        return this.lru.size;
+    }
+    get maxSize() {
+        return this.opts.maxSize;
+    }
+}
+/**
+ * Account-independent gateway payloads, shared across every {@link Session}.
+ * Keyed by country + method + params — see `Session.gw`.
+ */
+exports.sharedGatewayCache = new CountingCache(2000, 60 * 60000);
+/** In-flight requests for {@link sharedGatewayCache}, so concurrent sessions coalesce. */
+exports.sharedInFlight = new Map();
+/**
+ * Resize the shared cache. Call once at startup — reconfiguring drops its
+ * contents.
+ *
+ * ```ts
+ * configureCache({shared: {maxSize: 20_000, ttl: 30 * 60_000}});
+ * ```
+ */
+const configureCache = (options) => {
+    if (options.shared) {
+        exports.sharedGatewayCache.reconfigure(options.shared);
+        exports.sharedInFlight.clear();
+    }
+};
+exports.configureCache = configureCache;
+/** Drop the shared cache. Per-session caches are untouched (`session.cache.clear()` for those). */
+const clearSharedCaches = () => {
+    exports.sharedGatewayCache.clear();
+    exports.sharedInFlight.clear();
+};
+exports.clearSharedCaches = clearSharedCaches;
+/** A snapshot of shared-cache occupancy and hit rate — for metrics / health endpoints. */
+const cacheStats = () => ({
+    shared: {
+        size: exports.sharedGatewayCache.size,
+        maxSize: exports.sharedGatewayCache.maxSize,
+        hits: exports.sharedGatewayCache.hits,
+        misses: exports.sharedGatewayCache.misses,
+        inFlight: exports.sharedInFlight.size,
+    },
+});
+exports.cacheStats = cacheStats;

package/dist/lib/decrypt.js

@@ -34,6 +34,9 @@ const getBlowfishKey = (trackId) => {
     return key;
 };
 const CHUNK = 2048;
+// Note: memoising the initialised Blowfish schedule per track was measured and
+// rejected — key setup is 39.7µs against 33ms to decrypt an 8 MiB file (0.12%),
+// break-even at ~10 KiB decrypted per key. Not worth the cache.
 /**
  * Decrypt a downloaded track. Deezer applies Blowfish-CBC "stripe" obfuscation:
  * the file is split into 2048-byte chunks and only every third chunk (0, 3, 6…)

package/dist/lib/session.d.ts

@@ -102,7 +102,14 @@ export declare class Session {
      * backoff, and a wall-clock deadline. Throws `DeezerError` on exhaustion.
      */
     request<T>(method: 'GET' | 'POST', url: string, body?: unknown, config?: SessionRequestConfig): Promise<HttpResponse<T>>;
-    /** Single-flight + LRU around a fetcher, keyed per session. */
+    /**
+     * Single-flight + LRU around a fetcher.
+     *
+     * `shared` routes to the process-wide cache and in-flight map instead of this
+     * session's — used for gw methods whose payloads carry nothing account-scoped
+     * (see {@link ACCOUNT_INDEPENDENT_GW}). Two sessions asking for the same album
+     * concurrently then share one request rather than issuing one each.
+     */
     private coalesce;
     /** POST `gateway.php` — the main gw method channel. Coalesced + cached. */
     gw<T = any>(body: Record<string, unknown>, method: string): Promise<T>;

package/dist/lib/session.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setDefaultSession = exports.createSession = exports.initDeezerApi = exports.defaultSession = exports.Session = exports.RETRY_POLICY = exports.DEFAULT_ARL = void 0;
 const delay_1 = __importDefault(require("delay"));
+const caches_1 = require("./caches");
 const errors_1 = require("./errors");
 const fast_lru_1 = __importDefault(require("./fast-lru"));
 const http_1 = require("./http");
@@ -40,6 +41,27 @@ const backoffDelay = (attempt) => {
 };
 /** How long a loaded `deezer.getUserData` payload is trusted before a refresh. */
 const USER_DATA_TTL_MS = 25 * 60 * 1000;
+/**
+ * gw methods whose payloads carry **no account-scoped fields**, so one copy can
+ * serve every session instead of one copy per session.
+ *
+ * The account-scoped field that matters is `TRACK_TOKEN`, and it appears on
+ * exactly two response shapes — `trackType` and `showEpisodeType`. None of the
+ * methods below embed either, so their results are identical for every account
+ * in a given country. Everything else (`song.getData`, `playlist.getSongs`,
+ * `song.getListByAlbum`, `song.getListData`, `episode.getData`, `mobile.*`,
+ * `deezer.pageSearch`, `user_getInfo`, …) stays in the per-session cache.
+ *
+ * The shared key is prefixed with the session's country, so a multi-region
+ * deployment never serves one country's availability view to another.
+ */
+const ACCOUNT_INDEPENDENT_GW = new Set([
+    'album.getData',
+    'artist.getData',
+    'song.getLyrics',
+    'album.getDiscography',
+    'playlist.getData', // playlistInfo — metadata only (playlist.getSongs is NOT shared)
+]);
 /**
  * One Deezer session — owns the `arl`, the HTTP client (and its `sid` /
  * `api_token`), and the account's `license_token` / `country` / streaming
@@ -217,38 +239,52 @@ class Session {
         }
     }
     // ─── Cached request primitives ──────────────────────────────────────────────
-    /** Single-flight + LRU around a fetcher, keyed per session. */
-    coalesce(key, fetcher) {
-        const cached = this.cache.get(key);
+    /**
+     * Single-flight + LRU around a fetcher.
+     *
+     * `shared` routes to the process-wide cache and in-flight map instead of this
+     * session's — used for gw methods whose payloads carry nothing account-scoped
+     * (see {@link ACCOUNT_INDEPENDENT_GW}). Two sessions asking for the same album
+     * concurrently then share one request rather than issuing one each.
+     */
+    coalesce(key, fetcher, shared = false) {
+        const cache = shared ? caches_1.sharedGatewayCache : this.cache;
+        const inFlight = shared ? caches_1.sharedInFlight : this.inFlight;
+        const cached = cache.get(key);
         if (cached) {
             return Promise.resolve(cached);
         }
-        const pending = this.inFlight.get(key);
+        const pending = inFlight.get(key);
         if (pending) {
             return pending;
         }
         const promise = (async () => {
             try {
-                return await fetcher();
+                const value = await fetcher();
+                cache.set(key, value);
+                return value;
             }
             finally {
-                this.inFlight.delete(key);
+                inFlight.delete(key);
             }
         })();
-        this.inFlight.set(key, promise);
+        inFlight.set(key, promise);
         return promise;
     }
     /** POST `gateway.php` — the main gw method channel. Coalesced + cached. */
     gw(body, method) {
-        const key = `gw:${method}:${Object.entries(body).join(':')}`;
+        var _a;
+        const shared = ACCOUNT_INDEPENDENT_GW.has(method);
+        const key = shared
+            ? `${(_a = this.country) !== null && _a !== void 0 ? _a : 'XX'}:gw:${method}:${Object.entries(body).join(':')}`
+            : `gw:${method}:${Object.entries(body).join(':')}`;
         return this.coalesce(key, async () => {
             const { data: { error, results }, } = await this.request('POST', '/gateway.php', body, { params: { method } });
             if (results && Object.keys(results).length > 0) {
-                this.cache.set(key, results);
                 return results;
             }
             throw new errors_1.DeezerError(error);
-        });
+        }, shared);
     }
     /** POST `gw-light.php` — the lighter method channel (search, suggest, …). */
     gwLight(body, method) {
@@ -258,7 +294,6 @@ class Session {
                 params: { method, api_version: '1.0' },
             });
             if (results && Object.keys(results).length > 0) {
-                this.cache.set(key, results);
                 return results;
             }
             throw new errors_1.DeezerError(error);
@@ -272,7 +307,6 @@ class Session {
                 params: { method, ...params },
             });
             if (results && Object.keys(results).length > 0) {
-                this.cache.set(cacheKey, results);
                 return results;
             }
             throw new errors_1.DeezerError(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur-core",
-  "version": "2.13.3",
+  "version": "2.14.0",
   "description": "Deezer API client, cross-service URL resolution, Blowfish track decryption and MP3/FLAC metadata tagging — the engine behind the gerdur CLI.",
   "keywords": [
     "deezer",