@aglyn/tenant-data-admin 1.0.0-beta.250 → 1.0.0-beta.253

package/src/lib/server/storage-read-stream.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The listener limit for a Storage response body. The measured peak is 12
+ * (`error`). Room for a few more lets a library patch add one without
+ * bringing the warning back, but stays low enough that a per-chunk or
+ * per-request leak would still cross it within one read.
+ */
+export declare const STORAGE_READ_BODY_LISTENER_BUDGET = 16;
+/** The slice of a Storage `File` a read needs. */
+export interface StorageReadableFile {
+    createReadStream(options?: StorageReadOptions): NodeJS.ReadableStream;
+}
+/** The `createReadStream` options the platform uses. */
+export interface StorageReadOptions {
+    start?: number;
+    end?: number;
+    validation?: 'crc32c' | 'md5' | boolean;
+}
+/**
+ * `file.createReadStream(options)`, with the response body's listener
+ * limit sized to Storage's fixed fan-out (see the module note).
+ */
+export declare function openStorageReadStream(file: StorageReadableFile, options?: StorageReadOptions): NodeJS.ReadableStream;
+/**
+ * The whole object as one Buffer, like `file.download()`, read through
+ * {@link openStorageReadStream}. Rejects when the read fails.
+ */
+export declare function readStorageObject(file: StorageReadableFile, options?: StorageReadOptions): Promise<Buffer>;

package/src/lib/server/storage-read-stream.js

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Reading a Cloud Storage object without a false leak warning (AGL-3795).
+ *
+ * ## Why every Storage read used to warn
+ *
+ * `File#createReadStream` (and `File#download`, which is built on it) hands
+ * the HTTP response body, a node-fetch `PassThrough`, to three `pipeline`s at
+ * once:
+ *
+ * 1. node-fetch's own, from the socket into the body;
+ * 2. teeny-request's, from the body into the retry-request stream, which
+ *    Storage only `resume()`s;
+ * 3. Storage's, from the body into the read stream it returns.
+ *
+ * On Node 24 those add 12 `error` listeners and 11 `close` listeners to the
+ * body. Node's limit is 10, so `MaxListenersExceededWarning` fired once per
+ * read on every route that touches Storage. The count is a fixed fan-out: it
+ * is the same for a 1-chunk and a 200-chunk object and for the first and the
+ * hundredth request, and the listeners go away with the body when the read
+ * ends. So nothing accumulates. The warning is a heuristic tripping on a
+ * library's wiring.
+ *
+ * ## What this does
+ *
+ * Storage re-emits the body as the read stream's `response` event before it
+ * or teeny-request attaches its `pipeline`. At that point, only on that one
+ * per-request body, the limit is raised to {@link STORAGE_READ_BODY_LISTENER_BUDGET}:
+ * the measured fan-out plus a little headroom. The process default stays at
+ * 10, so a real leak anywhere still warns, and so does a real leak on this
+ * body once it grows past the budget.
+ */ import { buffer } from "node:stream/consumers";
+/**
+ * The listener limit for a Storage response body. The measured peak is 12
+ * (`error`). Room for a few more lets a library patch add one without
+ * bringing the warning back, but stays low enough that a per-chunk or
+ * per-request leak would still cross it within one read.
+ */ export const STORAGE_READ_BODY_LISTENER_BUDGET = 16;
+/** Raises the limit on the response body Storage just received. */ function budgetResponseBody(body) {
+    var _ref;
+    const emitter = body;
+    if (typeof (emitter == null ? void 0 : emitter.setMaxListeners) !== 'function') return;
+    const current = (_ref = emitter.getMaxListeners == null ? void 0 : emitter.getMaxListeners.call(emitter)) != null ? _ref : 0;
+    // 0 means unlimited, and a higher limit was set on purpose by someone else.
+    if (current === 0 || current >= STORAGE_READ_BODY_LISTENER_BUDGET) return;
+    emitter.setMaxListeners(STORAGE_READ_BODY_LISTENER_BUDGET);
+}
+/**
+ * `file.createReadStream(options)`, with the response body's listener
+ * limit sized to Storage's fixed fan-out (see the module note).
+ */ export function openStorageReadStream(file, options = {}) {
+    const stream = file.createReadStream(options);
+    stream.once('response', budgetResponseBody);
+    return stream;
+}
+/**
+ * The whole object as one Buffer, like `file.download()`, read through
+ * {@link openStorageReadStream}. Rejects when the read fails.
+ */ export async function readStorageObject(file, options = {}) {
+    return buffer(openStorageReadStream(file, options));
+}
+
+//# sourceMappingURL=storage-read-stream.js.map

