From da03dc078bb4631312b6da4a49659d303620d423 Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Thu, 25 Jun 2026 09:41:36 -0300 Subject: [PATCH 1/5] feat(storage): add purge_cache and purge_bucket_cache capabilities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Registers two new canonical storage capabilities sourced from supabase/supabase-js#2429: - storage.file_buckets.purge_cache — invalidate CDN cache for a single object via StorageFileApi.purgeCache(path) - storage.file_buckets.purge_bucket_cache — invalidate CDN cache for an entire bucket via StorageBucketApi.purgeBucketCache() Both require a service_role JWT and the purgeCache tenant feature. --- capabilities/storage.yaml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/capabilities/storage.yaml b/capabilities/storage.yaml index 2eb92fd..c5c0a5f 100644 --- a/capabilities/storage.yaml +++ b/capabilities/storage.yaml @@ -178,6 +178,14 @@ features: name: URL Cache Invalidation Nonce description: Append a cache-busting nonce to public and signed URLs to bypass CDN caching for a specific file version. group: file_buckets + - id: storage.file_buckets.purge_cache + name: Purge File CDN Cache + description: Invalidate the CDN cache for a specific object in a bucket. Requires service_role JWT and the purgeCache tenant feature to be enabled. + group: file_buckets + - id: storage.file_buckets.purge_bucket_cache + name: Purge Bucket CDN Cache + description: Invalidate the CDN cache for all objects in a bucket. Requires service_role JWT and the purgeCache tenant feature to be enabled. + group: file_buckets - id: storage.analytics.create_analytics_bucket name: Create Analytics Bucket description: Create a bucket backed by Apache Iceberg table format for structured analytical data storage. From df1d84acc32bb8b4da7d0958c82ca14e27601b09 Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Thu, 25 Jun 2026 09:44:36 -0300 Subject: [PATCH 2/5] docs(storage): add spec files for purge_cache and purge_bucket_cache Adds human-readable specs for the two new CDN cache purge capabilities: - specs/storage/file_buckets/purge_cache.md - specs/storage/file_buckets/purge_bucket_cache.md Covers the HTTP endpoint, behavioral contract, service_role requirement, purgeCache tenant feature prerequisite, error conditions, and cross-links. --- .../file_buckets/purge_bucket_cache.md | 33 +++++++++++++++++ specs/storage/file_buckets/purge_cache.md | 35 +++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 specs/storage/file_buckets/purge_bucket_cache.md create mode 100644 specs/storage/file_buckets/purge_cache.md diff --git a/specs/storage/file_buckets/purge_bucket_cache.md b/specs/storage/file_buckets/purge_bucket_cache.md new file mode 100644 index 0000000..5288645 --- /dev/null +++ b/specs/storage/file_buckets/purge_bucket_cache.md @@ -0,0 +1,33 @@ +# Purge Bucket CDN Cache + +Invalidate the CDN cache for all objects in a bucket. The server issues a CDN invalidation scoped to the entire bucket and returns a success message. + +## API + +Spec: [https://github.com/supabase/storage/blob/master/src/http/routes/cdn](https://github.com/supabase/storage/blob/master/src/http/routes/cdn) + +- `DELETE /cdn/{bucketName}` + +## Behavior + +Accepts a bucket ID. Sends `DELETE /cdn/{bucketName}` to the Storage API. On success the server returns `{ message: "success" }` and the CDN edge cache for the entire bucket is invalidated. The stored files themselves are not modified or deleted. + +## Prerequisites + +- The caller must be authenticated with a `service_role` JWT. The endpoint enforces `service_role` — requests made with the anon key or a user JWT are rejected. +- The `purgeCache` tenant feature must be enabled. On self-hosted deployments, `CDN_PURGE_ENDPOINT_URL` must be configured in the Storage service; if not, the server returns an error even with a valid `service_role` key. + +## Errors + +- Auth error — the JWT is absent, expired, or is not a `service_role` key. +- Feature not enabled — the `purgeCache` tenant feature is off or `CDN_PURGE_ENDPOINT_URL` is not set on the Storage instance. +- Not found — the bucket does not exist. + +## Notes + +This invalidates the CDN layer only. The bucket and its objects remain intact. The next request to any previously-cached object in the bucket will be served from the origin. + +## Related + +- [Purge File CDN Cache](purge_cache.md) — invalidate the CDN cache for a single object by exact path +- [URL Cache Invalidation Nonce](url_cache_nonce.md) — client-side alternative: append a nonce to URLs to bypass caching without server-side invalidation diff --git a/specs/storage/file_buckets/purge_cache.md b/specs/storage/file_buckets/purge_cache.md new file mode 100644 index 0000000..502face --- /dev/null +++ b/specs/storage/file_buckets/purge_cache.md @@ -0,0 +1,35 @@ +# Purge File CDN Cache + +Invalidate the CDN cache for a single object in a bucket. The server issues a CDN invalidation for the named path and returns a success message. + +## API + +Spec: [https://github.com/supabase/storage/blob/master/src/http/routes/cdn](https://github.com/supabase/storage/blob/master/src/http/routes/cdn) + +- `DELETE /cdn/{bucketName}/{objectPath}` + +## Behavior + +Accepts a bucket name (bound at the client level via the bucket accessor) and an exact object path. Sends `DELETE /cdn/{bucketName}/{objectPath}` to the Storage API. On success the server returns `{ message: "success" }` and the CDN edge cache for that object is invalidated. The stored file itself is not modified or deleted. + +The path must be the exact object key relative to the bucket root (e.g. `folder/avatar.png`). There is no wildcard or prefix matching: only the single named object is invalidated. + +## Prerequisites + +- The caller must be authenticated with a `service_role` JWT. The endpoint enforces `service_role` — requests made with the anon key or a user JWT are rejected. +- The `purgeCache` tenant feature must be enabled. On self-hosted deployments, `CDN_PURGE_ENDPOINT_URL` must be configured in the Storage service; if not, the server returns an error even with a valid `service_role` key. + +## Errors + +- Auth error — the JWT is absent, expired, or is not a `service_role` key. +- Feature not enabled — the `purgeCache` tenant feature is off or `CDN_PURGE_ENDPOINT_URL` is not set on the Storage instance. +- Not found — the object path does not exist in the bucket (server-dependent behavior; may return 404 or succeed silently). + +## Notes + +There is no batch or prefix-purge variant for objects. To invalidate multiple objects, call this feature once per path. For bulk invalidation, prefer a server-side solution (e.g. an Edge Function) rather than N sequential client calls. + +## Related + +- [Purge Bucket CDN Cache](purge_bucket_cache.md) — invalidate the CDN cache for all objects in a bucket +- [URL Cache Invalidation Nonce](url_cache_nonce.md) — client-side alternative: append a nonce to the URL to bypass CDN caching without a server-side invalidation From 100dcbe7d5e9ef65bcc5ef10e0b84d78452abdaf Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Thu, 25 Jun 2026 10:26:28 -0300 Subject: [PATCH 3/5] docs(storage): trim specs to SDK-only behavior --- .../file_buckets/purge_bucket_cache.md | 22 +++-------------- specs/storage/file_buckets/purge_cache.md | 24 +++---------------- 2 files changed, 6 insertions(+), 40 deletions(-) diff --git a/specs/storage/file_buckets/purge_bucket_cache.md b/specs/storage/file_buckets/purge_bucket_cache.md index 5288645..4971929 100644 --- a/specs/storage/file_buckets/purge_bucket_cache.md +++ b/specs/storage/file_buckets/purge_bucket_cache.md @@ -1,33 +1,17 @@ # Purge Bucket CDN Cache -Invalidate the CDN cache for all objects in a bucket. The server issues a CDN invalidation scoped to the entire bucket and returns a success message. - ## API -Spec: [https://github.com/supabase/storage/blob/master/src/http/routes/cdn](https://github.com/supabase/storage/blob/master/src/http/routes/cdn) - - `DELETE /cdn/{bucketName}` ## Behavior -Accepts a bucket ID. Sends `DELETE /cdn/{bucketName}` to the Storage API. On success the server returns `{ message: "success" }` and the CDN edge cache for the entire bucket is invalidated. The stored files themselves are not modified or deleted. - -## Prerequisites - -- The caller must be authenticated with a `service_role` JWT. The endpoint enforces `service_role` — requests made with the anon key or a user JWT are rejected. -- The `purgeCache` tenant feature must be enabled. On self-hosted deployments, `CDN_PURGE_ENDPOINT_URL` must be configured in the Storage service; if not, the server returns an error even with a valid `service_role` key. - -## Errors - -- Auth error — the JWT is absent, expired, or is not a `service_role` key. -- Feature not enabled — the `purgeCache` tenant feature is off or `CDN_PURGE_ENDPOINT_URL` is not set on the Storage instance. -- Not found — the bucket does not exist. +Accepts a bucket ID and issues a `DELETE` to `/cdn/{bucketName}`. -## Notes +Returns `{ data: { message }, error }`. Server errors are surfaced in `error`; `data` is `null` on failure. -This invalidates the CDN layer only. The bucket and its objects remain intact. The next request to any previously-cached object in the bucket will be served from the origin. +Accepts an optional fetch parameters argument (e.g. an `AbortController` signal) that is forwarded to the underlying request. ## Related - [Purge File CDN Cache](purge_cache.md) — invalidate the CDN cache for a single object by exact path -- [URL Cache Invalidation Nonce](url_cache_nonce.md) — client-side alternative: append a nonce to URLs to bypass caching without server-side invalidation diff --git a/specs/storage/file_buckets/purge_cache.md b/specs/storage/file_buckets/purge_cache.md index 502face..4d65ca7 100644 --- a/specs/storage/file_buckets/purge_cache.md +++ b/specs/storage/file_buckets/purge_cache.md @@ -1,35 +1,17 @@ # Purge File CDN Cache -Invalidate the CDN cache for a single object in a bucket. The server issues a CDN invalidation for the named path and returns a success message. - ## API -Spec: [https://github.com/supabase/storage/blob/master/src/http/routes/cdn](https://github.com/supabase/storage/blob/master/src/http/routes/cdn) - - `DELETE /cdn/{bucketName}/{objectPath}` ## Behavior -Accepts a bucket name (bound at the client level via the bucket accessor) and an exact object path. Sends `DELETE /cdn/{bucketName}/{objectPath}` to the Storage API. On success the server returns `{ message: "success" }` and the CDN edge cache for that object is invalidated. The stored file itself is not modified or deleted. - -The path must be the exact object key relative to the bucket root (e.g. `folder/avatar.png`). There is no wildcard or prefix matching: only the single named object is invalidated. - -## Prerequisites - -- The caller must be authenticated with a `service_role` JWT. The endpoint enforces `service_role` — requests made with the anon key or a user JWT are rejected. -- The `purgeCache` tenant feature must be enabled. On self-hosted deployments, `CDN_PURGE_ENDPOINT_URL` must be configured in the Storage service; if not, the server returns an error even with a valid `service_role` key. - -## Errors - -- Auth error — the JWT is absent, expired, or is not a `service_role` key. -- Feature not enabled — the `purgeCache` tenant feature is off or `CDN_PURGE_ENDPOINT_URL` is not set on the Storage instance. -- Not found — the object path does not exist in the bucket (server-dependent behavior; may return 404 or succeed silently). +Accepts an object path relative to the bucket root. The SDK prepends the bucket name to form the full path and issues a `DELETE` to `/cdn/{bucketName}/{objectPath}`. -## Notes +Returns `{ data: { message }, error }`. Server errors are surfaced in `error`; `data` is `null` on failure. -There is no batch or prefix-purge variant for objects. To invalidate multiple objects, call this feature once per path. For bulk invalidation, prefer a server-side solution (e.g. an Edge Function) rather than N sequential client calls. +Accepts an optional fetch parameters argument (e.g. an `AbortController` signal) that is forwarded to the underlying request. ## Related - [Purge Bucket CDN Cache](purge_bucket_cache.md) — invalidate the CDN cache for all objects in a bucket -- [URL Cache Invalidation Nonce](url_cache_nonce.md) — client-side alternative: append a nonce to the URL to bypass CDN caching without a server-side invalidation From b150e4d23ed4a6e33185cff3fa02aa819321c8ed Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Thu, 25 Jun 2026 10:27:30 -0300 Subject: [PATCH 4/5] docs(storage): remove spec files for purge_cache and purge_bucket_cache --- .../storage/file_buckets/purge_bucket_cache.md | 17 ----------------- specs/storage/file_buckets/purge_cache.md | 17 ----------------- 2 files changed, 34 deletions(-) delete mode 100644 specs/storage/file_buckets/purge_bucket_cache.md delete mode 100644 specs/storage/file_buckets/purge_cache.md diff --git a/specs/storage/file_buckets/purge_bucket_cache.md b/specs/storage/file_buckets/purge_bucket_cache.md deleted file mode 100644 index 4971929..0000000 --- a/specs/storage/file_buckets/purge_bucket_cache.md +++ /dev/null @@ -1,17 +0,0 @@ -# Purge Bucket CDN Cache - -## API - -- `DELETE /cdn/{bucketName}` - -## Behavior - -Accepts a bucket ID and issues a `DELETE` to `/cdn/{bucketName}`. - -Returns `{ data: { message }, error }`. Server errors are surfaced in `error`; `data` is `null` on failure. - -Accepts an optional fetch parameters argument (e.g. an `AbortController` signal) that is forwarded to the underlying request. - -## Related - -- [Purge File CDN Cache](purge_cache.md) — invalidate the CDN cache for a single object by exact path diff --git a/specs/storage/file_buckets/purge_cache.md b/specs/storage/file_buckets/purge_cache.md deleted file mode 100644 index 4d65ca7..0000000 --- a/specs/storage/file_buckets/purge_cache.md +++ /dev/null @@ -1,17 +0,0 @@ -# Purge File CDN Cache - -## API - -- `DELETE /cdn/{bucketName}/{objectPath}` - -## Behavior - -Accepts an object path relative to the bucket root. The SDK prepends the bucket name to form the full path and issues a `DELETE` to `/cdn/{bucketName}/{objectPath}`. - -Returns `{ data: { message }, error }`. Server errors are surfaced in `error`; `data` is `null` on failure. - -Accepts an optional fetch parameters argument (e.g. an `AbortController` signal) that is forwarded to the underlying request. - -## Related - -- [Purge Bucket CDN Cache](purge_bucket_cache.md) — invalidate the CDN cache for all objects in a bucket From 7f54cc13bccf786e637629b3a9c98d6df067c819 Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Thu, 25 Jun 2026 10:28:14 -0300 Subject: [PATCH 5/5] docs(storage): use 'capability' term in purge cache descriptions --- capabilities/storage.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/capabilities/storage.yaml b/capabilities/storage.yaml index c5c0a5f..13e8d79 100644 --- a/capabilities/storage.yaml +++ b/capabilities/storage.yaml @@ -180,11 +180,11 @@ features: group: file_buckets - id: storage.file_buckets.purge_cache name: Purge File CDN Cache - description: Invalidate the CDN cache for a specific object in a bucket. Requires service_role JWT and the purgeCache tenant feature to be enabled. + description: Invalidate the CDN cache for a specific object in a bucket. Requires service_role JWT and the purgeCache tenant capability to be enabled. group: file_buckets - id: storage.file_buckets.purge_bucket_cache name: Purge Bucket CDN Cache - description: Invalidate the CDN cache for all objects in a bucket. Requires service_role JWT and the purgeCache tenant feature to be enabled. + description: Invalidate the CDN cache for all objects in a bucket. Requires service_role JWT and the purgeCache tenant capability to be enabled. group: file_buckets - id: storage.analytics.create_analytics_bucket name: Create Analytics Bucket