openai 0.80.0 → 0.82.0

data/lib/openai/internal/logging.rb

@@ -15,25 +15,14 @@ module OpenAI
         set-cookie
         x-amz-security-token
         x-api-key
-      ].freeze
+      ]
+        .freeze
       MAX_BODY_BYTES = 16 * 1024
       MAX_ARRAY_ITEMS = 100
       OPAQUE_STRING_BYTES = 1_024
       SENSITIVE_BODY_KEY = /(?:api[-_]?key|authorization|credential|password|secret|signature|token)/i
-      SENSITIVE_QUERY_KEY = /
-        (?:
-          (?:\A|[-_\[])(?:key|sig)
-          | (?-i:K)ey
-          | api[-_]?key
-          | authorization
-          | credentials?
-          | password
-          | secret
-          | signature
-          | token
-        )
-        (?:\[|\]|\z)
-      /ix
+      SENSITIVE_QUERY_KEY = /(?:(?:\A|[-_\[])(?:key|sig)|(?-i:K)ey|api[-_]?key|authorization|credentials?|password|secret|signature|token)(?:\[|\]|\z)/i
+      CALL_ID_ALIASES = %w[callid call-id call_id].freeze
       URL_HEADER_KEY = /(?:\A|[-_])(?:location|url|uri)\z|\A(?:link|refresh)\z/i
 
       class Context
@@ -58,16 +47,18 @@ module OpenAI
               "headers=#{OpenAI::Internal::Logging.format_headers(request.headers)} " \
               "body=#{OpenAI::Internal::Logging.format_body(request.body, headers: request.headers)}"
           end
+
           @attempt_started_at = OpenAI::Internal::Util.monotonic_secs
         end
 
         def response_received(response)
           log(:debug) do
             "[openai] response received log_id=#{id} attempt=#{@attempts} " \
-              "status=#{response.status} request_id=#{safe_field(response.headers['x-request-id'])} " \
+              "status=#{response.status} request_id=#{safe_field(response.headers["x-request-id"])} " \
               "duration_ms=#{attempt_duration_ms} " \
               "headers=#{OpenAI::Internal::Logging.format_headers(response.headers)}"
           end
+
           return response unless enabled?(:debug)
 
           observed = ObservedBody.new(
@@ -113,7 +104,7 @@ module OpenAI
           log(:info) do
             "[openai] request complete log_id=#{id} method=#{@method} " \
               "path=#{OpenAI::Internal::Logging.safe_path(@url)} " \
-              "status=#{response.status} request_id=#{safe_field(response.headers['x-request-id'])} " \
+              "status=#{response.status} request_id=#{safe_field(response.headers["x-request-id"])} " \
               "attempts=#{@attempts} duration_ms=#{duration_ms}"
           end
         end
@@ -130,7 +121,7 @@ module OpenAI
           log(:error) do
             "[openai] request failed log_id=#{id} method=#{@method} " \
               "path=#{OpenAI::Internal::Logging.safe_path(@url)} " \
-              "status=#{status || 'none'} request_id=#{safe_field(request_id)} " \
+              "status=#{status || "none"} request_id=#{safe_field(request_id)} " \
               "error=#{error.class} attempts=#{@attempts} duration_ms=#{duration_ms}"
           end
         end
@@ -178,6 +169,7 @@ module OpenAI
           in :error
             @logger.error(message)
           end
+
         rescue StandardError
           nil
         end
@@ -207,6 +199,7 @@ module OpenAI
               capture(chunk)
               yield(chunk)
             end
+
             @complete = true
           ensure
             close
@@ -276,13 +269,15 @@ module OpenAI
         def safe_field(value)
           return "none" if value.nil?
 
-          value.to_s.dump.delete_prefix('"').delete_suffix('"')
+          value.to_s.dump.delete_prefix("\"").delete_suffix("\"")
         end
 
         # @api private
         def sensitive_header?(name)
           normalized_name = name.to_s.downcase
-          REDACTED_HEADERS.include?(normalized_name) || SENSITIVE_QUERY_KEY.match?(normalized_name)
+          REDACTED_HEADERS.include?(normalized_name) ||
+            SENSITIVE_QUERY_KEY.match?(normalized_name) ||
+            sensitive_call_id?(normalized_name)
         end
 
         # @api private
@@ -296,19 +291,19 @@ module OpenAI
         end
 
         def format_headers(headers)
-          redacted =
-            headers.sort.to_h do |name, value|
-              normalized_name = name.to_s.downcase
-              rendered =
-                if sensitive_header?(normalized_name)
-                  "[REDACTED]"
-                elsif URL_HEADER_KEY.match?(normalized_name)
-                  sanitized_header_url(value)
-                else
-                  value
-                end
-              [name, rendered]
+          redacted = headers.sort.to_h do |name, value|
+            normalized_name = name.to_s.downcase
+            rendered = if sensitive_header?(normalized_name)
+              "[REDACTED]"
+            elsif URL_HEADER_KEY.match?(normalized_name)
+              sanitized_header_url(value)
+            else
+              value
             end
+
+            [name, rendered]
+          end
+
           JSON.generate(redacted)
         end
 
@@ -334,6 +329,7 @@ module OpenAI
           unless textual_content_type?(content_type)
             return "[BINARY BODY OMITTED] bytes=#{total_bytes}"
           end
+
           if total_bytes > MAX_BODY_BYTES && json_content_type?(content_type)
             return "[JSON BODY OMITTED] bytes=#{total_bytes} reason=too_large"
           end
@@ -345,21 +341,114 @@ module OpenAI
           uri = url.dup
           uri.user = nil
           uri.password = nil
+          uri.fragment = nil
+          realtime_route = sanitize_realtime_path!(uri)
           return uri if uri.query.nil?
 
-          uri.query = sanitized_query(uri.query)
+          uri.query = sanitized_query(uri.query, redact_call_ids: realtime_route)
           uri
         end
 
-        private def sanitized_query(query)
+        private def sanitize_realtime_path!(uri)
+          segments = uri.path.split("/", -1)
+          normalized = segments.map { URI::RFC2396_PARSER.unescape(_1) }
+          effective_indexes = []
+          normalized.each_with_index do |segment, index|
+            next if segment.empty? || segment == "."
+
+            segment == ".." ? effective_indexes.pop : effective_indexes << index
+          end
+
+          realtime_route = redact_realtime_segments!(segments, normalized, normalized.each_index)
+          effective_route = redact_realtime_segments!(segments, normalized, effective_indexes)
+          realtime_route ||= effective_route
+
+          uri.path = segments.join("/") if realtime_route
+          realtime_route
+        end
+
+        private def redact_realtime_segments!(segments, normalized, indexes)
+          realtime_route = false
+          expecting_calls = false
+          expecting_call_id = false
+
+          indexes.each do |index|
+            segment = normalized[index]
+            next if segment.empty? || %w[. ..].include?(segment)
+
+            if expecting_call_id
+              segments[index] = "%5BREDACTED%5D"
+              expecting_call_id = false
+            end
+
+            if segment == "realtime"
+              realtime_route = true
+              expecting_calls = true
+            elsif expecting_calls
+              expecting_call_id = segment == "calls"
+              expecting_calls = false
+            end
+          end
+
+          realtime_route
+        end
+
+        private def sanitized_query(query, redact_call_ids: false)
           pairs = URI.decode_www_form(query).map do |name, value|
-            [name, SENSITIVE_QUERY_KEY.match?(name) ? "[REDACTED]" : value]
+            sensitive = SENSITIVE_QUERY_KEY.match?(name) ||
+              (redact_call_ids && sensitive_call_id?(name))
+            [name, sensitive ? "[REDACTED]" : value]
           end
+
           URI.encode_www_form(pairs)
         rescue ArgumentError
           nil
         end
 
+        private def sensitive_call_id?(name)
+          normalized = name.to_s.downcase
+          bytes = normalized.b
+          bracket = bytes.index("[")
+          identifier = bracket.nil? ? normalized : normalized.byteslice(0, bracket)
+          recognized = CALL_ID_ALIASES.any? do |candidate|
+            identifier == candidate || identifier.end_with?("-#{candidate}", "_#{candidate}")
+          end
+
+          unless recognized
+            return false if bracket.nil?
+
+            return nested_call_id_alias?(bytes, bracket)
+          end
+
+          return true if bracket.nil?
+
+          first_bracket = bracket
+          while bracket < bytes.bytesize
+            unless bytes.getbyte(bracket) == "[".ord
+              return nested_call_id_alias?(bytes, first_bracket)
+            end
+
+            closing = bytes.index("]", bracket + 1)
+            return nested_call_id_alias?(bytes, first_bracket) if closing.nil?
+
+            bracket = closing + 1
+          end
+
+          true
+        end
+
+        private def nested_call_id_alias?(bytes, bracket)
+          terminal_alias = CALL_ID_ALIASES.any? do |candidate|
+            bytes.end_with?("-#{candidate}", "_#{candidate}")
+          end
+
+          return false unless bytes.end_with?("]") || terminal_alias
+
+          CALL_ID_ALIASES.any? do |candidate|
+            bytes.index("-#{candidate}", bracket) || bytes.index("_#{candidate}", bracket)
+          end
+        end
+
         private def sanitized_header_url(value)
           safe_url(URI(value.to_s))
         rescue URI::InvalidURIError
@@ -385,6 +474,7 @@ module OpenAI
           unless content_type.match?(%r{\Aapplication/x-www-form-urlencoded(?:;|\z)}i)
             return "[TEXT BODY OMITTED] bytes=#{total_bytes}"
           end
+
           return "[FORM BODY OMITTED] bytes=#{total_bytes} reason=too_large" if total_bytes > MAX_BODY_BYTES
 
           fields = URI.decode_www_form(body).length
@@ -396,21 +486,21 @@ module OpenAI
         end
 
         private def summarize_json_body(value, total_bytes:)
-          shape =
-            case value
-            in Hash
-              "object fields=#{value.length}"
-            in Array
-              "array items=#{value.length}"
-            in String
-              "string"
-            in Integer | Float
-              "number"
-            in true | false
-              "boolean"
-            in nil
-              "null"
-            end
+          shape = case value
+          in Hash
+            "object fields=#{value.length}"
+          in Array
+            "array items=#{value.length}"
+          in String
+            "string"
+          in Integer | Float
+            "number"
+          in true | false
+            "boolean"
+          in nil
+            "null"
+          end
+
           "[JSON BODY] bytes=#{total_bytes} type=#{shape}"
         end
       end

data/lib/openai/internal/next_cursor_page.rb

@@ -73,6 +73,7 @@ module OpenAI
           @data = data.map { OpenAI::Internal::Type::Converter.coerce(@model, _1) }
         else
         end
+
         @has_more = page_data[:has_more]
         @next_ = page_data[:next]
       end
@@ -83,8 +84,7 @@ module OpenAI
       def inspect
         model = OpenAI::Internal::Type::Converter.inspect(@model, depth: 1)
 
-        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)} " \
-          "has_more=#{has_more.inspect} next_=#{next_.inspect}>"
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)} has_more=#{has_more.inspect} next_=#{next_.inspect}>"
       end
     end
   end

