openai 0.106.0 → 0.107.0

data/lib/openai/helpers/realtime/translation.rb

@@ -25,36 +25,11 @@ module OpenAI
   module Realtime
     # Future event data is accessible explicitly without leaking in diagnostics.
     class UnknownTranslationServerEvent < OpenAI::Realtime::UnknownServerEvent
-      def inspect = "#<#{self.class} type=#{@type.inspect}>"
-      alias to_s inspect
-
-      private def freeze_json(value)
-        pending = [value]
-        visited = {}.compare_by_identity
-        until pending.empty?
-          item = pending.pop
-          next if visited.key?(item)
-          visited[item] = true
-          case item
-          when Hash
-            item.each { |key, val| pending.push(key, val) }
-          when Array
-            pending.concat(item)
-          end
-
-          item.freeze
-        end
-
-        value
-      end
     end
 
     # Opening does not send any events. session.close flushes remaining output;
     # read through session.closed before leaving the block to consume it.
-    class TranslationConnection < OpenAI::WebSocket::Connection
-      include OpenAI::WebSocket::Protocol
-      include OpenAI::WebSocket::GuardedConnection
-
+    class TranslationConnection < OpenAI::WebSocket::TypedConnection
       # Timeout implementations before Ruby 4 raise StandardError through the
       # scheduler. Cross transport error wrappers without changing raw callers.
       # rubocop:disable Lint/InheritException
@@ -66,21 +41,17 @@ module OpenAI
 
       # @api private
       def initialize(socket:, url:)
-        super
+        super(
+          socket: socket,
+          url: url,
+          client_event: OpenAI::Realtime::RealtimeTranslationClientEvent,
+          server_event: OpenAI::Realtime::RealtimeTranslationServerEvent
+        )
         @poisoned = false
         @closed = false
         @write_mutex = Mutex.new
         @read_state_mutex = Mutex.new
         @active_reads = 0
-        @server_event_types = OpenAI::Realtime::RealtimeTranslationServerEvent.variants.to_h do |variant|
-          [variant.fields.fetch(:type).fetch(:const).to_s, variant]
-        end
-
-        @client_event_names = discriminator_values(OpenAI::Realtime::RealtimeTranslationClientEvent)
-      end
-
-      def send_event(event)
-        send_raw(encode_client_event(event))
       end
 
       # Request a final flush and yield every trailing event, including
@@ -101,10 +72,21 @@ module OpenAI
         require "timeout"
 
         @read_state_mutex.synchronize do
+          if @finish_owner
+            raise(
+              connection_error("Translation finish must run on the existing receive owner, between reads."),
+              cause: nil
+            )
+          end
+
+          # SDK .cause accessors can expose diagnostics hidden from native rendering.
+          raise @finish_error, cause: Exception.instance_method(:cause).bind_call(@finish_error) if @finish_error
           return @finish_terminal if @finish_terminal
-          raise @finish_error if @finish_error
-          if @active_reads.positive? || @finish_requested || @finish_owner
-            raise connection_error("Translation finish must run on the existing receive owner, between reads.")
+          if @active_reads.positive? || @finish_requested
+            raise(
+              connection_error("Translation finish must run on the existing receive owner, between reads."),
+              cause: nil
+            )
           end
 
           @finish_owner = Fiber.current
@@ -114,14 +96,13 @@ module OpenAI
           Timeout.timeout(seconds, FinishTimeout) do
             write_text(encode_client_event(type: "session.close"), finish: true)
             while (event = receive)
+              terminal = event.is_a?(OpenAI::Realtime::RealtimeTranslationSessionClosedEvent)
+              @read_state_mutex.synchronize { @finish_terminal = event } if terminal
               yield(event)
-              if event.is_a?(OpenAI::Realtime::RealtimeTranslationSessionClosedEvent)
-                @read_state_mutex.synchronize { @finish_terminal = event }
-                return event
-              end
+              return event if terminal
             end
 
-            raise connection_error("Translation socket closed before session.closed.")
+            raise connection_error("Translation socket closed before session.closed."), cause: nil
           end
 
         rescue FinishTimeout
@@ -139,10 +120,10 @@ module OpenAI
       private def write_text(text, finish: false)
         @write_mutex.synchronize do
           if @finish_requested || (@finish_owner && !finish)
-            raise connection_error("Cannot send after Translation finish was requested.")
+            raise connection_error("Cannot send after Translation finish was requested."), cause: nil
           end
 
