butler-http 0.1.0

data/lib/butler/quic/packet.rb

@@ -0,0 +1,113 @@
+class Butler
+  module Quic
+    # Packet-level protection (RFC 9001 sections 5.3-5.4), scoped to the two
+    # operations Butler needs for one QUIC packet: turning an already-built
+    # plaintext header + payload into the bytes that go on the wire, and
+    # reversing that for a packet just read off the wire. Building the
+    # *plaintext* header itself (choosing dcid/scid/token, computing the
+    # Length field) for a packet Butler is about to send, and driving a
+    # whole connection's worth of these, is Stage 4/5 work — this module
+    # only protects/unprotects, it doesn't construct.
+    module Packet
+      module_function
+
+      # +header+ is the complete unprotected header, ending in the true
+      # (unmasked) packet-number bytes — exactly RFC 9001 Appendix A's
+      # "*_PLAIN_HEADER" vectors. +pn_length+ is how many trailing bytes of
+      # +header+ are the packet number (1-4 bytes, RFC 9000 section 17.1).
+      def protect(header:, payload:, packet_number:, pn_length:, key:, iv:, hp_key:, cipher_suite: :aes_128_gcm)
+        nonce = Crypto::AEAD.nonce_for(iv, packet_number)
+        protected_payload = Crypto::AEAD.seal(cipher_suite, key, nonce, payload, header)
+
+        sample = protected_payload.byteslice(0, Crypto::HeaderProtection::SAMPLE_LENGTH)
+        mask = Crypto::HeaderProtection.mask_for(cipher_suite, hp_key, sample)
+
+        pn_offset = header.bytesize - pn_length
+        protected_header = header.dup
+        protected_header.setbyte(0, protected_header.getbyte(0) ^ (mask.getbyte(0) & first_byte_mask(header)))
+        pn_length.times do |i|
+          protected_header.setbyte(pn_offset + i, protected_header.getbyte(pn_offset + i) ^ mask.getbyte(1 + i))
+        end
+
+        protected_header + protected_payload
+      end
+
+      # Parses a raw packet off the wire and returns
+      # [unprotected_header, plaintext_payload, packet_number]. +pn_offset+
+      # is the byte offset where the (still-protected) packet-number field
+      # begins — everything before it (version, connection IDs, token,
+      # Length) is never protected and so is readable without unmasking
+      # first. +expected_packet_number+ is the "largest packet number seen
+      # so far in this space, plus one" that RFC 9000 section 17.1's
+      # decoding algorithm needs to reconstruct the full packet number from
+      # its truncated wire encoding — for the very first packet in a space
+      # this is 0.
+      def unprotect(bytes, pn_offset:, expected_packet_number: 0, key:, iv:, hp_key:, cipher_suite: :aes_128_gcm)
+        # +bytes+ just came off a UDP socket — it's whatever an attacker (or
+        # a corrupted/truncated-in-transit datagram) sent, not something
+        # Butler built. Every offset below is a byteslice into attacker-
+        # controlled length, so this has to be checked *before* any of it
+        # reaches OpenSSL: an out-of-range start returns nil, not an empty
+        # string, and feeding nil/a short buffer to a cipher raises a raw
+        # TypeError or OpenSSL::Cipher::CipherError — neither is a
+        # Butler::Errors type, so nothing upstream could tell "malformed
+        # packet, drop it" apart from "the reactor task just crashed."
+        if pn_offset.negative? || bytes.bytesize < pn_offset + 4 + Crypto::HeaderProtection::SAMPLE_LENGTH
+          raise Butler::Errors::ProtocolError, "QUIC packet too short (#{bytes.bytesize} bytes) to unprotect at pn_offset #{pn_offset}"
+        end
+
+        sample = bytes.byteslice(pn_offset + 4, Crypto::HeaderProtection::SAMPLE_LENGTH)
+        mask = Crypto::HeaderProtection.mask_for(cipher_suite, hp_key, sample)
+
+        header = bytes.byteslice(0, pn_offset).dup
+        first_byte = bytes.getbyte(0) ^ (mask.getbyte(0) & first_byte_mask(header))
+        header.setbyte(0, first_byte)
+        pn_length = (first_byte & 0x03) + 1
+
+        # No separate length check needed before slicing the packet number
+        # or the AEAD ciphertext+tag below: pn_length is at most 4, and the
+        # guard above already required bytes.bytesize >= pn_offset + 4 + 16
+        # — which is always >= pn_offset + pn_length + AEAD::TAG_LENGTH for
+        # any pn_length in 1..4, so both slices below are already in-bounds.
+        pn_bytes = (0...pn_length).map { |i| bytes.getbyte(pn_offset + i) ^ mask.getbyte(1 + i) }
+        header << pn_bytes.pack("C*")
+        truncated_pn = pn_bytes.reduce(0) { |acc, b| (acc << 8) | b }
+        packet_number = decode_packet_number(truncated_pn, pn_length * 8, expected_packet_number)
+
+        nonce = Crypto::AEAD.nonce_for(iv, packet_number)
+        ciphertext = bytes.byteslice(pn_offset + pn_length, bytes.bytesize - pn_offset - pn_length)
+        payload = Crypto::AEAD.open(cipher_suite, key, nonce, ciphertext, header)
+
+        [header, payload, packet_number]
+      end
+
+      # RFC 9000 Appendix A: reconstructs a full packet number from its
+      # truncated wire encoding using the connection's own view of what
+      # packet number it expected next — needed because the sender only
+      # sends as many low-order bytes as are provably unambiguous given
+      # what the receiver has already acknowledged.
+      def decode_packet_number(truncated, num_bits, expected)
+        window = 1 << num_bits
+        half_window = window / 2
+        candidate = (expected & ~(window - 1)) | truncated
+
+        if candidate <= expected - half_window && candidate < (1 << 62) - window
+          candidate + window
+        elsif candidate > expected + half_window && candidate >= window
+          candidate - window
+        else
+          candidate
+        end
+      end
+
+      # RFC 9001 5.4.1: a long header's first byte only has its low 4 bits
+      # maskable (the header-form/fixed bits are excluded); a short
+      # header's has its low 5 bits maskable (also excluding the key-phase
+      # bit's neighbors). Bit 7 (0x80) distinguishes long from short.
+      def first_byte_mask(header)
+        header.getbyte(0).nobits?(0x80) ? 0x1f : 0x0f
+      end
+      private_class_method :first_byte_mask
+    end
+  end
+end

