gapic-common 1.4.0 → 1.5.0

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

@@ -0,0 +1,129 @@
+# 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.
+
+module Gapic
+  module Rest
+    module ResumableUpload
+      ##
+      # @private
+      # Event vocabulary emitted by the Driver and dispatched to Core/Rules.
+      # Events are `outside-in` signaling. Something happened, e.g. a chunk of data
+      # was successfully read, and the Driver is reporting that to Core/Rules.
+      #
+      module Event
+        ##
+        # @private
+        # Signals the start of the upload session.
+        #
+        StartUpload = Data.define
+
+        ##
+        # @private
+        # Signals the resumption of an existing upload session.
+        #
+        ResumeUpload = Data.define
+
+        ##
+        # @private
+        # Signals that binary data was read from the stream into the Driver's buffer.
+        #
+        # @!attribute [r] bytes_buffered
+        #   @return [Integer] Number of bytes currently held in the Driver buffer
+        # @!attribute [r] eof
+        #   @return [Boolean] Whether stream EOF was encountered during the read
+        #
+        ChunkRead = Data.define :bytes_buffered, :eof do
+          ##
+          # @private
+          # Initializes a ChunkRead event.
+          #
+          # @param bytes_buffered [Integer] Number of bytes currently held in buffer
+          # @param eof [Boolean] Whether stream EOF was encountered
+          #
+          def initialize bytes_buffered: 0, eof: false
+            super bytes_buffered: bytes_buffered, eof: eof
+          end
+        end
+
+        ##
+        # @private
+        # Signals a completed HTTP exchange over the wire (status, headers, body, error).
+        #
+        # @!attribute [r] status
+        #   @return [Integer] HTTP status code
+        # @!attribute [r] headers
+        #   @return [Hash<String, String>] Response headers
+        # @!attribute [r] body
+        #   @return [String, nil] Response body
+        # @!attribute [r] error
+        #   @return [Gapic::Rest::Error, nil] Wrapped REST error if status >= 400
+        #
+        HttpResponse = Data.define :status, :headers, :body, :error do
+          ##
+          # @private
+          # Initializes an HttpResponse event.
+          #
+          # @param status [Integer] HTTP status code
+          # @param headers [Hash<String, String>] Response headers
+          # @param body [String, nil] Response body
+          # @param error [Gapic::Rest::Error, nil] Wrapped REST error
+          #
+          def initialize status:, headers: {}, body: nil, error: nil
+            super status: status, headers: headers || {}, body: body, error: error
+          end
+        end
+
+        ##
+        # @private
+        # Signals an HTTP request failure (e.g. request timeout, transport connection failure, or retries exhausted).
+        #
+        # @!attribute [r] kind
+        #   @return [Symbol] Failure kind: `:timeout`, `:connection_failed`, `:retries_exhausted` (a transport
+        #     error of no more specific kind), or `:unknown` (a non-transport error, e.g. a credentials failure)
+        # @!attribute [r] message
+        #   @return [String, nil] Human-readable failure summary
+        # @!attribute [r] source_error
+        #   @return [StandardError, nil] Original underlying exception
+        #
+        RequestFailed = Data.define :kind, :message, :source_error do
+          ##
+          # @private
+          # Initializes a RequestFailed event.
+          #
+          # @param kind [Symbol] Failure kind (`:timeout`, `:connection_failed`, `:retries_exhausted`, `:unknown`)
+          # @param message [String, nil] Human-readable failure summary
+          # @param source_error [StandardError, nil] Original underlying exception
+          #
+          def initialize kind:, message: nil, source_error: nil
+            super kind: kind, message: message, source_error: source_error
+          end
+        end
+
+        ##
+        # @private
+        # Signals a caller-requested session cancellation.
+        #
+        Cancel = Data.define
+
+        ##
+        # @private
+        # Signals that the global monotonic clock exceeded the configured deadline.
+        #
+        GlobalDeadlineExceeded = Data.define
+      end
+    end
+  end
+end

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

