feat(Storage): implement GCS idempotency tokens for all API operations- #10

Storage/src/Connection/Rest.php

@@ -19,7 +19,6 @@
 
 use Google\Auth\GetUniverseDomainInterface;
 use Google\Cloud\Core\RequestBuilder;
-use Google\Cloud\Core\RequestWrapper;
 use Google\Cloud\Core\RestTrait;
 use Google\Cloud\Core\Retry;
 use Google\Cloud\Core\Upload\AbstractUploader;
@@ -141,7 +140,7 @@ public function __construct(array $config = [])
 
         $this->apiEndpoint = $this->getApiEndpoint(null, $config, self::DEFAULT_API_ENDPOINT_TEMPLATE);
 
-        $this->setRequestWrapper(new RequestWrapper($config));
+        $this->setRequestWrapper(new StorageRequestWrapper($config));
         $this->setRequestBuilder(new RequestBuilder(
             $config['serviceDefinitionPath'],
             $this->apiEndpoint

Storage/src/Connection/StorageRequestWrapper.php

@@ -0,0 +1,95 @@
+<?php
+
+/**
+ * Copyright 2026 Google Inc. All Rights Reserved.
+ *
+ * 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
+ *
+ *      http://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.
+ */
+
+namespace Google\Cloud\Storage\Connection;
+
+use Google\Cloud\Core\RequestWrapper;
+use Psr\Http\Message\RequestInterface;
+use Ramsey\Uuid\Uuid;
+
+/**
+ * A wrapper for requests which adds an Idempotency Token.
+ *
+ * @internal
+ */
+class StorageRequestWrapper extends RequestWrapper
+{
+    /**
+     * @param RequestInterface $request A PSR-7 request.
+     * @param array $options [optional]
+     * @return mixed
+     */
+    public function send(RequestInterface $request, array $options = [])
+    {
+        $options = $this->addToken($request, $options);
+        return parent::send($request, $options);
+    }
+
+    /**
+     * @param RequestInterface $request A PSR-7 request.
+     * @param array $options [optional]
+     * @return mixed
+     */
+    public function sendAsync(RequestInterface $request, array $options = [])
+    {
+        $options = $this->addToken($request, $options);
+        return parent::sendAsync($request, $options);
+    }
+
+    /**
+     * Helper to inject the token.
+     *
+     * @param RequestInterface $request
+     * @param array $options
+     * @return array
+     */
+    private function addToken(RequestInterface $request, array $options)
+    {
+        $method = strtoupper($request->getMethod());
+        if (in_array($method, ['GET', 'HEAD', 'OPTIONS'])) {
+            return $options;
+        }
+
+        $hasTokenInOptions = false;
+        if (isset($options['restOptions']['headers'])) {
+            foreach ($options['restOptions']['headers'] as $key => $value) {
+                if (strtolower($key) === 'x-goog-gcs-idempotency-token') {
+                    $hasTokenInOptions = true;
+                    break;
+                }
+            }
+        }
+
+        if (!$hasTokenInOptions && !$request->hasHeader('x-goog-gcs-idempotency-token')) {
+            $token = Uuid::uuid4()->toString();
+            if (isset($options['retryHeaders'])) {
+                foreach ($options['retryHeaders'] as $header) {
+                    if (strpos($header, 'gccl-invocation-id/') === 0) {
+                        $extractedToken = substr($header, 19);
+                        if ($extractedToken !== false && $extractedToken !== '') {
+                            $token = $extractedToken;
+                        }
+                        break;
+                    }
+                }
+            }
+            $options['restOptions']['headers']['x-goog-gcs-idempotency-token'] = $token;
+        }
+        return $options;
+    }
+}

Storage/tests/System/ManageObjectsTest.php

@@ -22,6 +22,7 @@
 use Google\Cloud\Storage\StorageObject;
 use GuzzleHttp\Promise\PromiseInterface;
 use Psr\Http\Message\StreamInterface;
+use Ramsey\Uuid\Uuid;
 
 /**
  * @group storage
@@ -542,6 +543,81 @@ public function testUploadAsync()
         $this->assertInstanceOf(StorageObject::class, $resp);
     }
 
+    public function testIdempotencyTokenRetries()
+    {
+        $name = uniqid(self::TESTING_PREFIX);
+        $object = self::$bucket->upload('test data', [
+            'name' => $name
+        ]);
+
+        $uuid = Uuid::uuid4()->toString();
+
+        // First delete will succeed
+        $object->delete([
+            'restOptions' => [
+                'headers' => [
+                    'x-goog-gcs-idempotency-token' => $uuid
+                ]
+            ]
+        ]);
+
+        // Second delete uses the exact same UUID, simulating a network retry.
+        // It should NOT throw a NotFoundException because the GCS backend
+        // will recognize the token and return the cached success response.
+        $object->delete([
+            'restOptions' => [
+                'headers' => [
+                    'x-goog-gcs-idempotency-token' => $uuid
+                ]
+            ]
+        ]);
+
+        $this->assertFalse($object->exists());
+    }
+
+    public function testIdempotencyTokenUpdateRetriesWithPrecondition()
+    {
+        $name = uniqid(self::TESTING_PREFIX);
+        $object = self::$bucket->upload('test data', [
+            'name' => $name
+        ]);
+
+        $info = $object->info();
+        $metageneration = $info['metageneration'];
+
+        $uuid = Uuid::uuid4()->toString();
+
+        $metadata = [
+            'metadata' => [
+                'location' => 'test'
+            ]
+        ];
+
+        // First update will succeed and increment the metageneration
+        $object->update($metadata, [
+            'ifMetagenerationMatch' => $metageneration,
+            'restOptions' => [
+                'headers' => [
+                    'x-goog-gcs-idempotency-token' => $uuid
+                ]
+            ]
+        ]);
+
+        // Second update uses the exact same UUID, simulating a network retry.
+        // Even though the metageneration has changed, the backend recognizes
+        // the idempotency token and returns 200 OK instead of 412 Precondition Failed.
+        $object->update($metadata, [
+            'ifMetagenerationMatch' => $metageneration,
+            'restOptions' => [
+                'headers' => [
+                    'x-goog-gcs-idempotency-token' => $uuid
+                ]
+            ]
+        ]);
+
+        $this->assertEquals('test', $object->info()['metadata']['location']);
+    }
+
     public function testUpdateObject()
     {
         $metadata = [