@lenne.tech/nest-server 11.33.1 → 11.34.0

package/migration-guides/11.23.x-to-11.24.0.md

@@ -267,6 +267,6 @@ If your code accessed `result.author.password` after a CrudService call (within
 
 ## References
 
-- [SubDocument Array Optimization](../docs/subdocument-array-optimization-plan.md) — Detailed OOM analysis and implementation notes
+- SubDocument array handling (`pushToArray()` / `pullFromArray()`, and why a subdoc array must never pass through `CrudService.update()`) — see `CLAUDE.md` § High-Frequency Path Design Rules, rule 6. The former `docs/subdocument-array-optimization-plan.md` was a working document and no longer exists
 - [process() Performance Optimization](../docs/process-performance-optimization.md) — Pipeline optimization details
 - [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — Reference implementation

package/migration-guides/11.32.x-to-11.33.x.md

@@ -1297,6 +1297,8 @@ re-resolve. Update the lockfile and re-run `pnpm audit` rather than assuming the
 | Rate limiting enabled **behind a reverse proxy** | **Action required** | Set `trustProxy` (hop count) or every client shares one bucket — §11c. A boot warning names it |
 | Rate limiting enabled with **nothing in front of the app** | **Unchanged**, plus a boot warning | Set `trustProxy: false` to state it explicitly and silence the warning |
 | Project overriding `CoreFileService.getFileInfo()` | **Action required for `GET /files/id/:id`** | That route now resolves through `resolveFile()`; override it too — §14 |
+| Project calling `duplicateByName()` / `duplicateById()` | **Action required in 11.34.0** | They take an optional `serviceOptions` and are authorized now, and `duplicateByName()` resolves a `CoreFileInfo` instead of a write stream — [11.33.x → 11.34.x](./11.33.x-to-11.34.x.md) §1 |
+| Test asserting on the error of `deleteFile(<unknown id>)` | **Action required in 11.34.0** | `NotFoundException` (404) instead of `MongoRuntimeError` (500) — [11.33.x → 11.34.x](./11.33.x-to-11.34.x.md) §3 |
 | Project calling `findFileInfo()` **without** a `sort`, with `file.storage` other than `gridfs` | **Ordering changed** | The merged multi-store page defaults to `uploadDate` descending — §14 |
 | Overridden Hub collector `getData()` / mailbox reads | **Action required** | Await and widen the return type (§2) |
 | `const s: GridFSBucketReadStream = await getFileStream(...)` | **Action required** | Type is `Readable` now (§3) |

package/migration-guides/11.33.x-to-11.34.x.md

@@ -0,0 +1,394 @@
+# Migration Guide: 11.33.x → 11.34.x
+
+## Why this is a MINOR
+
+Per `.claude/rules/versioning.md` the MAJOR mirrors NestJS, so **MINOR is where breaking changes
+live**. This release changes the declared return type of a public method (§1), so it is `11.34.0`
+rather than a `11.33.2` patch — even though the change set is small and every other entry is a fix
+you simply inherit.
+
+## Upgrade urgency
+
+Three of the eight defects fixed here are severe. If you are on 11.33.x, these are the reason to
+move now rather than at the next convenient moment:
+
+| # | Defect | Exposure | Section |
+|---|--------|----------|---------|
+| 1 | **Duplication bypassed `checkRights()` entirely** on the GridFS driver — a per-file ownership rule did not apply to `duplicateByName()` at all | Any project with an overridden `checkRights()` that exposes duplication. The copy was made with **no** authorization | [§1](#1-security-duplication-bypassed-checkrights-on-gridfs) |
+| 2 | **An aborted upload crashed the process** — an unhandled stream `'error'` is an uncaught exception in Node | Every GridFS upload; and every tus finalization into S3. A client that hangs up mid-upload takes the API down | [§2](#2-crash-an-aborted-upload-no-longer-takes-the-process-down-gridfs-and-s3) |
+| 3 | Same crash on the **S3** streaming write path | `tus` + `file.storage: 's3'` | [§2](#2-crash-an-aborted-upload-no-longer-takes-the-process-down-gridfs-and-s3) |
+
+Both crash paths are reachable from unauthenticated-adjacent traffic (an upload that is simply cut
+off), and neither leaves a stack trace pointing at the file module — they surface as an unexplained
+pod restart. If you have been seeing those on a replica that accepts uploads, §2 is a strong
+candidate.
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Security** | `duplicateByName()` no longer copies a file without a rights check on the GridFS driver (§1) |
+| **Stability** | An upload whose SOURCE stream fails no longer crashes the process — on GridFS, and on the S3 driver's streaming (tus finalization) path (§2) |
+| **Breaking Changes** | `duplicateByName()` resolves the COPY's `CoreFileInfo` instead of a raw `GridFSBucketWriteStream` (§1). `duplicateByName()` / `duplicateById()` now run `checkRights()` — a project with a fail-closed `checkRights()` that duplicated files without passing a context gets a refusal where the GridFS driver previously copied unchecked (§1). `deleteFile()` answers `NotFoundException` (404) for an unknown id instead of the driver's `MongoRuntimeError` (500) (§3) |
+| **New Features** | `duplicateByName()` / `duplicateById()` accept an optional `serviceOptions` (§1). `CoreFileService.duplicateFile()` as the shared, driver-agnostic write half. The Hub's **Files panel covers all three storage drivers** (§6) |
+| **Bugfixes** | `findFileInfo()` sorts correctly on a DOTTED path (`metadata.ownerId`) across merged stores — a wrong order there returned the wrong ROWS, not merely the wrong order (§4). `findFileInfo()` can filter and sort on `contentType` across all three drivers (§5). `duplicateByName()` keeps the source's content type on the GridFS driver |
+| **Migration Effort** | Nothing to configure. Read §1 if you call `duplicateByName()` / `duplicateById()` anywhere, §3 if any test asserts on the error a delete-by-unknown-id produces. Everything else is a fix you inherit |
+
+All of it lives in the file module, the GridFS helper, `CoreS3Service`'s upload path and the Hub's DB
+service. If your project never calls the duplicate methods, the only changes you can observe are the
+fixes — all of which turn a wrong answer into a right one.
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.34.0
+pnpm run build
+pnpm test
+```
+
+**Vendor-mode projects:** eight modified files under `src/core/`, in two independent groups. No
+moved files and no new files, so a partial sync has no atomic file-set hazard — but the Hub group
+must land together, because the panel, its data contract and its action message changed as one.
+
+| Group | Files |
+|-------|-------|
+| File module (§1–§5) | `common/helpers/gridfs.helper.ts`, `common/services/core-s3.service.ts`, `modules/file/core-file.service.ts` |
+| Hub Files panel (§6) | `modules/hub/services/core-hub-db.service.ts`, `modules/hub/services/core-hub-actions.service.ts`, `modules/hub/interfaces/hub-panels.interface.ts`, `modules/hub/hub-action-messages.ts`, `modules/hub/helpers/hub-client-js.helper.ts` |
+
+The reference implementation in `src/server/modules/file/file.service.ts` also changed (§1), but
+vendor projects do not receive `src/server/` — if you copied its old `duplicate()` body, see §1.
+
+---
+
+## 1. Security: duplication bypassed `checkRights()` on GridFS
+
+### What was wrong
+
+Neither `duplicateByName()` nor `duplicateById()` accepted `serviceOptions` at all. They still called
+`getFileInfo()`, `getFileStream()` and `createFile()` — all of which run `checkRights()` — but with an
+**empty context**. Under the fail-closed `checkRights()` that this framework's README, its reference
+server and `nest-server-starter` all teach, that produced three different wrong answers depending on
+the storage driver:
+
+| Call | `gridfs` | `filesystem` | `s3` |
+|------|----------|--------------|------|
+| `duplicateById(id)` | `TypeError: Cannot read properties of null (reading 'filename')` | same `TypeError` | same `TypeError` |
+| `duplicateByName(a, b)` | **succeeded — the file was copied with no rights check at all** | `Error: FilesystemFileHelper.writeFile requires either 'buffer' or 'body'` | `TypeError: … (reading 'Symbol(Symbol.asyncIterator)')` |
+
+The GridFS cell is the severe one, and it is the reason this release exists: that branch went
+straight to the bucket and never consulted `checkRights()`, so a per-file ownership rule simply did
+not apply to duplication. On the default storage driver, any caller who could reach a duplicate
+endpoint could copy **any** file — and the copy, being a new file, was then reachable under whatever
+rule the copy itself satisfied.
+
+The other two cells are the same defect failing loudly instead of silently. That asymmetry is why it
+survived: the drivers that would have made the bug obvious were the ones nobody ran.
+
+### What it does now
+
+A duplicate is treated as what it is — a **READ of the source plus a WRITE of the copy** — and each
+half is authorized through the ordinary public method:
+
+| Half | Method | `checkInputType` |
+|------|--------|------------------|
+| read the source | `getFileInfoByName()` / `getFileInfo()` + `getFileStreamByName()` / `getFileStream()` | `'filename'` / `'id'` |
+| write the copy | `createFile()` | `'file'` |
+
+```typescript
+// Forward the caller's context, so the duplicate is COVERED by your rule
+await this.fileService.duplicateById(id, { currentUser });
+await this.fileService.duplicateByName(name, newName, { currentUser });
+
+// …or say explicitly that a role decorator already decided
+await this.fileService.duplicateById(id, { force: true });
+
+// …and give the COPY its own metadata (see below)
+await this.fileService.duplicateById(id, { currentUser, metadata: { ownerId: currentUser.id } });
+```
+
+A missing source, or a refused read, now answers `NotFoundException` — the same 404 the download
+routes answer, so a refusal never confirms that an id or a filename is real. A refused **write**
+answers through `accessDeniedException()` (403 authenticated / 401 anonymous), because at that point
+the caller has already been shown the source and the question is no longer whether the file exists.
+
+### Break 1 — a fail-closed `checkRights()` now applies to duplication
+
+This is the security fix seen from the consumer's side: if your project overrides `checkRights()` and
+duplicates files **without** passing a context, the GridFS driver used to copy anyway. It now refuses.
+
+**Symptom:** `NotFoundException: File not found with filename …` (or `… with id …`) from a code path
+that worked before, and no copy in the bucket.
+
+**Fix:** pass `{ currentUser }` where a user is in scope, or `{ force: true }` where a role decorator
+has already decided. Do **not** add `if (!options.currentUser) return true` to `checkRights()` — that
+reads "system-internal call", but it is also exactly what an anonymous request looks like.
+
+### Break 2 — the return value of `duplicateByName()`
+
+```typescript
+// 11.33.x and earlier, GridFS driver: the raw write stream
+const stream = await fileService.duplicateByName('a.txt', 'b.txt');
+stream.id; // ObjectId
+
+// 11.34.0: the copy's file info, under every driver
+const copy = await fileService.duplicateByName('a.txt', 'b.txt');
+copy.id;       // string
+copy.filename; // 'b.txt'
+```
+
+`.id` and `.filename` still answer (as a string and the new name), so the common uses keep working —
+`String(result.id)` and `getStringIds(result.id)` are unaffected. Anything that treated the result as
+a **stream** has to change. The declared return type moved from `Promise<any>` to
+`Promise<CoreFileInfo>`, so TypeScript points at the sites for you. **This is the change that makes
+the release a MINOR.**
+
+This break is not avoidable: the GridFS branch could only be authorized by routing it through
+`createFile()` like the other two drivers, and that is what produces a file info. The S3 and
+filesystem branches already returned a `CoreFileInfo`, so this also removes a driver-conditional
+return type that was never documented as one.
+
+`duplicateById()` still returns the copy's id as a `string`. Unchanged.
+
+### The copy does not inherit the source's metadata
+
+It never did, and it deliberately still does not: silently copying `metadata` would hand the
+duplicate the **source's owner**, which is the one thing an ownership rule must not do behind the
+caller's back. State the copy's own metadata instead:
+
+```typescript
+await this.fileService.duplicateById(id, { currentUser, metadata: { copiedFrom: id, ownerId: currentUser.id } });
+```
+
+Under a fail-closed rule a copy made without metadata is reachable by ADMIN only — that is
+fail-closed, not lost data, and `getFileInfo(copyId, { force: true })` still finds it.
+
+### If you copied `FileService.duplicate()` out of `src/server`
+
+The reference implementation was a direct GridFS pipe — and because it is a reference
+implementation, this defect was **designed to be copied**:
+
+```typescript
+// WRONG — and it was in the reference implementation until 11.34.0
+async duplicate(fileName: string, newName: string): Promise<any> {
+  return this.files.openDownloadStreamByName(fileName).pipe(this.files.openUploadStream(newName));
+}
+```
+
+It only worked on the GridFS driver, bypassed `checkRights()` entirely, returned before the copy was
+written, and carried no error handler on either stream (an unhandled stream `'error'` takes the
+process down — the same defect as §2). It now delegates:
+
+```typescript
+async duplicate(fileName: string, newName: string, serviceOptions?: FileServiceOptions): Promise<CoreFileInfo> {
+  return this.duplicateByName(fileName, newName, serviceOptions);
+}
+```
+
+**If you copied the old body into your own `FileService`, replace it with the delegation above.** The
+framework fix does not reach a copy living in your project.
+
+---
+
+## 2. Crash: an aborted upload no longer takes the process down (GridFS **and** S3)
+
+Two write paths handed a body stream to something that did not listen on the SOURCE. `pipe()` does
+not forward source errors, and an unhandled `'error'` event is an uncaught exception in Node — which
+ends the process. An aborted upload could take the API down.
+
+| Write path | Reached by | Before | After |
+|------------|-----------|--------|-------|
+| `GridFSHelper.writeFileFromStream()` | every GridFS upload | **process crash** | rejects, partial upload aborted |
+| `CoreS3Service.putObject()` with a body stream + `contentLength` | **tus finalization into S3** | **process crash** | rejects with the real cause |
+| `CoreS3Service.putObject()` without a length | `createFile()` on the S3 driver | rejects (`streamToBuffer` throws) | unchanged |
+| `FilesystemFileHelper.writeFile()` | every filesystem upload | rejects (`pipeline()` forwards both ends) | unchanged |
+
+So the same aborted upload behaved in three different ways depending on `file.storage` — which is
+the driver asymmetry this release keeps finding, in its most expensive form.
+
+**GridFS.** The failed write is now aborted as well, so its chunks do not linger in `fs.chunks` with
+no `fs.files` document naming them.
+
+**S3.** The AWS SDK pipes the request body into its HTTP request without a source listener. Adding a
+listener alone is *not* enough: the SDK's own pipeline still observes a stream that errored and
+rejects a promise nothing awaits — an unhandled rejection, which Node also treats as fatal by
+default. The body is therefore relayed through a `PassThrough` that simply **ends early** on source
+failure, which the SDK reports as an ordinary short-body request error; the captured source error
+then replaces the SDK's `socket hang up`, so the log names the cause rather than the symptom.
+
+Nothing to do — but if you have been seeing unexplained restarts on a pod that accepts uploads (or
+finalizes tus uploads into S3), this is the fix.
+
+---
+
+## 3. `deleteFile()` answers 404 for an unknown id, not 500
+
+`deleteFileByName()` threw `NotFoundException` for a filename that does not exist. `deleteFile()` fell
+through to the GridFS driver, which threw its own `MongoRuntimeError: File not found for id …` — an
+HTTP **500** for the very same condition, under all three storage drivers.
+
+```typescript
+await fileService.deleteFile(unknownId);
+// 11.33.x: MongoRuntimeError → 500
+// 11.34.0: NotFoundException → 404
+```
+
+A **refusal** still answers `null` rather than throwing, which is unchanged and is the module-wide
+contract: a refusal must be indistinguishable from a file that is not there.
+
+**What to check:** any test or client code that asserts on the error of a delete-by-unknown-id. If
+you catch `MongoRuntimeError` there, catch `NotFoundException` instead — or, better, treat 404 as the
+idempotent-delete case.
+
+---
+
+## 4. `findFileInfo()` sorts correctly on a dotted path across stores
+
+`SortInput.field` is a free string, and MongoDB reads `metadata.ownerId` as a path into the document.
+Each store therefore returned its own page correctly ordered — and the merge that follows compared
+`doc['metadata.ownerId']`, which is `undefined` for every row. Every comparison tied, and the merged
+page came back **grouped by store**.
+
+That is not a cosmetic ordering bug: `skip` / `limit` applied to a wrongly ordered merge returns
+**different rows**, so a paginated listing sorted on a nested field silently showed some files twice
+and others never.
+
+Only the multi-store read path was affected — i.e. any `file.storage` other than `gridfs`, or a
+GridFS deployment that also has files in `s3-files` / `filesystem-files` from a previous driver.
+
+---
+
+## 5. `findFileInfo()` can filter and sort on `contentType` under every driver
+
+`s3-files` and `filesystem-files` carry `contentType` at the root of the metadata document. GridFS
+keeps it inside `metadata` (the MongoDB driver dropped the top-level option in v7). So a filter on
+`contentType` matched every S3 / filesystem file and **no** GridFS file:
+
+| Driver | `findFileInfo({ filter: contentType == 'application/pdf' })` before | after |
+|--------|--------------------------------------------------------------------|-------|
+| `gridfs` | always `[]` | matches |
+| `filesystem` / `s3` | matches new files, **silently drops every pre-switch GridFS file** | matches both |
+
+`GridFSHelper.findFiles()` now rewrites a `contentType` key to `metadata.contentType` in both the
+filter and the sort — the mirror image of the normalisation it already did on the way out. The
+rewrite is deliberately narrow: only that one key, only where it names a field, recursing only
+through `$and` / `$or` / `$nor`, and an already-qualified `metadata.contentType` is left alone.
+
+**What you may notice:** a listing filtered on `contentType` that used to return nothing now returns
+rows. If you depended on the empty result, filter on something else.
+
+---
+
+## 6. The Hub's Files panel covers all three storage drivers
+
+`CoreHubDbService.getFiles()` / `deleteFile()` read GridFS directly, so under `file.storage: 's3'` or
+`'filesystem'` the Hub's Files panel reported **0 files** and could not delete anything.
+
+"0 files" is not "this panel does not cover your driver" — in an operator cockpit a confidently wrong
+answer is worse than an honest gap, because it is the answer an operator acts on. Somebody checking
+whether an upload landed would have concluded it had not.
+
+The panel now reads the same three metadata sources `CoreFileService.findFileInfo()` does
+(`fs.files`, `s3-files`, `filesystem-files`), merges them newest-first, and dispatches a delete to
+whichever store actually holds the file. Each row carries a **Store** column, and the panel's tiles
+name the stores consulted with a per-store count.
+
+| Behaviour | Before | After |
+|-----------|--------|-------|
+| Listing under `file.storage: 'gridfs'` | GridFS files | unchanged, plus any files left in the other stores by a previous driver |
+| Listing under `'s3'` / `'filesystem'` | **always empty** | the files that are actually there |
+| Deleting an S3- or filesystem-backed file | **impossible** (`File not found`) | deletes the bytes AND the metadata document |
+| Deleting a GridFS file | GridFS delete | unchanged |
+
+Nothing to configure. Two operational notes:
+
+- **S3 deletion needs `CoreS3Service` to be usable.** When `s3` is not configured, the Hub refuses an
+  S3-backed delete with `S3 storage is not available.` rather than deleting the metadata document and
+  orphaning the object in the bucket. A half-delete is unrecoverable in a way a refusal is not.
+- **Reading never creates a collection.** A GridFS-only deployment does not grow an empty `s3-files`
+  / `filesystem-files` from the Hub looking at them — the same rule
+  `ensureFilenameIndex()` follows on the write path.
+
+`HubFilesData` gained a `stores` summary and a `store` field per file. If you override
+`CoreHubDbService` or consume `files.json` directly, both are additive.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| Project that never calls `duplicateByName()` / `duplicateById()` | **Unchanged** | |
+| `duplicateById(id)` with the framework's default `checkRights()` | **Unchanged** | The default returns `true`, so an omitted context behaves exactly as before |
+| `duplicateByName(a, b)` reading `.id` / `.filename` off the result | **Compatible** | `.id` is a `string` now instead of an `ObjectId`; `String(...)` / `getStringIds(...)` are unaffected |
+| `duplicateByName(a, b)` treating the result as a stream | **Action required** | §1 — it is a `CoreFileInfo` now |
+| Overridden fail-closed `checkRights()` + duplication without a context | **Action required** | §1 — pass `{ currentUser }` or `{ force: true }` |
+| `FileService.duplicate()` copied out of `src/server` before 11.34.0 | **Action required** | §1 — the copy still bypasses `checkRights()`; replace the body with the delegation |
+| Test asserting `MongoRuntimeError` on delete-by-unknown-id | **Action required** | §3 — it is `NotFoundException` now |
+| `findFileInfo()` sorted on a nested field, `file.storage` other than `gridfs` | **Rows changed (fixed)** | §4 |
+| `findFileInfo()` filtered on `contentType` | **Rows changed (fixed)** | §5 |
+| Hub Files panel under `file.storage: 's3'` / `'filesystem'` | **Rows changed (fixed)** | §6 — it showed nothing before |
+| Project overriding `CoreFileService.deleteFile()` | **Review** | If you call `super.deleteFile()`, it may now throw where it previously returned |
+| Project overriding `GridFSHelper` behaviour | **Review** | `findFiles()` rewrites one filter key; `writeFileFromStream()` gained source-error handling |
+| Project overriding `CoreS3Service.putObject()` | **Review** | A body STREAM is now relayed through a `PassThrough` before it reaches the SDK (§2); Buffer and string bodies are untouched |
+| Project overriding `CoreHubDbService.getFiles()` / `deleteFile()` | **Review** | Both are multi-store now; `HubFilesData` gained `stores` + per-file `store` (§6) |
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `NotFoundException: File not found with filename …` from a duplicate that used to work | Fail-closed `checkRights()` now applies to duplication (§1) | Pass `{ currentUser }` or `{ force: true }` |
+| `Property 'pipe' does not exist on type 'CoreFileInfo'` | §1 — the return type changed | Use `copy.id` / `copy.filename`, or `getFileStream(copy.id)` if you really need bytes |
+| A delete that returned 500 now returns 404 | §3 — that is the fix | Treat 404 as the idempotent-delete case |
+| A copied file is suddenly invisible to its owner | The copy records no owner unless you say so (§1) | `duplicateById(id, { currentUser, metadata: { ownerId: currentUser.id } })` |
+| Hub Files panel says `S3 storage is not available.` on delete | §6 — the file's bytes are in S3, but `s3` is not configured in this process | Configure `s3` (and install `@aws-sdk/client-s3`), or delete through the file API |
+
+---
+
+## Verification
+
+```bash
+pnpm run build
+pnpm test
+```
+
+Framework suites covering this release:
+
+| Suite | Covers |
+|-------|--------|
+| `tests/file-duplicate.e2e-spec.ts` | Duplication under all three drivers: default context, owner context, stranger, missing context, content type, copy metadata (§1) |
+| `tests/file-upload-stream-error.e2e-spec.ts` | An aborted upload rejects instead of crashing, on GridFS and on the S3 streaming path (§2) |
+| `tests/file-missing-answers.e2e-spec.ts` | By-id vs by-name answers for a file that is not there (§3) |
+| `tests/file-find-info.e2e-spec.ts` | Merged multi-store ordering, dotted sort paths, paging, `contentType` filtering, and that unused metadata collections stay absent (§4, §5) |
+| `tests/tus-finalization.e2e-spec.ts` | A finished tus upload lands in the active driver, takes the S3→S3 copy path, and clears the staging bucket |
+| `tests/unit/core-hub-db.service.spec.ts` | The Hub Files panel across all three metadata stores, and its delete dispatch (§6) |
+
+Every defect above is additionally backed by a **registered mutation** in
+`tests/regression-mutations.json`: `pnpm run check:mutations` restores each bug on purpose and
+requires the suites that claim to catch it to go red. A regression test that was never seen failing
+is a claim, not a check — this release is the one that stopped taking those on trust.
+
+---
+
+## Module Documentation
+
+### File
+
+- [README](../src/core/modules/file/README.md) — § Access control, § Storage drivers
+- [`CoreFileService`](../src/core/modules/file/core-file.service.ts)
+- Reference implementation: `src/server/modules/file/`
+
+### Hub
+
+- [README](../src/core/modules/hub/README.md) — § Files panel
+- [`CoreHubDbService`](../src/core/modules/hub/services/core-hub-db.service.ts)
+
+---
+
+## References
+
+- [11.32.x → 11.33.x](./11.32.x-to-11.33.x.md) — the release that introduced the three storage drivers and closed the file endpoints
+- [11.32.3 → 11.32.4](./11.32.3-to-11.32.4.md) — the earlier round of GridFS upload/download hardening

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.33.1",
+  "version": "11.34.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -24,8 +24,10 @@
     "c": "pnpm run check",
     "cf": "pnpm run check:fix",
     "check": "node scripts/check.mjs",
+    "check:consumer": "node scripts/check-consumer.mjs",
     "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:manifest": "node scripts/check-package-manifest.mjs",
+    "check:mutations": "node scripts/check-mutations.mjs",
     "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
     "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",

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 };
   }
 
   /**