@lenne.tech/nest-server 11.42.1 → 11.42.2

package/migration-guides/11.42.1-to-11.42.2.md

@@ -0,0 +1,53 @@
+# Migration Guide: 11.42.1 → 11.42.2
+
+## Overview
+
+| Category             | Details                                                                  |
+| -------------------- | ------------------------------------------------------------------------ |
+| **Bugfix**           | Finished TUS uploads answer 204 behind the `compression` middleware (§1) |
+| **Migration Effort** | None — `pnpm update`                                                     |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick up the core update; nothing else to change.
+
+## 1. A finished TUS upload never got an answer although the file was stored
+
+`@tus/server` finishes its responses with `res.end(callback)`, a documented Node signature. The
+`compression` middleware patches `res.end(chunk, encoding)` and treats the first argument as a chunk,
+so the callback reached `Buffer.byteLength()` and threw:
+
+```
+TypeError [ERR_INVALID_ARG_TYPE]: The first argument must be of type string or an instance of Buffer … Received function
+```
+
+The starter's `main.ts` — and therefore every generated project — registers `compression` with
+`filter: () => true` and `threshold: 0`, which removes the two checks that would otherwise skip a
+bodyless 204. The failure hit the final `PATCH`, AFTER the upload had been migrated into the file
+store: the request hung — the headers were already sent, so no error response could follow — the
+client never saw a 2xx, `tus-js-client` never fired `onSuccess`, and no log named `compression`.
+
+Since 11.42.2 `CoreTusService` normalises `res.end(callback)` before the tus server writes
+(`normalizeEndCallback()`, wrapped around `getServer().handle()`), so it holds for the core controller
+and for any project controller that calls the tus server. No change to `main.ts` is needed; a project
+that worked around it by excluding `/tus` from the compression filter can keep or drop that filter.
+
+## 2. TUS request errors are logged with their stack
+
+`CoreTusController` logged only `error.message` for a failed TUS request. A `TypeError` thrown by a
+middleware's patched `res.end` then read like a tus failure, with nothing pointing at the middleware —
+the defect in §1 took several rounds to find for exactly that reason. The stack is now logged too.
+
+## Troubleshooting
+
+| Symptom                                                                                | Cause                                 | Fix               |
+| -------------------------------------------------------------------------------------- | ------------------------------------- | ----------------- |
+| File stored, final PATCH never answers (request hangs), `Received function` in the log | 11.42.1 or older behind `compression` | Update to 11.42.2 |
+
+## Module Documentation
+
+- [TUS README](../src/core/modules/tus/README.md) — Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.1",
+  "version": "11.42.2",
   "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",

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

@@ -526,6 +526,21 @@ from elsewhere (an API key, a signed form token), or to let a support role resum
 2. Verify MongoDB connection is established
 3. Check server logs for initialization errors
 
+### Upload is stored but the client never sees success (fixed in 11.42.2)
+
+**Symptom:** the file appears in the file store (`Upload … migrated to …` in the log), but the final
+`PATCH` never answers (the request hangs: the headers are already sent, so no error response can
+follow), `tus-js-client` never fires `onSuccess`, and the log shows
+`ERR_INVALID_ARG_TYPE … Received function`.
+
+**Cause:** `@tus/server` finishes its responses with `res.end(callback)`, and the `compression`
+middleware patches `res.end(chunk, encoding)` and reads the callback as a chunk. The starter registers
+`compression` with `filter: () => true` and `threshold: 0`, so it also handles the bodyless 204.
+
+**Solution:** update to 11.42.2 — `CoreTusService` normalises `res.end(callback)` before the tus
+server writes (`normalizeEndCallback()`), for the core controller and any project controller that
+calls `getServer().handle()`. No change to `main.ts` is needed.
+
 ### Upload stalls or fails to resume
 
 **Cause:** Upload expired or server restarted

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