-          raise connection_error("Cannot send on a closed Realtime Translation WebSocket.") if closed?
+          raise connection_error("Cannot send on a closed Realtime Translation WebSocket."), cause: nil if closed?
           @finish_requested = true if finish
           super(text)
         end
@@ -151,7 +132,10 @@ module OpenAI
       private def read_raw_message
         @read_state_mutex.synchronize do
           if @finish_owner && @finish_owner != Fiber.current
-            raise connection_error("Translation finish must run on the existing receive owner, between reads.")
+            raise(
+              connection_error("Translation finish must run on the existing receive owner, between reads."),
+              cause: nil
+            )
           end
 
           @active_reads += 1
@@ -164,133 +148,17 @@ module OpenAI
         end
       end
 
-      private def encode_client_event(event)
-        validate_client_tree!(event)
-        union = OpenAI::Realtime::RealtimeTranslationClientEvent
-        payload = OpenAI::Internal::Type::Converter.dump(union, event)
-        type = payload[:type] || payload["type"] if payload.is_a?(Hash)
-        raise ArgumentError unless (type.is_a?(String) || type.is_a?(Symbol)) && @client_event_names.key?(type.to_s)
-
-        coerced = coerce_event(union, payload, outbound: true)
-        serialized = OpenAI::Internal::Type::Converter.dump(union, coerced)
-        validate_client_tree!(serialized, json_only: true)
-        JSON.generate(serialized, max_nesting: false)
-      rescue StandardError, SystemStackError
-        raise ArgumentError, "Invalid Realtime Translation client event.", cause: nil
-      end
-
-      # A merged string-keyed JSON event and symbol-keyed override must not
-      # silently change the command or the configuration that is sent.
-      private def validate_client_tree!(event, json_only: false)
-        visited = {}.compare_by_identity
-        pending = [event]
-        until pending.empty?
-          item = pending.pop
-          next if visited.key?(item)
-          visited[item] = true
-          case item
-          when OpenAI::Internal::Type::BaseModel
-            raise ArgumentError if json_only
-            validate_model_constants!(item)
-            pending << item.to_h
-          when Hash
-            names = {}
-            item.each do |key, value|
-              raise ArgumentError unless key.is_a?(String) || key.is_a?(Symbol)
-              name = key.to_s
-              raise ArgumentError if names.key?(name)
-              names[name] = true
-              pending << value
-            end
-
-          when Array
-            pending.concat(item)
-          when NilClass, TrueClass, FalseClass, String, Integer, Float, Symbol
-            next
-          else
-            raise ArgumentError if json_only
-          end
-        end
-      end
-
-      private def validate_model_constants!(model)
-        model.to_h.each do |name, actual|
-          key = name.is_a?(String) ? name.to_sym : name
-          field = model.class.known_fields[key]
-          next unless field
-          const = field.fetch(:const)
-          next if const == OpenAI::Internal::OMIT
-          if const.is_a?(Symbol)
-            raise ArgumentError unless (actual.is_a?(String) || actual.is_a?(Symbol)) && actual.to_s == const.to_s
-          elsif actual != const
-            raise ArgumentError
-          end
-        end
-      end
+      private :parse_event
 
-      private def parse_event(data)
-        parsed = JSON.parse(data, symbolize_names: true, max_nesting: false)
-        type = event_type(parsed, message: "Realtime Translation server event must be an object with a string type")
-        model = @server_event_types[type.to_s]
-        unless model
-          return OpenAI::Realtime::UnknownTranslationServerEvent.new(data: parsed)
-        end
+      private def coerce_client_event(payload) = coerce_event(@client_event, payload, outbound: true)
 
-        # The converter copies unknown wire fields after known ones. A wire
-        # key spelled like a renamed Ruby field must not overwrite typed data.
-        model.fields.each do |name, field|
-          raise ArgumentError if name != field.fetch(:api_name) && parsed.key?(name)
-        end
+      private def coerce(type, value) = coerce_event(type, value)
 
-        coerce_event(OpenAI::Realtime::RealtimeTranslationServerEvent, parsed)
-      rescue StandardError, SystemStackError
-        raise OpenAI::Errors::TranslationProtocolError.new, cause: nil
-      end
+      private def client_event_error_message = "Invalid Realtime Translation client event."
 
