@lenne.tech/nest-server 11.32.2 → 11.32.4

package/src/core/modules/file/core-file.controller.spec.ts

@@ -0,0 +1,164 @@
+import { NotFoundException } from '@nestjs/common';
+import type { Response } from 'express';
+import { PassThrough, Readable } from 'stream';
+import { describe, expect, it } from 'vitest';
+
+import type { CoreFileService } from './core-file.service';
+import { CoreFileController, pipeFileToResponse } from './core-file.controller';
+
+/**
+ * Build a response stub that records what the handler did to it.
+ *
+ * A real `Response` is not needed here — what is under test is the decision
+ * (status vs. destroy), not Express. Writing it out as a stub also makes the
+ * "headers already sent" case reachable, which is awkward to force otherwise.
+ *
+ * What this stub CANNOT show is how Express itself treats headers: `res.json()`
+ * only defaults `Content-Type` when none is set, so a stub whose `json()` merely
+ * records a body can never reveal a stale one. That property is pinned at the
+ * HTTP level in `tests/file.e2e-spec.ts`; here we assert the removal list.
+ */
+function responseStub(headersSent = false) {
+  const sink = new PassThrough();
+  const calls = {
+    destroyed: false,
+    json: undefined as unknown,
+    removed: [] as string[],
+    set: {} as Record<string, string>,
+    status: 0,
+  };
+
+  const res = Object.assign(sink, {
+    destroy: () => {
+      calls.destroyed = true;
+      return res;
+    },
+    headersSent,
+    json: (body: unknown) => {
+      calls.json = body;
+      return res;
+    },
+    removeHeader: (name: string) => {
+      calls.removed.push(name);
+    },
+    setHeader: (name: string, value: string) => {
+      calls.set[name] = value;
+      return res;
+    },
+    status: (code: number) => {
+      calls.status = code;
+      return res;
+    },
+  }) as unknown as Response;
+
+  return { calls, res };
+}
+
+describe('pipeFileToResponse', () => {
+  it('turns a read error into 404 while nothing has been written yet', async () => {
+    // A GridFS record and its bytes are two separate writes, so the record can
+    // outlive the chunks. GridFS reports that on the stream, asynchronously.
+    // A bare `stream.pipe(res)` installs no error handler, so the error goes
+    // unhandled, Node destroys the socket mid-response, and any reverse proxy
+    // in front reports 502 Bad Gateway — "the server is down", which is the one
+    // diagnosis that is wrong while every other route answers normally.
+    const stream = new Readable({ read() {} });
+    const { calls, res } = responseStub(false);
+
+    pipeFileToResponse(stream, res);
+    stream.emit('error', new Error('FileNotFound: file 0123456789ab was not found'));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(calls.status).toBe(404);
+    expect(calls.json).toMatchObject({ statusCode: 404 });
+    expect(calls.destroyed).toBe(false);
+  });
+
+  it('drops every header that describes the file, not just the download one', async () => {
+    // Each of these would otherwise survive onto the error response:
+    // `Content-Disposition` offers a JSON error body as a file to save, a long
+    // `Cache-Control` lets the client cache the failure, `ETag` describes bytes
+    // that were never sent — and `Content-Type` makes an ofetch/`$fetch` client
+    // parse the JSON as an image and lose the message entirely.
+    const stream = new Readable({ read() {} });
+    const { calls, res } = responseStub(false);
+
+    pipeFileToResponse(stream, res);
+    stream.emit('error', new Error('chunks missing'));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(calls.removed).toEqual(
+      expect.arrayContaining(['Cache-Control', 'Content-Disposition', 'Content-Type', 'ETag']),
+    );
+    expect(calls.set['X-Content-Type-Options']).toBe('nosniff');
+  });
+
+  it('closes the connection once bytes are already on the wire', async () => {
+    // Past the first byte there is no status left to send. Dropping the
+    // connection is the only remaining signal — and it is the correct one: it
+    // is what a truncated transfer looks like, so the client does not cache a
+    // half file as if it were complete.
+    const stream = new Readable({ read() {} });
+    const { calls, res } = responseStub(true);
+
+    pipeFileToResponse(stream, res);
+    stream.emit('error', new Error('connection lost mid-stream'));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(calls.destroyed).toBe(true);
+    expect(calls.status).toBe(0);
+  });
+
+  it('answers a refused download exactly like an unknown id', async () => {
+    // `getFileStream()` returns null when the service's own `checkRights()`
+    // refuses — a branch only a CONSUMER project can reach, since the framework's
+    // base implementation always returns true. That is precisely why the
+    // framework has to pin it: consumers cannot, and if the two answers ever
+    // diverge (403 here, 404 there, or different messages) the endpoint becomes
+    // an existence oracle for files the caller may not read.
+    // Invoked through the prototype rather than a subclass: `CoreFileController`
+    // has a protected constructor (it is abstract by design), and a subclass added
+    // only to widen that visibility is exactly what `no-useless-constructor`
+    // strips — leaving code that no longer compiles.
+    const download = (service: Partial<CoreFileService>, res: Response) =>
+      (CoreFileController.prototype.getFileById as (this: unknown, id: string, res: Response) => Promise<unknown>).call(
+        { fileService: service },
+        'abc',
+        res,
+      );
+
+    const file = { contentType: 'image/png', filename: 'secret.png', id: 'abc' };
+    const { res } = responseStub(false);
+
+    const refusedErr = await download(
+      { getFileInfo: async () => file, getFileStream: async () => null } as unknown as Partial<CoreFileService>,
+      res,
+    ).catch((e: unknown) => e);
+    const unknownErr = await download(
+      { getFileInfo: async () => null, getFileStream: async () => null } as unknown as Partial<CoreFileService>,
+      res,
+    ).catch((e: unknown) => e);
+
+    expect(refusedErr).toBeInstanceOf(NotFoundException);
+    expect(unknownErr).toBeInstanceOf(NotFoundException);
+    // Byte-identical answers: same status, same message.
+    expect((refusedErr as NotFoundException).getStatus()).toBe((unknownErr as NotFoundException).getStatus());
+    expect((refusedErr as NotFoundException).getResponse()).toEqual((unknownErr as NotFoundException).getResponse());
+  });
+
+  it('destroys the source stream when the client goes away', async () => {
+    // `pipe()` only ever unpipes the DESTINATION; it never destroys the source.
+    // On a public download route an aborted request would therefore leak the
+    // GridFS read stream and its server-side cursor until the cursor timeout.
+    const stream = new Readable({ read() {} });
+    const { res } = responseStub(false);
+
+    pipeFileToResponse(stream, res);
+    expect(stream.destroyed).toBe(false);
+
+    res.emit('close');
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(stream.destroyed).toBe(true);
+  });
+});

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

