feat(storage): adding_support_for_partialsuccess_bucket_list

google-cloud-storage/lib/google/cloud/storage/bucket/list.rb

@@ -27,6 +27,14 @@ class List < DelegateClass(::Array)
           # that match the request and this value should be passed to
           # the next {Google::Cloud::Storage::Project#buckets} to continue.
           attr_accessor :token
+          ##
+          # The list of buckets that could not be reached.
+          #
+          # This is only populated when `return_partial_success` is set to `true`
+          # in the call to {Google::Cloud::Storage::Project#buckets}.
+          #
+          # @return [Array<String>]
+          attr_reader :unreachable
 
           ##
           # @private Create a new Bucket::List with an array of values.
@@ -147,7 +155,7 @@ def all request_limit: nil, &block
           # @private New Bucket::List from a Google API Client
           # Google::Apis::StorageV1::Buckets object.
           def self.from_gapi gapi_list, service, prefix = nil, max = nil,
-                             user_project: nil, soft_deleted: nil
+                             user_project: nil, soft_deleted: nil, return_partial_success: nil
             buckets = new(Array(gapi_list.items).map do |gapi_object|
               Bucket.from_gapi gapi_object, service, user_project: user_project
             end)
@@ -157,6 +165,7 @@ def self.from_gapi gapi_list, service, prefix = nil, max = nil,
             buckets.instance_variable_set :@max, max
             buckets.instance_variable_set :@user_project, user_project
             buckets.instance_variable_set :@soft_deleted, soft_deleted
+            buckets.instance_variable_set :@unreachable, Array(gapi_list.unreachable) if return_partial_success
             buckets
           end
 

google-cloud-storage/lib/google/cloud/storage/project.rb

@@ -158,6 +158,8 @@ def add_custom_header header_name, header_value
         #   bucket instances and their files.
         #
         #   See also {Bucket#requester_pays=} and {Bucket#requester_pays}.
+        # @param [Boolean] return_partial_success If true, retrieves the list of
+        #   buckets that could not be reached.
         #
         # @return [Array<Google::Cloud::Storage::Bucket>] (See
         #   {Google::Cloud::Storage::Bucket::List})
@@ -201,11 +203,22 @@ def add_custom_header header_name, header_value
         #   soft_deleted_buckets.each do |bucket|
         #     puts bucket.name
         #   end
-        def buckets prefix: nil, token: nil, max: nil, user_project: nil, soft_deleted: nil
+        # @example Retrieve list of unreachable buckets
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   buckets = storage.buckets return_partial_success: true
+        #   buckets.unreachable.each do |bucket|
+        #     puts bucket
+        #   end
+        #  
+        def buckets prefix: nil, token: nil, max: nil, user_project: nil, soft_deleted: nil, return_partial_success: nil
           gapi = service.list_buckets \
-            prefix: prefix, token: token, max: max, user_project: user_project, soft_deleted: soft_deleted
+            prefix: prefix, token: token, max: max, user_project: user_project, soft_deleted: soft_deleted, return_partial_success: return_partial_success
           Bucket::List.from_gapi \
-            gapi, service, prefix, max, user_project: user_project, soft_deleted: soft_deleted
+            gapi, service, prefix, max, user_project: user_project, soft_deleted: soft_deleted, return_partial_success: return_partial_success
+
         end
         alias find_buckets buckets
 

google-cloud-storage/lib/google/cloud/storage/service.rb

@@ -96,12 +96,14 @@ def project_service_account
 
         ##
         # Retrieves a list of buckets for the given project.
-        def list_buckets prefix: nil, token: nil, max: nil, user_project: nil, soft_deleted: nil, options: {}
+        def list_buckets prefix: nil, token: nil, max: nil, user_project: nil, soft_deleted: nil, return_partial_success: nil, options: {}
           execute do
             service.list_buckets \
               @project, prefix: prefix, page_token: token, max_results: max,
                         user_project: user_project(user_project),
-                        soft_deleted: soft_deleted, options: options
+                        soft_deleted: soft_deleted,
+                        return_partial_success: return_partial_success,
+                        options: options
           end
         end
 

google-cloud-storage/samples/storage_list_unreachable_buckets.rb

@@ -0,0 +1,46 @@
+# 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
+#
+#     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.
+
+# [START storage_list_buckets_partial_success]
+# Lists and prints buckets that were reported as unreachable when requesting
+# a (possibly partial) list of buckets from Google Cloud Storage.
+#
+# This helper enables partial success when listing buckets by setting
+# `return_partial_success: true` on the API call. When the server returns
+# partial results, the returned collection exposes an `unreachable` list
+# containing the names (or identifiers) of buckets that could not be
+# retrieved in the request. This method iterates over that list and writes
+# each unreachable bucket to STDOUT.
+#
+# Behavior:
+# - Initializes a Storage client.
+# - Uses `Storage#buckets(return_partial_success: true)` to request buckets.
+# - Prints one unreachable bucket per line to standard output.
+#
+# Example:
+#   # Ensure credentials and project are configured, then call:
+#   list_unreachable_buckets
+
+def list_unreachable_buckets
+  require "google/cloud/storage"
+
+  storage = Google::Cloud::Storage.new
+  bucket_list = storage.buckets(return_partial_success: true)
+  bucket_list.unreachable.each do |bucket|
+    puts bucket
+  end
+end
+# [END storage_list_buckets_partial_success]
+
+list_unreachable_buckets if $PROGRAM_NAME == __FILE__