-      private def coerce_event(union, payload, outbound: false)
-        state = OpenAI::Internal::Type::Converter.new_coerce_state(request_only: outbound)
-        event = OpenAI::Internal::Type::Converter.coerce(union, payload, state: state)
-        raise ArgumentError if state[:error] || !state.fetch(:exactness).fetch(:no).zero?
-        ancestors = {}.compare_by_identity
-        pending = [[event, false]]
-        until pending.empty?
-          value, exiting = pending.pop
-          if exiting
-            ancestors.delete(value)
-            next
-          end
+      private def unknown_server_event(payload) = OpenAI::Realtime::UnknownTranslationServerEvent.new(data: payload)
 
-          children = case value
-          when OpenAI::Internal::Type::BaseModel
-            data = value.to_h
-            validate_model_constants!(value)
-            value.class.fields.each do |name, field|
-              const = field.fetch(:const)
-              if field.fetch(:required) &&
-                  field.fetch(:mode) != (outbound ? :coerce : :dump) &&
-                  (!outbound || const == OpenAI::Internal::OMIT) &&
-                  !data.key?(name)
-                raise ArgumentError
-              end
-            end
-
-            data.values
-          when Hash
-            value.values
-          when Array
-            value
-          else
-            next
-          end
-
-          raise ArgumentError if ancestors.key?(value)
-          ancestors[value] = true
-          pending << [value, true]
-          children.each { |child| pending << [child, false] }
-        end
-
-        event
-      end
+      private def protocol_error = OpenAI::Errors::TranslationProtocolError.new
 
       private def transport_error = OpenAI::Errors::TranslationConnectionError.new(url: @url)
       private def failed_read_message = "Cannot read from a failed Realtime Translation WebSocket."

data/lib/openai/helpers/realtime/unknown_server_event.rb

@@ -4,6 +4,8 @@ module OpenAI
   module Realtime
     # A valid JSON event whose discriminator is newer than this SDK version.
     class UnknownServerEvent
+      include OpenAI::WebSocket::Protocol
+
       # @return [Symbol]
       attr_reader :type
 
@@ -25,20 +27,11 @@ module OpenAI
       # @return [Hash{Symbol=>Object}]
       def to_h = @data
 
-      private def freeze_json(value)
-        case value
-        when Hash
-          value.each do |key, item|
-            freeze_json(key)
-            freeze_json(item)
-          end
+      # Remote values, including the discriminator, require explicit access.
+      def inspect = "#<#{self.class}>"
 
-        when Array
-          value.each { |item| freeze_json(item) }
-        end
+      alias to_s inspect
 
-        value.freeze
-      end
     end
   end
 end

data/lib/openai/helpers/responses_websocket/connection.rb

@@ -51,7 +51,13 @@ module OpenAI
         assert_owner!
         raise connection_error("Cannot send on a closed Responses WebSocket.") if poisoned? || closed?
 
-        write_encoded(JSON.generate(encode_client_event(event)))
+        encoded = begin
+          generate_json(encode_client_event(event))
+        rescue SystemStackError
+          raise OpenAI::Errors::ResponsesClientEventError.new, cause: nil
+        end
+
+        write_encoded(encoded)
       rescue OpenAI::Errors::ResponsesConnectionError,
         OpenAI::Errors::ResponsesClientEventError,
         OpenAI::Errors::ResponsesSendError
@@ -107,21 +113,22 @@ module OpenAI
       def closed? = @state == :closed || super
 
       private def parse_event(data)
-        parsed = JSON.parse(data, symbolize_names: true)
+        parsed = parse_json(data)
         type = event_type(parsed, message: "Responses server event must be a JSON object")
         unless @server_event_names.key?(type.to_s)
           return OpenAI::Responses::UnknownServerEvent.new(data: parsed)
         end
 
         state = OpenAI::Internal::Type::Converter.new_coerce_state
