Google Cloud Storage C++ Client  2.2.1
A C++ Client Library for Google Cloud Storage
bucket_metadata.h
Go to the documentation of this file.
1 // Copyright 2018 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_BUCKET_METADATA_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_BUCKET_METADATA_H
17 
18 #include "google/cloud/storage/bucket_access_control.h"
19 #include "google/cloud/storage/internal/common_metadata.h"
20 #include "google/cloud/storage/internal/patch_builder.h"
21 #include "google/cloud/storage/lifecycle_rule.h"
22 #include "google/cloud/storage/object_access_control.h"
23 #include "google/cloud/storage/version.h"
24 #include "google/cloud/optional.h"
25 #include "absl/types/optional.h"
26 #include <chrono>
27 #include <map>
28 #include <string>
29 #include <tuple>
30 #include <utility>
31 #include <vector>
32 
33 namespace google {
34 namespace cloud {
35 namespace storage {
37 namespace internal {
38 struct BucketMetadataParser;
39 struct GrpcBucketMetadataParser;
40 struct GrpcBucketRequestParser;
41 } // namespace internal
42 
43 /**
44  * The billing configuration for a Bucket.
45  *
46  * @see https://cloud.google.com/storage/docs/requester-pays for general
47  * information on "Requester Pays" billing.
48  */
49 struct BucketBilling {
50  BucketBilling() = default;
51  // NOLINTNEXTLINE(google-explicit-constructor)
52  BucketBilling(bool v) : requester_pays(v) {}
53 
54  bool requester_pays{false};
55 };
56 
57 inline bool operator==(BucketBilling const& lhs, BucketBilling const& rhs) {
58  return lhs.requester_pays == rhs.requester_pays;
59 }
60 
61 inline bool operator<(BucketBilling const& lhs, BucketBilling const& rhs) {
62  return !lhs.requester_pays && rhs.requester_pays;
63 }
64 
65 inline bool operator!=(BucketBilling const& lhs, BucketBilling const& rhs) {
66  return std::rel_ops::operator!=(lhs, rhs);
67 }
68 
69 inline bool operator>(BucketBilling const& lhs, BucketBilling const& rhs) {
70  return std::rel_ops::operator>(lhs, rhs);
71 }
72 
73 inline bool operator<=(BucketBilling const& lhs, BucketBilling const& rhs) {
74  return std::rel_ops::operator<=(lhs, rhs);
75 }
76 
77 inline bool operator>=(BucketBilling const& lhs, BucketBilling const& rhs) {
78  return std::rel_ops::operator>=(lhs, rhs);
79 }
80 
81 /**
82  * An entry in the CORS list.
83  *
84  * CORS (Cross-Origin Resource Sharing) is a mechanism to enable client-side
85  * cross-origin requests. An entry in the configuration has a maximum age and a
86  * list of allowed origin and methods, as well as a list of returned response
87  * headers.
88  *
89  * @see https://en.wikipedia.org/wiki/Cross-origin_resource_sharing for general
90  * information on CORS.
91  *
92  * @see https://cloud.google.com/storage/docs/cross-origin for general
93  * information about CORS in the context of Google Cloud Storage.
94  *
95  * @see https://cloud.google.com/storage/docs/configuring-cors for information
96  * on how to set and troubleshoot CORS settings.
97  */
98 struct CorsEntry {
99  absl::optional<std::int64_t> max_age_seconds;
100  std::vector<std::string> method;
101  std::vector<std::string> origin;
102  std::vector<std::string> response_header;
103 };
104 
105 //@{
106 /// @name Comparison operators for CorsEntry.
107 inline bool operator==(CorsEntry const& lhs, CorsEntry const& rhs) {
108  return std::tie(lhs.max_age_seconds, lhs.method, lhs.origin,
109  lhs.response_header) == std::tie(rhs.max_age_seconds,
110  rhs.method, rhs.origin,
111  rhs.response_header);
112 }
113 
114 inline bool operator<(CorsEntry const& lhs, CorsEntry const& rhs) {
115  return std::tie(lhs.max_age_seconds, lhs.method, lhs.origin,
116  lhs.response_header) < std::tie(rhs.max_age_seconds,
117  rhs.method, rhs.origin,
118  rhs.response_header);
119 }
120 
121 inline bool operator!=(CorsEntry const& lhs, CorsEntry const& rhs) {
122  return std::rel_ops::operator!=(lhs, rhs);
123 }
124 
125 inline bool operator>(CorsEntry const& lhs, CorsEntry const& rhs) {
126  return std::rel_ops::operator>(lhs, rhs);
127 }
128 
129 inline bool operator<=(CorsEntry const& lhs, CorsEntry const& rhs) {
130  return std::rel_ops::operator<=(lhs, rhs);
131 }
132 
133 inline bool operator>=(CorsEntry const& lhs, CorsEntry const& rhs) {
134  return std::rel_ops::operator>=(lhs, rhs);
135 }
136 //@}
137 
138 std::ostream& operator<<(std::ostream& os, CorsEntry const& rhs);
139 
140 /**
141  * Configure if only the IAM policies are used for access control.
142  *
143  * @see Before enabling Uniform Bucket Level Access please
144  * review the [feature documentation][ubla-link], as well as
145  * ["Should you use uniform bucket-level access ?"][ubla-should-link].
146  *
147  * [ubla-link]:
148  * https://cloud.google.com/storage/docs/uniform-bucket-level-access
149  * [ubla-should-link]:
150  * https://cloud.google.com/storage/docs/uniform-bucket-level-access#should-you-use
151  */
153  bool enabled;
154  std::chrono::system_clock::time_point locked_time;
155 };
156 using BucketPolicyOnly = UniformBucketLevelAccess;
157 
158 //@{
159 /// @name Comparison operators For UniformBucketLevelAccess
160 inline bool operator==(UniformBucketLevelAccess const& lhs,
161  UniformBucketLevelAccess const& rhs) {
162  return std::tie(lhs.enabled, lhs.locked_time) ==
163  std::tie(rhs.enabled, rhs.locked_time);
164 }
165 
166 inline bool operator<(UniformBucketLevelAccess const& lhs,
167  UniformBucketLevelAccess const& rhs) {
168  return std::tie(lhs.enabled, lhs.locked_time) <
169  std::tie(rhs.enabled, rhs.locked_time);
170 }
171 
172 inline bool operator!=(UniformBucketLevelAccess const& lhs,
173  UniformBucketLevelAccess const& rhs) {
174  return std::rel_ops::operator!=(lhs, rhs);
175 }
176 
177 inline bool operator>(UniformBucketLevelAccess const& lhs,
178  UniformBucketLevelAccess const& rhs) {
179  return std::rel_ops::operator>(lhs, rhs);
180 }
181 
182 inline bool operator<=(UniformBucketLevelAccess const& lhs,
183  UniformBucketLevelAccess const& rhs) {
184  return std::rel_ops::operator<=(lhs, rhs);
185 }
186 
187 inline bool operator>=(UniformBucketLevelAccess const& lhs,
188  UniformBucketLevelAccess const& rhs) {
189  return std::rel_ops::operator>=(lhs, rhs);
190 }
191 //@}
192 
193 std::ostream& operator<<(std::ostream& os, UniformBucketLevelAccess const& rhs);
194 
195 /**
196  * The IAM configuration for a Bucket.
197  *
198  * Currently this only holds the UniformBucketLevelAccess. In the future, we may
199  * define additional IAM which would be included in this object.
200  *
201  * @see Before enabling Uniform Bucket Level Access please review the
202  * [feature documentation][ubla-link], as well as
203  * ["Should you use uniform bucket-level access ?"][ubla-should-link].
204  *
205  * [ubla-link]:
206  * https://cloud.google.com/storage/docs/uniform-bucket-level-access
207  * [ubla-should-link]:
208  * https://cloud.google.com/storage/docs/uniform-bucket-level-access#should-you-use
209  */
212  absl::optional<std::string> public_access_prevention;
213 };
214 
215 //@{
216 /// @name Public Access Prevention helper functions
217 inline std::string PublicAccessPreventionEnforced() { return "enforced"; }
218 inline std::string PublicAccessPreventionInherited() { return "inherited"; }
219 GOOGLE_CLOUD_CPP_DEPRECATED("Use PublicAccessPreventionInherited()")
220 inline std::string PublicAccessPreventionUnspecified() { return "unspecified"; }
221 //@}
222 
223 //@{
224 /// @name Comparison operators for BucketIamConfiguration.
225 inline bool operator==(BucketIamConfiguration const& lhs,
226  BucketIamConfiguration const& rhs) {
227  return std::tie(lhs.uniform_bucket_level_access,
229  std::tie(rhs.uniform_bucket_level_access,
231 }
232 
233 inline bool operator<(BucketIamConfiguration const& lhs,
234  BucketIamConfiguration const& rhs) {
235  return std::tie(lhs.uniform_bucket_level_access,
237  std::tie(rhs.uniform_bucket_level_access,
239 }
240 
241 inline bool operator!=(BucketIamConfiguration const& lhs,
242  BucketIamConfiguration const& rhs) {
243  return std::rel_ops::operator!=(lhs, rhs);
244 }
245 
246 inline bool operator>(BucketIamConfiguration const& lhs,
247  BucketIamConfiguration const& rhs) {
248  return std::rel_ops::operator>(lhs, rhs);
249 }
250 
251 inline bool operator<=(BucketIamConfiguration const& lhs,
252  BucketIamConfiguration const& rhs) {
253  return std::rel_ops::operator<=(lhs, rhs);
254 }
255 
256 inline bool operator>=(BucketIamConfiguration const& lhs,
257  BucketIamConfiguration const& rhs) {
258  return std::rel_ops::operator>=(lhs, rhs);
259 }
260 //@}
261 
262 std::ostream& operator<<(std::ostream& os, BucketIamConfiguration const& rhs);
263 
264 /**
265  * The Object Lifecycle configuration for a Bucket.
266  *
267  * @see https://cloud.google.com/storage/docs/managing-lifecycles for general
268  * information on object lifecycle rules.
269  */
271  std::vector<LifecycleRule> rule;
272 };
273 
274 //@{
275 /// @name Comparison operators for BucketLifecycle.
276 inline bool operator==(BucketLifecycle const& lhs, BucketLifecycle const& rhs) {
277  return lhs.rule == rhs.rule;
278 }
279 
280 inline bool operator<(BucketLifecycle const& lhs, BucketLifecycle const& rhs) {
281  return lhs.rule < rhs.rule;
282 }
283 
284 inline bool operator!=(BucketLifecycle const& lhs, BucketLifecycle const& rhs) {
285  return std::rel_ops::operator!=(lhs, rhs);
286 }
287 
288 inline bool operator>(BucketLifecycle const& lhs, BucketLifecycle const& rhs) {
289  return std::rel_ops::operator>(lhs, rhs);
290 }
291 
292 inline bool operator<=(BucketLifecycle const& lhs, BucketLifecycle const& rhs) {
293  return std::rel_ops::operator<=(lhs, rhs);
294 }
295 
296 inline bool operator>=(BucketLifecycle const& lhs, BucketLifecycle const& rhs) {
297  return std::rel_ops::operator>=(lhs, rhs);
298 }
299 //@}
300 
301 /**
302  * The Logging configuration for a Bucket.
303  *
304  * @see https://cloud.google.com/storage/docs/access-logs for general
305  * information about using access logs with Google Cloud Storage.
306  */
308  std::string log_bucket;
309  std::string log_object_prefix;
310 };
311 
312 inline bool operator==(BucketLogging const& lhs, BucketLogging const& rhs) {
313  return std::tie(lhs.log_bucket, lhs.log_object_prefix) ==
314  std::tie(rhs.log_bucket, rhs.log_object_prefix);
315 }
316 
317 inline bool operator<(BucketLogging const& lhs, BucketLogging const& rhs) {
318  return std::tie(lhs.log_bucket, lhs.log_object_prefix) <
319  std::tie(rhs.log_bucket, rhs.log_object_prefix);
320 }
321 
322 inline bool operator!=(BucketLogging const& lhs, BucketLogging const& rhs) {
323  return std::rel_ops::operator!=(lhs, rhs);
324 }
325 
326 inline bool operator>(BucketLogging const& lhs, BucketLogging const& rhs) {
327  return std::rel_ops::operator>(lhs, rhs);
328 }
329 
330 inline bool operator<=(BucketLogging const& lhs, BucketLogging const& rhs) {
331  return std::rel_ops::operator<=(lhs, rhs);
332 }
333 
334 inline bool operator>=(BucketLogging const& lhs, BucketLogging const& rhs) {
335  return std::rel_ops::operator>=(lhs, rhs);
336 }
337 
338 std::ostream& operator<<(std::ostream& os, BucketLogging const& rhs);
339 
340 /**
341  * Describes the default customer managed encryption key for a bucket.
342  *
343  * Customer managed encryption keys (CMEK) are encryption keys selected by the
344  * user and generated by Google Cloud Key Management Service.
345  *
346  * @see https://cloud.google.com/storage/docs/encryption/customer-managed-keys
347  * for a general description of CMEK in Google Cloud Storage.
348  *
349  * @see https://cloud.google.com/kms/ for details about the Cloud Key Management
350  * Service.
351  */
353  std::string default_kms_key_name;
354 };
355 
356 inline bool operator==(BucketEncryption const& lhs,
357  BucketEncryption const& rhs) {
359 }
360 
361 inline bool operator<(BucketEncryption const& lhs,
362  BucketEncryption const& rhs) {
364 }
365 
366 inline bool operator!=(BucketEncryption const& lhs,
367  BucketEncryption const& rhs) {
368  return std::rel_ops::operator!=(lhs, rhs);
369 }
370 
371 inline bool operator>(BucketEncryption const& lhs,
372  BucketEncryption const& rhs) {
373  return std::rel_ops::operator>(lhs, rhs);
374 }
375 
376 inline bool operator<=(BucketEncryption const& lhs,
377  BucketEncryption const& rhs) {
378  return std::rel_ops::operator<=(lhs, rhs);
379 }
380 
381 inline bool operator>=(BucketEncryption const& lhs,
382  BucketEncryption const& rhs) {
383  return std::rel_ops::operator>=(lhs, rhs);
384 }
385 
386 /**
387  * The retention policy for a bucket.
388  *
389  * The Bucket Lock feature of Google Cloud Storage allows you to configure a
390  * data retention policy for a Cloud Storage bucket. This policy governs how
391  * long objects in the bucket must be retained. The feature also allows you to
392  * lock the data retention policy, permanently preventing the policy from from
393  * being reduced or removed.
394  *
395  * @see https://cloud.google.com/storage/docs/bucket-lock for a general
396  * overview
397  */
399  std::chrono::seconds retention_period;
400  std::chrono::system_clock::time_point effective_time;
401  bool is_locked;
402 };
403 
404 inline bool operator==(BucketRetentionPolicy const& lhs,
405  BucketRetentionPolicy const& rhs) {
406  return std::tie(lhs.retention_period, lhs.effective_time, lhs.is_locked) ==
407  std::tie(rhs.retention_period, rhs.effective_time, rhs.is_locked);
408 }
409 
410 inline bool operator<(BucketRetentionPolicy const& lhs,
411  BucketRetentionPolicy const& rhs) {
412  return std::tie(lhs.retention_period, lhs.effective_time, lhs.is_locked) <
413  std::tie(rhs.retention_period, rhs.effective_time, rhs.is_locked);
414 }
415 
416 inline bool operator!=(BucketRetentionPolicy const& lhs,
417  BucketRetentionPolicy const& rhs) {
418  return std::rel_ops::operator!=(lhs, rhs);
419 }
420 
421 inline bool operator>(BucketRetentionPolicy const& lhs,
422  BucketRetentionPolicy const& rhs) {
423  return std::rel_ops::operator>(lhs, rhs);
424 }
425 
426 inline bool operator<=(BucketRetentionPolicy const& lhs,
427  BucketRetentionPolicy const& rhs) {
428  return std::rel_ops::operator<=(lhs, rhs);
429 }
430 
431 inline bool operator>=(BucketRetentionPolicy const& lhs,
432  BucketRetentionPolicy const& rhs) {
433  return std::rel_ops::operator>=(lhs, rhs);
434 }
435 
436 std::ostream& operator<<(std::ostream& os, BucketRetentionPolicy const& rhs);
437 
438 /// A helper function to avoid typos in the RPO configuration
439 inline std::string RpoDefault() { return "DEFAULT"; }
440 
441 /// A helper function to avoid typos in the RPO configuration
442 inline std::string RpoAsyncTurbo() { return "ASYNC_TURBO"; }
443 
444 /**
445  * The versioning configuration for a Bucket.
446  *
447  * @see https://cloud.google.com/storage/docs/requester-pays for general
448  * information on "Requester Pays" billing.
449  */
451  BucketVersioning() = default;
452  explicit BucketVersioning(bool flag) : enabled(flag) {}
453 
454  bool enabled{true};
455 };
456 
457 inline bool operator==(BucketVersioning const& lhs,
458  BucketVersioning const& rhs) {
459  return lhs.enabled == rhs.enabled;
460 }
461 
462 inline bool operator<(BucketVersioning const& lhs,
463  BucketVersioning const& rhs) {
464  return !lhs.enabled && rhs.enabled;
465 }
466 
467 inline bool operator!=(BucketVersioning const& lhs,
468  BucketVersioning const& rhs) {
469  return std::rel_ops::operator!=(lhs, rhs);
470 }
471 
472 inline bool operator>(BucketVersioning const& lhs,
473  BucketVersioning const& rhs) {
474  return std::rel_ops::operator>(lhs, rhs);
475 }
476 
477 inline bool operator<=(BucketVersioning const& lhs,
478  BucketVersioning const& rhs) {
479  return std::rel_ops::operator<=(lhs, rhs);
480 }
481 
482 inline bool operator>=(BucketVersioning const& lhs,
483  BucketVersioning const& rhs) {
484  return std::rel_ops::operator>=(lhs, rhs);
485 }
486 
487 /**
488  * The website configuration for a Bucket.
489  *
490  * @see https://cloud.google.com/storage/docs/static-website for information on
491  * how to configure Buckets to serve as a static website.
492  */
494  std::string main_page_suffix;
495  std::string not_found_page;
496 };
497 
498 inline bool operator==(BucketWebsite const& lhs, BucketWebsite const& rhs) {
499  return std::tie(lhs.main_page_suffix, lhs.not_found_page) ==
500  std::tie(rhs.main_page_suffix, rhs.not_found_page);
501 }
502 
503 inline bool operator<(BucketWebsite const& lhs, BucketWebsite const& rhs) {
504  return std::tie(lhs.main_page_suffix, lhs.not_found_page) <
505  std::tie(rhs.main_page_suffix, rhs.not_found_page);
506 }
507 
508 inline bool operator!=(BucketWebsite const& lhs, BucketWebsite const& rhs) {
509  return std::rel_ops::operator!=(lhs, rhs);
510 }
511 
512 inline bool operator>(BucketWebsite const& lhs, BucketWebsite const& rhs) {
513  return std::rel_ops::operator>(lhs, rhs);
514 }
515 
516 inline bool operator<=(BucketWebsite const& lhs, BucketWebsite const& rhs) {
517  return std::rel_ops::operator<=(lhs, rhs);
518 }
519 
520 inline bool operator>=(BucketWebsite const& lhs, BucketWebsite const& rhs) {
521  return std::rel_ops::operator>=(lhs, rhs);
522 }
523 
524 /**
525  * Configuration for Custom Dual Regions.
526  *
527  * It should specify precisely two eligible regions within the same Multiregion.
528  *
529  * @see Additional information on custom dual regions in the
530  * [feature documentation][cdr-link].
531  *
532  * [cdr-link]: https://cloud.google.com/storage/docs/locations
533  */
535  std::vector<std::string> data_locations;
536 };
537 
538 //@{
539 /// @name Comparison operators for BucketCustomPlacementConfig.
540 inline bool operator==(BucketCustomPlacementConfig const& lhs,
541  BucketCustomPlacementConfig const& rhs) {
542  return lhs.data_locations == rhs.data_locations;
543 }
544 
545 inline bool operator<(BucketCustomPlacementConfig const& lhs,
546  BucketCustomPlacementConfig const& rhs) {
547  return lhs.data_locations < rhs.data_locations;
548 }
549 
550 inline bool operator!=(BucketCustomPlacementConfig const& lhs,
551  BucketCustomPlacementConfig const& rhs) {
552  return std::rel_ops::operator!=(lhs, rhs);
553 }
554 
555 inline bool operator>(BucketCustomPlacementConfig const& lhs,
556  BucketCustomPlacementConfig const& rhs) {
557  return std::rel_ops::operator>(lhs, rhs);
558 }
559 
560 inline bool operator<=(BucketCustomPlacementConfig const& lhs,
561  BucketCustomPlacementConfig const& rhs) {
562  return std::rel_ops::operator<=(lhs, rhs);
563 }
564 
565 inline bool operator>=(BucketCustomPlacementConfig const& lhs,
566  BucketCustomPlacementConfig const& rhs) {
567  return std::rel_ops::operator>=(lhs, rhs);
568 }
569 //@}
570 
571 std::ostream& operator<<(std::ostream& os,
572  BucketCustomPlacementConfig const& rhs);
573 
574 /**
575  * Represents a Google Cloud Storage Bucket Metadata object.
576  */
577 class BucketMetadata : private internal::CommonMetadata<BucketMetadata> {
578  public:
579  BucketMetadata() = default;
580 
581  // Please keep these in alphabetical order, that make it easier to verify we
582  // have actually implemented all of them.
583  /**
584  * @name Get and set Bucket Access Control Lists.
585  *
586  * @see https://cloud.google.com/storage/docs/access-control/lists
587  */
588  ///@{
589  std::vector<BucketAccessControl> const& acl() const { return acl_; }
590  std::vector<BucketAccessControl>& mutable_acl() { return acl_; }
592  acl_ = std::move(acl);
593  return *this;
594  }
595  ///@}
596 
597  /**
598  * @name Get and set billing configuration for the Bucket.
599  *
600  * @see https://cloud.google.com/storage/docs/requester-pays
601  */
602  ///@{
603  bool has_billing() const { return billing_.has_value(); }
604  BucketBilling const& billing() const { return *billing_; }
605  absl::optional<BucketBilling> const& billing_as_optional() const {
606  return billing_;
607  }
609  billing_ = v;
610  return *this;
611  }
613  billing_.reset();
614  return *this;
615  }
616  ///@}
617 
618  /**
619  * @name Get and set the default event based hold for the Bucket.
620  *
621  * Objects may have an event-based hold associated with them. If a Bucket
622  * has the `default_event_based_hold()` parameter set, and you create a new
623  * object in the bucket without specifying its event-event based hold then the
624  * object gets the value set in the bucket.
625  *
626  * @see https://cloud.google.com/storage/docs/bucket-lock for generation
627  * information on retention policies. The section on
628  * [Object
629  * holds](https://cloud.google.com/storage/docs/bucket-lock#object-holds) is
630  * particularly relevant.
631  *
632  * @see https://cloud.google.com/storage/docs/holding-objects for examples
633  * of using default event-based hold policy.
634  */
635  ///@{
636  bool default_event_based_hold() const { return default_event_based_hold_; }
638  default_event_based_hold_ = v;
639  return *this;
640  }
641  ///@}
642 
643  /**
644  * @name Get and set CORS configuration for the Bucket.
645  *
646  * @see https://en.wikipedia.org/wiki/Cross-origin_resource_sharing for
647  * general information on CORS.
648  *
649  * @see https://cloud.google.com/storage/docs/cross-origin for general
650  * information about CORS in the context of Google Cloud Storage.
651  *
652  * @see https://cloud.google.com/storage/docs/configuring-cors for information
653  * on how to set and troubleshoot CORS settings.
654  */
655  ///@{
656  std::vector<CorsEntry> const& cors() const { return cors_; }
657  std::vector<CorsEntry>& mutable_cors() { return cors_; }
658  BucketMetadata& set_cors(std::vector<CorsEntry> cors) {
659  cors_ = std::move(cors);
660  return *this;
661  }
662  ///@}
663 
664  /**
665  * @name Get and set the Default Object Access Control Lists.
666  *
667  * @see https://cloud.google.com/storage/docs/access-control/lists#default for
668  * general information of default ACLs.
669  *
670  * @see
671  * https://cloud.google.com/storage/docs/access-control/create-manage-lists#defaultobjects
672  * for information on how to set the default ACLs.
673  */
674  ///@{
675  std::vector<ObjectAccessControl> const& default_acl() const {
676  return default_acl_;
677  }
679  return default_acl_;
680  }
682  default_acl_ = std::move(acl);
683  return *this;
684  }
685  ///@}
686 
687  /**
688  * @name Get and set the Default Object Access Control Lists.
689  *
690  * @see https://cloud.google.com/storage/docs/access-control/lists#default for
691  * general information of default ACLs.
692  *
693  * @see
694  * https://cloud.google.com/storage/docs/encryption/customer-managed-keys
695  * for information on Customer-Managed Encryption Keys.
696  */
697  ///@{
698  bool has_encryption() const { return encryption_.has_value(); }
699  BucketEncryption const& encryption() const { return *encryption_; }
700  absl::optional<BucketEncryption> const& encryption_as_optional() const {
701  return encryption_;
702  }
704  encryption_ = std::move(v);
705  return *this;
706  }
708  encryption_.reset();
709  return *this;
710  }
711  ///@}
712 
713  using CommonMetadata::etag;
714 
715  /**
716  * @name Get and set the IAM configuration.
717  *
718  * @see Before enabling Uniform Bucket Level Access please review the
719  * [feature documentation][ubla-link], as well as
720  * ["Should you use uniform bucket-level access ?"][ubla-should-link].
721  *
722  * [ubla-link]:
723  * https://cloud.google.com/storage/docs/uniform-bucket-level-access
724  * [ubla-should-link]:
725  * https://cloud.google.com/storage/docs/uniform-bucket-level-access#should-you-use
726  */
727  ///@{
728  bool has_iam_configuration() const { return iam_configuration_.has_value(); }
730  return *iam_configuration_;
731  }
733  const {
734  return iam_configuration_;
735  }
737  iam_configuration_ = std::move(v);
738  return *this;
739  }
741  iam_configuration_.reset();
742  return *this;
743  }
744  ///@}
745 
746  using CommonMetadata::id;
747  using CommonMetadata::kind;
748 
749  /// @name Accessors and modifiers to the `labels`.
750  ///@{
751 
752  /// Returns `true` if the key is present in the Bucket's metadata labels.
753  bool has_label(std::string const& key) const {
754  return labels_.end() != labels_.find(key);
755  }
756 
757  /**
758  * Returns the value of @p key in the Bucket's metadata labels.
759  *
760  * It is undefined behavior to call `label(key)` if `has_label(key) == false`.
761  */
762  std::string const& label(std::string const& key) const {
763  return labels_.at(key);
764  }
765 
766  /// Delete a label. This is a no-op if the key does not exist.
767  BucketMetadata& delete_label(std::string const& key) {
768  auto i = labels_.find(key);
769  if (i == labels_.end()) {
770  return *this;
771  }
772  labels_.erase(i);
773  return *this;
774  }
775 
776  /// Insert or update the label entry.
777  BucketMetadata& upsert_label(std::string key, std::string value) {
778  auto i = labels_.lower_bound(key);
779  if (i == labels_.end() || i->first != key) {
780  labels_.emplace_hint(i, std::move(key), std::move(value));
781  } else {
782  i->second = std::move(value);
783  }
784  return *this;
785  }
786 
787  /// Returns all the Bucket's labels.
788  std::map<std::string, std::string> const& labels() const { return labels_; }
789 
790  /// Returns all the Bucket's labels.
791  std::map<std::string, std::string>& mutable_labels() { return labels_; }
792  ///@}
793 
794  /**
795  * @name Accessors and modifiers for object lifecycle rules.
796  *
797  * @see https://cloud.google.com/storage/docs/managing-lifecycles for general
798  * information on object lifecycle rules.
799  */
800  ///@{
801  bool has_lifecycle() const { return lifecycle_.has_value(); }
802  BucketLifecycle const& lifecycle() const { return *lifecycle_; }
803  absl::optional<BucketLifecycle> const& lifecycle_as_optional() const {
804  return lifecycle_;
805  }
807  lifecycle_ = std::move(v);
808  return *this;
809  }
811  lifecycle_.reset();
812  return *this;
813  }
814  ///@}
815 
816  std::string const& location() const { return location_; }
817  BucketMetadata& set_location(std::string v) {
818  location_ = std::move(v);
819  return *this;
820  }
821 
822  std::string const& location_type() const { return location_type_; }
823 
824  /// @name Accessors and modifiers for logging configuration.
825  ///@{
826  bool has_logging() const { return logging_.has_value(); }
827  BucketLogging const& logging() const { return *logging_; }
828  absl::optional<BucketLogging> const& logging_as_optional() const {
829  return logging_;
830  }
832  logging_ = std::move(v);
833  return *this;
834  }
836  logging_.reset();
837  return *this;
838  }
839  ///@}
840 
841  /// The bucket metageneration.
842  using CommonMetadata::metageneration;
843 
844  /// The bucket name.
845  using CommonMetadata::name;
846 
847  /**
848  * Changes the name.
849  *
850  * @note Bucket names can only be set during bucket creation. This modifier
851  * is used to set the name when using a `BucketMetadata` object that changes
852  * some other attribute.
853  */
854  BucketMetadata& set_name(std::string v) {
855  CommonMetadata::set_name(std::move(v));
856  return *this;
857  }
858 
859  /// Returns true if the bucket `owner` attribute is present.
860  using CommonMetadata::has_owner;
861  using CommonMetadata::owner;
862 
863  std::int64_t const& project_number() const { return project_number_; }
864 
865  using CommonMetadata::self_link;
866 
867  /// @name Accessors and modifiers for retention policy configuration.
868  ///@{
869  bool has_retention_policy() const { return retention_policy_.has_value(); }
871  return *retention_policy_;
872  }
874  const {
875  return retention_policy_;
876  }
878  retention_policy_ = std::move(v);
879  return *this;
880  }
881 
882  /**
883  * Sets the retention period.
884  *
885  * The retention period is the only writable attribute in a retention policy.
886  * This function makes it easier to set the retention policy when the
887  * `BucketMetadata` object is used to update or patch the bucket.
888  */
889  BucketMetadata& set_retention_policy(std::chrono::seconds retention_period) {
891  retention_period, std::chrono::system_clock::time_point{}, false});
892  }
893 
895  retention_policy_.reset();
896  return *this;
897  }
898  ///@}
899 
900  /// @name Accessors and modifiers for the Recovery Point Objective.
901  ///@{
902  std::string const& rpo() const { return rpo_; }
903  BucketMetadata& set_rpo(std::string v) {
904  rpo_ = std::move(v);
905  return *this;
906  }
907  ///@}
908 
909  /// @name Access and modify the default storage class attribute.
910  ///@{
911  using CommonMetadata::storage_class;
913  CommonMetadata::set_storage_class(std::move(v));
914  return *this;
915  }
916  ///@}
917 
918  /// Returns the bucket creation timestamp.
919  using CommonMetadata::time_created;
920 
921  /// Returns the timestamp for the last bucket metadata update.
922  using CommonMetadata::updated;
923 
924  /// @name Accessors and modifiers for versioning configuration.
925  ///@{
926  absl::optional<BucketVersioning> const& versioning() const {
927  return versioning_;
928  }
929  bool has_versioning() const { return versioning_.has_value(); }
931  versioning_.emplace(BucketVersioning{true});
932  return *this;
933  }
935  versioning_.emplace(BucketVersioning{false});
936  return *this;
937  }
939  versioning_.reset();
940  return *this;
941  }
943  versioning_ = std::move(v);
944  return *this;
945  }
946  ///@}
947 
948  /// @name Accessors and modifiers for website configuration.
949  ///@{
950  bool has_website() const { return website_.has_value(); }
951  BucketWebsite const& website() const { return *website_; }
952  absl::optional<BucketWebsite> const& website_as_optional() const {
953  return website_;
954  }
956  website_ = std::move(v);
957  return *this;
958  }
960  website_.reset();
961  return *this;
962  }
963  ///@}
964 
965  /// @name Accessors and modifiers for custom placement configuration.
966  ///@{
968  return custom_placement_config_.has_value();
969  }
971  return *custom_placement_config_;
972  }
973  absl::optional<BucketCustomPlacementConfig> const&
975  return custom_placement_config_;
976  }
977  /// Placement configuration can only be set when the bucket is created.
979  custom_placement_config_ = std::move(v);
980  return *this;
981  }
982  /// Placement configuration can only be set when the bucket is created.
984  custom_placement_config_.reset();
985  return *this;
986  }
987  ///@}
988 
989  friend bool operator==(BucketMetadata const& lhs, BucketMetadata const& rhs);
990  friend bool operator!=(BucketMetadata const& lhs, BucketMetadata const& rhs) {
991  return !(lhs == rhs);
992  }
993 
994  private:
995  friend struct internal::BucketMetadataParser;
996  friend struct internal::GrpcBucketMetadataParser;
997 
998  friend std::ostream& operator<<(std::ostream& os, BucketMetadata const& rhs);
999  // Keep the fields in alphabetical order.
1000  std::vector<BucketAccessControl> acl_;
1001  absl::optional<BucketBilling> billing_;
1002  std::vector<CorsEntry> cors_;
1003  bool default_event_based_hold_ = false;
1004  std::vector<ObjectAccessControl> default_acl_;
1005  absl::optional<BucketEncryption> encryption_;
1006  absl::optional<BucketIamConfiguration> iam_configuration_;
1007  std::map<std::string, std::string> labels_;
1008  absl::optional<BucketLifecycle> lifecycle_;
1009  std::string location_;
1010  std::string location_type_;
1011  absl::optional<BucketLogging> logging_;
1012  std::int64_t project_number_ = 0;
1013  absl::optional<BucketRetentionPolicy> retention_policy_;
1014  std::string rpo_;
1015  absl::optional<BucketVersioning> versioning_;
1016  absl::optional<BucketWebsite> website_;
1017  absl::optional<BucketCustomPlacementConfig> custom_placement_config_;
1018 };
1019 
1020 std::ostream& operator<<(std::ostream& os, BucketMetadata const& rhs);
1021 
1022 /**
1023  * Prepares a patch for the Bucket resource.
1024  *
1025  * The Bucket resource has many modifiable fields. The application may send a
1026  * patch request to change (or delete) a small fraction of these fields by using
1027  * this object.
1028  *
1029  * @see
1030  * https://cloud.google.com/storage/docs/json_api/v1/how-tos/performance#patch
1031  * for general information on PATCH requests for the Google Cloud Storage
1032  * JSON API.
1033  */
1035  public:
1037 
1038  std::string BuildPatch() const;
1039 
1041 
1042  /**
1043  * Clears the ACL for the Bucket.
1044  *
1045  * @warning Currently the server ignores requests to reset the full ACL.
1046  */
1048 
1051 
1054 
1057 
1059  std::vector<ObjectAccessControl> const& v);
1060 
1061  /**
1062  * Clears the default object ACL for the Bucket.
1063  *
1064  * @warning Currently the server ignores requests to reset the full ACL.
1065  */
1067 
1069  BucketIamConfiguration const& v);
1071 
1074 
1075  BucketMetadataPatchBuilder& SetLabel(std::string const& label,
1076  std::string const& value);
1077  BucketMetadataPatchBuilder& ResetLabel(std::string const& label);
1079 
1082 
1085 
1086  BucketMetadataPatchBuilder& SetName(std::string const& v);
1088 
1090  BucketRetentionPolicy const& v);
1092  std::chrono::seconds retention_period) {
1093  // This is the only parameter that the application can set, so make it easy
1094  // for them to set it.
1096  retention_period, std::chrono::system_clock::time_point{}, false});
1097  }
1099 
1100  BucketMetadataPatchBuilder& SetRpo(std::string const& v);
1102 
1105 
1108 
1111 
1112  private:
1113  friend struct internal::GrpcBucketRequestParser;
1114 
1115  internal::PatchBuilder impl_;
1116  bool labels_subpatch_dirty_{false};
1117  internal::PatchBuilder labels_subpatch_;
1118 };
1119 
1121 } // namespace storage
1122 } // namespace cloud
1123 } // namespace google
1124 
1125 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_BUCKET_METADATA_H