@lenne.tech/nest-server 11.33.1 → 11.34.1

package/src/core/common/helpers/gridfs.helper.ts

@@ -72,7 +72,22 @@ export class GridFSHelper {
   }
 
   /**
-   * Write a file to GridFS from a stream
+   * Write a file to GridFS from a stream.
+   *
+   * **The SOURCE stream needs its own error handler.** `pipe()` does not forward
+   * errors, so an error on `stream` used to have no listener at all: Node turns an
+   * unhandled `'error'` event into an uncaught exception, which takes the whole
+   * process down. That is reachable from ordinary traffic — a client that aborts a
+   * GraphQL upload mid-body errors the capacitor stream — and it was
+   * driver-conditional: the same abort is a rejected promise under the S3 driver
+   * (`streamToBuffer` throws) and under the filesystem driver (`pipeline()`
+   * forwards both ends), and a process crash under GridFS, the pre-11.33 default.
+   * The migration helper's `uploadFileToGridFS()` already carried this handler; the
+   * one on the request path did not.
+   *
+   * The partial upload is aborted rather than left behind: without it the failed
+   * write keeps its chunks in `fs.chunks` with no `fs.files` document naming them,
+   * which nothing can ever find or clean up.
    */
   static writeFileFromStream(
     bucket: GridFSBucket,
@@ -90,8 +105,37 @@ export class GridFSHelper {
         metadata,
       });
 
