feat(gcs): enumerate objects (#137)

With the ability to enumerate objects, it becomes possible to delete
non-empty buckets (by enumerating the objects in the buckets, deleting
them individually, and then deleting the buckets).

So this PR introduces a new test function `createBucketWithTearDown`
that creates a bucket and deletes it when the test completes.

Most of this PR is modifying the tests to use this method, which means
that all tests now completely clean up the resources that they create.

Author: brianquinlan

packages/google_cloud_storage/lib/src/client.dart

@@ -109,14 +109,18 @@ final class Storage {
   /// `"noAcl"` (the default) omits the `owner`, `acl`, and `defaultObjectAcl`
   /// properties.
   ///
-  /// [softDeleted] filters the returned buckets to those that are soft deleted.
+  /// If [softDeleted] is `true`, then the stream will include **only**
+  /// [soft-deleted buckets][]. If `false`, then the stream will not include
+  /// soft-deleted buckets.
   ///
   /// [maxResults] limits the number of buckets returned in a single API
   /// response. This does not affect the output but does affect the trade-off
   /// between latency and memory usage; a larger value will result in fewer
   /// network requests but higher memory usage.
   ///
   /// See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/buckets/list).
+  ///
+  /// [soft-deleted buckets]: https://cloud.google.com/storage/docs/soft-delete
   Stream<BucketMetadata> listBuckets({
     String? prefix,
     String? projection,
@@ -143,6 +147,60 @@ final class Storage {
     } while (nextPageToken != null);
   }
 
+  /// A stream of objects contained in [bucket] in lexicographical order by
+  /// name.
+  ///
+  /// If [softDeleted] is `true`, then the stream will include **only**
+  /// [soft-deleted objects][]. If `false`, then the stream will not include
+  /// soft-deleted objects.
+  ///
+  /// [projection] controls the level of detail returned in the response. A
+  /// value of `"full"` returns all object properties, while a value of
+  /// `"noAcl"` (the default) omits the `owner` and `acl` properties.
+  ///
+  /// If set, [userProject] is the project to be billed for this request. This
+  /// argument must be set for [Requester Pays] buckets.
+  ///
+  /// [maxResults] limits the number of objects returned in a single API
+  /// response. This does not affect the output but does affect the trade-off
+  /// between latency and memory usage; a larger value will result in fewer
+  /// network requests but higher memory usage.
+  ///
+  /// See [API reference docs](https://cloud.google.com/storage/docs/json_api/v1/objects/list).
+  ///
+  /// [soft-deleted objects]: https://cloud.google.com/storage/docs/soft-delete
+  /// [Requester Pays]: https://docs.cloud.google.com/storage/docs/requester-pays
+  Stream<ObjectMetadata> listObjects(
+    String bucket, {
+    bool? softDeleted,
+    String? projection,
+    String? userProject,
+    int? maxResults,
+  }) async* {
+    String? nextPageToken;
+
+    do {
+      final url = Uri(
+        scheme: 'https',
+        host: 'storage.googleapis.com',
+        pathSegments: ['storage', 'v1', 'b', bucket, 'o'],
+        queryParameters: {
+          'softDeleted': ?softDeleted?.toString(),
+          'maxResults': ?maxResults?.toString(),
+          'pageToken': ?nextPageToken,
+          'projection': ?projection,
+          'userProject': ?userProject,
+        },
+      );
+      final json = await _serviceClient.get(url);
+      nextPageToken = json['nextPageToken'] as String?;
+
+      for (final object in json['items'] as List<Object?>? ?? const []) {
+        yield objectMetadataFromJson(object as Map<String, Object?>);
+      }
+    } while (nextPageToken != null);
+  }
+
   /// Update a Google Cloud Storage bucket.
   ///
   /// This operation is idempotent if [ifMetagenerationMatch] is set.

packages/google_cloud_storage/test/delete_object_test.dart

@@ -55,12 +55,10 @@ void main() async {
         'delete_object_success',
       );
       addTearDown(testClient.endTest);
-      final bucketName = bucketNameWithTearDown(
+      final bucketName = await createBucketWithTearDown(
         storage,
         'delete_object_success',
       );
-
-      await storage.createBucket(BucketMetadata(name: bucketName));
       await storage.insertObject(
         bucketName,
         'object.txt',
@@ -82,13 +80,11 @@ void main() async {
         'delete_object_not_found',
       );
       addTearDown(testClient.endTest);
-      final bucketName = bucketNameWithTearDown(
+      final bucketName = await createBucketWithTearDown(
         storage,
         'delete_object_not_found',
       );
 
-      await storage.createBucket(BucketMetadata(name: bucketName));
-
       expect(
         () => storage.deleteObject(bucketName, 'non-existent.txt'),
         throwsA(isA<NotFoundException>()),
@@ -101,27 +97,20 @@ void main() async {
         'delete_object_with_generation',
       );
       addTearDown(testClient.endTest);
-      final bucketName = bucketNameWithTearDown(
+      final bucketName = await createBucketWithTearDown(
         storage,
         'delete_object_with_generation',
+        metadata: BucketMetadata(versioning: BucketVersioning(enabled: true)),
       );
-
-      await storage.createBucket(
-        BucketMetadata(
-          name: bucketName,
-          versioning: BucketVersioning(enabled: true),
-        ),
-      );
-
       final obj1 = await storage.insertObject(
         bucketName,
         'object.txt',
-        utf8.encode('v1'),
+        utf8.encode('Text'),
       );
       final obj2 = await storage.insertObject(
         bucketName,
         'object.txt',
-        utf8.encode('v2'),
+        utf8.encode('More text'),
       );
 
       // Verify both exist
@@ -159,13 +148,6 @@ void main() async {
         'object.txt',
         generation: obj2.generation,
       );
-
-      // Cleanup v2
-      await storage.deleteObject(
-        bucketName,
-        'object.txt',
-        generation: obj2.generation,
-      );
     });
 
     test('with ifGenerationMatch success', () async {
@@ -174,12 +156,10 @@ void main() async {
         'delete_object_with_if_generation_match_success',
       );
       addTearDown(testClient.endTest);
-      final bucketName = bucketNameWithTearDown(
+      final bucketName = await createBucketWithTearDown(
         storage,
         'delete_object_with_if_generation_match_success',
       );
-
-      await storage.createBucket(BucketMetadata(name: bucketName));
       final obj = await storage.insertObject(
         bucketName,
         'object.txt',
@@ -205,12 +185,10 @@ void main() async {
         'delete_object_with_if_generation_match_failure',
       );
       addTearDown(testClient.endTest);
-      final bucketName = bucketNameWithTearDown(
+      final bucketName = await createBucketWithTearDown(
         storage,
         'delete_object_with_if_generation_match_failure',
       );
-
-      await storage.createBucket(BucketMetadata(name: bucketName));
       final obj = await storage.insertObject(
         bucketName,
         'object.txt',