typesafe-sdk 0.2.0

data/lib/typesafe/sdk/noul.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class Noul
+      TYPE = "noul"
+
+      attr_reader :instructions, :criteria
+
+      def initialize(instructions: nil, criteria: nil)
+        unless criteria.nil? || criteria.is_a?(Hash)
+          raise(Error, "noul criteria must be a hash with true and false descriptions")
+        end
+
+        @instructions = instructions
+        @criteria = criteria
+        freeze
+      end
+
+      def type
+        TYPE
+      end
+
+      def to_h
+        hash = { "type" => TYPE }
+        hash["instructions"] = JsonValue.normalize(instructions, path: "instructions") unless instructions.nil?
+        hash["criteria"] = normalized_criteria unless criteria.nil?
+        hash
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+
+      private
+
+      def normalized_criteria
+        criteria.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = JsonValue.normalize(value, path: "criteria.#{key}")
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/noul_answer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class NoulAnswer
+      TYPE = "noul"
+
+      attr_reader :noul
+
+      class << self
+        def from_hash(hash, path:)
+          new(noul: FieldReader.number(hash: hash, key: "noul", path: path))
+        end
+      end
+
+      def initialize(noul:)
+        @noul = noul
+        freeze
+      end
+
+      def type
+        TYPE
+      end
+
+      def to_h
+        { type: TYPE, noul: noul }
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/question_set.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class QuestionSet
+      QUESTION_CLASSES = [Noul, Choice, Score].freeze
+      TYPES_REQUIRING_CRITERIA = %w[choice score].freeze
+
+      class << self
+        def normalize(questions)
+          raise(Error, "questions must be a hash of names to questions") unless questions.is_a?(Hash)
+          raise(Error, "at least one question is required") if questions.empty?
+
+          questions.each_with_object({}) do |(name, question), result|
+            unless name.is_a?(String) || name.is_a?(Symbol)
+              raise(Error, "question names must be strings or symbols, got #{name.class}")
+            end
+
+            result[name.to_s] = normalize_question(name: name.to_s, question: question)
+          end
+        end
+
+        private
+
+        def normalize_question(name:, question:)
+          hash = question_hash(name: name, question: question)
+          type = hash["type"]
+          if TYPES_REQUIRING_CRITERIA.include?(type) && !hash.key?("criteria")
+            raise(Error, "question #{name.inspect} requires \"criteria\"")
+          end
+          validate_score_criteria(name: name, criteria: hash["criteria"]) if type == Score::TYPE
+          hash
+        end
+
+        def question_hash(name:, question:)
+          return question.to_h if QUESTION_CLASSES.any? { |klass| question.is_a?(klass) }
+
+          hash = question.is_a?(Hash) ? JsonValue.normalize(question, path: "questions.#{name}") : nil
+          return hash if hash && hash["type"].is_a?(String) && !hash["type"].empty?
+
+          raise(
+            Error,
+            "question #{name.inspect} must be a Noul, Choice, or Score, or a hash with a nonempty \"type\""
+          )
+        end
+
+        def validate_score_criteria(name:, criteria:)
+          return unless criteria.nil? || (criteria.respond_to?(:empty?) && criteria.empty?)
+
+          raise(Error, "score question #{name.inspect} has no criteria, at least one level is required")
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/rate_limit_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class RateLimitError < APIError
+      attr_reader :retry_after_ms
+
+      def initialize(status:, body:, headers:, message: nil, endpoint: nil)
+        @retry_after_ms = RetryAfter.parse(headers)
+        super
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/request_builder.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class RequestBuilder
+      JSON_CONTENT_TYPE = "application/json"
+      RUNTIME = "ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})".freeze
+
+      class << self
+        def build(configuration:, http_method:, path:, body:, timeout:, headers:)
+          merged = configuration.headers.merge("User-Agent" => configuration.user_agent)
+          merge_headers(into: merged, headers: headers || {})
+          delete_header(headers: merged, name: RETRY_COUNT_HEADER)
+          protected_headers(configuration).each { |name, value| assign_header(headers: merged, name: name, value: value) }
+          assign_header(headers: merged, name: "Content-Type", value: JSON_CONTENT_TYPE) unless body.nil?
+
+          HTTPRequest.new(
+            http_method: http_method,
+            url: "#{configuration.base_url}#{path}",
+            headers: merged,
+            body: body.nil? ? nil : encode(body),
+            timeout: Configuration.validate_timeout(timeout.nil? ? configuration.timeout : timeout)
+          )
+        end
+
+        def assign_header(headers:, name:, value:)
+          delete_header(headers: headers, name: name)
+          headers[name] = value
+        end
+
+        private
+
+        def protected_headers(configuration)
+          {
+            "Authorization" => configuration.authorization,
+            "Accept" => JSON_CONTENT_TYPE,
+            "X-TypeSafe-SDK" => "#{SDK_NAME}/#{VERSION}",
+            "X-TypeSafe-Runtime" => RUNTIME
+          }
+        end
+
+        def merge_headers(into:, headers:)
+          headers.each { |name, value| assign_header(headers: into, name: name.to_s, value: value.to_s) }
+        end
+
+        def delete_header(headers:, name:)
+          headers.delete_if { |existing, _value| existing.casecmp?(name) }
+        end
+
+        def encode(body)
+          JSON.generate(body)
+        rescue JSON::GeneratorError, EncodingError => e
+          raise(Error, "the request body could not be encoded as json: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/request_logger.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class RequestLogger
+      SECRET_HEADERS = %w[authorization proxy-authorization x-api-key api-key cookie set-cookie].freeze
+
+      class << self
+        def redact(headers)
+          headers.to_h do |name, value|
+            [name, secret?(name) ? "***" : value]
+          end
+        end
+
+        private
+
+        def secret?(name)
+          lowered = name.to_s.downcase
+          SECRET_HEADERS.include?(lowered) || lowered.include?("token") || lowered.include?("secret")
+        end
+      end
+
+      def initialize(logger)
+        @logger = logger
+      end
+
+      def sending(request)
+        return unless logger
+
+        logger.debug("sending #{describe(request)} headers=#{self.class.redact(request.headers)} body=#{request.body.inspect}")
+      end
+
+      def retrying(request:, retry_count:)
+        return unless logger
+
+        logger.info("retrying #{describe(request)} (retry #{retry_count})")
+      end
+
+      def failed(request:, error:)
+        return unless logger
+
+        logger.info("#{describe(request)} failed: #{error.message}")
+      end
+
+      def received(request:, response:, elapsed_ms:)
+        return unless logger
+
+        request_id = response.headers[REQUEST_ID_HEADER] || "-"
+        logger.info("#{describe(request)} returned #{response.status} in #{elapsed_ms.round}ms (request #{request_id})")
+        logger.debug("received #{describe(request)} headers=#{self.class.redact(response.headers)} body=#{response.body.inspect}")
+      end
+
+      def warn(message)
+        return unless logger
+
+        logger.warn(message)
+      end
+
+      private
+
+      attr_reader :logger
+
+      def describe(request)
+        "#{request.http_method} #{request.url}"
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/requester.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class Requester
+      def initialize(transport:, logger:)
+        @transport = transport
+        @request_logger = RequestLogger.new(logger)
+      end
+
+      def perform(request:, response_class:, retry_policy:)
+        started_at = monotonic_now
+        attempt = 1
+        begin
+          attempt_once(request: request, response_class: response_class, retry_count: attempt - 1)
+        rescue StandardError => e
+          delay = retry_delay(policy: retry_policy, error: e, attempt: attempt, started_at: started_at)
+          raise if delay.nil?
+
+          Kernel.sleep(delay) if delay.positive?
+          attempt += 1
+          retry
+        end
+      end
+
+      private
+
+      attr_reader :transport, :request_logger
+
+      def retry_delay(policy:, error:, attempt:, started_at:)
+        return unless policy.retryable?(error)
+        return if attempt >= policy.max_attempts
+
+        delay = policy.delay_for(attempt: attempt, error: error)
+        return delay if policy.timeout.nil?
+        return delay if monotonic_now - started_at + delay < policy.timeout
+
+        nil
+      end
+
+      def attempt_once(request:, response_class:, retry_count:)
+        attempt_request = request
+        if retry_count.positive?
+          headers = request.headers.dup
+          RequestBuilder.assign_header(headers: headers, name: RETRY_COUNT_HEADER, value: retry_count.to_s)
+          attempt_request = request.with_headers(headers)
+          request_logger.retrying(request: request, retry_count: retry_count)
+        end
+        response = send_request(attempt_request)
+        parse(request: request, response: response, response_class: response_class)
+      end
+
+      def send_request(request)
+        request_logger.sending(request)
+        started_at = monotonic_now
+        response = transport.call(request)
+        request_logger.received(request: request, response: response, elapsed_ms: (monotonic_now - started_at) * 1000)
+        response
+      rescue APIConnectionError => e
+        request_logger.failed(request: request, error: e)
+        raise
+      end
+
+      def parse(request:, response:, response_class:)
+        raise(APIErrorFactory.build(response: response, endpoint: request.endpoint)) unless response.success?
+
+        body = parse_body(response)
+        response_class.from_body(body, request_logger: request_logger, http_response: response)
+      rescue InvalidResponseField => e
+        raise(
+          APIResponseValidationError.new(
+            status: response.status,
+            body: BodyDecoder.decode(response.body),
+            headers: response.headers,
+            field_path: e.field_path,
+            endpoint: request.endpoint
+          )
+        )
+      end
+
+      def parse_body(response)
+        JSON.parse(response.body.dup.force_encoding(Encoding::UTF_8))
+      rescue JSON::ParserError, EncodingError
+        raise(InvalidResponseField, "")
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/retry_after.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class RetryAfter
+      HEADERS = [["retry-after-ms", 1], ["retry-after", 1000]].freeze
+
+      class << self
+        def parse(headers)
+          HEADERS.each do |name, multiplier|
+            raw = headers[name]
+            next if raw.nil?
+
+            stripped = raw.to_s.strip
+            value = Float(stripped.empty? ? "0" : stripped, exception: false)
+            if value.nil?
+              return from_http_date(stripped) if name == "retry-after" && http_date?(stripped)
+
+              next
+            end
+            next unless value.finite?
+            return if value.negative? && name == "retry-after"
+            next if value.negative?
+
+            delay = value * multiplier
+            return delay if delay.finite?
+          end
+          nil
+        end
+
+        private
+
+        def http_date?(value)
+          Time.httpdate(value)
+          true
+        rescue ArgumentError
+          false
+        end
+
+        def from_http_date(value)
+          [0.0, (Time.httpdate(value) - Time.now) * 1000].max
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/retry_policy.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class RetryPolicy
+      DEFAULT_HTTP_STATUSES = [408, 429, *500..599].freeze
+
+      attr_reader :max_retries, :backoff_initial, :backoff_max, :backoff_jitter, :http_statuses,
+        :respect_retry_after, :api_connection_error, :api_timeout_error, :exceptions, :predicate, :timeout
+
+      def initialize(
+        max_retries: 2,
+        backoff_initial: 0.5,
+        backoff_max: 5.0,
+        backoff_jitter: 0.25,
+        http_statuses: DEFAULT_HTTP_STATUSES,
+        respect_retry_after: true,
+        api_connection_error: true,
+        api_timeout_error: true,
+        exceptions: [],
+        predicate: nil,
+        timeout: 30.0
+      )
+        @max_retries = max_retries
+        @backoff_initial = backoff_initial
+        @backoff_max = backoff_max
+        @backoff_jitter = backoff_jitter
+        @http_statuses = http_statuses.to_a.freeze
+        @respect_retry_after = respect_retry_after
+        @api_connection_error = api_connection_error
+        @api_timeout_error = api_timeout_error
+        @exceptions = exceptions.to_a.freeze
+        @predicate = predicate
+        @timeout = timeout
+        validate
+        freeze
+      end
+
+      def max_attempts
+        max_retries + 1
+      end
+
+      def retryable?(error)
+        builtin_retryable?(error) ||
+          exceptions.any? { |klass| error.is_a?(klass) } ||
+          (!predicate.nil? && predicate.call(error) ? true : false)
+      end
+
+      def delay_for(attempt:, error:)
+        if respect_retry_after && error.is_a?(APIError)
+          retry_after_ms = RetryAfter.parse(error.headers)
+          return retry_after_ms / 1000.0 if retry_after_ms
+        end
+        backoff(attempt)
+      end
+
+      def backoff(attempt)
+        return 0.0 if backoff_initial.zero? || backoff_max.zero?
+
+        exponent = attempt - 1
+        capped = exponent >= Math.log2(backoff_max) - Math.log2(backoff_initial)
+        exponential = capped ? backoff_max.to_f : backoff_initial * (2**exponent)
+        jittered = exponential * (1 - (Random.rand * backoff_jitter))
+        [exponential, jittered.round(3)].min
+      end
+
+      private
+
+      def builtin_retryable?(error)
+        case error
+        when APITimeoutError then api_timeout_error
+        when APIConnectionError then api_connection_error
+        when APIError then http_statuses.include?(error.status)
+        else false
+        end
+      end
+
+      def validate
+        raise(Error, "max_retries must be a non-negative integer") unless max_retries.is_a?(Integer) && max_retries >= 0
+
+        validate_seconds(name: "backoff_initial", value: backoff_initial)
+        validate_seconds(name: "backoff_max", value: backoff_max)
+        unless backoff_jitter.is_a?(Numeric) && backoff_jitter.between?(0, 1)
+          raise(Error, "backoff_jitter must be between zero and one")
+        end
+        Configuration.validate_timeout(timeout) unless timeout.nil?
+      end
+
+      def validate_seconds(name:, value:)
+        return if value.is_a?(Numeric) && value.finite? && value >= 0
+
+        raise(Error, "#{name} must be a non-negative, finite number of seconds")
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/score.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class Score
+      TYPE = "score"
+
+      attr_reader :criteria, :instructions
+
+      def initialize(criteria:, instructions: nil)
+        raise(Error, "score criteria must be an array of level descriptions") unless criteria.is_a?(Array)
+        raise(Error, "score criteria must include at least one level") if criteria.empty?
+
+        @criteria = criteria
+        @instructions = instructions
+        freeze
+      end
+
+      def type
+        TYPE
+      end
+
+      def to_h
+        hash = { "type" => TYPE }
+        hash["instructions"] = JsonValue.normalize(instructions, path: "instructions") unless instructions.nil?
+        hash["criteria"] = JsonValue.normalize(criteria, path: "criteria")
+        hash
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/score_answer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class ScoreAnswer
+      TYPE = "score"
+
+      attr_reader :score, :confidence, :legend, :probabilities
+
+      class << self
+        def from_hash(hash, path:)
+          new(
+            score: FieldReader.number(hash: hash, key: "score", path: path),
+            confidence: FieldReader.number(hash: hash, key: "confidence", path: path),
+            legend: FieldReader.integer_keys(
+              hash: FieldReader.content_map(hash: hash, key: "legend", path: path),
+              path: "#{path}.legend"
+            ),
+            probabilities: FieldReader.integer_keys(
+              hash: FieldReader.number_map(hash: hash, key: "probabilities", path: path),
+              path: "#{path}.probabilities"
+            )
+          )
+        end
+      end
+
+      def initialize(score:, confidence:, legend:, probabilities:)
+        @score = score
+        @confidence = confidence
+        @legend = legend.freeze
+        @probabilities = probabilities.freeze
+        freeze
+      end
+
+      def type
+        TYPE
+      end
+
+      def to_h
+        { type: TYPE, score: score, confidence: confidence, legend: legend, probabilities: probabilities }
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/stderr_logger.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class StderrLogger
+      LEVELS = { "debug" => 0, "info" => 1, "warn" => 2, "warning" => 2, "error" => 3 }.freeze
+
+      attr_reader :level
+
+      def initialize(level: "warn", io: $stderr)
+        @level = LEVELS.fetch(level.to_s)
+        @io = io
+      end
+
+      def debug(message = nil)
+        write(severity: "debug", message: message)
+      end
+
+      def info(message = nil)
+        write(severity: "info", message: message)
+      end
+
+      def warn(message = nil)
+        write(severity: "warn", message: message)
+      end
+
+      def error(message = nil)
+        write(severity: "error", message: message)
+      end
+
+      private
+
+      attr_reader :io
+
+      def write(severity:, message:)
+        return if LEVELS.fetch(severity) < level
+
+        io.puts("typesafe-sdk #{severity}: #{message}")
+      end
+    end
+  end
+end