butler-http 0.1.0

data/lib/butler/async.rb

@@ -0,0 +1,130 @@
+require "async"
+require "async/barrier"
+
+# Thin aliases over the `async` gem's own structured-concurrency primitives
+# rather than a reimplementation — Async::Task/Async::Barrier already give
+# exactly the parent/child task lifecycle (exiting the parent
+# resolves/cancels children, releases resources, propagates exceptions) the
+# PRD describes. See Butler::Client#async for how these are actually used.
+class Butler
+  module Async
+    Task = ::Async::Task
+    Barrier = ::Async::Barrier
+
+    # The object handed to a `client.async { |tasks| ... }` block, so
+    # callers never need to reach for ::Async::Barrier directly.
+    class TaskGroup
+      def initialize(barrier)
+        @barrier = barrier
+      end
+
+      # Spawns a child task; returns an ::Async::Task (#wait blocks for its
+      # result and re-raises any exception it raised).
+      def async(&block)
+        @barrier.async(&block)
+      end
+    end
+
+    class Cancellation
+      def initialize(task)
+        @task = task
+      end
+
+      def cancel!
+        @task.stop
+      end
+
+      def cancelled?
+        @task.stopping? || @task.stopped?
+      end
+    end
+
+    # Backs every *bare* `client.get`/`client.post`/etc call (one made from
+    # outside any existing reactor — the common synchronous case). Spinning
+    # up a full Async::Reactor (event loop, I/O selector, Fiber scheduler
+    # registration) and tearing it down again on every single such call is
+    # real, measurable overhead on top of the request itself — this instead
+    # starts exactly one reactor, lazily, on first use, and keeps it alive
+    # for the life of the process, dispatching each call into it as a
+    # cheap child task instead. The calling thread (an arbitrary OS thread
+    # — Puma workers, a plain script, anything) blocks on a plain
+    # Thread::Queue until that task's result (or exception) comes back,
+    # so this is invisible from the outside: still fully synchronous from
+    # the caller's point of view.
+    #
+    # Never touched when Client#request is called from *inside* an
+    # existing reactor (nested client.async, or a Fiber-scheduler-based
+    # app server like Falcon) — running inline on the current task there
+    # is strictly better than hopping through this at all.
+    class BackgroundReactor
+      Job = Struct.new(:block, :results)
+
+      def initialize
+        @jobs = ::Queue.new
+        @mutex = Mutex.new
+        @thread = nil
+        @pid = nil
+      end
+
+      def call(&block)
+        ensure_running!
+        results = ::Queue.new
+        @jobs << Job.new(block, results)
+        status, value = results.pop
+        status == :error ? (raise value) : value
+      end
+
+      # Called after a fork (see Butler.reset_connections!) so a forked
+      # worker doesn't try to keep using its parent's reactor thread —
+      # Ruby thread objects don't survive fork(), only the forking thread
+      # does. #call also checks the pid itself on every dispatch, so this
+      # is a defensive fast path more than a strict requirement.
+      def reset!
+        @mutex.synchronize do
+          @thread = nil
+          @pid = nil
+        end
+      end
+
+      private
+
+      def ensure_running!
+        return if running?
+
+        @mutex.synchronize do
+          return if running?
+
+          @pid = ::Process.pid
+          @thread = ::Thread.new { run }
+        end
+      end
+
+      def running?
+        @thread&.alive? && @pid == ::Process.pid
+      end
+
+      def run
+        Async do |parent|
+          loop do
+            job = @jobs.pop
+            parent.async do
+              # Deliberately `rescue Exception`, not StandardError: whatever
+              # happens here, *something* must always be pushed to
+              # job.results, or the caller's #call blocks forever on a
+              # Queue nothing will ever write to again.
+              begin
+                job.results << [:ok, job.block.call]
+              rescue Exception => e # rubocop:disable Lint/RescueException
+                job.results << [:error, e]
+              end
+            end
+          end
+        end
+      end
+    end
+
+    def self.background
+      @background ||= BackgroundReactor.new
+    end
+  end
+end

data/lib/butler/body.rb

