openai 0.85.0 → 0.86.0

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

@@ -5,6 +5,8 @@ module OpenAI
     module Realtime
       # Realtime request integration kept outside the generated client implementation.
       module ClientExtension
+        include OpenAI::WebSocket::ClientRequest
+
         MAX_CALL_CLEANUP_SECONDS = 5.0
         private_constant :MAX_CALL_CLEANUP_SECONDS
 
@@ -140,28 +142,20 @@ module OpenAI
         #
         # @api private
         def with_realtime_connection_request(path:, query:, websocket_base_url: nil, options: nil)
-          request, deadline = build_realtime_connection_request(
-            path: path,
-            query: query,
-            websocket_base_url: websocket_base_url,
-            options: options
-          )
-          handshake_completed = false
-          mark_handshake_completed = -> { handshake_completed = true }
-          yield(request, mark_handshake_completed)
-        rescue OpenAI::Errors::RealtimeConnectionError => e
-          raise if handshake_completed
-          raise unless e.http_status == 401 && @workload_identity_auth
+          build = lambda do |deadline|
+            build_realtime_connection_request(
+              path: path,
+              query: query,
+              websocket_base_url: websocket_base_url,
+              options: options,
+              deadline: deadline
+            )
+          end
 
-          @workload_identity_auth.invalidate_token
-          refreshed, = build_realtime_connection_request(
-            path: path,
-            query: query,
-            websocket_base_url: websocket_base_url,
-            options: options,
-            deadline: deadline
-          )
-          yield(refreshed, mark_handshake_completed)
+          with_websocket_connection_retry(
+            error_class: OpenAI::Errors::RealtimeConnectionError,
+            build: build
+          ) { |request, marker| yield(request, marker) }
         end
 
         private def build_realtime_connection_request(
@@ -171,6 +165,28 @@ module OpenAI
           options:,
           deadline: nil
         )
+          build_shared_websocket_connection_request(
+            path: path,
+            query: query,
+            websocket_base_url: websocket_base_url,
+            options: options,
+            deadline: deadline,
+            validate: -> (value) { validate_realtime_websocket_request!(value) },
+            invalid_base_url_message: "`websocket_base_url` must be an absolute HTTP or WebSocket URL " \
+              "without credentials, query, or fragment",
+            malformed_base_url_message: "`websocket_base_url` is not a valid URL",
+            preserve_base_url_cause: true,
+            extra_query_message: "`request_options[:extra_query]` is not supported for Realtime WebSocket " \
+              "connections; omit it",
+            max_retries_message: "`request_options[:max_retries]` is not supported for Realtime WebSocket " \
+              "connections; use 0 or omit it",
+            timeout_error: lambda do |url, cause|
+              OpenAI::Errors::RealtimeConnectionError.new(url: url, cause: cause)
+            end
+          )
+        end
+
+        private def validate_realtime_websocket_request!(websocket_base_url)
           if x509_identity?(@copy_options.fetch(:workload_identity))
             raise OpenAI::Errors::Error, "X.509 workload identity does not support Realtime WebSocket connections"
           end
@@ -184,106 +200,6 @@ module OpenAI
           if websocket_base_url && @provider_runtime
             raise ArgumentError, "`websocket_base_url` cannot be combined with `provider`"
           end
