typesafe-sdk 0.2.0

data/lib/typesafe/sdk/client.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class Client
+      attr_reader :retry_policy
+
+      class << self
+        def open(**options)
+          client = new(**options)
+          return client unless block_given?
+
+          begin
+            yield(client)
+          ensure
+            client.close
+          end
+        end
+      end
+
+      def initialize(
+        api_key:,
+        model: nil,
+        base_url: nil,
+        timeout: nil,
+        headers: nil,
+        user_agent: nil,
+        retry_policy: nil,
+        logger: nil,
+        transport: nil
+      )
+        @configuration = Configuration.resolve(
+          api_key: api_key,
+          base_url: base_url,
+          model: model,
+          timeout: timeout,
+          headers: headers,
+          user_agent: user_agent,
+          logger: logger
+        )
+        @retry_policy = retry_policy || RetryPolicy.new
+        @transport = transport || NetHttpTransport.new
+        @requester = Requester.new(transport: @transport, logger: @configuration.logger)
+        @models = Models.new(configuration: @configuration, requester: @requester, retry_policy: @retry_policy)
+      end
+
+      attr_reader :models
+
+      def model
+        configuration.model
+      end
+
+      def base_url
+        configuration.base_url
+      end
+
+      def timeout
+        configuration.timeout
+      end
+
+      def user_agent
+        configuration.user_agent
+      end
+
+      def system_one(state:, questions:, model: nil, retry_policy: nil, timeout: nil, extra_headers: nil, extra_body: nil)
+        request = RequestBuilder.build(
+          configuration: configuration,
+          http_method: "POST",
+          path: SYSTEM_ONE_PATH,
+          body: system_one_body(state: state, questions: questions, model: model, extra_body: extra_body),
+          timeout: timeout,
+          headers: extra_headers
+        )
+        requester.perform(
+          request: request,
+          response_class: SystemOneResponse,
+          retry_policy: retry_policy || self.retry_policy
+        )
+      end
+
+      def close
+        transport.close if transport.respond_to?(:close)
+        nil
+      end
+
+      def inspect
+        "#<#{self.class.name} base_url=#{base_url.inspect} model=#{model.inspect} timeout=#{timeout.inspect}>"
+      end
+
+      private
+
+      attr_reader :configuration, :transport, :requester
+
+      def system_one_body(state:, questions:, model:, extra_body:)
+        raise(Error, "state must be a string, hash, or array") unless JsonValue.content?(state)
+
+        body = {
+          "state" => JsonValue.normalize(state, path: "state"),
+          "model" => model.nil? ? configuration.model : model,
+          "questions" => QuestionSet.normalize(questions)
+        }
+        return body if extra_body.nil?
+
+        body.merge(JsonValue.normalize(extra_body.to_h, path: "extra_body"))
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/configuration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class Configuration
+      attr_reader :base_url, :model, :timeout, :headers, :user_agent, :logger
+
+      class << self
+        def resolve(api_key:, base_url: nil, model: nil, timeout: nil, headers: nil, user_agent: nil, logger: nil)
+          raise(Error, "api_key is required") unless api_key.is_a?(String) && !api_key.strip.empty?
+
+          normalized_headers = (headers || {}).to_h { |name, value| [name.to_s, value.to_s] }
+          header_user_agent = normalized_headers.find { |name, _value| name.casecmp?("User-Agent") }
+          normalized_headers.delete_if { |name, _value| name.casecmp?("User-Agent") }
+
+          new(
+            api_key: api_key,
+            base_url: base_url.nil? ? DEFAULT_BASE_URL : base_url,
+            model: model.nil? ? DEFAULT_MODEL : model,
+            timeout: validate_timeout(timeout.nil? ? DEFAULT_TIMEOUT : timeout),
+            headers: normalized_headers,
+            user_agent: validate_user_agent(user_agent || (header_user_agent && header_user_agent.last) || DEFAULT_USER_AGENT),
+            logger: logger
+          )
+        end
+
+        def validate_timeout(value)
+          return value if value.is_a?(Numeric) && value.finite? && value.positive?
+
+          raise(Error, "timeout must be a positive, finite number of seconds")
+        end
+
+        private
+
+        def validate_user_agent(value)
+          return value if value.is_a?(String) && !value.strip.empty?
+
+          raise(Error, "user_agent must be a nonempty string")
+        end
+      end
+
+      def initialize(api_key:, base_url:, model:, timeout:, headers:, user_agent:, logger:)
+        @api_key = api_key
+        @base_url = base_url.sub(%r{/+\z}, "")
+        @model = model
+        @timeout = timeout
+        @headers = headers.freeze
+        @user_agent = user_agent
+        @logger = logger
+        freeze
+      end
+
+      def authorization
+        "Bearer #{api_key}"
+      end
+
+      def inspect
+        "#<#{self.class.name} base_url=#{base_url.inspect} model=#{model.inspect} timeout=#{timeout.inspect}>"
+      end
+
+      private
+
+      attr_reader :api_key
+    end
+  end
+end

