google-cloud-storage 1.59.0 → 1.60.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a5e8e41dae5b34405a89c08fcd7f69b05cf5a062c976a2bc2f2cd7bdbfbbc91
-  data.tar.gz: 5464e7f858f731504b9986103b184ba7de27ecb0b5ef049000c5f3231ef558d3
+  metadata.gz: 925378eecd9da2c4ab58069c24c0b4ef3b3b8a210484d5262b4339b2b8c9764b
+  data.tar.gz: 0b771cf975054dc8f01e129ed7c244907df82d6e62b8e75a43dbed4ef926a979
 SHA512:
-  metadata.gz: de418f7fd18cb8b404d9c74d11ef980c71ed0250e8776bd81ca60d3c7f4f672d475f6a90c2250f85d3a00227203e63005fee7d0a52cbc8ef772db390f8695274
-  data.tar.gz: cfdd5a84b8bb02e721434c6c137e856386aeab2d7909c238e4fc28af82a3e4ac974708e8dad582e45349572acebd5538e9c992b1041215780c236ea833154709
+  metadata.gz: 54cf73c127fb464fc4829b32d3aaa246b55a81ee56f2930362819827ed39d7d273e6100bcea9089ed1d7fac090a032b4e61ed62652a363cb0a1d7efdc933c191
+  data.tar.gz: 50a4568bd351558f59a2c8ac119aab5385618f16489f458d6e29d8e802204f262782ec1c957b8efa8fbaf6c4c1862abcd8899d4a055b5b4d68860550107bc1aa

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release History
 