-
-          websocket_uri = parse_websocket_base_url(websocket_base_url)
-
-          opts = options.to_h.dup
-          OpenAI::RequestOptions.validate!(opts)
-          extra_query = opts.delete(:extra_query)
-          unless extra_query.nil? || (extra_query.respond_to?(:empty?) && extra_query.empty?)
-            message = "`request_options[:extra_query]` is not supported for Realtime WebSocket " \
-              "connections; omit it"
-            raise ArgumentError, message
-          end
-
-          max_retries = opts[:max_retries]
-          unless max_retries.nil? || max_retries == 0
-            message = "`request_options[:max_retries]` is not supported for Realtime WebSocket " \
-              "connections; use 0 or omit it"
-            raise ArgumentError, message
-          end
-
-          request = build_request(
-            {
-              method: :get,
-              path: path,
-              query: query,
-              security: {bearer_auth: true}
-            },
-            opts
-          )
-          error_request = if websocket_uri
-            with_websocket_base_url(request, path: path, base_url: websocket_uri)
-          else
-            request
-          end
-
-          error_url = websocket_url(error_request.fetch(:url))
-
-          if @workload_identity_auth
-            deadline ||= request[:timeout]&.then do |timeout|
-              OpenAI::Internal::Util.monotonic_secs + timeout
-            end
-          end
-
-          workload_identity_header = "Bearer #{OpenAI::Client::WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER}"
-          if @workload_identity_auth && request.fetch(:headers)["authorization"] == workload_identity_header
-            token = @workload_identity_auth.get_token(deadline: deadline)
-            request = request.merge(
-              headers: request.fetch(:headers).merge("authorization" => "Bearer #{token}")
-            )
-          end
-
-          request = prepare_request(request, redirect_count: 0, retry_count: 0)
-          request = with_websocket_base_url(request, path: path, base_url: websocket_uri) if websocket_uri
-
-          url = websocket_url(request.fetch(:url))
-          headers = request.fetch(:headers).except("accept", "content-type").reject do |name, _value|
-            name.to_s.casecmp?("proxy-authorization")
-          end
-
-          request = request.merge(url: url, headers: headers)
-          request = request_with_remaining_timeout(request, deadline) unless deadline.nil?
-          [request, deadline]
-        rescue Timeout::Error => e
-          raise(
-            OpenAI::Errors::RealtimeConnectionError.new(
-              url: error_url,
-              cause: e
-            )
-          )
-        end
-
-        private def with_websocket_base_url(request, path:, base_url:)
-          url = OpenAI::Internal::Util.join_parsed_uri(
-            OpenAI::Internal::Util.parse_uri(base_url.to_s),
-            {path: OpenAI::Internal::Util.interpolate_path(path)}
-          )
-          url.query = request.fetch(:url).query
-          request.merge(url: url)
-        end
-
-        private def parse_websocket_base_url(value)
-          return if value.nil?
-
-          uri = URI(value.to_s)
-          valid_scheme = %w[http https ws wss].include?(uri.scheme)
-          ambiguous_component = uri.userinfo || uri.query || uri.fragment
-          unless uri.absolute? && uri.host && valid_scheme && !ambiguous_component
-            message = "`websocket_base_url` must be an absolute HTTP or WebSocket URL " \
-              "without credentials, query, or fragment"
-            raise ArgumentError, message
-          end
-
-          uri
-        rescue URI::Error => e
-          raise ArgumentError, "`websocket_base_url` is not a valid URL", cause: e
-        end
-
-        private def websocket_url(url)
-          url = url.dup
-          url.scheme = {"http" => "ws", "https" => "wss"}.fetch(url.scheme, url.scheme)
-          url
         end
       end
     end

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

@@ -3,8 +3,8 @@
 module OpenAI
   module Realtime
     # A live, typed Realtime WebSocket connection.
-    class Connection
-      include Enumerable
+    class Connection < OpenAI::WebSocket::Connection
+      include OpenAI::WebSocket::Protocol
 
       # @return [OpenAI::Realtime::ConnectionResources::Session]
       attr_reader :session
@@ -20,8 +20,7 @@ module OpenAI
 
       # @api private
       def initialize(socket:, url:)
-        @socket = socket
-        @url = url
+        super
         @server_event_names = discriminator_values(OpenAI::Realtime::RealtimeServerEvent)
         @client_event_names = discriminator_values(OpenAI::Realtime::RealtimeClientEvent)
         @session = OpenAI::Realtime::ConnectionResources::Session.new(self)
@@ -30,34 +29,6 @@ module OpenAI
         @input_audio_buffer = OpenAI::Realtime::ConnectionResources::InputAudioBuffer.new(self)
       end
 
-      # @return [URI::Generic]
-      attr_reader :url
-
-      # Yield server events until the remote peer closes the connection.
-      def each
-        return enum_for(__method__) unless block_given?
-
-        while (event = receive)
-          yield(event)
-        end
-
-        self
-      end
-
-      # Receive and parse the next server event, or return nil after a clean close.
-      def receive
-        data = receive_raw
-        return nil if data.nil?
-
-        parse_event(data)
-      end
-
-      # Receive the next raw WebSocket message.
-      def receive_raw
-        message = @socket.read
-        message&.to_str
-      end
-
       # Parse raw JSON as a typed server event. Valid events that are newer than this
       # SDK remain observable as {UnknownServerEvent} values.
       def parse_event(data)
