feat(storage): add content-encoding support for uploads

[Athaxv]

Add content-encoding support for uploads

🔍 Description

• Add contentEncoding to FileOptions and apply the Content-Encoding header for uploads and signed uploads when provided.
• Ensure streaming / non-FormData uploads can declare gzip (or other) encodings.
• Add unit coverage verifying the header is sent.

What changed?

• Extended FileOptions with an optional contentEncoding field.
• Updated StorageFileApi upload and uploadToSignedUrl to set the Content-Encoding header when contentEncoding is passed.
• Added tests in storageFileApi.test.ts to assert the correct headers are sent for uploads using streams/buffers.

Why was this change needed?

• Storage currently doesn’t expose a way to set Content-Encoding on uploads.

• This is required to support use cases where files are uploaded already compressed (e.g. gzip) from Edge Functions and should be served correctly in browsers.

• Implements the feature requested in Support for setting the Content-Encoding header when uploading files to Storage #1883.

• No breaking changes. The new contentEncoding option is optional and only affects behavior when explicitly provided.

[mandarini]

Thanks for the PR @Athaxv! This is a great feature request and the client-side implementation looks good.

However, the storage server's REST API (/object/* routes) doesn't currently handle the Content-Encoding header. The client will send it, but the server will ignore it.

Specifically, in the storage server:

• fileUploadFromRequest() only extracts content-type, cache-control, x-robots-tag, and x-metadata headers
• The uploadObject() backend method doesn't have a contentEncoding parameter
• The S3 Upload params don't include ContentEncoding

The S3-compatible API routes (/s3/*) already support Content-Encoding, it's just the REST API that's missing this.

You can open a feature request on the supabase/storage repo to add Content-Encoding support to the REST API routes. Once that's implemented and released, we can merge this PR and the feature will work end-to-end.

You can reference this PR and issue #1883 in that request. The server-side changes would involve:

1. Extracting content-encoding header in fileUploadFromRequest()
2. Adding contentEncoding parameter to the uploadObject() method
3. Passing ContentEncoding to the S3 Upload params

I'll keep this PR open and we can revisit once the server-side support lands.