docs: add gaxios and node 18 migration guide

handwritten/storage/MIGRATION.md

@@ -0,0 +1,84 @@
+# Storage v7 to v8 Migration Guide - Node.js 18 & Gaxios Update
+
+This guide helps you migrate your application from `@google-cloud/storage` v7 to v8, focusing on the transition to Node.js 18+ as the minimum supported environment and changes introduced by updating the underlying HTTP client, `gaxios`, to version 7.
+
+## Minimum Requirements: Node.js 18
+
+`@google-cloud/storage` v8 now officially requires Node.js 18 or higher. This update aligns the library with modern JavaScript environments.
+
+Specifically, Node.js 18 introduced native global Web APIs (such as `fetch` and `Headers`). Conforming to this standard, the underlying HTTP client, `gaxios` (updated to v7), leverages native `Headers` rather than custom user-land header representations. As a result, `@google-cloud/storage` v8 has transitioned response and request headers to standard native global `Headers` objects.
+
+
+## Key Breaking Changes for Storage Users
+
+### 1. Response Headers are now `Headers` objects
+
+When you receive a full API response from Storage methods (e.g., via callbacks or promise resolutions that include the response object), the `headers` property of the response is now a standard native `Headers` object (aligned with the Fetch API standard in Node.js 18) rather than a plain JavaScript object.
+
+**Before (Storage v7):**
+
+```js
+const [retrievedFile, apiResponse] = await file.get();
+const contentType = apiResponse.headers['content-type'];
+```
+
+**After (Storage v8):**
+
+```js
+const [retrievedFile, apiResponse] = await file.get();
+// Accessing headers requires the .get() method
+const contentType = apiResponse.headers.get('content-type');
+```
+
+### 2. Passing Headers in Options
+
+If you pass custom headers in options to Storage methods (which extend `GaxiosOptions`), you can still pass plain objects, as the Storage library will convert them to standard `Headers` internally for the request. However, if you read them back from the prepared options or response, they will be `Headers` objects.
+
+**Before (Storage v7):**
+
+```js
+// Reading request headers back from response metadata returned a plain object
+const customHeader = apiResponse.config.headers['x-custom-header'];
+```
+
+**After (Storage v8):**
+
+```js
+// Reading request headers back from response metadata requires .get()
+const customHeader = apiResponse.config.headers.get('x-custom-header');
+```
+
+> [!WARNING]
+> **Header Value Stringification:** Plain JavaScript objects allow passing non-string values (such as arrays or numbers) which are implicitly processed. However, the native `Headers` constructor strictly converts all values to standard string representations. For example, passing an array of values (e.g., `['val1', 'val2']`) will result in a single comma-separated string (e.g., `'val1, val2'`). Ensure you pre-format or verify your header values before passing them to custom options.
+
+
+### 3. URL Resolution (`baseURL`)
+
+If you are using custom `baseURL` options or passing relative URLs to methods that accept them, be aware that resolution now strictly follows the standard native `URL` constructor spec (`new URL(url, baseURL)`). This can affect how leading slashes in paths resolve.
+
+**Before (Storage v7):**
+
+Using standard path-joining custom resolution:
+- `baseURL`: `https://storage.googleapis.com/storage/v1`
+- `url`: `/b/my-bucket`
+- Resolved URL: `https://storage.googleapis.com/storage/v1/b/my-bucket`
+
+**After (Storage v8):**
+
+Strictly resolved via the standard native `URL` constructor rules (where a leading slash resolves relative to the root of the host):
+- `baseURL`: `https://storage.googleapis.com/storage/v1`
+- `url`: `/b/my-bucket`
+- Resolved URL: `https://storage.googleapis.com/b/my-bucket` (resolves relative to host root, stripping `storage/v1`)
+
+
+## Upgrade Instructions
+
+Update your `@google-cloud/storage` dependency to version 8:
+
+```sh
+npm install @google-cloud/storage@latest
+```
+
+## Troubleshooting
+
+- If you encounter `undefined` when accessing headers on the response object, ensure you are using `apiResponse.headers.get('header-name')`.

handwritten/storage/system-test/storage.ts

@@ -286,12 +286,7 @@ describe('storage', function () {
         await bucket.acl.delete({entity: USER_ACCOUNT});
       });
 