@@ -115,65 +86,9 @@ module OpenAI
         raise ArgumentError.new("Invalid Realtime client event."), cause: e
       end
 
-      # Send an already encoded text message.
-      def send_raw(data)
-        if closed?
-          raise(
-            OpenAI::Errors::RealtimeConnectionError.new(
-              url: @url,
-              message: "Cannot send on a closed Realtime WebSocket."
-            )
-          )
-        end
-
-        text = data.dup
-        text.force_encoding(Encoding::UTF_8) if text.encoding == Encoding::BINARY
-        text = text.encode(Encoding::UTF_8) unless text.encoding == Encoding::UTF_8
-        unless text.valid_encoding?
-          raise ArgumentError, "Realtime WebSocket text must contain valid UTF-8"
-        end
-
-        @socket.write(text)
-        nil
-      end
-
-      # Close the connection.
-      def close(code: 1000, reason: "")
-        return if closed?
-
-        @socket.close(code: code, reason: reason)
-        nil
-      end
-
-      # Abort without waiting for the WebSocket close handshake.
-      #
-      # @api private
-      def abort
-        return if closed?
-
-        @socket.abort
-        nil
-      end
-
-      # @return [Boolean]
-      def closed? = @socket.closed?
-
-      private def discriminator_values(union)
-        union.variants.to_h do |variant|
-          value = variant.fields.fetch(:type).fetch(:const)
-          [value.to_s, true]
-        end
-      end
-
       private def event_type(event)
-        unless event.is_a?(Hash)
-          raise ArgumentError, "Realtime server event must be a JSON object"
-        end
-
-        type = event[:type]
-        return type if type.is_a?(String) || type.is_a?(Symbol)
-
-        raise ArgumentError, "Realtime server event type must be a string or symbol"
+        super(event, message: "Realtime server event must be a JSON object") unless event.is_a?(Hash)
+        super(event, message: "Realtime server event type must be a string or symbol")
       end
 
       private def validate_discriminator!(event, allowed, kind:)
@@ -194,6 +109,14 @@ module OpenAI
 
         ArgumentError.new("Realtime event is missing required fields or contains invalid values")
       end
+
+      private def connection_error(message)
+        OpenAI::Errors::RealtimeConnectionError.new(url: @url, message: message)
+      end
+
+      private def closed_send_message = "Cannot send on a closed Realtime WebSocket."
+
+      private def invalid_text_message = "Realtime WebSocket text must contain valid UTF-8"
     end
   end
 end

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

@@ -5,19 +5,7 @@ module OpenAI
     # Internal block-scoped lifecycle manager for Realtime WebSocket connections.
     #
     # @api private
-    class ConnectionManager
-      RESERVED_TRANSPORT_OPTIONS = [
-        :alpn_protocols,
-        :headers,
-        :hostname,
-        :port,
-        :protocol,
-        :scheme,
-        :ssl_context,
-        :timeout,
-        :url
-      ].freeze
-
+    class ConnectionManager < OpenAI::WebSocket::ConnectionManager
       # @api private
       def initialize(
         client:,
@@ -28,79 +16,36 @@ module OpenAI
         transport_options:,
         connection_class: OpenAI::Realtime::Connection
       )
-        @client = client
-        @query = query
+        query = query
           .to_h
           .to_h do |key, value|
             [key.to_s.dup.freeze, value.to_s.dup.freeze]
           end
           .freeze