data/lib/butler/quic/varint.rb

@@ -0,0 +1,56 @@
+class Butler
+  module Quic
+    # QUIC's variable-length integer encoding (RFC 9000 section 16): the top
+    # two bits of the first byte select the encoded length (1, 2, 4, or 8
+    # bytes, holding 6/14/30/62 bits of value respectively), so small values
+    # — which dominate QUIC's wire format — cost far fewer bytes than a
+    # fixed-width encoding would.
+    module Varint
+      module_function
+
+      MAX_VALUE = (1 << 62) - 1
+
+      # Encodes +value+ using the smallest length that fits it, returning
+      # the raw bytes as a binary String.
+      def encode(value)
+        raise ArgumentError, "#{value} does not fit in a QUIC varint" if value.negative? || value > MAX_VALUE
+
+        if value <= 0x3f
+          [value].pack("C")
+        elsif value <= 0x3fff
+          [0x4000 | value].pack("n")
+        elsif value <= 0x3fffffff
+          [0x80000000 | value].pack("N")
+        else
+          [0xc000000000000000 | value].pack("Q>")
+        end
+      end
+
+      # How many bytes #encode(value) would produce, without building them.
+      def encoded_length(value)
+        raise ArgumentError, "#{value} does not fit in a QUIC varint" if value.negative? || value > MAX_VALUE
+
+        if value <= 0x3f then 1
+        elsif value <= 0x3fff then 2
+        elsif value <= 0x3fffffff then 4
+        else 8
+        end
+      end
+
+      # Decodes one varint starting at the beginning of +bytes+, returning
+      # [value, bytes_consumed] — the caller slices off bytes_consumed to
+      # continue parsing whatever follows.
+      def decode(bytes)
+        first = bytes.getbyte(0)
+        raise ArgumentError, "empty input" unless first
+
+        length = 1 << (first >> 6)
+        raise ArgumentError, "truncated varint" if bytes.bytesize < length
+
+        value = first & 0x3f
+        (1...length).each { |i| value = (value << 8) | bytes.getbyte(i) }
+        [value, length]
+      end
+    end
+  end
+end

