openai 0.84.0 → 0.86.0

data/lib/openai/helpers/structured_output/response_parser.rb

@@ -85,7 +85,7 @@ module OpenAI
           in {
               text: {
                   format: {
-                      type: :json_schema,
+                      type: :json_schema | "json_schema",
                       schema: OpenAI::StructuredOutput::JsonSchemaConverter => model
                     }
                 }
@@ -108,7 +108,7 @@ module OpenAI
                   name: name,
                   parameters: tool.to_json_schema
                 }
-              in {type: :function, parameters: OpenAI::StructuredOutput::JsonSchemaConverter => params}
+              in {type: :function | "function", parameters: OpenAI::StructuredOutput::JsonSchemaConverter => params}
                 func = tool.fetch(:function, tool)
                 name = func[:name] ||= params.name.split("::").last
                 tool_models.store(name, params)
@@ -139,6 +139,129 @@ module OpenAI
 
           [model, tool_models]
         end
+
+        # Extracts retrieval-local structured-output hints without mutating caller-owned values.
+        #
+        # @api private
+        #
+        # @param parsed [Hash] Dumped retrieval parameters containing local text/tool hints
+        # @return [Array<(JsonSchemaConverter|nil, Hash)>] Text model and named tool models
+        def self.get_retrieval_models(parsed)
+          get_models(duplicate_retrieval_params(parsed.slice(:text, :tools)))
+        end
+
+        # Parses retrieval output only when status and payload shape indicate it is complete.
+        #
+        # @api private
+        #
+        # @param raw [Hash] The raw retrieved response hash that will be mutated with parsed data
+        # @param model [JsonSchemaConverter, nil] The converter for structured text output
+        # @param tool_models [Hash<String, JsonSchemaConverter>] Tool names and their converters
+        # @return [Hash] The same response with typed values in its :parsed fields when ready
+        def self.parse_retrieved!(raw, model, tool_models)
+          staged = {}.compare_by_identity
+          return raw unless retrieval_complete?(raw, model, tool_models, staged)
+
+          parse!(raw.merge(output: parsable_output(raw, staged)), model, tool_models)
+          staged.each_value do |target, converter, parsed|
+            target.store(:parsed, OpenAI::Internal::Type::Converter.coerce(converter, parsed))
+          end
+
+          raw
+        end
+
+        def self.retrieval_complete?(raw, model, tool_models, staged)
+          return false unless [nil, "completed"].include?(raw[:status])
+
+          raw[:output].to_a.none? do |output|
+            case output[:type]
+            when "message"
+              model && unfinished_message?(output, model, staged, response_status: raw[:status])
+            when "function_call"
+              unfinished_function_call?(output, tool_models, staged, response_status: raw[:status])
+            else
+              false
+            end
+          end
+        end
+
+        def self.unfinished_message?(output, model, staged, response_status:)
+          return true if pending_status?(output[:status])
+          return false unless response_status.nil? && output[:status].nil?
+
+          output[:content].to_a.any? do |content|
+            next false unless content[:type] == "output_text"
+            next true unless content.key?(:text)
+
+            ready, parsed = prepare_value(content[:text])
+            staged.store(content, [content, model, parsed]) if ready
+            !ready
+          end
+        end
+
+        def self.unfinished_function_call?(output, tool_models, staged, response_status:)
+          return false if tool_models.empty?
+          return false unless output.key?(:name)
+          return false unless tool_models.key?(output[:name])
+          return true if pending_status?(output[:status])
+          return false unless response_status.nil? && output[:status].nil?
+          return true unless output.key?(:arguments)
+
+          model = tool_models.fetch(output[:name])
+          ready, parsed = prepare_value(output[:arguments])
+          staged.store(output, [output, model, parsed]) if ready
+          !ready
+        end
+
+        def self.pending_status?(status)
+          ["queued", "in_progress", "incomplete"].include?(status)
+        end
+
+        def self.prepare_value(value)
+          [true, JSON.parse(value, symbolize_names: true)]
+        rescue JSON::ParserError, TypeError
+          [false, nil]
+        end
+
+        def self.parsable_output(raw, staged)
+          raw[:output].to_a.filter_map do |output|
+            next if output[:type] == "function_call" && (!output.key?(:name) || staged.key?(output))
+            next output unless output[:type] == "message"
+
+            content = output[:content].to_a.reject { |item| staged.key?(item) }
+            output.merge(content: content)
+          end
+        end
+
+        def self.duplicate_retrieval_params(value)
+          case value
+          when Array
+            value.map { |item| duplicate_retrieval_params(item) }
+          when Hash
+            value.to_h do |key, item|
+              normalized_key = key.is_a?(String) ? key.to_sym : key
+              normalized_key = :format if normalized_key == :format_
+              normalized_item = duplicate_retrieval_params(item)
+              if normalized_key == :type && ["function", "json_schema"].include?(normalized_item)
+                normalized_item = normalized_item.to_sym
+              end
+
+              [normalized_key, normalized_item]
+            end
+          else
+            value
+          end
+        end
+
+        private_class_method(
+          :duplicate_retrieval_params,
+          :parsable_output,
+          :pending_status?,
+          :prepare_value,
+          :retrieval_complete?,
+          :unfinished_function_call?,
+          :unfinished_message?
+        )
       end
     end
   end

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

