fix(storage): make dedicated storage host opt-in via useNewHostname flag

[grdsdev]

Summary

storage_client 2.5.0 introduced _transformStorageUrl() which unconditionally rewrites all storage URLs to use the dedicated storage host (*.storage.supabase.co). This host is not available on all projects, silently breaking every storage operation with StorageException: Invalid Storage request.

This PR implements Option B: make the URL transformation opt-in (useNewHostname defaults to false). Projects with the dedicated storage host enabled can opt in via StorageClientOptions(useNewHostname: true) in Supabase.initialize().

Changes

• storage_client: Added useNewHostname parameter to SupabaseStorageClient (defaults to false)
• supabase: Added useNewHostname field to StorageClientOptions, threaded through to SupabaseStorageClient
• Tests: Reorganized URL construction tests into default behavior (useNewHostname: false) and opt-in behavior (useNewHostname: true) groups; added 6 new tests covering the default no-transform path

Root Cause

• File: packages/storage_client/lib/src/storage_client.dart:45
• Issue: _transformStorageUrl(url) was called unconditionally at construction time
• Fix: useNewHostname ? _transformStorageUrl(url) : url

Testing

Reproduction Test

All 35 tests in storage_client pass, including 12 URL construction tests that explicitly verify both the default (no transform) and opt-in (transform) paths.

Test Coverage

• 6 new tests: default behavior does not transform any Supabase host URLs
• 6 existing tests: opt-in behavior preserves all original transformation cases
• All other storage_client and supabase package tests continue to pass

Manual Testing

• Test with a project that does NOT have *.storage.supabase.co enabled (default should work)
• Test with a project that has the dedicated host enabled and useNewHostname: true

Risk Assessment

• Breaking changes: Yes — projects relying on the automatic URL transformation will need to add StorageClientOptions(useNewHostname: true). This is intentional (Option B).
• Migration: Add storageOptions: StorageClientOptions(useNewHostname: true) to Supabase.initialize() if your project has the dedicated storage host enabled.
• Performance impact: Negligible (single boolean check at construction time)

Acceptance Criteria

• Projects without dedicated storage host can use legacy URL format (default behavior)
• useNewHostname: true flag available from StorageClientOptions through to SupabaseStorageClient
• All existing URL transformation tests continue to pass (as opt-in tests)
• New tests cover the useNewHostname: false default path
• No breaking changes to the public StorageFileApi surface

Linear Issue

Closes: SDK-789
GitHub: #1328

---

🤖 Generated with Claude Code /take

[Copilot]

Pull request overview

This PR addresses a regression in storage_client 2.5.0 where storage base URLs were always rewritten to the dedicated storage hostname (*.storage.supabase.co), breaking projects that don’t have that host enabled. It makes the rewrite behavior opt-in via a useNewHostname flag, defaulting to false, and wires the option through the supabase package.

Changes:

• Add useNewHostname (default false) to SupabaseStorageClient to gate _transformStorageUrl() behind an opt-in flag.
• Expose useNewHostname via StorageClientOptions in supabase and pass it through when initializing the storage client.
• Reorganize and expand URL-construction tests to cover both default (no transform) and opt-in (transform) behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
packages/supabase/lib/src/supabase_client_options.dart	Adds StorageClientOptions.useNewHostname with documentation and default false.
packages/supabase/lib/src/supabase_client.dart	Threads useNewHostname from StorageClientOptions into SupabaseStorageClient initialization.
packages/storage_client/lib/src/storage_client.dart	Makes legacy→dedicated host rewrite conditional on useNewHostname.
packages/storage_client/test/basic_test.dart	Splits URL construction tests into default vs opt-in groups and adds coverage for the default path.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.