openai 0.80.0 → 0.82.0

data/lib/openai/errors.rb

@@ -11,6 +11,41 @@ module OpenAI
     class InvalidWebhookSignatureError < OpenAI::Errors::Error
     end
 
+    # Raised when a polling helper cannot continue safely.
+    class PollingError < OpenAI::Errors::Error
+    end
+
+    # Raised when a polling helper exceeds its overall timeout.
+    class PollingTimeoutError < OpenAI::Errors::PollingError
+      # The last resource returned by the API before the timeout, or `nil` when
+      # the deadline elapsed before the first response.
+      #
+      # @return [Object, nil]
+      attr_reader :resource
+
+      # The configured overall polling timeout in seconds.
+      #
+      # @return [Float]
+      attr_reader :timeout
+
+      # A human-readable description of the operation being polled.
+      #
+      # @return [String]
+      attr_reader :operation
+
+      # @api private
+      #
+      # @param operation [String]
+      # @param timeout [Float]
+      # @param resource [Object, nil]
+      def initialize(operation:, timeout:, resource:)
+        @operation = operation
+        @timeout = timeout
+        @resource = resource
+        super("Timed out waiting for #{operation} after #{timeout} seconds.")
+      end
+    end
+
     class ConversionError < OpenAI::Errors::Error
       # @return [StandardError, nil]
       def cause = @cause.nil? ? super : @cause
@@ -164,16 +199,15 @@ module OpenAI
       #
       # @return [self]
       def self.for(url:, status:, headers:, body:, request:, response:, message: nil)
-        kwargs =
-          {
-            url: url,
-            status: status,
-            headers: headers,
-            body: body,
-            request: request,
-            response: response,
-            message: message
-          }
+        kwargs = {
+          url: url,
+          status: status,
+          headers: headers,
+          body: body,
+          request: request,
+          response: response,
+          message: message
+        }
 
         case status
         in 400
@@ -223,7 +257,13 @@ module OpenAI
       # @param response [nil]
       # @param message [String, nil]
       def initialize(url:, status:, headers:, body:, request:, response:, message: nil)
-        message ||= OpenAI::Internal::Util.dig(body, :message) { {url: url.to_s, status: status, body: body} }
+        message ||= case OpenAI::Internal::Util.dig(body, :message)
+        in String | Symbol | Numeric | true | false => upstream_message
+          upstream_message
+        else
+          safe_status_message(url: url, status: status, body: body)
+        end
+
         @code = OpenAI::Internal::Type::Converter.coerce(String, OpenAI::Internal::Util.dig(body, :code))
         @param = OpenAI::Internal::Type::Converter.coerce(String, OpenAI::Internal::Util.dig(body, :param))
         @type = OpenAI::Internal::Type::Converter.coerce(String, OpenAI::Internal::Util.dig(body, :type))
@@ -237,6 +277,226 @@ module OpenAI
           message: message&.to_s
         )
       end
