typesafe-ai-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 21d48754dd7b9582a87e2905f23d01de27c9d8e8f47a14c3eaf5e7f5bccf2e19
+  data.tar.gz: '0958ee9c8ef35da5b53b90dbacfdf3012ceaef7f79c27bf244ff50803deab56c'
+SHA512:
+  metadata.gz: 6bb1ef123a99b204a3dae6e22ff9567494d328c2ec1bd5ed47061554aa2ac2d2c2b76f796f53cd40cae2f4821d9dee4f7f940b3695b3e34446ef176c922f968c
+  data.tar.gz: 95750fac853da2683a7c41b452518bb027ca2696552fc7312b8075377c6ac47668fc55242488d52ce26328d2e96f70f4140fe7aeb31ea4adc98aba5abc68a4c1

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-19
+
+Initial release.
+
+- `TypeSafe::Client#system_one` and `client.models.list` for the System One API.
+- `TypeSafe::Noul`, `Choice` and `Score` questions with typed answers.
+- Configuration from options or `TYPESAFE_*` environment variables.
+- Retries with backoff and `Retry-After`, keep-alive connections, logging and instrumentation hooks.
+- RBS signatures.
+
+[Unreleased]: https://github.com/hnegishi/typesafe-ai-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/hnegishi/typesafe-ai-ruby/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 hnegishi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,176 @@
+# TypeSafe AI Ruby Library
+
+[![CI](https://github.com/hnegishi/typesafe-ai-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/hnegishi/typesafe-ai-ruby/actions/workflows/ci.yml)
+
+The TypeSafe AI Ruby library provides convenient access to the [TypeSafe](https://typesafe.ai) System One API from applications written in Ruby. Send state and typed questions to Jev, and get back structured answers with probabilities and confidence that your code can use directly.
+
+See the [TypeSafe documentation](https://docs.typesafe.ai/) for the concepts behind the API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "typesafe-ai-ruby"
+```
+
+Or install it yourself:
+
+```sh
+gem install typesafe-ai-ruby
+```
+
+### Requirements
+
+- Ruby 3.1 or newer.
+- No runtime dependencies beyond the Ruby standard library.
+
+## Usage
+
+Get an API key from the [TypeSafe console](https://console.typesafe.ai/settings/keys) and set it as `TYPESAFE_API_KEY`, or pass it to the client directly.
+
+```ruby
+require "typesafe-ai-ruby"
+
+client = TypeSafe::Client.new(api_key: ENV["TYPESAFE_API_KEY"])
+
+response = client.system_one(
+  state: "I was charged twice. Please fix this ASAP.",
+  questions: {
+    department: TypeSafe::Choice.new(
+      instructions: "Which team should handle this?",
+      criteria: { billing: "Payment issues", technical: "Bugs or integrations", sales: "Pricing questions" }
+    ),
+    frustration: TypeSafe::Score.new(
+      instructions: "How frustrated is the customer?",
+      criteria: ["Calm", "Frustrated but civil", "Very angry"]
+    ),
+    is_urgent: TypeSafe::Noul.new(instructions: "Does the message convey urgency?")
+  }
+)
+
+response.choices[:department].choice      # => "billing"
+response.choices[:department].confidence  # => 1.0
+response.scores[:frustration].score       # => 1.06
+response.nouls[:is_urgent].noul           # => 0.97
+response.model                            # => "jev-1.13.0"
+```
+
+### Questions
+
+There are three question types. `instructions` and every description can be a string, a Hash, or an Array when a sentence is not enough.
+
+- `TypeSafe::Noul` asks a yes/no question and returns the probability of yes. Criteria are optional: `criteria: { true: "Spam", false: "A real conversation" }`.
+- `TypeSafe::Choice` picks one option from a set. Criteria are required; use `nil` when the name speaks for itself.
+- `TypeSafe::Score` rates the state against ordered levels. Criteria are an Array of at least two levels, and each level's index is its score.
+
+The shorthand helpers take the instructions first:
+
+```ruby
+TypeSafe.noul("Is this spam?")
+TypeSafe.choice("What is the tone?", calm: nil, frustrated: nil, angry: nil)
+TypeSafe.score("How urgent is this?", ["Can wait", "This week", "Today"])
+```
+
+You can also pass a plain Hash with a `type` key. Extra keys are sent to the API untouched, so new API fields work before this library knows about them.
+
+`state` is whatever the questions are about: a String, a Hash, or an Array. Symbols are converted to strings, and objects that respond to `as_json` are converted through it.
+
+### Answers
+
+`system_one` returns a `TypeSafe::Responses::SystemOneResponse`. Answers are keyed by question name and accept String or Symbol keys.
+
+```ruby
+response.answers          # every answer
+response.nouls            # only Noul answers
+response.choices          # only Choice answers, with #choice, #probabilities and #confidence
+response.scores           # only Score answers, with #score, #legend, #probabilities and #confidence
+response.usage.input_tokens
+response.request_id
+response.to_h             # the raw JSON body
+```
+
+Use `confidence` to decide whether to act on an answer automatically or hand it to a human. See `examples/` for confidence-gated routing and asking many questions in one request.
+
+### Errors
+
+Errors inherit from `TypeSafe::Error`. HTTP failures raise a subclass of `TypeSafe::APIError` with `status`, `body`, `headers`, `endpoint` and `request_id`.
+
+```ruby
+begin
+  client.system_one(state: ticket, questions: questions)
+rescue TypeSafe::RateLimitError => e
+  sleep(e.retry_after || 1)
+rescue TypeSafe::APIError => e
+  logger.error("TypeSafe #{e.status}: #{e.message} (request #{e.request_id})")
+rescue TypeSafe::APIConnectionError => e
+  # no HTTP response; includes TypeSafe::APITimeoutError
+end
+```
+
+Malformed questions raise `TypeSafe::ValidationError` before anything is sent.
+
+## Configuration
+
+Options can be passed to `TypeSafe::Client.new` or set once for the default client. Explicit options win over environment variables, which win over the defaults.
+
+```ruby
+TypeSafe.configure do |c|
+  c.api_key = ENV.fetch("TYPESAFE_API_KEY")   # TYPESAFE_API_KEY
+  c.model = "jev-1.13.0"                       # TYPESAFE_DEFAULT_MODEL, default jev-latest
+  c.base_url = "https://api.typesafe.ai"       # TYPESAFE_BASE_URL
+  c.timeout = 10                               # seconds per attempt
+  c.logger = Logger.new($stdout)
+  c.log_level = :info                          # TYPESAFE_LOG_LEVEL, default :warn
+end
+
+TypeSafe.client.system_one(state: "...", questions: { urgent: TypeSafe.noul("Is this urgent?") })
+```
+
+Per-call overrides go in `request_options`:
+
+```ruby
+client.system_one(state: "...", questions: questions, model: "jev-preview",
+                  request_options: { timeout: 30, headers: { "X-Team" => "growth" } })
+```
+
+### Retries
+
+Requests that fail with 408, 429, 5xx, a connection error or a timeout are retried twice with exponential backoff, honoring `Retry-After`. Adjust or disable this with a `retry_policy`:
+
+```ruby
+client = TypeSafe::Client.new(retry_policy: { max_retries: 5, backoff_max: 10 })
+client.models.list(request_options: { retry_policy: { max_retries: 0 } })
+```
+
+### Logging and instrumentation
+
+At `:info` the client logs one line per request and each retry. At `:debug` it also logs headers and bodies, with credential headers redacted.
+
+`TypeSafe::Instrumentation` reports every call once it finishes, including retries:
+
+```ruby
+TypeSafe::Instrumentation.subscribe(:request_end) do |event|
+  StatsD.timing("typesafe.request", event.duration, tags: ["status:#{event.http_status}"])
+end
+```
+
+### Rails
+
+The library has no Rails specific code. Configure the default client in an initializer, keep question definitions in frozen constants, and layer ActiveJob retries on top of the built-in ones. `examples/rails/` shows each of these.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run `bundle exec rake` to run the tests, RuboCop and the RBS validation.
+
+The live API tests are skipped unless `TYPESAFE_API_KEY` is set:
+
+```sh
+TYPESAFE_API_KEY=... bundle exec rake test:integration
+```
+
+To release a new version, update the version number in `lib/typesafe/version.rb` and the changelog, then push a matching `v*` tag. The release workflow publishes the gem to RubyGems through trusted publishing.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/typesafe/client.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  # Client for the TypeSafe AI API.
+  #
+  # Explicit options take precedence over environment variables, then SDK defaults.
+  # Instances are immutable and safe to share between threads.
+  #
+  # For example:
+  #   client = TypeSafe::Client.new(api_key: "sk-...")
+  #   response = client.system_one(
+  #     state: "I was charged twice. Please help.",
+  #     questions: { billing: TypeSafe::Noul.new(instructions: "Is this about billing?") }
+  #   )
+  #   response.nouls[:billing].noul # => 0.98
+  class Client
+    # The resolved, frozen configuration.
+    attr_reader :config
+
+    def initialize(**options)
+      @config = Configuration.new(**options).resolve
+      @requestor = HTTP::Requestor.new(@config)
+      @models = Resources::Models.new(@requestor)
+    end
+
+    # Answer named questions about text or structured state.
+    def system_one(state:, questions:, model: nil, request_options: {})
+      options = RequestOptions.from(request_options)
+      body = {
+        "state" => Questions::Normalizer.state(state),
+        "model" => resolve_model(model),
+        "questions" => Questions::Normalizer.questions(questions)
+      }
+      body.merge!(options.extra_body) if options.extra_body
+      response = @requestor.post(Constants::SYSTEM_ONE_PATH, body: body, options: options)
+      Responses::SystemOneResponse.from_http(response)
+    end
+
+    # The models resource.
+    attr_reader :models
+
+    # Release network resources held by the transport.
+    def close
+      @requestor.close
+    end
+
+    private
+
+    def resolve_model(model)
+      return config.model if model.nil?
+      raise ValidationError, "model must be a non-blank String" if Util.blank?(model)
+
+      model.to_s
+    end
+  end
+end

data/lib/typesafe/configuration.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  # Client settings. Explicit values take precedence over environment variables, then SDK defaults.
+  #
+  # A Configuration starts mutable (used by TypeSafe.configure) and becomes a frozen, validated
+  # copy through #resolve, which is what TypeSafe::Client keeps.
+  class Configuration
+    LOG_LEVELS = {
+      debug: Logger::DEBUG, info: Logger::INFO, warn: Logger::WARN, error: Logger::ERROR, fatal: Logger::FATAL
+    }.freeze
+
+    # API key; falls back to TYPESAFE_API_KEY.
+    attr_accessor :api_key
+    # API root; falls back to TYPESAFE_BASE_URL, then https://api.typesafe.ai.
+    attr_accessor :base_url
+    # Default model; falls back to TYPESAFE_DEFAULT_MODEL, then jev-latest.
+    attr_accessor :model
+    # Timeout per HTTP attempt in seconds. Default: 10.
+    attr_accessor :timeout
+    # Additional headers sent with every request.
+    attr_accessor :headers
+    # Logger; defaults to a Logger on $stderr.
+    attr_accessor :logger
+    # Log level; falls back to TYPESAFE_LOG_LEVEL, then :warn.
+    attr_accessor :log_level
+    # Retry policy: a RetryPolicy, or a Hash of overrides on the SDK defaults.
+    attr_accessor :retry_policy
+    # Custom transport responding to #call(request); defaults to Net::HTTP.
+    attr_accessor :transport
+
+    def initialize(api_key: nil, base_url: nil, model: nil, timeout: nil, headers: nil, logger: nil,
+                   log_level: nil, retry_policy: nil, transport: nil)
+      @api_key = api_key
+      @base_url = base_url
+      @model = model
+      @timeout = timeout
+      @headers = headers
+      @logger = logger
+      @log_level = log_level
+      @retry_policy = retry_policy
+      @transport = transport
+    end
+
+    # The explicitly set options, suitable for splatting into Client.new.
+    def to_h
+      {
+        api_key: api_key, base_url: base_url, model: model, timeout: timeout, headers: headers,
+        logger: logger, log_level: log_level, retry_policy: retry_policy, transport: transport
+      }.compact
+    end
+
+    # Apply environment fallbacks and defaults, validate, and return a frozen copy.
+    def resolve(env: ENV)
+      resolved = dup
+      resolved.api_key = resolve_api_key(env)
+      resolved.base_url = resolve_base_url(env)
+      resolved.model = resolve_model(env)
+      resolved.timeout = resolve_timeout
+      resolved.headers = resolve_headers
+      resolved.retry_policy = RetryPolicy.from(retry_policy)
+      resolve_logging(resolved, env)
+      resolved.freeze
+    end
+
+    # The Logger severity matching #log_level.
+    def logger_severity
+      LOG_LEVELS.fetch(log_level.to_s.downcase.to_sym, Logger::WARN)
+    end
+
+    private
+
+    def resolve_api_key(env)
+      value = api_key.nil? ? Util.env_value(env, Constants::API_KEY_ENV) : api_key.to_s.strip
+      return value unless Util.blank?(value)
+
+      raise ConfigurationError,
+            "No API key provided. Pass api_key: to TypeSafe::Client.new or set #{Constants::API_KEY_ENV}."
+    end
+
+    def resolve_base_url(env)
+      value = Util.blank?(base_url) ? Util.env_value(env, Constants::BASE_URL_ENV) : base_url.to_s.strip
+      value ||= Constants::DEFAULT_BASE_URL
+      uri = URI.parse(value)
+      raise ConfigurationError, "base_url must be an http(s) URL, got #{value.inspect}" unless uri.is_a?(URI::HTTP)
+
+      value.sub(%r{/+\z}, "")
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "base_url must be an http(s) URL, got #{value.inspect}"
+    end
+
+    def resolve_model(env)
+      value = Util.blank?(model) ? Util.env_value(env, Constants::DEFAULT_MODEL_ENV) : model.to_s.strip
+      value || Constants::DEFAULT_MODEL
+    end
+
+    def resolve_timeout
+      value = timeout.nil? ? Constants::DEFAULT_TIMEOUT : timeout
+      unless value.is_a?(Numeric) && value.finite? && value.positive?
+        raise ConfigurationError, "timeout must be a positive number of seconds, got #{timeout.inspect}"
+      end
+
+      value
+    end
+
+    def resolve_headers
+      (headers || {}).each_with_object({}) { |(name, value), result| result[name.to_s] = value.to_s }
+    end
+
+    def resolve_logging(resolved, env)
+      resolved.log_level = resolve_log_level(env)
+      resolved.logger = logger || build_logger(resolved.log_level)
+    end
+
+    def resolve_log_level(env)
+      value = Util.blank?(log_level) ? Util.env_value(env, Constants::LOG_LEVEL_ENV) : log_level
+      value = (value || Constants::DEFAULT_LOG_LEVEL).to_s.downcase.to_sym
+      return value if LOG_LEVELS.key?(value)
+
+      raise ConfigurationError, "log_level must be one of #{LOG_LEVELS.keys.join(", ")}, got #{value.inspect}"
+    end
+
+    def build_logger(level)
+      logger = Logger.new($stderr, progname: "typesafe")
+      logger.level = LOG_LEVELS.fetch(level)
+      logger
+    end
+  end
+end

data/lib/typesafe/constants.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  # Environment variable names, client defaults, endpoint paths, and header names.
+  #
+  # Values mirror the official TypeSafe Python and JavaScript SDKs so that
+  # configuration behaves the same across languages.
+  module Constants
+    # Environment variable holding the API key.
+    API_KEY_ENV = "TYPESAFE_API_KEY"
+    # Environment variable overriding the API base URL.
+    BASE_URL_ENV = "TYPESAFE_BASE_URL"
+    # Environment variable overriding the default model.
+    DEFAULT_MODEL_ENV = "TYPESAFE_DEFAULT_MODEL"
+    # Environment variable overriding the log level.
+    LOG_LEVEL_ENV = "TYPESAFE_LOG_LEVEL"
+
+    # Default API base URL.
+    DEFAULT_BASE_URL = "https://api.typesafe.ai"
+    # Default model alias.
+    DEFAULT_MODEL = "jev-latest"
+    # Default timeout in seconds for each HTTP attempt.
+    DEFAULT_TIMEOUT = 10.0
+    # Default log level.
+    DEFAULT_LOG_LEVEL = :warn
+
+    # Path of the System One evaluation endpoint.
+    SYSTEM_ONE_PATH = "/v1/systemone"
+    # Path of the model listing endpoint.
+    MODELS_PATH = "/v1/models"
+
+    # Identifier sent in User-Agent and X-TypeSafe-SDK headers.
+    SDK_NAME = "typesafe-ruby"
+    # MIME type used for request and response bodies.
+    JSON_CONTENT_TYPE = "application/json"
+
+    # HTTP header names used by the client.
+    module Headers
+      AUTHORIZATION = "Authorization"
+      ACCEPT = "Accept"
+      CONTENT_TYPE = "Content-Type"
+      USER_AGENT = "User-Agent"
+      SDK = "X-TypeSafe-SDK"
+      RUNTIME = "X-TypeSafe-Runtime"
+      RETRY_COUNT = "X-TypeSafe-Retry-Count"
+      REQUEST_ID = "x-typesafe-request-id"
+    end
+  end
+end

data/lib/typesafe/errors.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  # Base class for every error raised by this gem.
+  class Error < StandardError; end
+
+  # Raised when the client cannot be configured, for example when the API key is missing.
+  class ConfigurationError < Error; end
+
+  # Raised before a request is sent when questions or state are malformed.
+  class ValidationError < Error; end
+
+  # An unsuccessful HTTP response, carrying the status, decoded body, headers and endpoint.
+  class APIError < Error
+    # HTTP status code.
+    attr_reader :status
+    # JSON body, plain text, or nil for an empty body.
+    attr_reader :body
+    # Response headers with lower-cased names.
+    attr_reader :headers
+    # Request method and URL without credentials, e.g. "POST https://api.typesafe.ai/v1/systemone".
+    attr_reader :endpoint
+
+    def initialize(message = nil, status: nil, body: nil, headers: {}, endpoint: nil)
+      @status = status
+      @body = body
+      @headers = Util.normalize_headers(headers)
+      @endpoint = endpoint
+      super(message || self.class.build_message(status: status, body: body, endpoint: endpoint, request_id: request_id))
+    end
+
+    # The x-typesafe-request-id response header.
+    def request_id
+      @headers[Constants::Headers::REQUEST_ID]
+    end
+
+    # Build the error subclass matching the response status.
+    def self.from_response(response)
+      class_for_status(response.status).new(
+        status: response.status,
+        body: response.json || (response.body.empty? ? nil : response.body),
+        headers: response.headers,
+        endpoint: response.request&.endpoint
+      )
+    end
+
+    def self.class_for_status(status)
+      STATUS_CLASSES.fetch(status) { (500..599).cover?(status) ? InternalServerError : APIError }
+    end
+
+    def self.build_message(status:, body:, endpoint:, request_id:)
+      head = [status && "[#{status}]", endpoint].compact.join(" ")
+      summary = Util.summarize_body(body)
+      message = [head, summary].reject(&:empty?).join(": ")
+      message = "API request failed" if message.empty?
+      request_id ? "#{message} (request_id: #{request_id})" : message
+    end
+  end
+
+  # The request was invalid (400).
+  class BadRequestError < APIError; end
+  # Authentication failed (401).
+  class AuthenticationError < APIError; end
+  # Access was denied (403).
+  class PermissionDeniedError < APIError; end
+  # The resource was not found (404).
+  class NotFoundError < APIError; end
+  # The request failed server-side validation (422).
+  class UnprocessableEntityError < APIError; end
+  # The server failed to process the request (5xx).
+  class InternalServerError < APIError; end
+  # TypeSafe is temporarily overloaded (529).
+  class OverloadedError < InternalServerError; end
+
+  # The rate limit was exceeded (429).
+  class RateLimitError < APIError
+    # The wait requested by the server in seconds, from retry-after-ms or Retry-After.
+    def retry_after
+      Util.parse_retry_after(headers)
+    end
+  end
+
+  # A successful HTTP response whose body was missing or structurally invalid required data.
+  class APIResponseValidationError < APIError
+    # Dotted path to the offending field, such as "answers.tone.confidence".
+    attr_reader :field_path
+
+    def initialize(message = nil, field_path:, **options)
+      @field_path = field_path
+      super(message || "Invalid response field #{field_path}", **options)
+    end
+  end
+
+  APIError::STATUS_CLASSES = {
+    400 => BadRequestError,
+    401 => AuthenticationError,
+    403 => PermissionDeniedError,
+    404 => NotFoundError,
+    422 => UnprocessableEntityError,
+    429 => RateLimitError,
+    529 => OverloadedError
+  }.freeze
+
+  # A request failed without an HTTP response.
+  class APIConnectionError < Error; end
+
+  # A request exceeded its configured timeout.
+  class APITimeoutError < APIConnectionError
+    # The timeout applied to the request, in seconds.
+    attr_reader :timeout
+
+    def initialize(message = nil, timeout: nil)
+      @timeout = timeout
+      super(message || "Request timed out after #{timeout}s")
+    end
+  end
+end

data/lib/typesafe/http/connection_manager.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module HTTP
+    # Keeps one open Net::HTTP connection per scheme, host and port so that consecutive
+    # requests reuse the TCP and TLS session. Net::HTTP is not thread safe, so the transport
+    # holds one manager per thread.
+    #
+    # Connections idle for longer than IDLE_TIMEOUT are closed before reuse, and every
+    # connection is dropped after a fork so child processes never share a parent's socket.
+    class ConnectionManager
+      IDLE_TIMEOUT = 120
+
+      def initialize(clock: nil)
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @connections = {}
+        @touched = {}
+        @pid = Process.pid
+      end
+
+      # An open connection for the URI with the given timeout applied.
+      def connection_for(uri, timeout:)
+        clear if @pid != Process.pid
+        key = key_for(uri)
+        drop(key) if @connections.key?(key) && (now - @touched[key]) > IDLE_TIMEOUT
+
+        connection = (@connections[key] ||= start(uri, timeout))
+        connection.open_timeout = timeout
+        connection.read_timeout = timeout
+        connection.write_timeout = timeout
+        @touched[key] = now
+        connection
+      end
+
+      # Close and forget the connection for the URI, typically after a network error.
+      def discard(uri)
+        drop(key_for(uri))
+      end
+
+      # Close and forget every connection.
+      def clear
+        @connections.each_key.to_a.each { |key| drop(key) }
+        @pid = Process.pid
+      end
+
+      def size
+        @connections.size
+      end
+
+      private
+
+      def now
+        @clock.call
+      end
+
+      def key_for(uri)
+        "#{uri.scheme}://#{uri.host}:#{uri.port}"
+      end
+
+      def start(uri, timeout)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+        http.start
+      end
+
+      def drop(key)
+        connection = @connections.delete(key)
+        @touched.delete(key)
+        return unless connection
+
+        begin
+          connection.finish if connection.started?
+        rescue IOError
+          # Already closed by the server or the runtime; nothing to release.
+        end
+      end
+    end
+  end
+end