feat(storage): add purgeCache to invalidate CDN cache for a single object

Author: spydon

packages/storage_client/lib/src/storage_file_api.dart

@@ -695,6 +695,37 @@ class StorageFileApi {
     return fileObjects;
   }
 
+  /// Purges the CDN cache for a single object.
+  ///
+  /// Invalidates the CDN cache for the object at [path] (relative to the
+  /// bucket). There is no wildcard or recursion; pass the exact path of the
+  /// object to invalidate. For example: `purgeCache('folder/avatar.png')`.
+  ///
+  /// When [transformations] is `true`, only the resized/formatted variants are
+  /// purged, leaving the original cached file intact. When omitted the object
+  /// cache is purged.
+  ///
+  /// Requires the service-role key and the tenant `purgeCache` feature to be
+  /// enabled on the storage server.
+  Future<String> purgeCache(
+    String path, {
+    bool transformations = false,
+  }) async {
+    final finalPath = _getFinalPath(path);
+    var requestUrl = Uri.parse('$url/cdn/$finalPath');
+    if (transformations) {
+      requestUrl = requestUrl.replace(
+        queryParameters: {'transformations': 'true'},
+      );
+    }
+    final response = await _storageFetch.delete(
+      requestUrl.toString(),
+      {},
+      options: _fetchOptions,
+    );
+    return (response as Map<String, dynamic>)['message'] as String;
+  }
+
   /// Lists all the files within a bucket.
   ///
   /// [path] The folder path.

packages/storage_client/test/basic_test.dart

@@ -248,6 +248,37 @@ void main() {
       expect(response, 'Move');
     });
 
+    test('should purgeCache issuing DELETE to /cdn/{bucket}/{path}', () async {
+      customHttpClient.response = {'message': 'success'};
+
+      final response = await client.from('public').purgeCache('folder/a.txt');
+
+      final request = customHttpClient.receivedRequests.last;
+      expect(request.method, 'DELETE');
+      expect(
+        request.url.toString(),
+        endsWith('/storage/v1/cdn/public/folder/a.txt'),
+      );
+      expect(request.url.query, isEmpty);
+      expect(response, 'success');
+    });
+
+    test('should purgeCache with transformations query param', () async {
+      customHttpClient.response = {'message': 'success'};
+
+      final response = await client
+          .from('public')
+          .purgeCache('folder/a.txt', transformations: true);
+
+      final request = customHttpClient.receivedRequests.last;
+      expect(request.method, 'DELETE');
+      expect(
+        request.url.queryParameters['transformations'],
+        'true',
+      );
+      expect(response, 'success');
+    });
+
     test('should createSignedUrl file', () async {
       customHttpClient.response = {'signedURL': '/signed/url'};
 

sdk-compliance.yaml

@@ -438,6 +438,10 @@ features:
   storage.file_buckets.copy: implemented
   storage.file_buckets.copy_cross_bucket: implemented
   storage.file_buckets.remove: implemented
+  storage.file_buckets.purge_cache:
+    status: implemented
+    symbols:
+      - StorageFileApi.purgeCache
   storage.file_buckets.create_signed_url:
     status: implemented
     symbols: