butler-http 0.1.0

data/lib/butler/uri.rb

@@ -0,0 +1,77 @@
+# Wraps ::URI to add the handful of things Butler needs repeatedly: joining
+# a client's base_url with a per-request path, merging a params: hash into
+# the query string, and the origin/cross-origin comparisons the connection
+# pool and redirect/credential-stripping logic depend on.
+class Butler::URI
+  attr_reader :uri
+
+  def self.build(base_url, path = nil, params = nil)
+    resolved = resolve(base_url, path)
+    new(::URI.parse(resolved)).with_params(params)
+  end
+
+  def self.resolve(base_url, path)
+    if path.nil? || path.to_s.empty?
+      base_url.to_s
+    elsif path.to_s =~ %r{\Ahttps?://}i
+      path.to_s
+    elsif base_url
+      ::URI.join(base_url.to_s, path.to_s).to_s
+    else
+      path.to_s
+    end
+  end
+  private_class_method :resolve
+
+  def initialize(uri)
+    @uri = uri
+  end
+
+  def with_params(params)
+    return self if params.nil? || params.empty?
+
+    existing = uri.query ? ::URI.decode_www_form(uri.query) : []
+    new_uri = uri.dup
+    new_uri.query = ::URI.encode_www_form(existing + params.to_a)
+    self.class.new(new_uri)
+  end
+
+  def scheme
+    uri.scheme
+  end
+
+  def host
+    uri.host
+  end
+
+  def port
+    uri.port
+  end
+
+  # "scheme://host:port" — the key the connection pool groups connections by.
+  def origin_key
+    "#{scheme}://#{host}:#{port}"
+  end
+
+  # The path+query Butler sends on the wire (never the full absolute URL).
+  def request_target
+    target = uri.path.to_s
+    target = "/" if target.empty?
+    target += "?#{uri.query}" if uri.query
+    target
+  end
+
+  def cross_origin?(other)
+    origin_key != other.origin_key
+  end
+
+  # Resolves a redirect's Location header (absolute or relative) against
+  # this URI.
+  def merge(location)
+    self.class.new(uri.merge(location.to_s))
+  end
+
+  def to_s
+    uri.to_s
+  end
+end

data/lib/butler/version.rb

@@ -0,0 +1,3 @@
+class Butler
+  VERSION = "0.1.0"
+end

data/lib/butler.rb

@@ -0,0 +1,176 @@
+require "json"
+require "uri"
+require "openssl"
+require "logger"
+require "weakref"
+
+require_relative "butler/version"
+require_relative "butler/errors"
+require_relative "butler/headers"
+require_relative "butler/uri"
+require_relative "butler/body"
+require_relative "butler/stream"
+require_relative "butler/configuration"
+require_relative "butler/request"
+require_relative "butler/response"
+
+require_relative "butler/telemetry/instrumentation"
+require_relative "butler/telemetry/open_telemetry_bridge"
+require_relative "butler/telemetry/logger"
+
+require_relative "butler/security/tls"
+require_relative "butler/security/host_policy"
+require_relative "butler/security/redirect_policy"
+require_relative "butler/security/limits"
+
+require_relative "butler/resilience/deadline"
+require_relative "butler/resilience/timeout"
+require_relative "butler/resilience/backoff"
+require_relative "butler/resilience/retry_policy"
+require_relative "butler/resilience/circuit_breaker"
+
+require_relative "butler/testing/stub"
+require_relative "butler/testing/stub_registry"
+require_relative "butler/testing/fake_transport"
+require_relative "butler/testing"
+
+require_relative "butler/connection"
+require_relative "butler/transport"
+require_relative "butler/connection_pool"
+
+# QUIC/HTTP3 (see docs/architecture.md and the "hand-rolled HTTP/3 (QUIC)
+# support" plan): foundational packet-protection code only so far, not yet
+# reachable from Client/Transport.current or any config option — nothing
+# above this line depends on it, and requiring butler still works exactly
+# as before if you never touch Butler::Quic directly.
+require_relative "butler/quic/varint"
+require_relative "butler/quic/crypto/hkdf"
+require_relative "butler/quic/crypto/key_schedule"
+require_relative "butler/quic/crypto/aead"
+require_relative "butler/quic/crypto/header_protection"
+require_relative "butler/quic/packet"
+
+require_relative "butler/pipeline/context"
+require_relative "butler/pipeline/middleware"
+require_relative "butler/pipeline/chain"
+require_relative "butler/pipeline/middlewares/security_middleware"
+require_relative "butler/pipeline/middlewares/telemetry_middleware"
+require_relative "butler/pipeline/middlewares/timeout_middleware"
+require_relative "butler/pipeline/middlewares/circuit_breaker_middleware"
+require_relative "butler/pipeline/middlewares/retry_middleware"
+
+require_relative "butler/async"
+require_relative "butler/client"
+
+# Butler is a Fiber-native HTTP client: HTTP/1.1 and HTTP/2 (transparent ALPN
+# negotiation, multiplexed connection reuse via the `async`/`async-http`
+# gems), structured concurrency, built-in resilience (timeouts, deadlines,
+# retries with backoff+jitter, a circuit breaker), security-conscious
+# defaults, a small middleware pipeline, standalone instrumentation with
+# optional OpenTelemetry/Rails bridges, and native request stubbing for
+# tests — none of which ever exposes its underlying transport in the public
+# API. See docs/architecture.md for the full request lifecycle.
+#
+# Module-level calls (Butler.get/post/...) are the quickest way to reach
+# for Butler — they run against Butler.default_client, one lazily-built,
+# connection-pooled Butler::Client shared for the life of the process, so
+# repeated calls still get everything a real Client gives you (pooling,
+# retries, a circuit breaker) rather than reconnecting from scratch each
+# time:
+#
+#   response = Butler.get("https://api.example.com/users")
+#   response = Butler.post("https://api.example.com/users", json: { name: "Ram" })
+#
+# Reach for a real Butler::Client — everything above is built on it — once
+# you want per-instance configuration (a fixed base_url, custom retry
+# policy, middleware) rather than the shared default:
+#
+#   client = Butler::Client.new(base_url: "https://api.example.com")
+#   response = client.get("/users")
+#   response.status; response.headers; response.body; response.json
+#
+#   client.async do |tasks|
+#     users = tasks.async { client.get("/users") }
+#     orders = tasks.async { client.get("/orders") }
+#     { users: users.wait, orders: orders.wait }
+#   end
+class Butler
+  class << self
+    def configuration
+      @configuration ||= Butler::Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    # The Butler::Client every module-level call (Butler.get, Butler.post,
+    # ...) runs against — built lazily on first use and memoized for the
+    # life of the process, so it keeps its own connection pool/circuit
+    # breaker state across calls instead of reconnecting every time. It
+    # snapshots Butler.configuration as of whenever it's first built, the
+    # same way Butler::Client.new always has — call Butler.configure
+    # before your first module-level call (or Butler.reset_default_client!
+    # afterward) if you need later configuration changes to reach it.
+    def default_client
+      return @default_client if @default_client
+
+      @default_client_mutex ||= Mutex.new
+      @default_client_mutex.synchronize { @default_client ||= Butler::Client.new }
+    end
+
+    # Discards the memoized default client (its connections are closed
+    # first) so the next module-level call rebuilds one from whatever
+    # Butler.configuration looks like now. Mostly useful in tests, or after
+    # reconfiguring Butler well after the first module-level call already
+    # built one.
+    def reset_default_client!
+      return unless @default_client_mutex
+
+      @default_client_mutex.synchronize do
+        @default_client&.reset_connections!
+        @default_client = nil
+      end
+    end
+
+    Client::HTTP_METHODS.each do |http_method|
+      define_method(http_method) do |path = nil, **opts|
+        default_client.public_send(http_method, path, **opts)
+      end
+    end
+
+    def async(&block)
+      default_client.async(&block)
+    end
+
+    def register_client(client)
+      @clients_mutex ||= Mutex.new
+      @clients ||= []
+      @clients_mutex.synchronize { @clients << WeakRef.new(client) }
+    end
+
+    # Closes every tracked client's pooled connections and resets the
+    # shared background reactor (see Butler::Async.background). Called
+    # automatically post-fork by Butler::Rails::Railtie so a forked Puma
+    # worker never inherits a parent's live Async::HTTP::Client/reactor
+    # state — Ruby Thread objects don't survive fork(), only the forking
+    # thread does — safe to call manually otherwise (e.g. after a known
+    # upstream restart).
+    def reset_connections!
+      Butler::Async.background.reset!
+
+      return unless @clients
+
+      @clients_mutex.synchronize do
+        @clients.each do |ref|
+          ref.__getobj__.reset_connections! if ref.weakref_alive?
+        rescue WeakRef::RefError
+          nil
+        end
+        @clients.reject! { |ref| !ref.weakref_alive? }
+      end
+    end
+  end
+end
+
+require "butler/rails/railtie" if defined?(::Rails::Railtie)

data/sig/butler/client.rbs

@@ -0,0 +1,41 @@
+class Butler
+  class Client
+    HTTP_METHODS: Array[Symbol]
+
+    @configuration: Butler::Configuration
+    @connection_pool: Butler::ConnectionPool
+    @circuit_breaker: Butler::Resilience::CircuitBreaker
+    @retry_policy: Butler::Resilience::RetryPolicy
+    @custom_middlewares: Array[untyped]
+    @pipeline: Butler::Pipeline::Chain
+
+    attr_reader configuration: Butler::Configuration
+
+    def initialize: (**untyped options) -> void
+
+    def get: (?String? path, **untyped opts) -> Butler::Response
+    def post: (?String? path, **untyped opts) -> Butler::Response
+    def put: (?String? path, **untyped opts) -> Butler::Response
+    def patch: (?String? path, **untyped opts) -> Butler::Response
+    def delete: (?String? path, **untyped opts) -> Butler::Response
+    def head: (?String? path, **untyped opts) -> Butler::Response
+    def options: (?String? path, **untyped opts) -> Butler::Response
+
+    def use: (untyped middleware) -> self
+
+    def request: (String | Symbol method, ?String? path, **untyped opts) -> Butler::Response
+
+    def async: () { (Butler::Async::TaskGroup) -> untyped } -> untyped
+
+    def reset_connections!: () -> void
+
+    private
+
+    def perform_request: (String | Symbol method, String? path, Hash[Symbol, untyped] opts) -> Butler::Response
+    def per_call_config: (Hash[Symbol, untyped] opts) -> Butler::Configuration
+    def maybe_raise: (Butler::Response response) -> Butler::Response
+    def strip_credential_headers: (untyped headers) -> Butler::Headers
+    def build_pipeline: () -> Butler::Pipeline::Chain
+    def attempt_timeout: (Butler::Configuration config, Butler::Resilience::Deadline deadline) -> Numeric
+  end
+end

data/sig/butler/configuration.rbs

@@ -0,0 +1,63 @@
+class Butler
+  class Configuration
+    class RetryOptions
+      attr_accessor max_attempts: Integer
+      attr_accessor retryable_status_codes: Array[Integer]
+      attr_accessor backoff: Symbol
+      attr_accessor base_delay: Float
+      attr_accessor max_delay: Float
+      attr_accessor jitter: bool
+    end
+
+    class CircuitBreakerOptions
+      attr_accessor enabled: bool
+      attr_accessor scope: Symbol
+      attr_accessor failure_threshold: Integer
+      attr_accessor recovery_timeout: Integer
+      attr_accessor max_tracked_hosts: Integer
+    end
+
+    class SecurityOptions
+      attr_accessor verify_tls: bool
+      attr_accessor allowed_hosts: Array[String]?
+      attr_accessor blocked_hosts: Array[String]
+      attr_accessor max_response_size: Integer
+      attr_accessor max_header_size: Integer
+      attr_accessor strip_credentials_on_redirect: bool
+    end
+
+    class PoolOptions
+      attr_accessor max_connections: Integer
+      attr_accessor idle_timeout: Integer
+    end
+
+    class TelemetryOptions
+      attr_accessor enabled: bool
+      attr_accessor opentelemetry: Symbol | bool
+      attr_accessor logger: untyped
+    end
+
+    attr_accessor base_url: String?
+    attr_accessor user_agent: String?
+    attr_accessor connect_timeout: Numeric
+    attr_accessor read_timeout: Numeric
+    attr_accessor write_timeout: Numeric
+    attr_accessor request_timeout: Numeric?
+    attr_accessor deadline: Numeric?
+    attr_accessor follow_redirects: bool
+    attr_accessor max_redirects: Integer
+    attr_accessor http_version: Symbol
+    attr_accessor proxy: String?
+    attr_accessor raise_on_error: bool
+
+    attr_reader default_headers: Butler::Headers
+    attr_reader retry: RetryOptions
+    attr_reader circuit_breaker: CircuitBreakerOptions
+    attr_reader security: SecurityOptions
+    attr_reader pool: PoolOptions
+    attr_reader telemetry: TelemetryOptions
+
+    def initialize: () -> void
+    def apply: (Hash[Symbol, untyped] options) -> self
+  end
+end

data/sig/butler/errors.rbs

@@ -0,0 +1,67 @@
+class Butler
+  module Errors
+    class Error < StandardError
+    end
+
+    class ConfigurationError < Error
+    end
+
+    class RequestError < Error
+    end
+
+    class TooManyRedirectsError < RequestError
+    end
+
+    class HostNotAllowed < RequestError
+    end
+
+    class TransportError < Error
+    end
+
+    class ConnectionError < TransportError
+    end
+
+    class TimeoutError < TransportError
+    end
+
+    class TLSError < TransportError
+    end
+
+    class CertificateVerificationError < TLSError
+    end
+
+    class DNSFailure < TransportError
+    end
+
+    class ProtocolError < TransportError
+    end
+
+    class HTTPError < Error
+      attr_reader response: Butler::Response
+
+      def initialize: (Butler::Response response) -> void
+    end
+
+    class ClientError < HTTPError
+    end
+
+    class ServerError < HTTPError
+    end
+
+    class RetryExhausted < Error
+      attr_reader cause_response: Butler::Response?
+      attr_reader attempts: Integer?
+
+      def initialize: (String message, ?cause_response: Butler::Response?, ?attempts: Integer?) -> void
+    end
+
+    class CircuitOpen < Error
+    end
+
+    class Cancelled < Error
+    end
+
+    class LimitExceeded < Error
+    end
+  end
+end

data/sig/butler/headers.rbs

@@ -0,0 +1,22 @@
+class Butler
+  class Headers
+    include Enumerable[[String, String]]
+
+    def initialize: (?untyped pairs) -> void
+    def self.from_a: (Array[[String, String]] pairs) -> Butler::Headers
+    def self.coerce: (untyped headers) -> Butler::Headers
+
+    def []: (String | Symbol key) -> String?
+    def []=: (String | Symbol key, untyped value) -> untyped
+    def add: (String | Symbol key, untyped value) -> untyped
+    def key?: (String | Symbol key) -> bool
+    def delete: (String | Symbol key) -> String?
+    def values_at: (String | Symbol key) -> Array[String]
+    def each: () { (String, String) -> void } -> self
+    def to_a: () -> Array[[String, String]]
+    def to_h: () -> Hash[String, String]
+    def merge: (untyped other) -> Butler::Headers
+    def empty?: () -> bool
+    def size: () -> Integer
+  end
+end

data/sig/butler/request.rbs

@@ -0,0 +1,21 @@
+class Butler
+  class Request
+    attr_reader method: String
+    attr_reader uri: Butler::URI
+    attr_reader headers: Butler::Headers
+    attr_reader body: untyped
+    attr_reader idempotent: bool
+    attr_reader basic_auth: untyped
+
+    def self.build: (method: String | Symbol, uri: Butler::URI, options: Hash[Symbol, untyped], config: Butler::Configuration) -> Butler::Request
+
+    def initialize: (method: String, uri: Butler::URI, headers: Butler::Headers, ?body: untyped, ?idempotent: bool, ?basic_auth: untyped, ?stream: bool) -> void
+
+    def stream?: () -> bool
+    def origin_key: () -> String
+    def safe?: () -> bool
+    def retry_eligible?: () -> bool
+    def with_uri: (Butler::URI new_uri) -> Butler::Request
+    def without_credentials: () -> Butler::Request
+  end
+end

data/sig/butler/response.rbs

@@ -0,0 +1,28 @@
+class Butler
+  class Response
+    attr_reader uri: Butler::URI
+    attr_reader status: Integer
+    attr_reader headers: Butler::Headers
+
+    def initialize: (uri: Butler::URI, status: Integer, headers: Butler::Headers, body: untyped) -> void
+
+    def body: () -> String
+    def stream: () -> untyped
+    def code: () -> Integer
+
+    def informational?: () -> bool
+    def success?: () -> bool
+    def ok?: () -> bool
+    def redirect?: () -> bool
+    def client_error?: () -> bool
+    def server_error?: () -> bool
+    def error?: () -> bool
+
+    def content_type: () -> String
+    def json?: () -> bool
+    def json: () -> untyped
+    def parsed: () -> untyped
+
+    def to_s: () -> String
+  end
+end

data/sig/butler.rbs

@@ -0,0 +1,22 @@
+class Butler
+  VERSION: String
+
+  def self.configuration: () -> Butler::Configuration
+  def self.configure: () { (Butler::Configuration) -> void } -> void
+
+  def self.default_client: () -> Butler::Client
+  def self.reset_default_client!: () -> void
+
+  def self.get: (?String? path, **untyped opts) -> Butler::Response
+  def self.post: (?String? path, **untyped opts) -> Butler::Response
+  def self.put: (?String? path, **untyped opts) -> Butler::Response
+  def self.patch: (?String? path, **untyped opts) -> Butler::Response
+  def self.delete: (?String? path, **untyped opts) -> Butler::Response
+  def self.head: (?String? path, **untyped opts) -> Butler::Response
+  def self.options: (?String? path, **untyped opts) -> Butler::Response
+
+  def self.async: () { (Butler::Async::TaskGroup) -> untyped } -> untyped
+
+  def self.register_client: (Butler::Client client) -> void
+  def self.reset_connections!: () -> void
+end