feat: add storage control anywhere cache samples

storage-control/createAnywhereCache.js

@@ -0,0 +1,122 @@
+// Copyright 2025 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.
+
+'use strict';
+
+/**
+ * This application demonstrates how to perform basic operations on an Anywhere Cache
+ * instance with the Google Cloud Storage API.
+ *
+ * For more information, see the documentation at https://cloud.google.com/storage/docs/anywhere-cache.
+ */
+
+function main(bucketName, zoneName) {
+  // [START storage_control_create_anywhere_cache]
+
+  /**
+   * Creates an Anywhere Cache instance for a Cloud Storage bucket.
+   * Anywhere Cache is a feature that provides an SSD-backed zonal read cache.
+   * This can significantly improve read performance for frequently accessed data
+   * by caching it in the same zone as your compute resources.
+   *
+   * @param {string} bucketName The name of the bucket to create the cache for.
+   * Example: 'your-gcp-bucket-name'
+   * @param {string} zoneName The zone where the cache will be created.
+   * Example: 'us-central1-a'
+   */
+
+  // Imports the Control library
+  const {StorageControlClient} = require('@google-cloud/storage-control').v2;
+
+  // Instantiates a client
+  const controlClient = new StorageControlClient();
+
+  async function callCreateAnywhereCache() {
+    const bucketPath = controlClient.bucketPath('_', bucketName);
+
+    // Create the request
+    const request = {
+      parent: bucketPath,
+      anywhereCache: {
+        zone: zoneName,
+        ttl: {
+          seconds: '10000s',
+        }, // Optional. Default: '86400s'(1 day)
+        admissionPolicy: 'admit-on-first-miss', // Optional. Default: 'admit-on-first-miss'
+      },
+    };
+
+    try {
+      // Run the request, which returns an Operation object
+      const [operation] = await controlClient.createAnywhereCache(request);
+      console.log(`Waiting for operation ${operation.name} to complete...`);
+
+      // Wait for the operation to complete and get the final resource
+      const anywhereCache = await checkCreateAnywhereCacheProgress(
+        operation.name
+      );
+      console.log(`Created anywhere cache: ${anywhereCache.result.name}.`);
+    } catch (error) {
+      // Handle any error that occurred during the creation or polling process.
+      console.error('Failed to create Anywhere Cache:', error.message);
+      throw error;
+    }
+  }
+
+  // A custom function to check the operation's progress.
+  async function checkCreateAnywhereCacheProgress(operationName) {
+    let operation = {done: false};
+    console.log('Starting manual polling for operation...');
+
+    // Poll the operation until it's done.
+    while (!operation.done) {
+      await new Promise(resolve => setTimeout(resolve, 180000)); // Wait for 3 minutes before the next check.
+      const request = {
+        name: operationName,
+      };
+      try {
+        const [latestOperation] = await controlClient.getOperation(request);
+        operation = latestOperation;
+      } catch (err) {
+        // Handle potential errors during polling.
+        console.error('Error while polling:', err.message);
+        break; // Exit the loop on error.
+      }
+    }
+
+    // Return the final result of the operation.
+    if (operation.response) {
+      // Decode the operation response into a usable Operation object
+      const decodeOperation = new controlClient._gaxModule.Operation(
+        operation,
+        controlClient.descriptors.longrunning.createAnywhereCache,
+        controlClient._gaxModule.createDefaultBackoffSettings()
+      );
+      // Return the decoded operation
+      return decodeOperation;
+    } else {
+      // If there's no response, it indicates an issue, so throw an error
+      throw new Error('Operation completed without a response.');
+    }
+  }
+
+  callCreateAnywhereCache();
+  // [END storage_control_create_anywhere_cache]
+}
+
+process.on('unhandledRejection', err => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+main(...process.argv.slice(2));

storage-control/disableAnywhereCache.js

@@ -0,0 +1,104 @@
+// Copyright 2025 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.
+
+'use strict';
+
+/**
+ * This application demonstrates how to perform basic operations on an Anywhere Cache
+ * instance with the Google Cloud Storage API.
+ *
+ * For more information, see the documentation at https://cloud.google.com/storage/docs/anywhere-cache.
+ */
+
+function main(bucketName, cacheName) {
+  // [START storage_control_disable_anywhere_cache]
+  /**
+   * Disables an Anywhere Cache instance.
+   *
+   * Disabling a cache is the first step to permanently removing it. Once disabled,
+   * the cache stops ingesting new data. After a grace period, the cache and its
+   * contents are deleted. This is useful for decommissioning caches that are no
+   * longer needed.
+   *
+   * @param {string} bucketName The name of the bucket where the cache resides.
+   * Example: 'your-gcp-bucket-name'
+   * @param {string} cacheName The unique identifier of the cache instance to disable.
+   * Example: 'cacheName'
+   */
+
+  // Imports the Control library
+  const {StorageControlClient} = require('@google-cloud/storage-control').v2;
+
+  // Instantiates a client
+  const controlClient = new StorageControlClient();
+
+  async function callDisableAnywhereCache() {
+    // You have a one-hour grace period after disabling a cache to resume it and prevent its deletion.
+    // If you don't resume the cache within that hour, it will be deleted, its data will be evicted,
+    // and the cache will be permanently removed from the bucket.
+
+    const anywhereCachePath = controlClient.anywhereCachePath(
+      '_',
+      bucketName,
+      cacheName
+    );
+
+    // Create the request
+    const request = {
+      name: anywhereCachePath,
+    };
+
+    try {
+      // Run request. This initiates the disablement process.
+      const [response] = await controlClient.disableAnywhereCache(request);
+
+      console.log(
+        `Successfully initiated disablement for Anywhere Cache: '${cacheName}'.`
+      );
+      console.log(`  Current State: ${response.state}`);
+      console.log(`  Resource Name: ${response.name}`);
+    } catch (error) {
+      // Catch and handle potential API errors.
+      console.error(
+        `Error disabling Anywhere Cache '${cacheName}': ${error.message}`
+      );
+
+      if (error.code === 5) {
+        // NOT_FOUND (gRPC code 5) error can occur if the bucket or cache does not exist.
+        console.error(
+          `Please ensure the cache '${cacheName}' exists in bucket '${bucketName}'.`
+        );
+      } else if (error.code === 9) {
+        // FAILED_PRECONDITION (gRPC code 9) can occur if the cache is already being disabled
+        // or is not in a RUNNING state that allows the disable operation.
+        console.error(
+          `Cache '${cacheName}' may not be in a state that allows disabling (e.g., must be RUNNING).`
+        );
+      }
+      throw error;
+    }
+    // Run request
+    const [response] = await controlClient.disableAnywhereCache(request);
+    console.log(`Disabled anywhere cache: ${response.name}.`);
+  }
+
+  callDisableAnywhereCache();
+  // [END storage_control_disable_anywhere_cache]
+}
+
+process.on('unhandledRejection', err => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+main(...process.argv.slice(2));

storage-control/getAnywhereCache.js

@@ -0,0 +1,91 @@
+// Copyright 2025 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.
+
+'use strict';
+
+/**
+ * This application demonstrates how to perform basic operations on an Anywhere Cache
+ * instance with the Google Cloud Storage API.
+ *
+ * For more information, see the documentation at https://cloud.google.com/storage/docs/anywhere-cache.
+ */
+
+function main(bucketName, cacheName) {
+  // [START storage_control_get_anywhere_cache]
+  /**
+   * Retrieves details of a specific Anywhere Cache instance.
+   *
+   * This function is useful for checking the current state, configuration (like TTL),
+   * and other metadata of an existing cache.
+   *
+   * @param {string} bucketName The name of the bucket where the cache resides.
+   * Example: 'your-gcp-bucket-name'
+   * @param {string} cacheName The unique identifier of the cache instance.
+   * Example: 'my-anywhere-cache-id'
+   */
+
+  // Imports the Control library
+  const {StorageControlClient} = require('@google-cloud/storage-control').v2;
+
+  // Instantiates a client
+  const controlClient = new StorageControlClient();
+
+  async function callGetAnywhereCache() {
+    const anywhereCachePath = controlClient.anywhereCachePath(
+      '_',
+      bucketName,
+      cacheName
+    );
+
+    // Create the request
+    const request = {
+      name: anywhereCachePath,
+    };
+
+    try {
+      // Run request
+      const [response] = await controlClient.getAnywhereCache(request);
+      console.log(`Anywhere Cache details for '${cacheName}':`);
+      console.log(`  Name: ${response.name}`);
+      console.log(`  Zone: ${response.zone}`);
+      console.log(`  State: ${response.state}`);
+      console.log(`  TTL: ${response.ttl.seconds}s`);
+      console.log(`  Admission Policy: ${response.admissionPolicy}`);
+      console.log(
+        `  Create Time: ${new Date(response.createTime.seconds * 1000).toISOString()}`
+      );
+    } catch (error) {
+      // Handle errors (e.g., cache not found, permission denied).
+      console.error(
+        `Error retrieving Anywhere Cache '${cacheName}': ${error.message}`
+      );
+
+      if (error.code === 5) {
+        console.error(
+          `Ensure the cache '${cacheName}' exists in bucket '${bucketName}'.`
+        );
+      }
+      throw error;
+    }
+  }
+
+  callGetAnywhereCache();
+  // [END storage_control_get_anywhere_cache]
+}
+
+process.on('unhandledRejection', err => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+main(...process.argv.slice(2));