data/lib/openai/internal/page.rb

@@ -30,7 +30,7 @@ module OpenAI
       # @raise [OpenAI::HTTP::Error]
       # @return [self]
       def next_page
-        RuntimeError.new("No more pages available.")
+        raise RuntimeError.new("No more pages available.")
       end
 
       # @param blk [Proc]
@@ -64,6 +64,7 @@ module OpenAI
           @data = data.map { OpenAI::Internal::Type::Converter.coerce(@model, _1) }
         else
         end
+
         @object = page_data[:object]
       end
 

data/lib/openai/internal/poller.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module OpenAI
+  module Internal
+    # Shared polling behavior for long-running API resources.
+    #
+    # @api private
+    class Poller
+      DEFAULT_INTERVAL = 5.0
+      DEFAULT_TIMEOUT = 30 * 60.0
+
+      # @api private
+      #
+      # @param operation [String]
+      # @param poll_interval [Integer, Float, nil]
+      # @param timeout [Integer, Float, nil]
+      def initialize(operation:, poll_interval: nil, timeout: DEFAULT_TIMEOUT)
+        @operation = operation
+        @poll_interval, @timeout = self.class.validate!(poll_interval: poll_interval, timeout: timeout)
+        @deadline = monotonic_time + @timeout unless @timeout.nil?
+      end
+
+      # Validate polling configuration without starting the deadline used by the
+      # eventual polling operation.
+      #
+      # Composite helpers call this before making any API requests so invalid local
+      # arguments cannot leave partially-created remote resources behind.
+      #
+      # @api private
+      #
+      # @param poll_interval [Integer, Float, nil]
+      # @param timeout [Integer, Float, nil]
+      # @return [Array(Float, nil)] the normalized poll interval and timeout
+      def self.validate!(poll_interval: nil, timeout: DEFAULT_TIMEOUT)
+        [
+          duration(poll_interval, name: :poll_interval, allow_zero: false),
+          duration(timeout, name: :timeout, allow_zero: true)
+        ]
+      end
+
+      # Run one retrieval within the remaining polling deadline. The block-level
+      # timeout covers work outside the HTTP transport, including authentication
+      # and request replays, while the postcondition catches a result that arrives
+      # as the deadline expires.
+      #
+      # @api private
+      #
+      # @param request_options [OpenAI::RequestOptions, Hash{Symbol=>Object}, nil]
+      # @param extra_headers [Hash{String=>String, nil}] endpoint headers to preserve
+      # @param resource [Object, nil] the last resource returned by the API
+      # @yieldparam options [Hash{Symbol=>Object}]
+      # @yieldreturn [Object]
+      # @return [Object]
+      def request(request_options, extra_headers: {}, resource: nil, &block)
+        remaining = check_deadline!(resource)
+        options = bounded_request_options(request_options, extra_headers: extra_headers, remaining: remaining)
+
+        result = if remaining.nil?
+          block.call(options)
+        else
+          Timeout.timeout(remaining) { block.call(options) }
+        end
+
+        check_deadline!(result)
+        result
+      rescue Timeout::Error
+        check_deadline!(resource)
+        raise
+      end
+
+      private def bounded_request_options(request_options, extra_headers:, remaining:)
+        options = request_options.to_h
+        headers = OpenAI::Internal::Util.normalized_headers(
+          extra_headers,
+          options[:extra_headers].to_h,
+          {"X-Stainless-Poll-Helper" => "true"}
+        )
+        unless @poll_interval.nil?
+          milliseconds = [(@poll_interval * 1000).round, 1].max
+          headers["x-stainless-custom-poll-interval"] = milliseconds.to_s
+        end
+
+        bounded = {**options, extra_headers: headers}
+        unless remaining.nil?
+          request_timeout = options[:timeout]
+          request_timeout = request_timeout.to_f.clamp(0..) unless request_timeout.nil?
+          bounded[:timeout] = [request_timeout, remaining].compact.min
+
+          # The transport applies `timeout` to every retry attempt independently.
+          # Disable those retries so the polling deadline bounds the whole request.
+          bounded[:max_retries] = 0
+        end
+
+        bounded
+      end
+
+      # Raise when the overall polling deadline has elapsed and otherwise return
+      # the time remaining. Resource helpers also call this after request timeouts
+      # to distinguish an exhausted polling deadline from a shorter caller timeout.
+      #
+      # @api private
+      #
+      # @param resource [Object, nil] the last resource returned by the API
+      # @return [Float, nil]
+      def check_deadline!(resource = nil)
+        remaining = @deadline - monotonic_time unless @deadline.nil?
+        raise_timeout(resource) if !remaining.nil? && remaining <= 0
+
+        remaining
+      end
+
+      # Sleep until the next request, respecting both the server's polling hint and
+      # the overall polling deadline.
+      #
+      # @api private
+      #
+      # @param resource [OpenAI::Internal::Type::BaseModel]
+      # @return [void]
+      def wait(resource)
+        remaining = check_deadline!(resource)
+
+        interval = @poll_interval || server_interval(resource) || DEFAULT_INTERVAL
+        if !remaining.nil? && interval >= remaining
+          sleep(remaining)
+          raise_timeout(resource)
+        end
+
+        sleep(interval)
+      end
+
+      private def raise_timeout(resource)
+        raise(
+          OpenAI::Errors::PollingTimeoutError.new(
+            operation: @operation,
+            timeout: @timeout,
+            resource: resource
+          )
+        )
+      end
+
+      private_class_method def self.duration(value, name:, allow_zero:)
+        return if value.nil?
+
+        unless value.is_a?(Integer) || value.is_a?(Float)
+          return invalid_duration!(name: name, allow_zero: allow_zero)
+        end
+
+        duration = value.to_f
+        valid = duration.finite? && (allow_zero ? duration >= 0 : duration.positive?)
+        return duration if valid
+
+        invalid_duration!(name: name, allow_zero: allow_zero)
+      end
+
+      private_class_method def self.invalid_duration!(name:, allow_zero:)
+        qualifier = allow_zero ? "non-negative" : "positive"
+        raise ArgumentError, "`#{name}` must be a #{qualifier} number of seconds or nil"
+      end
+
+      private def monotonic_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      private def server_interval(resource)
+        value = resource.last_response&.headers&.[]("openai-poll-after-ms")
+        return if value.nil?
+
+        interval = Float(value) / 1000
+        interval if interval.finite? && interval.positive?
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/openai/internal/read_io_adapter.rb