data/lib/butler/rails/notifications.rb

@@ -0,0 +1,10 @@
+# The ActiveSupport::Notifications bridge itself is automatic (see
+# Butler::Telemetry::Instrumentation, which checks
+# `defined?(ActiveSupport::Notifications)` at instrument-time and needs no
+# separate wiring). What's Rails-specific and worth this file: pointing
+# Butler's structured request log line at Rails.logger instead of the bare
+# Logger.new($stdout) default, without overriding anything an application
+# already configured explicitly.
+Butler.configure do |config|
+  config.telemetry.logger ||= ::Rails.logger
+end

data/lib/butler/rails/railtie.rb

@@ -0,0 +1,24 @@
+# Only ever required from the guarded line at the bottom of lib/butler.rb
+# (`require "butler/rails/railtie" if defined?(::Rails::Railtie)`), so
+# `require "butler"` keeps working standalone in a non-Rails process.
+class Butler
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "butler.notifications" do
+        require "butler/rails/notifications"
+      end
+
+      config.after_initialize do
+        # ActiveSupport::ForkTracker is the same mechanism Active Record
+        # itself uses to reset connections after Puma (or any preload_app!
+        # server) forks a worker — without this, a forked worker would
+        # inherit the parent's live Async::HTTP::Client/reactor state and
+        # corrupt it the moment two processes tried to use the same
+        # sockets.
+        if defined?(::ActiveSupport::ForkTracker)
+          ::ActiveSupport::ForkTracker.after_fork { Butler.reset_connections! }
+        end
+      end
+    end
+  end
+end

data/lib/butler/request.rb

@@ -0,0 +1,92 @@
+# An immutable-ish value object describing one HTTP call: method, resolved
+# Butler::URI, Butler::Headers, and an optional Butler::Body. Built fresh for
+# every attempt/redirect hop by Client#request; Transport is the only thing
+# downstream that reads it.
+class Butler::Request
+  attr_reader :method, :uri, :headers, :body, :idempotent, :basic_auth
+
+  def self.build(method:, uri:, options:, config:)
+    headers = config.default_headers.merge(Butler::Headers.coerce(options[:headers] || {}))
+    body = Butler::Body.wrap(options)
+
+    if body && !body.empty? && !headers.key?("content-type") && body.content_type
+      headers["Content-Type"] = body.content_type
+    end
+    headers["User-Agent"] = config.user_agent if config.user_agent && !headers.key?("user-agent")
+
+    new(
+      method: method.to_s.upcase,
+      uri: uri,
+      headers: headers,
+      body: body,
+      idempotent: options.fetch(:idempotent, false),
+      basic_auth: options[:basic_auth],
+      stream: options.fetch(:stream, false),
+    )
+  end
+
+  def initialize(method:, uri:, headers:, body: nil, idempotent: false, basic_auth: nil, stream: false)
+    @method = method
+    @uri = uri
+    @headers = headers
+    @body = body
+    @idempotent = idempotent
+    @basic_auth = basic_auth
+    @stream = stream
+    apply_basic_auth!
+  end
+
+  def stream?
+    @stream
+  end
+
+  def origin_key
+    uri.origin_key
+  end
+
+  # GET/HEAD/OPTIONS are always safe to retry; anything else only becomes
+  # retry-eligible (on a retryable status code) when the caller explicitly
+  # opts in via idempotent: true.
+  def safe?
+    %w[GET HEAD OPTIONS].include?(method)
+  end
+
+  def retry_eligible?
+    safe? || idempotent
+  end
+
+  def with_uri(new_uri)
+    copy = dup
+    copy.instance_variable_set(:@uri, new_uri)
+    copy
+  end
+
+  # Used on a cross-origin redirect: drops Authorization/Cookie so
+  # credentials for the original host aren't handed to a different one.
+  def without_credentials
+    stripped = headers.dup
+    stripped.delete("authorization")
+    stripped.delete("cookie")
+    copy = dup
+    copy.instance_variable_set(:@headers, stripped)
+    copy.instance_variable_set(:@basic_auth, nil)
+    copy
+  end
+
+  private
+
+  def apply_basic_auth!
+    case basic_auth
+    in [user, password]
+      set_basic_auth(user, password)
+    in { username:, password: }
+      set_basic_auth(username, password)
+    else
+      nil
+    end
+  end
+
+  def set_basic_auth(user, password)
+    headers["Authorization"] = "Basic #{["#{user}:#{password}"].pack("m0")}"
+  end
+end

