gapic-common 1.3.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4338a183319704aa9fb613e73d34b4092a94ad56f3136c2d4a0490a3218770f
-  data.tar.gz: 3a0d1456f8c2bc573245e5c46afae6b2c83be393085bf6bebc5b28c06368d3f7
+  metadata.gz: b913235ab6a4508add68839ed5249a5593fe35543c12d7c5a0fd10da958d52d4
+  data.tar.gz: 25da91337dde92ebab37ce20f20d6795c3eb15f70480e488fb5a76e0c3e771ab
 SHA512:
-  metadata.gz: 696026e2b9ca26c060c2b65a336f790ec193938a7740d8bdce3008c6bfae40cd80290077b717174554d7e6a1530e470f2523a5859b210c2bf9bd583e7dd72041
-  data.tar.gz: 42979948486f1e55f990bdbcc0ee2a697ffbf3c450b4013a7ae293e0960291533bfc4356fcfb8cfdeca5eae94d97a7ff522e2b5667cd1e9611de93cf39af560e
+  metadata.gz: '093cefa2ecd695bc76f1a9bc0b90934f946e8953576b110abb834e60efa6b849e684e39d86d0c02ca560fb52b221261e348c5bf4ff7caf1c2b45256c7ea3ff21'
+  data.tar.gz: 12e1f11af015c7ee7df9dc3049123b998e3a3aa0d6fb7cf39cb5804620a9bd1883870b05526d8d1418d7162c2f883b1fdafa2f1731ef8ea216a53d8e884f3979

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Release History
 
