gapic-common 1.4.1 → 1.5.0

data/lib/gapic/rest/resumable_upload/driver/abridge.rb

@@ -0,0 +1,168 @@
+# 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 "uri"
+
+module Gapic
+  module Rest
+    module ResumableUpload
+      class Driver
+        ##
+        # @private
+        # Pure functions for redacting and abridging sensitive data and large payloads in logs.
+        #
+        module Abridge
+          module_function
+
+          ##
+          # @private
+          # Formats binary payload into truncated hex representation.
+          #
+          # @param data [Object, nil] Binary or string payload
+          # @return [String, nil] Truncated hex representation or nil
+          #
+          def bytes data
+            return nil if data.nil?
+
+            str = data.to_s
+            if str.bytesize >= 64
+              "#{str.byteslice(0, 32).unpack1('H*')}... <#{str.bytesize} bytes>"
+            else
+              str.unpack1 "H*"
+            end
+          end
+
+          ##
+          # @private
+          # Truncates error body to a safe log length.
+          #
+          # @param data [Object, nil] Error body payload
+          # @return [String, nil] UTF-8 scrubbed and truncated string
+          #
+          def error_body data
+            return nil if data.nil?
+
+            data.to_s.dup.force_encoding(Encoding::UTF_8).scrub[0, 512]
+          end
+
+          ##
+          # @private
+          # Redacts query parameter values in URLs for safe logging.
+          #
+          # @param url [Object, nil] URL string or URI
+          # @return [String, nil] URL with query values elided
+          #
+          def url url
+            return nil if url.nil?
+
+            uri = URI.parse url.to_s
+            if uri.query && !uri.query.empty?
+              elided = uri.query.split("&").map do |pair|
+                key, _val = pair.split "=", 2
+                "#{key}=<...>"
+              end.join "&"
+              uri.query = nil
+              return "#{uri}?#{elided}"
+            end
+            uri.to_s
+          rescue URI::InvalidURIError
+            url.to_s
+          end
+
+          ##
+          # @private
+          # Redacts non-protocol headers for safe logging.
+          #
+          # @param headers [Object] Headers hash
+          # @return [Hash<String, String>] Redacted headers
+          #
+          def headers headers
+            return {} unless headers.is_a? Hash
+
+            headers.each_with_object({}) do |(k, v), acc|
+              key_str = k.to_s
+              acc[key_str] = if key_str.downcase == "x-goog-upload-url"
+                               url v
+                             elsif key_str.downcase.start_with? "x-goog-upload-"
+                               v
+                             else
+                               "<...>"
+                             end
+            end
+          end
+
+          ##
+          # @private
+          # Converts a list of instructions into log-safe representation hashes.
+          #
+          # @param instructions [Array<Object>] List of instructions
+          # @return [Array<Hash>] Log-safe instruction summaries
+          #
+          def instructions instructions
+            instructions.map { |i| instruction i }
+          end
+
+          # rubocop:disable Metrics/MethodLength
+          ##
+          # @private
+          # Converts an instruction into a log-safe representation hash.
+          #
+          # @param instruction [Object] Instruction object
+          # @return [Hash] Log-safe instruction summary
+          #
+          def instruction instruction
+            case instruction
+            when Instruction::SendStart
+              { "type" => "SendStart", "url" => url(instruction.url) }
+            when Instruction::SendChunk
+              {
+                "type"     => "SendChunk",
+                "url"      => url(instruction.url),
+                "offset"   => instruction.offset,
+                "length"   => instruction.length,
+                "finalize" => instruction.finalize
+              }
+            when Instruction::SendFinalize
+              { "type" => "SendFinalize", "url" => url(instruction.url) }
+            when Instruction::SendQuery
+              { "type" => "SendQuery", "url" => url(instruction.url), "backoff" => instruction.backoff }
+            when Instruction::SendCancel
+              { "type" => "SendCancel", "url" => url(instruction.url) }
+            when Instruction::RealignBuffer
+              { "type" => "RealignBuffer", "serverOffset" => instruction.server_offset }
+            when Instruction::FillBuffer
+              { "type" => "FillBuffer", "targetBytesize" => instruction.target_bytesize }
+            when Instruction::NotifyProgress
+              {
+                "type"          => "NotifyProgress",
+                "phase"         => instruction.progress.phase.to_s,
+                "bytesUploaded" => instruction.progress.bytes_uploaded,
+                "totalBytes"    => instruction.progress.total_bytes
+              }
+            when Instruction::TerminateSuccess
+              { "type" => "TerminateSuccess" }
+            when Instruction::TerminateFailure
+              { "type" => "TerminateFailure", "error" => instruction.error.to_s }
+            else
+              { "type" => instruction.class.name }
+            end
+          end
+          # rubocop:enable Metrics/MethodLength
+        end
+      end
+    end
+  end
+end