-      /**
-       * TODO: Re-enable once the test environment allows public IAM roles.
-       * Currently disabled to avoid 403 errors when adding 'allUsers' or
-       * 'allAuthenticatedUsers' permissions.
-       */
-      it.skip('should make a bucket public', async () => {
+      it('should make a bucket public', async () => {
         await bucket.makePublic();
         const [aclObject] = await bucket.acl.get({entity: 'allUsers'});
         assert.deepStrictEqual(aclObject, {
@@ -304,12 +299,7 @@ describe('storage', function () {
         await bucket.acl.delete({entity: 'allUsers'});
       });
 
-      /**
-       * TODO: Re-enable once the test environment allows public IAM roles.
-       * Currently disabled to avoid 403 errors when adding 'allUsers' or
-       * 'allAuthenticatedUsers' permissions.
-       */
-      it.skip('should make files public', async () => {
+      it('should make files public', async () => {
         await Promise.all(
           ['a', 'b', 'c'].map(text => createFileWithContentPromise(text)),
         );
@@ -326,12 +316,7 @@ describe('storage', function () {
         ]);
       });
 
-      /**
-       * TODO: Re-enable once the test environment allows public IAM roles.
-       * Currently disabled to avoid 403 errors when adding 'allUsers' or
-       * 'allAuthenticatedUsers' permissions.
-       */
-      it.skip('should make a bucket private', async () => {
+      it('should make a bucket private', async () => {
         try {
           await bucket.makePublic();
           await new Promise(resolve =>
@@ -416,12 +401,7 @@ describe('storage', function () {
         await file.acl.delete({entity: USER_ACCOUNT});
       });
 
-      /**
-       * TODO: Re-enable once the test environment allows public IAM roles.
-       * Currently disabled to avoid 403 errors when adding 'allUsers' or
-       * 'allAuthenticatedUsers' permissions.
-       */
-      it.skip('should make a file public', async () => {
+      it('should make a file public', async () => {
         await file.makePublic();
         const [aclObject] = await file.acl.get({entity: 'allUsers'});
         assert.deepStrictEqual(aclObject, {
@@ -469,12 +449,7 @@ describe('storage', function () {
         assert.strictEqual(encryptionAlgorithm, 'AES256');
       });
 
-      /**
-       * TODO: Re-enable once the test environment allows public IAM roles.
-       * Currently disabled to avoid 403 errors when adding 'allUsers' or
-       * 'allAuthenticatedUsers' permissions.
-       */
-      it.skip('should make a file public during the upload', async () => {
+      it('should make a file public during the upload', async () => {
         const [file] = await bucket.upload(FILES.big.path, {
           resumable: false,
           public: true,
@@ -487,12 +462,7 @@ describe('storage', function () {
         });
       });
 
-      /**
-       * TODO: Re-enable once the test environment allows public IAM roles.
-       * Currently disabled to avoid 403 errors when adding 'allUsers' or
-       * 'allAuthenticatedUsers' permissions.
-       */
-      it.skip('should make a file public from a resumable upload', async () => {
+      it('should make a file public from a resumable upload', async () => {
         const [file] = await bucket.upload(FILES.big.path, {
           resumable: true,
           public: true,
@@ -556,12 +526,7 @@ describe('storage', function () {
         ]);
       });
 
-      /**
-       * TODO: Re-enable once the test environment allows public IAM roles.
-       * Currently disabled to avoid 403 errors when adding 'allUsers' or
-       * 'allAuthenticatedUsers' permissions.
-       */
-      it.skip('should set a policy', async () => {
+      it('should set a policy', async () => {
         const [policy] = await bucket.iam.getPolicy();
         policy!.bindings.push({
           role: 'roles/storage.legacyBucketReader',
@@ -3141,12 +3106,7 @@ describe('storage', function () {
       await Promise.all([file.delete, copiedFile.delete()]);
     });
 
-    /**
-     * TODO: Re-enable once the test environment allows public IAM roles.
-     * Currently disabled to avoid 403 errors when adding 'allUsers' or
-     * 'allAuthenticatedUsers' permissions.
-     */
-    it.skip('should respect predefined Acl at file#copy', async () => {
+    it('should respect predefined Acl at file#copy', async () => {
       const opts = {destination: 'CloudLogo'};
       const [file] = await bucket.upload(FILES.logo.path, opts);
       const copyOpts = {predefinedAcl: 'publicRead'};