data/lib/butler/resilience/backoff.rb

@@ -0,0 +1,17 @@
+class Butler
+  module Resilience
+    # Exponential backoff with equal-jitter: the raw exponential delay is
+    # scaled by a random factor in [0.5, 1.0) rather than being used
+    # verbatim, so many clients failing at once don't all retry in lockstep
+    # against a recovering server.
+    module Backoff
+      module_function
+
+      def delay_for(attempt, retry_options)
+        base = retry_options.base_delay * (2**(attempt - 1))
+        capped = [base, retry_options.max_delay].min
+        retry_options.jitter ? capped * (0.5 + (rand * 0.5)) : capped
+      end
+    end
+  end
+end

data/lib/butler/resilience/circuit_breaker.rb

@@ -0,0 +1,120 @@
+class Butler
+  module Resilience
+    # A CLOSED -> OPEN -> HALF_OPEN -> CLOSED/OPEN state machine, scoped
+    # either per-client (circuit_breaker.scope = :client, one shared state)
+    # or per-host (the default) so one struggling upstream doesn't trip the
+    # breaker for every other host the same client talks to.
+    #
+    # One Mutex guards every state transition. Ruby Fibers never run two at
+    # once on the same thread (they're cooperative, not preemptive), so this
+    # is really guarding against ordinary multi-threaded use (e.g. several
+    # Puma threads sharing one Butler::Client) — the critical sections are
+    # tiny bookkeeping only, never I/O, so contention is not a concern.
+    #
+    # State is capped at max_tracked_hosts (a Hash-based LRU: touching an
+    # entry re-inserts it at the end, and the oldest entry is evicted once
+    # the cap is exceeded) so a client that fans out to many different
+    # hosts (e.g. webhook delivery) can't grow this unboundedly.
+    class CircuitBreaker
+      HostState = Struct.new(:status, :failure_count, :opened_at, :probing)
+
+      def initialize
+        @states = {}
+        @mutex = Mutex.new
+      end
+
+      def scope_key_for(request, config)
+        config.circuit_breaker.scope == :client ? :client : request.uri.host
+      end
+
+      # +failure+ decides whether a *non-raising* result still counts as a
+      # circuit-breaker failure (e.g. a 5xx response returned normally
+      # rather than raised, since Butler only raises on error responses
+      # when raise_on_error is set) — an exception from the block always
+      # counts as a failure regardless of +failure+.
+      def call(scope_key, circuit_breaker_options, failure: ->(_result) { false })
+        state = fetch(scope_key, circuit_breaker_options)
+        guard!(state, circuit_breaker_options)
+
+        begin
+          result = yield
+          if failure.call(result)
+            record_failure!(state, circuit_breaker_options)
+          else
+            record_success!(state)
+          end
+          result
+        rescue Butler::Errors::CircuitOpen
+          raise
+        rescue StandardError
+          record_failure!(state, circuit_breaker_options)
+          raise
+        end
+      end
+
+      private
+
+      def fetch(scope_key, circuit_breaker_options)
+        @mutex.synchronize do
+          state = @states.delete(scope_key) || HostState.new(:closed, 0, nil, false)
+          @states[scope_key] = state # re-insert at the end: cheap LRU touch
+          evict!(circuit_breaker_options)
+          state
+        end
+      end
+
+      def guard!(state, circuit_breaker_options)
+        @mutex.synchronize do
+          case state.status
+          when :open
+            if monotonic_now - state.opened_at >= circuit_breaker_options.recovery_timeout
+              raise Butler::Errors::CircuitOpen, "circuit half-open probe already in flight" if state.probing
+
+              state.status = :half_open
+              state.probing = true
+            else
+              raise Butler::Errors::CircuitOpen, "circuit is open"
+            end
+          when :half_open
+            raise Butler::Errors::CircuitOpen, "circuit half-open probe already in flight" if state.probing
+
+            state.probing = true
+          end
+        end
+      end
+
+      def record_success!(state)
+        @mutex.synchronize do
+          state.status = :closed
+          state.failure_count = 0
+          state.opened_at = nil
+          state.probing = false
+        end
+      end
+
+      def record_failure!(state, circuit_breaker_options)
+        @mutex.synchronize do
+          state.probing = false
+          if state.status == :half_open
+            state.status = :open
+            state.opened_at = monotonic_now
+          else
+            state.failure_count += 1
+            if state.failure_count >= circuit_breaker_options.failure_threshold
+              state.status = :open
+              state.opened_at = monotonic_now
+            end
+          end
+        end
+      end
+
+      def evict!(circuit_breaker_options)
+        @states.shift while @states.size > circuit_breaker_options.max_tracked_hosts
+      end
+
+      def monotonic_now
+        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/butler/resilience/deadline.rb