@@ -0,0 +1,422 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module WebSocket
+    # Product-neutral transport backed by the optional async-websocket gem.
+    #
+    # @api private
+    class AsyncWebSocketTransport
+      REDACTED_HEADER_VALUE = "[REDACTED]"
+      private_constant :REDACTED_HEADER_VALUE
+
+      # Preserve real header fields for the wire while presenting a safe snapshot to
+      # Protocol::HTTP1 tracing, which calls #to_h before writing the request.
+      class TraceSafeHeaderFields
+        include Enumerable
+
+        def initialize(fields)
+          @fields = fields.to_a.freeze
+        end
+
+        def each(&block) = @fields.each(&block)
+
+        def to_h
+          @fields.to_h do |name, value|
+            safe_value = if OpenAI::Internal::Logging.sensitive_header?(name)
+              REDACTED_HEADER_VALUE
+            else
+              value
+            end
+
+            [name, safe_value]
+          end
+        end
+      end
+
+      private_constant :TraceSafeHeaderFields
+
+      module TraceSafeHeaders
+        def header(&block)
+          return super(&block) if block
+
+          TraceSafeHeaderFields.new(super)
+        end
+      end
+
+      private_constant :TraceSafeHeaders
+
+      # HTTP/1 tracing observes the request target passed to #write_request.
+      # Keep that target redacted while restoring the real call ID only at the
+      # private connection's first serialized request-line boundary.
+      class TraceSafeRequestStream
+        def initialize(stream, trace_request_line:, wire_request_line:)
+          @stream = stream
+          @trace_request_line = trace_request_line
+          @wire_request_line = wire_request_line
+          @first_write = true
+        end
+
+        def write(data)
+          if @first_write
+            @first_write = false
+            unless data == @trace_request_line
+              raise IOError, "Unexpected WebSocket request-line serialization."
+            end
+
+            data = @wire_request_line
+          end
+
+          @stream.write(data)
+        end
+      end
+
+      private_constant :TraceSafeRequestStream
+
+      module TraceSafeRequestWriter
+        def write_request(authority, method, target, version, headers)
+          return super unless @sensitive_query_parameter
+
+          trace_target = target.gsub(/([?&])([^&=]+)(?:=[^&]*)?/) do |parameter|
+            separator = Regexp.last_match(1)
+            name = Regexp.last_match(2)
+            if URI.decode_www_form_component(name) == @sensitive_query_parameter
+              "#{separator}#{name}=[REDACTED]"
+            else
+              parameter
+            end
+          end
+
+          original_stream = @stream
+          @stream = TraceSafeRequestStream.new(
+            original_stream,
+            trace_request_line: "#{method} #{trace_target} #{version}\r\n",
+            wire_request_line: "#{method} #{target} #{version}\r\n"
+          )
+
+          super(authority, method, trace_target, version, headers)
+        ensure
+          @stream = original_stream
+        end
+      end
+
+      private_constant :TraceSafeRequestWriter
+
+      class TraceSafeProtocol
+        def initialize(protocol, sensitive_query_parameter:)
+          @protocol = protocol
+          @sensitive_query_parameter = sensitive_query_parameter
+        end
+
+        def client(peer, **options)
+          @protocol.client(peer, **options).tap do |client|
+            client.extend(TraceSafeRequestWriter)
+            client.instance_variable_set(:@sensitive_query_parameter, @sensitive_query_parameter)
+          end
+        end
+
+        def to_s = @protocol.to_s
+      end
+
+      private_constant :TraceSafeProtocol
+
+      # Async's ordinary framer close flushes buffered output. Exceptional cleanup
+      # must instead close the raw socket first, then release the acquired pool slot.
+      module AbortableFramer
+        def abort
+          stream = @stream
+          pool = @pool
+          connection = @connection
+          @pool = nil
+          @connection = nil
+
+          begin
+            io = stream.to_io
+            io.close unless io.closed?
+          ensure
+            pool&.release(connection)
+          end
+        end
+      end
+
+      private_constant :AbortableFramer
+
+      # Configure the native TLS context used by secure WebSockets.
+      # Peer and hostname verification and HTTP/1.1 ALPN remain SDK-owned.
+      def initialize(
+        product_name:,
+        error_class:,
+        error_factory:,
+        dependency_message: nil,
+        sensitive_query_parameter: nil,
+        &tls_configurator
+      )
+        @product_name = product_name
+        @error_class = error_class
+        @error_factory = error_factory
+        @dependency_message = dependency_message
+        @sensitive_query_parameter = sensitive_query_parameter
+        @tls_configurator = tls_configurator
+      end
+
+      class Socket
+        # @api private
+        def initialize(connection, url:, error_factory:)
+          @connection = connection
+          @url = url
+          @error_factory = error_factory
+          @aborted = false
+        end
+
+        def read
+          @connection.read
+        rescue StandardError => e
+          error = @error_factory.call(url: @url, cause: e)
+          raise error, cause: error.cause
+        end
+
+        def write(message)
+          @connection.write(message)
+          @connection.flush
+        rescue StandardError => e
+          error = @error_factory.call(url: @url, cause: e)
+          raise error, cause: error.cause
+        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
+        end
+
+        # @api private
+        def abort
+          framer = @connection.framer
+          framer.extend(AbortableFramer)
+          framer.abort
+          @aborted = true
+        rescue StandardError => e
+          error = @error_factory.call(url: @url, cause: e)
+          raise error, cause: error.cause
+        end
+
+        # @api private
+        def aborted? = @aborted
+
+        def closed? = @aborted || @connection.closed?
+      end
+
+      def open(url:, headers:, timeout:, **endpoint_options)
+        load_dependencies(url)
+
+        # Proxy credentials belong only on the CONNECT request assembled from
+        # proxy configuration. Never forward a caller-supplied value to the
+        # origin handshake.
+        headers = headers.reject do |name, _value|
+          name.to_s.casecmp?("proxy-authorization")
+        end
+
+        # Classic WebSocket negotiation uses HTTP/1.1. Pinning ALPN also avoids an
+        # HTTP/2 selection on servers that advertise both protocols.
+        options = {
+          alpn_protocols: ::Async::HTTP::Protocol::HTTP11.names,
+          **endpoint_options
+        }
+        if url.scheme == "wss" || @tls_configurator
+          options[:ssl_context] = build_tls_context(url)
+        end
+
+        sideband = sensitive_query?(url)
+        endpoint_url = url.dup
+        endpoint_url.query = nil if sideband
+
+        endpoint = ::Async::HTTP::Endpoint.parse(
+          endpoint_url.to_s,
+          **options
+        )
+        request_target = endpoint.path
+        request_target = "#{request_target}?#{url.query}" if sideband
+        proxy_client = nil
+        if (proxy = proxy_uri(url))
+          proxy_endpoint = ::Async::HTTP::Endpoint.parse(proxy_url(proxy).to_s)
+          proxy_client = ::Async::HTTP::Client.open(proxy_endpoint)
+          tunnel = ::Async::HTTP::Proxy.new(
+            proxy_client,
+            authority(url, include_default_port: true),
+            trace_safe_headers(proxy_headers(proxy))
+          )
+          endpoint = tunnel.wrap_endpoint(endpoint)
+        end
+
+        block_error = nil
+        # Keep the request timeout scoped to WebSocket negotiation. Endpoint timeouts
+        # remain installed on the socket and would otherwise terminate healthy idle
+        # sessions after the ordinary HTTP request timeout.
+        ::Kernel.Sync() do
+          client_options = if sideband
+            {
+              protocol: TraceSafeProtocol.new(
+                endpoint.protocol,
+                sensitive_query_parameter: @sensitive_query_parameter
+              )
+            }
+          else
+            {}
+          end
+
+          client = nil
+          connection = nil
+          socket = nil
+          begin
+            client = ::Async::WebSocket::Client.open(endpoint, **client_options)
+            connection = negotiate(
+              client,
+              endpoint,
+              request_target: request_target,
+              headers: headers,
+              timeout: timeout
+            )
+            socket = build_socket(connection, url: url)
+            begin
+              yield(socket)
+            rescue StandardError => e
+              block_error = e
+              raise
+            end
+
+          ensure
+            close_resources(
+              connection,
+              client,
+              proxy_client,
+              connection_aborted: socket&.aborted?,
+              pending_error: $ERROR_INFO
+            )
+          end
+        end
+
+      rescue StandardError => e
+        raise if @error_class === e
+        raise if e.equal?(block_error)
+
+        error = @error_factory.call(url: url, cause: e, http_status: handshake_status(e))
+        raise error, cause: error.cause
+      end
+
+      private def negotiate(client, endpoint, request_target:, headers:, timeout:)
+        safe_headers = trace_safe_headers(headers)
+        operation = lambda do
+          client.connect(authority(endpoint.url), request_target, headers: safe_headers)
+        end
+
+        return operation.call if timeout.nil?
+
+        ::Async::Task.current.with_timeout(timeout, &operation)
+      end
+
+      private def build_socket(connection, url:)
+        Socket.new(connection, url: url, error_factory: @error_factory)
+      end
+
+      private def sensitive_query?(url)
+        return false unless @sensitive_query_parameter && url.query
+
+        URI.decode_www_form(url.query).any? { |name, _value| name == @sensitive_query_parameter }
+      end
+
+      private def build_tls_context(url)
+        unless url.scheme == "wss"
+          raise ArgumentError, "TLS configuration requires a wss:// #{@product_name} endpoint"
+        end
+
+        context = OpenSSL::SSL::SSLContext.new
+        @tls_configurator&.call(context)
+        if context.verify_callback
+          raise ArgumentError, "#{@product_name} WebSocket TLS configuration cannot set verify_callback"
+        end
+
+        context.set_params(verify_mode: OpenSSL::SSL::VERIFY_PEER)
+        context.verify_hostname = true
+        context.alpn_protocols = ::Async::HTTP::Protocol::HTTP11.names
+        context
+      end
+
+      private def close_resources(connection, client, proxy_client, connection_aborted:, pending_error:)
+        cleanup_error = nil
+        resources = [client, proxy_client]
+        resources.unshift(connection) unless connection_aborted
+        resources.compact.each do |resource|
+          resource.close
+        rescue StandardError => e
+          cleanup_error ||= e
+        end
+
+        raise cleanup_error if pending_error.nil? && cleanup_error
+      end
+
+      private def load_dependencies(url)
+        require("async/websocket/client")
+        require("async/http/endpoint")
+        require("async/http/proxy")
+
+      rescue LoadError => e
+        message = @dependency_message ||
+          "#{@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
+      end
+
+      private def authority(url, include_default_port: false)
+        host = url.hostname
+        host = "[#{host}]" if host.include?(":")
+        default_port = %w[https wss].include?(url.scheme) ? 443 : 80
+        return host if !include_default_port && url.port == default_port
+
+        "#{host}:#{url.port}"
+      end
+
+      private def proxy_uri(url)
+        policy_url = url.dup
+        policy_url.scheme = {"ws" => "http", "wss" => "https"}.fetch(url.scheme, url.scheme)
+        policy_url.find_proxy
+      end
+
+      private def proxy_url(proxy)
+        unless %w[http https].include?(proxy.scheme) && proxy.hostname
+          raise ArgumentError, "#{@product_name} WebSocket proxy must be an absolute HTTP or HTTPS URL"
+        end
+
+        proxy.dup.tap do |url|
+          url.user = nil
+          url.password = nil
+        end
+      end
+
+      private def proxy_headers(proxy)
+        return {} unless proxy.user
+
+        user = URI::RFC2396_PARSER.unescape(proxy.user)
+        password = URI::RFC2396_PARSER.unescape(proxy.password.to_s)
+        {"proxy-authorization" => "Basic #{["#{user}:#{password}"].pack("m0")}"}
+      end
+
+      private def trace_safe_headers(headers)
+        fields = ::Protocol::HTTP::Headers[headers].to_a
+        trace_safe_headers_class.new(fields)
+      end
+
+      private def trace_safe_headers_class
+        @trace_safe_headers_class ||= Class.new(::Protocol::HTTP::Headers) do
+          include(TraceSafeHeaders)
+        end
+      end
+
+      private def handshake_status(error)
+        return unless error.is_a?(::Async::WebSocket::ConnectionError)
+
+        error.response.status
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module WebSocket
+    # Shared handshake request helpers used by product WebSocket facades.
+    #
+    # @api private
+    module ClientRequest
+      private def with_websocket_connection_retry(error_class:, build:)
+        request, deadline = build.call(nil)
+        handshake_completed = false
+        mark_handshake_completed = -> { handshake_completed = true }
+        yield(request, mark_handshake_completed)
+      rescue error_class => e
+        raise if handshake_completed
+        raise unless e.http_status == 401 && @workload_identity_auth
+
+        @workload_identity_auth.invalidate_token
+        refreshed, = build.call(deadline)
+        yield(refreshed, mark_handshake_completed)
+      end
+
+      private def shared_websocket_request_options(options, extra_query_message:, max_retries_message:)
+        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?)
+          raise ArgumentError, extra_query_message
+        end
+
+        max_retries = opts[:max_retries]
+        raise ArgumentError, max_retries_message unless max_retries.nil? || max_retries == 0
+
+        opts
+      end
+
+      private def parse_shared_websocket_base_url(value, invalid_message:, malformed_message:, preserve_cause:)
+        return if value.nil?
+
+        uri = URI(value.to_s)
+        valid_scheme = %w[http https ws wss].include?(uri.scheme)
+        ambiguous = uri.userinfo || uri.query || uri.fragment
+        raise ArgumentError, invalid_message unless uri.absolute? && uri.host && valid_scheme && !ambiguous
+
+        uri
+      rescue URI::Error => e
+        raise ArgumentError, malformed_message, cause: preserve_cause ? e : nil
+      end
+
+      private def shared_websocket_url(url)
+        url = url.dup
+        url.scheme = {"http" => "ws", "https" => "wss"}.fetch(url.scheme, url.scheme)
+        url
+      end
+
+      private def shared_websocket_headers(headers)
+        headers.except("accept", "content-type").reject do |name, _value|
+          name.to_s.casecmp?("proxy-authorization")
+        end
+      end
+
+      private def build_shared_websocket_connection_request(
+        path:,
+        query:,
+        websocket_base_url:,
+        options:,
+        deadline: nil,
+        validate:,
+        invalid_base_url_message:,
+        malformed_base_url_message:,
+        preserve_base_url_cause:,
+        extra_query_message:,
+        max_retries_message:,
+        timeout_error:
+      )
+        validate.call(websocket_base_url)
+        websocket_uri = parse_shared_websocket_base_url(
+          websocket_base_url,
+          invalid_message: invalid_base_url_message,
+          malformed_message: malformed_base_url_message,
+          preserve_cause: preserve_base_url_cause
+        )
+        opts = shared_websocket_request_options(
+          options,
+          extra_query_message: extra_query_message,
+          max_retries_message: max_retries_message
+        )
+
+        request = build_request(
+          {method: :get, path: path, query: query, security: {bearer_auth: true}},
+          opts
+        )
+        error_request = websocket_uri ? with_shared_websocket_base_url(request, path:, base_url: websocket_uri) : request
+        error_url = shared_websocket_url(error_request.fetch(:url))
+
+        if @workload_identity_auth
+          deadline ||= request[:timeout]&.then do |timeout|
+            OpenAI::Internal::Util.monotonic_secs + timeout
+          end
+        end
+
+        placeholder = "Bearer #{OpenAI::Client::WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER}"
+        if @workload_identity_auth && request.fetch(:headers)["authorization"] == placeholder
+          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_shared_websocket_base_url(request, path:, base_url: websocket_uri) if websocket_uri
+        request = request.merge(
+          url: shared_websocket_url(request.fetch(:url)),
+          headers: shared_websocket_headers(request.fetch(:headers))
+        )
+        request = request_with_remaining_timeout(request, deadline) unless deadline.nil?
+        [request, deadline]
+      rescue Timeout::Error => e
+        error = timeout_error.call(error_url, e)
+        raise error, cause: error.cause
+      end
+
+      private def with_shared_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
+    end
+  end
+end