gapic-common 1.4.0 → 1.5.0

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

@@ -0,0 +1,1210 @@
+# 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/common/error"
+require "gapic/rest/resumable_upload/errors"
+require "gapic/rest/resumable_upload/data_types"
+require "gapic/rest/resumable_upload/events"
+require "gapic/rest/resumable_upload/instructions"
+
+module Gapic
+  module Rest
+    module ResumableUpload
+      ##
+      # @private
+      # Pure functional transition engine for the Resumable Upload Protocol.
+      # Contains zero side-effects and zero persistent state.
+      #
+      # ### Model
+      #
+      # {Rules.decide} is the protocol. It is a total function of `[state.status, shape_of(event, state.status)]`
+      # returning a {Decision} that carries the next {State} and the instructions for the Driver to execute. Three
+      # vocabularies define it, each published as a frozen constant:
+      #
+      # * {STATUSES} - protocol lifecycle statuses a {State} may hold.
+      # * {SHAPES} - canonical event shapes that {Rules.shape_of} reduces raw events to.
+      # * {RECIPES} - transition handlers that {Rules.decide} may select.
+      #
+      # Every router arm maps one (status, shape) pair to exactly one recipe, and every recipe returns
+      # `[next_state, instructions]`. Adding a protocol behaviour means adding a shape, a recipe and an arm.
+      # It never means adding branching to the Driver.
+      #
+      # ### Trampoline invariant
+      #
+      # {Driver#run} executes as a synchronous trampoline loop, so every recipe in {RECIPES} must return an
+      # instruction batch that yields either:
+      #
+      # 1. **Exactly one** event-producing instruction (`FillBuffer` or `Send*`) and zero terminal instructions, or
+      # 2. **Exactly one** terminal instruction (`TerminateSuccess` or `TerminateFailure`) and zero event-producing
+      #    instructions.
+      #
+      # A recipe returning zero event-producing instructions without terminating stalls the loop, and a recipe
+      # returning multiple event-producing instructions discards continuation events. The Driver validates each
+      # batch against {Instruction::CONTINUATION}, {Instruction::TERMINAL} and {Instruction::SIDE_EFFECT} before
+      # executing any instruction, rejecting malformed batches up front. Side-effect instructions
+      # ({Instruction::NotifyProgress}, {Instruction::RealignBuffer}) explicitly return `nil` in the Driver by
+      # construction, so only {Instruction::FillBuffer} and `Send*` instructions produce continuation events.
+      #
+      # ### State transition graph
+      #
+      # ```mermaid
+      # stateDiagram-v2
+      #     [*] --> initializing
+      #     initializing --> starting : start_upload
+      #     initializing --> recovery : resume_upload
+      #     starting --> transmission_reading : response_active
+      #     transmission_reading --> transmission_sending : chunk_read_full
+      #     transmission_sending --> transmission_reading : response_active
+      #     transmission_reading --> finalizing_sending_upload : chunk_read_eof_with_data
+      #     transmission_reading --> finalizing_sending_finalize : chunk_read_eof_empty
+      #     finalizing_sending_upload --> success : response_final
+      #     finalizing_sending_finalize --> success : response_final
+      #     transmission_sending --> recovery : response_cat2 / connection_failed / timeout
+      #     finalizing_sending_upload --> recovery : response_cat2 / connection_failed / timeout
+      #     finalizing_sending_finalize --> recovery : response_cat2 / connection_failed / timeout
+      #     recovery --> recovery : response_cat2
+      #     recovery --> transmission_reading : response_active
+      #     recovery --> success : response_final
+      #     starting --> error : response_cat2 / response_fatal_bad_response / request_*
+      #     recovery --> error : request_*
+      #     transmission_sending --> rejected : response_rejected
+      #     recovery --> rejected : response_rejected
+      #     cancelling --> cancelled : response_cancelled
+      #     transmission_sending --> cancelled : response_cancelled
+      #     success --> [*]
+      #     rejected --> [*]
+      #     cancelled --> [*]
+      #     error --> [*]
+      # ```
+      #
+      # The graph shows the protocol's intended path and its recoverable detours. Failure edges are largely omitted
+      # to keep it readable: every non-terminal status can also reach `error` (on `:global_deadline_exceeded`, on an
+      # unretriable request failure, on a bad or out-of-phase response, or on any unmatched event) and `rejected` (on
+      # `:response_rejected`), and every status listed in the `:user_cancel` arm can reach `cancelling`. `cancelling`
+      # in particular has only its success edge drawn; it fails like any other in-flight state. The
+      # `transmission_sending --> cancelled` edge stands in for all four statuses that reach `cancelled` on a
+      # server-reported out-of-band cancellation. {Rules.route} is the authoritative enumeration.
+      #
+      # ### Routing table
+      #
+      # {Rules.route} is the table: a pure function from `[status, shape]` to a recipe symbol, naming the handler
+      # without running it. {Rules.decide} runs whatever it names. Keeping selection separate from execution is what
+      # lets the tests enumerate the entire {STATUSES} x {SHAPES} product and assert every cell.
+      #
+      # Arms are written so that no arm matches a pair another arm also matches, which makes their order
+      # presentational. There is one deliberate exception:
+      #
+      # * `enter_recovery` and `fail_with_request_error` both match
+      #   `[:transmission_sending | :finalizing_sending_upload | :finalizing_sending_finalize,`
+      #   `:request_connection_failed | :request_timeout]`. Recovery wins purely because its arm precedes
+      #   `fail_with_request_error`.
+      #
+      # Two properties of the table are easy to misread and are called out at their arms:
+      #
+      # * `[:starting, :response_cat2]` fails instead of recovering, unlike the same shape during transmission
+      #   and finalizing. There is no upload to recover to until initiation yields an upload URL.
+      # * `recovery` re-queries on `:response_cat2` with no attempt cap. Termination is guaranteed only by the
+      #   global deadline the Driver enforces, not by anything in this module. Re-queries are spaced by the
+      #   recovery episode's backoff, tracked in {State#recovery_offset} and signalled through
+      #   {Instruction::SendQuery#backoff}; see `design/resumable_upload/implementation-guide.md` section 6.2.1.
+      #
+      # See `design/resumable_upload/implementation-guide.md` section 4 for the transition specification and
+      # section 6.1 for the error category taxonomy this module implements.
+      #
+      # rubocop:disable Metrics/ModuleLength
+      module Rules
+        ##
+        # @private
+        # Default chunk size in bytes (8 MB).
+        # @return [Integer]
+        DEFAULT_CHUNK_SIZE = 8_388_608 # 8 MB
+
+        # Failures are classified into three categories, which the rest of this module is written in terms of:
+        #
+        # * **Category 1 (transient transport)** - connection resets, TLS failures, load shedding. Retried inside
+        #   the Driver by {Driver::RetryDecider} for initiation, `query` and `cancel`, and never retried for
+        #   `upload` and `finalize`, where a lost connection leaves the server offset unknown. Whatever the Driver
+        #   does not retry, or stops retrying, reaches this module as a `:request_*` shape.
+        # * **Category 2 (recoverable protocol)** - the client offset may be misaligned with the server, or a
+        #   proxy stripped the protocol headers. Resolved by querying the server for its acknowledged offset
+        #   and realigning, never by blindly retransmitting. Shape: `:response_cat2`.
+        # * **Category 3 (terminal)** - structurally invalid, unauthorized, rejected, or out of budget.
+        #   Resolved by transitioning to `:error` or `:rejected` and emitting `Instruction::TerminateFailure`.
+        #
+        # See `design/resumable_upload/implementation-guide.md` section 6.1 for the full classification, and
+        # section 6.1.1 for which failures the Driver retries.
+
+        ##
+        # @private
+        # 4xx status codes the initiation, `query` and `cancel` retry policies retry by default.
+        #
+        # The data plane never retries a 4xx; see {Driver::RetryDecider}.
+        #
+        # @return [Array<Integer>]
+        RETRIABLE_4XX_STATUS_CODES = [409, 429, 499].freeze
+
+        ##
+        # @private
+        # 5xx status codes every retry policy retries by default.
+        #
+        # @return [Array<Integer>]
+        RETRIABLE_5XX_STATUS_CODES = [500, 503, 504].freeze
+
+        ##
+        # @private
+        # HTTP status codes eligible for Category 2 (recovery) handling.
+        #
+        # {Rules.classify_http_response} classifies a non-200 response whose `X-Goog-Upload-Status`
+        # is missing, empty or `active` as `:response_cat2` **only** if its status is listed here, and as
+        # `:response_fatal_bad_response` otherwise. It is an allowlist on purpose: a status nobody anticipated
+        # fails the upload rather than looping it through recovery.
+        #
+        # Every status either retry policy retries by default is listed, so a response the Driver stopped
+        # retrying still recovers. 408 and 502 are listed but not retried by default: neither has a gRPC code
+        # in `Gapic::Common::ErrorCodes`, so neither can be named in `retry_codes`.
+        #
+        # @return [Array<Integer>]
+        CAT2_STATUS_CODES = (RETRIABLE_4XX_STATUS_CODES + RETRIABLE_5XX_STATUS_CODES +
+                             [400, 408, 412, 416, 502]).sort.freeze
+
+        ##
+        # @private
+        # Human-readable state descriptions for error reporting.
+        # @return [Hash<Symbol, String>]
+        STATE_DESCRIPTIONS = {
+          initializing:                "initializing upload",
+          starting:                    "initiating upload session",
+          transmission_reading:        "reading chunk from stream",
+          transmission_sending:        "sending a chunk of data",
+          finalizing_sending_upload:   "sending final data chunk",
+          finalizing_sending_finalize: "sending finalize command",
+          recovery:                    "querying upload offset for recovery",
+          cancelling:                  "cancelling upload session",
+          success:                     "in completed upload state",
+          cancelled:                   "in cancelled upload state",
+          error:                       "in error state",
+          rejected:                    "in rejected upload state"
+        }.freeze
+
+        ##
+        # @private
+        # Canonical list of protocol lifecycle statuses a {State} may hold. Guaranteed to match the keys of
+        # {STATE_DESCRIPTIONS} by the classification test suite.
+        #
+        # * `:initializing` - nothing dispatched yet; awaits `:start_upload` or `:resume_upload`.
+        # * `:starting` - initiation request in flight; no upload URL yet.
+        # * `:transmission_reading` - filling the buffer from the stream.
+        # * `:transmission_sending` - a non-final chunk is in flight.
+        # * `:finalizing_sending_upload` - the last chunk is in flight, combined with the finalize command.
+        # * `:finalizing_sending_finalize` - a standalone finalize is in flight; all data bytes were already sent.
+        # * `:recovery` - offset query in flight, either after a recoverable failure or as the first step of a
+        #   resume.
+        # * `:cancelling` - cancel command in flight. Not reachable from the public API.
+        # * `:success` - terminal; the upload finalized.
+        # * `:cancelled` - terminal; the server acknowledged cancellation.
+        # * `:rejected` - terminal; the server refused the upload.
+        # * `:error` - terminal for this run; `last_error` holds the exception.
+        #
+        # `:success`, `:cancelled` and `:rejected` are finalized and yield no {ResumeHandle}. `:error` ends the
+        # run but may still be resumable from a fresh upload; see {Rules.resume_handle_from}.
+        #
+        # @return [Array<Symbol>]
+        STATUSES = [
+          :initializing,
+          :starting,
+          :transmission_reading,
+          :transmission_sending,
+          :finalizing_sending_upload,
+          :finalizing_sending_finalize,
+          :recovery,
+          :cancelling,
+          :success,
+          :cancelled,
+          :rejected,
+          :error
+        ].freeze
+
+        ##
+        # @private
+        # Terminal protocol lifecycle statuses in {STATUSES}.
+        # @return [Array<Symbol>]
+        TERMINAL_STATUSES = [:success, :cancelled, :rejected, :error].freeze
+
+        ##
+        # @private
+        # Canonical list of event shapes produced by {Rules.shape_of} and matched by {Rules.decide},
+        # grouped by the event family each is reduced from.
+        #
+        # Lifecycle signals, one shape each from {Event::StartUpload}, {Event::ResumeUpload}, {Event::Cancel}
+        # and {Event::GlobalDeadlineExceeded}: `:start_upload`, `:resume_upload`, `:user_cancel`,
+        # `:global_deadline_exceeded`.
+        #
+        # Stream reads, from {Event::ChunkRead} split by EOF and buffer occupancy. The three-way split is what
+        # lets a zero-length tail finalize without sending an empty chunk: `:chunk_read_full`,
+        # `:chunk_read_eof_with_data`, `:chunk_read_eof_empty`.
+        #
+        # Request failures, from {Event::RequestFailed} split by `kind`: `:request_timeout`,
+        # `:request_retries_exhausted`, `:request_connection_failed`, `:request_failed_unknown`.
+        #
+        # HTTP responses, from {Event::HttpResponse} split by `X-Goog-Upload-Status` and HTTP status:
+        # `:response_active`, `:response_final`, `:response_cancelled`, `:response_rejected`, `:response_cat2`,
+        # `:response_fatal_bad_response`.
+        #
+        # `:unknown` is a live shape rather than an error sentinel. It is what {Rules.shape_of} returns for anything
+        # it does not recognise, and it routes to {Rules.fail_with_unmatched_transition}.
+        #
+        # @return [Array<Symbol>]
+        SHAPES = [
+          :start_upload,
+          :resume_upload,
+          :user_cancel,
+          :global_deadline_exceeded,
+          :chunk_read_full,
+          :chunk_read_eof_with_data,
+          :chunk_read_eof_empty,
+          :request_timeout,
+          :request_retries_exhausted,
+          :request_connection_failed,
+          :request_failed_unknown,
+          :response_active,
+          :response_final,
+          :response_cancelled,
+          :response_rejected,
+          :response_cat2,
+          :response_fatal_bad_response,
+          :unknown
+        ].freeze
+
+        ##
+        # @private
+        # Canonical list of recipe symbols emitted by {Rules.decide}.
+        # @return [Array<Symbol>]
+        RECIPES = [
+          :start_session,
+          :resume_session,
+          :begin_transmission,
+          :send_chunk,
+          :send_upload_finalize,
+          :send_finalize,
+          :ack_chunk,
+          :enter_recovery,
+          :retry_recovery,
+          :realign_from_recovery,
+          :complete_upload_with_data,
+          :complete_upload_finalized,
+          :cancel_session,
+          :complete_cancellation,
+          :fail_with_cancelled,
+          :fail_with_deadline_exceeded,
+          :fail_with_rejected,
+          :fail_with_bad_response,
+          :fail_with_request_error,
+          :fail_with_unmatched_transition
+        ].freeze
+
+        ##
+        # @private
+        # Mapping of notifying recipes to their emitted {Progress} phase.
+        # @return [Hash<Symbol, Symbol>]
+        RECIPE_PHASES = {
+          start_session:             :initiating,
+          resume_session:            :initiating,
+          begin_transmission:        :uploading,
+          ack_chunk:                 :uploading,
+          realign_from_recovery:     :uploading,
+          enter_recovery:            :recovering,
+          send_upload_finalize:      :finalizing,
+          send_finalize:             :finalizing,
+          complete_upload_with_data: :completed,
+          complete_upload_finalized: :completed,
+          cancel_session:            :cancelling
+        }.freeze
+
+        ##
+        # @private
+        # Recipes that do not emit {Instruction::NotifyProgress}.
+        # @return [Array<Symbol>]
+        NON_NOTIFYING_RECIPES = [
+          :send_chunk,
+          :retry_recovery,
+          :complete_cancellation,
+          :fail_with_cancelled,
+          :fail_with_deadline_exceeded,
+          :fail_with_rejected,
+          :fail_with_bad_response,
+          :fail_with_request_error,
+          :fail_with_unmatched_transition
+        ].freeze
+
+        ##
+        # @private
+        # Classifies incoming event into a canonical shape symbol.
+        #
+        # @param event [Object] Input event
+        # @param state_status [Symbol] Status of the state the event arrives in. Only HTTP responses use it; see
+        #   {Rules.classify_http_response}.
+        # @return [Symbol] Canonical event shape
+        def self.shape_of event, state_status
+          case event
+          when Event::StartUpload, Event::StartUpload.singleton_class
+            :start_upload
+          when Event::ResumeUpload, Event::ResumeUpload.singleton_class
+            :resume_upload
+          when Event::ChunkRead
+            classify_chunk_read event
+          when Event::Cancel, Event::Cancel.singleton_class
+            :user_cancel
+          when Event::GlobalDeadlineExceeded, Event::GlobalDeadlineExceeded.singleton_class
+            :global_deadline_exceeded
+          when Event::RequestFailed
+            classify_request_failed event
+          when Event::HttpResponse
+            classify_http_response event, state_status
+          when Class
+            classify_event_class event
+          else
+            :unknown
+          end
+        end
+
+        ##
+        # @private
+        # Top-level transition decision engine. Routes `[state.status, shape_of(event, state.status)]` to a recipe
+        # and runs it.
+        #
+        # @param state [State] Current state
+        # @param event [Object] Input event
+        # @param config [StartUploadConfig, ResumeUploadConfig] Static configuration
+        # @return [Decision] Decision snapshot
+        # @raise [InternalError] If {Rules.shape_of} or {Rules.route} produces an unlisted value
+        def self.decide state, event, config
+          shape = shape_of event, state.status
+          unless SHAPES.include? shape
+            raise InternalError, "Resumable upload internal error: shape_of returned unknown shape #{shape.inspect}"
+          end
+
+          recipe = route state.status, shape
+          unless RECIPES.include? recipe
+            raise InternalError, "Resumable upload internal error: decide selected unknown recipe #{recipe.inspect}"
+          end
+
+          next_state, instructions = public_send recipe, state, event, config
+          Decision.new(
+            from_status:  state.status,
+            shape:        shape,
+            recipe:       recipe,
+            next_state:   next_state,
+            instructions: instructions
+          )
+        end
+
+        ##
+        # @private
+        # The routing table. Maps a `[status, shape]` pair to the recipe that handles it.
+        #
+        # Pure and side-effect free: it selects a recipe without running it, so the whole
+        # {STATUSES} x {SHAPES} product can be enumerated and asserted directly. {Rules.decide} is the only
+        # caller in production code.
+        #
+        # Arms are written so that no arm matches a pair another arm also matches, meaning
+        # the order does not matter, with a single deliberate exception, flagged in place,
+        # where `enter_recovery` must precede `fail_with_request_error`.
+        #
+        # @param status [Symbol] Current protocol status, one of {STATUSES}
+        # @param shape [Symbol] Canonical event shape, one of {SHAPES}
+        # @return [Symbol] Recipe symbol, one of {RECIPES}
+        #
+        # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/MethodLength
+        def self.route status, shape
+          case [status, shape]
+          in [:initializing, :start_upload]
+            :start_session
+          in [:initializing, :resume_upload]
+            :resume_session
+          in [:starting, :response_active]
+            :begin_transmission
+          in [:transmission_reading, :chunk_read_full]
+            :send_chunk
+          in [:transmission_reading, :chunk_read_eof_with_data]
+            :send_upload_finalize
+          in [:transmission_reading, :chunk_read_eof_empty]
+            :send_finalize
+          in [:transmission_sending, :response_active]
+            :ack_chunk
+          # Order matters: `enter_recovery` and `fail_with_request_error` below both match
+          # `[:transmission_sending | :finalizing_sending_upload | :finalizing_sending_finalize,
+          # :request_connection_failed | :request_timeout]`. Recovery wins purely because this arm comes first.
+          # This is the only overlap in the table.
+          in [:transmission_sending | :finalizing_sending_upload | :finalizing_sending_finalize,
+              :response_cat2 | :request_connection_failed | :request_timeout]
+            :enter_recovery
+          in [:finalizing_sending_upload, :response_final]
+            :complete_upload_with_data
+          in [:finalizing_sending_finalize | :recovery, :response_final]
+            :complete_upload_finalized
+          in [:recovery, :response_active]
+            :realign_from_recovery
+          # Re-query with no attempt cap. Only the Driver's global deadline guarantees termination.
+          in [:recovery, :response_cat2]
+            :retry_recovery
+          in [:cancelling, :response_cancelled]
+            :complete_cancellation
+          # A `cancelled` status on a session this client did not ask to cancel: the session was terminated
+          # out of band and no byte of it will ever be accepted again. Terminal, and deliberately not a bad
+          # response — the server answered correctly, so the caller gets no resume handle to loop on.
+          in [:transmission_sending | :finalizing_sending_upload |
+              :finalizing_sending_finalize | :recovery, :response_cancelled]
+            :fail_with_cancelled
+          in [_, :global_deadline_exceeded]
+            :fail_with_deadline_exceeded
+          in [:transmission_reading | :transmission_sending | :finalizing_sending_upload |
+              :finalizing_sending_finalize | :recovery, :user_cancel]
+            :cancel_session
+          in [:starting | :transmission_sending | :finalizing_sending_upload |
+              :finalizing_sending_finalize | :recovery | :cancelling, :response_rejected]
+            :fail_with_rejected
+          # Every HTTP response shape in an HTTP-awaiting status that no arm above claims. Spelled out per
+          # status rather than as a `[six statuses, five shapes]` cross product: the product would also cover
+          # combinations which are handled above.
+          #
+          # Note `[:starting, :response_cat2]`: initiation fails on a Category 2 response rather than
+          # recovering, unlike the transmission and finalizing statuses, because there is no upload to
+          # recover to until initiation has returned an upload URL.
+          in [:starting, :response_final | :response_cancelled |
+                         :response_cat2 | :response_fatal_bad_response] |
+             [:transmission_sending, :response_final | :response_fatal_bad_response] |
+             [:finalizing_sending_upload | :finalizing_sending_finalize,
+              :response_active | :response_fatal_bad_response] |
+             [:recovery, :response_fatal_bad_response] |
+             [:cancelling, :response_active | :response_final |
+                           :response_cat2 | :response_fatal_bad_response]
+            :fail_with_bad_response
+          in [:starting | :transmission_sending | :finalizing_sending_upload |
+              :finalizing_sending_finalize | :recovery | :cancelling,
+              :request_retries_exhausted | :request_connection_failed | :request_timeout |
+              :request_failed_unknown]
+            :fail_with_request_error
+          else
+            :fail_with_unmatched_transition
+          end
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/MethodLength
+
+        ##
+        # @private
+        # Top-level transition router. Matches [state.status, shape].
+        #
+        # @param state [State] Current state
+        # @param event [Object] Input event
+        # @param config [StartUploadConfig, ResumeUploadConfig] Static configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.step state, event, config
+          decision = decide state, event, config
+          [decision.next_state, decision.instructions]
+        end
+
+        ##
+        # @private
+        # Initiates the upload session.
+        #
+        # @param state [State] Current state
+        # @param _event [Object] Dispatched event
+        # @param config [StartUploadConfig] Session configuration; only an initiating run reaches this recipe
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.start_session state, _event, config
+          next_state = state.with status: :starting
+          progress = Progress.new phase: :initiating, bytes_uploaded: next_state.offset, total_bytes: config.upload_size
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::SendStart.new(
+              url:     config.initial_url,
+              headers: config.initial_headers,
+              body:    config.initial_body
+            )
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Resumes an existing upload session by transitioning to recovery and querying backend offset.
+        #
+        # Opens a recovery episode at offset 0, so the first query is sent at once.
+        #
+        # @param state [State] Current state
+        # @param _event [Object] Dispatched event
+        # @param config [ResumeUploadConfig] Resume session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.resume_session state, _event, config
+          next_state = state.with(
+            status:          :recovery,
+            upload_url:      config.upload_url,
+            chunk_size:      config.chunk_size,
+            offset:          0,
+            recovery_offset: 0
+          )
+          progress = Progress.new(
+            phase:          :initiating,
+            bytes_uploaded: 0,
+            total_bytes:    config.upload_size
+          )
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::SendQuery.new(url: config.upload_url)
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Processes initiation response and begins data reading.
+        #
+        # @param state [State] Current state
+        # @param event [Event::HttpResponse] Initiation response
+        # @param config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.begin_transmission state, event, config
+          granularity_str = header_value event.headers, "x-goog-upload-chunk-granularity"
+          granularity = parse_header_non_negative_integer granularity_str
+          granularity = nil unless granularity&.positive?
+          chunk_size = resolve_chunk_size config.chunk_size, granularity
+          upload_url = header_value event.headers, "x-goog-upload-url"
+          next_state = state.with(
+            status:            :transmission_reading,
+            upload_url:        upload_url,
+            chunk_granularity: granularity,
+            chunk_size:        chunk_size,
+            offset:            0,
+            in_flight_length:  0
+          )
+          progress = Progress.new phase: :uploading, bytes_uploaded: next_state.offset, total_bytes: config.upload_size
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::FillBuffer.new(target_bytesize: chunk_size)
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Emits instruction to transmit a filled data chunk.
+        #
+        # @param state [State] Current state
+        # @param event [Event::ChunkRead] Chunk read event
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.send_chunk state, event, _config
+          next_state = state.with(
+            status:           :transmission_sending,
+            in_flight_length: event.bytes_buffered
+          )
+          instructions = [
+            Instruction::SendChunk.new(
+              url:      state.upload_url,
+              offset:   state.offset,
+              length:   event.bytes_buffered,
+              finalize: false
+            )
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Emits instruction to transmit the final data chunk with finalize.
+        #
+        # @param state [State] Current state
+        # @param event [Event::ChunkRead] Chunk read event with EOF
+        # @param config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.send_upload_finalize state, event, config
+          next_state = state.with(
+            status:           :finalizing_sending_upload,
+            in_flight_length: event.bytes_buffered
+          )
+          progress = Progress.new phase: :finalizing, bytes_uploaded: next_state.offset, total_bytes: config.upload_size
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::SendChunk.new(
+              url:      state.upload_url,
+              offset:   state.offset,
+              length:   event.bytes_buffered,
+              finalize: true
+            )
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Emits instruction to send a zero-length finalize command.
+        #
+        # @param state [State] Current state
+        # @param _event [Object] Dispatched event
+        # @param config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.send_finalize state, _event, config
+          next_state = state.with(
+            status:           :finalizing_sending_finalize,
+            in_flight_length: 0
+          )
+          progress = Progress.new phase: :finalizing, bytes_uploaded: next_state.offset, total_bytes: config.upload_size
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::SendFinalize.new(url: state.upload_url)
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Acknowledges transmitted chunk and advances offset.
+        #
+        # Closes any open recovery episode: the server acknowledged a data command.
+        #
+        # @param state [State] Current state
+        # @param _event [Object] Dispatched event
+        # @param config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.ack_chunk state, _event, config
+          new_offset = state.offset + state.in_flight_length
+          next_state = state.with(
+            status:           :transmission_reading,
+            offset:           new_offset,
+            in_flight_length: 0,
+            recovery_offset:  nil
+          )
+          progress = Progress.new phase: :uploading, bytes_uploaded: new_offset, total_bytes: config.upload_size
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::RealignBuffer.new(server_offset: new_offset),
+            Instruction::FillBuffer.new(target_bytesize: state.chunk_size)
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Transitions to recovery state to query backend byte offset.
+        #
+        # Opens a recovery episode at the current offset and queries at once, unless an episode is already
+        # open. An open episode means the server has confirmed no new bytes since the previous recovery (an
+        # upload keeps failing while the query keeps answering `active`), so the query waits for the episode's
+        # next backoff delay instead.
+        #
+        # @param state [State] Current state
+        # @param _event [Object] Dispatched event
+        # @param config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.enter_recovery state, _event, config
+          episode_open = !state.recovery_offset.nil?
+          next_state = state.with(
+            status:           :recovery,
+            in_flight_length: 0,
+            recovery_offset:  episode_open ? state.recovery_offset : state.offset
+          )
+          progress = Progress.new phase: :recovering, bytes_uploaded: next_state.offset, total_bytes: config.upload_size
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::SendQuery.new(url: state.upload_url, backoff: episode_open)
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Retries offset query during recovery, after the open recovery episode's next backoff delay.
+        #
+        # @param state [State] Current state
+        # @param _event [Object] Dispatched event
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.retry_recovery state, _event, _config
+          next_state = state.with(
+            status:           :recovery,
+            in_flight_length: 0
+          )
+          [next_state, [Instruction::SendQuery.new(url: state.upload_url, backoff: true)]]
+        end
+
+        ##
+        # @private
+        # Completes upload when final chunk transmission succeeds.
+        #
+        # @param state [State] Current state
+        # @param event [Event::HttpResponse] Final HTTP response
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.complete_upload_with_data state, event, _config
+          new_offset = state.offset + state.in_flight_length
+          next_state = state.with(
+            status:           :success,
+            offset:           new_offset,
+            in_flight_length: 0
+          )
+          # `total_bytes` is set from `new_offset` even when `config.upload_size` is nil (see `Progress#total_bytes`).
+          progress = Progress.new phase: :completed, bytes_uploaded: new_offset, total_bytes: new_offset
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::TerminateSuccess.new(response: event)
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Completes upload when standalone finalize succeeds.
+        #
+        # @param state [State] Current state
+        # @param event [Event::HttpResponse] Final HTTP response
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.complete_upload_finalized state, event, _config
+          next_state = state.with(
+            status:           :success,
+            in_flight_length: 0
+          )
+          # `total_bytes` is set from `next_state.offset` even when `config.upload_size` is nil
+          # (see `Progress#total_bytes`).
+          progress = Progress.new phase: :completed, bytes_uploaded: next_state.offset, total_bytes: next_state.offset
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::TerminateSuccess.new(response: event)
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Realigns buffer and resumes transmission from recovered offset.
+        #
+        # Closes the open recovery episode only if the server confirmed bytes beyond the offset the episode
+        # began at. Otherwise the episode stays open: the command that failed has not yet been re-sent
+        # successfully, and if it fails again the next query must keep backing off. {Rules.ack_chunk} closes
+        # the episode once the re-sent command succeeds.
+        #
+        # @param state [State] Current state
+        # @param event [Event::HttpResponse] Query response containing acknowledged offset
+        # @param config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.realign_from_recovery state, event, config
+          server_offset_str = header_value event.headers, "x-goog-upload-size-received"
+          # Never nil here: {Rules.classify_http_response} classifies a query answer without a parseable offset
+          # as Category 2, so it is routed to {Rules.retry_recovery} instead.
+          server_offset = parse_header_non_negative_integer server_offset_str
+          # `>`, not `!=`: a lower offset is a regression, not progress. Closing on it would reset the backoff,
+          # and a server whose reported offset flips between two values would then query with no delay forever.
+          progressed = state.recovery_offset.nil? || server_offset > state.recovery_offset
+          next_state = state.with(
+            status:           :transmission_reading,
+            offset:           server_offset,
+            in_flight_length: 0,
+            recovery_offset:  progressed ? nil : state.recovery_offset
+          )
+          progress = Progress.new phase: :uploading, bytes_uploaded: server_offset, total_bytes: config.upload_size
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::RealignBuffer.new(server_offset: server_offset),
+            Instruction::FillBuffer.new(target_bytesize: state.chunk_size)
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Completes session cancellation and emits failure instruction.
+        #
+        # @param state [State] Current state
+        # @param event [Object] Cancellation response event
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.complete_cancellation state, event, _config
+          err = UploadCancelledError.from event
+          next_state = state.with status: :cancelled, in_flight_length: 0, last_error: err
+          [next_state, [Instruction::TerminateFailure.new(error: err)]]
+        end
+
+        ##
+        # @private
+        # Terminates the run after the server reported a session this client did not cancel as cancelled.
+        #
+        # Distinct from {Rules.complete_cancellation}, which acknowledges a cancellation this client
+        # requested. Both land in `:cancelled` with an {UploadCancelledError}, so the caller sees one error
+        # type for "this session is gone" regardless of who ended it. No resume handle is attached:
+        # {UploadCancelledError} does not include {HasResumeHandle}, because a cancelled session will never
+        # accept another byte and retrying against it cannot succeed.
+        #
+        # @param state [State] Current state
+        # @param _event [Event::HttpResponse] Response carrying `X-Goog-Upload-Status: cancelled`
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.fail_with_cancelled state, _event, _config
+          action = STATE_DESCRIPTIONS[state.status] || "processing #{state.status}"
+          err = UploadCancelledError.new "Resumable upload session was cancelled (detected while #{action})"
+          next_state = state.with status: :cancelled, in_flight_length: 0, last_error: err
+          [next_state, [Instruction::TerminateFailure.new(error: err)]]
+        end
+
+        ##
+        # @private
+        # Initiates session cancellation request.
+        #
+        # @param state [State] Current state
+        # @param _event [Object] Dispatched event
+        # @param config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.cancel_session state, _event, config
+          next_state = state.with status: :cancelling
+          progress = Progress.new phase: :cancelling, bytes_uploaded: next_state.offset, total_bytes: config.upload_size
+          instructions = [
+            Instruction::NotifyProgress.new(progress: progress),
+            Instruction::SendCancel.new(url: state.upload_url)
+          ]
+          [next_state, instructions]
+        end
+
+        ##
+        # @private
+        # Extracts a {ResumeHandle} from current protocol state.
+        # Completed uploads (`:success`), rejected uploads (`:rejected`), and cancelled uploads
+        # (`:cancelled`) are finalized and not resumable, returning `nil`.
+        #
+        # @param state [State] Protocol state
+        # @return [ResumeHandle, nil] Resume handle if upload URL is established and resumable, or nil
+        def self.resume_handle_from state
+          return nil if state.nil? || state.upload_url.nil? || [:rejected, :cancelled, :success].include?(state.status)
+
+          ResumeHandle.new upload_url: state.upload_url, chunk_size: state.chunk_size
+        end
+
+        ##
+        # @private
+        # Fails upload due to exceeded execution deadline.
+        #
+        # @param state [State] Current state
+        # @param _event [Object] Dispatched event
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.fail_with_deadline_exceeded state, _event, _config
+          handle = resume_handle_from state
+          err = DeadlineExceededError.new resume_handle: handle
+          next_state = state.with(
+            status:           :error,
+            in_flight_length: 0,
+            last_error:       err
+          )
+          [next_state, [Instruction::TerminateFailure.new(error: err)]]
+        end
+
+        ##
+        # @private
+        # Fails upload when backend explicitly rejects session.
+        #
+        # @param state [State] Current state
+        # @param event [Event::HttpResponse] Rejected HTTP response
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.fail_with_rejected state, event, _config
+          err = UploadRejectedError.from event
+          next_state = state.with(
+            status:           :rejected,
+            in_flight_length: 0,
+            last_error:       err
+          )
+          [next_state, [Instruction::TerminateFailure.new(error: err)]]
+        end
+
+        ##
+        # @private
+        # Fails upload when an unrecoverable HTTP response is encountered.
+        #
+        # Covers both malformed responses and well-formed ones that arrived in the wrong protocol phase, so
+        # the message names the phase: an `X-Goog-Upload-Status` of `final` is unremarkable on its own and
+        # only makes sense as a failure once the reader knows a non-final chunk was in flight.
+        #
+        # @param state [State] Current state
+        # @param event [Event::HttpResponse] Fatal or out-of-phase HTTP response
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.fail_with_bad_response state, event, _config
+          handle = resume_handle_from state
+          action = STATE_DESCRIPTIONS[state.status] || "processing #{state.status}"
+          err = BadResponseError.from event, resume_handle: handle,
+                                      prefix: "Resumable upload failed while #{action}"
+          next_state = state.with(
+            status:           :error,
+            in_flight_length: 0,
+            last_error:       err
+          )
+          [next_state, [Instruction::TerminateFailure.new(error: err)]]
+        end
+
+        ##
+        # @private
+        # Fails upload when an unrecoverable network or request error occurs.
+        #
+        # @param state [State] Current state
+        # @param event [Event::RequestFailed] Request failure event
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @return [Array<State, Array<Object>>] Tuple of [next_state, instructions]
+        def self.fail_with_request_error state, event, _config
+          handle = resume_handle_from state
+          err = RequestFailedError.from event, resume_handle: handle
+          next_state = state.with(
+            status:           :error,
+            in_flight_length: 0,
+            last_error:       err
+          )
+          [next_state, [Instruction::TerminateFailure.new(error: err)]]
+        end
+
+        ##
+        # @private
+        # Raises {InvalidTransitionError} for an unmatched state and event pair.
+        #
+        # Only reachable on an internal sequencing bug. Every externally caused failure — including an HTTP
+        # response whose upload status does not match the phase of the request in flight — is claimed by an
+        # arm in {Rules.route} and terminates through a recipe instead of raising from here.
+        #
+        # No resume handle is attached, for the same reason: this reports a defect in the library, not a
+        # resumable upload condition. A caller that still wants the handle can read it from
+        # {Gapic::ResumableUpload#resume_handle}.
+        #
+        # @param state [State] Current state
+        # @param event [Object] Dispatched event
+        # @param _config [StartUploadConfig, ResumeUploadConfig] Session configuration
+        # @raise [InvalidTransitionError]
+        def self.fail_with_unmatched_transition state, event, _config
+          shape = shape_of event, state.status
+          action = STATE_DESCRIPTIONS[state.status] || "processing #{state.status}"
+          happened = describe_event event, shape
+          message = "Resumable upload failed while #{action}: #{happened}."
+          response = event.is_a?(Event::HttpResponse) ? event : nil
+          raise InvalidTransitionError.new(
+            message,
+            state:    state.status,
+            event:    event,
+            response: response
+          )
+        end
+
+        ##
+        # @private
+        # Formats human-readable summary of an event.
+        #
+        # @param event [Object] Event instance
+        # @param shape [Symbol] Event shape symbol
+        # @return [String] Formatted description
+        def self.describe_event event, shape
+          case event
+          when Event::HttpResponse
+            upload_status = event.headers["x-goog-upload-status"] || event.headers["X-Goog-Upload-Status"]
+            status_desc = upload_status ? "'#{upload_status}'" : "missing"
+            "received an unexpected HTTP #{event.status} response (X-Goog-Upload-Status: #{status_desc})"
+          when Event::ChunkRead
+            "received unexpected stream chunk read (#{event.bytes_buffered} bytes, eof: #{event.eof})"
+          when Event::RequestFailed
+            "encountered unexpected request failure (#{event.kind}: #{event.message})"
+          else
+            "received unexpected event #{shape} (#{event.class.name})"
+          end
+        end
+
+        ##
+        # @private
+        # Parses a numeric protocol header value strictly.
+        #
+        # Accepts only a non-negative decimal integer, optionally surrounded by whitespace. Anything else —
+        # `nil`, empty, signed, fractional, or trailing garbage such as `"12abc"` — returns `nil`, so callers
+        # treat a malformed header the same as a missing one. `String#to_i` is deliberately not used: it turns
+        # `"12abc"` into `12` and `"-5"` into `-5`.
+        #
+        # @param value [String, nil] Raw header value
+        # @return [Integer, nil] Parsed value, or `nil` if the value is not a non-negative integer
+        def self.parse_header_non_negative_integer value
+          return nil unless value.is_a? String
+
+          stripped = value.strip
+          return nil unless stripped.match?(/\A\d+\z/)
+
+          Integer stripped, 10
+        end
+
+        ##
+        # @private
+        # Resolves effective chunk size given user specification and backend granularity.
+        #
+        # @param user_chunk_size [Integer, nil] Configured chunk size
+        # @param chunk_granularity [Integer, nil] Backend alignment granularity
+        # @return [Integer] Effective chunk size in bytes
+        def self.resolve_chunk_size user_chunk_size, chunk_granularity
+          base_size = user_chunk_size || DEFAULT_CHUNK_SIZE
+          return base_size if chunk_granularity.nil? || chunk_granularity <= 0
+          return chunk_granularity if base_size <= chunk_granularity
+
+          base_size - (base_size % chunk_granularity)
+        end
+
+        ##
+        # @private
+        # Classifies an HTTP response into a canonical response shape.
+        #
+        # Shapes are shown without their `response_` prefix.
+        #
+        # | `X-Goog-Upload-Status` | `200`         | in CAT2_STATUS_CODES | any other non-200 |
+        # |------------------------|---------------|----------------|-------------------|
+        # | missing / empty        | `cat2`        | `cat2`         | `fatal_bad_response` |
+        # | `active`               | `active` (1)  | `cat2`         | `fatal_bad_response` |
+        # | `final`                | `final`       | `rejected`     | `rejected`        |
+        # | `cancelled`            | `cancelled`   | `fatal_bad_response` | `fatal_bad_response` |
+        # | any other value        | `fatal_bad_response` | `fatal_bad_response` | `fatal_bad_response` |
+        #
+        # A headerless `200` is Category 2 regardless of {CAT2_STATUS_CODES}.
+        #
+        # (1) `cat2` instead if the response lacks a header that the command it answers requires (see
+        # {Rules.required_headers_present?}). This is the only cell that depends on `state_status`: every status
+        # that awaits a response awaits exactly one command, so the status says which headers are required.
+        #
+        # @param response [Event::HttpResponse] Response event
+        # @param state_status [Symbol] Status of the state the response arrives in
+        # @return [Symbol] Canonical response shape
+        def self.classify_http_response response, state_status
+          status_header = header_value(response.headers, "x-goog-upload-status")&.downcase
+
+          case status_header
+          when "active"
+            return classify_unsuccessful_status response.status unless response.status == 200
+            required_headers_present?(response, state_status) ? :response_active : :response_cat2
+          when "final"
+            response.status == 200 ? :response_final : :response_rejected
+          when "cancelled"
+            response.status == 200 ? :response_cancelled : :response_fatal_bad_response
+          when nil, ""
+            response.status == 200 ? :response_cat2 : classify_unsuccessful_status(response.status)
+          else
+            :response_fatal_bad_response
+          end
+        end
+
+        ##
+        # @private
+        # Whether a `200` `active` response carries the headers the command it answers needs to be acted on.
+        #
+        # * `start` (awaited in `:starting`): `X-Goog-Upload-URL` must be present and non-blank. Without it there
+        #   is no session to upload to.
+        # * `query` (awaited in `:recovery`): `X-Goog-Upload-Size-Received` must parse as a non-negative integer.
+        #   Treating a missing or malformed offset as `0` would silently restart the upload.
+        #
+        # A response that fails this check is Category 2, like a response with no upload status header at all.
+        # {Rules.route} then decides per status: `:starting` fails with {BadResponseError}, `:recovery`
+        # re-queries.
+        #
+        # @param response [Event::HttpResponse] Response event
+        # @param state_status [Symbol] Status of the state the response arrives in
+        # @return [Boolean]
+        def self.required_headers_present? response, state_status
+          case state_status
+          when :starting
+            !header_value(response.headers, "x-goog-upload-url").to_s.strip.empty?
+          when :recovery
+            !parse_header_non_negative_integer(header_value(response.headers, "x-goog-upload-size-received")).nil?
+          else
+            true
+          end
+        end
+
+        ##
+        # @private
+        # Classifies a non-200 status whose upload status header is missing, empty or `active`.
+        #
+        # @param status [Integer] HTTP status code
+        # @return [Symbol] `:response_cat2` if the status is in {CAT2_STATUS_CODES}, else
+        #   `:response_fatal_bad_response`
+        def self.classify_unsuccessful_status status
+          CAT2_STATUS_CODES.include?(status) ? :response_cat2 : :response_fatal_bad_response
+        end
+
+        ##
+        # @private
+        # Case-insensitive header lookup helper.
+        #
+        # @param headers [Hash, Object] Headers collection
+        # @param key [String] Target header key
+        # @return [String, nil] Header value
+        def self.header_value headers, key
+          return nil unless headers.is_a? Hash
+          return headers[key] if headers.key? key
+
+          target = key.downcase
+          _, val = headers.find { |k, _| k.to_s.downcase == target }
+          val
+        end
+
+        ##
+        # @private
+        # Classifies chunk read event by buffer size and EOF flag.
+        #
+        # @param event [Event::ChunkRead] Chunk read event
+        # @return [Symbol] Canonical chunk shape
+        def self.classify_chunk_read event
+          if !event.eof
+            :chunk_read_full
+          elsif event.bytes_buffered.positive?
+            :chunk_read_eof_with_data
+          else
+            :chunk_read_eof_empty
+          end
+        end
+
+        ##
+        # @private
+        # Classifies request failure event by failure kind.
+        #
+        # @param event [Event::RequestFailed] Request failed event
+        # @return [Symbol] Canonical failure shape
+        def self.classify_request_failed event
+          case event.kind
+          when :timeout then :request_timeout
+          when :retries_exhausted then :request_retries_exhausted
+          when :connection_failed then :request_connection_failed
+          else :request_failed_unknown
+          end
+        end
+
+        ##
+        # @private
+        # Classifies raw event class objects.
+        #
+        # @param event_class [Class] Event class
+        # @return [Symbol] Canonical shape
+        def self.classify_event_class event_class
+          if event_class == Event::StartUpload
+            :start_upload
+          elsif event_class == Event::ResumeUpload
+            :resume_upload
+          elsif event_class == Event::Cancel
+            :user_cancel
+          elsif event_class == Event::GlobalDeadlineExceeded
+            :global_deadline_exceeded
+          else
+            :unknown
+          end
+        end
+      end
+      # rubocop:enable Metrics/ModuleLength
+    end
+  end
+end