@@ -10,8 +10,11 @@ module OpenAI
         class InterruptibleEnumerator
           # Cancellation must bypass application rescues so a suspended source cannot
           # swallow it and keep the request teardown blocked.
-          class Interrupt < Exception # rubocop:disable Lint/InheritException
+          # rubocop:disable Lint/InheritException
+          class Interrupt < Exception
           end
+          # rubocop:enable Lint/InheritException
+
           private_constant :Interrupt
 
           def initialize(source)
@@ -40,13 +43,14 @@ module OpenAI
           end
 
           def close
-            @fiber&.raise(Interrupt) if @started && @fiber&.alive?
+            @fiber&.raise Interrupt if @started && @fiber&.alive?
           rescue Interrupt
             nil
           ensure
             @fiber = nil
           end
         end
+
         private_constant :InterruptibleEnumerator
 
         # @api private
@@ -81,6 +85,7 @@ module OpenAI
             @buf << @stream.next.b while @buf.bytesize < max_len
             read_buffer(max_len)
           end
+
         rescue StopIteration
           return @buf.slice!(0..) if max_len.nil?
 
@@ -112,15 +117,14 @@ module OpenAI
             raise ArgumentError, "negative length #{max_len} given"
           end
 
-          read =
-            case @stream
-            in nil
-              max_len.nil? || max_len.zero? ? +"" : nil
-            in IO | StringIO
-              return @stream.read(max_len, out_string).tap(&@blk)
-            in Enumerator | InterruptibleEnumerator
-              read_enum(max_len)
-            end
+          read = case @stream
+          in nil
+            max_len.nil? || max_len.zero? ? +"" : nil
+          in IO | StringIO
+            return @stream.read(max_len, out_string).tap(&@blk)
+          in Enumerator | InterruptibleEnumerator
+            read_enum(max_len)
+          end
 
           case out_string
           in String