data/lib/typesafe/sdk/connection_pool.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class ConnectionPool
+      def initialize
+        @mutex = Mutex.new
+        @idle = {}
+        @pid = Process.pid
+      end
+
+      def checkout(uri:, timeout:)
+        connection = mutex.synchronize do
+          reset_after_fork
+          idle_for(key_for(uri)).pop
+        end
+        connection = start(uri: uri, timeout: timeout) if connection.nil?
+        apply_timeout(connection: connection, timeout: timeout)
+        connection
+      end
+
+      def checkin(uri:, connection:)
+        return discard(connection) unless connection.started?
+
+        mutex.synchronize do
+          reset_after_fork
+          idle_for(key_for(uri)).push(connection)
+        end
+      end
+
+      def discard(connection)
+        return if connection.nil?
+
+        connection.finish if connection.started?
+      rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+        nil
+      end
+
+      def shutdown
+        connections = mutex.synchronize do
+          all = idle.values.flatten
+          idle.clear
+          all
+        end
+        connections.each { |connection| discard(connection) }
+      end
+
+      private
+
+      attr_reader :mutex, :idle
+
+      def key_for(uri)
+        "#{uri.scheme}://#{uri.host}:#{uri.port}"
+      end
+
+      def idle_for(key)
+        idle[key] ||= []
+      end
+
+      def reset_after_fork
+        return if @pid == Process.pid
+
+        @idle = {}
+        @pid = Process.pid
+      end
+
+      def start(uri:, timeout:)
+        connection = Net::HTTP.new(uri.host, uri.port)
+        connection.use_ssl = uri.scheme == "https"
+        apply_timeout(connection: connection, timeout: timeout)
+        connection.start
+      end
+
+      def apply_timeout(connection:, timeout:)
+        connection.open_timeout = timeout
+        connection.read_timeout = timeout
+        connection.write_timeout = timeout
+        connection.ssl_timeout = timeout
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/error_message.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class ErrorMessage
+      class << self
+        def extract(body)
+          return presence(body) if body.is_a?(String)
+          return unless body.is_a?(Hash)
+
+          from_error(body["error"]) ||
+            string_or_nil(body["message"]) ||
+            from_detail(body["detail"])
+        end
+
+        private
+
+        def from_error(error)
+          return error if error.is_a?(String)
+          return unless error.is_a?(Hash)
+
+          string_or_nil(error["message"])
+        end
+
+        def from_detail(detail)
+          return detail if detail.is_a?(String)
+          return string_or_nil(detail["message"]) if detail.is_a?(Hash)
+          return unless detail.is_a?(Array)
+
+          presence(detail.filter_map { |entry| validation_entry(entry) }.join("; "))
+        end
+
+        def validation_entry(entry)
+          return unless entry.is_a?(Hash) && entry["msg"].is_a?(String)
+
+          location = entry["loc"]
+          path = location.is_a?(Array) ? location.reject { |item| item == "body" }.join(".") : ""
+          path.empty? ? entry["msg"] : "#{path}: #{entry["msg"]}"
+        end
+
+        def string_or_nil(value)
+          value.is_a?(String) ? value : nil
+        end
+
+        def presence(value)
+          value.empty? ? nil : value
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/field_reader.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class FieldReader
+      INTEGER_KEY = /\A-?\d+\z/
+
+      class << self
+        def object(value, path:)
+          return value if value.is_a?(Hash)
+
+          raise(InvalidResponseField, path)
+        end
+
+        def fetch(hash:, key:, path:)
+          raise(InvalidResponseField, join(path: path, key: key)) unless hash.key?(key)
+
+          hash[key]
+        end
+
+        def string(hash:, key:, path:)
+          value = fetch(hash: hash, key: key, path: path)
+          return value if value.is_a?(String)
+
+          raise(InvalidResponseField, join(path: path, key: key))
+        end
+
+        def number(hash:, key:, path:)
+          value = fetch(hash: hash, key: key, path: path)
+          return value.to_f if value.is_a?(Numeric)
+
+          raise(InvalidResponseField, join(path: path, key: key))
+        end
+
+        def optional_integer(hash:, key:, path:)
+          value = hash[key]
+          return value if value.nil? || value.is_a?(Integer)
+
+          raise(InvalidResponseField, join(path: path, key: key))
+        end
+
+        def number_map(hash:, key:, path:)
+          map_path = join(path: path, key: key)
+          object(fetch(hash: hash, key: key, path: path), path: map_path).to_h do |name, value|
+            raise(InvalidResponseField, join(path: map_path, key: name)) unless value.is_a?(Numeric)
+
+            [name, value.to_f]
+          end
+        end
+
+        def content_map(hash:, key:, path:)
+          map_path = join(path: path, key: key)
+          map = object(fetch(hash: hash, key: key, path: path), path: map_path)
+          map.each do |name, value|
+            next if value.is_a?(String) || value.is_a?(Hash) || value.is_a?(Array)
+
+            raise(InvalidResponseField, join(path: map_path, key: name))
+          end
+          map
+        end
+
+        def integer_keys(hash:, path:)
+          hash.to_h do |key, value|
+            raise(InvalidResponseField, join(path: path, key: key)) unless INTEGER_KEY.match?(key)
+
+            [Integer(key, 10), value]
+          end
+        end
+
+        def join(path:, key:)
+          path.empty? ? key.to_s : "#{path}.#{key}"
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/http_request.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class HTTPRequest
+      attr_reader :http_method, :url, :headers, :body, :timeout
+
+      def initialize(http_method:, url:, headers:, body:, timeout:)
+        @http_method = http_method
+        @url = url
+        @headers = headers.freeze
+        @body = body
+        @timeout = timeout
+        freeze
+      end
+
+      def with_headers(headers)
+        self.class.new(http_method: http_method, url: url, headers: headers, body: body, timeout: timeout)
+      end
+
+      def endpoint
+        uri = URI.parse(url)
+        port = uri.port == uri.default_port ? "" : ":#{uri.port}"
+        "#{http_method} #{uri.scheme}://#{uri.host}#{port}#{uri.path}"
+      rescue URI::InvalidURIError
+        http_method
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/http_response.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class HTTPResponse
+      attr_reader :status, :headers, :body
+
+      def initialize(status:, headers:, body:)
+        @status = status
+        @headers = headers.to_h { |name, value| [name.to_s.downcase, value] }.freeze
+        @body = body.to_s
+        freeze
+      end
+
+      def success?
+        status.between?(200, 299)
+      end
+
+      def json
+        JSON.parse(body)
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/invalid_response_field.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class InvalidResponseField < StandardError
+      attr_reader :field_path
+
+      def initialize(field_path)
+        @field_path = field_path
+        super("invalid response data at #{field_path.inspect}")
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/json_value.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class JsonValue
+      class << self
+        def normalize(value, path: "value")
+          case value
+          when nil, true, false, String, Integer then value
+          when Float then normalize_float(value: value, path: path)
+          when Symbol then value.to_s
+          when Hash then normalize_hash(value: value, path: path)
+          when Array then value.each_with_index.map { |item, index| normalize(item, path: "#{path}.#{index}") }
+          else normalize_object(value: value, path: path)
+          end
+        end
+
+        def content?(value)
+          value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Hash) || value.is_a?(Array)
+        end
+
+        private
+
+        def normalize_float(value:, path:)
+          return value if value.finite?
+
+          raise(Error, "#{path} is #{value}, which cannot be encoded as json")
+        end
+
+        def normalize_hash(value:, path:)
+          value.each_with_object({}) do |(key, item), result|
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise(Error, "#{path} has a #{key.class} key, json object keys must be strings or symbols")
+            end
+
+            result[key.to_s] = normalize(item, path: "#{path}.#{key}")
+          end
+        end
+
+        def normalize_object(value:, path:)
+          if value.respond_to?(:as_json)
+            converted = value.as_json
+            return normalize(converted, path: path) unless converted.equal?(value)
+          end
+
+          raise(Error, "#{path} is a #{value.class}, which cannot be encoded as json")
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/list_models_response.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class ListModelsResponse
+      include Enumerable
+
+      attr_reader :models, :http_response
+
+      class << self
+        def from_body(body, request_logger: nil, http_response: nil)
+          root = FieldReader.object(body, path: "")
+          entries = FieldReader.fetch(hash: root, key: "models", path: "")
+          raise(InvalidResponseField, "models") unless entries.is_a?(Array)
+
+          models = entries.each_with_index.map do |entry, index|
+            path = "models.#{index}"
+            ModelMetadata.from_hash(FieldReader.object(entry, path: path), path: path)
+          end
+          new(models: models, http_response: http_response)
+        end
+      end
+
+      def initialize(models:, http_response: nil)
+        @models = models.freeze
+        @http_response = http_response
+        freeze
+      end
+
+      def each(&block)
+        models.each(&block)
+      end
+
+      def request_id
+        return unless http_response
+
+        http_response.headers[REQUEST_ID_HEADER]
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/model_metadata.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class ModelMetadata
+      attr_reader :name, :description, :release_date
+
+      class << self
+        def from_hash(hash, path:)
+          new(
+            name: FieldReader.string(hash: hash, key: "name", path: path),
+            description: FieldReader.string(hash: hash, key: "description", path: path),
+            release_date: FieldReader.string(hash: hash, key: "release_date", path: path)
+          )
+        end
+      end
+
+      def initialize(name:, description:, release_date:)
+        @name = name
+        @description = description
+        @release_date = release_date
+        freeze
+      end
+
+      def to_h
+        { name: name, description: description, release_date: release_date }
+      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/models.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class Models
+      def initialize(configuration:, requester:, retry_policy:)
+        @configuration = configuration
+        @requester = requester
+        @default_retry_policy = retry_policy
+      end
+
+      def list(retry_policy: nil, timeout: nil, extra_headers: nil)
+        request = RequestBuilder.build(
+          configuration: configuration,
+          http_method: "GET",
+          path: MODELS_PATH,
+          body: nil,
+          timeout: timeout,
+          headers: extra_headers
+        )
+        requester.perform(
+          request: request,
+          response_class: ListModelsResponse,
+          retry_policy: retry_policy || default_retry_policy
+        )
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      attr_reader :configuration, :requester, :default_retry_policy
+    end
+  end
+end

