@naturalcycles/backend-lib 9.63.1 → 9.65.0

package/dist/server/eventLoop.util.d.ts

@@ -5,6 +5,11 @@ import type { Integer, NonNegativeInteger, NumberOfMilliseconds, NumberOfPercent
  * Also, monitors GC performance.
  * Once per `measureInterval` sends a callback with stats.
  *
+ * On Node >=24.19 (or >=26.5) delays are sampled once per event loop iteration
+ * (`samplePerIteration`), so stats reflect true per-iteration delay:
+ * expect p50/mean near 0 on a healthy service, instead of the ~`resolution` baseline
+ * reported by older interval-based sampling.
+ *
  * @experimental
  */
 export declare class EventLoopMonitor {
@@ -22,10 +27,6 @@ export declare class EventLoopMonitor {
     stop(): void;
 }
 export interface EventLoopMonitorCfg {
-    /**
-     * Defaults to 20.
-     */
-    resolution?: NumberOfMilliseconds;
     /**
      * Defaults to 60_000 ms
      */

package/dist/server/eventLoop.util.js

@@ -21,12 +21,24 @@ import { monitorEventLoopDelay, performance, PerformanceObserver } from 'node:pe
  * Also, monitors GC performance.
  * Once per `measureInterval` sends a callback with stats.
  *
+ * On Node >=24.19 (or >=26.5) delays are sampled once per event loop iteration
+ * (`samplePerIteration`), so stats reflect true per-iteration delay:
+ * expect p50/mean near 0 on a healthy service, instead of the ~`resolution` baseline
+ * reported by older interval-based sampling.
+ *
  * @experimental
  */
 export class EventLoopMonitor {
     constructor(cfg = {}) {
-        const { resolution = 20, measureInterval = 60_000 } = cfg;
-        this.eld = monitorEventLoopDelay({ resolution });
+        const { measureInterval = 60_000 } = cfg;
+        const eldOptions = {
+            // Node >=24.19 / >=26.5: sample once per event loop iteration (uv_prepare/uv_check hooks),
+            // which measures actual per-iteration delay instead of timer jitter.
+            // More accurate (no `resolution` offset baked into every percentile) and cheaper.
+            // Older Node silently ignores this option and falls back to interval-based sampling.
+            samplePerIteration: true,
+        };
+        this.eld = monitorEventLoopDelay(eldOptions);
         this.eld.enable();
         this.lastElu = performance.eventLoopUtilization();
         this.po = new PerformanceObserver(list => {

package/dist/upload/getUploadedFiles.d.ts

@@ -0,0 +1,43 @@
+import type { NumberOfBytes } from '@naturalcycles/js-lib/types';
+import type { BackendRequest } from '../server/server.model.js';
+/**
+ * Parses a `multipart/form-data` request body (on top of `busboy`), populates `req.body` with the
+ * form fields, and returns the requested files keyed by their form field name:
+ *
+ *     const { csv } = await getUploadedFiles(req, { files: ['csv'] })
+ *     const { csv, avatar } = await getUploadedFiles(req, {
+ *       files: ['csv'],            // required   -> UploadedFile
+ *       optionalFiles: ['avatar'], // optional   -> UploadedFile | undefined
+ *     })
+ *
+ * `files` are required: each is asserted to be present and non-empty (throws 400 otherwise).
+ * `optionalFiles` are returned as `UploadedFile | undefined` — `undefined` when the field is
+ * absent or empty (e.g. a blank file input), so "optional" is genuinely optional.
+ *
+ * Throws 413 as soon as ANY uploaded file exceeds `maxFileSize` bytes (default: 10 MB), aborting
+ * the parse immediately without buffering the rest of the body.
+ *
+ * Meant to be called from inside a request handler, AFTER authentication — so an
+ * unauthenticated/unauthorized request is rejected before its (potentially large) multipart body
+ * is buffered into memory.
+ */
+export declare function getUploadedFiles<const FILENAMES extends string = never, const OPTIONAL_FILENAMES extends string = never>(req: BackendRequest, opt: {
+    files?: readonly FILENAMES[];
+    optionalFiles?: readonly OPTIONAL_FILENAMES[];
+    maxFileSize?: NumberOfBytes;
+}): Promise<Record<FILENAMES, UploadedFile> & Record<OPTIONAL_FILENAMES, UploadedFile | undefined>>;
+/**
+ * A single uploaded file, buffered in memory.
+ */
+export interface UploadedFile {
+    /** Original filename from the client. */
+    name: string;
+    /** Content-Type of the file part. */
+    mimeType: string;
+    /** Content-Transfer-Encoding of the file part. */
+    encoding: string;
+    /** File contents. */
+    data: Buffer;
+    /** Size of `data` in bytes. */
+    size: NumberOfBytes;
+}

package/dist/upload/getUploadedFiles.js

@@ -0,0 +1,94 @@
+import { _assert, AppError } from '@naturalcycles/js-lib/error';
+import busboy from 'busboy';
+/**
+ * Parses a `multipart/form-data` request body (on top of `busboy`), populates `req.body` with the
+ * form fields, and returns the requested files keyed by their form field name:
+ *
+ *     const { csv } = await getUploadedFiles(req, { files: ['csv'] })
+ *     const { csv, avatar } = await getUploadedFiles(req, {
+ *       files: ['csv'],            // required   -> UploadedFile
+ *       optionalFiles: ['avatar'], // optional   -> UploadedFile | undefined
+ *     })
+ *
+ * `files` are required: each is asserted to be present and non-empty (throws 400 otherwise).
+ * `optionalFiles` are returned as `UploadedFile | undefined` — `undefined` when the field is
+ * absent or empty (e.g. a blank file input), so "optional" is genuinely optional.
+ *
+ * Throws 413 as soon as ANY uploaded file exceeds `maxFileSize` bytes (default: 10 MB), aborting
+ * the parse immediately without buffering the rest of the body.
+ *
+ * Meant to be called from inside a request handler, AFTER authentication — so an
+ * unauthenticated/unauthorized request is rejected before its (potentially large) multipart body
+ * is buffered into memory.
+ */
+export async function getUploadedFiles(req, opt) {
+    const { files: requiredNames = [], optionalFiles = [], maxFileSize = 10 * MB } = opt;
+    const uploadedFiles = await parseMultipart(req, maxFileSize);
+    const result = {};
+    for (const name of requiredNames) {
+        const file = uploadedFiles[name];
+        _assert(file, `Uploaded file "${name}" is missing`, { backendResponseStatusCode: 400 });
+        _assert(file.size > 0, `Uploaded file "${name}" is empty`, { backendResponseStatusCode: 400 });
+        result[name] = file;
+    }
+    for (const name of optionalFiles) {
+        const file = uploadedFiles[name];
+        // Absent or empty (e.g. a blank file input) is treated as "not provided".
+        result[name] = file && file.size > 0 ? file : undefined;
+    }
+    return result;
+}
+/**
+ * Streams the request through busboy, buffering each file into memory and collecting the form
+ * fields onto `req.body`. Resolves with the uploaded files keyed by their form field name.
+ *
+ * Rejects (aborting the parse) the moment a file exceeds `maxFileSize`.
+ */
+async function parseMultipart(req, maxFileSize) {
+    return new Promise((resolve, reject) => {
+        const files = {};
+        const body = {};
+        let bb;
+        try {
+            bb = busboy({ headers: req.headers, limits: { fileSize: maxFileSize } });
+        }
+        catch {
+            // Not a multipart request (or malformed Content-Type) — no files to parse
+            resolve(files);
+            return;
+        }
+        bb.on('field', (name, value) => {
+            body[name] = value;
+        });
+        bb.on('file', (name, stream, info) => {
+            const chunks = [];
+            stream.on('data', (chunk) => chunks.push(chunk));
+            // Abort as soon as the size limit is hit: stop feeding busboy and reject right away,
+            // rather than buffering the whole over-limit body and reporting it at the end.
+            stream.on('limit', () => {
+                req.unpipe(bb);
+                req.resume(); // drain the remainder so the connection can close cleanly
+                reject(new AppError(`Uploaded file "${name}" exceeds the size limit of ${maxFileSize} bytes`, {
+                    backendResponseStatusCode: 413,
+                }));
+            });
+            stream.on('close', () => {
+                const data = Buffer.concat(chunks);
+                files[name] = {
+                    name: info.filename,
+                    mimeType: info.mimeType,
+                    encoding: info.encoding,
+                    data,
+                    size: data.length,
+                };
+            });
+        });
+        bb.on('error', reject);
+        bb.on('close', () => {
+            req.body = body;
+            resolve(files);
+        });
+        req.pipe(bb);
+    });
+}
+const MB = 1024 * 1024;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.63.1",
+  "version": "9.65.0",
   "dependencies": {
     "@naturalcycles/db-lib": "^10",
     "@naturalcycles/js-lib": "^15",
@@ -14,6 +14,7 @@
     "@types/on-finished": "^2",
     "@types/on-headers": "^1",
     "@types/vary": "^1",
+    "busboy": "^1",
     "compressible": "^2",
     "cookie-parser": "^1",
     "cors": "^2",
@@ -43,7 +44,8 @@
   },
   "devDependencies": {
     "@sentry/node-core": "^10",
-    "typescript": "rc",
+    "@types/busboy": "^1",
+    "typescript": "^7",
     "fastify": "^5",
     "@naturalcycles/dev-lib": "0.0.0"
   },
@@ -55,6 +57,7 @@
     "./deploy": "./dist/deploy/index.js",
     "./deploy/*.js": "./dist/deploy/*.js",
     "./express/*.js": "./dist/express/*.js",
+    "./upload": "./dist/upload/getUploadedFiles.js",
     "./validateRequest": "./dist/validation/ajv/validateRequest.js",
     "./onFinished": "./dist/onFinished.js",
     "./testing": "./dist/testing/index.js"

package/src/server/eventLoop.util.ts

@@ -1,4 +1,8 @@
-import type { EventLoopUtilization, IntervalHistogram } from 'node:perf_hooks'
+import type {
+  EventLoopMonitorOptions,
+  EventLoopUtilization,
+  IntervalHistogram,
+} from 'node:perf_hooks'
 import { monitorEventLoopDelay, performance, PerformanceObserver } from 'node:perf_hooks'
 import type {
   Integer,
@@ -30,13 +34,25 @@ import type {
  * Also, monitors GC performance.
  * Once per `measureInterval` sends a callback with stats.
  *
+ * On Node >=24.19 (or >=26.5) delays are sampled once per event loop iteration
+ * (`samplePerIteration`), so stats reflect true per-iteration delay:
+ * expect p50/mean near 0 on a healthy service, instead of the ~`resolution` baseline
+ * reported by older interval-based sampling.
+ *
  * @experimental
  */
 export class EventLoopMonitor {
   constructor(cfg: EventLoopMonitorCfg = {}) {
-    const { resolution = 20, measureInterval = 60_000 } = cfg
-
-    this.eld = monitorEventLoopDelay({ resolution })
+    const { measureInterval = 60_000 } = cfg
+
+    const eldOptions: EventLoopMonitorOptions2 = {
+      // Node >=24.19 / >=26.5: sample once per event loop iteration (uv_prepare/uv_check hooks),
+      // which measures actual per-iteration delay instead of timer jitter.
+      // More accurate (no `resolution` offset baked into every percentile) and cheaper.
+      // Older Node silently ignores this option and falls back to interval-based sampling.
+      samplePerIteration: true,
+    }
+    this.eld = monitorEventLoopDelay(eldOptions)
     this.eld.enable()
 
     this.lastElu = performance.eventLoopUtilization()
@@ -107,11 +123,6 @@ export class EventLoopMonitor {
 }
 
 export interface EventLoopMonitorCfg {
-  /**
-   * Defaults to 20.
-   */
-  resolution?: NumberOfMilliseconds
-
   /**
    * Defaults to 60_000 ms
    */
@@ -156,3 +167,11 @@ export interface EventLoopStats {
    */
   gcCPU: Integer
 }
+
+/**
+ * Extends the Node types with `samplePerIteration` (added in Node 24.19 / 26.5).
+ * Remove once @types/node declares it.
+ */
+interface EventLoopMonitorOptions2 extends EventLoopMonitorOptions {
+  samplePerIteration?: boolean
+}

package/src/upload/getUploadedFiles.ts

@@ -0,0 +1,140 @@
+import { _assert, AppError } from '@naturalcycles/js-lib/error'
+import type { NumberOfBytes } from '@naturalcycles/js-lib/types'
+import busboy from 'busboy'
+import type { Busboy, FileInfo } from 'busboy'
+import type { BackendRequest } from '../server/server.model.js'
+
+/**
+ * Parses a `multipart/form-data` request body (on top of `busboy`), populates `req.body` with the
+ * form fields, and returns the requested files keyed by their form field name:
+ *
+ *     const { csv } = await getUploadedFiles(req, { files: ['csv'] })
+ *     const { csv, avatar } = await getUploadedFiles(req, {
+ *       files: ['csv'],            // required   -> UploadedFile
+ *       optionalFiles: ['avatar'], // optional   -> UploadedFile | undefined
+ *     })
+ *
+ * `files` are required: each is asserted to be present and non-empty (throws 400 otherwise).
+ * `optionalFiles` are returned as `UploadedFile | undefined` — `undefined` when the field is
+ * absent or empty (e.g. a blank file input), so "optional" is genuinely optional.
+ *
+ * Throws 413 as soon as ANY uploaded file exceeds `maxFileSize` bytes (default: 10 MB), aborting
+ * the parse immediately without buffering the rest of the body.
+ *
+ * Meant to be called from inside a request handler, AFTER authentication — so an
+ * unauthenticated/unauthorized request is rejected before its (potentially large) multipart body
+ * is buffered into memory.
+ */
+export async function getUploadedFiles<
+  const FILENAMES extends string = never,
+  const OPTIONAL_FILENAMES extends string = never,
+>(
+  req: BackendRequest,
+  opt: {
+    files?: readonly FILENAMES[]
+    optionalFiles?: readonly OPTIONAL_FILENAMES[]
+    maxFileSize?: NumberOfBytes
+  },
+): Promise<Record<FILENAMES, UploadedFile> & Record<OPTIONAL_FILENAMES, UploadedFile | undefined>> {
+  const { files: requiredNames = [], optionalFiles = [], maxFileSize = 10 * MB } = opt
+
+  const uploadedFiles = await parseMultipart(req, maxFileSize)
+  const result: Record<string, UploadedFile | undefined> = {}
+
+  for (const name of requiredNames) {
+    const file = uploadedFiles[name]
+    _assert(file, `Uploaded file "${name}" is missing`, { backendResponseStatusCode: 400 })
+    _assert(file.size > 0, `Uploaded file "${name}" is empty`, { backendResponseStatusCode: 400 })
+    result[name] = file
+  }
+
+  for (const name of optionalFiles) {
+    const file = uploadedFiles[name]
+    // Absent or empty (e.g. a blank file input) is treated as "not provided".
+    result[name] = file && file.size > 0 ? file : undefined
+  }
+
+  return result as Record<FILENAMES, UploadedFile> &
+    Record<OPTIONAL_FILENAMES, UploadedFile | undefined>
+}
+
+/**
+ * Streams the request through busboy, buffering each file into memory and collecting the form
+ * fields onto `req.body`. Resolves with the uploaded files keyed by their form field name.
+ *
+ * Rejects (aborting the parse) the moment a file exceeds `maxFileSize`.
+ */
+async function parseMultipart(
+  req: BackendRequest,
+  maxFileSize: NumberOfBytes,
+): Promise<Record<string, UploadedFile>> {
+  return new Promise((resolve, reject) => {
+    const files: Record<string, UploadedFile> = {}
+    const body: Record<string, string> = {}
+
+    let bb: Busboy
+    try {
+      bb = busboy({ headers: req.headers, limits: { fileSize: maxFileSize } })
+    } catch {
+      // Not a multipart request (or malformed Content-Type) — no files to parse
+      resolve(files)
+      return
+    }
+
+    bb.on('field', (name, value) => {
+      body[name] = value
+    })
+
+    bb.on('file', (name: string, stream, info: FileInfo) => {
+      const chunks: Buffer[] = []
+      stream.on('data', (chunk: Buffer) => chunks.push(chunk))
+      // Abort as soon as the size limit is hit: stop feeding busboy and reject right away,
+      // rather than buffering the whole over-limit body and reporting it at the end.
+      stream.on('limit', () => {
+        req.unpipe(bb)
+        req.resume() // drain the remainder so the connection can close cleanly
+        reject(
+          new AppError(`Uploaded file "${name}" exceeds the size limit of ${maxFileSize} bytes`, {
+            backendResponseStatusCode: 413,
+          }),
+        )
+      })
+      stream.on('close', () => {
+        const data = Buffer.concat(chunks)
+        files[name] = {
+          name: info.filename,
+          mimeType: info.mimeType,
+          encoding: info.encoding,
+          data,
+          size: data.length,
+        }
+      })
+    })
+
+    bb.on('error', reject)
+    bb.on('close', () => {
+      req.body = body
+      resolve(files)
+    })
+
+    req.pipe(bb)
+  })
+}
+
+const MB = 1024 * 1024
+
+/**
+ * A single uploaded file, buffered in memory.
+ */
+export interface UploadedFile {
+  /** Original filename from the client. */
+  name: string
+  /** Content-Type of the file part. */
+  mimeType: string
+  /** Content-Transfer-Encoding of the file part. */
+  encoding: string
+  /** File contents. */
+  data: Buffer
+  /** Size of `data` in bytes. */
+  size: NumberOfBytes
+}