@@ -0,0 +1,55 @@
+class Butler
+  module Resilience
+    # A total wall-clock budget for one Client#request call — DNS, connect,
+    # TLS, every retry attempt, every redirect hop, all count against the
+    # same Deadline. It is created once per call and threaded through
+    # Pipeline::Context; nothing downstream (RetryMiddleware included) is
+    # ever allowed to reset it, which is exactly the PRD's core rule:
+    # retries must never reset the total deadline.
+    class Deadline
+      def self.start(seconds)
+        seconds ? new(seconds) : Unbounded.new
+      end
+
+      def initialize(seconds)
+        @end_at = monotonic_now + seconds
+      end
+
+      def remaining
+        [@end_at - monotonic_now, 0].max
+      end
+
+      def expired?
+        remaining <= 0
+      end
+
+      def exceeded!
+        raise Butler::Errors::TimeoutError, "deadline exceeded" if expired?
+      end
+
+      private
+
+      def monotonic_now
+        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    class Deadline::Unbounded < Deadline
+      def initialize
+        # deliberately does not call super — there is no @end_at to compute
+      end
+
+      def remaining
+        Float::INFINITY
+      end
+
+      def expired?
+        false
+      end
+
+      def exceeded!
+        nil
+      end
+    end
+  end
+end

data/lib/butler/resilience/retry_policy.rb

@@ -0,0 +1,76 @@
+class Butler
+  module Resilience
+    # Decides whether a failed attempt should be retried, and how long to
+    # wait first. Two independent questions, deliberately kept separate:
+    #
+    # - #retry_on_exception? — the request never got a well-formed HTTP
+    #   response at all (connection refused/reset, TLS failure, timeout).
+    #   Retried for *any* HTTP method: nothing that reached the server can
+    #   be confirmed either way, and refusing to retry a network-level
+    #   failure wouldn't make a non-idempotent request any safer, just
+    #   less reliable.
+    # - #retry_on_response? — a response *was* received. Only retried when
+    #   its status is in retryable_status_codes *and* the method is
+    #   GET/HEAD/OPTIONS or was explicitly marked idempotent: true. POST is
+    #   never auto-retried on a 5xx.
+    #
+    # Both refuse to retry once the deadline has expired or max_attempts is
+    # reached, regardless of the above.
+    class RetryPolicy
+      RETRYABLE_EXCEPTIONS = [
+        Butler::Errors::ConnectionError,
+        Butler::Errors::TimeoutError,
+        Butler::Errors::TLSError,
+        Butler::Errors::DNSFailure,
+        Butler::Errors::ProtocolError,
+      ].freeze
+
+      # Exceptions checked *before* RETRYABLE_EXCEPTIONS and, if matched,
+      # never retried even though they're a subclass of something in that
+      # list above (Errors::CertificateVerificationError < Errors::TLSError)
+      # — a bad certificate won't become valid on the next attempt, so
+      # retrying it only delays surfacing a real problem.
+      NON_RETRYABLE_EXCEPTIONS = [
+        Butler::Errors::CertificateVerificationError,
+      ].freeze
+
+      def retry_on_exception?(exception:, attempt:, deadline:, retry_options:)
+        return false if deadline.expired?
+        return false if attempt >= retry_options.max_attempts
+        return false if NON_RETRYABLE_EXCEPTIONS.any? { |klass| exception.is_a?(klass) }
+
+        RETRYABLE_EXCEPTIONS.any? { |klass| exception.is_a?(klass) }
+      end
+
+      def retry_on_response?(request:, response:, attempt:, deadline:, retry_options:)
+        return false if deadline.expired?
+        return false if attempt >= retry_options.max_attempts
+        return false unless retry_options.retryable_status_codes.include?(response.status)
+
+        request.retry_eligible?
+      end
+
+      def delay_for(response: nil, attempt:, retry_options:, deadline:)
+        retry_after = response && parse_retry_after(response)
+        computed = retry_after || Backoff.delay_for(attempt, retry_options)
+        [computed, deadline.remaining].min
+      end
+
+      private
+
+      def parse_retry_after(response)
+        value = response.headers["retry-after"]
+        return nil unless value
+
+        if value.match?(/\A\d+\z/)
+          value.to_i
+        else
+          delay = ::Time.httpdate(value) - ::Time.now
+          delay.positive? ? delay : 0
+        end
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/butler/resilience/timeout.rb