+### 1.6.1 (2026-10-29)
+
+#### Documentation
+
+* link to the published Ruby version support policy ([#91](https://github.com/googleapis/ruby-core-libraries/issues/91)) 
+
+### 1.6.0 (2026-10-22)
+
+#### Features
+
+* require grpc >= 1.84.1 ([#90](https://github.com/googleapis/ruby-core-libraries/issues/90)) 
+#### Bug Fixes
+
+* ignore inherited Service constants in normalize_service ([#71](https://github.com/googleapis/ruby-core-libraries/issues/71)) ([47c7e98](https://github.com/googleapis/ruby-core-libraries/commit/47c7e9854904caa59955aab31a6fdacd0af200b8)), refs [#70](https://github.com/googleapis/ruby-core-libraries/issues/70)
+
+### 1.5.1 (2026-09-30)
+
+#### Bug Fixes
+
+* tighten path template matching in the REST transcoder ([#83](https://github.com/googleapis/ruby-core-libraries/issues/83)) 
+
+### 1.5.0 (2026-09-29)
+
+#### Features
+
+* Resumable Media Upload functionality implementation ([#72](https://github.com/googleapis/ruby-core-libraries/issues/72)) 
+#### Documentation
+
+* remove stale preview notice and disclaimer from READMEs ([#77](https://github.com/googleapis/ruby-core-libraries/issues/77)) 
+
+### 1.4.1 (2026-09-28)
+
+#### Bug Fixes
+
+* validate path parameters and prevent traversal/injection in REST transcoder ([#67](https://github.com/googleapis/ruby-core-libraries/issues/67)) 
+
+### 1.4.0 (2026-09-23)
+
+#### Features
+
+* add custom predicate matching to RetryPolicy ([#59](https://github.com/googleapis/ruby-core-libraries/issues/59)) 
+#### Bug Fixes
+
+* require grpc >= 1.83 for post-quantum key exchange ([#73](https://github.com/googleapis/ruby-core-libraries/issues/73)) 
+* only use emit_default for proto messages ([#75](https://github.com/googleapis/ruby-core-libraries/issues/75)) 
+
 ### 1.3.0 (2026-03-05)
 
 #### Features

data/README.md

@@ -15,14 +15,41 @@ convenient and idiomatic API surface to callers.
 
 ## Supported Ruby Versions
 
-This library is supported on Ruby 3.0+.
+This library is supported on Ruby 3.2+.
 
-Google provides official support for Ruby versions that are actively supported
-by Ruby Core—that is, Ruby versions that are either in normal maintenance or in
-security maintenance, and not end of life. Older versions of Ruby _may_ still
-work, but are unsupported and not recommended. See
-https://www.ruby-lang.org/en/downloads/branches/ for details about the Ruby
-support schedule.
+Google provides official support for Ruby versions as described in the
+[Supported Ruby versions](https://docs.cloud.google.com/ruby/getting-started/supported-ruby-versions)
+policy. Older versions of Ruby _may_ still work, but are unsupported and not
+recommended.
+
+## Post-Quantum Key Exchange
+
+Clients built on this library negotiate the hybrid post-quantum key exchange
+group `X25519MLKEM768` — classical X25519 paired with ML-KEM-768 ([NIST FIPS
+203][]) — over TLS 1.3. No application code changes are required, because the
+handshake belongs to the transport layer. The two transports source that
+support differently:
+
+| Transport | Cryptographic provider | Requirement | Enforced by this gem? |
+| --- | --- | --- | --- |
+| gRPC | BoringSSL, vendored inside the `grpc` gem | `grpc >= 1.83` | Yes |
+| REST | Host system OpenSSL, via `Net::HTTP` and Faraday | OpenSSL `>= 3.5` | No |
+
+gRPC clients get post-quantum key exchange automatically: `gapic-common`
+depends on `grpc >= 1.83`, the first release to offer `X25519MLKEM768` in the
+TLS ClientHello by default.
+
+The REST requirement cannot be expressed as a gem dependency. Ruby's `openssl`
+is a default gem bound to whatever `libssl` the host provides, and ML-KEM first
+ships in OpenSSL 3.5. On an older host, REST connections negotiate classical
+X25519 instead — a safe fallback rather than an error, but not post-quantum. To
+check the OpenSSL your Ruby is linked against:
+
+```sh
+ruby -ropenssl -e 'puts OpenSSL::OPENSSL_LIBRARY_VERSION'
+```
+
+[NIST FIPS 203]: https://csrc.nist.gov/pubs/fips/203/final
 
 ## Contributing
 
@@ -32,9 +59,6 @@ See the {file:CONTRIBUTING.md CONTRIBUTING} documentation for more information o
 
 ## Versioning
 
-This library is currently a **preview** with no guarantees of stability or support. Please get
-involved and let us know if you find it useful and we'll work towards a stable version.
-
-## Disclaimer
+This library follows [Semantic Versioning](http://semver.org/).
 
-This is not an official Google product.
+This library is considered to be stable and will not have backwards-incompatible changes introduced in subsequent minor releases.

data/lib/gapic/common/retry_policy.rb

@@ -19,6 +19,12 @@ module Gapic
     ##
     # Gapic Common retry policy base class.
     #
+    # A policy distinguishes "set to this value" from "never set". Every setting is stored as `nil`
+    # until someone supplies it, and the reader for each substitutes the corresponding `DEFAULT_`
+    # constant on the way out, so a reader can never say which of the two happened. That distinction is
+    # what lets {#apply_defaults} fill in gaps without overwriting a caller's choices, and {#overrides}
+    # report what a caller actually asked for.
+    #
     class RetryPolicy
       # @return [Numeric] Default initial delay in seconds.
       DEFAULT_INITIAL_DELAY = 1
@@ -45,9 +51,17 @@ module Gapic
       # @param retry_codes [Array<String|Integer>] List of retry codes.
       # @param timeout [Numeric] Timeout threshold value in seconds.
       # @param jitter [Numeric] Random jitter added to the delay in seconds.
+      # @param retry_predicate [Proc, nil] The predicate to evaluate whether to retry on a given error. Optional.
+      #   If the predicate is specified, it is run first. If it returns nil, the decision on
+      #   whether to retry is made on the basis of retry_codes. Otherwise, the truthiness of
+      #   the return value determines whether to retry.
       #
-      def initialize initial_delay: nil, max_delay: nil, multiplier: nil, retry_codes: nil, timeout: nil, jitter: nil
+      def initialize initial_delay: nil, max_delay: nil, multiplier: nil, retry_codes: nil, timeout: nil,
+                     jitter: nil, retry_predicate: nil
         raise ArgumentError, "jitter cannot be negative" if jitter&.negative?
+        if retry_predicate && !retry_predicate.respond_to?(:call)
+          raise ArgumentError, "retry_predicate must respond to :call"
+        end
 
         # Instance values are set as `nil` to determine whether values are overriden from default.
         @initial_delay = initial_delay
@@ -56,6 +70,7 @@ module Gapic
         @retry_codes = convert_codes retry_codes
         @timeout = timeout
         @jitter = jitter
+        @retry_predicate = retry_predicate
         start!
       end
 
@@ -89,6 +104,47 @@ module Gapic
         @jitter || DEFAULT_JITTER
       end
 
+      ##
+      # The predicate to evaluate whether to retry on a given error. Optional.
+      #
+      # When a predicate is specified:
+      # 1. The predicate is executed first on the error.
+      # 2. If it returns nil, the decision on whether to retry is made on the basis of retry_codes.
+      # 3. Otherwise, the truthiness of the return value determines whether to retry.
+      #
+      # @return [Proc, nil]
+      def retry_predicate
+        @retry_predicate
+      end
+
+      ##
+      # @private
+      # The settings this policy actually carries, as keyword arguments for {RetryPolicy.initialize}.
+      #
+      # A key is present only if that setting was explicitly supplied; a key that was never set is
+      # absent rather than `nil`. This is what the readers cannot tell you — {#max_delay} returns
+      # {DEFAULT_MAX_DELAY} whether the caller chose that number or said nothing — so it is the only
+      # safe way to carry one policy's settings onto another without dragging defaults along, and
+      # without mistaking a deliberate choice that happens to equal a default for silence.
+      #
+      # An empty `retry_codes` list counts as unset. It retries nothing, which is exactly what an
+      # unset list does, so there is nothing for it to carry.
+      #
+      # @return [Hash{Symbol=>Object}] Explicitly set settings only
+      def overrides
+        # Assigns nil, and so omits the key, when the list is absent or empty.
+        retry_codes = @retry_codes unless @retry_codes.nil? || @retry_codes.empty?
+        {
+          initial_delay:   @initial_delay,
+          max_delay:       @max_delay,
+          multiplier:      @multiplier,
+          retry_codes:     retry_codes,
+          timeout:         @timeout,
+          jitter:          @jitter,
+          retry_predicate: @retry_predicate
+        }.compact
+      end
+
       ##
       # Returns a duplicate in a non-executing state, i.e. with the deadline
       # and current delay reset.
@@ -101,7 +157,8 @@ module Gapic
                         multiplier: @multiplier,
                         retry_codes: @retry_codes,
                         timeout: @timeout,
-                        jitter: @jitter
+                        jitter: @jitter,
+                        retry_predicate: @retry_predicate
       end
 
       ##
@@ -176,6 +233,13 @@ module Gapic
       # @return [Boolean] Whether this error should be retried.
       #
       def retry_error? error
+        # Run predicate first. If it returns nil, decision is made on the basis of retry_codes.
+        # Otherwise return truthiness.
+        if @retry_predicate.respond_to? :call
+          result = @retry_predicate.call error
+          return !!result unless result.nil?
+        end
+
         (defined?(::GRPC) && error.is_a?(::GRPC::BadStatus) && retry_codes.include?(error.code)) ||
           (error.respond_to?(:response_status) &&
             retry_codes.include?(ErrorCodes.grpc_error_for(error.response_status)))
@@ -197,11 +261,12 @@ module Gapic
       #
       def apply_defaults retry_policy
         return unless retry_policy.is_a? Hash
-        @retry_codes   ||= convert_codes retry_policy[:retry_codes]
-        @initial_delay ||= retry_policy[:initial_delay]
-        @multiplier    ||= retry_policy[:multiplier]
-        @max_delay     ||= retry_policy[:max_delay]
-        @jitter        ||= retry_policy[:jitter]
+        @retry_codes     ||= convert_codes retry_policy[:retry_codes]
+        @initial_delay   ||= retry_policy[:initial_delay]
+        @multiplier      ||= retry_policy[:multiplier]
+        @max_delay       ||= retry_policy[:max_delay]
+        @jitter          ||= retry_policy[:jitter]
+        @retry_predicate ||= retry_policy[:retry_predicate]
 
         self
       end
@@ -214,13 +279,14 @@ module Gapic
           other.multiplier == multiplier &&
           other.retry_codes == retry_codes &&
           other.timeout == timeout &&
-          other.jitter == jitter
+          other.jitter == jitter &&
+          other.retry_predicate == retry_predicate
       end
       alias == eql?
 
       # @private Hash code
       def hash
-        [initial_delay, max_delay, multiplier, retry_codes, timeout, jitter].hash
+        [initial_delay, max_delay, multiplier, retry_codes, timeout, jitter, retry_predicate].hash
       end
 
       private

data/lib/gapic/common/version.rb

@@ -14,6 +14,6 @@
 
 module Gapic
   module Common
-    VERSION = "1.3.0".freeze
+    VERSION = "1.6.1".freeze
   end
 end

data/lib/gapic/logging_concerns.rb

@@ -67,6 +67,10 @@ module Gapic
         log(Logger::DEBUG, &)
       end
 
+      def warn(&)
+        log(Logger::WARN, &)
+      end
+
       ##
       # @private
       # Builder for a log entry, passed to {StubLogger#log}.
@@ -200,12 +204,14 @@ module Gapic
           input
         when Class
           mod = input.name.split("::")[..-2].inject(Object) { |m, n| m.const_get n }
-          if mod.const_defined? "Service"
-            mod.const_get("Service").service_name
+          # inherit: false so a top-level ::Service is not mistaken for the
+          # generated gRPC Service sibling that REST stubs do not define.
+          if mod.const_defined? "Service", false
+            mod.const_get("Service", false).service_name
           else
             name_segments = input.name.split("::")[..-3]
             mod = name_segments.inject(Object) { |m, n| m.const_get n }
-            name_segments.join "." if mod.const_defined? "Rest"
+            name_segments.join "." if mod.const_defined? "Rest", false
           end
         end
       end

data/lib/gapic/rest/client_stub.rb

@@ -287,17 +287,27 @@ module Gapic
           entry.set "requestId", request_id
           entry.message = "Sending request to #{entry.service}.#{method_name} (try #{try_number})"
         end
-        body = body.to_s
+        body_str = body.to_s
         metadata = metadata.to_h rescue {}
-        return if body.empty? && metadata.empty?
+        return if body_str.empty? && metadata.empty?
         stub_logger.debug do |entry|
           entry.set "requestId", request_id
-          entry.set "request", body
+          entry.set "request", abridge_request_body(body_str)
           entry.set "headers", metadata
           entry.message = "(request payload as JSON)"
         end
       end
 
+      def abridge_request_body body_str
+        utf8_body = body_str.dup.force_encoding Encoding::UTF_8
+        if body_str.bytesize > 1024 || !utf8_body.valid_encoding?
+          prefix_hex = body_str.byteslice(0, 32).unpack1 "H*"
+          "<#{body_str.bytesize} bytes, first 32: #{prefix_hex}>"
+        else
+          utf8_body
+        end
+      end
+
       def log_response method_name, request_id, try_number, response, is_server_streaming
         return unless stub_logger&.enabled?
         stub_logger.info do |entry|

data/lib/gapic/rest/error.rb

@@ -22,6 +22,9 @@ module Gapic
   module Rest
     # Gapic REST exception class
     class Error < ::Gapic::Common::Error
+      # @private
+      REST_ERROR_PREFIX = "An error has occurred when making a REST request".freeze
+
       # @return [Integer, nil] the http status code for the error
       attr_reader :status_code
       # @return [Object, nil] the text representation of status as parsed from the response body
@@ -79,7 +82,7 @@ module Gapic
 
           if err.response_body
             msg, code, status, details = try_parse_from_body err.response_body
-            message = "An error has occurred when making a REST request: #{msg}" unless msg.nil?
+            message = "#{REST_ERROR_PREFIX}: #{msg}" unless msg.nil?
             status_code = code unless code.nil?
           end
 

data/lib/gapic/rest/grpc_transcoder.rb

@@ -111,12 +111,14 @@ module Gapic
       # @return [Hash{String, String}]
       #   Name to value hash of the variables for the uri template expansion.
       #   The values are percent-escaped with slashes potentially preserved.
+      # @raise [Gapic::Common::Error] If any parameter value fails path traversal validation.
       def bind_uri_values! http_binding, request_hash
         http_binding.field_bindings.to_h do |field_binding|
           field_path_camel = field_binding.field_path.split(".").map { |part| camel_name_for part }.join(".")
           field_value = extract_scalar_value! request_hash, field_path_camel, field_binding.regex
 
           if field_value
+            validate_field_binding! field_binding, field_value
             field_value = field_value.split("/").map { |segment| percent_escape segment }.join("/")
           end
 
@@ -124,6 +126,43 @@ module Gapic
         end
       end
 
+      # Validates a user-supplied parameter value bound to a standard (*) or path (**) URI template variable
+      # to prevent directory traversal exploits.
+      #
+      # @param field_binding [HttpBinding::FieldBinding] The field binding template metadata.
+      # @param field_value [String] The parameter value to validate.
+      # @raise [Gapic::Common::Error] If validation fails.
+      def validate_field_binding! field_binding, field_value
+        validate_path_binding! field_binding, field_value
+      end
+
+      # Validates standard (*) and path (**) parameters by ensuring that no segment in the parameter
+      # value is a directory traversal segment (. or ..).
+      #
+      # Validation Mechanism:
+      # 1. Splits the parameter value by slash (`/`) using `-1` limit to preserve all segments.
+      # 2. Checks each segment. If any segment matches `.` or `..`, it immediately raises
+      #    a `Gapic::Common::Error`, aborting the request.
+      # 3. Empty segments (e.g. duplicate slashes `//` or trailing slashes `/`) are allowed
+      #    by this validator and passed to the server, which handles normalization or returns 400.
+      #
+      # @param field_binding [HttpBinding::FieldBinding] The field binding template metadata.
+      # @param field_value [String] The parameter value to validate.
+      # @raise [Gapic::Common::Error] If validation fails.
+      def validate_path_binding! field_binding, field_value
+        segments = field_value.split("/", -1)
+        segments.each do |segment|
+          next unless [".", ".."].include? segment
+          if field_binding.preserve_slashes
+            raise ::Gapic::Common::Error,
+                  "Value for #{field_binding.field_path} must not contain segments that are exactly '#{segment}'."
+          else
+            raise ::Gapic::Common::Error,
+                  "Invalid value for #{field_binding.field_path} '#{segment}'."
+          end
+        end
+      end
+
       # Percent-escapes a string.
       # @param str [String] String to escape.
       # @return [String] Escaped string.
@@ -160,7 +199,16 @@ module Gapic
           request_body_field = request.send body_template.to_sym if request.respond_to? body_template.to_sym
           if request_body_field
             request_hash_without_uri.delete camel_name_for body_template
-            body = request_body_field.to_json emit_defaults: true
+            # `emit_defaults` is only meaningful for, and only accepted by,
+            # `Google::Protobuf::MessageExts#to_json`. When the body template points at a
+            # scalar, enum or repeated field, `to_json` resolves to the json gem's
+            # `Object#to_json`, which has never accepted the keyword: json 2.x silently
+            # discarded unknown keywords, json 3.x raises ArgumentError.
+            body = if request_body_field.is_a? ::Google::Protobuf::MessageExts
+                     request_body_field.to_json emit_defaults: true
+                   else
+                     request_body_field.to_json
+                   end
           end
 
           query_params = build_query_params request_hash_without_uri
@@ -204,7 +252,7 @@ module Gapic
       # Returns nil if:
       # - the field is not found
       # - the field is a Message or an array,
-      # - the regex does not match
+      # - the regex does not match the entire string representation
       # @param request_hash [Hash]
       #   A hash of the GRPC request or the sub-request with the unset
       #   proto3_optional fields removed.
@@ -218,7 +266,9 @@ module Gapic
 
         # Covers the case where in `foo.bar.baz`, `baz` is still a submessage or an array.
         return nil if value.is_a?(::Hash) || value.is_a?(::Array)
-        value.to_s if value.to_s =~ regex
+        str = value.to_s
+        match = regex.match str
+        str if match && match.pre_match.empty? && match.post_match.empty?
       end
 
       # Finds a value in the hash by path.

data/lib/gapic/rest/resumable_upload/core.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Copyright 2026 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.
+
+require "gapic/rest/resumable_upload/data_types"
+require "gapic/rest/resumable_upload/rules"
+
+module Gapic
+  module Rest
+    module ResumableUpload
+      ##
+      # @private
+      # State machine container holding the immutable State snapshot.
+      # Contains zero protocol branching logic and zero side-effects.
+      #
+      # The middle tier of the three-tier design: `Driver` executes side effects, {Rules} decides transitions,
+      # and Core holds the {State} between the two. See {Rules} for the protocol narrative and state graph, and
+      # `design/resumable_upload/implementation-guide.md` section 1 for the tier boundaries.
+      #
+      class Core
+        # @private
+        # @return [State] Current immutable state snapshot
+        attr_reader :state
+
+        # @private
+        # @return [Decision, nil] Decision emitted during the last dispatch
+        attr_reader :last_decision
+
+        ##
+        # @private
+        # Initializes a Core state machine container.
+        #
+        # @param config [StartUploadConfig, ResumeUploadConfig] Upload session configuration
+        #
+        def initialize config
+          @config = config
+          @last_decision = nil
+          @state = State.new(
+            status:            :initializing,
+            upload_url:        nil,
+            offset:            0,
+            chunk_size:        config.chunk_size || Rules::DEFAULT_CHUNK_SIZE,
+            chunk_granularity: nil,
+            in_flight_length:  0,
+            last_error:        nil
+          )
+        end
+
+        ##
+        # @private
+        # Dispatches event to Rules and updates internal state snapshot.
+        #
+        # @param event [Object] Input event
+        # @return [Array<Object>] Driver instructions
+        #
+        def dispatch event
+          decision = Rules.decide @state, event, @config
+          @state = decision.next_state
+          @last_decision = decision
+          decision.instructions
+        end
+      end
+    end
+  end
+end