-        OpenAI::Internal::Type::Converter.coerce(
+        event = OpenAI::Internal::Type::Converter.coerce(
           OpenAI::Responses::ResponsesServerEvent,
           parsed,
           state: state
         )
+        validate_wire_field_names!(event, parsed)
       rescue OpenAI::Errors::ResponsesProtocolError
         raise
-      rescue StandardError
+      rescue StandardError, SystemStackError
         raise OpenAI::Errors::ResponsesProtocolError.new, cause: nil
       end
 
@@ -209,34 +216,33 @@ module OpenAI
         raise connection_error("Responses WebSocket connections are single-owner.")
       end
 
-      private def validate_event_tree!(value, active = {}.compare_by_identity)
-        case value
-        when OpenAI::Internal::Type::BaseModel
-          guard_cycle!(value, active)
-          begin
-            data = value.to_h
-            reject_duplicate_serialized_model_keys!(value.class, data)
-            validate_event_tree!(data, active)
-          ensure
+      private def validate_event_tree!(value)
+        active = {}.compare_by_identity
+        pending = [[value, false]]
+        until pending.empty?
+          value, exiting = pending.pop
+          if exiting
             active.delete(value)
+            next
           end
 
-        when Hash
-          guard_cycle!(value, active)
-          reject_duplicate_semantic_keys!(value)
-          begin
-            value.each_value { |item| validate_event_tree!(item, active) }
-          ensure
-            active.delete(value)
+          children = case value
+          when OpenAI::Internal::Type::BaseModel
+            data = value.to_h
+            reject_duplicate_serialized_model_keys!(value.class, data)
+            [data]
+          when Hash
+            reject_duplicate_semantic_keys!(value)
+            value.values
+          when Array
+            value
+          else
+            next
           end
 
-        when Array
           guard_cycle!(value, active)
-          begin
-            value.each { |item| validate_event_tree!(item, active) }
-          ensure
-            active.delete(value)
-          end
+          pending << [value, true]
+          children.reverse_each { |child| pending << [child, false] }
         end
 
         nil
@@ -272,18 +278,33 @@ module OpenAI
       end
 
       private def normalize_event_keys(value)
-        case value
-        when Hash
-          value.to_h do |key, item|
+        return value unless value.is_a?(Hash) || value.is_a?(Array)
+
+        result = value.is_a?(Hash) ? {} : []
+        copies = {}.compare_by_identity
+        copies[value] = result
+        pending = [[value, result]]
+        until pending.empty?
+          source, destination = pending.pop
+          entries = source.is_a?(Hash) ? source.each_pair : source.each_with_index.lazy.map { |item, index|
+            [index, item]
+          }
+          entries.each do |key, item|
+            if item.is_a?(Hash) || item.is_a?(Array)
+              unless copies.key?(item)
+                copies[item] = item.is_a?(Hash) ? {} : []
+                pending << [item, copies.fetch(item)]
+              end
+
+              item = copies.fetch(item)
+            end
+
             normalized_key = key.is_a?(String) ? key.to_sym : key
-            [normalized_key, normalize_event_keys(item)]
+            destination[normalized_key] = item
           end
-
-        when Array
-          value.map { |item| normalize_event_keys(item) }
-        else
-          value
         end
+
+        result
       end
 
       private def connection_error(message)

data/lib/openai/helpers/responses_websocket/unknown_server_event.rb

@@ -4,6 +4,8 @@ module OpenAI
   module Responses
     # A valid JSON event whose discriminator is newer than this SDK version.
     class UnknownServerEvent
+      include OpenAI::WebSocket::Protocol
+
       # @return [Symbol]
       attr_reader :type
 
@@ -35,20 +37,6 @@ module OpenAI
 
       alias to_s inspect
 
-      private def freeze_json(value)
-        case value
-        when Hash
-          value.each do |key, item|
-            freeze_json(key)
-            freeze_json(item)
-          end
-
-        when Array
-          value.each { |item| freeze_json(item) }
-        end
-
-        value.freeze
-      end
     end
   end
 end

data/lib/openai/helpers/websocket/async_websocket_transport.rb

@@ -171,7 +171,9 @@ module OpenAI
           @connection.read
         rescue StandardError => e
           error = @error_factory.call(url: @url, cause: e)
-          raise error, cause: error.cause
+          # The factory retains explicit diagnostics; do not render them as a
+          # native exception chain, which can include payloads or credentials.
+          raise error, cause: nil
         end
 
         def write(message)
@@ -179,14 +181,14 @@ module OpenAI
           @connection.flush
         rescue StandardError => e
           error = @error_factory.call(url: @url, cause: e)
-          raise error, cause: error.cause
+          raise error, cause: nil
         end
 
         def close(code: 1000, reason: "")
           @connection.close(code, reason)
         rescue StandardError => e
           error = @error_factory.call(url: @url, cause: e)
-          raise error, cause: error.cause
+          raise error, cause: nil
         end
 
         # @api private
@@ -197,7 +199,7 @@ module OpenAI
           @aborted = true
         rescue StandardError => e
           error = @error_factory.call(url: @url, cause: e)
-          raise error, cause: error.cause
+          raise error, cause: nil
         end
 
         # @api private
@@ -302,7 +304,7 @@ module OpenAI
         raise if e.equal?(block_error)
 
         error = @error_factory.call(url: url, cause: e, http_status: handshake_status(e))
-        raise error, cause: error.cause
+        raise error, cause: nil
       end
 
       private def negotiation_options(_endpoint_options) = {}
@@ -373,7 +375,7 @@ module OpenAI
           "#{@product_name} WebSockets require the `async-websocket` gem. " \
             "Add `gem \"async-websocket\"` to your Gemfile."
         error = @error_factory.call(url: url, message: message, cause: e)
-        raise error, cause: error.cause
+        raise error, cause: nil
       end
 
       private def authority(url, include_default_port: false)

data/lib/openai/helpers/websocket/client_request.rb

@@ -140,7 +140,7 @@ module OpenAI
         [request, deadline]
       rescue Timeout::Error => e
         error = timeout_error.call(error_url, e)
-        raise error, cause: error.cause
+        raise error, cause: nil
       end
 
       private def with_shared_websocket_base_url(request, path:, base_url:)

data/lib/openai/helpers/websocket/connection.rb

@@ -28,20 +28,13 @@ module OpenAI
       end
 
       private def write_text(text)
-        complete = false
         super
-        complete = true
-        nil
       rescue StandardError
         raise transport_error, cause: nil
-      ensure
-        # Also retire a possibly buffered write when cancellation bypasses
-        # StandardError, before another sender or normal cleanup can flush it.
-        @poisoned = true unless complete
       end
 
       private def read_raw_message
-        raise connection_error(failed_read_message) if @poisoned
+        raise connection_error(failed_read_message), cause: nil if @poisoned
         return nil if @closed
         text = super
         @closed = text.nil?
@@ -73,6 +66,7 @@ module OpenAI
       def initialize(socket:, url:)
         @socket = socket
         @url = url
+        @poisoned = false
       end
 
       # Yield server events until the remote peer closes the connection.
@@ -100,6 +94,8 @@ module OpenAI
       def receive_raw = read_raw_message
 
       private def read_raw_message
+        raise connection_error("Cannot read from a failed WebSocket."), cause: nil if @poisoned
+
         message = @socket.read
         message&.to_str
       end
@@ -108,7 +104,7 @@ module OpenAI
       #
       # @api private
       def send_raw(data)
-        raise connection_error(closed_send_message) if closed?
+        raise connection_error(closed_send_message), cause: nil if closed?
 
         text = data.dup
         text.force_encoding(Encoding::UTF_8) if text.encoding == Encoding::BINARY
@@ -120,6 +116,7 @@ module OpenAI
 
       # Close the connection.
       def close(code: 1000, reason: "")
+        return abort if @poisoned
         return if socket_closed?
 
         @socket.close(code: code, reason: reason)
@@ -137,7 +134,7 @@ module OpenAI
       end
 
       # @return [Boolean]
-      def closed? = socket_closed?
+      def closed? = @poisoned || socket_closed?
 
       private def parse_event(_data)
         raise NotImplementedError
@@ -154,8 +151,22 @@ module OpenAI
       private def socket_closed? = @socket.closed?
 
       private def write_text(text)
+        complete = false
         @socket.write(text)
+        complete = true
         nil
+      ensure
+        unless complete
+          # Retire the physical socket immediately: an already-running reader
+          # can otherwise flush buffered application bytes while replying to close.
+          @poisoned = true
+          begin
+            @socket.abort
+          rescue StandardError
+            # Preserve the original write failure or cancellation.
+            nil
+          end
+        end
       end
     end
   end

data/lib/openai/helpers/websocket/connection_manager.rb

@@ -73,7 +73,8 @@ module OpenAI
 
         rescue StandardError => error
           raise if @transport_error_factory.nil?
-          raise block_error, cause: block_error.cause if block_error
+          # Preserve the native chain, not an SDK accessor's explicit diagnostics.
+          raise block_error, cause: Exception.instance_method(:cause).bind_call(block_error) if block_error
           raise @transport_error_factory.call(url: request.fetch(:url), error: error), cause: nil
         end
       end