typesafe-jev 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 331918548db2a5fdbd2f3dc3c2ac3bf650ff80d530e1bf5df205ddabede2299b
-  data.tar.gz: ce1c7bef8487e643d53fcfa8cb338fdb4abd26a085c19478e50cb53eac01d336
+  metadata.gz: 0627352ab282ec9a72607ebbc8d39bc73e2577231c567b4c66a7fc74e6140a0e
+  data.tar.gz: 218abce1d559c90b75e1b6bcf5872ff3f661d453dc6dd5c9bd15613141a89f1a
 SHA512:
-  metadata.gz: 18dee0e01b1df600771dcc3eff223841f7074df76f309494dbdfc3b200ff6db4cc6627c6ce8cd0a3934665302385b07986e6a66f3bd96b51af3126f61d95e823
-  data.tar.gz: cb4261224cfec035eed1b1bac36a02f84cc388a9ff05997aff7d9bc59a35a31108465eb6bd277cd94c0296408321ae17c8c8883b41718b1d95a9b363236ec120
+  metadata.gz: ff6c07bf97933605fe0aa29c6d63fc6ed2390fa9cde14e9fc0016d17c373b45a85482f58ccf98b4df5279bb1c43e9174db8521faa4599c0ab2656eb94bb04b48
+  data.tar.gz: d6cd7d83fcff85966c653434fa64a5fd87a0a5fa23a7970643c5669ac298b367a4ead66d7eb44ebefdb32ab4f2a54963af1bdf5a9eeb2254952ecca9b966addd

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.7.0
+
+- **Breaking**: `Typesafe::Client#evaluate` (and `Typesafe::Jev.evaluate`) now raises typed `Typesafe::Error` subclasses on any non-2xx response instead of raw `Net::HTTPClientException`/`Net::HTTPFatalError`: `BadRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422, with `#errors`), `RateLimitError` (429, with `#retry_after`), `OverloadedError` (529) and `ServerError` (5xx), all under the `Typesafe::APIError` base with `status`, `body`, `headers`, `request_id` and `#retryable?`. `Typesafe::Error` is the root rescuable class.
+
 ## 0.6.0
 
 - **Breaking**: `Typesafe::Client#evaluate` (and `Typesafe::Jev.evaluate`) now returns a typed `Typesafe::Response` instead of the raw parsed Hash; answers come back as `NoulAnswer`/`ChoiceAnswer`/`ScoreAnswer` objects accessible via `response[question_id]` (String or Symbol). Use `response.to_h` for the previous raw-Hash behavior.

data/lib/typesafe/client.rb

@@ -55,8 +55,11 @@ module Typesafe
     #   String/Symbol keys to Question values, +model+ is invalid, or the
     #   response body is not a valid response shape.
     # @raise [JSON::ParserError] if the response body is not valid JSON.
-    # @raise [Net::HTTPClientException, Net::HTTPFatalError] on any non-2xx
-    #   HTTP response.
+    # @raise [Typesafe::APIError] (or a subclass) on any non-2xx HTTP response:
+    #   {Typesafe::BadRequestError}, {Typesafe::AuthenticationError},
+    #   {Typesafe::PermissionDeniedError}, {Typesafe::NotFoundError},
+    #   {Typesafe::UnprocessableEntityError}, {Typesafe::RateLimitError},
+    #   {Typesafe::OverloadedError} and {Typesafe::ServerError}.
     def evaluate(state:, questions:, model: nil)
       model = model.nil? ? self.model : freeze_string(model, "model must be a non-empty String")
       questions = validate_questions!(questions)
@@ -68,7 +71,10 @@ module Typesafe
       )
 
       response = post(body)
-      response.value
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Errors.from_response(status: response.code.to_i, headers: response, body: response.body)
+      end
+
       Response.from_json(response.body)
     end
 