data/lib/typesafe/sdk/net_http_transport.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    class NetHttpTransport
+      REQUEST_CLASSES = { "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post }.freeze
+      CONNECTION_ERRORS = [
+        SocketError,
+        SystemCallError,
+        IOError,
+        OpenSSL::SSL::SSLError,
+        Net::HTTPBadResponse,
+        Net::ProtocolError,
+        Zlib::Error
+      ].freeze
+
+      def initialize(pool: ConnectionPool.new)
+        @pool = pool
+      end
+
+      def call(request)
+        uri = URI.parse(request.url)
+        connection = nil
+        connection = pool.checkout(uri: uri, timeout: request.timeout)
+        raw = connection.request(build(uri: uri, request: request))
+        pool.checkin(uri: uri, connection: connection)
+        HTTPResponse.new(status: raw.code.to_i, headers: raw.each_header.to_h, body: raw.body)
+      rescue Timeout::Error
+        pool.discard(connection)
+        raise(APITimeoutError.new(timeout: request.timeout))
+      rescue *CONNECTION_ERRORS => e
+        pool.discard(connection)
+        raise(APIConnectionError, "connection error: #{e.class}: #{e.message}")
+      end
+
+      def close
+        pool.shutdown
+      end
+
+      private
+
+      attr_reader :pool
+
+      def build(uri:, request:)
+        request_class = REQUEST_CLASSES.fetch(request.http_method)
+        net_request = request_class.new(uri.request_uri)
+        request.headers.each { |name, value| net_request[name] = value }
+        net_request.body = request.body unless request.body.nil?
+        net_request
+      end
+    end
+  end
+end