@@ -1,10 +1,82 @@
-import { BadRequestException, Controller, Get, NotFoundException, Param, Res } from '@nestjs/common';
-import { Response } from 'express';
+import { BadRequestException, Controller, Get, Logger, NotFoundException, Param, Res } from '@nestjs/common';
+import type { Response } from 'express';
+import type { Readable } from 'stream';
 
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
+import { ErrorCode } from '../error-code/error-codes';
 import { CoreFileService } from './core-file.service';
 
+const fileStreamLogger = new Logger('CoreFileController');
+
+/**
+ * Headers that describe the FILE and must not survive onto an error response.
+ *
+ * Deliberately not the whole set: CORS headers are already on the response at
+ * this point, and removing those would turn a readable 404 into an opaque CORS
+ * failure in the browser — hiding the very answer this handler exists to give.
+ *
+ * `Content-Type` is the one most easily missed. Express only defaults it in
+ * `res.json()` when nothing is set yet (`if (!this.get('Content-Type'))`), so the
+ * file's own type would otherwise label a JSON body as `image/png` — and an
+ * ofetch/`$fetch` client picks its parser from that header and hands the caller a
+ * Blob instead of the error message.
+ */
+const FILE_DELIVERY_HEADERS = ['Cache-Control', 'Content-Disposition', 'Content-Type', 'ETag'];
+
+/**
+ * Pipe a GridFS download to the response without letting a read error kill the socket.
+ *
+ * A GridFS record and its chunks are two separate writes, so a file document can
+ * outlive its bytes — an interrupted upload, a restored backup, a manual cleanup.
+ * GridFS reports that asynchronously, on the stream, and `stream.pipe(res)` alone
+ * installs no error handler: the error goes unhandled, Node destroys the socket
+ * mid-response, and any reverse proxy in front turns that into **502 Bad Gateway**.
+ * That reads as "the server is down" — the one diagnosis that is wrong here, while
+ * every other route keeps answering normally.
+ *
+ * Nothing has been written when GridFS reports a missing file, so the status is
+ * still ours to set and the answer becomes an honest 404. Once bytes are on the
+ * wire there is no status left to send and closing the connection is all that
+ * remains — but at that point it genuinely is a truncated transfer, which is
+ * exactly what a dropped connection means to the client.
+ *
+ * Note on `pipe()` vs `stream.pipeline()`: pipeline would destroy BOTH streams on
+ * error, including the response — which is precisely the object still needed to
+ * send the 404. So the source is cleaned up explicitly on `res` close instead;
+ * `pipe()` only ever unpipes the destination and would otherwise leave the
+ * GridFS read stream and its server-side cursor open on every aborted download.
+ */
+export function pipeFileToResponse(stream: Readable, res: Response): Response {
+  res.on('close', () => {
+    if (!stream.destroyed) {
+      stream.destroy();
+    }
+  });
+
+  stream.on('error', (err: Error) => {
+    // The answer to the CLIENT stays deliberately indistinguishable from an
+    // unknown id, but the server must not lose the event: a files document
+    // without its chunks is data corruption, and an error silently converted
+    // into a 404 is one nobody will ever notice.
+    fileStreamLogger.error(`GridFS download failed: ${err.message}`, err.stack);
+
+    if (res.headersSent) {
+      res.destroy();
+      return;
+    }
+    for (const header of FILE_DELIVERY_HEADERS) {
+      res.removeHeader(header);
+    }
+    // No global nosniff on this route, and the body is now correctly typed —
+    // set it anyway so a mislabelled response can never be sniffed into markup.
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.status(404).json({ error: 'Not Found', message: ErrorCode.FILE_NOT_FOUND, statusCode: 404 });
+  });
+
+  return stream.pipe(res);
+}
+
 /**
  * File controller
  */
