@lenne.tech/nest-server 11.32.4 → 11.33.1

package/src/core/modules/file/s3-file.helper.ts

@@ -0,0 +1,209 @@
+import { Types } from 'mongoose';
+import { Readable } from 'stream';
+
+import { CoreS3Service } from '../../common/services/core-s3.service';
+import {
+  ensureFilenameIndex,
+  FileCollection,
+  FileMetadataInfo,
+  findMetadata,
+  findMetadataById,
+  findMetadataByName,
+} from './file-metadata.helper';
+
+/**
+ * Name of the MongoDB collection holding the metadata of S3-stored files.
+ *
+ * S3 itself has no queryable metadata store, so file info (filename, contentType,
+ * length, uploadDate) is kept in this collection — the equivalent of GridFS's
+ * `fs.files`. The object key in the bucket is the string form of `_id`.
+ */
+export const S3_FILES_COLLECTION = 's3-files';
+
+/**
+ * Metadata of a file stored in S3.
+ *
+ * Alias of the shared {@link FileMetadataInfo}, kept as a named export because it is
+ * part of the published API. It used to be a separate, structurally identical
+ * declaration alongside `FilesystemFileInfo` — which is how the two lookup surfaces
+ * drifted apart. One declaration now, so they cannot.
+ */
+export type S3FileInfo = FileMetadataInfo;
+
+/**
+ * Read a stream completely into a buffer
+ */
+export async function streamToBuffer(stream: Readable): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Helper for files stored in S3 with their metadata in MongoDB.
+ *
+ * Counterpart of GridFSHelper: same operations, S3 as the byte store and
+ * `s3-files` as the metadata store.
+ */
+export class S3FileHelper {
+  /**
+   * Store a file in S3 and record its metadata.
+   *
+   * The object is verified via HEAD before the metadata document is written, so
+   * a file info is never returned for bytes that did not arrive (same guarantee
+   * GridFSHelper gives by reading the file document back after the upload).
+   */
+  static async writeFile(
+    s3Service: CoreS3Service,
+    collection: FileCollection,
+    options: {
+      body?: Readable;
+      buffer?: Buffer;
+      contentLength?: number;
+      contentType?: string;
+      filename: string;
+      metadata?: Record<string, any>;
+    },
+  ): Promise<S3FileInfo> {
+    const _id = new Types.ObjectId();
+    const key = _id.toHexString();
+
+    // A stream with a known length streams straight through. Reading it into a Buffer first —
+    // which every caller used to do — materialises the WHOLE file in one process: a 4 GB
+    // resumable upload (well inside the 50 GB default cap) then either throws
+    // "Array buffer allocation failed" or gets the container OOM-killed at 100% progress,
+    // taking every other in-flight request with it.
+    const body = options.body ?? options.buffer;
+    if (!body) {
+      throw new Error('S3FileHelper.writeFile needs either a body stream or a buffer');
+    }
+    await s3Service.putObject(key, body, options.contentType, options.contentLength ?? options.buffer?.length);
+
+    return S3FileHelper.recordFile(s3Service, collection, _id, {
+      contentType: options.contentType,
+      filename: options.filename,
+      length: options.contentLength ?? options.buffer?.length,
+      metadata: options.metadata,
+    });
+  }
+
+  /**
+   * Adopt an object that ALREADY lives in the same S3 endpoint into file storage.
+   *
+   * The bytes are moved by S3 itself (`CopyObject`) rather than pulled into this process and
+   * pushed back out — see {@link CoreS3Service.copyObject}. Used for the TUS S3→S3 hand-off,
+   * where source and destination are two buckets of the same store.
+   *
+   * The metadata document is written by the same {@link S3FileHelper.recordFile} the streaming
+   * path uses, so the two cannot drift into producing differently-shaped file infos.
+   */
+  static async copyFile(
+    s3Service: CoreS3Service,
+    collection: FileCollection,
+    options: {
+      contentLength?: number;
+      contentType?: string;
+      filename: string;
+      metadata?: Record<string, any>;
+      sourceBucket?: string;
+      sourceKey: string;
+    },
+  ): Promise<S3FileInfo> {
+    const _id = new Types.ObjectId();
+    await s3Service.copyObject(options.sourceKey, _id.toHexString(), options.sourceBucket, options.contentType);
+
+    return S3FileHelper.recordFile(s3Service, collection, _id, {
+      contentType: options.contentType,
+      filename: options.filename,
+      length: options.contentLength,
+      metadata: options.metadata,
+    });
+  }
+
+  /**
+   * Verify the object arrived and record its metadata.
+   *
+   * The HEAD before the insert is what keeps a file info from ever describing bytes that are not
+   * there (the guarantee GridFSHelper gets by reading the file document back after the upload).
+   */
+  protected static async recordFile(
+    s3Service: CoreS3Service,
+    collection: FileCollection,
+    _id: Types.ObjectId,
+    options: { contentType?: string; filename: string; length?: number; metadata?: Record<string, any> },
+  ): Promise<S3FileInfo> {
+    if (!(await s3Service.objectExists(_id.toHexString()))) {
+      throw new Error('File uploaded but not found in S3');
+    }
+
+    // On the WRITE path, not the read path: createIndex creates the collection, so
+    // ensuring it when reading gave a GridFS-only deployment an empty `s3-files`.
+    // Here the collection is about to exist anyway. Never throws.
+    await ensureFilenameIndex(collection);
+
+    const fileInfo: S3FileInfo = {
+      _id,
+      contentType: options.contentType,
+      filename: options.filename,
+      length: options.length,
+      metadata: options.metadata,
+      // Records WHERE the bytes went, so a reader never has to probe all three
+      // stores to find out. Legacy documents lack it and are handled by probing.
+      storage: 's3',
+      uploadDate: new Date(),
+    };
+    await collection.insertOne(fileInfo);
+    return fileInfo;
+  }
+
+  /**
+   * Find file metadata by ID
+   */
+  static async findFileById(collection: FileCollection, id: string | Types.ObjectId): Promise<null | S3FileInfo> {
+    return findMetadataById(collection, id);
+  }
+
+  /**
+   * Find file metadata by filename
+   */
+  static async findFileByName(collection: FileCollection, filename: string): Promise<null | S3FileInfo> {
+    return findMetadataByName(collection, filename);
+  }
+
+  /**
+   * Find files with filter and options
+   */
+  static async findFiles(collection: FileCollection, filter: any = {}, options: any = {}): Promise<S3FileInfo[]> {
+    return findMetadata(collection, filter, options);
+  }
+
+  /**
+   * Delete a file from S3 and remove its metadata
+   */
+  static async deleteFile(
+    s3Service: CoreS3Service,
+    collection: FileCollection,
+    id: string | Types.ObjectId,
+  ): Promise<void> {
+    const objectId = typeof id === 'string' ? new Types.ObjectId(id) : id;
+    await s3Service.deleteObject(objectId.toHexString());
+    await collection.deleteOne({ _id: objectId });
+  }
+
+  /**
+   * Get the download stream of a file
+   */
+  static async getStream(s3Service: CoreS3Service, id: string | Types.ObjectId): Promise<Readable> {
+    const objectId = typeof id === 'string' ? new Types.ObjectId(id) : id;
+    return (await s3Service.getObject(objectId.toHexString())).body;
+  }
+
+  /**
+   * Get the content of a file as buffer
+   */
+  static async getBuffer(s3Service: CoreS3Service, id: string | Types.ObjectId): Promise<Buffer> {
+    return streamToBuffer(await S3FileHelper.getStream(s3Service, id));
+  }
+}

