feat(tus): return created object id via X-Supabase-Object-Id response header (closes #647)

[61465]

What

Fixes #647 — TUS clients
had no way to resolve the storage row they just wrote without issuing a
follow-up list or search request.

Maintainer @fenos pre-approved the pattern on the issue in 2024:

Yes! we could send the object_id back via a header like the upload-id.
totally a legit enhancement

Change

In onUploadFinish (src/http/routes/tus/lifecycle.ts):

- await uploader.completeUpload({ ... })
+ const completed = await uploader.completeUpload({ ... })

- return { headers: { 'Tus-Complete': '1' } }
+ const responseHeaders: Record<string, string> = { 'Tus-Complete': '1' }
+ if (completed?.obj?.id) {
+   responseHeaders['X-Supabase-Object-Id'] = String(completed.obj.id)
+ }
+ return { headers: responseHeaders }

• Header name follows the existing kebab-case convention
  (Tus-Complete, Upload-ID).
• Prefixed with X-Supabase- so it is unambiguously distinct from TUS
  protocol headers.
• Gracefully omitted if completeUpload returns without an id — the
  header is never emitted as the string "undefined".

Tests

Two new vitest cases in src/http/routes/tus/lifecycle.test.ts:

1. includes X-Supabase-Object-Id when the created object id is available
   — happy path with a UUID.
2. omits X-Supabase-Object-Id gracefully when completeUpload returns no id
   — defensive fallback.

Both use the existing createRawTusRequest helper + spies on Uploader.prototype.completeUpload,
so they run without needing storage infrastructure.

CORS note

Verified src/app.ts:25 — CORS is handled by Kong upstream (// kong should take care of cors). No Access-Control-Expose-Headers change needed in
the app itself; operators who front the service without Kong already
configure header exposure at the reverse proxy.

Impact

• Backwards compatible — adds a header, removes nothing. Older clients
  that don't read it see no change.
• Zero behavior change for failure paths. The header is only set when
  completed.obj.id is non-empty.
• Removes one round-trip from every TUS client flow that needs to look up
  the object after upload — common in file-manager UIs, workflow
  orchestrators, and S3-to-TUS bridges.