-      uploadStream.on('error', (error) => {
+      // One settle guard for all three paths: aborting a write stream can itself
+      // emit, and a second rejection after a resolve would otherwise be silent.
+      let settled = false;
+      const fail = (error: Error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
         reject(error);
+      };
+      const succeed = (fileInfo: GridFSFileInfo) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        resolve(fileInfo);
+      };
+
+      stream.on('error', (error) => {
+        // Discard the chunks already written — see the note above.
+        Promise.resolve(uploadStream.abort?.()).catch(() => undefined);
+        fail(error);
+      });
+
+      uploadStream.on('error', (error) => {
+        // `pipe()` only unpipes on a destination error; the source would stay open,
+        // holding a GridFS read cursor or an upload capacitor for nothing.
+        if (!stream.destroyed) {
+          stream.destroy();
+        }
+        fail(error);
       });
 
       uploadStream.on('finish', () => {
@@ -101,12 +145,12 @@ export class GridFSHelper {
           .toArray()
           .then((files) => {
             if (files && files.length > 0) {
-              resolve(GridFSHelper.normalizeFileInfo(files[0]));
+              succeed(GridFSHelper.normalizeFileInfo(files[0]));
             } else {
-              reject(new Error('File uploaded but metadata not found'));
+              fail(new Error('File uploaded but metadata not found'));
             }
           })
-          .catch(reject);
+          .catch(fail);
       });
 
       stream.pipe(uploadStream);
@@ -162,13 +206,54 @@ export class GridFSHelper {
   }
 
   /**
-   * Find files with filter and options
+   * Find files with filter and options.
+   *
+   * The `contentType` key is rewritten to `metadata.contentType` in BOTH the
+   * filter and the sort — the exact mirror image of what
+   * {@link GridFSHelper.normalizeFileInfo} does on the way out.
+   *
+   * Without it, `contentType` was the one field where the three storage drivers
+   * were not equivalent: `s3-files` / `filesystem-files` carry it at the root of
+   * the document, GridFS keeps it inside `metadata` (the driver dropped the
+   * top-level option in mongodb 7). A `findFileInfo()` filtered on `contentType`
+   * therefore matched every S3 / filesystem file and NO GridFS file — silently
+   * returning nothing at all on the default driver, and silently dropping the
+   * pre-switch files on any other. That is exactly the "switching drivers is
+   * forward-only, no migration" promise failing for one field.
    */
   static async findFiles(bucket: GridFSBucket, filter: any = {}, options: any = {}): Promise<GridFSFileInfo[]> {
-    const files = await bucket.find(filter, options).toArray();
+    const query = GridFSHelper.mapContentTypeKeys(filter);
+    const findOptions =
+      options && options.sort ? { ...options, sort: GridFSHelper.mapContentTypeKeys(options.sort) } : options;
+    const files = await bucket.find(query, findOptions).toArray();
     return files.map((file) => GridFSHelper.normalizeFileInfo(file));
   }
 
+  /**
+   * Rename a top-level `contentType` key to `metadata.contentType`, recursing
+   * through the logical operators `generateFilterQuery()` can emit.
+   *
+   * Deliberately narrow: only that one key is touched, only where it names a
+   * field, and an already-qualified `metadata.contentType` is left alone. Nothing
+   * else about the query is interpreted.
+   */
+  private static mapContentTypeKeys(value: any): any {
+    if (Array.isArray(value)) {
+      return value.map((entry) => GridFSHelper.mapContentTypeKeys(entry));
+    }
+    if (!value || typeof value !== 'object' || value instanceof RegExp || value instanceof Date) {
+      return value;
+    }
+    const mapped: Record<string, any> = {};
+    for (const [key, entry] of Object.entries(value)) {
+      // Only the logical operators hold nested FIELD maps; `$gt`, `$in`, `$regex`
+      // and friends hold VALUES, which must be passed through untouched.
+      const nested = key === '$and' || key === '$nor' || key === '$or' ? GridFSHelper.mapContentTypeKeys(entry) : entry;
+      mapped[key === 'contentType' ? 'metadata.contentType' : key] = nested;
+    }
+    return mapped;
+  }
+
   /**
    * Delete a file from GridFS
    */

package/src/core/common/helpers/validation-message.helper.ts

@@ -0,0 +1,83 @@
+import { ValidationArguments } from 'class-validator';
+
+/**
+ * Renders a single constraint for use in an error message.
+ *
+ * Mirror of class-validator's internal `constraintToString`
+ * (`class-validator/cjs/validation/ValidationUtils`), which is NOT part of its public API.
+ *
+ * See {@link replaceMessageSpecialTokens} for why this lives here and what holds it in sync.
+ */
+export function constraintToString(constraint: unknown): string {
+  if (Array.isArray(constraint)) {
+    return constraint.join(', ');
+  }
+  if (typeof constraint === 'symbol') {
+    constraint = constraint.description;
+  }
+  return `${constraint}`;
+}
+
+/**
+ * Resolves a message (string or function) and interpolates the special tokens
+ * $constraint1..N, $value, $property and $target.
+ *
+ * Mirror of class-validator's internal `ValidationUtils.replaceMessageSpecialTokens`
+ * (`class-validator/cjs/validation/ValidationUtils`), which is NOT part of its public API.
+ * `MapAndValidatePipe` re-implements the validation executor and therefore has to render messages
+ * exactly the way class-validator's own `validate()` would — otherwise the same decorator produces
+ * two different strings depending on which of the two ran.
+ *
+ * WHY IT IS NOT BARREL-EXPORTED
+ * Deliberately absent from `src/index.ts`. It exists to reproduce a dependency's internal
+ * behaviour, so it has to stay free to follow that dependency; exporting it would owe consumers
+ * backward compatibility for a surface we do not control. Vendor-mode consumers resolve their own
+ * class-validator, so the copy in `src/core/` can meet a version this repo never installed —
+ * `tests/unit/validation-message-mirror.spec.ts` compares it against the INSTALLED implementation
+ * over a fixture table so a divergence surfaces as a failing test rather than as two renderers of
+ * one contract.
+ *
+ * SECURITY — `$value` echoes the SUBMITTED value back to the client, and validation errors are
+ * never scrubbed: `security.secretFields` is applied by `CheckSecurityInterceptor` on the RESPONSE
+ * path, whereas the `BadRequestException` raised from the pipe goes to the exception filter and is
+ * forwarded verbatim. The check below is a TYPE guard (boolean | number | string), not a secrecy
+ * guard — it happily admits a password or a token. No built-in message uses `$value`, so reaching
+ * it is opt-in: never put `$value` in a custom message on a sensitive field.
+ */
+export function replaceMessageSpecialTokens(
+  message: ((args: ValidationArguments) => string) | string,
+  validationArguments: ValidationArguments,
+): string {
+  let messageString = '';
+  if (typeof message === 'function') {
+    messageString = message(validationArguments);
+  } else if (typeof message === 'string') {
+    messageString = message;
+  }
+
+  if (messageString && Array.isArray(validationArguments.constraints)) {
+    validationArguments.constraints.forEach((constraint, index) => {
+      messageString = messageString.replace(
+        new RegExp(`\\$constraint${index + 1}`, 'g'),
+        constraintToString(constraint),
+      );
+    });
+  }
+
+  if (
+    messageString &&
+    validationArguments.value !== undefined &&
+    validationArguments.value !== null &&
+    ['boolean', 'number', 'string'].includes(typeof validationArguments.value)
+  ) {
+    messageString = messageString.replace(/\$value/g, `${validationArguments.value}`);
+  }
+  if (messageString) {
+    messageString = messageString.replace(/\$property/g, validationArguments.property);
+  }
+  if (messageString) {
+    messageString = messageString.replace(/\$target/g, validationArguments.targetName);
+  }
+
+  return messageString;
+}

package/src/core/common/pipes/map-and-validate.pipe.ts

@@ -20,6 +20,7 @@ import {
   maxLength,
   min,
   minLength,
+  ValidationArguments,
   ValidationError,
 } from 'class-validator';
 import { ValidationMetadata } from 'class-validator/types/metadata/ValidationMetadata';
@@ -27,6 +28,7 @@ import { inspect } from 'util';
 
 import { getUnifiedFieldKeys, nestedTypeRegistry } from '../decorators/unified-field.decorator';
 import { isBasicType } from '../helpers/input.helper';
+import { replaceMessageSpecialTokens } from '../helpers/validation-message.helper';
 import { ConfigService } from '../services/config.service';
 import { ErrorCode } from '../../modules/error-code/error-codes';
 
@@ -268,18 +270,21 @@ async function validateWithInheritance(object: any, originalPlainValue: any): Pr
                       isValid = validationResult instanceof Promise ? await validationResult : validationResult;
                     }
 
-                    // Get default message and constraint name if validation failed
+                    // Get message and constraint name if validation failed
                     if (!isValid) {
                       // Use metadata.name for the constraint key (e.g., "isEmail", "isString")
                       const constraintName = metadata.name || 'customValidation';
 
-                      if (typeof constraintInstance.defaultMessage === 'function') {
-                        errorMessage = constraintInstance.defaultMessage(validationArgs);
-                        // Replace $property placeholder with actual property name
-                        errorMessage = errorMessage.replace(/\$property/g, propertyName);
-                      } else {
-                        errorMessage = `${propertyName} failed custom validation`;
+                      // A custom message from ValidationOptions takes precedence over the
+                      // constraint's default message — same order as class-validator's executor
+                      let messageTemplate: string | ((args: ValidationArguments) => string) | undefined =
+                        metadata.message as string | ((args: ValidationArguments) => string) | undefined;
+                      if (!messageTemplate && typeof constraintInstance.defaultMessage === 'function') {
+                        messageTemplate = constraintInstance.defaultMessage(validationArgs);
                       }
+                      errorMessage = messageTemplate
+                        ? replaceMessageSpecialTokens(messageTemplate, validationArgs)
+                        : `${propertyName} failed custom validation`;
 
                       // Add to constraints with the proper name
                       propertyError.constraints[constraintName] = errorMessage;
@@ -578,6 +583,19 @@ async function validateWithInheritance(object: any, originalPlainValue: any): Pr
 
           // Add constraint violation if validation failed
           if (!isValid) {
+            // A custom message from ValidationOptions takes precedence over the built-in message
+            if (metadata.message) {
+              errorMessage = replaceMessageSpecialTokens(
+                metadata.message as string | ((args: ValidationArguments) => string),
+                {
+                  constraints: metadata.constraints || [],
+                  object: tempInstance,
+                  property: propertyName,
+                  targetName: targetClass.name,
+                  value: propertyValue,
+                },
+              );
+            }
             propertyError.constraints[constraintType] = errorMessage;
           }
         }

package/src/core/common/services/core-s3.service.ts

@@ -1,4 +1,5 @@
 import { Injectable, Logger, OnApplicationShutdown, OnModuleInit } from '@nestjs/common';
+import { PassThrough } from 'stream';
 
 import { buildContentDisposition } from '../helpers/content-disposition.helper';
 import { ConfigService } from './config.service';
@@ -276,15 +277,76 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
       length = (body as Buffer).length;
     }
 
-    await client.send(
-      new sdk.PutObjectCommand({
-        Body: payload,
-        Bucket: config.bucket,
-        ...(contentType ? { ContentType: contentType } : {}),
-        ...(length === undefined ? {} : { ContentLength: length }),
-        Key: key,
-      }),
-    );
+    const send = () =>
+      client.send(
+        new sdk.PutObjectCommand({
+          Body: payload,
+          Bucket: config.bucket,
+          ...(contentType ? { ContentType: contentType } : {}),
+          ...(length === undefined ? {} : { ContentLength: length }),
+          Key: key,
+        }),
+      );
+
+    // A stream handed straight to the SDK is the ONE body shape whose failure is not already
+    // ours: the unknown-length branch above reads the stream itself (`for await` throws), and a
+    // Buffer cannot fail. See `guardBodyStream` for what goes wrong without this.
+    if (this.isStream(payload)) {
+      const guard = this.guardBodyStream(payload);
+      payload = guard.body;
+      try {
+        await send();
+      } catch (error) {
+        throw guard.sourceError() ?? error;
+      }
+      // A source that died after the SDK already considered the request done would otherwise be
+      // reported as a successful upload of a truncated object.
+      const failure = guard.sourceError();
+      if (failure) {
+        throw failure;
+      }
+      return;
+    }
+    await send();
+  }
+
+  /**
+   * Shield the SDK from a REQUEST-BODY stream that can fail, and keep the cause.
+   *
+   * WHY THIS EXISTS: the AWS SDK pipes the body into its HTTP request without listening on the
+   * SOURCE. An error there therefore reached a stream with NO listener, and Node turns an unhandled
+   * `'error'` event into an uncaught exception that ends the process. Reachable from ordinary
+   * operation — this is the path a tus upload takes when it is migrated into S3 (`body` plus a
+   * known `contentLength`), so a staged read that drops mid-migration took the API down with it.
+   * It is also a driver asymmetry of the shape this release keeps finding: the filesystem driver
+   * routes the same stream through `pipeline()`, which forwards both ends, and GridFS has its own
+   * source handler. Only S3 had none.
+   *
+   * WHY A RELAY RATHER THAN JUST A LISTENER: a listener alone stops the uncaught exception, but the
+   * SDK's own request pipeline still observes a body stream that ERRORED and rejects a promise of
+   * its own that nothing awaits — an unhandled rejection, which Node also treats as fatal by
+   * default. So the SDK must never see a failing stream at all. It gets a `PassThrough` that simply
+   * ENDS early instead; short of its declared `Content-Length`, that is an ordinary request failure
+   * the SDK reports through the promise we are already awaiting. `sourceError()` then replaces the
+   * SDK's `socket hang up` with the actual cause, which is the part an operator needs.
+   *
+   * A `Promise.race` against the send would be the obvious alternative and is worse: it introduces
+   * a second promise for the same failure, and whichever loses the race is a rejection nobody
+   * consumes — trading the uncaught exception for exactly the unhandled rejection above.
+   */
+  protected guardBodyStream(stream: Readable): { body: Readable; sourceError: () => Error | undefined } {
+    const relay = new PassThrough();
+    let sourceError: Error | undefined;
+
+    stream.on('error', (error: Error) => {
+      sourceError = error;
+      // GRACEFUL end, never `destroy(error)`: propagating the error into the relay would hand the
+      // SDK the failing stream this method exists to keep away from it.
+      relay.end();
+    });
+    stream.pipe(relay);
+
+    return { body: relay, sourceError: () => sourceError };
   }
 
   /**

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

@@ -93,6 +93,26 @@ Reads consult **every** store, so files written under a previous driver stay rea
 migration step and no cut-over moment. New files go to the active driver; `findFileInfo()` returns
 the union, paged once over the merged result.
 
+That holds per method and in **both** directions — adopting a driver and switching away from one.
+The metadata lookups are gated on whether a store is USABLE, never on whether it is the active write
+driver, so pinning `file.storage: 'gridfs'` on a deployment that once used S3 keeps the S3 files
+readable rather than 404-ing them.
+
+Three consequences worth knowing about the merged read path:
+
+- **Ordering.** Each store answers its own correctly ordered page, and the merge re-establishes a
+  global order before it pages (`sortMergedFileInfo()`), including dotted sort fields such as
+  `metadata.ownerId`. Without a `sort` the merged page is `uploadDate` descending.
+- **`contentType`.** GridFS keeps it inside `metadata`, the other two stores at the document root.
+  `GridFSHelper.findFiles()` rewrites the key so a filter or sort on `contentType` behaves the same
+  under every driver.
+- **Duplication crosses drivers.** `duplicateByName()` / `duplicateById()` read the source from
+  whichever store holds it and write the copy to the ACTIVE driver, so duplicating a file that is
+  still in GridFS while `file.storage: 's3'` simply moves it forward.
+
+`s3-files` and `filesystem-files` are created on their first WRITE, never on a read — a deployment
+that only ever uses GridFS never grows them.
+
 The boot log names the driver in use, so it never has to be inferred from where files stopped
 appearing:
 
@@ -184,6 +204,20 @@ rather than exempt from it. The reference server does both: `src/server/modules/
 `src/server/modules/user/avatar.controller.ts`. The contract test for the whole rule, covering the
 `id` **and** the `filename` branch, lives in `tests/file-ownership.e2e-spec.ts`.
 
+**It covers duplication too (11.34.0+).** `duplicateByName()` / `duplicateById()` authorize a copy as
+a READ of the source (`'filename'` / `'id'`) plus a WRITE of the copy (`'file'`), through the same
+public methods every other caller uses — so forward the context:
+
+```typescript
+await this.fileService.duplicateById(id, { currentUser });
+// …and give the COPY its own owner, because it does NOT inherit the source's metadata
+await this.fileService.duplicateById(id, { currentUser, metadata: { ownerId: currentUser.id } });
+```
+
+Not copying the source's `metadata` is deliberate: doing so would silently hand the duplicate the
+source's owner. A copy made without metadata is ADMIN-only under the rule above — fail-closed, not
+lost.
+
 Three pieces make this work, and all three are needed:
 
 1. **Write the metadata at upload time** — `createFile(file, { metadata: { ownerId: user.id } })`.
@@ -325,12 +359,14 @@ export class FileController extends CoreFileController {
 
 ### Error responses
 
-| Situation                                                                              | Status | Body                                                                                                  |
-| -------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
-| Unknown id / filename, or `checkRights()` refused                                      | `404`  | `NotFoundException` with `ErrorCode.FILE_NOT_FOUND`                                                   |
-| Missing id / filename in the route                                                     | `400`  | `BadRequestException` with `ErrorCode.REQUIRED_FIELD_MISSING`                                         |
-| GridFS read fails **before** any byte was sent (file document exists, chunks are gone) | `404`  | `{ "error": "Not Found", "message": "<FILE_NOT_FOUND>", "statusCode": 404 }`                          |
-| GridFS read fails **after** streaming started                                          | —      | The connection is closed; a truncated transfer is the only signal left once the status is on the wire |
+| Situation                                                                              | Status | Body                                                                                                                                                                                 |
+| -------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Unknown id / filename, or `checkRights()` refused                                      | `404`  | `NotFoundException` with `ErrorCode.FILE_NOT_FOUND`                                                                                                                                  |
+| `deleteFile()` / `deleteFileByName()` / `duplicate*()` on a file that is not there     | `404`  | `NotFoundException`. Both halves of each id/name pair answer identically — up to 11.33.1 the by-id delete surfaced the driver's `MongoRuntimeError` as a `500`                       |
+| Missing id / filename in the route                                                     | `400`  | `BadRequestException` with `ErrorCode.REQUIRED_FIELD_MISSING`                                                                                                                        |
+| An upload's SOURCE stream fails (client aborts, staged read drops)                     | `500`  | The promise rejects with the cause — under **every** driver. It used to be an uncaught exception (i.e. a process exit) on GridFS, and on the S3 streaming path tus finalization uses |
+| GridFS read fails **before** any byte was sent (file document exists, chunks are gone) | `404`  | `{ "error": "Not Found", "message": "<FILE_NOT_FOUND>", "statusCode": 404 }`                                                                                                         |
+| GridFS read fails **after** streaming started                                          | —      | The connection is closed; a truncated transfer is the only signal left once the status is on the wire                                                                                |
 
 The mid-stream failure case is handled by `pipeFileToResponse()`. Without it the stream error would
 go unhandled, Node would destroy the socket, and a reverse proxy would report **502 Bad Gateway** —