@@ -0,0 +1,130 @@
+# Butler::Body::Base and its four concrete shapes are how request bodies are
+# represented internally *before* they reach the transport layer — Transport
+# is the only place that ever needs to know how to turn one into wire bytes,
+# so nothing above it (Client, Request) needs to change if a fifth body kind
+# is added later.
+module Butler::Body
+  def self.wrap(options)
+    if options.key?(:json)
+      JSONBody.new(options[:json])
+    elsif options.key?(:form)
+      StringBody.new(::URI.encode_www_form(options[:form]), content_type: "application/x-www-form-urlencoded")
+    elsif options.key?(:stream)
+      StreamBody.new(options[:stream])
+    elsif options.key?(:io)
+      IOBody.new(options[:io])
+    elsif options.key?(:body)
+      wrap_raw(options[:body])
+    end
+  end
+
+  def self.wrap_raw(raw)
+    case raw
+    when IO, StringIO
+      IOBody.new(raw)
+    when Hash
+      StringBody.new(::URI.encode_www_form(raw), content_type: "application/x-www-form-urlencoded")
+    else
+      StringBody.new(raw.to_s)
+    end
+  end
+
+  class Base
+    def content_type
+      nil
+    end
+
+    def empty?
+      false
+    end
+
+    # Yields successive byte-string chunks. Subclasses must implement this;
+    # #to_s (used by anything that just wants the whole body as one string)
+    # is derived from it for free.
+    def each
+      raise NotImplementedError
+    end
+
+    def to_s
+      buffer = +""
+      each { |chunk| buffer << chunk }
+      buffer
+    end
+  end
+
+  class StringBody < Base
+    attr_reader :content_type
+
+    def initialize(string, content_type: nil)
+      @string = string.to_s
+      @content_type = content_type
+    end
+
+    def empty?
+      @string.empty?
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      yield @string unless @string.empty?
+    end
+
+    def to_s
+      @string
+    end
+  end
+
+  class JSONBody < Base
+    def initialize(object)
+      @json = object.to_json
+    end
+
+    def content_type
+      "application/json"
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      yield @json
+    end
+
+    def to_s
+      @json
+    end
+  end
+
+  # Wraps an already-open IO/StringIO (e.g. a file upload) and streams it in
+  # chunks rather than reading it all into memory up front.
+  class IOBody < Base
+    CHUNK_SIZE = 16 * 1024
+
+    def initialize(io)
+      @io = io
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      @io.rewind if @io.respond_to?(:rewind)
+      while (chunk = @io.read(CHUNK_SIZE))
+        yield chunk
+      end
+    end
+  end
+
+  # Wraps a caller-supplied Enumerable of chunks for streaming uploads Butler
+  # itself has no opinion about the shape of (e.g. a lazily-generated body).
+  class StreamBody < Base
+    def initialize(enumerable)
+      @enumerable = enumerable
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @enumerable.each(&block)
+    end
+  end
+end

data/lib/butler/client.rb