@@ -105,7 +105,9 @@ export class CoreTusController {
     try {
       await server.handle(req, res);
     } catch (error) {
-      this.logger.error(`TUS request error: ${error.message}`);
+      // The stack, not just the message: a TypeError from a middleware's patched `res.end` reads
+      // like a tus failure without it, and that cost a project several rounds of diagnosis (11.42.2).
+      this.logger.error(`TUS request error: ${error.message}`, error?.stack);
       if (!res.headersSent) {
         res.status(500).json({ message: 'Upload error' });
       }
@@ -131,7 +133,7 @@ export class CoreTusController {
     try {
       await server.handle(req, res);
     } catch (error) {
-      this.logger.error(`TUS request error for upload ${req.params.id}: ${error.message}`);
+      this.logger.error(`TUS request error for upload ${req.params.id}: ${error.message}`, error?.stack);
       if (!res.headersSent) {
         res.status(500).json({ message: 'Upload error' });
       }

package/src/core/modules/tus/core-tus.service.ts

@@ -54,6 +54,9 @@ export interface CoreTusServiceOptions {
   s3Service?: CoreS3Service;
 }
 
+/** Marks a response whose `end()` was already normalised (see `normalizeEndCallback()`). */
+const END_CALLBACK_NORMALIZED = Symbol('tusEndCallbackNormalized');
+
 /**
  * Core TUS Service
  *
@@ -794,9 +797,66 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       respectForwardedHeaders: true,
     });
 
+    // Every caller of getServer().handle() — the core controller and any project controller — gets
+    // the response normalised before @tus/server writes to it. See normalizeEndCallback().
+    const handle = server.handle.bind(server);
+    server.handle = (req, res) => {
+      this.normalizeEndCallback(res);
+      return handle(req, res);
+    };
+
     return server;
   }
 
+  /**
+   * Makes `res.end(callback)` safe for middlewares that patch `res.end` with the old two-argument form.
+   *
+   * @tus/server finishes its responses through srvx with `res.end(callback)` — a documented Node
+   * signature. `compression` (and any middleware written like it) patches `res.end(chunk, encoding)`
+   * and treats the first argument as a chunk unconditionally, so the callback reaches
+   * `Buffer.byteLength()` and throws `ERR_INVALID_ARG_TYPE ... Received function`. The starter
+   * registers `compression` with `filter: () => true, threshold: 0`, which removes the checks that
+   * would otherwise skip a bodyless 204, so every finished upload failed AFTER the file had been
+   * stored: the client never saw a 2xx and retried an upload that was already complete.
+   *
+   * The wrapper moves a function argument into the callback slot and runs it on `finish`, which is
+   * what Node itself does with it — or on `close`, so a connection dropped after `end()` resolves srvx
+   * too. A response destroyed before `end()` stays unresolved, exactly as with plain Node.
+   * Idempotent per response. Protected so a project can widen it.
+   */
+  protected normalizeEndCallback(res: any): void {
+    if (!res || typeof res.end !== 'function' || res[END_CALLBACK_NORMALIZED]) {
+      return;
+    }
+    const end = res.end;
+    res.end = function normalizedEnd(this: any, chunk?: unknown, encoding?: unknown, callback?: unknown) {
+      if (typeof chunk === 'function') {
+        callback = chunk;
+        chunk = undefined;
+        encoding = undefined;
+      } else if (typeof encoding === 'function') {
+        callback = encoding;
+        encoding = undefined;
+      }
+      if (typeof callback === 'function') {
+        let called = false;
+        const done = () => {
+          if (!called) {
+            called = true;
+            (callback as () => void)();
+          }
+        };
+        this.once('finish', done);
+        this.once('close', done);
+      }
+      if (chunk === undefined) {
+        return end.call(this);
+      }
+      return encoding === undefined ? end.call(this, chunk) : end.call(this, chunk, encoding);
+    };
+    res[END_CALLBACK_NORMALIZED] = true;
+  }
+
   /**
    * Parse TUS metadata into object
    * @tus/server v2 already parses metadata into an object