@tus/server: allow metadata changes in onUploadCreate (#599)

* @tus/server: allow metadata changes in onUploadCreate

* Do not use instanceof :(

* Add changeset

* Add example in comment

.changeset/wild-actors-leave.md

@@ -0,0 +1,5 @@
+---
+'@tus/server': minor
+---
+
+Allow onUploadCreate hook to override metadata

packages/server/README.md

@@ -140,11 +140,12 @@ finished uploads. (`boolean`)
 #### `options.onUploadCreate`
 
 `onUploadCreate` will be invoked before a new upload is created.
-(`(req, res, upload) => Promise<res>`).
+(`(req, res, upload) => Promise<{ res: http.ServerResponse, metadata?: Record<string, string>}>`).
 
-If the function returns the (modified) response, the upload will be created. You can
-`throw` an Object and the HTTP request will be aborted with the provided `body` and
-`status_code` (or their fallbacks).
+- If the function returns the (modified) response the upload will be created.
+- You can optionally return `metadata` which will override (not merge!) `upload.metadata`.
+- You can `throw` an Object and the HTTP request will be aborted with the provided `body`
+  and `status_code` (or their fallbacks).
 
 This can be used to implement validation of upload metadata or add headers.
 
@@ -445,13 +446,15 @@ const {Server} = require('@tus/server')
 const server = new Server({
   // ..
   async onUploadCreate(req, res, upload) {
-    const {ok, expected, received} = validateMetadata(upload)
+    const {ok, expected, received} = validateMetadata(upload) // your logic
     if (!ok) {
       const body = `Expected "${expected}" in "Upload-Metadata" but received "${received}"`
       throw {status_code: 500, body} // if undefined, falls back to 500 with "Internal server error".
     }
-    // We have to return the (modified) response.
-    return res
+    // You can optionally return metadata to override the upload metadata,
+    // such as `{ storagePath: "/upload/123abc..." }`
+    const extraMeta = getExtraMetadata(req) // your logic
+    return {res, metadata: {...upload.metadata, ...extraMeta}}
   },
 })
 ```

packages/server/src/handlers/PostHandler.ts

@@ -12,7 +12,7 @@ import {
 } from '@tus/utils'
 import {validateHeader} from '../validators/HeaderValidator'
 
-import type http from 'node:http'
+import http from 'node:http'
 import type {ServerOptions, WithRequired} from '../types'
 
 const log = debug('tus-node-server:handlers:post')
@@ -100,7 +100,23 @@ export class PostHandler extends BaseHandler {
 
     if (this.options.onUploadCreate) {
       try {
-        res = await this.options.onUploadCreate(req, res, upload)
+        const resOrObject = await this.options.onUploadCreate(req, res, upload)
+        // Backwards compatibility, remove in next major
+        // Ugly check because we can't use `instanceof` because we mock the instance in tests
+        if (
+          typeof (resOrObject as http.ServerResponse).write === 'function' &&
+          typeof (resOrObject as http.ServerResponse).writeHead === 'function'
+        ) {
+          res = resOrObject as http.ServerResponse
+        } else {
+          // Ugly types because TS only understands instanceof
+          type ExcludeServerResponse<T> = T extends http.ServerResponse ? never : T
+          const obj = resOrObject as ExcludeServerResponse<typeof resOrObject>
+          res = obj.res
+          if (obj.metadata) {
+            upload.metadata = obj.metadata
+          }
+        }
       } catch (error) {
         log(`onUploadCreate error: ${error.body}`)
         throw error

packages/server/src/types.ts

@@ -90,7 +90,10 @@ export type ServerOptions = {
     req: http.IncomingMessage,
     res: http.ServerResponse,
     upload: Upload
-  ) => Promise<http.ServerResponse>
+  ) => Promise<
+    // TODO: change in the next major
+    http.ServerResponse | {res: http.ServerResponse; metadata?: Upload['metadata']}
+  >
 
   /**
    * `onUploadFinish` will be invoked after an upload is completed but before a response is returned to the client.

packages/server/test/Server.test.ts

@@ -10,7 +10,7 @@ import request from 'supertest'
 
 import {Server} from '../src'
 import {FileStore} from '@tus/file-store'
-import {TUS_RESUMABLE, EVENTS, DataStore} from '@tus/utils'
+import {TUS_RESUMABLE, EVENTS, DataStore, Metadata} from '@tus/utils'
 import httpMocks from 'node-mocks-http'
 import sinon from 'sinon'
 
@@ -423,6 +423,35 @@ describe('Server', () => {
         .expect(500, 'no', done)
     })
 
+    it('should allow metadata to be changed in onUploadCreate', (done) => {
+      const filename = 'foo.txt'
+      const server = new Server({
+        path: '/test/output',
+        datastore: new FileStore({directory}),
+        async onUploadCreate(_, res, upload) {
+          const metadata = {...upload.metadata, filename}
+          return {res, metadata}
+        },
+      })
+      const s = server.listen()
+      request(s)
+        .post(server.options.path)
+        .set('Tus-Resumable', TUS_RESUMABLE)
+        .set('Upload-Length', '4')
+        .expect(201)
+        .then((res) => {
+          request(s)
+            .head(removeProtocol(res.headers.location))
+            .set('Tus-Resumable', TUS_RESUMABLE)
+            .expect(200)
+            .then((r) => {
+              const metadata = Metadata.parse(r.headers['upload-metadata'])
+              assert.equal(metadata.filename, filename)
+              done()
+            })
+        })
+    })
+
     it('should call onUploadFinish and return its error to the client', (done) => {
       const server = new Server({
         path: '/test/output',