@@ -0,0 +1,206 @@
+# The public entry point. Builds one middleware pipeline at construction
+# time (Security -> Telemetry -> [custom middlewares] -> Timeout ->
+# CircuitBreaker -> Retry -> [terminal: ConnectionPool + Transport]) and
+# reuses it for every request; redirects are handled by a loop in #request
+# itself rather than as a pipeline step, since each hop needs a fresh
+# HostPolicy check and independent security/telemetry/circuit-breaker
+# accounting against the *new* host, while still sharing one Deadline
+# across the whole call.
+#
+#   client = Butler::Client.new(base_url: "https://api.example.com")
+#   response = client.get("/users")
+#
+#   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::Client
+  HTTP_METHODS = %i[get post put patch delete head options].freeze
+
+  attr_reader :configuration
+
+  def initialize(**options)
+    @configuration = Butler.configuration.dup.apply(options)
+    @connection_pool = Butler::ConnectionPool.new(@configuration)
+    @circuit_breaker = Butler::Resilience::CircuitBreaker.new
+    @retry_policy = Butler::Resilience::RetryPolicy.new
+    @custom_middlewares = []
+    @pipeline = build_pipeline
+    Butler.register_client(self)
+  end
+
+  HTTP_METHODS.each do |http_method|
+    define_method(http_method) do |path = nil, **opts|
+      request(http_method, path, **opts)
+    end
+  end
+
+  # Inserts a custom middleware between Telemetry and Timeout — third-party
+  # extensions can inspect/modify/short-circuit/observe/transform a request
+  # without core resilience/security features having to be expressed as
+  # middleware themselves.
+  def use(middleware)
+    @custom_middlewares << middleware
+    @pipeline = build_pipeline
+    self
+  end
+
+  # Whether this runs inline or gets dispatched depends on whether we're
+  # already inside a reactor:
+  #
+  # - Called from inside one (a nested client.async call, or a
+  #   Fiber-scheduler-based app server like Falcon) — #perform_request just
+  #   runs directly on the current task. No new task, no reactor, nothing
+  #   to tear down.
+  # - Called from ordinary synchronous code (the common case — a bare
+  #   `client.get("/users")` with no surrounding client.async block) — it's
+  #   dispatched into Butler::Async.background, a single reactor shared by
+  #   every Butler::Client in the process and lazily started once, rather
+  #   than spinning up and tearing down a brand new one on *every* such
+  #   call. That per-call setup/teardown is real, measurable overhead for
+  #   back-to-back sequential calls; paying it once instead is what makes
+  #   this fast without changing anything about how it looks to call.
+  #
+  # Either way this is fully synchronous from the caller's perspective, and
+  # neither path ever trips `async`'s own "Task may have ended with
+  # unhandled exception" diagnostic logging for a routinely-handled Butler
+  # error (a 4xx/5xx with raise_on_error, TooManyRedirectsError, a stubbed
+  # exception in tests): the inline path never opens a new task boundary
+  # for the exception to cross, and BackgroundReactor#call catches inside
+  # its own task and re-raises back on the calling thread afterward.
+  def request(method, path = nil, **opts)
+    perform = -> { perform_request(method, path, opts) }
+    ::Async::Task.current? ? perform.call : Butler::Async.background.call(&perform)
+  end
+
+  # Structured Fiber concurrency:
+  #
+  #   client.async do |tasks|
+  #     a = tasks.async { client.get("/a") }
+  #     b = tasks.async { client.get("/b") }
+  #     [a.wait, b.wait]
+  #   end
+  #
+  # Same inline-vs-background-reactor dispatch as #request, for the same
+  # reason. The ensure block resolves any child the caller forgot to #wait
+  # and cancels anything still running after an exception, so exiting the
+  # block always leaves every child task/connection resolved or cancelled.
+  def async(&block)
+    raise ArgumentError, "block required" unless block
+
+    perform = lambda do
+      barrier = Butler::Async::Barrier.new
+      begin
+        block.call(Butler::Async::TaskGroup.new(barrier))
+      ensure
+        barrier.wait
+        barrier.stop
+      end
+    end
+
+    ::Async::Task.current? ? perform.call : Butler::Async.background.call(&perform)
+  end
+
+  # Closes every pooled connection this client is holding open. Called
+  # automatically post-fork by Butler::Rails::Railtie; safe to call
+  # manually otherwise (e.g. before a process exits, or to force
+  # reconnection after a known upstream restart).
+  def reset_connections!
+    @connection_pool.reset!
+  end
+
+  private
+
+  def perform_request(method, path, opts)
+    config = per_call_config(opts)
+    deadline = Butler::Resilience::Deadline.start(opts[:deadline] || configuration.deadline)
+    uri = Butler::URI.build(configuration.base_url, path, opts[:params])
+    current_method = method.to_s.upcase
+    current_opts = opts
+    redirects = 0
+
+    loop do
+      butler_request = Butler::Request.build(method: current_method, uri: uri, options: current_opts, config: config)
+      context = Butler::Pipeline::Context.new(client: self, request: butler_request, config: config, deadline: deadline)
+      response = @pipeline.call(context)
+
+      return maybe_raise(response) unless response.redirect? && configuration.follow_redirects
+
+      location = response.headers["location"]
+      return maybe_raise(response) unless location
+
+      if redirects >= configuration.max_redirects
+        raise Butler::Errors::TooManyRedirectsError, "exceeded #{configuration.max_redirects} redirects for #{uri}"
+      end
+
+      new_uri = uri.merge(location)
+      if Butler::Security::RedirectPolicy.strip_credentials?(configuration, uri, new_uri)
+        current_opts = current_opts.merge(headers: strip_credential_headers(current_opts[:headers]), basic_auth: nil)
+      end
+      current_method = Butler::Security::RedirectPolicy.method_for(response.status, current_method)
+      uri = new_uri
+      redirects += 1
+    end
+  end
+
+  # A per-call http_version: override needs its own Configuration — duped
+  # once per call, never mutating the shared client-level one — because
+  # it has to flow all the way through Request.build/Pipeline::Context
+  # into ConnectionPool's fingerprint and Security::TLS's ALPN selection,
+  # exactly like the client-level default already does (see
+  # Configuration#http_version). That's what lets a request pinned to
+  # :http1 get its own pooled connection rather than reusing one that
+  # negotiated :http2 for the same origin, and vice versa. No-op (returns
+  # the shared configuration as-is, no dup) when the call doesn't ask for
+  # an override.
+  def per_call_config(opts)
+    return configuration unless opts.key?(:http_version)
+
+    configuration.dup.tap { |c| c.http_version = opts[:http_version] }
+  end
+
+  def maybe_raise(response)
+    return response unless configuration.raise_on_error && response.error?
+
+    klass = response.client_error? ? Butler::Errors::ClientError : Butler::Errors::ServerError
+    raise klass, response
+  end
+
+  def strip_credential_headers(headers)
+    stripped = Butler::Headers.coerce(headers || {}).dup
+    stripped.delete("authorization")
+    stripped.delete("cookie")
+    stripped
+  end
+
+  def build_pipeline
+    middlewares = [
+      Butler::Pipeline::Middlewares::SecurityMiddleware.new,
+      Butler::Pipeline::Middlewares::TelemetryMiddleware.new,
+      *@custom_middlewares,
+      Butler::Pipeline::Middlewares::TimeoutMiddleware.new,
+      Butler::Pipeline::Middlewares::CircuitBreakerMiddleware.new(@circuit_breaker),
+      Butler::Pipeline::Middlewares::RetryMiddleware.new(@retry_policy),
+    ]
+
+    terminal = lambda do |context|
+      connection = @connection_pool.acquire(context.request.uri, context.config)
+      timeout = attempt_timeout(context.config, context.deadline)
+      Butler::Transport.current.call(connection, context.request, context.config, timeout: timeout)
+    end
+
+    Butler::Pipeline::Chain.new(middlewares, terminal: terminal)
+  end
+
+  # The per-attempt ceiling Transport enforces around one request/response
+  # round-trip: config.request_timeout if set, otherwise the larger of
+  # read_timeout/write_timeout (Async::HTTP::Client performs the whole
+  # round-trip as one call, so read and write can't be timed independently
+  # once a request reaches Transport::Async) — always additionally capped
+  # by however much of the total deadline remains.
+  def attempt_timeout(config, deadline)
+    per_attempt = config.request_timeout || [config.read_timeout, config.write_timeout].compact.max
+    [per_attempt, deadline.remaining].compact.min
+  end
+end