@@ -0,0 +1,22 @@
+class Butler
+  module Resilience
+    # A single helper for wrapping a block with a per-attempt timeout via
+    # the async gem's Fiber-aware Task#with_timeout, translating its
+    # Async::TimeoutError into Butler's own Errors::TimeoutError so callers
+    # never need to rescue an async-gem class directly. Used by
+    # Transport::Async to enforce connect/read/write-ish budgets without
+    # duplicating this logic in every transport method.
+    module Timeout
+      module_function
+
+      def enforce(seconds)
+        return yield if seconds.nil? || !seconds.finite?
+        raise Butler::Errors::TimeoutError, "deadline exceeded" if seconds <= 0
+
+        ::Async::Task.current.with_timeout(seconds) { yield }
+      rescue ::Async::TimeoutError => e
+        raise Butler::Errors::TimeoutError, e.message
+      end
+    end
+  end
+end

data/lib/butler/response.rb

@@ -0,0 +1,81 @@
+# One consistent response shape regardless of protocol (HTTP/1.1 vs HTTP/2)
+# or whether it came from the real transport or Butler::Testing's fake one.
+# +body+ is either a String (the default, fully buffered) or a Butler::Stream
+# (when the request was made with stream: true).
+class Butler::Response
+  attr_reader :uri, :status, :headers
+
+  def initialize(uri:, status:, headers:, body:)
+    @uri = uri
+    @status = status
+    @headers = headers
+    @body = body
+  end
+
+  def body
+    @body.is_a?(Butler::Stream) ? @body.read_all : @body
+  end
+
+  # The raw Butler::Stream, for callers who passed stream: true and want to
+  # consume it chunk-by-chunk instead of buffering it via #body.
+  def stream
+    @body
+  end
+
+  alias code status # familiar alias for anyone coming from Net::HTTP-style clients
+
+  def informational?
+    (100..199).cover?(status)
+  end
+
+  def success?
+    (200..299).cover?(status)
+  end
+  alias ok? success?
+
+  def redirect?
+    (300..399).cover?(status)
+  end
+
+  def client_error?
+    (400..499).cover?(status)
+  end
+
+  def server_error?
+    (500..599).cover?(status)
+  end
+
+  def error?
+    client_error? || server_error?
+  end
+
+  def content_type
+    headers["content-type"].to_s
+  end
+
+  def json?
+    content_type.include?("json")
+  end
+
+  # Parses the body as JSON when the response looks like JSON, memoized
+  # since callers commonly read this more than once. Returns nil (rather
+  # than raising) when the body isn't valid JSON despite the header, since
+  # plenty of upstream services get their own Content-Type wrong.
+  def json
+    return @json if defined?(@json)
+
+    @json =
+      if json? && !body.to_s.empty?
+        begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+  end
+  alias parsed json
+
+  def to_s
+    body.to_s
+  end
+end