data/lib/gapic/rest/resumable_upload/driver/retry_decider.rb

@@ -0,0 +1,190 @@
+# 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 "faraday"
+require "gapic/rest/error"
+require "gapic/rest/resumable_upload/rules"
+
+module Gapic
+  module Rest
+    module ResumableUpload
+      class Driver
+        ##
+        # @private
+        # Single owner of every retry decision for one resumable upload command.
+        #
+        # `ClientStub` is handed a never-retry policy, so each `ClientStub` call is exactly one attempt and
+        # every outcome comes back to the Driver. The Driver asks this object whether to send the same request
+        # again. It only ever chooses between re-sending and surfacing: an outcome it declines, and whatever
+        # is left when the budget runs out, is converted to an event unchanged and handed to {Rules}, which
+        # alone decides between recovery and a terminal outcome.
+        #
+        # The decision table (first match wins):
+        #
+        # | # | Outcome                                             | start / control        | data                   |
+        # |---|-----------------------------------------------------|------------------------|------------------------|
+        # | 1 | non-transport error (e.g. auth refresh)             | ask policy             | ask policy             |
+        # | 2 | `Faraday::TimeoutError`, or no response and no kind | ask policy             | surface                |
+        # | 3 | `Faraday::ConnectionFailed`, `Faraday::SSLError`    | retry within budget    | surface                |
+        # | 4 | `200` without `X-Goog-Upload-Status`                | retry within budget    | surface                |
+        # | 5 | non-200 with `X-Goog-Upload-Status: final`          | surface                | surface                |
+        # | 6 | any 4xx                                             | (falls through)        | surface                |
+        # | 7 | any other non-200                                   | ask policy             | ask policy             |
+        # | - | any other `2xx`, or `200` with the header           | surface                | surface                |
+        #
+        # * **Retry within budget** is the no-argument `RetryPolicy#call`: it checks the policy deadline and
+        #   applies backoff, and hands nothing to a caller predicate.
+        # * **Ask policy** is `retry_with_deadline? && call(error)`: the caller's `retry_predicate`, then its
+        #   `retry_codes`. `RetryPolicy#call(error)` does not check the deadline itself, hence the guard.
+        # * The data plane never re-sends after an outcome that leaves the server offset unknown (rows 2, 3, 4,
+        #   6); recovery owns those. A non-transport error (row 1) fails before anything reaches the wire, so
+        #   re-sending cannot duplicate bytes.
+        # * Rows 5 and 6 are fixed ahead of the policy, so no caller setting can retry a rejection or make the
+        #   data plane re-send on a 4xx.
+        #
+        # Row 2 is inert for timeouts until attempts get their own timeouts: each attempt currently receives the
+        # whole remaining command budget, so a timed-out attempt leaves none to retry with.
+        #
+        # See `design/resumable_upload/implementation-guide.md` section 6.1.1.
+        #
+        class RetryDecider
+          ##
+          # @private
+          # Classifies a raised request error by what reached the wire.
+          #
+          # Shared with {Driver#rescue_request_error}, so the kind an error is retried as and the kind it is
+          # surfaced as cannot drift apart.
+          #
+          # @param error [StandardError] Error raised by, or through, `ClientStub#make_post_request`
+          # @return [Symbol] `:status` (an HTTP response arrived), `:timeout`, `:connection_failed`,
+          #   `:no_response` (a transport error of no more specific kind), or `:non_transport`
+          def self.failure_kind error
+            case error
+            when Gapic::Rest::DeadlineExceededError then :timeout
+            when Gapic::Rest::Error then error.status_code ? :status : :connection_failed
+            when Faraday::Error then faraday_failure_kind error
+            else :non_transport
+            end
+          end
+
+          ##
+          # @private
+          # @param error [Faraday::Error]
+          # @return [Symbol] See {.failure_kind}
+          def self.faraday_failure_kind error
+            if error.response.is_a?(Hash) && error.response[:status]
+              :status
+            elsif error.is_a? Faraday::TimeoutError
+              :timeout
+            elsif error.is_a?(Faraday::ConnectionFailed) || error.is_a?(Faraday::SSLError)
+              :connection_failed
+            else
+              :no_response
+            end
+          end
+
+          ##
+          # @private
+          # @param policy [Gapic::Common::RetryPolicy] Started policy for this command
+          # @param data_plane [Boolean] Whether the command transmits upload bytes (`upload`, `finalize`)
+          def initialize policy, data_plane:
+            @policy = policy
+            @data_plane = data_plane
+          end
+
+          ##
+          # @private
+          # Decides whether to send the same request again, performing the backoff delay if so.
+          #
+          # @param outcome [Object, StandardError] The response returned by `ClientStub#make_post_request`, or
+          #   the error it raised
+          # @return [Boolean] `true` if the request should be sent again (the delay has been performed)
+          def retry? outcome
+            return retry_response? outcome unless outcome.is_a? Exception
+
+            error = unwrap outcome
+            case self.class.failure_kind error
+            when :status then retry_status? error
+            when :connection_failed then !@data_plane && @policy.call
+            when :timeout, :no_response then !@data_plane && ask_policy(error)
+            else ask_policy error
+            end
+          end
+
+          private
+
+          ##
+          # @private
+          # Under `raise_faraday_errors: false`, `ClientStub` raises a {Gapic::Rest::Error} from inside its own
+          # `rescue`, so `cause` is the original Faraday error. `retry_codes` can read a status only from the
+          # latter.
+          #
+          # @param error [StandardError]
+          # @return [StandardError]
+          def unwrap error
+            return error.cause if error.is_a?(Gapic::Rest::Error) && error.cause.is_a?(Faraday::Error)
+            error
+          end
+
+          ##
+          # @private
+          # Faraday raises on every `4xx`/`5xx`, so a returned response is a `1xx`-`3xx`. Only a headerless
+          # `200` is worth re-sending.
+          #
+          # @param response [Object] Response exposing `status` and `headers`
+          # @return [Boolean]
+          def retry_response? response
+            return false unless response.status == 200
+            return false unless upload_status(response.headers).nil?
+            !@data_plane && @policy.call
+          end
+
+          ##
+          # @private
+          # @param error [Faraday::Error, Gapic::Rest::Error] Error carrying an HTTP status
+          # @return [Boolean]
+          def retry_status? error
+            status, headers = if error.is_a? Gapic::Rest::Error
+                                [error.status_code, error.headers]
+                              else
+                                [error.response[:status], error.response[:headers]]
+                              end
+            return false if upload_status(headers) == "final"
+            return false if @data_plane && (400..499).cover?(status)
+            ask_policy error
+          end
+
+          ##
+          # @private
+          # @param error [StandardError]
+          # @return [Boolean]
+          def ask_policy error
+            @policy.retry_with_deadline? && @policy.call(error)
+          end
+
+          ##
+          # @private
+          # @param headers [Hash, nil]
+          # @return [String, nil] Downcased `X-Goog-Upload-Status`, or `nil` when missing or empty
+          def upload_status headers
+            value = Rules.header_value headers, "x-goog-upload-status"
+            value.nil? || value.empty? ? nil : value.downcase
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gapic/rest/resumable_upload/driver/upload_log.rb

