feat(storage): support soft-deleted objects

google/cloud/storage/client.h

@@ -991,7 +991,8 @@ class Client {
    * @param options a list of optional query parameters and/or request headers.
    *     Valid types for this operation include `Generation`,
    *     `IfGenerationMatch`, `IfGenerationNotMatch`, `IfMetagenerationMatch`,
-   *     `IfMetagenerationNotMatch`, `Projection`, and `UserProject`.
+   *     `IfMetagenerationNotMatch`, `SoftDeleted`, `Projection`, and
+   *     `UserProject`.
    *
    * @par Idempotency
    * This is a read-only operation and is always idempotent.
@@ -1017,7 +1018,8 @@ class Client {
    * @param options a list of optional query parameters and/or request headers.
    *     Valid types for this operation include `MaxResults`, `Prefix`,
    *     `Delimiter`, `IncludeTrailingDelimiter`, `StartOffset`, `EndOffset`,
-   *     `MatchGlob`, `Projection`, `UserProject`, and `Versions`.
+   *     `MatchGlob`, `Projection`, `SoftDeleted`, `UserProject`, and
+   *     `Versions`.
    *
    * @par Idempotency
    * This is a read-only operation and is always idempotent.

google/cloud/storage/google_cloud_cpp_storage.bzl

@@ -141,6 +141,7 @@ google_cloud_cpp_storage_hdrs = [
     "retry_policy.h",
     "service_account.h",
     "signed_url_options.h",
+    "soft_deleted.h",
     "storage_class.h",
     "upload_options.h",
     "user_ip_option.h",

google/cloud/storage/google_cloud_cpp_storage.cmake

@@ -235,6 +235,7 @@ add_library(
     service_account.cc
     service_account.h
     signed_url_options.h
+    soft_deleted.h
     storage_class.h
     upload_options.h
     user_ip_option.h

google/cloud/storage/internal/grpc/object_request_parser.cc

@@ -337,6 +337,9 @@ google::storage::v2::GetObjectRequest ToProto(
   result.set_generation(request.GetOption<storage::Generation>().value_or(0));
   auto projection = request.GetOption<storage::Projection>().value_or("");
   if (projection == "full") result.mutable_read_mask()->add_paths("*");
+  if (request.GetOption<storage::SoftDeleted>().value_or(false)) {
+    result.set_soft_deleted(true);
+  }
   return result;
 }
 
@@ -573,12 +576,15 @@ google::storage::v2::ListObjectsRequest ToProto(
   result.set_include_trailing_delimiter(
       request.GetOption<storage::IncludeTrailingDelimiter>().value_or(false));
   result.set_prefix(request.GetOption<storage::Prefix>().value_or(""));
-  result.set_versions(request.GetOption<storage::Versions>().value_or(""));
+  result.set_versions(request.GetOption<storage::Versions>().value_or(false));
   result.set_lexicographic_start(
       request.GetOption<storage::StartOffset>().value_or(""));
   result.set_lexicographic_end(
       request.GetOption<storage::EndOffset>().value_or(""));
   result.set_match_glob(request.GetOption<storage::MatchGlob>().value_or(""));
+  if (request.GetOption<storage::SoftDeleted>().value_or(false)) {
+    result.set_soft_deleted(true);
+  }
   return result;
 }
 

google/cloud/storage/internal/grpc/object_request_parser_test.cc

@@ -214,6 +214,20 @@ TEST(GrpcObjectRequestParser, DeleteObjectAllFields) {
   EXPECT_THAT(actual, IsProtoEqual(expected));
 }
 
+TEST(GrpcObjectRequestParser, GetObjectMetadata) {
+  google::storage::v2::GetObjectRequest expected;
+  EXPECT_TRUE(TextFormat::ParseFromString(
+      R"pb(
+        bucket: "projects/_/buckets/test-bucket" object: "test-object"
+      )pb",
+      &expected));
+
+  storage::internal::GetObjectMetadataRequest req("test-bucket", "test-object");
+
+  auto const actual = ToProto(req);
+  EXPECT_THAT(actual, IsProtoEqual(expected));
+}
+
 TEST(GrpcObjectRequestParser, GetObjectMetadataAllFields) {
   google::storage::v2::GetObjectRequest expected;
   EXPECT_TRUE(TextFormat::ParseFromString(
@@ -226,6 +240,7 @@ TEST(GrpcObjectRequestParser, GetObjectMetadataAllFields) {
         if_metageneration_match: 3
         if_metageneration_not_match: 4
         read_mask { paths: "*" }
+        soft_deleted: true
       )pb",
       &expected));
 
@@ -234,8 +249,7 @@ TEST(GrpcObjectRequestParser, GetObjectMetadataAllFields) {
       storage::Generation(7), storage::IfGenerationMatch(1),
       storage::IfGenerationNotMatch(2), storage::IfMetagenerationMatch(3),
       storage::IfMetagenerationNotMatch(4), storage::Projection("full"),
-      storage::UserProject("test-user-project"),
-      storage::UserProject("test-user-project"),
+      storage::SoftDeleted(true), storage::UserProject("test-user-project"),
       storage::QuotaUser("test-quota-user"), storage::UserIp("test-user-ip"));
 
   auto const actual = ToProto(req);
@@ -871,6 +885,20 @@ TEST(GrpcObjectRequestParser, WriteObjectResponseWithResource) {
                                    Pair("other-header", "other-value")));
 }
 
+TEST(GrpcObjectRequestParser, ListObjectsRequest) {
+  google::storage::v2::ListObjectsRequest expected;
+  ASSERT_TRUE(TextFormat::ParseFromString(
+      R"pb(
+        parent: "projects/_/buckets/test-bucket"
+      )pb",
+      &expected));
+
+  storage::internal::ListObjectsRequest req("test-bucket");
+
+  auto const actual = ToProto(req);
+  EXPECT_THAT(actual, IsProtoEqual(expected));
+}
+
 TEST(GrpcObjectRequestParser, ListObjectsRequestAllFields) {
   google::storage::v2::ListObjectsRequest expected;
   ASSERT_TRUE(TextFormat::ParseFromString(
@@ -885,6 +913,7 @@ TEST(GrpcObjectRequestParser, ListObjectsRequestAllFields) {
         lexicographic_start: "test/prefix/a"
         lexicographic_end: "test/prefix/abc"
         match_glob: "**/*.cc"
+        soft_deleted: true
       )pb",
       &expected));
 
@@ -895,7 +924,7 @@ TEST(GrpcObjectRequestParser, ListObjectsRequestAllFields) {
       storage::IncludeTrailingDelimiter(true), storage::Prefix("test/prefix"),
       storage::Versions(true), storage::StartOffset("test/prefix/a"),
       storage::EndOffset("test/prefix/abc"), storage::MatchGlob("**/*.cc"),
-      storage::UserProject("test-user-project"),
+      storage::SoftDeleted(true), storage::UserProject("test-user-project"),
       storage::QuotaUser("test-quota-user"), storage::UserIp("test-user-ip"));
 
   auto const actual = ToProto(req);

google/cloud/storage/internal/object_requests.h

@@ -24,6 +24,7 @@
 #include "google/cloud/storage/internal/hash_values.h"
 #include "google/cloud/storage/internal/http_response.h"
 #include "google/cloud/storage/object_metadata.h"
+#include "google/cloud/storage/soft_deleted.h"
 #include "google/cloud/storage/upload_options.h"
 #include "google/cloud/storage/version.h"
 #include "google/cloud/storage/well_known_parameters.h"
@@ -47,7 +48,8 @@ namespace internal {
 class ListObjectsRequest
     : public GenericRequest<ListObjectsRequest, MaxResults, Prefix, Delimiter,
                             IncludeTrailingDelimiter, StartOffset, EndOffset,
-                            MatchGlob, Projection, UserProject, Versions> {
+                            MatchGlob, Projection, SoftDeleted, UserProject,
+                            Versions> {
  public:
   ListObjectsRequest() = default;
   explicit ListObjectsRequest(std::string bucket_name)
@@ -87,7 +89,7 @@ class GetObjectMetadataRequest
     : public GenericObjectRequest<
           GetObjectMetadataRequest, Generation, IfGenerationMatch,
           IfGenerationNotMatch, IfMetagenerationMatch, IfMetagenerationNotMatch,
-          Projection, UserProject> {
+          Projection, SoftDeleted, UserProject> {
  public:
   using GenericObjectRequest::GenericObjectRequest;
 };

google/cloud/storage/internal/object_requests_test.cc

@@ -62,14 +62,16 @@ TEST(ObjectRequestsTest, ParseAclListFailure) {
 TEST(ObjectRequestsTest, List) {
   ListObjectsRequest request("my-bucket");
   EXPECT_EQ("my-bucket", request.bucket_name());
-  request.set_multiple_options(UserProject("my-project"), Prefix("foo/"));
+  request.set_multiple_options(UserProject("my-project"), Prefix("foo/"),
+                               SoftDeleted(true));
 
   std::ostringstream os;
   os << request;
   std::string actual = os.str();
   EXPECT_THAT(actual, HasSubstr("my-bucket"));
   EXPECT_THAT(actual, HasSubstr("userProject=my-project"));
   EXPECT_THAT(actual, HasSubstr("prefix=foo/"));
+  EXPECT_THAT(actual, HasSubstr("softDeleted=true"));
 }
 
 TEST(ObjectRequestsTest, ParseListResponse) {
@@ -146,14 +148,16 @@ TEST(ObjectRequestsTest, ParseListResponseFailureInItems) {
 
 TEST(ObjectRequestsTest, Get) {
   GetObjectMetadataRequest request("my-bucket", "my-object");
-  request.set_multiple_options(Generation(1), IfMetagenerationMatch(3));
+  request.set_multiple_options(Generation(1), IfMetagenerationMatch(3),
+                               SoftDeleted(true));
   std::ostringstream os;
   os << request;
   auto str = os.str();
   EXPECT_THAT(str, HasSubstr("my-bucket"));
   EXPECT_THAT(str, HasSubstr("my-object"));
   EXPECT_THAT(str, HasSubstr("generation=1"));
   EXPECT_THAT(str, HasSubstr("ifMetagenerationMatch=3"));
+  EXPECT_THAT(str, HasSubstr("softDeleted=true"));
 }
 
 TEST(ObjectRequestsTest, InsertObjectMedia) {

google/cloud/storage/soft_deleted.h

@@ -0,0 +1,40 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_SOFT_DELETED_H
+#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_SOFT_DELETED_H
+
+#include "google/cloud/storage/internal/well_known_parameters_impl.h"
+#include "google/cloud/storage/version.h"
+
+namespace google {
+namespace cloud {
+namespace storage {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+/**
+ * Set this parameter to `true` to include soft-deleted object in
+ * `Client::ListObjects()` and `Client::GetObjectMetadata()` calls.
+ */
+struct SoftDeleted : public internal::WellKnownParameter<SoftDeleted, bool> {
+  using WellKnownParameter<SoftDeleted, bool>::WellKnownParameter;
+  static char const* well_known_parameter_name() { return "softDeleted"; }
+};
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace storage
+}  // namespace cloud
+}  // namespace google
+
+#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_SOFT_DELETED_H