-        @websocket_base_url = websocket_base_url&.to_s&.dup&.freeze
-        @transport = transport
-        @request_options = request_options
-        @connection_class = connection_class
-        transport_options = transport_options.dup.freeze
-        reserved_options = transport_options.keys.select do |key|
-          (key.is_a?(String) || key.is_a?(Symbol)) && RESERVED_TRANSPORT_OPTIONS.include?(key.to_sym)
-        end
-
-        unless reserved_options.empty?
-          raise(
-            ArgumentError,
-            "`transport_options` cannot include #{reserved_options.map(&:inspect).join(", ")}"
+        base_url = websocket_base_url&.to_s&.dup&.freeze
+        request = lambda do |&request_block|
+          client.with_realtime_connection_request(
+            path: "realtime",
+            query: query,
+            websocket_base_url: base_url,
+            options: request_options,
+            &request_block
           )
         end
 
-        @transport_options = transport_options
-      end
-
-      # Open the WebSocket and yield a typed connection for the lifetime of the block.
-      #
-      # @api private
-      #
-      # @yieldparam connection [OpenAI::Realtime::Connection]
-      # @return [Object]
-      def open
-        raise ArgumentError, "A block is required to open a Realtime WebSocket." unless block_given?
-
-        transport = @transport || OpenAI::Realtime::Transports::AsyncWebSocket.new
-        unless transport.respond_to?(:open)
-          raise ArgumentError, "`transport` must respond to `open`"
-        end
-
-        @client
-          .with_realtime_connection_request(
-            path: "realtime",
-            query: @query,
-            websocket_base_url: @websocket_base_url,
-            options: @request_options
-          ) do |request, mark_handshake_completed|
-            transport
-              .open(
-                url: request.fetch(:url),
-                headers: request.fetch(:headers),
-                timeout: request.fetch(:timeout),
-                **@transport_options
-              ) do |socket|
-                mark_handshake_completed.call
-                connection = @connection_class.new(socket: socket, url: request.fetch(:url))
-                begin
-                  yield(connection)
-                ensure
-                  pending_error = $ERROR_INFO
-                  begin
-                    if pending_error
-                      connection.abort unless connection.closed?
-                    else
-                      connection.close unless connection.closed?
-                    end
-
-                  rescue StandardError
-                    raise if pending_error.nil?
-                  end
-                end
-              end
+        super(
+          transport: transport,
+          transport_options: transport_options,
+          default_transport: -> { OpenAI::Realtime::Transports::AsyncWebSocket.new },
+          connection_class: connection_class,
+          request: request,
+          block_error_message: "A block is required to open a Realtime WebSocket.",
+          abort_after_block: -> (_connection, pending_error) { !pending_error.nil? },
+          transport_error_message: "`transport` must respond to `open`",
+          reserved_options_error_message: lambda do |reserved|
+            "`transport_options` cannot include #{reserved.map(&:inspect).join(", ")}"
           end
+        )
       end
     end
   end

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

@@ -14,7 +14,9 @@ module OpenAI
         private def event_payload(params, *metadata_keys)
           payload = params.to_h.dup
           metadata = metadata_keys.to_h do |key|
-            value = payload.key?(key) ? payload.delete(key) : payload.delete(key.to_s)
+            value = payload.key?(key) ? payload.fetch(key) : payload.fetch(key.to_s, nil)
+            payload.delete(key)
+            payload.delete(key.to_s)
             [key, value]
           end
 

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

@@ -3,32 +3,8 @@
 module OpenAI
   module Errors
     # Raised when a Realtime WebSocket cannot be opened or used.
-    class RealtimeConnectionError < OpenAI::Errors::Error
-      # @return [URI::Generic]
-      attr_reader :url
-
-      # HTTP status returned by a failed WebSocket upgrade, when available.
-      #
-      # @api private
-      #
-      # @return [Integer, nil]
-      attr_reader :http_status
-
-      # @return [Exception, nil]
-      def cause = @cause.nil? ? super : @cause
-
-      # @api private
-      #
-      # @param url [URI::Generic]
-      # @param message [String, nil]
-      # @param cause [Exception, nil]
-      # @param http_status [Integer, nil]
-      def initialize(url:, message: nil, cause: nil, http_status: nil)
-        @url = sanitized_error_url(url)
-        @cause = cause
-        @http_status = http_status
-        super(message || "Realtime WebSocket connection error.")
-      end
+    class RealtimeConnectionError < OpenAI::Errors::WebSocketConnectionError
+      private def default_message = "Realtime WebSocket connection error."
 
       private def sanitized_error_url(url)
         query = url.query
@@ -52,7 +28,7 @@ module OpenAI
     end
 
     # Raised when a Realtime WebSocket message cannot be parsed as a typed event.
-    class RealtimeProtocolError < OpenAI::Errors::Error
+    class RealtimeProtocolError < OpenAI::Errors::WebSocketProtocolError
       # @return [String]
       attr_reader :data