@@ -0,0 +1,273 @@
+# 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.
+
+module Gapic
+  module Rest
+    module ResumableUpload
+      ##
+      # @private
+      # Instruction vocabulary emitted by Rules/Core to be executed by Driver.
+      # The vocabulary is partitioned three ways ({CONTINUATION}, {TERMINAL}, {SIDE_EFFECT}),
+      # and every instruction class must join exactly one list.
+      #
+      module Instruction
+        ##
+        # @private
+        # Execute initiation request to establish upload session.
+        #
+        # @!attribute [r] url
+        #   @return [String] Initial endpoint URI
+        # @!attribute [r] headers
+        #   @return [Hash<String, String>] Additional headers for initiation request
+        # @!attribute [r] body
+        #   @return [String, nil] Request payload for session initiation
+        #
+        SendStart = Data.define :url, :headers, :body do
+          ##
+          # @private
+          # Initializes a SendStart instruction.
+          #
+          # @param url [String] Initial endpoint URI
+          # @param headers [Hash<String, String>] Additional headers
+          # @param body [String, nil] Request payload
+          #
+          def initialize url:, headers: {}, body: nil
+            super url: url, headers: headers || {}, body: body
+          end
+        end
+
+        ##
+        # @private
+        # Transmit buffered chunk starting at offset for length bytes.
+        #
+        # @!attribute [r] url
+        #   @return [String] Session upload URL
+        # @!attribute [r] offset
+        #   @return [Integer] Byte offset within the full upload stream
+        # @!attribute [r] length
+        #   @return [Integer] Number of bytes to transmit from buffer
+        # @!attribute [r] finalize
+        #   @return [Boolean] Whether to append finalize command to upload request
+        #
+        SendChunk = Data.define :url, :offset, :length, :finalize do
+          ##
+          # @private
+          # Initializes a SendChunk instruction.
+          #
+          # @param url [String] Session upload URL
+          # @param offset [Integer] Byte offset within upload stream
+          # @param length [Integer] Number of bytes to transmit
+          # @param finalize [Boolean] Whether to combine upload and finalize commands
+          #
+          def initialize url:, offset:, length:, finalize: false
+            super url: url, offset: offset, length: length, finalize: finalize
+          end
+        end
+
+        ##
+        # @private
+        # Send standalone finalize command when all data bytes were already uploaded.
+        #
+        # @!attribute [r] url
+        #   @return [String] Session upload URL
+        #
+        SendFinalize = Data.define :url do
+          ##
+          # @private
+          # Initializes a SendFinalize instruction.
+          #
+          # @param url [String] Session upload URL
+          #
+          def initialize url:
+            super url: url
+          end
+        end
+
+        ##
+        # @private
+        # Query backend for current acknowledged offset.
+        #
+        # Every query belongs to a recovery episode (see {State#recovery_offset}). The Driver keeps one
+        # `Gapic::Common::RetryPolicy` per episode and uses it both between attempts of a single query and
+        # between queries, so the delay grows across the whole episode instead of restarting per command.
+        #
+        # @!attribute [r] url
+        #   @return [String] Session upload URL
+        # @!attribute [r] backoff
+        #   @return [Boolean] `false` to open a new recovery episode and send at once; `true` to continue the
+        #     open episode, waiting for its next backoff delay before sending
+        #
+        SendQuery = Data.define :url, :backoff do
+          ##
+          # @private
+          # Initializes a SendQuery instruction.
+          #
+          # @param url [String] Session upload URL
+          # @param backoff [Boolean] Whether to continue the open recovery episode after its next backoff delay
+          #
+          def initialize url:, backoff: false
+            super url: url, backoff: backoff
+          end
+        end
+
+        ##
+        # @private
+        # Cancel upload session on backend.
+        #
+        # @!attribute [r] url
+        #   @return [String] Session upload URL
+        #
+        SendCancel = Data.define :url do
+          ##
+          # @private
+          # Initializes a SendCancel instruction.
+          #
+          # @param url [String] Session upload URL
+          #
+          def initialize url:
+            super url: url
+          end
+        end
+
+        ##
+        # @private
+        # Realign Driver in-memory buffer and stream position to match server_offset.
+        #
+        # @!attribute [r] server_offset
+        #   @return [Integer] Acknowledged byte offset reported by server
+        #
+        RealignBuffer = Data.define :server_offset do
+          ##
+          # @private
+          # Initializes a RealignBuffer instruction.
+          #
+          # @param server_offset [Integer] Target server byte offset
+          #
+          def initialize server_offset:
+            super server_offset: server_offset
+          end
+        end
+
+        ##
+        # @private
+        # Read from stream until in-memory buffer reaches target_bytesize or stream hits EOF.
+        #
+        # @!attribute [r] target_bytesize
+        #   @return [Integer] Target buffer size in bytes
+        #
+        FillBuffer = Data.define :target_bytesize do
+          ##
+          # @private
+          # Initializes a FillBuffer instruction.
+          #
+          # @param target_bytesize [Integer] Target buffer size in bytes
+          #
+          def initialize target_bytesize:
+            super target_bytesize: target_bytesize
+          end
+        end
+
+        ##
+        # @private
+        # Invoke user progress callback with a Progress instance.
+        #
+        # @!attribute [r] progress
+        #   @return [Gapic::Rest::ResumableUpload::Progress] Progress notification snapshot
+        #
+        NotifyProgress = Data.define :progress do
+          ##
+          # @private
+          # Initializes a NotifyProgress instruction.
+          #
+          # @param progress [Gapic::Rest::ResumableUpload::Progress] Progress notification snapshot
+          #
+          def initialize progress:
+            super progress: progress
+          end
+        end
+
+        ##
+        # @private
+        # Upload finalized cleanly; return response.
+        #
+        # @!attribute [r] response
+        #   @return [Gapic::Rest::ResumableUpload::Event::HttpResponse] Final response object
+        #
+        TerminateSuccess = Data.define :response do
+          ##
+          # @private
+          # Initializes a TerminateSuccess instruction.
+          #
+          # @param response [Gapic::Rest::ResumableUpload::Event::HttpResponse] Final response object
+          #
+          def initialize response:
+            super response: response
+          end
+        end
+
+        ##
+        # @private
+        # Terminate upload with error.
+        #
+        # @!attribute [r] error
+        #   @return [StandardError] Terminal exception to raise
+        #
+        TerminateFailure = Data.define :error do
+          ##
+          # @private
+          # Initializes a TerminateFailure instruction.
+          #
+          # @param error [StandardError] Terminal exception to raise
+          #
+          def initialize error:
+            super error: error
+          end
+        end
+
+        ##
+        # @private
+        # Instruction classes that produce a continuation event for the next step of the trampoline loop.
+        # @return [Array<Class>]
+        CONTINUATION = [
+          FillBuffer,
+          SendStart,
+          SendChunk,
+          SendFinalize,
+          SendQuery,
+          SendCancel
+        ].freeze
+
+        ##
+        # @private
+        # Instruction classes that terminate the upload run.
+        # @return [Array<Class>]
+        TERMINAL = [
+          TerminateSuccess,
+          TerminateFailure
+        ].freeze
+
+        ##
+        # @private
+        # Instruction classes that perform side effects without producing continuation events or terminating.
+        # @return [Array<Class>]
+        SIDE_EFFECT = [
+          NotifyProgress,
+          RealignBuffer
+        ].freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# 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_codes"
+require "gapic/common/retry_policy"
+require "gapic/rest/resumable_upload/rules"
+
+module Gapic
+  module Rest
+    module ResumableUpload
+      ##
+      # @private
+      # Default retry policy generators for control plane and data plane requests.
+      #
+      # The defaults carry no `retry_predicate`: every protocol-specific retry decision lives in
+      # {Driver::RetryDecider}, which consults a policy only for its budget and backoff, and for the
+      # caller-facing `retry_predicate` and `retry_codes`. The `retry_codes` below are derived from the HTTP
+      # status sets on {Rules}, so HTTP status is the single source of truth.
+      #
+      # Keep in sync with the "Retry Policies" section of the {Gapic::ResumableUpload} class doc.
+      #
+      module RetryPolicies
+        ##
+        # @private
+        # Default `retry_codes` for initiation, `query` and `cancel`: 409, 429, 499, 500, 503 and 504.
+        # @return [Array<Integer>]
+        START_AND_CONTROL_PLANE_RETRY_CODES =
+          (Rules::RETRIABLE_4XX_STATUS_CODES + Rules::RETRIABLE_5XX_STATUS_CODES).map do |status|
+            Gapic::Common::ErrorCodes.grpc_error_for status
+          end.freeze
+
+        ##
+        # @private
+        # Default `retry_codes` for `upload` and `finalize`: 500, 503 and 504. The data plane never
+        # retries a 4xx, so none is listed.
+        # @return [Array<Integer>]
+        DATA_PLANE_RETRY_CODES = Rules::RETRIABLE_5XX_STATUS_CODES.map do |status|
+          Gapic::Common::ErrorCodes.grpc_error_for status
+        end.freeze
+
+        ##
+        # @private
+        # Default options for start command retry policy.
+        # @return [Hash]
+        START_DEFAULTS = {
+          retry_codes:   START_AND_CONTROL_PLANE_RETRY_CODES,
+          initial_delay: 1.0,
+          max_delay:     15.0,
+          multiplier:    1.3
+        }.freeze
+
+        ##
+        # @private
+        # Default options for query and cancel commands retry policy.
+        # @return [Hash]
+        CONTROL_PLANE_DEFAULTS = {
+          retry_codes:   START_AND_CONTROL_PLANE_RETRY_CODES,
+          initial_delay: 1.0,
+          max_delay:     15.0,
+          multiplier:    1.3
+        }.freeze
+
+        ##
+        # @private
+        # Default options for upload and finalize commands retry policy.
+        # @return [Hash]
+        DATA_PLANE_DEFAULTS = {
+          retry_codes:   DATA_PLANE_RETRY_CODES,
+          initial_delay: 1.0,
+          max_delay:     15.0,
+          multiplier:    1.3
+        }.freeze
+
+        ##
+        # @private
+        # Default retry policy for session initiation requests (start).
+        #
+        # @return [Gapic::Common::RetryPolicy]
+        def self.default_start
+          Gapic::Common::RetryPolicy.new(**START_DEFAULTS)
+        end
+
+        ##
+        # @private
+        # Default retry policy for session control requests (query, cancel).
+        #
+        # @return [Gapic::Common::RetryPolicy]
+        def self.default_control_plane
+          Gapic::Common::RetryPolicy.new(**CONTROL_PLANE_DEFAULTS)
+        end
+
+        ##
+        # @private
+        # Default retry policy for data plane requests (upload, finalize).
+        #
+        # @return [Gapic::Common::RetryPolicy]
+        def self.default_data_plane
+          Gapic::Common::RetryPolicy.new(**DATA_PLANE_DEFAULTS)
+        end
+      end
+    end
+  end
+end