@@ -16,6 +88,18 @@ export abstract class CoreFileController {
    */
   protected constructor(protected fileService: CoreFileService) {}
 
+  /**
+   * Stream a file to the response.
+   *
+   * Delegates to the module-level {@link pipeFileToResponse} (which stays exported
+   * so it can be unit-tested without a Nest context). Override this to change the
+   * error status, the body shape or the logging for a project — the free function
+   * alone would not be reachable from a subclass.
+   */
+  protected pipeFileToResponse(stream: Readable, res: Response): Response {
+    return pipeFileToResponse(stream, res);
+  }
+
   /**
    * Download file by ID
    *
@@ -26,17 +110,22 @@ export abstract class CoreFileController {
   @Roles(RoleEnum.S_EVERYONE)
   async getFileById(@Param('id') id: string, @Res() res: Response) {
     if (!id) {
-      throw new BadRequestException('Missing file ID for download');
+      throw new BadRequestException(ErrorCode.REQUIRED_FIELD_MISSING);
     }
 
     const file = await this.fileService.getFileInfo(id);
     if (!file) {
-      throw new NotFoundException('File not found');
+      throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
     }
     const filestream = await this.fileService.getFileStream(id);
+    // `getFileStream` answers null when the service's own rights check refuses.
+    // Same answer as an unknown id: never confirm that the file exists.
+    if (!filestream) {
+      throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
+    }
     res.header('Content-Type', file.contentType || 'application/octet-stream');
     res.header('Content-Disposition', `attachment; filename=${file.filename}`);
-    return filestream.pipe(res);
+    return this.pipeFileToResponse(filestream, res);
   }
 
   /**
@@ -49,16 +138,19 @@ export abstract class CoreFileController {
   @Roles(RoleEnum.S_EVERYONE)
   async getFile(@Param('filename') filename: string, @Res() res: Response) {
     if (!filename) {
-      throw new BadRequestException('Missing filename for download');
+      throw new BadRequestException(ErrorCode.REQUIRED_FIELD_MISSING);
     }
 
     const file = await this.fileService.getFileInfoByName(filename);
     if (!file) {
-      throw new NotFoundException('File not found');
+      throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
     }
     const filestream = await this.fileService.getFileStream(file.id);
+    if (!filestream) {
+      throw new NotFoundException(ErrorCode.FILE_NOT_FOUND);
+    }
     res.header('Content-Type', file.contentType || 'application/octet-stream');
     res.header('Content-Disposition', `attachment; filename=${file.filename}`);
-    return filestream.pipe(res);
+    return this.pipeFileToResponse(filestream, res);
   }
 }

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

@@ -387,6 +387,41 @@ const fileId = await uploadFileToGridFS('mongodb://localhost/mydb', '../assets/i
 });
 ```
 
+`relativePath` is resolved against the **helper module's** directory, not the migration file's — the
+paths in this example and in the migration template are written accordingly.
+
+The returned promise settles only after three guarantees hold:
+
+| Guarantee                       | Behaviour                                                                                                                                                                                                         |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The bytes are stored            | Chunk completeness is verified before resolving (see `assertGridFsFileComplete()` below). An incomplete upload **rejects** and the incomplete file is removed, rather than returning an id that points at nothing |
+| An unreadable source fails fast | A missing or unreadable file **rejects** with the underlying `ENOENT`. It used to hang forever, because `pipe()` does not forward read-stream errors                                                              |
+| The connection is released      | The MongoClient it opens is always closed, on the success and the failure path alike. A leaked connection keeps the Node event loop alive and `migrate up` never exits                                            |
+
+Since these are hard failures, a seed migration whose asset is missing or only partially stored now
+fails the migration — and with the default `MIGRATE_FAILURE_POLICY=abort` in `docker-entrypoint.sh`,
+the container refuses to start rather than booting with broken data. That is intentional: the point
+of running migrations before the server is to find exactly this.
+
+### assertGridFsFileComplete()
+
+Verifies that every chunk of an already-stored GridFS file is present. `uploadFileToGridFS()` calls
+it for you; call it directly to check files written by something else (a restored dump, another
+service, a manual upload):
+
+```typescript
+import { assertGridFsFileComplete, getDb } from '@lenne.tech/nest-server';
+
+const db = await getDb('mongodb://localhost/mydb');
+await assertGridFsFileComplete(db, 'images', fileId, 'logo.png'); // throws if incomplete
+```
+
+Throws when the files document is missing entirely, or when fewer chunks are stored than its
+`length` implies. It counts chunk documents rather than reading bytes back, so a chunk that was
+written but truncated is **not** detected — the check targets the failure that actually occurs, a
+connection lost mid-upload. Empty files are valid and pass: GridFS stores a zero-byte file with no
+chunk documents at all.
+
 ### Migration Templates
 
 Ready-to-use template for nest-server projects:

package/src/core/modules/migrate/cli/migrate-cli.ts

@@ -328,13 +328,76 @@ Environment Variables:
 `);
 }
 
-// Run CLI if executed directly
-if (require.main === module) {
-  main().catch((error) => {
+/**
+ * Exit with `code`, but never before our own output has actually left the process.
+ *
+ * `process.exit()` does NOT drain stdout, and stdout is asynchronous whenever it
+ * is a pipe — which is exactly the Docker / CI / `| tee` case. Exiting straight
+ * after the completion log therefore discards the record of what this run did,
+ * and the line at risk is the last one ("All migrations completed successfully"),
+ * which is precisely what a CI step greps for. Measured: past the 64 KiB pipe
+ * buffer everything beyond it is lost.
+ *
+ * `process.exitCode` is assigned first so that a future `exitCode = 1` elsewhere
+ * is honoured rather than overwritten by a hardcoded 0. The timer is the safety
+ * net for the opposite failure — a consumer that never reads — and is `unref`'d
+ * so it cannot itself keep the process alive.
+ */
+const flushAndExit = async (code: number): Promise<void> => {
+  process.exitCode = code;
+
+  const guard = setTimeout(() => process.exit(code), 5000);
+  guard.unref();
+
+  await Promise.all(
+    [process.stdout, process.stderr].map(
+      (stream) =>
+        new Promise<void>((resolve) => {
+          if (!stream.writableLength) {
+            resolve();
+            return;
+          }
+          stream.write('', () => resolve());
+        }),
+    ),
+  );
+
+  clearTimeout(guard);
+  process.exit(code);
+};
+
+/**
+ * Run the CLI and terminate the process when it is done.
+ *
+ * This is the entry point the `migrate` / `nest-migrate` bin uses. It exists
+ * separately from `main()` because the shell around it matters: migrations touch
+ * MongoDB, GridFS and — via the state store — a second connection, and any handle
+ * one of them leaves behind keeps Node alive forever. The CLI then prints
+ * "All migrations completed successfully" and simply never returns: a CI job
+ * blocks until its timeout, and a container entrypoint that runs migrations
+ * before `exec`ing the server never reaches the server at all.
+ *
+ * Note this must NOT be guarded by `require.main === module`: the shipped
+ * `bin/migrate.js` loads this module and calls in, so `require.main` is the shim,
+ * never this file. A guard here would make the exit unreachable on every path
+ * that actually ships.
+ */
+const runCli = async (): Promise<void> => {
+  try {
+    await main();
+  } catch (error) {
     console.error('Fatal error:', error);
-    process.exit(1);
-  });
+    await flushAndExit(1);
+    return;
+  }
+  await flushAndExit(0);
+};
+
+// Run CLI if executed directly (`node migrate-cli.js`). The bin shim calls
+// runCli() itself, so this only covers a direct invocation of the compiled file.
+if (require.main === module) {
+  void runCli();
 }
 
 // parseArgs is exported for unit testing only (same pattern as resolveCliPath in bin/migrate.js)