+
+      private def safe_status_message(url:, status:, body:)
+        sensitive_description = %r{
+          https?:// |
+          \bdata:[^,]{0,512}, |
+          \b(?:bearer|basic)\s+(?!tokens?\b|credentials?\b|authentication\b)\S |
+          \b(?:(?:access|refresh|id|session)\s+)?(?:tokens?|credentials?)\s+
+              (?!is\b|was\b|invalid\b|expired\b|missing\b|required\b)[a-z0-9._-]{8,} |
+          \b[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}\b |
+          \beyJ[a-z0-9_-]+\.[a-z0-9_-]+\.[a-z0-9_-]+ |
+          \b(?:AKIA|ASIA)[a-z0-9]{16}\b |
+          \b(?:sk|rk|ek)(?:[-_][a-z0-9]{16,}|(?:[-_][a-z0-9]+){2,}) |
+          \b(?:invalid|expired|missing|required|malformed|unsupported|incorrect|unknown|
+              revoked|disabled|empty|too\s+(?:long|short|large|small))\b
+              (?:
+                [\s\S]{0,512}\b(?:private|customer\s+(?:prompt|input|response|output|content|data)|
+                    model\s+(?:response|output))\b |
+                \s*[\r\n\(\[\{<"';,/—–-]+\s*
+                    (?!expected\b|(?:a|an)\s+(?:string|integer|number|boolean|object|array)\b|
+                        maximum\b|max\b|minimum\b|min\b|limit\b|check\b|please\b|add\b|
+                        retry\b|refresh\b|sign\b)\S
+              ) |
+          \b(?:[a-z0-9]+[-_])*
+              (?:api[-_\s]?key|access[-_\s]?token|client[-_\s]?secret|authorization|awsaccesskeyid|
+                  (?:customer|user)[-_\s]?(?:id|identifier)|email|
+                  (?:set[-_\s]?)?cookie|credentials?|assertions?|tokens?|keys?|signature|secret|password|
+                  prompt|input|responses?|outputs?|messages?|content)
+              (?:[-_][a-z0-9]+|\[[a-z0-9_-]*\])*
+              (?:["']?\s*[:=]\s*|\s+(?:is|was)\s+|\s+["'“‘]\s*)
+              (?!
+                (?:invalid|valid|expired|missing|required|malformed|truncated|unsupported|incorrect|unknown|
+                    revoked|disabled|empty|too\s+(?:long|short|large|small)|string|integer|
+                    number|boolean|object|array|null|\d+(?:\s+tokens?)?)\b
+                    (?!\s*[:=]\s*(?!expected\b|string\b|integer\b|number\b|boolean\b)\S)
+              )
+              \S
+        }ix
+        credential_description = %r{
+          \b(?:api[-_\s]?keys?|(?:access|refresh|id|session)[-_\s]?tokens?|tokens?|
+              client[-_\s]?secrets?|private[-_\s]?keys?|secrets?|credentials?|
+              passwords?|authorization|(?:set[-_\s]?)?cookies?|assertions?|signatures?)\b
+        }ix
+        content_description = /\b(?:prompt|input|responses?|outputs?|messages?|content|customer|data)\b/i
+        safe_description = %r{
+          \A(?:
+            [\s'"“”‘’().,:;!?-]+ | \d+ |
+            \b(?:invalid_(?:request|client|grant|scope|token|subject_token|prompt|
+                    image(?:_format|_url|_mode)?|base64_image)|
+                unauthorized_client|unsupported_(?:grant_type|response_type|image_media_type)|
+                access_denied|insufficient_scope|server_error|temporarily_unavailable|
+                rate_limit_exceeded|data_residency_mismatch|bio_policy|vector_store_timeout|
+                image_(?:too_(?:large|small)|parse_error|content_policy_violation|
+                    file_(?:too_large|not_found))|empty_image_file|failed_to_download_image)\b |
+            \b(?:a|an|the|this|your|for|of|to|from|in|on|with|by|and|or|has|have|is|was|were|
+                be|not|no|does|do|could|cannot|must|should|when|it|invalid|expired|missing|
+                required|malformed|unsupported|incorrect|unknown|revoked|disabled|empty|blank|
+                unavailable|too|long|short|large|small|api|key|keys|access|refresh|id|session|
+                bearer|basic|client|secret|secrets|token|tokens|credentials|authentication|
+                authorization|signature|password|assertion|please|sign|again|add|one|account|
+                settings|check|format|operation|configured|configuration|failed|rejected|
+                denied|provided|permissions|expected|string|integer|number|boolean|object|
+                array|null|maximum|max|minimum|min|limit|length|request|requested|provider|
+                input|response|output|message|content|data|url|selected|model|processed|role|
+                user|value|field|header|exist|match|exceeds|exceed|exceeded|context|contains|
+                contain|many|parsed|as|json|truncated|because|valid|but|permission|resource|
+                scopes|scope|nested|oauth|error|explanation|top|level|failure|forged|log|entry|
+                rate|reached|try|later|you|current|quota|plan|billing|details|found|internal|
+                server|service|temporarily|http|status)\b
+          )+\z
+        }ix
+        upstream_message = [
+          OpenAI::Internal::Util.dig(body, [:error, :message]),
+          OpenAI::Internal::Util.dig(body, [:error, :error_description]),
+          OpenAI::Internal::Util.dig(body, :error_description),
+          OpenAI::Internal::Util.dig(body, :error)
+        ].find do |candidate|
+          next false unless candidate.is_a?(String)
+
+          classified_candidate = candidate[...512].encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+          next false if classified_candidate.strip.empty? || classified_candidate.match?(sensitive_description)
+          next false unless classified_candidate.match?(safe_description)
+
+          diagnostic_words = classified_candidate.downcase.scan(/[a-z]+|\d+/)
+          safe_named_code = classified_candidate.match?(/\A[a-z]+(?:_[a-z0-9]+){1,4}\z/i)
+          unless safe_named_code ||
+              classified_candidate.match?(/\d/) ||
+              safe_provider_diagnostic?(diagnostic_words)
+            next false
+          end
+
+          classified_markers = classified_candidate.gsub(/(?<=[a-z0-9])(?=[A-Z])/, " ").tr("_-", "  ")
+          credential = classified_markers.match?(credential_description)
+          content = classified_markers.match?(content_description)
+          if classified_candidate.match?(/\d/)
+            if credential
+              quantity_indexes = diagnostic_words.each_index.select { diagnostic_words[_1].match?(/\A\d+\z/) }
+              quantity_prefix = quantity_indexes.one? ? diagnostic_words[...quantity_indexes.first] : []
+              safe_prefix_words = %w[the your request input output context maximum max minimum min limit length] +
+                %w[contains exceeds exceed exceeded is of too long]
+              only_quantity_tokens = classified_markers.scan(credential_description).all? { _1.match?(/\Atokens?\z/i) }
+              safe_limit = content &&
+                only_quantity_tokens &&
+                quantity_indexes.one? &&
+                diagnostic_words[quantity_indexes.first].length <= 8 &&
+                quantity_prefix.all? { safe_prefix_words.include?(_1) } &&
+                quantity_prefix.any? { %w[request input output context].include?(_1) } &&
+                quantity_prefix.any? do
+                  %w[maximum max minimum min limit length contains exceeds exceed exceeded].include?(_1)
+                end &&
+                [%w[token], %w[tokens], %w[input token], %w[input tokens], %w[output token], %w[output tokens]].include?(
+                  diagnostic_words[(quantity_indexes.first + 1)..]
+                )
+              next false unless safe_limit
+            else
+              status_code = diagnostic_words.last
+              safe_status_code = status_code.length == 3 &&
+                ("100".."599").cover?(status_code) &&
+                [%w[error], %w[status], %w[http status]].include?(diagnostic_words[...-1])
+              next false unless safe_status_code || safe_named_code
+            end
+          end
+
+          true
+        end
+
+        safe_url = OpenAI::Internal::Logging.safe_url(url).sub(/[?#].*/, "")
+        fields = ["status=#{status}", "url=#{safe_url}"]
+        fields << "message=#{bounded_status_field(upstream_message, limit: 512)}" if upstream_message
+
+        fields.join(" ")
+      end
+
+      private def safe_provider_diagnostic?(words)
+        words = words.drop(1) if %w[the your].include?(words.first)
+        safe_templates = [
+          %w[nested provider error],
+          %w[nested provider explanation],
+          %w[nested oauth provider error],
+          %w[oauth provider rejected the request],
+          %w[oauth credentials were rejected],
+          %w[provider error],
+          %w[provider failure],
+          %w[provider rejected the request],
+          %w[top level explanation],
+          %w[rate limit reached please try again later],
+          %w[you exceeded your current quota please check your plan and billing details],
+          %w[requested model was not found],
+          %w[requested model is unavailable],
+          %w[internal server error],
+          %w[service temporarily unavailable],
+          %w[invalid bearer token],
+          %w[invalid access token],
+          %w[invalid token expired],
+          %w[api key missing],
+          %w[basic authentication failed],
+          %w[access token is expired],
+          %w[access token is expired please sign in again],
+          %w[token is invalid],
+          %w[token is invalid or has expired],
+          %w[api key is missing],
+          %w[api key required],
+          %w[api key required for this operation],
+          %w[api key format is invalid],
+          %w[api key authentication failed],
+          %w[api key cannot be empty],
+          %w[api key has expired],
+          %w[api key does not exist],
+          %w[client secret missing],
+          %w[client secret does not match],
+          %w[password too short],
+          %w[password cannot be blank],
+          %w[api key is missing add one to your account settings],
+          %w[api key is valid but does not have permission to access this resource],
+          %w[client secret is invalid],
+          %w[access token does not contain the required scopes],
+          %w[signature is invalid],
+          %w[request input is invalid],
+          %w[input exceeds the maximum context length],
+          %w[request contains too many input tokens],
+          %w[request input is invalid expected a string],
+          %w[input is invalid expected a string],
+          %w[input is required],
+          %w[input is required for this operation],
+          %w[response is malformed],
+          %w[response is malformed and could not be processed],
+          %w[response could not be parsed as json],
+          %w[response is malformed expected an object],
+          %w[output is too long],
+          %w[output is too long for the selected model],
+          %w[output was truncated because it exceeded the maximum token limit],
+          %w[api key is invalid check your credentials],
+          %w[message is required],
+          %w[content is required],
+          %w[data url is invalid],
+          %w[invalid data expected a string],
+          %w[expected input string],
+          %w[authentication failed],
+          %w[authorization failed],
+          %w[request failed],
+          %w[request rejected],
+          %w[input invalid],
+          %w[response invalid],
+          %w[output invalid],
+          %w[model unavailable],
+          %w[rate limit exceeded],
+          %w[quota exceeded],
+          %w[invalid request],
+          %w[resource not found],
+          %w[permission denied]
+        ]
+        safe_templates.include?(words)
+      end
+
+      private def bounded_status_field(value, limit:)
+        text = value.to_s
+        escaped = OpenAI::Internal::Logging.safe_field(text[...limit])
+        return escaped if text.length <= limit && escaped.bytesize <= limit
+
+        "#{escaped.byteslice(0, limit)}..."
+      end
     end
 
     class BadRequestError < OpenAI::Errors::APIStatusError
@@ -276,19 +536,15 @@ module OpenAI
       attr_reader :error_code
 
       def initialize(status:, body:, headers:)
-        @error_code = OpenAI::Internal::Type::Converter.coerce(
-          OpenAI::Models::OAuthErrorCode,
-          body&.dig(:error)
-        )
+        @error_code = OpenAI::Internal::Type::Converter.coerce(OpenAI::Models::OAuthErrorCode, body&.dig(:error))
 
-        message =
-          if body&.dig(:error_description)
-            body[:error_description]
-          elsif @error_code
-            @error_code
-          else
-            "OAuth2 authentication error"
-          end
+        message = if body&.dig(:error_description)
+          body[:error_description]
+        elsif @error_code
+          @error_code
+        else
+          "OAuth2 authentication error"
+        end
 
         super(
           url: URI("https://auth.openai.com/oauth/token"),

data/lib/openai/file_part.rb

@@ -2,15 +2,81 @@
 
 module OpenAI
   class FilePart
+    # HTTP media types contain ASCII tokens and possibly empty parameter slots.
+    # Quoted values may contain horizontal whitespace and non-ASCII header bytes, but
+    # never CR, LF, NUL, other forbidden control bytes, or an unescaped quote.
+    #
+    # @api private
+    # @type [Regexp]
+    MEDIA_TYPE = %r{
+      \A
+      [!#$%&'*+\-.^_`|~0-9A-Za-z]+
+      /
+      [!#$%&'*+\-.^_`|~0-9A-Za-z]+
+      (?:
+        [\x20\t]*;[\x20\t]*
+        (?:
+          [!#$%&'*+\-.^_`|~0-9A-Za-z]+
+          [\x20\t]*=[\x20\t]*
+          (?:
+            [!#$%&'*+\-.^_`|~0-9A-Za-z]+
+            |
+            "(?:[\x20\t\x21\x23-\x5B\x5D-\x7E\x80-\xFF]|\\[\x20\t\x21-\x7E\x80-\xFF])*"
+          )
+        )?
+      )*
+      [\x20\t]*
+      \z
+    }nx
+    private_constant :MEDIA_TYPE
+
+    # Validate an effective media type before it is written to multipart headers.
+    #
+    # @api private
+    # @param content_type [String, nil]
+    # @return [String, nil]
+    # @raise [ArgumentError] if the content type is not a valid MIME media type
+    def self.validate_content_type(content_type)
+      return if content_type.nil?
+      return content_type if content_type.is_a?(String) && MEDIA_TYPE.match?(content_type.b)
+
+      raise ArgumentError, "`content_type` must be a valid MIME media type"
+    end
+
     # @return [Pathname, StringIO, IO, String]
     attr_reader :content
 
     # @return [String, nil]
-    attr_reader :content_type
+    # @raise [ArgumentError] if the content type is not a valid MIME media type
+    def content_type
+      OpenAI::FilePart.validate_content_type(@content_type)
+    end
 
     # @return [String, nil]
     attr_reader :filename
 
+    # Return a copy with different content while preserving multipart behavior.
+    #
+    # @api private
+    #
+    # @param content [Pathname, StringIO, IO, String]
+    # @return [OpenAI::FilePart]
+    def with_content(content)
+      dup.tap do |copy|
+        copy.content = content
+        copy.content_type = content_type || default_content_type
+      end
+    end
+
+    protected(attr_writer(:content, :content_type))
+
+    # @api private
+    #
+    # @return [String]
+    private def default_content_type
+      content.is_a?(String) ? "text/plain" : "application/octet-stream"
+    end
+
     # @api private
     #
     # @return [String]
@@ -40,19 +106,20 @@ module OpenAI
     # @param content [Pathname, StringIO, IO, String]
     # @param filename [Pathname, String, nil]
     # @param content_type [String, nil]
+    # @raise [ArgumentError] if the content type is not a valid MIME media type
     def initialize(content, filename: nil, content_type: nil)
+      OpenAI::FilePart.validate_content_type(content_type)
       @content_type = content_type
-      @filename =
-        case [filename, (@content = content)]
-        in [String | Pathname, _]
-          ::File.basename(filename)
-        in [nil, Pathname]
-          content.basename.to_path
-        in [nil, IO]
-          content.to_path
-        else
-          filename
-        end
+      @filename = case [filename, (@content = content)]
+      in [String | Pathname, _]
+        ::File.basename(filename)
+      in [nil, Pathname]
+        content.basename.to_path
+      in [nil, IO]
+        content.to_path&.then { ::File.basename(_1) }
+      else
+        filename
+      end
     end
   end
 end

data/lib/openai/helpers/client_options.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Internal
+    # Resolved constructor settings for derived clients. This stays handwritten
+    # so provider and credential configuration is not inferred from public readers.
+    # @api private
+    module ClientOptions
+      # Marks an already-resolved header set: the constructor must not read
+      # OPENAI_CUSTOM_HEADERS again when creating a derived client.
+      # @api private
+      class ResolvedHeaders < Hash
+      end
+
+      class << self
+        # @api private
+        def capture(**options)
+          options
+            .transform_values do |value|
+              case value
+              when String
+                value.dup.freeze
+              when Hash
+                value.transform_values { _1.is_a?(String) ? _1.dup.freeze : _1 }.freeze
+              else
+                value
+              end
+            end
+            .freeze
+        end
+
+        # @api private
+        def copy(defaults, overrides)
+          overrides = overrides.dup
+          data_residency = overrides.delete(:data_residency)
+          unless data_residency.nil?
+            overrides[:base_url] = resolve_data_residency(
+              data_residency,
+              base_url: overrides.fetch(:base_url, OpenAI::Internal::OMIT),
+              provider: overrides.fetch(:provider, defaults[:provider])
+            )
+          end
+
+          unknown = overrides.keys - defaults.keys
+          unless unknown.empty?
+            raise ArgumentError, "Unknown client option#{unknown.one? ? "" : "s"}: #{unknown.join(", ")}"
+          end
+
+          options = defaults.dup
+          provider_changed = overrides.key?(:provider) && !overrides[:provider].equal?(defaults[:provider])
+          credentials_changed = [:api_key, :admin_api_key, :workload_identity].any? { overrides.key?(_1) }
+
+          if provider_changed
+            [:api_key, :admin_api_key, :workload_identity, :base_url, :organization, :project].each do |name|
+              options[name] = nil
+            end
+
+            options[:default_headers] = {}
+          elsif credentials_changed
+            options[:default_headers] = options.fetch(:default_headers).reject do |name, _value|
+              OpenAI::Internal::Logging.credential_header?(name)
+            end
+          end
+
+          # An explicitly selected authentication method replaces the inherited
+          # mutually exclusive method. Explicitly conflicting values still fail
+          # the ordinary constructor validation.
+          if overrides[:api_key] && !overrides.key?(:workload_identity)
+            options[:workload_identity] = nil
+          elsif overrides[:workload_identity] && !overrides.key?(:api_key)
+            options[:api_key] = nil
+          end
+
+          headers = options.fetch(:default_headers)
+          if overrides.key?(:default_headers)
+            supplied = overrides[:default_headers]
+            headers = supplied.nil? ? {} : OpenAI::Internal::Util.normalized_headers(headers, supplied)
+          end
+
+          options.merge!(overrides)
+          options[:default_headers] = ResolvedHeaders.new.replace(headers)
+          options
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/data_residency.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Internal
+    # @api private
+    module ClientOptions
+      # @api private
+      DATA_RESIDENCY_URLS = {
+        "global" => "https://api.openai.com/v1",
+        "us" => "https://us.api.openai.com/v1",
+        "eu" => "https://eu.api.openai.com/v1",
+        "ae" => "https://ae.api.openai.com/v1"
+      }.freeze
+
+      class << self
+        # Resolve the shorthand before environment defaults or inherited options
+        # are applied. Only an explicitly supplied base_url is a conflict.
+        # @api private
+        def resolve_data_residency(data_residency, base_url:, provider:)
+          return base_url if data_residency.nil?
+
+          unless base_url.equal?(OpenAI::Internal::OMIT)
+            raise ArgumentError, "`data_residency` and `base_url` are mutually exclusive"
+          end
+
+          unless provider.nil?
+            raise ArgumentError, "`data_residency` cannot be combined with `provider`"
+          end
+
+          url = DATA_RESIDENCY_URLS[data_residency.to_s] if data_residency.is_a?(String) || data_residency.is_a?(Symbol)
+          return url unless url.nil?
+
+          raise ArgumentError, "`data_residency` must be one of: #{DATA_RESIDENCY_URLS.keys.join(", ")}"
+        end
+      end
+    end
+  end
+end