feat(storage): buckets with object retention

google/cloud/storage/bucket_metadata.cc

@@ -102,6 +102,7 @@ bool operator==(BucketMetadata const& lhs, BucketMetadata const& rhs) {
          && lhs.logging_ == rhs.logging_                                    //
          && lhs.metageneration_ == rhs.metageneration_                      //
          && lhs.name_ == rhs.name_                                          //
+         && lhs.object_retention_ == rhs.object_retention_                  //
          && lhs.owner_ == rhs.owner_                                        //
          && lhs.project_number_ == rhs.project_number_                      //
          && lhs.retention_policy_ == rhs.retention_policy_                  //
@@ -182,6 +183,9 @@ std::ostream& operator<<(std::ostream& os, BucketMetadata const& rhs) {
 
   os << ", metageneration=" << rhs.metageneration() << ", name=" << rhs.name();
 
+  if (rhs.has_object_retention()) {
+    os << ", object_retention=" << rhs.object_retention();
+  }
   if (rhs.has_owner()) {
     os << ", owner.entity=" << rhs.owner().entity
        << ", owner.entity_id=" << rhs.owner().entity_id;

google/cloud/storage/bucket_metadata.h

@@ -25,6 +25,7 @@
 #include "google/cloud/storage/bucket_iam_configuration.h"
 #include "google/cloud/storage/bucket_lifecycle.h"
 #include "google/cloud/storage/bucket_logging.h"
+#include "google/cloud/storage/bucket_object_retention.h"
 #include "google/cloud/storage/bucket_retention_policy.h"
 #include "google/cloud/storage/bucket_rpo.h"
 #include "google/cloud/storage/bucket_soft_delete_policy.h"
@@ -411,6 +412,30 @@ class BucketMetadata {
     return *this;
   }
 
+  /// Returns true if the bucket `object_retention` attribute is present.
+  bool has_object_retention() const { return object_retention_.has_value(); }
+
+  /**
+   * Returns the owner.
+   *
+   * It is undefined behavior to call `owner()` if `has_owner()` is false.
+   */
+  BucketObjectRetention const& object_retention() const {
+    return *object_retention_;
+  }
+
+  /// @note this is only intended for mocking.
+  BucketMetadata& set_object_retention(BucketObjectRetention v) {
+    object_retention_ = std::move(v);
+    return *this;
+  }
+
+  /// @note this is only intended for mocking.
+  BucketMetadata& reset_object_retention() {
+    object_retention_.reset();
+    return *this;
+  }
+
   /// Returns true if the bucket `owner` attribute is present.
   bool has_owner() const { return owner_.has_value(); }
   /**
@@ -648,6 +673,7 @@ class BucketMetadata {
   absl::optional<BucketLogging> logging_;
   std::int64_t metageneration_{0};
   std::string name_;
+  absl::optional<BucketObjectRetention> object_retention_;
   absl::optional<Owner> owner_;
   std::int64_t project_number_ = 0;
   absl::optional<BucketRetentionPolicy> retention_policy_;

google/cloud/storage/bucket_metadata_test.cc

@@ -152,6 +152,9 @@ BucketMetadata CreateBucketMetadataForTest() {
       },
       "metageneration": "4",
       "name": "test-bucket",
+      "objectRetention": {
+        "mode": "Enabled"
+      },
       "owner": {
         "entity": "project-owners-123456789",
         "entityId": "test-owner-id-123"
@@ -274,6 +277,10 @@ TEST(BucketMetadataTest, Parse) {
   EXPECT_EQ(4, actual.metageneration());
   EXPECT_EQ("test-bucket", actual.name());
 
+  // object_retention
+  ASSERT_TRUE(actual.has_object_retention());
+  EXPECT_TRUE(actual.object_retention().enabled);
+
   // owner
   EXPECT_EQ("project-owners-123456789", actual.owner().entity);
   EXPECT_EQ("test-owner-id-123", actual.owner().entity_id);
@@ -392,6 +399,11 @@ TEST(BucketMetadataTest, IOStream) {
   // name()
   EXPECT_THAT(actual, HasSubstr("name=test-bucket"));
 
+  // object_retention()
+  EXPECT_THAT(
+      actual,
+      HasSubstr("object_retention=BucketObjectRetention={enabled=true}"));
+
   // project_team()
   EXPECT_THAT(actual, HasSubstr("project-owners-123456789"));
   EXPECT_THAT(actual, HasSubstr("test-owner-id-123"));
@@ -900,6 +912,24 @@ TEST(BucketMetadataTest, ResetLogging) {
   EXPECT_THAT(os.str(), Not(HasSubstr("logging.")));
 }
 
+TEST(BucketMetadataTest, SetObjectRetention) {
+  auto const expected = CreateBucketMetadataForTest();
+  auto copy = expected;
+  copy.set_object_retention(BucketObjectRetention{false});
+  ASSERT_TRUE(copy.has_object_retention());
+  EXPECT_FALSE(copy.object_retention().enabled);
+  EXPECT_NE(expected, copy);
+}
+
+TEST(BucketMetadataTest, ResetObjectRetention) {
+  auto const expected = CreateBucketMetadataForTest();
+  ASSERT_TRUE(expected.has_object_retention());
+  auto copy = expected;
+  copy.reset_object_retention();
+  ASSERT_FALSE(copy.has_object_retention());
+  EXPECT_NE(expected, copy);
+}
+
 /// @test Verify we can change the retention policy in BucketMetadata.
 TEST(BucketMetadataTest, SetRetentionPolicy) {
   auto expected = CreateBucketMetadataForTest();

google/cloud/storage/bucket_object_retention.cc

@@ -0,0 +1,31 @@
+// 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.
+
+#include "google/cloud/storage/bucket_object_retention.h"
+#include <iostream>
+
+namespace google {
+namespace cloud {
+namespace storage {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+std::ostream& operator<<(std::ostream& os, BucketObjectRetention const& rhs) {
+  return os << "BucketObjectRetention={enabled="
+            << (rhs.enabled ? "true" : "false") << "}";
+}
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace storage
+}  // namespace cloud
+}  // namespace google

google/cloud/storage/bucket_object_retention.h

@@ -0,0 +1,53 @@
+// 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_BUCKET_OBJECT_RETENTION_H
+#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_BUCKET_OBJECT_RETENTION_H
+
+#include "google/cloud/storage/version.h"
+#include <iosfwd>
+
+namespace google {
+namespace cloud {
+namespace storage {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+/**
+ * The soft delete policy for a bucket.
+ *
+ * The soft delete policy prevents soft-deleted objects from being permanently
+ * deleted.
+ */
+struct BucketObjectRetention {
+  bool enabled;
+};
+
+inline bool operator==(BucketObjectRetention const& lhs,
+                       BucketObjectRetention const& rhs) {
+  return lhs.enabled == rhs.enabled;
+}
+
+inline bool operator!=(BucketObjectRetention const& lhs,
+                       BucketObjectRetention const& rhs) {
+  return !(lhs == rhs);
+}
+
+std::ostream& operator<<(std::ostream& os, BucketObjectRetention const& rhs);
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace storage
+}  // namespace cloud
+}  // namespace google
+
+#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_BUCKET_OBJECT_RETENTION_H

google/cloud/storage/bucket_object_retention_test.cc

@@ -0,0 +1,45 @@
+// 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.
+
+#include "google/cloud/storage/bucket_object_retention.h"
+#include "google/cloud/internal/absl_str_cat_quiet.h"
+#include <gmock/gmock.h>
+#include <sstream>
+
+namespace google {
+namespace cloud {
+namespace storage {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+namespace {
+
+TEST(BucketObjectRetention, Compare) {
+  auto const a = BucketObjectRetention{true};
+  auto const b = BucketObjectRetention{false};
+
+  EXPECT_EQ(a, a);
+  EXPECT_NE(a, b);
+}
+
+TEST(BucketObjectRetention, IOStream) {
+  std::ostringstream os;
+  os << BucketObjectRetention{true};
+  auto const actual = os.str();
+  EXPECT_EQ(actual, "BucketObjectRetention={enabled=true}");
+}
+
+}  // namespace
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace storage
+}  // namespace cloud
+}  // namespace google

google/cloud/storage/client.h

@@ -381,9 +381,9 @@ class Client {
    * @param metadata the metadata for the new Bucket.  The `name` field is
    *     ignored in favor of @p bucket_name.
    * @param options a list of optional query parameters and/or request headers.
-   *     Valid types for this operation include `PredefinedAcl`,
-   *     `PredefinedDefaultObjectAcl`, `Projection`, `UserProject`,
-   *     and `OverrideDefaultProject`.
+   *     Valid types for this operation include `EnableObjectRetention`,
+   *     `PredefinedAcl`, `PredefinedDefaultObjectAcl`, `Projection`,
+   *     `UserProject`, and `OverrideDefaultProject`.
    *
    * @par Idempotency
    * This operation is always idempotent. It fails if the bucket already exists.
@@ -424,9 +424,10 @@ class Client {
    * @param metadata the metadata for the new Bucket.  The `name` field is
    *     ignored in favor of @p bucket_name.
    * @param options a list of optional query parameters and/or request headers.
-   *     Valid types for this operation include `PredefinedAcl`,
-   *     `PredefinedDefaultObjectAcl`, `Projection`, and `UserProject`.
-   *     `OverrideDefaultProject` is accepted, but has no effect.
+   *     Valid types for this operation include `EnableObjectRetention`,
+   *     `PredefinedAcl`, `PredefinedDefaultObjectAcl`, `Projection`, and
+   *     `UserProject`. The function also accepts `OverrideDefaultProject`, but
+   *     this option has no effect.
    *
    * @par Idempotency
    * This operation is always idempotent. It fails if the bucket already exists.

google/cloud/storage/enable_object_retention.h

@@ -0,0 +1,42 @@
+// 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_ENABLE_OBJECT_RETENTION_H
+#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_ENABLE_OBJECT_RETENTION_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 create buckets with object retention enabled.
+ */
+struct EnableObjectRetention
+    : public internal::WellKnownParameter<EnableObjectRetention, bool> {
+  using WellKnownParameter<EnableObjectRetention, bool>::WellKnownParameter;
+  static char const* well_known_parameter_name() {
+    return "enableObjectRetention";
+  }
+};
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace storage
+}  // namespace cloud
+}  // namespace google
+
+#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_ENABLE_OBJECT_RETENTION_H

google/cloud/storage/examples/CMakeLists.txt

@@ -37,6 +37,7 @@ set(storage_examples
     storage_bucket_cors_samples.cc
     storage_bucket_default_kms_key_samples.cc
     storage_bucket_iam_samples.cc
+    storage_bucket_object_retention_samples.cc
     storage_bucket_requester_pays_samples.cc
     storage_bucket_samples.cc
     storage_bucket_soft_delete_samples.cc