package/src/lib/server/storage-read-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/storage-read-stream.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Reading a Cloud Storage object without a false leak warning (AGL-3795).\n *\n * ## Why every Storage read used to warn\n *\n * `File#createReadStream` (and `File#download`, which is built on it) hands\n * the HTTP response body, a node-fetch `PassThrough`, to three `pipeline`s at\n * once:\n *\n * 1. node-fetch's own, from the socket into the body;\n * 2. teeny-request's, from the body into the retry-request stream, which\n *    Storage only `resume()`s;\n * 3. Storage's, from the body into the read stream it returns.\n *\n * On Node 24 those add 12 `error` listeners and 11 `close` listeners to the\n * body. Node's limit is 10, so `MaxListenersExceededWarning` fired once per\n * read on every route that touches Storage. The count is a fixed fan-out: it\n * is the same for a 1-chunk and a 200-chunk object and for the first and the\n * hundredth request, and the listeners go away with the body when the read\n * ends. So nothing accumulates. The warning is a heuristic tripping on a\n * library's wiring.\n *\n * ## What this does\n *\n * Storage re-emits the body as the read stream's `response` event before it\n * or teeny-request attaches its `pipeline`. At that point, only on that one\n * per-request body, the limit is raised to {@link STORAGE_READ_BODY_LISTENER_BUDGET}:\n * the measured fan-out plus a little headroom. The process default stays at\n * 10, so a real leak anywhere still warns, and so does a real leak on this\n * body once it grows past the budget.\n */\n\nimport type { Readable } from 'node:stream'\nimport { buffer } from 'node:stream/consumers'\n\n/**\n * The listener limit for a Storage response body. The measured peak is 12\n * (`error`). Room for a few more lets a library patch add one without\n * bringing the warning back, but stays low enough that a per-chunk or\n * per-request leak would still cross it within one read.\n */\nexport const STORAGE_READ_BODY_LISTENER_BUDGET = 16\n\n/** The slice of a Storage `File` a read needs. */\nexport interface StorageReadableFile {\n  createReadStream(options?: StorageReadOptions): NodeJS.ReadableStream\n}\n\n/** The `createReadStream` options the platform uses. */\nexport interface StorageReadOptions {\n  start?: number\n  end?: number\n  validation?: 'crc32c' | 'md5' | boolean\n}\n\n/** Raises the limit on the response body Storage just received. */\nfunction budgetResponseBody(body: unknown): void {\n  const emitter = body as\n    | { getMaxListeners?: () => number; setMaxListeners?: (n: number) => unknown }\n    | null\n    | undefined\n  if (typeof emitter?.setMaxListeners !== 'function') return\n  const current = emitter.getMaxListeners?.() ?? 0\n  // 0 means unlimited, and a higher limit was set on purpose by someone else.\n  if (current === 0 || current >= STORAGE_READ_BODY_LISTENER_BUDGET) return\n  emitter.setMaxListeners(STORAGE_READ_BODY_LISTENER_BUDGET)\n}\n\n/**\n * `file.createReadStream(options)`, with the response body's listener\n * limit sized to Storage's fixed fan-out (see the module note).\n */\nexport function openStorageReadStream(\n  file: StorageReadableFile,\n  options: StorageReadOptions = {},\n): NodeJS.ReadableStream {\n  const stream = file.createReadStream(options)\n  stream.once('response', budgetResponseBody)\n  return stream\n}\n\n/**\n * The whole object as one Buffer, like `file.download()`, read through\n * {@link openStorageReadStream}. Rejects when the read fails.\n */\nexport async function readStorageObject(\n  file: StorageReadableFile,\n  options: StorageReadOptions = {},\n): Promise<Buffer> {\n  return buffer(openStorageReadStream(file, options) as Readable)\n}\n"],"names":["buffer","STORAGE_READ_BODY_LISTENER_BUDGET","budgetResponseBody","body","emitter","setMaxListeners","current","getMaxListeners","openStorageReadStream","file","options","stream","createReadStream","once","readStorageObject"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC,GAGD,SAASA,MAAM,QAAQ,wBAAuB;AAE9C;;;;;CAKC,GACD,OAAO,MAAMC,oCAAoC,GAAE;AAcnD,iEAAiE,GACjE,SAASC,mBAAmBC,IAAa;;IACvC,MAAMC,UAAUD;IAIhB,IAAI,QAAOC,2BAAAA,QAASC,eAAe,MAAK,YAAY;IACpD,MAAMC,kBAAUF,QAAQG,eAAe,oBAAvBH,QAAQG,eAAe,MAAvBH,2BAA+B;IAC/C,4EAA4E;IAC5E,IAAIE,YAAY,KAAKA,WAAWL,mCAAmC;IACnEG,QAAQC,eAAe,CAACJ;AAC1B;AAEA;;;CAGC,GACD,OAAO,SAASO,sBACdC,IAAyB,EACzBC,UAA8B,CAAC,CAAC;IAEhC,MAAMC,SAASF,KAAKG,gBAAgB,CAACF;IACrCC,OAAOE,IAAI,CAAC,YAAYX;IACxB,OAAOS;AACT;AAEA;;;CAGC,GACD,OAAO,eAAeG,kBACpBL,IAAyB,EACzBC,UAA8B,CAAC,CAAC;IAEhC,OAAOV,OAAOQ,sBAAsBC,MAAMC;AAC5C"}