-export { main, parseArgs };
+export { flushAndExit, main, parseArgs, runCli };

package/src/core/modules/migrate/helpers/migration.helper.spec.ts

@@ -0,0 +1,85 @@
+import type { Db } from 'mongodb';
+import { ObjectId } from 'mongodb';
+import { describe, expect, it } from 'vitest';
+
+import { assertGridFsFileComplete } from './migration.helper';
+
+/**
+ * Minimal stand-in for the two collections the check reads.
+ *
+ * A real Mongo instance is not needed to pin this contract — what matters is
+ * the decision the function makes given a files document and a chunk count.
+ * The stub records what it was asked for, so a hardcoded bucket name or a wrong
+ * filter key cannot slip past unnoticed; the real-MongoDB counterpart lives in
+ * `tests/migrate/upload-file-to-gridfs.e2e-spec.ts`.
+ */
+function dbStub(files: null | Record<string, unknown>, chunkCount: number) {
+  const asked: { filters: unknown[]; names: string[] } = { filters: [], names: [] };
+
+  const db = {
+    collection: (name: string) => {
+      asked.names.push(name);
+      if (name.endsWith('.files')) {
+        return {
+          findOne: async (filter: unknown) => {
+            asked.filters.push(filter);
+            return files;
+          },
+        };
+      }
+      return {
+        countDocuments: async (filter: unknown) => {
+          asked.filters.push(filter);
+          return chunkCount;
+        },
+      };
+    },
+  } as unknown as Db;
+
+  return { asked, db };
+}
+
+describe('assertGridFsFileComplete', () => {
+  const id = new ObjectId();
+
+  it('passes when every chunk is stored', async () => {
+    // 700 KiB at the default 255 KiB chunk size = 3 chunks.
+    const { db } = dbStub({ _id: id, chunkSize: 261120, length: 716800 }, 3);
+    await expect(assertGridFsFileComplete(db, 'fs', id, 'layout.jpg')).resolves.toBeUndefined();
+  });
+
+  it('rejects when the record promises more bytes than exist', async () => {
+    // The nasty case: the files document looks perfectly healthy, so every
+    // listing and every metadata check says the file is fine — only the
+    // download fails. Reporting this at upload time is what keeps a broken
+    // asset from being persisted as if it were good.
+    const { db } = dbStub({ _id: id, chunkSize: 261120, length: 716800 }, 1);
+    await expect(assertGridFsFileComplete(db, 'fs', id, 'layout.jpg')).rejects.toThrow(/incomplete: 1 of 3 chunks/);
+  });
+
+  it('rejects when the file document is missing entirely', async () => {
+    const { db } = dbStub(null, 0);
+    await expect(assertGridFsFileComplete(db, 'fs', id, 'layout.jpg')).rejects.toThrow(/no file document/);
+  });
+
+  it('accepts an empty file, which GridFS stores with no chunks at all', async () => {
+    // GridFS does NOT write a placeholder chunk for a zero-byte file: the
+    // driver's `writeRemnant()` returns early on `pos === 0`. A `Math.max(1, …)`
+    // floor in the expectation would therefore reject every legitimately empty
+    // asset — and since the container entrypoint defaults to
+    // `MIGRATE_FAILURE_POLICY=abort`, that would keep the server from starting.
+    const { db } = dbStub({ _id: id, chunkSize: 261120, length: 0 }, 0);
+    await expect(assertGridFsFileComplete(db, 'fs', id, 'empty.bin')).resolves.toBeUndefined();
+  });
+
+  it('reads the bucket it was given, filtered by the file id', async () => {
+    // Guards the two things the assertions above cannot see: that the bucket
+    // name is not hardcoded, and that the chunk lookup uses `files_id` (a wrong
+    // key would count zero and turn every upload into a false failure).
+    const { asked, db } = dbStub({ _id: id, chunkSize: 261120, length: 261120 }, 1);
+    await assertGridFsFileComplete(db, 'images', id, 'logo.png');
+
+    expect(asked.names).toEqual(['images.files', 'images.chunks']);
+    expect(asked.filters).toEqual([{ _id: id }, { files_id: id }]);
+  });
+});