@@ -139,19 +143,19 @@ module OpenAI
         #
         # @yieldparam [String]
         def initialize(src, &blk)
-          @stream =
-            case src
-            in String
-              StringIO.new(src)
-            in Pathname
-              @closing = true
-              src.open(binmode: true)
-            in Enumerator
-              @closing = true
-              InterruptibleEnumerator.new(src)
-            else
-              src
-            end
+          @stream = case src
+          in String
+            StringIO.new(src)
+          in Pathname
+            @closing = true
+            src.open(binmode: true)
+          in Enumerator
+            @closing = true
+            InterruptibleEnumerator.new(src)
+          else
+            src
+          end
+
           @buf = String.new.b
           @blk = blk
         end

data/lib/openai/internal/request_options_scope.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module OpenAI
+  module Internal
+    # Derives request options for the individual writes in a composite helper.
+    #
+    # A caller-supplied idempotency key names the composite operation. Each child
+    # write receives a deterministic derived key so its retries remain stable
+    # without colliding with another write in the same operation. Structured keys
+    # are materialized as the standard header; an explicit header remains authoritative.
+    #
+    # @api private
+    class RequestOptionsScope
+      IDEMPOTENCY_HEADER = "Idempotency-Key"
+      private_constant :IDEMPOTENCY_HEADER
+
+      # @api private
+      #
+      # @param request_options [OpenAI::RequestOptions, Hash{Symbol=>Object}, nil]
+      def initialize(request_options)
+        options = request_options.to_h.dup
+        OpenAI::RequestOptions.validate!(options)
+        if options.key?(:extra_headers)
+          options[:extra_headers] = options[:extra_headers].to_h.dup.freeze
+        end
+
+        @options = options.freeze
+      end
+
+      # @api private
+      #
+      # @param operation [String]
+      # @return [Hash{Symbol=>Object}]
+      def child(operation)
+        options = @options.dup
+        key = options[:idempotency_key]
+        derived_key = derive(key, operation) unless key.nil?
+        options[:idempotency_key] = derived_key unless derived_key.nil?
+
+        headers = options[:extra_headers].to_h
+        header = headers.keys.reverse.find { _1.to_s.casecmp?(IDEMPOTENCY_HEADER) }
+        header_key = headers[header] unless header.nil?
+        if header.nil?
+          options[:extra_headers] = headers.merge(IDEMPOTENCY_HEADER => derived_key) unless derived_key.nil?
+        elsif !header_key.nil?
+          options[:extra_headers] = headers.merge(header => derive(header_key, operation))
+        end
+
+        options
+      end
+
+      private def derive(key, operation)
+        digest = Digest::SHA256.hexdigest("#{key}\0#{operation}")
+        "stainless-ruby-#{digest}"
+      end
+    end
+  end
+end