@@ -0,0 +1,343 @@
+# 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 "google/logging/message"
+require "gapic/rest/resumable_upload/driver/abridge"
+
+module Gapic
+  module Rest
+    module ResumableUpload
+      class Driver
+        ##
+        # @private
+        # Structured logging helper for a single Resumable Upload run.
+        #
+        class UploadLog
+          ##
+          # @private
+          # Recipes omitted from INFO lifecycle logging.
+          # @return [Array<Symbol>]
+          SILENT_RECIPES = [
+            :ack_chunk,                     # per-chunk transition, doesn't belong at INFO
+            :fail_with_unmatched_transition # raises before Decision exists, logged by #unmatched_transition
+          ].freeze
+
+          ##
+          # @private
+          # Severity and message mapping for lifecycle transitions.
+          # @return [Hash<Symbol, Array>]
+          LIFECYCLE = {
+            start_session:               [:info, "Initiating resumable upload"],
+            resume_session:              [:info, "Resuming upload session"],
+            begin_transmission:          [:info, "Upload session established"],
+            send_chunk:                  [:debug, "Sending upload chunk"],
+            send_upload_finalize:        [:info, "Sending final upload chunk"],
+            send_finalize:               [:info, "Sending finalize command"],
+            enter_recovery:              [:info, "Entering upload recovery"],
+            retry_recovery:              [:info, "Retrying upload recovery query"],
+            realign_from_recovery:       [:info, "Resuming upload from server offset"],
+            complete_upload_with_data:   [:info, "Resumable upload completed"],
+            complete_upload_finalized:   [:info, "Resumable upload completed"],
+            cancel_session:              [:info, "Canceling resumable upload"],
+            complete_cancellation:       [:info, "Resumable upload canceled"],
+            fail_with_cancelled:         [:warn, "Resumable upload canceled on the server"],
+            fail_with_deadline_exceeded: [:warn, "Resumable upload failed"],
+            fail_with_rejected:          [:warn, "Resumable upload failed"],
+            fail_with_bad_response:      [:warn, "Resumable upload failed"],
+            fail_with_request_error:     [:warn, "Resumable upload failed"]
+          }.freeze
+
+          # @private
+          # @return [String]
+          attr_reader :upload_id
+
+          ##
+          # @private
+          # Initializes a new UploadLog logger wrapper.
+          #
+          # @param stub_logger [Logger, Object] Underlying structured logger
+          # @param upload_id [String] Unique session identifier
+          #
+          def initialize stub_logger, upload_id:
+            @stub_logger = stub_logger
+            @upload_id = upload_id
+          end
+
+          ##
+          # @private
+          # Logs state machine transition decision at DEBUG level.
+          #
+          # @param decision [Decision] Decision snapshot
+          #
+          def decision decision
+            msg = "Rules: #{decision.from_status} + #{decision.shape} -> " \
+                  "#{decision.recipe} -> #{decision.next_state.status}"
+            entry(
+              :debug,
+              msg,
+              fromStatus:     decision.from_status,
+              shape:          decision.shape,
+              recipe:         decision.recipe,
+              toStatus:       decision.next_state.status,
+              offset:         decision.next_state.offset,
+              inFlightLength: decision.next_state.in_flight_length,
+              recoveryOffset: decision.next_state.recovery_offset,
+              instructions:   Abridge.instructions(decision.instructions)
+            )
+          end
+
+          ##
+          # @private
+          # Logs high-level protocol lifecycle milestone if configured.
+          #
+          # @param decision [Decision] Decision snapshot
+          # @param config [StartUploadConfig, ResumeUploadConfig] Upload configuration
+          #
+          def lifecycle decision, config
+            return if SILENT_RECIPES.include? decision.recipe
+
+            severity, message = LIFECYCLE[decision.recipe]
+            return unless severity
+
+            extra_fields = lifecycle_fields decision, config
+            entry severity, message, recipe: decision.recipe, **extra_fields
+          end
+
+          ##
+          # @private
+          # Logs an outgoing HTTP request at DEBUG level.
+          #
+          # @param method [String] HTTP method
+          # @param url [String] Request URL
+          # @param headers [Hash] Request headers
+          # @param start_attempt [Integer] Attempt index for start command
+          # @param body_size [Integer, nil] Byte size of request payload
+          # @param body [Object, nil] Request payload
+          # @param body_is_error [Boolean] Whether body contains an error payload
+          #
+          def wire_send method:, url:, headers:, start_attempt:, body_size: nil, body: nil, body_is_error: false
+            command = Rules.header_value headers, "x-goog-upload-command"
+            offset = Rules.header_value headers, "x-goog-upload-offset"
+            fields = {
+              method:       method,
+              url:          Abridge.url(url),
+              headers:      Abridge.headers(headers),
+              startAttempt: start_attempt
+            }
+            fields[:command] = command if command
+            fields[:offset] = offset.to_i if offset
+            fields[:bodySize] = body_size if body_size
+            fields[:body] = body_is_error ? Abridge.error_body(body) : Abridge.bytes(body) if body
+
+            entry :debug, "Sending #{method} request", **fields
+          end
+
+          ##
+          # @private
+          # Logs a received HTTP response at DEBUG level.
+          #
+          # @param event [Event::HttpResponse] Received HTTP event
+          #
+          def wire_receive event
+            upload_status = Rules.header_value event.headers, "x-goog-upload-status"
+            size_recv = Rules.parse_header_non_negative_integer(
+              Rules.header_value(event.headers, "x-goog-upload-size-received")
+            )
+            gran = Rules.parse_header_non_negative_integer(
+              Rules.header_value(event.headers, "x-goog-upload-chunk-granularity")
+            )
+            err = event.error if event.respond_to? :error
+            fields = {
+              status:  event.status,
+              headers: Abridge.headers(event.headers),
+              body:    wire_receive_body(event, err)
+            }
+            fields[:uploadStatus] = upload_status if upload_status
+            fields[:errorStatus] = err.status if err&.status
+            fields[:sizeReceived] = size_recv if size_recv
+            fields[:granularity] = gran if gran
+
+            entry :debug, "Received HTTP #{event.status}", **fields
+          end
+
+          ##
+          # @private
+          # Logs a network or transport failure at DEBUG level.
+          #
+          # @param event [Event::RequestFailed] Failure event
+          #
+          def wire_failure event
+            entry(
+              :debug,
+              "Request failed: #{event.kind}",
+              kind:  event.kind,
+              error: event.message
+            )
+          end
+
+          ##
+          # @private
+          # Logs the backoff delay about to be performed before a query that continues a recovery episode.
+          #
+          # @param delay [Numeric] Base delay in seconds, before jitter and the `max_delay` cap
+          # @param attempt [Integer] 1-based index of the delay within the recovery episode
+          #
+          def recovery_backoff delay:, attempt:
+            entry :debug, "Performing backoff delay before recovery query", delay: delay, backoffAttempt: attempt
+          end
+
+          ##
+          # @private
+          # Logs buffer realignment action.
+          #
+          # @param action [String] Realignment action description
+          # @param server_offset [Integer] Target server offset
+          # @param current_offset [Integer] Current buffer start offset
+          # @param unseekable [Boolean] Whether rewind was attempted on an unseekable stream
+          #
+          def buffer_realign action, server_offset:, current_offset:, unseekable: false
+            if unseekable
+              entry(
+                :warn,
+                "Server offset rewind on unseekable stream",
+                action:        action,
+                serverOffset:  server_offset,
+                currentOffset: current_offset
+              )
+            end
+
+            entry(
+              :debug,
+              "Buffer realignment: #{action}",
+              action:        action,
+              serverOffset:  server_offset,
+              currentOffset: current_offset
+            )
+          end
+
+          ##
+          # @private
+          # Logs an invalid or unmatched state machine transition at WARN level.
+          #
+          # @param state [State] Current state
+          # @param event [Object] Triggering event
+          # @param error [StandardError] Resulting error
+          #
+          def unmatched_transition state, event, error
+            entry(
+              :warn,
+              "Unmatched transition",
+              status: state.status,
+              shape:  Rules.shape_of(event, state.status),
+              error:  error.message
+            )
+          end
+
+          private
+
+          ##
+          # @private
+          # Formats response body for wire log entry.
+          #
+          # @param event [Event::HttpResponse] Response event
+          # @param err [Gapic::Rest::Error, nil] Error instance
+          # @return [String, nil] Formatted body
+          #
+          def wire_receive_body event, err
+            return Abridge.bytes event.body if event.status < 400
+
+            err&.message ? Abridge.error_body(err.message) : Abridge.error_body(event.body)
+          end
+
+          ##
+          # @private
+          # Extracts relevant state fields for lifecycle logging.
+          #
+          # @param decision [Decision] Decision snapshot
+          # @param config [StartUploadConfig, ResumeUploadConfig] Upload configuration
+          # @return [Hash] Metadata fields for log entry
+          #
+          def lifecycle_fields decision, config
+            state = decision.next_state
+            case decision.recipe
+            when :start_session
+              { uploadSize: config.upload_size, requestedChunkSize: config.chunk_size }
+            when :resume_session
+              {
+                uploadUrl: Abridge.url(state.upload_url),
+                chunkSize: state.chunk_size
+              }
+            when :begin_transmission
+              {
+                effectiveChunkSize: state.chunk_size,
+                granularity:        state.chunk_granularity,
+                uploadUrl:          Abridge.url(state.upload_url)
+              }
+            when :send_chunk, :send_upload_finalize
+              { offset: state.offset, inFlightLength: state.in_flight_length }
+            when :send_finalize, :enter_recovery, :retry_recovery,
+                 :realign_from_recovery, :complete_upload_with_data, :complete_upload_finalized
+              { offset: state.offset }
+            when :cancel_session
+              { uploadUrl: Abridge.url(state.upload_url) }
+            when :fail_with_deadline_exceeded, :fail_with_rejected, :fail_with_bad_response,
+                 :fail_with_request_error
+              failure_fields state
+            else
+              {}
+            end
+          end
+
+          ##
+          # @private
+          # Extracts error and response details for failure lifecycle logs.
+          #
+          # @param state [State] Current protocol state
+          # @return [Hash] Failure metadata fields
+          #
+          def failure_fields state
+            err = state.last_error
+            fields = { error: err&.message || err.to_s }
+            if err.respond_to?(:response_body) && err.response_body
+              fields[:responseBody] = Abridge.error_body err.response_body
+            end
+            fields
+          end
+
+          ##
+          # @private
+          # Dispatches structured log entry to stub logger.
+          #
+          # @param severity [Symbol] Log severity level
+          # @param log_msg [String] Primary log message
+          # @param fields [Hash] Structured key-value fields
+          #
+          def entry severity, log_msg, **fields
+            @stub_logger.public_send severity do |builder|
+              builder.set_system_name
+              builder.set_service
+              builder.set "uploadId", @upload_id
+              fields.each do |k, v|
+                builder.set k.to_s, v
+              end
+              builder.message = log_msg
+            end
+          end
+        end
+      end
+    end
+  end
+end