chore: improved storage errors

[dnywh]

What kind of change does this PR introduce?

Support gets a lot of requests for help around bucket vs global file size limits. For example:

I've upgraded to the pro tier so I can upload file sizes larger than 50MB. For some reason, when I try to upload via API, I keep getting a statusCode: "413", error: "Payload too large", message: "The object exceeded the maximum allowed size"

supabase/supabase#38272 introduces UI clarity for Studio users. This PR introduces clarity at this error-message level, for API users.

What is the current behavior?

A user who forgets they have a bucket limit set will get a vague error message like:

The object exceeded the maximum allowed size

That isn’t very helpful, especially with the potential footguns of global and bucket-specific limits.

What is the new behavior?

Clearer error message with bucket and/or global file size limits inline. For example, using that same scenario above:

The object exceeded the maximum allowed size for bucket "my-bucket" (50 MB). This bucket has a lower limit than your global setting (100 MB). You can increase the bucket limit in your Storage settings.

It also makes the global-only situation a bit clearer:

The object exceeded the maximum allowed size in your global settings (100 MB)

And if no context is provided:

The object exceeded the maximum allowed size

Additional context and outstanding questions

• This introduces the need for passing through some new information: context?: { bucketName?: string; bucketLimit?: number; globalLimit?: number })
• This is my first PR here so please test thoroughly :)
• Does this cover CLI use cases? Are there any other clients that need consideration?
• Is it okay to expose bucketName,bucketLimit, and globalLimit to API users? Or do we need to check the user’s permissions per project?

[coveralls]

Pull Request Test Coverage Report for Build 17481645045

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 225 of 246 (91.46%) changed or added relevant lines in 10 files are covered.
• 4 unchanged lines in 2 files lost coverage.
• Overall coverage increased (+0.08%) to 76.305%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/storage/storage.ts	0	4	0.0%
src/storage/uploader.ts	21	25	84.0%
src/http/routes/s3/commands/put-object.ts	44	49	89.8%
src/storage/protocols/s3/byte-limit-stream.ts	8	16	50.0%

Files with Coverage Reduction	New Missed Lines	%
src/storage/storage.ts	1	66.2%
src/test/common.ts	3	95.76%

Totals
Change from base Build 16888447455:	0.08%
Covered Lines:	20993
Relevant Lines:	27275

---

💛 - Coveralls