gerdur-core 2.13.2 → 2.14.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # 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
+
+- **`MIGRATING.md`** — a migration guide from `@soulwax/d-fi-core`: dependency
+  swap, import rename, the one breaking `addTrackTags` change, the local
+  workarounds that can now be deleted (OpenSSL-3 Blowfish fallback, per-track
+  URL-retry loops, manual album-info caching, `code === 4` spin guards), and the
+  faster primitives to adopt (`downloadTrackBuffer`, batch `resolveDownloadUrls`,
+  `streamTrackDownload`, `Session` / `createSession`, `DeezerError`). Linked from
+  the README and shipped in the package.
+
 ## 2.13.2 - 2026-08-31
 
 ### Changed

package/MIGRATING.md

@@ -0,0 +1,249 @@
+# Migrating from `@soulwax/d-fi-core`
+
+`gerdur-core` is the continuation of `@soulwax/d-fi-core`. It was relaunched
+clean-slate on 2026-08-30 — new repo, squashed history, published under a new
+name — so **`gerdur-core@1.0.1` is the last state of `@soulwax/d-fi-core` with
+every identifier renamed**. Everything since (`1.0.1 → 2.13.x`) is additive
+except for one call.
+
+**TL;DR:** rename the dependency and the imports, fix one `addTrackTags` call,
+and you're done. Then delete the workarounds you no longer need and adopt the
+faster primitives below.
+
+---
+
+## 1. Swap the dependency
+
+```bash
+npm rm @soulwax/d-fi-core
+npm i gerdur-core
+```
+
+```jsonc
+// package.json
+-  "@soulwax/d-fi-core": "^x.y.z"
++  "gerdur-core": "^2.13.2"
+```
+
+## 2. Rename imports
+
+Mechanical, whole codebase:
+
+```ts
+- import { … } from '@soulwax/d-fi-core';
++ import { … } from 'gerdur-core';
+
+- import type { trackType } from '@soulwax/d-fi-core/types';
++ import type { trackType } from 'gerdur-core/types';   // the /types subpath name is unchanged
+```
+
+## 3. Fix the one breaking change — `addTrackTags`
+
+The third argument changed from a cover-size `number` to an options object, and
+the return changed from `Buffer` to `{buffer, model}`.
+
+```ts
+// before
+const out: Buffer = await addTrackTags(audio, track, 500);
+
+// after
+const {buffer: out, model} = await addTrackTags(audio, track, {coverSize: 500});
+```
+
+- `coverSize` now defaults to **1000** (was 1000 in code but often passed
+  explicitly) and is clamped to Deezer's real ceiling of **1800**.
+- `model` is the full [`TrackTagModel`](README.md#types) — every resolved field,
+  plus `model.lyricsSynced` (an LRC document, ready for a `.lrc` sidecar).
+
+If you called the lower-level writers directly, they now take a `TrackTagModel`
+instead of `(buffer, track, album, cover)`:
+
+```ts
+// before
+writeMetadataMp3(buffer, track, album, cover);
+writeMetadataFlac(buffer, track, album, size, cover);
+
+// after — build the model, or just call addTrackTags
+import {buildTagModel} from 'gerdur-core';
+const model = buildTagModel({track, album, publicTrack, lyrics, cover, coverSize: 1000, deezerIds: true, includeRank: true});
+writeMetadataMp3(buffer, model);
+writeMetadataFlac(buffer, model, {embedSyncedLyrics: true});
+```
+
+## 4. Everything else compiles unchanged
+
+Same names, same signatures, same return shapes:
+
+- `initDeezerApi(arl)` — still `Promise<string>` (the gateway `SESSION` id); the
+  `arl` must still be exactly 192 characters.
+- `getTrackInfo` · `getTrackInfoPublicApi` · `getLyrics` · `getAlbumInfo` ·
+  `getAlbumInfoPublicApi` · `getAlbumTracks` · `getPlaylistInfo` ·
+  `getPlaylistTracks` · `getArtistInfo` · `getDiscography` · `getProfile` ·
+  `getUser` · `getChannelList` · `getShowInfo` · `getPlaylistChannel`
+- `searchMusic` · `searchAlternative`
+- `getTrackDownloadUrl(track, 1 | 3 | 9)` → `{trackUrl, isEncrypted, fileSize} | null`
+- `decryptDownload(buffer, sngId)` · `getSongFileName(track, quality)`
+- `WrongLicense` · `GeoBlocked`
+- `parseInfo` · `getUrlParts` · `isrc2deezer` · `upc2deezer`
+- the `spotify` · `tidal` · `youtube` converter namespaces
+
+## 5. Delete your workarounds
+
+If your integration carried any of these, remove them — `gerdur-core` handles it
+now:
+
+| Workaround you probably wrote | Now handled by |
+| :--- | :--- |
+| `egoroof-blowfish` / manual `bf-cbc` fallback for `ERR_OSSL_EVP_UNSUPPORTED` on Node 17+ / OpenSSL 3 | native, dependency-free Blowfish since `1.0.2` (~290 MiB/s), verified against the canonical test vectors |
+| per-track `for (const q of [9,3,1]) try { getTrackDownloadUrl(track, q) }` retry loops | `getTrackDownloadUrl` / `resolveDownloadUrls` — media-API 403/429/5xx triggers re-auth + backoff, then a token-free legacy-CDN fallback instead of throwing |
+| a guard against `requestWithRetry` spinning forever on `error.code === 4` | `RETRY_POLICY` — per-error-class attempt caps + a 30 s wall-clock deadline; throws `DeezerError` on exhaustion |
+| a `Map` / object cache of album info while tagging a whole album | LRU + in-flight coalescing in the API layer — each metadata endpoint is hit once per album automatically |
+| `isEncrypted = url.includes('/mobile/')` heuristics | `resolved.isEncrypted` now comes from the media API's `cipher` field — authoritative |
+| clearing a cache yourself when switching `arl` | `initDeezerApi(newArl)` clears the default session cache |
+| buffering the whole file twice (download, then decrypt) | `streamTrackDownload` — constant memory, ~one 2048-byte stripe |
+
+## 6. Adopt the faster primitives
+
+### One-call download
+
+The `getTrackDownloadUrl` → fetch → `decryptDownload` sequence collapses to:
+
+```ts
+import {downloadTrackBuffer} from 'gerdur-core';
+const audio = await downloadTrackBuffer(track, 3); // Buffer | null — URL resolve, retries and decrypt inside
+```
+
+### Batch URL resolution — one request per album, not N
+
+```ts
+import {refreshTrackTokens, resolveDownloadUrls} from 'gerdur-core';
+
+const fresh = await refreshTrackTokens(tracks);                       // one request; refreshes tokens older than ~1 h
+const urls  = await resolveDownloadUrls(fresh, ['FLAC', 'MP3_320', 'MP3_128']);
+// urls[i] = {trackUrl, isEncrypted, fileSize, format, cipher} | null — Deezer returns the best each is licensed for
+```
+
+`resolveDownloadUrls` is a single `media.deezer.com/v1/get_url` POST for the
+whole list — roughly **19× faster** than the old per-track-per-quality loop for a
+14-track album. `refreshTrackTokens` first prevents the classic "long playlist
+starts 403-ing partway through" (tokens expire after ~1 h).
+
+### Streaming — constant memory + resume
+
+```ts
+import {pipeline} from 'stream/promises';
+import {createWriteStream, existsSync, statSync} from 'fs';
+import {streamTrackDownload} from 'gerdur-core';
+
+const {stream, startedAt} = await streamTrackDownload(track, 9, {
+  resumeFrom: existsSync(f) ? statSync(f).size : 0, // snapped to a 2048-byte stripe boundary
+  onProgress: (received, total) => …,
+});
+await pipeline(stream, createWriteStream(f, {flags: startedAt ? 'a' : 'w'}));
+```
+
+Or drop `createDecryptStream(sngId, startChunk)` into a pipeline you already own.
+
+### Multi-account without global state
+
+The module-level `arl` / session / `license_token` are gone into a `Session`:
+
+```ts
+import {createSession} from 'gerdur-core';
+
+const a = await createSession(arlOne);
+const b = await createSession(arlTwo);
+const track = await a.getTrackInfo('3135556');
+const audio = await a.getTrackBuffer(track, 9); // isolated arl, tokens, and response cache
+```
+
+`initDeezerApi` still works — it is now a thin shim over a process-wide default
+session.
+
+### Typed errors
+
+```ts
+import {DeezerError, GeoBlocked, WrongLicense, ExpiredTrackToken} from 'gerdur-core';
+
+try {
+  await downloadTrackBuffer(track, 9);
+} catch (err) {
+  if (err instanceof DeezerError) console.error(err.code, err.keys, err.retryable);
+  if (err instanceof ExpiredTrackToken) { /* re-fetch the track and retry */ }
+}
+```
+
+### Richer tags, fed once
+
+```ts
+const {buffer, model} = await addTrackTags(audio, track, {album, lyrics, cover}); // skip the refetch
+if (model.lyricsSynced) writeFileSync(f.replace(/\.\w+$/, '.lrc'), model.lyricsSynced);
+```
+
+`addTrackTags` now also writes ReplayGain, BPM, real `©` / `℗` lines, the
+original (vs reissue) release date, full engineer / producer / performer credits,
+featured artists, ISRC / UPC, a proper explicit-status enum, Deezer ids, and the
+artist photo as a second embedded image.
+
+### New read surfaces
+
+Mostly no auth required:
+
+- **Search** — `searchPublicApi` / `searchTracks` / `searchAlbums` / … ,
+  `buildAdvancedQuery`, `suggest`, `searchFacets`
+- **Browse** — `getChart`, `getGenres`, `getRelatedArtists`, `getArtistTopTracks`,
+  `getEditorialReleases`, …
+- **Resolve codes** — `getTrackByISRC`, `getAlbumByUPC`
+- **Flow / library / radios** — `getUserFlow`, `getUserFavoriteTracks`,
+  `getRadioTracks`, …
+- **Podcasts** — `getEpisode`, `getShowEpisodes`
+- **Previews** — `getTrackPreview`, `downloadPreview` (licence-free 30 s MP3, no
+  `arl`, no decryption — good for tests / CI)
+
+### Enrichment — covers larger than Deezer's 1800 px cap
+
+```ts
+import {configureMusicBrainz, getCoverArtByISRC, getBuffer, addTrackTags} from 'gerdur-core';
+
+configureMusicBrainz({userAgent: 'my-app/1.0 ( me@example.com )'});
+const coverUrl = await getCoverArtByISRC(track.ISRC, {minSize: 1200});
+if (coverUrl) await addTrackTags(audio, track, {cover: await getBuffer(coverUrl)});
+```
+
+### Shared socket pool
+
+```ts
+import {httpAgent, httpsAgent, getBuffer, getJson, getStream} from 'gerdur-core';
+// hand httpAgent / httpsAgent to your own got/undici calls to reuse the same keep-alive sockets
+```
+
+---
+
+## Before / after
+
+```ts
+// ── before: @soulwax/d-fi-core ───────────────────────────────────────────────
+import got from 'got';
+import {initDeezerApi, getTrackInfo, getTrackDownloadUrl, decryptDownload, addTrackTags} from '@soulwax/d-fi-core';
+
+await initDeezerApi(arl);
+const track = await getTrackInfo('3135556');
+const {trackUrl, isEncrypted} = (await getTrackDownloadUrl(track, 3))!;
+const body = (await got(trackUrl, {responseType: 'buffer'})).body;
+const audio = isEncrypted ? decryptDownload(body, track.SNG_ID) : body;
+const tagged = await addTrackTags(audio, track, 500);          // Buffer
+fs.writeFileSync('out.mp3', tagged);
+
+// ── after: gerdur-core ──────────────────────────────────────────────────────
+import {initDeezerApi, getTrackInfo, downloadTrackBuffer, addTrackTags} from 'gerdur-core';
+
+await initDeezerApi(arl);
+const track = await getTrackInfo('3135556');
+const audio = await downloadTrackBuffer(track, 3);             // fetch + decrypt, retries handled
+const {buffer, model} = await addTrackTags(audio!, track, {coverSize: 500});
+fs.writeFileSync('out.mp3', buffer);
+if (model.lyricsSynced) fs.writeFileSync('out.lrc', model.lyricsSynced);
+```
+
+See [README.md](README.md) for the full guide and the
+[CHANGELOG](CHANGELOG.md) for the version-by-version history.

package/README.md

@@ -27,6 +27,10 @@ It has **no CLI and does no disk I/O** — every function returns data or a
 `Buffer`/stream. The [`gerdur`](https://www.npmjs.com/package/gerdur) package is
 the CLI and the file-writing layer on top.
 
+> **Coming from `@soulwax/d-fi-core`?** `gerdur-core` is its continuation — a
+> near drop-in rename plus one `addTrackTags` change. See
+> **[MIGRATING.md](MIGRATING.md)**.
+
 ---
 
 ## Contents
@@ -51,10 +55,12 @@ 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)
 - [API reference](#api-reference)
+- [Migrating from @soulwax/d-fi-core](#migrating)
 - [The name](#the-name)
 - [Legal](#legal)
 
@@ -599,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,
@@ -754,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>
@@ -762,6 +801,17 @@ import type {
 See the [FAQ](docs/faq.md) and the [`gerdur` CLI](https://www.npmjs.com/package/gerdur)
 for end-to-end usage.
 
+<a id="migrating"></a>
+
+## Migrating from @soulwax/d-fi-core
+
+`gerdur-core` is the continuation of `@soulwax/d-fi-core`. `gerdur-core@1.0.1` is
+that codebase renamed; everything since is additive except a single `addTrackTags`
+signature change. **[MIGRATING.md](MIGRATING.md)** has the exact steps —
+dependency swap, import rename, the one fix, the workarounds you can now delete,
+and the faster primitives (`downloadTrackBuffer`, batch `resolveDownloadUrls`,
+`streamTrackDownload`, `Session`, `DeezerError`) to adopt.
+
 ## The name
 
 **Gerðr** is the jötunn Freyr sends Skírnir riding through a wall of fire to

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.2",
+  "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",
@@ -31,7 +31,8 @@
   "files": [
     "dist/**/*",
     "types/**/*",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "MIGRATING.md"
   ],
   "engines": {
     "node": ">=12"