+### 1.60.0 (2026-05-11)
+
+#### Features
+
+* add support for object context ([#32902](https://github.com/googleapis/google-cloud-ruby/issues/32902)) 
+* setting default checksum ([#33331](https://github.com/googleapis/google-cloud-ruby/issues/33331)) 
+* Support bucket encryption config ([#33452](https://github.com/googleapis/google-cloud-ruby/issues/33452)) 
+
 ### 1.59.0 (2026-03-19)
 
 #### Features

data/lib/google/cloud/storage/bucket.rb

@@ -716,6 +716,171 @@ module Google
             default_kms_key_name: new_default_kms_key
           patch_gapi! :encryption
         end
+        ##
+        # The bucket's encryption configuration for customer-managed encryption keys.
+        # This configuration defines the
+        # default encryption behavior for the bucket and its files, and it can be used to enforce encryption requirements for the bucket.
+        # For more information, see [Bucket encryption](https://docs.cloud.google.com/storage/docs/encryption/).
+        # @return [Google::Apis::StorageV1::Bucket::Encryption::CustomerManagedEncryptionEnforcementConfig, nil] The bucket's encryption configuration, or `nil` if no encryption configuration has been set.
+        # @example
+        #   require "google/cloud/storage"
+        #   #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #   bucket.customer_managed_encryption_enforcement_config 
+        #   ==> #<Google::Apis::StorageV1::Bucket::Encryption::CustomerManagedEncryptionEnforcementConfig:0x00007f3b1c102e90 @restriction_mode="NotRestricted">
+        #   The value for `restriction_mode` can be either "NotRestricted" or "FullyRestricted"
+
+        def customer_managed_encryption_enforcement_config
+          @gapi.encryption&.customer_managed_encryption_enforcement_config
+        end
+        ##
+        # Sets the customer-managed encryption enforcement configuration for the bucket.
+        #
+        # @param new_customer_managed_encryption_enforcement_config [Hash, nil] 
+        #   The configuration hash for encryption enforcement. 
+        #   * `:restriction_mode` (String) - Can be "NotRestricted" or "FullyRestricted".
+        #   Pass `nil` to clear the current configuration.
+        #
+        # @example Enforcing Customer-Managed Encryption
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   # Set restriction mode to FullyRestricted
+        #   restricted_config = { restriction_mode: "FullyRestricted" }
+        #   bucket.customer_managed_encryption_enforcement_config = restricted_config
+        #
+        # @example Setting via Request Object (Google API Client)
+        #   require "google/apis/storage_v1"
+        #
+        #   enforcement_config = { restriction_mode: "FullyRestricted" }
+        #   
+        #   request_obj = Google::Apis::StorageV1::Bucket::Encryption.new(
+        #     customer_managed_encryption_enforcement_config: enforcement_config
+        #   )
+        #   bucket.customer_managed_encryption_enforcement_config = request_obj
+        #
+        # @return [Hash, Google::Apis::StorageV1::Bucket::Encryption] The updated configuration.
+        # @raise [Google::Cloud::Error] If the update fails due to permissions or invalid arguments.
+        def customer_managed_encryption_enforcement_config= new_customer_managed_encryption_enforcement_config
+          @gapi.encryption ||= API::Bucket::Encryption.new
+          @gapi.encryption.customer_managed_encryption_enforcement_config =
+            new_customer_managed_encryption_enforcement_config || {}
+          patch_gapi! :encryption
+        end
+
+        ##
+        # The bucket's encryption configuration for customer-supplied encryption keys.
+        # For more information, see [Bucket encryption](https://docs.cloud.google.com/storage/docs/encryption/).
+        # @return [Google::Apis::StorageV1::Bucket::Encryption::CustomerSuppliedEncryptionEnforcementConfig, nil]
+        # The bucket's encryption configuration, or `nil` if no encryption configuration has been set.
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.customer_supplied_encryption_enforcement_config 
+        #     ==> #<Google::Apis::StorageV1::Bucket::Encryption::CustomerSuppliedEncryptionEnforcementConfig:0x00007f3b1c102e90 @restriction_mode="NotRestricted">
+        #   The value for `restriction_mode` can be either "NotRestricted" or "FullyRestricted".
+
+        def customer_supplied_encryption_enforcement_config
+          @gapi.encryption&.customer_supplied_encryption_enforcement_config
+        end
+
+        ##
+        # Sets the bucket's encryption configuration for customer-supplied encryption that will be used to protect files.
+        # @param new_customer_supplied_encryption_enforcement_config [Hash, nil]
+        #   The configuration hash for encryption enforcement. 
+        #   * `:restriction_mode` (String) - Can be "NotRestricted" or "FullyRestricted".
+        #   Pass `nil` to clear the current configuration.
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #   restricted_config = { restriction_mode: "FullyRestricted" }
+        #   bucket.customer_supplied_encryption_enforcement_config = restricted_config
+        #
+        # @example Setting via Request Object (Google API Client)
+        #   require "google/apis/storage_v1"
+        #
+        #   enforcement_config = { restriction_mode: "FullyRestricted" }
+        #   
+        #   request_obj = Google::Apis::StorageV1::Bucket::Encryption.new(
+        #     customer_supplied_encryption_enforcement_config: enforcement_config
+        #   )
+        #   bucket.customer_supplied_encryption_enforcement_config = request_obj
+        #
+        # @return [Hash, Google::Apis::StorageV1::Bucket::Encryption] The updated configuration.
+        # @raise [Google::Cloud::Error] If the update fails due to permissions or invalid arguments.
+
+        def customer_supplied_encryption_enforcement_config= new_customer_supplied_encryption_enforcement_config
+          @gapi.encryption ||= API::Bucket::Encryption.new
+          @gapi.encryption.customer_supplied_encryption_enforcement_config =
+            new_customer_supplied_encryption_enforcement_config || {}
+          patch_gapi! :encryption
+        end
+
+        ##
+        # The bucket's encryption configuration for google-managed encryption keys.
+        # This configuration defines the
+        # default encryption behavior for the bucket and its files, and it can be used to enforce encryption
+        # requirements for the bucket.
+        # For more information, see [Bucket encryption](https://docs.cloud.google.com/storage/docs/encryption/).
+        # @return [Google::Apis::StorageV1::Bucket::Encryption::GoogleManagedEncryptionEnforcementConfig, nil]
+        # The bucket's encryption configuration, or `nil` if no encryption configuration has been set.
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #   bucket.google_managed_encryption_enforcement_config
+        #   ==> #<Google::Apis::StorageV1::Bucket::Encryption::GoogleManagedEncryptionEnforcementConfig:0x00007f3b1c102e90 @restriction_mode="NotRestricted">
+        #   The value for `restriction_mode` can be either "NotRestricted" or "FullyRestricted".
+
+        def google_managed_encryption_enforcement_config
+          @gapi.encryption&.google_managed_encryption_enforcement_config
+        end
+
+        ##
+        # Sets the google-managed encryption enforcement configuration for the bucket.
+        #
+        # @param new_google_managed_encryption_enforcement_config [Hash, nil] 
+        #   The configuration hash for encryption enforcement. 
+        #   * `:restriction_mode` (String) - Can be "NotRestricted" or "FullyRestricted".
+        #   Pass `nil` to clear the current configuration.
+        #
+        # @example Enforcing Customer-Managed Encryption
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #   # Set restriction mode to FullyRestricted
+        #   restricted_config = { restriction_mode: "FullyRestricted" }
+        #   bucket.google_managed_encryption_enforcement_config = restricted_config
+        #
+        # @example Setting via Request Object (Google API Client)
+        #   require "google/apis/storage_v1"
+        #
+        #   enforcement_config = { restriction_mode: "FullyRestricted" }
+        #   
+        #   request_obj = Google::Apis::StorageV1::Bucket::Encryption.new(
+        #     google_managed_encryption_enforcement_config: enforcement_config
+        #   )
+        #   bucket.google_managed_encryption_enforcement_config = request_obj
+        #
+        # @return [Hash, Google::Apis::StorageV1::Bucket::Encryption] The updated configuration.
+        # @raise [Google::Cloud::Error] If the update fails due to permissions or invalid arguments.
+
+        def google_managed_encryption_enforcement_config= new_google_managed_encryption_enforcement_config
+          @gapi.encryption ||= API::Bucket::Encryption.new
+          @gapi.encryption.google_managed_encryption_enforcement_config =
+            new_google_managed_encryption_enforcement_config || {}
+          patch_gapi! :encryption
+        end
 
         ##
         # The period of time (in seconds) that files in the bucket must be
@@ -1373,6 +1538,7 @@ module Google
           updater.check_for_changed_labels!
           updater.check_for_mutable_cors!
           updater.check_for_mutable_lifecycle!
+          updater.check_for_encryption_enforcement_config!
           return if updater.updates.empty?
           update_gapi! updater.updates,
                        if_metageneration_match: if_metageneration_match,
@@ -1439,7 +1605,23 @@ module Google
         #   Only applicable if delimiter is set to '/'.
         # @param [Boolean] soft_deleted If true, only soft-deleted object
         #   versions will be listed. The default is false.
+        # @param [String] filter An optional string for filtering listed objects.
+        #   Supported fields: contexts
+        #   If delimiter is set, the returned prefixes are exempt from this filter
+        #  List any object that has a context with the specified key attached
+        #  filter = "contexts.\"KEY\":*";
+        #
+        #  List any object that has a context with the specified key attached and value attached
+        #  filter = "contexts.\"keyA\"=\"valueA\""
+        #
+        #  List any object that does not have a context with the specified key attached
+        #  filter = "-contexts.\"KEY\":*";
+        #
+        #  List any object that has a context with the specified key and value attached
+        #  filter = "contexts.\"KEY\"=\"VALUE\"";
         #
+        #  List any object that does not have a context with the specified key and value attached
+        #  filter = "-contexts.\"KEY\"=\"VALUE\"";
         # @return [Array<Google::Cloud::Storage::File>] (See
         #   {Google::Cloud::Storage::File::List})
         #
@@ -1465,9 +1647,18 @@ module Google
         #     puts file.name
         #   end
         #
+        # @example Filter files by context:
+        #   require "google/cloud/storage"
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #   files = bucket.files filter: "contexts.\"myKey\"=\"myValue\""
+        #   files.each do |file|
+        #     puts file.name
+        #   end
+        #
         def files prefix: nil, delimiter: nil, token: nil, max: nil,
                   versions: nil, match_glob: nil, include_folders_as_prefixes: nil,
-                  soft_deleted: nil
+                  soft_deleted: nil, filter: nil
           ensure_service!
           gapi = service.list_files name, prefix: prefix, delimiter: delimiter,
                                           token: token, max: max,
@@ -1475,13 +1666,15 @@ module Google
                                           user_project: user_project,
                                           match_glob: match_glob,
                                           include_folders_as_prefixes: include_folders_as_prefixes,
-                                          soft_deleted: soft_deleted
+                                          soft_deleted: soft_deleted,
+                                          filter: filter
           File::List.from_gapi gapi, service, name, prefix, delimiter, max,
                                versions,
                                user_project: user_project,
                                match_glob: match_glob,
                                include_folders_as_prefixes: include_folders_as_prefixes,
-                               soft_deleted: soft_deleted
+                               soft_deleted: soft_deleted,
+                               filter: filter
         end
         alias find_files files
 
@@ -1628,7 +1821,7 @@ module Google
         #   changed to a time in the future. If custom_time must be unset, you
         #   must either perform a rewrite operation, or upload the data again
         #   and create a new file.
-        # @param [Symbol, nil] checksum The type of checksum for the client to
+        # @param [Symbol, nil, Boolean] checksum The type of checksum for the client to
         #   automatically calculate and send with the create request to verify
         #   the integrity of the object. If provided, Cloud Storage will only
         #   create the file if the value calculated by the client matches the
@@ -1636,11 +1829,12 @@ module Google
         #
         #   Acceptable values are:
         #
+        #   * `true` [Boolean] - Calculate and provide a checksum using the CRC32c hash.
+        #   * `false` [Boolean] - Do not calculate or provide a checksum.
         #   * `md5` - Calculate and provide a checksum using the MD5 hash.
         #   * `crc32c` - Calculate and provide a checksum using the CRC32c hash.
         #   * `all` - Calculate and provide checksums for all available verifications.
-        #
-        #   Optional. The default is `nil`. Do not provide if also providing a
+        #   Optional. The default is `crc32c`. Do not provide if also providing a
         #   corresponding `crc32c` or `md5` argument. See
         #   [Validation](https://cloud.google.com/storage/docs/hashes-etags)
         #   for more information.
@@ -1805,6 +1999,11 @@ module Google
           path ||= file.path if file.respond_to? :path
           path ||= file if file.is_a? String
           raise ArgumentError, "must provide path" if path.nil?
+          # If no checksum type or specific value is provided, the default will be set to crc32c. 
+          # If the checksum is set to false, it will be disabled.
+          if [checksum, crc32c, md5].all?(&:nil?) || checksum == true
+            checksum = :crc32c
+          end
           crc32c = crc32c_for file, checksum, crc32c
           md5 = md5_for file, checksum, md5
 
@@ -3386,6 +3585,26 @@ module Google
             patch_gapi! :lifecycle
           end
 
+          def check_for_encryption_enforcement_config!
+            return unless @gapi.encryption
+
+            [
+              :google_managed_encryption_enforcement_config,
+              :customer_managed_encryption_enforcement_config,
+              :customer_supplied_encryption_enforcement_config
+            ].each do |attr|
+              config = @gapi.encryption.send(attr)
+              next unless config
+              unless config.respond_to?(:to_h)
+                raise ArgumentError, "Encryption config for #{attr} must be a Hash or valid Config object"
+              end
+              clean_config = config.to_h
+              clean_config.delete :effective_time
+              clean_config.delete "effective_time"
+              @gapi.encryption.send "#{attr}=", clean_config
+            end
+          end
+
           protected
 
           ##

data/lib/google/cloud/storage/file/list.rb

@@ -167,7 +167,7 @@ module Google
                              delimiter = nil, max = nil, versions = nil,
                              user_project: nil, match_glob: nil,
                              include_folders_as_prefixes: nil,
-                             soft_deleted: nil
+                             soft_deleted: nil, filter: nil
             files = new(Array(gapi_list.items).map do |gapi_object|
               File.from_gapi gapi_object, service, user_project: user_project
             end)
@@ -183,6 +183,7 @@ module Google
             files.instance_variable_set :@match_glob, match_glob
             files.instance_variable_set :@include_folders_as_prefixes, include_folders_as_prefixes
             files.instance_variable_set :@soft_deleted, soft_deleted
+            files.instance_variable_set :@filter, filter
             files
           end
 

data/lib/google/cloud/storage/file/verifier.rb

@@ -49,29 +49,47 @@ module Google
             gcloud_file.crc32c == crc32c_for(local_file)
           end
 
+          # Calculates MD5 digest using either file path or open stream.
           def self.md5_for local_file
-            if local_file.respond_to? :to_path
-              ::File.open Pathname(local_file).to_path, "rb" do |f|
-                ::Digest::MD5.file(f).base64digest
-              end
-            else # StringIO
-              local_file.rewind
-              md5 = ::Digest::MD5.base64digest local_file.read
-              local_file.rewind
-              md5
-            end
+            _digest_for local_file, ::Digest::MD5
           end
 
+          # Calculates CRC32c digest using either file path or open stream.
           def self.crc32c_for local_file
-            if local_file.respond_to? :to_path
+            _digest_for local_file, ::Digest::CRC32c
+          end
+
+          # @private
+          # Computes a base64-encoded digest for a local file or IO stream.
+          #
+          # This method handles two types of inputs for `local_file`:
+          # 1. A file path (String or Pathname): It efficiently streams the file
+          #    to compute the digest without loading the entire file into memory.
+          # 2. An IO-like stream (e.g., File, StringIO): It reads the stream's
+          #    content to compute the digest. The stream is rewound before and after
+          #    reading to ensure its position is not permanently changed.
+          #
+          # @param local_file [String, Pathname, IO] The local file path or IO
+          #   stream for which to compute the digest.
+          # @param digest_class [Class] The digest class to use for the
+          #   calculation (e.g., `Digest::MD5`). It must respond to `.file` and
+          #   `.base64digest`.
+          #
+          # @return [String] The base64-encoded digest of the file's content.
+          #
+          def self._digest_for local_file, digest_class
+
+            if local_file.respond_to?(:to_path) || local_file.is_a?(String)
+              # Case 1: Input is a file path (String, Pathname, or object that responds to :to_path).
               ::File.open Pathname(local_file).to_path, "rb" do |f|
-                ::Digest::CRC32c.file(f).base64digest
+                digest_class.file(f).base64digest
               end
-            else # StringIO
+            else
+              # Case 2: Input is an open stream (File or StringIO).
               local_file.rewind
-              crc32c = ::Digest::CRC32c.base64digest local_file.read
+              digest = digest_class.base64digest local_file.read
               local_file.rewind
-              crc32c
+              digest
             end
           end
         end

data/lib/google/cloud/storage/file.rb

@@ -370,6 +370,45 @@ module Google
           update_gapi! :content_type
         end
 
+        ##
+        # User-defined object contexts. Each object context is a key-
+        # payload pair, where the key provides the identification and the payload holds
+        # the associated value and additional metadata.
+        # Object contexts are used to provide additional information about an object
+        # @return [Google::Apis::StorageV1::Object::Contexts, nil] The object contexts, or `nil` if there are none.
+        
+        def contexts
+          @gapi.contexts
+        end
+
+        ##
+        # Sets the object context.
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        # @param [Google::Apis::StorageV1::Object::Contexts] contexts The object contexts to set.
+        # @see https://docs.cloud.google.com/storage/docs/use-object-contexts#attach-modify-contexts Object Contexts documentation
+        # @example
+        #   require "google/cloud/storage"
+        #  storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #   file = bucket.file "path/to/my-file.ext"
+        #   payload = Google::Apis::StorageV1::ObjectCustomContextPayload.new(
+        #     value: "your-custom-context-value"
+        #   )
+        #   custom_hash = {
+        #     "your-custom-context-key" => payload
+        #   }
+        #   contexts = Google::Apis::StorageV1::Object::Contexts.new(
+        #     custom: custom_hash
+        #   )
+        #   file.update do |file|
+        #     file.contexts = contexts
+        #   end
+        def contexts= contexts
+          @gapi.contexts = contexts
+          update_gapi! :contexts
+        end
+
         ##
         # A custom time specified by the user for the file, or `nil`.
         #

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

@@ -372,7 +372,7 @@ module Google
         def list_files bucket_name, delimiter: nil, max: nil, token: nil,
                        prefix: nil, versions: nil, user_project: nil,
                        match_glob: nil, include_folders_as_prefixes: nil,
-                       soft_deleted: nil, options: {}
+                       soft_deleted: nil, filter: nil, options: {}
           execute do
             service.list_objects \
               bucket_name, delimiter: delimiter, max_results: max,
@@ -382,6 +382,7 @@ module Google
                            match_glob: match_glob,
                            include_folders_as_prefixes: include_folders_as_prefixes,
                            soft_deleted: soft_deleted,
+                           filter: filter,
                            options: options
           end
         end

data/lib/google/cloud/storage/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Storage
-      VERSION = "1.59.0".freeze
+      VERSION = "1.60.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-storage
 version: !ruby/object:Gem::Version
-  version: 1.59.0
+  version: 1.60.0
 platform: ruby
 authors:
 - Mike Moore