package/src/core/modules/hub/README.md

@@ -146,6 +146,54 @@ Three in-memory ring buffers (fixed capacity, no timers, per-app-instance — pa
 - **Queries** — MongoDB driver command monitoring; records value-free query SHAPES (N+1 templates), never values.
   Enabling it opts the driver into `monitorCommands` from `core.module.ts`.
 
+The mailbox (`hub.mailbox`) uses the same buffer.
+
+### Multi-replica
+
+**Without Redis** each buffer is process-local, so a pod only ever shows the logs, traces,
+queries and mails it produced itself. Behind a load balancer that makes the panels look
+lossy — every poll may hit a different pod and show a different slice. Route `/hub` to a
+single replica (sticky routing) if you need a coherent view.
+
+**With Redis** (`ServerOptions.redis`) all four collectors mirror into shared, capped Redis
+lists (`<keyPrefix>:hub:{logs,traces,queries,mailbox}`) and read from there, so every pod
+shows the merged cluster-wide view and "clear" clears it everywhere. Sequence numbers come
+from a shared counter, so the panels' cursor-based polling keeps working across replicas.
+
+Writes are fire-and-forget — the collectors sit in hot paths and their API stays synchronous.
+If Redis is unreachable a read silently falls back to the local buffer (a diagnostics panel
+must not be the thing that breaks), so a partial view during an outage is expected.
+
+#### Cost: Redis write volume scales with your traffic
+
+**Know this before enabling `redis` together with `hub.collectors`.** Every mirrored entry costs a
+3-command `MULTI` (`INCR` the shared sequence counter, `LPUSH` the JSON-serialized entry, `LTRIM`
+back to the buffer capacity). There is **no sampling** — each retained entry is one `MULTI`:
+
+| Collector | One mirror write per                                    | Rough volume                                                         |
+| --------- | ------------------------------------------------------- | -------------------------------------------------------------------- |
+| Logs      | log line at a captured level (`collectors.logs.levels`) | 3 Redis commands × your log rate                                     |
+| Traces    | HTTP request outside the excluded path prefixes         | 3 Redis commands × your request rate                                 |
+| Queries   | monitored MongoDB command (opt-in)                      | 3 Redis commands × your query rate — usually the highest of the four |
+| Mailbox   | outgoing mail                                           | negligible                                                           |
+
+At 500 req/s with request tracing on, that is ~1 500 extra Redis commands per second before the log
+lines are counted. The buffers stay capped in memory (`LTRIM` holds them at the configured
+capacity), so this is a **throughput** cost on the Redis instance, not a growth problem — but it is
+a cost that lands on the same Redis your rate-limit counters, cron leases and subscriptions use.
+
+Two ways to keep it out of the way, both deliberate choices rather than defaults:
+
+- **Give the Hub a dedicated Redis database or instance.** `redis.db` picks a numbered database on
+  the same server (cheap, still one instance's throughput); a separate instance isolates it fully.
+  Either way set `redis.keyPrefix` so environments cannot collide.
+- **Accept the volume knowingly**, and keep `collectors.queries` off (it is opt-in for exactly this
+  reason) unless you are actively profiling. Turning individual collectors off via
+  `hub.collectors` removes their mirror writes entirely.
+
+A single-replica deployment gains nothing from mirroring — leave `redis` unset, or the Hub
+collectors off, and every buffer stays process-local at zero Redis cost.
+
 ## Overrides
 
 ```typescript

package/src/core/modules/hub/core-hub.controller.ts

@@ -97,8 +97,8 @@ export class CoreHubController {
   }
 
   @Get('diagnostics.json')
-  diagnosticsJson(@Res() res: Response): void {
-    this.sendJson(res, this.hubService.getDiagnostics(this.collectorBuffers()));
+  async diagnosticsJson(@Res() res: Response): Promise<void> {
+    this.sendJson(res, this.hubService.getDiagnostics(await this.collectorBuffers()));
   }
 
   @Get('files.json')
@@ -117,17 +117,17 @@ export class CoreHubController {
   }
 
   @Get('mailbox.json')
-  mailboxJson(@Query('since') since: string | undefined, @Res() res: Response): void {
+  async mailboxJson(@Query('since') since: string | undefined, @Res() res: Response): Promise<void> {
     if (!this.mailboxService) {
       this.sendJson(res, { available: false, hint: 'The mailbox is not enabled.' });
       return;
     }
-    this.sendJson(res, this.mailboxService.getMailbox(since !== undefined ? Number(since) : undefined));
+    this.sendJson(res, await this.mailboxService.getMailbox(since !== undefined ? Number(since) : undefined));
   }
 
   @Get('mailbox/:seq/html')
-  mailboxHtml(@Param('seq') seq: string, @Res() res: Response): void {
-    const html = this.mailboxService?.getMailHtml(Number(seq));
+  async mailboxHtml(@Param('seq') seq: string, @Res() res: Response): Promise<void> {
+    const html = await this.mailboxService?.getMailHtml(Number(seq));
     res.set({
       'Cache-Control': 'no-store',
       'Content-Security-Policy': "default-src 'none'; img-src * data:; style-src 'unsafe-inline'; font-src data:",
@@ -143,12 +143,12 @@ export class CoreHubController {
   }
 
   @Get('logs.json')
-  logsJson(@Query('since') since: string | undefined, @Res() res: Response): void {
+  async logsJson(@Query('since') since: string | undefined, @Res() res: Response): Promise<void> {
     if (!this.logBuffer.enabled) {
       this.sendJson(res, { available: false, hint: 'The logs collector is disabled.' });
       return;
     }
-    this.sendJson(res, this.logBuffer.getData(since !== undefined ? Number(since) : undefined));
+    this.sendJson(res, await this.logBuffer.getData(since !== undefined ? Number(since) : undefined));
   }
 
   @Get('models.json')
@@ -167,7 +167,7 @@ export class CoreHubController {
   }
 
   @Get('queries.json')
-  queriesJson(@Res() res: Response): void {
+  async queriesJson(@Res() res: Response): Promise<void> {
     if (!this.queryProfiler.enabled) {
       this.sendJson(res, {
         available: false,
@@ -175,16 +175,16 @@ export class CoreHubController {
       });
       return;
     }
-    this.sendJson(res, this.queryProfiler.getData());
+    this.sendJson(res, await this.queryProfiler.getData());
   }
 
   @Get('traces.json')
-  tracesJson(@Query('since') since: string | undefined, @Res() res: Response): void {
+  async tracesJson(@Query('since') since: string | undefined, @Res() res: Response): Promise<void> {
     if (!this.traceBuffer.enabled) {
       this.sendJson(res, { available: false, hint: 'The traces collector is disabled.' });
       return;
     }
-    this.sendJson(res, this.traceBuffer.getData(since !== undefined ? Number(since) : undefined));
+    this.sendJson(res, await this.traceBuffer.getData(since !== undefined ? Number(since) : undefined));
   }
 
   @Get('routes.json')
@@ -261,10 +261,12 @@ export class CoreHubController {
   }
 
   /** Buffer fill levels for the diagnostics panel. */
-  protected collectorBuffers(): Record<string, { capacity: number; enabled: boolean; size: number }> {
-    const logs = this.logBuffer.getData();
-    const traces = this.traceBuffer.getData();
-    const queries = this.queryProfiler.getData();
+  protected async collectorBuffers(): Promise<Record<string, { capacity: number; enabled: boolean; size: number }>> {
+    const [logs, traces, queries] = await Promise.all([
+      this.logBuffer.getData(),
+      this.traceBuffer.getData(),
+      this.queryProfiler.getData(),
+    ]);
     return {
       logs: { capacity: 0, enabled: this.logBuffer.enabled, size: logs.records.length },
       queries: { capacity: 0, enabled: this.queryProfiler.enabled, size: queries.recent.length },

package/src/core/modules/hub/helpers/hub-mask.helper.ts

@@ -6,12 +6,29 @@
  * keys IN PLACE, which would corrupt the running server config. Cloning here is the guarantee.
  */
 
-/** Key-name heuristics that mark a value as secret. Matched case-insensitively against each key. */
+/**
+ * Key-name heuristics that mark a value as secret. Matched case-insensitively against each key.
+ *
+ * `access[-_]?key` also covers `accessKeyId`: the trailing `(^|[^a-z])key([^a-z]|$)` alternative
+ * does NOT, because the `i` flag makes `[^a-z]` reject an uppercase letter, so `…sKeyI…` fails it.
+ * `s3.secretAccessKey` was already caught by `secret`; the ID was not.
+ */
 const SECRET_KEY_PATTERN =
-  /secret|passwd|password|passphrase|credential|api[-_]?key|access[-_]?token|refresh[-_]?token|private[-_]?key|encryption|\btoken\b|\bpass\b|(^|[^a-z])key([^a-z]|$)/i;
+  /secret|passwd|password|passphrase|credential|api[-_]?key|access[-_]?key|access[-_]?token|refresh[-_]?token|private[-_]?key|encryption|\btoken\b|\bpass\b|(^|[^a-z])key([^a-z]|$)/i;
 
-/** Value-shape heuristic: a connection URI carrying `scheme://user:password@host`. */
-const URI_CREDENTIAL_PATTERN = /^([a-z][a-z0-9+.-]*:\/\/[^/@:\s]+:)([^@/\s]+)(@)/i;
+/**
+ * Value-shape heuristic: a connection URI carrying `scheme://user:password@host`.
+ *
+ * The user part is `*`, not `+`, so the PASSWORD-ONLY form is matched too:
+ * `redis://:password@host` is the canonical Redis URL (Redis < 6 has no username, and
+ * `redis-cli -u`, Heroku Redis and ElastiCache AUTH all emit it). Requiring a non-empty
+ * user printed that shape verbatim in the Hub config panel. `redis.url` became a
+ * first-class option in 11.33.0, so the shape is newly reachable here.
+ *
+ * Still safe against false positives: the password group cannot contain `/`, and the `@`
+ * must follow it immediately — so `http://host:8080/x@y` does not match.
+ */
+const URI_CREDENTIAL_PATTERN = /^([a-z][a-z0-9+.-]*:\/\/[^/@:\s]*:)([^@/\s]+)(@)/i;
 
 const MASK = '***';
 

package/src/core/modules/hub/hub-buffer.ts

@@ -0,0 +1,198 @@
+import { CoreRedisService } from '../../common/services/core-redis.service';
+import { HubBufferEntry, HubRingBuffer } from './hub-ring-buffer';
+
+/** A buffer read, shaped like the `cursor` / `dropped` fields every Hub panel payload carries. */
+export interface HubBufferData<T> {
+  /** Highest assigned seq (`-1` when nothing was ever added) — the client's next cursor. */
+  cursor: number;
+  /** Seq of the oldest retained entry (`-1` when empty) — clients detect eviction gaps against this. */
+  dropped: number;
+  entries: T[];
+}
+
+/**
+ * How long a mirrored buffer survives without being written to, in seconds.
+ *
+ * The list is size-bounded by LTRIM but was never time-bounded, so its contents outlived the
+ * process, the deployment and every Redis snapshot taken in between. That matters because of WHAT
+ * these buffers hold: log lines, full request traces and — in mailbox capture mode — whole
+ * outgoing emails, including verification and password-reset links that are still valid.
+ * Diagnostics are worth keeping for a shift, not forever.
+ */
+const DEFAULT_SHARED_TTL_SECONDS = 24 * 60 * 60;
+
+/**
+ * Entries fetched per poll before the range is widened.
+ *
+ * A Hub panel polls every 5s and normally sees single-digit deltas, while the trace buffer holds
+ * up to 1000 entries — reading and parsing the whole list on every poll of every open tab was
+ * paying 1000× for that delta. The widen-and-retry loop below keeps the read exact when a client
+ * really is further behind.
+ */
+const SHARED_READ_CHUNK = 64;
+
+/**
+ * A collector buffer with an OPTIONAL Redis backing — the single boundary at which the Hub's
+ * diagnostic collectors (logs, traces, queries, mailbox) become multi-replica aware.
+ *
+ * Without Redis this is exactly the process-local {@link HubRingBuffer} and nothing changes.
+ * With Redis (`ServerOptions.redis`) every append is ALSO mirrored into a capped Redis list
+ * (`LPUSH` + `LTRIM` to the same capacity) and reads come from that list, so every pod shows
+ * the merged view instead of only its own slice.
+ *
+ * **Sequence numbers stay meaningful across replicas.** The mirror keeps a companion counter:
+ * the write is `MULTI: INCR seq / LPUSH / LTRIM` and the read is `MULTI: GET seq / LRANGE`,
+ * both atomic, so the newest list element is always `seq = total - 1` and the counter can
+ * never disagree with the list. `clear()` deletes only the list — the counter keeps advancing,
+ * so existing client cursors stay valid, matching `HubRingBuffer.clear()`.
+ *
+ * **Writes are fire-and-forget.** The collectors sit in hot paths (every log line, every
+ * request) and their API towards callers must stay synchronous. A Redis failure is logged at
+ * debug level; reads then fall back to the local buffer rather than failing the panel.
+ */
+export class HubBuffer<T extends HubBufferEntry> {
+  protected readonly listKey: string;
+  protected readonly local: HubRingBuffer<T>;
+  protected readonly redis?: CoreRedisService;
+  protected readonly seqKey: string;
+
+  /** Retention of the mirrored list, refreshed on every append. */
+  protected readonly ttlSeconds: number;
+
+  constructor(capacity: number, name: string, redis?: CoreRedisService, ttlSeconds = DEFAULT_SHARED_TTL_SECONDS) {
+    this.local = new HubRingBuffer<T>(capacity);
+    this.redis = redis?.enabled ? redis : undefined;
+    this.listKey = this.redis?.key('hub', name) ?? '';
+    this.seqKey = this.redis?.key('hub', name, 'seq') ?? '';
+    this.ttlSeconds = ttlSeconds;
+  }
+
+  /** Append an entry. Returns the local entry (with its process-local seq) synchronously. */
+  add(entry: Omit<T, 'seq' | 'timestamp'> & { timestamp?: number }): T {
+    const full = this.local.add(entry);
+    this.mirror('append', (client) =>
+      client
+        .multi()
+        .incr(this.seqKey)
+        .lpush(this.listKey, JSON.stringify(full))
+        .ltrim(this.listKey, 0, this.local.capacity - 1)
+        // Refreshed on every append, so an actively used buffer never expires and an abandoned one
+        // (a scaled-down replica, a torn-down environment) stops being a durable copy of captured
+        // logs, traces and emails. Only the LIST expires — the seq counter must survive so client
+        // cursors stay valid, exactly as they do across clear().
+        .expire(this.listKey, this.ttlSeconds)
+        .exec(),
+    );
+    return full;
+  }
+
+  /** Drop all retained entries — on every replica when Redis-backed. */
+  clear(): void {
+    this.local.clear();
+    this.mirror('clear', (client) => client.del(this.listKey));
+  }
+
+  /**
+   * Run a fire-and-forget mirror write. Swallows BOTH failure modes: `getClient()` throws
+   * synchronously before `CoreRedisService.onModuleInit` has run (log lines during bootstrap
+   * reach the collector earlier than that), and the command itself rejects on an outage.
+   * Neither may escape into a hot logging or request path.
+   */
+  protected mirror(label: string, run: (client: ReturnType<CoreRedisService['getClient']>) => Promise<unknown>): void {
+    if (!this.redis) {
+      return;
+    }
+    const failed = (err: Error): void =>
+      // console, NOT Logger: the Hub logs collector captures Logger output INTO a HubBuffer,
+      // so reporting a mirror failure through Logger re-enters this very method. With a
+      // synchronous throw from getClient() — exactly what happens for log lines emitted
+      // before CoreRedisService has connected — that recurses on one stack until it
+      // overflows, turning a Redis hiccup into a crashed process.
+      console.debug(`Hub buffer ${label} failed (${this.listKey}): ${err.message}`);
+    try {
+      run(this.redis.getClient()).catch(failed);
+    } catch (err) {
+      failed(err as Error);
+    }
+  }
+
+  /** Entries oldest→newest, optionally only those newer than `since`. */
+  async read(since?: number, limit?: number): Promise<HubBufferData<T>> {
+    const shared = this.redis ? await this.readShared(since, limit) : undefined;
+    if (shared) {
+      return shared;
+    }
+    return {
+      cursor: this.local.lastSeq,
+      dropped: this.local.firstRetainedSeq,
+      entries: since === undefined ? this.local.recent(limit) : this.local.since(since, limit),
+    };
+  }
+
+  /**
+   * Read the shared list, or undefined when Redis is unreachable (caller falls back to local).
+   *
+   * The list is newest-first, so the entry with seq `s` sits at index `total - 1 - s` and the
+   * entries a client with cursor `since` still needs are exactly the first `total - 1 - since`.
+   * `total` is only known once the read has happened, so the range starts at a poll-sized chunk
+   * and is widened only when that turns out not to have covered the client's cursor — which keeps
+   * the common poll O(delta) instead of O(capacity) without ever returning a short answer.
+   */
+  protected async readShared(since?: number, limit?: number): Promise<HubBufferData<T> | undefined> {
+    try {
+      const client = this.redis!.getClient();
+      const capacity = this.local.capacity;
+      const cap = Math.min(limit ?? capacity, capacity);
+      // Without a cursor the caller wants the newest window, which LTRIM already bounds by
+      // capacity — so the full range is exact rather than a guess.
+      let want = Math.max(1, since === undefined ? cap : Math.min(cap, SHARED_READ_CHUNK));
+
+      for (let attempt = 0; ; attempt++) {
+        const result = await client
+          .multi()
+          .get(this.seqKey)
+          .lrange(this.listKey, 0, want - 1)
+          .exec();
+        const total = Number(result?.[0]?.[1] ?? 0);
+        const raw = (result?.[1]?.[1] ?? []) as string[];
+        const needed = since === undefined ? cap : Math.max(0, Math.min(cap, total - 1 - since));
+
+        // Enough in hand, or the list simply ended before the bound, or we have widened often
+        // enough — three more round trips is already pathological, and answering with what we
+        // have beats spinning while the panel waits.
+        if (raw.length >= needed || raw.length < want || attempt >= 2) {
+          return this.shape(total, raw, needed);
+        }
+        want = Math.min(Math.max(needed, want * 4), capacity);
+      }
+    } catch (err) {
+      // console, NOT Logger — same re-entrancy as in mirror() above
+      console.debug(`Hub buffer read failed (${this.listKey}), using the local buffer: ${(err as Error).message}`);
+      return undefined;
+    }
+  }
+
+  /**
+   * Turn a newest-first slice into the oldest→newest payload, stamping the SHARED seq over the
+   * per-replica one that was serialized.
+   *
+   * `dropped` is derived from what the slice covers, so for a polling client it reports "nothing
+   * you had was evicted" — and when entries really were evicted (the client is further behind than
+   * the buffer is deep) the slice ends early and the true gap surfaces.
+   */
+  protected shape(total: number, raw: string[], needed: number): HubBufferData<T> {
+    const entries: T[] = [];
+    for (let i = Math.min(raw.length, needed) - 1; i >= 0; i--) {
+      try {
+        entries.push({ ...JSON.parse(raw[i]), seq: total - 1 - i } as T);
+      } catch {
+        // A single unparseable element must not blank the whole panel.
+      }
+    }
+    return {
+      cursor: total - 1,
+      dropped: raw.length ? total - raw.length : -1,
+      entries,
+    };
+  }
+}

package/src/core/modules/hub/services/core-hub-mailbox.service.ts

@@ -1,8 +1,9 @@
-import { Inject, Injectable } from '@nestjs/common';
+import { Inject, Injectable, Optional } from '@nestjs/common';
 
 import { redactSensitiveText } from '../../../common/helpers/logging.helper';
+import { CoreRedisService } from '../../../common/services/core-redis.service';
 import { HUB_CONFIG } from '../hub.constants';
-import { HubRingBuffer } from '../hub-ring-buffer';
+import { HubBuffer } from '../hub-buffer';
 import { HubMailboxData, HubMailboxEntry } from '../interfaces/hub-panels.interface';
 import { IHubCapturedMailInput, IHubEmailCapture, ResolvedHubConfig } from '../interfaces/hub-config.interface';
 
@@ -24,14 +25,17 @@ const TRUNCATION_MARKER = '… [truncated]';
  */
 @Injectable()
 export class CoreHubMailboxService implements IHubEmailCapture {
-  protected readonly buffer: HubRingBuffer<StoredMail>;
+  protected readonly buffer: HubBuffer<StoredMail>;
   protected readonly mode: 'capture' | 'copy';
 
-  constructor(@Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig) {
+  constructor(
+    @Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig,
+    @Optional() protected readonly redis?: CoreRedisService,
+  ) {
     const mailbox =
       config.mailbox === false ? { capacity: 100, maxMailSize: 262144, mode: 'capture' as const } : config.mailbox;
     this.mode = mailbox.mode;
-    this.buffer = new HubRingBuffer<StoredMail>(mailbox.capacity);
+    this.buffer = new HubBuffer<StoredMail>(mailbox.capacity, 'mailbox', redis);
   }
 
   /** Record a mail. Returns true when the caller should SKIP the transport (capture mode). */
@@ -40,7 +44,13 @@ export class CoreHubMailboxService implements IHubEmailCapture {
     return this.mode === 'capture';
   }
 
-  /** Convenience for tests/actions: capture and return the assigned seq. */
+  /**
+   * Convenience for tests/actions: capture and return the assigned seq.
+   *
+   * The returned seq is the PROCESS-LOCAL one. When the mailbox is Redis-backed, the seq the
+   * panels (and {@link CoreHubMailboxService.getMailHtml}) use comes from the shared counter and
+   * will differ — read it from `getMailbox()` instead of assuming this value.
+   */
   captureAndGetSeq(mail: IHubCapturedMailInput): number {
     return this.store(mail).seq;
   }
@@ -51,8 +61,8 @@ export class CoreHubMailboxService implements IHubEmailCapture {
   }
 
   /** Stored HTML (or text fallback) for a mail, for the sandboxed preview iframe. */
-  getMailHtml(seq: number): string | undefined {
-    const mail = this.buffer.recent().find((m) => m.seq === seq);
+  async getMailHtml(seq: number): Promise<string | undefined> {
+    const mail = (await this.buffer.read()).entries.find((m) => m.seq === seq);
     if (!mail) {
       return undefined;
     }
@@ -60,11 +70,11 @@ export class CoreHubMailboxService implements IHubEmailCapture {
   }
 
   /** Mailbox listing (metadata only), oldest→newest, optionally since a cursor. */
-  getMailbox(since?: number): HubMailboxData {
-    const entries = since === undefined ? this.buffer.recent() : this.buffer.since(since);
+  async getMailbox(since?: number): Promise<HubMailboxData> {
+    const { cursor, dropped, entries } = await this.buffer.read(since);
     return {
-      cursor: this.buffer.lastSeq,
-      dropped: this.buffer.firstRetainedSeq,
+      cursor,
+      dropped,
       mails: entries.map(toEntry),
       mode: this.mode,
     };