data/lib/butler/configuration.rb

@@ -0,0 +1,161 @@
+# Every option Butler::Client understands, with production-safe defaults:
+# TLS/hostname verification on, redirects followed but bounded, resilience
+# (retry/circuit-breaker) on, no total deadline (unbounded) unless asked for.
+#
+# Butler.configuration is a process-wide template; Butler::Client.new(**opts)
+# takes a private #dup of it (see #initialize_copy below — every nested
+# options object is deep-copied too) and applies +opts+ on top, so
+# per-client configuration never leaks back into the global default or
+# across sibling clients.
+class Butler::Configuration
+  class RetryOptions
+    attr_accessor :max_attempts, :retryable_status_codes, :backoff, :base_delay, :max_delay, :jitter
+
+    def initialize
+      @max_attempts = 2
+      @retryable_status_codes = [408, 425, 429, 500, 502, 503, 504].freeze
+      @backoff = :exponential
+      @base_delay = 0.1
+      @max_delay = 5.0
+      @jitter = true
+    end
+  end
+
+  class CircuitBreakerOptions
+    attr_accessor :enabled, :scope, :failure_threshold, :recovery_timeout, :max_tracked_hosts
+
+    def initialize
+      @enabled = true
+      @scope = :host # or :client, to share one breaker across every origin
+      @failure_threshold = 5
+      @recovery_timeout = 30
+      @max_tracked_hosts = 256
+    end
+  end
+
+  class SecurityOptions
+    attr_accessor :verify_tls, :allowed_hosts, :blocked_hosts,
+                  :max_response_size, :max_header_size, :strip_credentials_on_redirect
+
+    def initialize
+      @verify_tls = true
+      @allowed_hosts = nil # nil = no allow-list restriction
+      @blocked_hosts = []
+      @max_response_size = 50 * 1024 * 1024
+      @max_header_size = 64 * 1024
+      @strip_credentials_on_redirect = true
+    end
+
+    def initialize_copy(source)
+      super
+      @blocked_hosts = source.blocked_hosts.dup
+      @allowed_hosts = source.allowed_hosts&.dup
+    end
+  end
+
+  class PoolOptions
+    attr_accessor :max_connections, :idle_timeout
+
+    def initialize
+      @max_connections = 100
+      @idle_timeout = 60
+    end
+  end
+
+  class TelemetryOptions
+    attr_accessor :enabled, :opentelemetry, :logger
+
+    def initialize
+      @enabled = true
+      @opentelemetry = :auto
+      @logger = nil
+    end
+  end
+
+  attr_accessor :base_url, :user_agent,
+                :connect_timeout, :read_timeout, :write_timeout, :request_timeout,
+                :deadline,
+                :follow_redirects, :max_redirects,
+                :http_version, :proxy, :raise_on_error
+  attr_reader :default_headers, :retry, :circuit_breaker, :security, :pool, :telemetry
+
+  def initialize
+    @base_url = nil
+    @default_headers = Butler::Headers.new
+    @user_agent = "Butler/#{Butler::VERSION}"
+
+    @connect_timeout = 5
+    @read_timeout = 10
+    @write_timeout = 10
+    # An explicit override for the per-attempt timeout Transport enforces
+    # around one request/response round-trip. Left unset, that budget is
+    # derived from read_timeout/write_timeout instead (see
+    # Client#attempt_timeout) — read and write aren't independently
+    # timed once the request reaches Transport::Async, since
+    # Async::HTTP::Client performs the whole round-trip as one call.
+    @request_timeout = nil
+
+    @deadline = nil
+
+    @follow_redirects = true
+    @max_redirects = 5
+
+    # :auto | :http1 | :http2 — :auto offers both via ALPN and lets the
+    # server pick (HTTP/2 whenever it supports it, HTTP/1.1 otherwise);
+    # :http1/:http2 force that choice. Overridable per call — see
+    # Client#request's http_version: option.
+    @http_version = :auto
+    @proxy = nil
+    @raise_on_error = false
+
+    @retry = RetryOptions.new
+    @circuit_breaker = CircuitBreakerOptions.new
+    @security = SecurityOptions.new
+    @pool = PoolOptions.new
+    @telemetry = TelemetryOptions.new
+  end
+
+  def initialize_copy(source)
+    super
+    @default_headers = source.default_headers.dup
+    @retry = source.retry.dup
+    @circuit_breaker = source.circuit_breaker.dup
+    @security = source.security.dup
+    @pool = source.pool.dup
+    @telemetry = source.telemetry.dup
+  end
+
+  # Applies a Client.new(**options) hash on top of this (already-duped)
+  # configuration. Nested option groups (retry:, circuit_breaker:, security:,
+  # pool:, telemetry:) merge into the existing sub-object rather than
+  # replacing it, so callers only need to specify the keys they want to
+  # override.
+  NESTED_OPTIONS = %i[retry circuit_breaker security pool telemetry].freeze
+
+  def apply(options)
+    options.each do |key, value|
+      if NESTED_OPTIONS.include?(key)
+        merge_nested(public_send(key), value)
+      elsif key == :headers
+        Butler::Headers.coerce(value || {}).each { |k, v| default_headers[k] = v }
+      elsif respond_to?("#{key}=")
+        public_send("#{key}=", value)
+      else
+        raise Butler::Errors::ConfigurationError, "unknown Butler::Client option #{key.inspect}"
+      end
+    end
+    self
+  end
+
+  private
+
+  def merge_nested(target, value)
+    return unless value
+
+    value.each do |k, v|
+      raise Butler::Errors::ConfigurationError, "unknown option #{k.inspect}" unless target.respond_to?("#{k}=")
+
+      target.public_send("#{k}=", v)
+    end
+  end
+end

data/lib/butler/connection.rb

@@ -0,0 +1,21 @@
+# One origin's live connection state: the underlying async_client is an
+# Async::HTTP::Client for the real transport (already doing its own HTTP/1.1
+# vs HTTP/2 multiplexing and per-origin pooling internally) or nil for
+# Butler::Testing::FakeTransport, which never touches it. Butler::Connection
+# itself is the only thing ConnectionPool hands around — it never leaks the
+# Async::HTTP::Client type further than butler/transport.rb.
+class Butler::Connection
+  attr_reader :origin_key, :async_client, :http_version
+
+  def initialize(origin_key:, async_client:, http_version:)
+    @origin_key = origin_key
+    @async_client = async_client
+    @http_version = http_version
+  end
+
+  def close
+    @async_client&.close
+  rescue StandardError
+    nil
+  end
+end