Google Cloud Storage C++ Client  2.2.1
A C++ Client Library for Google Cloud Storage
idempotency_policy.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_IDEMPOTENCY_POLICY_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_IDEMPOTENCY_POLICY_H
17 
18 #include "google/cloud/storage/internal/bucket_acl_requests.h"
19 #include "google/cloud/storage/internal/bucket_requests.h"
20 #include "google/cloud/storage/internal/default_object_acl_requests.h"
21 #include "google/cloud/storage/internal/hmac_key_requests.h"
22 #include "google/cloud/storage/internal/notification_requests.h"
23 #include "google/cloud/storage/internal/object_acl_requests.h"
24 #include "google/cloud/storage/internal/object_requests.h"
25 #include "google/cloud/storage/internal/service_account_requests.h"
26 #include "google/cloud/storage/internal/sign_blob_requests.h"
27 #include "google/cloud/storage/version.h"
28 #include <memory>
29 
30 namespace google {
31 namespace cloud {
32 namespace storage {
34 /**
35  * Define the interface for the idempotency policy.
36  *
37  * The idempotency policy controls which requests are treated as idempotent and
38  * therefore safe to retry on a transient failure. Non-idempotent operations can
39  * result in data loss. For example, consider `DeleteObject()`, if this
40  * operation is called without pre-conditions retrying this operation may delete
41  * more than one version of an object, which may not have the desired effect.
42  * Even operations that "add" data can result in data loss, consider
43  * `InsertObjectMedia()`, if called without pre-conditions retrying this
44  * operation will insert multiple new versions, possibly deleting old data if
45  * the bucket is configured to keep only N versions of each object.
46  *
47  * Some applications are designed to handle duplicate requests without data
48  * loss, or the library may be used in an environment where the risk of data
49  * loss due to duplicate requests is negligible or zero.
50  *
51  * This policy allows application developers to control the behavior of the
52  * library with respect to retrying non-idempotent operations. Application
53  * developers can configure the library to only retry operations that are known
54  * to be idempotent (that is, they will succeed only once). Application may also
55  * configure the library to retry all operations, regardless of whether the
56  * operations are idempotent or not.
57  */
59  public:
60  virtual ~IdempotencyPolicy() = default;
61 
62  /// Create a new copy of this object.
63  virtual std::unique_ptr<IdempotencyPolicy> clone() const = 0;
64 
65  //@{
66  /// @name Bucket resource operations
67  virtual bool IsIdempotent(
68  internal::ListBucketsRequest const& request) const = 0;
69  virtual bool IsIdempotent(
70  internal::CreateBucketRequest const& request) const = 0;
71  virtual bool IsIdempotent(
72  internal::GetBucketMetadataRequest const& request) const = 0;
73  virtual bool IsIdempotent(
74  internal::DeleteBucketRequest const& request) const = 0;
75  virtual bool IsIdempotent(
76  internal::UpdateBucketRequest const& request) const = 0;
77  virtual bool IsIdempotent(
78  internal::PatchBucketRequest const& request) const = 0;
79  virtual bool IsIdempotent(
80  internal::GetBucketIamPolicyRequest const& request) const = 0;
81  virtual bool IsIdempotent(
82  internal::SetNativeBucketIamPolicyRequest const& request) const = 0;
83  virtual bool IsIdempotent(
84  internal::TestBucketIamPermissionsRequest const& request) const = 0;
85  virtual bool IsIdempotent(
86  internal::LockBucketRetentionPolicyRequest const& request) const = 0;
87  //@}
88 
89  //@{
90  /// @name Object resource operations
91  virtual bool IsIdempotent(
92  internal::InsertObjectMediaRequest const& request) const = 0;
93  virtual bool IsIdempotent(
94  internal::CopyObjectRequest const& request) const = 0;
95  virtual bool IsIdempotent(
96  internal::GetObjectMetadataRequest const& request) const = 0;
97  virtual bool IsIdempotent(
98  internal::ReadObjectRangeRequest const& request) const = 0;
99  virtual bool IsIdempotent(
100  internal::ListObjectsRequest const& request) const = 0;
101  virtual bool IsIdempotent(
102  internal::DeleteObjectRequest const& request) const = 0;
103  virtual bool IsIdempotent(
104  internal::UpdateObjectRequest const& request) const = 0;
105  virtual bool IsIdempotent(
106  internal::PatchObjectRequest const& request) const = 0;
107  virtual bool IsIdempotent(
108  internal::ComposeObjectRequest const& request) const = 0;
109  virtual bool IsIdempotent(
110  internal::RewriteObjectRequest const& request) const = 0;
111  virtual bool IsIdempotent(
112  internal::ResumableUploadRequest const& request) const = 0;
113  virtual bool IsIdempotent(
114  internal::UploadChunkRequest const& request) const = 0;
115  //@}
116 
117  //@{
118  /// @name BucketAccessControls resource operations
119  virtual bool IsIdempotent(
120  internal::ListBucketAclRequest const& request) const = 0;
121  virtual bool IsIdempotent(
122  internal::CreateBucketAclRequest const& request) const = 0;
123  virtual bool IsIdempotent(
124  internal::DeleteBucketAclRequest const& request) const = 0;
125  virtual bool IsIdempotent(
126  internal::GetBucketAclRequest const& request) const = 0;
127  virtual bool IsIdempotent(
128  internal::UpdateBucketAclRequest const& request) const = 0;
129  virtual bool IsIdempotent(
130  internal::PatchBucketAclRequest const& request) const = 0;
131  //@}
132 
133  //@{
134  /// @name ObjectAccessControls operations
135  virtual bool IsIdempotent(
136  internal::ListObjectAclRequest const& request) const = 0;
137  virtual bool IsIdempotent(
138  internal::CreateObjectAclRequest const& request) const = 0;
139  virtual bool IsIdempotent(
140  internal::DeleteObjectAclRequest const& request) const = 0;
141  virtual bool IsIdempotent(
142  internal::GetObjectAclRequest const& request) const = 0;
143  virtual bool IsIdempotent(
144  internal::UpdateObjectAclRequest const& request) const = 0;
145  virtual bool IsIdempotent(
146  internal::PatchObjectAclRequest const& request) const = 0;
147  //@}
148 
149  //@{
150  /// @name DefaultObjectAccessControls operations.
151  virtual bool IsIdempotent(
152  internal::ListDefaultObjectAclRequest const& request) const = 0;
153  virtual bool IsIdempotent(
154  internal::CreateDefaultObjectAclRequest const& request) const = 0;
155  virtual bool IsIdempotent(
156  internal::DeleteDefaultObjectAclRequest const& request) const = 0;
157  virtual bool IsIdempotent(
158  internal::GetDefaultObjectAclRequest const& request) const = 0;
159  virtual bool IsIdempotent(
160  internal::UpdateDefaultObjectAclRequest const& request) const = 0;
161  virtual bool IsIdempotent(
162  internal::PatchDefaultObjectAclRequest const& request) const = 0;
163  //@}
164 
165  //@{
166  virtual bool IsIdempotent(
167  internal::GetProjectServiceAccountRequest const& request) const = 0;
168  virtual bool IsIdempotent(
169  internal::ListHmacKeysRequest const& request) const = 0;
170  virtual bool IsIdempotent(
171  internal::CreateHmacKeyRequest const& request) const = 0;
172  virtual bool IsIdempotent(
173  internal::DeleteHmacKeyRequest const& request) const = 0;
174  virtual bool IsIdempotent(
175  internal::GetHmacKeyRequest const& request) const = 0;
176  virtual bool IsIdempotent(
177  internal::UpdateHmacKeyRequest const& request) const = 0;
178  virtual bool IsIdempotent(internal::SignBlobRequest const& request) const = 0;
179  //@}
180 
181  //@{
182  virtual bool IsIdempotent(
183  internal::ListNotificationsRequest const& request) const = 0;
184  virtual bool IsIdempotent(
185  internal::CreateNotificationRequest const& request) const = 0;
186  virtual bool IsIdempotent(
187  internal::GetNotificationRequest const& request) const = 0;
188  virtual bool IsIdempotent(
189  internal::DeleteNotificationRequest const& request) const = 0;
190  //@}
191 };
192 
193 /**
194  * A IdempotencyPolicy that always retries all requests.
195  */
197  public:
199 
200  std::unique_ptr<IdempotencyPolicy> clone() const override;
201 
202  //@{
203  /// @name Bucket resource operations
204  bool IsIdempotent(internal::ListBucketsRequest const& request) const override;
206  internal::CreateBucketRequest const& request) const override;
208  internal::GetBucketMetadataRequest const& request) const override;
210  internal::DeleteBucketRequest const& request) const override;
212  internal::UpdateBucketRequest const& request) const override;
213  bool IsIdempotent(internal::PatchBucketRequest const& request) const override;
215  internal::GetBucketIamPolicyRequest const& request) const override;
217  internal::SetNativeBucketIamPolicyRequest const& request) const override;
219  internal::TestBucketIamPermissionsRequest const& request) const override;
221  internal::LockBucketRetentionPolicyRequest const& request) const override;
222  //@}
223 
224  //@{
225  /// @name Object resource operations
227  internal::InsertObjectMediaRequest const& request) const override;
228  bool IsIdempotent(internal::CopyObjectRequest const& request) const override;
230  internal::GetObjectMetadataRequest const& request) const override;
232  internal::ReadObjectRangeRequest const& request) const override;
233  bool IsIdempotent(internal::ListObjectsRequest const& request) const override;
235  internal::DeleteObjectRequest const& request) const override;
237  internal::UpdateObjectRequest const& request) const override;
238  bool IsIdempotent(internal::PatchObjectRequest const& request) const override;
240  internal::ComposeObjectRequest const& request) const override;
242  internal::RewriteObjectRequest const& request) const override;
244  internal::ResumableUploadRequest const& request) const override;
245  bool IsIdempotent(internal::UploadChunkRequest const& request) const override;
246  //@}
247 
248  //@{
249  /// @name BucketAccessControls resource operations
251  internal::ListBucketAclRequest const& request) const override;
253  internal::CreateBucketAclRequest const& request) const override;
255  internal::DeleteBucketAclRequest const& request) const override;
257  internal::GetBucketAclRequest const& request) const override;
259  internal::UpdateBucketAclRequest const& request) const override;
261  internal::PatchBucketAclRequest const& request) const override;
262  //@}
263 
264  //@{
265  /// @name ObjectAccessControls operations
267  internal::ListObjectAclRequest const& request) const override;
269  internal::CreateObjectAclRequest const& request) const override;
271  internal::DeleteObjectAclRequest const& request) const override;
273  internal::GetObjectAclRequest const& request) const override;
275  internal::UpdateObjectAclRequest const& request) const override;
277  internal::PatchObjectAclRequest const& request) const override;
278  //@}
279 
280  //@{
281  /// @name DefaultObjectAccessControls operations.
283  internal::ListDefaultObjectAclRequest const& request) const override;
285  internal::CreateDefaultObjectAclRequest const& request) const override;
287  internal::DeleteDefaultObjectAclRequest const& request) const override;
289  internal::GetDefaultObjectAclRequest const& request) const override;
291  internal::UpdateDefaultObjectAclRequest const& request) const override;
293  internal::PatchDefaultObjectAclRequest const& request) const override;
294  //@}
295 
296  //@{
298  internal::GetProjectServiceAccountRequest const& request) const override;
300  internal::ListHmacKeysRequest const& request) const override;
302  internal::CreateHmacKeyRequest const& request) const override;
304  internal::DeleteHmacKeyRequest const& request) const override;
305  bool IsIdempotent(internal::GetHmacKeyRequest const& request) const override;
307  internal::UpdateHmacKeyRequest const& request) const override;
308  bool IsIdempotent(internal::SignBlobRequest const& request) const override;
309  //@}
310 
311  //@{
313  internal::ListNotificationsRequest const& request) const override;
315  internal::CreateNotificationRequest const& request) const override;
317  internal::GetNotificationRequest const& request) const override;
319  internal::DeleteNotificationRequest const& request) const override;
320  //@}
321 };
322 
323 /**
324  * A IdempotencyPolicy that only retries strictly idempotent requests.
325  */
327  public:
329 
330  std::unique_ptr<IdempotencyPolicy> clone() const override;
331 
332  //@{
333  /// @name Bucket resource operations
334  bool IsIdempotent(internal::ListBucketsRequest const& request) const override;
336  internal::CreateBucketRequest const& request) const override;
338  internal::GetBucketMetadataRequest const& request) const override;
340  internal::DeleteBucketRequest const& request) const override;
342  internal::UpdateBucketRequest const& request) const override;
343  bool IsIdempotent(internal::PatchBucketRequest const& request) const override;
345  internal::GetBucketIamPolicyRequest const& request) const override;
347  internal::SetNativeBucketIamPolicyRequest const& request) const override;
349  internal::TestBucketIamPermissionsRequest const& request) const override;
351  internal::LockBucketRetentionPolicyRequest const& request) const override;
352  //@}
353 
354  //@{
355  /// @name Object resource operations
357  internal::InsertObjectMediaRequest const& request) const override;
358  bool IsIdempotent(internal::CopyObjectRequest const& request) const override;
360  internal::GetObjectMetadataRequest const& request) const override;
362  internal::ReadObjectRangeRequest const& request) const override;
363  bool IsIdempotent(internal::ListObjectsRequest const& request) const override;
365  internal::DeleteObjectRequest const& request) const override;
367  internal::UpdateObjectRequest const& request) const override;
368  bool IsIdempotent(internal::PatchObjectRequest const& request) const override;
370  internal::ComposeObjectRequest const& request) const override;
372  internal::RewriteObjectRequest const& request) const override;
374  internal::ResumableUploadRequest const& request) const override;
375  bool IsIdempotent(internal::UploadChunkRequest const& request) const override;
376  //@}
377 
378  //@{
379  /// @name BucketAccessControls resource operations
381  internal::ListBucketAclRequest const& request) const override;
383  internal::CreateBucketAclRequest const& request) const override;
385  internal::DeleteBucketAclRequest const& request) const override;
387  internal::GetBucketAclRequest const& request) const override;
389  internal::UpdateBucketAclRequest const& request) const override;
391  internal::PatchBucketAclRequest const& request) const override;
392  //@}
393 
394  //@{
395  /// @name ObjectAccessControls operations
397  internal::ListObjectAclRequest const& request) const override;
399  internal::CreateObjectAclRequest const& request) const override;
401  internal::DeleteObjectAclRequest const& request) const override;
403  internal::GetObjectAclRequest const& request) const override;
405  internal::UpdateObjectAclRequest const& request) const override;
407  internal::PatchObjectAclRequest const& request) const override;
408  //@}
409 
410  //@{
411  /// @name DefaultObjectAccessControls operations.
413  internal::ListDefaultObjectAclRequest const& request) const override;
415  internal::CreateDefaultObjectAclRequest const& request) const override;
417  internal::DeleteDefaultObjectAclRequest const& request) const override;
419  internal::GetDefaultObjectAclRequest const& request) const override;
421  internal::UpdateDefaultObjectAclRequest const& request) const override;
423  internal::PatchDefaultObjectAclRequest const& request) const override;
424  //@}
425 
426  //@{
428  internal::GetProjectServiceAccountRequest const& request) const override;
430  internal::ListHmacKeysRequest const& request) const override;
432  internal::CreateHmacKeyRequest const& request) const override;
434  internal::DeleteHmacKeyRequest const& request) const override;
435  bool IsIdempotent(internal::GetHmacKeyRequest const& request) const override;
437  internal::UpdateHmacKeyRequest const& request) const override;
438  bool IsIdempotent(internal::SignBlobRequest const& request) const override;
439  //@}
440 
441  //@{
443  internal::ListNotificationsRequest const& request) const override;
445  internal::CreateNotificationRequest const& request) const override;
447  internal::GetNotificationRequest const& request) const override;
449  internal::DeleteNotificationRequest const& request) const override;
450  //@}
451 };
452 
454 } // namespace storage
455 } // namespace cloud
456 } // namespace google
457 
458 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_IDEMPOTENCY_POLICY_H