data/lib/typesafe/errors.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # Root of all errors raised by the gem, so users can `rescue Typesafe::Error`.
+  class Error < StandardError; end
+
+  # A non-2xx HTTP response from the TypeSafe API.
+  #
+  #   begin
+  #     client.evaluate(state:, questions:)
+  #   rescue Typesafe::RateLimitError => e
+  #     sleep(e.retry_after || 1.0)
+  #     retry
+  #   end
+  #
+  # The `detail` field of an error body comes in three shapes, all of which
+  # are rendered into the exception message:
+  #
+  # * a plain String — `{"detail": "Unknown model: jev-99"}`
+  # * a Hash with error_type/message —
+  #   `{"detail": {"error_type": "authentication_error", "message": "..."}}`
+  # * an Array of validation entries (FastAPI/pydantic style) —
+  #   `{"detail": [{"type": "missing", "loc": ["body", "questions"], "msg": "Field required"}]}`
+  class APIError < Error
+    # @return [Integer] the HTTP status code.
+    attr_reader :status
+    # @return [Hash, Array, String, nil] the parsed JSON body (Hash or Array),
+    #   the raw body String when it is not valid JSON, or nil for an empty body.
+    attr_reader :body
+    # @return [Hash{String => String}] the response headers, as received.
+    attr_reader :headers
+    # @return [String, nil] the +x-typesafe-request-id+ response header, when present.
+    attr_reader :request_id
+
+    # @param status [Integer] the HTTP status code.
+    # @param body [Hash, Array, String, nil] the parsed or raw response body.
+    # @param headers [Hash{String => String}] the response headers.
+    # @param message [String, nil] overrides the rendered +detail+-based message.
+    def initialize(status:, body: nil, headers: {}, message: nil)
+      @status = status
+      @body = body
+      @headers = headers
+      @request_id = header("x-typesafe-request-id")
+      super(message || "The TypeSafe API returned status #{status}.")
+    end
+
+    # True when the request may succeed if retried after a delay: rate limits
+    # (429), overload (529) and server errors (5xx).
+    # @return [Boolean]
+    def retryable?
+      status == 429 || status == 529 || (500..599).cover?(status)
+    end
+
+    private
+
+    # Case-insensitive header lookup, since header casing depends on the server.
+    def header(name)
+      headers.each { |key, value| return value if key.to_s.downcase == name }
+      nil
+    end
+  end
+
+  # The request was invalid (400).
+  class BadRequestError < APIError; end
+
+  # Missing or invalid API key (401).
+  class AuthenticationError < APIError; end
+
+  # Access denied (403). The API also returns this for a missing API key.
+  class PermissionDeniedError < APIError; end
+
+  # The endpoint or resource was not found (404).
+  class NotFoundError < APIError; end
+
+  # The request body failed server-side validation (422).
+  class UnprocessableEntityError < APIError
+    # The parsed validation entries, e.g.
+    # `{"type" => "missing", "loc" => ["body", "questions"], "msg" => "Field required"}`;
+    # empty when the body carries none.
+    # @return [Array<Hash>]
+    def errors
+      detail = body.is_a?(Hash) ? body["detail"] : nil
+      detail.is_a?(Array) ? detail : []
+    end
+  end
+
+  # The rate limit was exceeded (429).
+  class RateLimitError < APIError
+    # The server's requested wait before retrying, parsed from the
+    # +Retry-After+ (seconds) or +Retry-After-Ms+ (milliseconds) header.
+    # @return [Float, Integer, nil]
+    def retry_after
+      if (ms = header("retry-after-ms"))
+        Float(ms) / 1000
+      elsif (seconds = header("retry-after"))
+        Float(seconds)
+      end
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+
+  # TypeSafe is temporarily overloaded (529).
+  class OverloadedError < APIError; end
+
+  # The server failed to process the request (5xx, excluding 529).
+  class ServerError < APIError; end
+
+  # Builds error instances from raw HTTP responses.
+  module Errors
+    module_function
+
+    # Maps a non-2xx response to the matching error class.
+    #
+    # @param status [Integer] the HTTP status code.
+    # @param headers [Hash, #each_header] the response headers.
+    # @param body [String, Hash, Array, nil] the raw or parsed response body.
+    # @return [APIError] an instance of the class matching +status+.
+    def from_response(status:, headers: {}, body: nil)
+      parsed_body = parse_body(body)
+      klass = STATUS_CLASSES.fetch(status) do
+        (500..599).cover?(status) ? ServerError : APIError
+      end
+
+      klass.new(
+        status: status,
+        body: parsed_body.is_a?(String) ? parsed_body.dup.freeze : parsed_body.freeze,
+        headers: normalize_headers(headers).freeze,
+        message: message_from_body(parsed_body, status)
+      )
+    end
+
+    def parse_body(body)
+      return body unless body.is_a?(String)
+
+      JSON.parse(body)
+    rescue JSON::ParserError, TypeError
+      body
+    end
+
+    def message_from_body(parsed_body, status)
+      detail = parsed_body.is_a?(Hash) ? parsed_body["detail"] : nil
+      case detail
+      when String then detail
+      when Hash then detail["message"] || detail[:message] || "Invalid request."
+      when Array then detail.map { |entry| validation_message(entry) }.join("; ")
+      else "The TypeSafe API returned status #{status}."
+      end
+    end
+
+    def validation_message(entry)
+      return entry.to_s unless entry.is_a?(Hash)
+
+      loc = Array(entry["loc"]).join(".")
+      msg = entry["msg"] || entry[:msg]
+      loc.empty? ? msg.to_s : "#{loc}: #{msg}"
+    end
+
+    def normalize_headers(headers)
+      return headers.each_header.to_h if headers.respond_to?(:each_header)
+
+      headers.dup
+    rescue TypeError
+      {}
+    end
+
+    STATUS_CLASSES = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => PermissionDeniedError,
+      404 => NotFoundError,
+      422 => UnprocessableEntityError,
+      429 => RateLimitError,
+      529 => OverloadedError
+    }.freeze
+    private_constant :STATUS_CLASSES
+  end
+end

data/lib/typesafe/jev.rb

@@ -35,8 +35,8 @@ module Typesafe
     # @raise [ArgumentError] if +questions+ is invalid, +model+ is not the
     #   pinned one, or the response body is not a valid response shape.
     # @raise [JSON::ParserError] if the response body is not valid JSON.
-    # @raise [Net::HTTPClientException, Net::HTTPFatalError] on any non-2xx
-    #   HTTP response.
+    # @raise [Typesafe::APIError] (or a subclass) on any non-2xx HTTP response;
+    #   see {Typesafe::Client#evaluate}.
     def evaluate(state:, questions:, model: nil)
       if model && model != PINNED_MODEL
         raise ArgumentError,

data/lib/typesafe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Typesafe
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/typesafe.rb

@@ -16,6 +16,7 @@ require_relative "typesafe/score_answer"
 
 require_relative "typesafe/usage"
 require_relative "typesafe/response"
+require_relative "typesafe/errors"
 require_relative "typesafe/client"
 require_relative "typesafe/jev"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typesafe-jev
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - dtheofr
@@ -66,6 +66,7 @@ files:
 - lib/typesafe/choice.rb
 - lib/typesafe/choice_answer.rb
 - lib/typesafe/client.rb
+- lib/typesafe/errors.rb
 - lib/typesafe/jev.rb
 - lib/typesafe/noul.rb
 - lib/typesafe/noul_answer.rb