@lenne.tech/nest-server 11.33.0 → 11.34.0

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/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/INTEGRATION-CHECKLIST.md

@@ -65,8 +65,18 @@ decision worth making explicitly.
 caller have THIS file". For the latter, write an owner or tenant into the metadata at upload time
 (`createFile(file, { metadata: { ownerId } })`) and compare it in `checkRights()` via
 `getRawFileInfo()` / `getRawFileInfoByName()`. The public `getFileInfo()` strips restricted fields
-and is unusable for the decision. `getRawFileInfo()` checks S3 metadata first, then GridFS, so the
-same rule works under either `file.storage`.
+and is unusable for the decision. Both raw lookups consult every store — S3 metadata first, then the
+filesystem store, then GridFS — so the same rule works under any `file.storage`.
+
+Handle **both** `checkInputType: 'id'` and `'filename'`. An id-only rule is enough while bytes are
+streamed (the filename route resolves an id and re-checks it), but not with presigned S3 downloads,
+and not for `deleteFileByName()`, which authorizes by name only.
+
+**Copy from the executed reference, not from prose:** `src/server/modules/file/file.service.ts`
+implements exactly this rule, and `src/config.env.ts` widens `file.downloadRoles` to `[S_USER]` so
+it is actually reached. Note the internal callers there too — `{ force: true }` on the
+`@Roles(ADMIN)` endpoints, and a real `{ currentUser }` in `AvatarController` — because a rule that
+reads a missing user as "internal, allow" fails open the moment the coarse gate is widened.
 
 ### 5. Decide how the frontend fetches files
 
@@ -82,8 +92,10 @@ route for exactly the public files and leave the core routes gated.
 
 - [ ] `pnpm run build` succeeds
 - [ ] Anonymous `GET /files/id/<id>` answers **401**
-- [ ] A signed-in non-privileged user answers **403** (not 401 — a 401 makes SPA auth layers log the
-      user out)
+- [ ] A signed-in non-privileged user answers **403** when the ROLE GATE is what refuses (not 401 —
+      a 401 makes SPA auth layers log the user out). If you widened `downloadRoles` and let
+      `checkRights()` decide instead, the expected answer is **404**, byte-identical to an unknown
+      id — a 403 there would confirm the file exists
 - [ ] A caller holding a configured role downloads successfully
 - [ ] If you set `file.downloadRoles`, the value actually takes effect — if it does not, something
       in your controller is overriding the member (see step 2)

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:
 
@@ -141,18 +161,63 @@ export class FileService extends CoreFileService {
     input: any,
     options?: FileServiceOptions & { checkInputType: FileInputCheckType },
   ): Promise<boolean> {
-    if (options?.checkInputType !== 'id' || options.force) {
+    // Writes, list queries and forced (system) calls stay on the coarse role gate
+    if (options?.force || (options?.checkInputType !== 'filename' && options?.checkInputType !== 'id')) {
       return true;
     }
-    if (options.currentUser?.hasRole([RoleEnum.ADMIN])) {
+    if (options.currentUser?.hasRole?.([RoleEnum.ADMIN])) {
       return true;
     }
-    const raw = await this.getRawFileInfo(input);
-    return !!raw && String(raw.metadata?.ownerId) === String(options.currentUser?.id);
+    const raw =
+      options.checkInputType === 'id' ? await this.getRawFileInfo(input) : await this.getRawFileInfoByName(input);
+    // Fails closed without a user, and on a file that records no owner.
+    return !!raw?.metadata?.ownerId && String(raw.metadata.ownerId) === String(options.currentUser?.id);
   }
 }
 ```
 
+This is not a sketch: it is the rule `src/server/modules/file/file.service.ts` runs, with
+`file: { downloadRoles: [RoleEnum.S_USER] }` in `src/config.env.ts` so the coarse gate actually
+lets it fire. It used to live here and in that file as a **comment**, on the reasoning that the
+`[ADMIN]` default made it unreachable in the reference server anyway — and a commented rule is never
+compiled, never type-checked and never run. That is how a `deleteFileByName()` regression on the
+`filename` branch shipped through a full green suite.
+
+**Cover the `filename` branch too, not just `id`.** An id-only rule is enough while bytes are
+streamed, because the filename route resolves an id and checks it again — but not once
+`file.storage: 's3'` with presigned downloads is enabled, where the filename route authorizes on the
+by-name lookup alone and then redirects, and not for `deleteFileByName()`, which authorizes by name
+only.
+
+**Never add `if (!options.currentUser) return true`.** It reads as "system-internal call, the guard
+already decided" — but "no user in context" is also exactly what an **anonymous** request looks like.
+While `downloadRoles` is narrower than `S_EVERYONE` the role gate turns those away first, so the
+branch looks harmless; widen the gate, which this very section invites you to do, and it hands every
+file to everyone. The ownership rule evaporates precisely when it starts to matter. The same reason
+makes `!!raw?.metadata?.ownerId` load-bearing: without it, an owner-less file compares
+`String(undefined)` against `String(undefined)` and matches.
+
+Callers that really are internal should say so instead of relying on the omission — `{ force: true }`
+where a role decorator already decided (an `@Roles(ADMIN)` admin endpoint), or the real
+`{ currentUser }` where the user is in scope, so that call is **covered** by the ownership rule
+rather than exempt from it. The reference server does both: `src/server/modules/file/` and
+`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 } })`.
@@ -294,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** —