bidi2pdf 0.1.14 → 0.1.16

data/lib/bidi2pdf/session_warmer.rb

@@ -0,0 +1,377 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  # Keeps a small number of Chrome sessions pre-warmed (chromedriver started, WebSocket connected,
+  # browser ready) so a render can skip that startup latency on the request path. Isolation matches
+  # today's one-Chrome-per-render model exactly: every checked-out slot is used for exactly one
+  # +with_tab+ block and then retired (never returned to the cache) - only a fresh replacement is
+  # warmed in its place, off the request path. Checkout never waits for a warm slot: one is used if
+  # it is ready, otherwise a slot is created synchronously on the spot, i.e. today's exact behavior
+  # for that one render - including its failure mode: if that cold start fails, the error propagates
+  # out of +with_tab+ exactly as it would without the warmer.
+  #
+  # @example Rails initializer
+  #   Bidi2pdf::SessionWarmer.configure do |c|
+  #     c.size = 2
+  #     c.headless = true
+  #   end
+  #
+  # @example Per-request usage
+  #   Bidi2pdf::SessionWarmer.with_tab do |tab|
+  #     tab.navigate_to(url)
+  #     tab.print("invoice.pdf")
+  #   end
+  class SessionWarmer
+    # Configuration for the session warmer.
+    class Configuration
+      # @return [Integer] Number of Chrome slots to keep pre-warmed.
+      attr_accessor :size
+
+      # @return [Boolean] Whether to run Chrome in headless mode.
+      attr_accessor :headless
+
+      # @return [Array<String>] Chrome launch arguments.
+      attr_accessor :chrome_args
+
+      # @return [String, nil] A remote chromedriver session URL (e.g. a `remote-chrome` sidecar). When
+      #   set, a slot connects directly to it instead of spawning a local ChromedriverManager -
+      #   mirrors Launcher#session's own local/remote branch.
+      attr_accessor :remote_browser_url
+
+      # @return [#call, nil] Optional factory callable that returns a slot hash - injectable for tests.
+      #   A custom factory owns the cleanup of anything it half-built before raising: the warmer can
+      #   only retire a slot it was actually handed.
+      attr_accessor :slot_factory
+
+      # @return [Numeric, nil] Seconds a warm slot may sit unused before it is retired and replaced.
+      #   A warm slot is an open, unauthenticated automation endpoint (chromedriver's port, Chrome's
+      #   debugging port) for as long as it idles, so that window is bounded by default. A slot older
+      #   than this is never handed out, and a background reaper recycles idle ones within roughly
+      #   1.25x this value even when no render ever comes. +nil+ disables the limit.
+      attr_accessor :max_idle_age
+
+      DEFAULT_MAX_IDLE_AGE = 300
+
+      def initialize
+        @size = 1
+        @headless = true
+        @chrome_args = Bidi2pdf::Bidi::Session::DEFAULT_CHROME_ARGS
+        @remote_browser_url = nil
+        @slot_factory = nil
+        @max_idle_age = DEFAULT_MAX_IDLE_AGE
+      end
+
+      # @raise [ArgumentError] if a setting can't be honored - checked once, at construction.
+      def validate!
+        validate_size!
+        validate_max_idle_age!
+      end
+
+      private
+
+      def validate_size!
+        return if size.is_a?(Integer) && !size.negative?
+
+        raise ArgumentError, "size must be a non-negative Integer, got #{size.inspect}"
+      end
+
+      def validate_max_idle_age!
+        return if max_idle_age.nil? || (max_idle_age.is_a?(Numeric) && max_idle_age.positive?)
+
+        raise ArgumentError, "max_idle_age must be nil or a positive number of seconds, got #{max_idle_age.inspect}"
+      end
+    end
+
+    class << self
+      # Configures the warmer and eagerly (re)creates the singleton, warming config.size slots right
+      # here - at boot/configuration time, off the request path - instead of lazily on whichever
+      # request happens to trigger the first #with_tab (which would otherwise pay for every
+      # configured slot, serially, on that one unlucky request).
+      def configure
+        @config = Configuration.new
+        yield @config if block_given?
+        @instance&.shutdown
+        # Cleared first: if the constructor below raises, a stale, already-shut-down instance must
+        # not stay registered (it would keep serving cold slots but never warm again).
+        @instance = nil
+        @instance = new(@config, slot_factory: @config.slot_factory)
+      end
+
+      # Returns the warmer's configuration, initializing defaults if needed.
+      def config
+        @config ||= Configuration.new
+      end
+
+      # Returns a callable that creates one real, fully-warmed Chrome slot from +config+. If building
+      # fails part-way (chromedriver up, but the session or its browser never came ready), whatever
+      # already exists is retired before the error propagates - no caller ever gets a reference to a
+      # half-built slot, so nobody else could clean it up.
+      def default_slot_factory(config)
+        lambda do
+          parts = {}
+          build_slot(config, parts)
+        rescue StandardError
+          retire_slot(session: parts[:session], manager: parts[:manager])
+          raise
+        end
+      end
+
+      # Closes a slot's session and stops its chromedriver (nil for a remote slot, or for a part that
+      # was never created). Each step is independent: a failure in one is logged, never raised, and
+      # never skips the other.
+      def retire_slot(session:, manager:)
+        safe_close("session") { session&.close }
+        safe_close("manager") { manager&.stop }
+      end
+
+      def safe_close(label)
+        yield
+      rescue StandardError => e
+        Bidi2pdf.logger.warn "session_warmer: error closing #{label}: #{e.message}"
+      end
+
+      # Returns the shared singleton warmer instance, creating it (and pre-warming it) on first call.
+      def instance
+        @instance ||= new(config, slot_factory: config.slot_factory)
+      end
+
+      # Checks out a slot, yields a fresh tab for one render, then retires the slot.
+      def with_tab(&)
+        instance.with_tab(&)
+      end
+
+      # Retires every currently-warm spare and resets the singleton.
+      def shutdown
+        @instance&.shutdown
+        @instance = nil
+      end
+
+      private
+
+      # Records each part in +parts+ the moment it exists, so #default_slot_factory's rescue can
+      # retire exactly what was created so far. Mirrors Launcher#session's local/remote branch.
+      def build_slot(config, parts)
+        config.remote_browser_url ? connect_remote(config, parts) : start_local(config, parts)
+
+        { session: parts[:session], browser: parts[:session].browser, manager: parts[:manager] }
+      end
+
+      def connect_remote(config, parts)
+        parts[:session] = Bidi2pdf::Bidi::Session.new(
+          session_url: config.remote_browser_url,
+          headless: config.headless,
+          chrome_args: config.chrome_args
+        )
+      end
+
+      def start_local(config, parts)
+        parts[:manager] = Bidi2pdf::ChromedriverManager.new(port: 0, headless: config.headless, chrome_args: config.chrome_args)
+        parts[:manager].start
+        parts[:session] = parts[:manager].session
+      end
+    end
+
+    def initialize(config, slot_factory: nil)
+      config.validate!
+      @config = config
+      @slot_factory = slot_factory || self.class.default_slot_factory(config)
+      @mutex = Mutex.new
+      @available = []
+      @replenish_threads = []
+      @warming = 0
+      @shutdown = false
+      @reaper_wakeup = Thread::Queue.new
+      prewarm
+      @reaper = Thread.new { reap_loop } if @config.max_idle_age
+    end
+
+    # Checks out a slot, creates an isolated UserContext/Window/Tab for one render, yields the tab,
+    # then unconditionally closes those resources and retires the underlying slot.
+    def with_tab
+      slot = checkout
+      user_context = nil
+      window = nil
+      tab = nil
+
+      begin
+        user_context = slot[:browser].create_user_context
+        window = user_context.create_browser_window
+        tab = window.create_browser_tab
+        yield tab
+      ensure
+        safe_close("tab") { tab&.close }
+        safe_close("window") { window&.close }
+        safe_close("user context") { user_context&.close }
+        retire(slot)
+      end
+    end
+
+    # Retires every currently-warm spare and waits for any in-flight background replenishment to
+    # finish (each of those, seeing @shutdown, retires its own result instead of stashing it - see
+    # #stash_or_retire). A subsequent #with_tab still works - it just falls back to a synchronous
+    # slot, since checkout never depends on a warm one being there.
+    def shutdown
+      spares, threads = @mutex.synchronize do
+        @shutdown = true
+        [@available.dup.tap { @available.clear }, @replenish_threads.dup.tap { @replenish_threads.clear }]
+      end
+
+      @reaper_wakeup << :stop
+      @reaper&.join
+      threads.each(&:join)
+      spares.each { |slot| retire(slot) }
+    end
+
+    private
+
+    # Fail-fast on purpose (a Chrome that can't start at boot should be loud), but not leaky: if slot
+    # N fails, no instance is returned to own slots 1..N-1, so they are retired here first.
+    def prewarm
+      @config.size.times { @available << stamp(create_slot) }
+    rescue StandardError
+      @available.each { |slot| retire(slot) }
+      @available.clear
+      raise
+    end
+
+    def create_slot
+      @slot_factory.call
+    end
+
+    # Session#started? is just an internal flag set once at startup - it never flips back if Chrome,
+    # ChromeDriver, or the WebSocket dies externally while a slot sits idle in the cache. The
+    # client's own #open? is kept live by the reader thread noticing a real socket error, so
+    # checking it too catches that case - cheap (no network round trip), though still a heuristic,
+    # not a full liveness guarantee (a stuck-but-not-yet-disconnected socket still reads healthy).
+    def healthy?(slot)
+      slot[:session].started? && slot[:session].client&.open? == true
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # Marks the moment a slot entered the cache - idle age counts from here, not from when its
+    # Chrome started, since it is the unattended waiting that max_idle_age bounds.
+    def stamp(slot)
+      slot.merge(warmed_at: now)
+    end
+
+    def expired?(slot)
+      !@config.max_idle_age.nil? && now - slot[:warmed_at] > @config.max_idle_age
+    end
+
+    # Checkout alone can't bound idle time: with no traffic nothing would ever look at a spare. This
+    # thread does, four times per max_idle_age, so an unused slot is recycled within ~1.25x of it.
+    # Thread::Queue#pop(timeout:) doubles as an interruptible sleep - #shutdown pushes :stop.
+    def reap_loop
+      interval = [@config.max_idle_age / 4.0, 0.05].max
+      recycle_expired until @reaper_wakeup.pop(timeout: interval) == :stop
+    end
+
+    def recycle_expired
+      expired = @mutex.synchronize do
+        next [] if @shutdown
+
+        old, fresh = @available.partition { |slot| expired?(slot) }
+        @available.replace(fresh)
+        old
+      end
+      return if expired.empty?
+
+      Bidi2pdf.notification_service.instrument("session_warmer.expired.bidi2pdf", { count: expired.size })
+      replenish_async
+      expired.each { |slot| retire(slot) }
+    rescue StandardError => e
+      Bidi2pdf.logger.warn "session_warmer: recycling idle slots failed: #{e.message}"
+    end
+
+    # A warm hit takes the spare and triggers a background replacement; a miss (empty cache, or a
+    # spare that died while idle) falls straight through to a synchronous slot - it never waits, so
+    # an under-provisioned warmer is never worse than not having one. A cold start that fails raises,
+    # as it would without the warmer.
+    #
+    # Oldest spare first (shift, not pop), so no slot lingers at the bottom of the cache while newer
+    # ones are used; and one past max_idle_age is never handed out, even if the reaper hasn't got to
+    # it yet - it is retired like a dead spare and this render cold-starts instead.
+    def checkout
+      slot = @mutex.synchronize { @available.shift }
+      had_spare = !slot.nil?
+      hit = had_spare && !expired?(slot) && healthy?(slot)
+      taken = nil
+
+      Bidi2pdf.notification_service.instrument("session_warmer.checkout.bidi2pdf", { hit: hit }) do
+        taken = hit ? slot : cold_checkout(slot)
+      end
+
+      # Every checkout tops the cache back up, hit or miss - #replenish_async itself bounds the work
+      # to the current deficit, so a miss on an already-full-or-filling cache starts nothing.
+      replenish_async
+      taken
+    end
+
+    def cold_checkout(dead_slot)
+      retire(dead_slot) if dead_slot
+      create_slot
+    end
+
+    # Tops the cache up towards config.size, counting warmers already in flight. Deficit-based on
+    # purpose, not "replace what this checkout popped": that rule could never recover from a single
+    # failed warm (nothing stashed -> every later checkout a miss -> never replenished again), while
+    # replenishing unconditionally let @available grow without bound under a burst of misses.
+    # available + warming never exceeds config.size, and a failed warm frees its reservation, so the
+    # next checkout simply tries again.
+    #
+    # Threads are created and registered inside the same critical section, so #shutdown's snapshot
+    # can't miss one that has started but isn't listed yet (#warm_one needs this mutex to finish,
+    # so it just waits for it).
+    def replenish_async
+      @mutex.synchronize do
+        next if @shutdown
+
+        @replenish_threads.select!(&:alive?)
+        deficit = @config.size - (@available.size + @warming)
+        deficit.times do
+          @warming += 1
+          @replenish_threads << Thread.new { warm_one }
+        end
+      end
+    end
+
+    def warm_one
+      slot = create_slot
+    rescue StandardError => e
+      @mutex.synchronize { @warming -= 1 }
+      Bidi2pdf.logger.warn "session_warmer: failed to warm a replacement slot: #{e.message}"
+      Bidi2pdf.notification_service.instrument("session_warmer.warm_failed.bidi2pdf", { error: e.class.name })
+    else
+      stash_or_retire(slot)
+    end
+
+    # A replacement warmed after #shutdown has nothing to stash into - retire it immediately rather
+    # than leaking a live Chrome process that nothing will ever check out. Either way this warmer's
+    # reservation is released here, in the same critical section as the stash.
+    def stash_or_retire(slot)
+      discard = @mutex.synchronize do
+        @warming -= 1
+
+        if @shutdown
+          true
+        else
+          @available << stamp(slot)
+          false
+        end
+      end
+
+      retire(slot) if discard
+    end
+
+    def retire(slot)
+      self.class.retire_slot(session: slot[:session], manager: slot[:manager])
+    end
+
+    def safe_close(label, &)
+      self.class.safe_close(label, &)
+    end
+  end
+end

data/lib/bidi2pdf/test_helpers/testcontainers/chromedriver_test_helper.rb

@@ -70,7 +70,8 @@ RSpec.configure do |config|
       config.chromedriver_container = start_chromedriver_container(
         build_dir: File.join(Bidi2pdf::TestHelpers.configuration.docker_dir, ".."),
         mounts: config.respond_to?(:chromedriver_mounts) ? config.chromedriver_mounts : {},
-        shared_network: config.shared_network
+        shared_network: config.shared_network,
+        chromedriver_log_level: config.respond_to?(:chromedriver_log_level) ? config.chromedriver_log_level : "WARNING"
       )
 
       reporter.message("🚀 chromedriver container started for tests")
@@ -121,12 +122,13 @@ end
 # alias the long class name
 ChromedriverTestcontainer = Bidi2pdf::TestHelpers::Testcontainers::ChromedriverContainer
 
-def start_chromedriver_container(build_dir:, mounts:, shared_network:)
+def start_chromedriver_container(build_dir:, mounts:, shared_network:, chromedriver_log_level: "WARNING")
   container = ChromedriverTestcontainer.new(ChromedriverTestcontainer::DEFAULT_IMAGE,
                                             build_dir: build_dir,
                                             docker_file: "docker/Dockerfile.chromedriver")
                                        .with_network(shared_network)
                                        .with_network_aliases("remote-chrome")
+                                       .with_env("CHROMEDRIVER_LOG_LEVEL", chromedriver_log_level)
 
   container.with_filesystem_binds(mounts) if mounts&.any?
 

data/lib/bidi2pdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
-  VERSION = "0.1.14"
+  VERSION = "0.1.16"
 end

data/lib/bidi2pdf.rb

@@ -9,9 +9,11 @@ require_relative "bidi2pdf/bidi/session"
 require_relative "bidi2pdf/dsl"
 require_relative "bidi2pdf/notifications"
 require_relative "bidi2pdf/notifications/logging_subscriber"
+require_relative "bidi2pdf/notifications/json_subscriber"
+require_relative "bidi2pdf/session_warmer"
 require_relative "bidi2pdf/verbose_logger"
 
-module Bidi2pdf
+module Bidi2pdf # rubocop:disable Metrics/ModuleLength
   PAPER_FORMATS_CM = {
     letter: { width: 21.59, height: 27.94 },
     legal: { width: 21.59, height: 35.56 },
@@ -26,11 +28,32 @@ module Bidi2pdf
     a6: { width: 10.5, height: 14.8 }
   }.freeze
 
-  class Error < StandardError; end
+  # Base class for every error this gem raises. Carries the machine-readable surface used by
+  # --json/--json-stream/manifests/recipe results (see Bidi2pdf::ErrorCodes): #retryable? and
+  # #hint are overridden per subclass below where a useful default exists; #details is set at
+  # raise time for structured, serializable context (e.g. which selector, which assertion).
+  class Error < StandardError
+    attr_reader :details
 
-  class SessionNotStartedError < Error; end
+    def initialize(message = nil, details: {})
+      @details = details
+      super(message)
+    end
+
+    def retryable? = false
+
+    def hint = nil
+  end
+
+  class SessionNotStartedError < Error
+    def retryable? = true
 
-  class WebsocketError < Error; end
+    def hint = "Check Chrome/chromedriver are installed and reachable, or that --remote-browser-url points at a running instance"
+  end
+
+  class WebsocketError < Error
+    def retryable? = true
+  end
 
   class ClientError < WebsocketError; end
 
@@ -47,7 +70,11 @@ module Bidi2pdf
 
   class CmdResponseNotStoredError < ClientError; end
 
-  class CmdTimeoutError < ClientError; end
+  class CmdTimeoutError < ClientError
+    def retryable? = true
+
+    def hint = "Raise --default-timeout"
+  end
 
   class PrintError < Error; end
 
@@ -76,18 +103,74 @@ module Bidi2pdf
       @url = url
       super("Navigation to #{url} failed due to authentication error. #{message}")
     end
+
+    def hint = "Pass --auth user:pass, or check the credentials are still valid"
   end
 
-  class NavigationTimeoutError < NavigationError; end
+  class NavigationTimeoutError < NavigationError
+    def retryable? = true
+
+    def hint = "Raise --default-timeout, or add --wait-network-idle if the page loads data after the load event"
+  end
+
+  class NavigationNotFoundError < NavigationError
+    def hint = "Check the URL is correct"
+  end
 
-  class NavigationNotFoundError < NavigationError; end
+  class NavigationDNSError < NavigationError
+    attr_reader :url
+
+    def initialize(url = nil, message = nil)
+      @url = url
+      super(url ? "Navigation to #{url} failed: DNS resolution error. #{message}" : message)
+    end
 
-  class NavigationDNSError < NavigationError; end
+    def retryable? = true
+
+    def hint = "Check the hostname is correct and reachable from this machine/container"
+  end
+
+  # --- Errors introduced for the CLI/recipe surface.
+  # Same style as the errors above: a thin subclass per failure mode, message text carried at the
+  # raise site so it stays exactly as specific as the situation warrants.
+
+  class MissingInputError < Error; end
+
+  class MultipleInputSourcesError < Error; end
+
+  class EmptyInputError < Error; end
+
+  class InvalidConfigError < Error; end
+
+  class InvalidPrintOptionError < Error; end
+
+  class InvalidRecipeError < Error; end
+
+  class SelectorNotFoundError < Error; end
+
+  class PageNotAsExpectedError < Error; end
+
+  class OutputWriteError < Error; end
+
+  class PdfInspectionUnavailableError < Error
+    def hint = "Install the pdf-reader gem, or drop assertions/fields that need it"
+  end
+
+  # Loaded here, after the error classes above, since these reference them at load time.
+  require_relative "bidi2pdf/error_codes"
+  require_relative "bidi2pdf/exit_codes"
+  require_relative "bidi2pdf/result"
+  require_relative "bidi2pdf/pdf_inspection"
+  require_relative "bidi2pdf/result_collector"
+  require_relative "bidi2pdf/manifest"
+  require_relative "bidi2pdf/schema"
+  require_relative "bidi2pdf/diagnose"
+  require_relative "bidi2pdf/recipe"
 
   # Global configuration for Bidi2pdf
 
   class << self
-    attr_accessor :default_timeout, :enable_default_logging_subscriber
+    attr_accessor :default_timeout, :enable_default_logging_subscriber, :log_truncate_limit, :chromedriver_log_level
     attr_reader :logging_subscriber, :logger, :network_events_logger, :browser_console_logger, :notification_service
 
     # Allow configuration through a block
@@ -110,6 +193,26 @@ module Bidi2pdf
       end
     end
 
+    # Truncates a value for safe log output - a raw url/param can be a `data:` URL whose base64
+    # payload is proportional to document size, and logging it whole can be large enough to choke
+    # CI log ingestion (confirmed live: GitHub Actions' log UI stalls badly on very long single
+    # lines, reading as a hung job even though the process underneath is fine).
+    #
+    # @param [Object] value The value to truncate (converted via #to_s).
+    # @param [Integer] limit The maximum number of bytes to keep. Defaults to
+    #   +Bidi2pdf.log_truncate_limit+, itself configurable via +Bidi2pdf.configure+.
+    # @return [String] The value unchanged if short enough, otherwise a truncated prefix plus a
+    #   byte-count marker. Truncation is byte-based (not character-based), since the goal is
+    #   bounding actual log-entry size; a partial trailing multi-byte character is scrubbed rather
+    #   than left as invalid UTF-8.
+    def truncate_for_log(value, limit: log_truncate_limit)
+      str = value.to_s
+      return str if str.bytesize <= limit
+
+      truncated = str.byteslice(0, limit).scrub("")
+      "#{truncated}... (#{str.bytesize} bytes total)"
+    end
+
     def translate_paper_format(format)
       format = format.to_s.downcase.to_sym
 
@@ -161,6 +264,8 @@ module Bidi2pdf
 
     config.default_timeout = 60
 
+    config.log_truncate_limit = 200
+
     config.notification_service = Notifications
   end
 end

data/sig/bidi2pdf/bidi/browser_tab.rbs

@@ -235,6 +235,23 @@ module Bidi2pdf
 
       def navigate_with_listeners: (untyped url, ?wait: ::String) -> untyped
 
+      def raise_navigation_error_for: (untyped url, untyped error) -> untyped
+
+      # browsingContext.navigate's own response never carries an HTTP status - only a
+      # network.responseCompleted event does, correlated back to this specific navigation via its
+      # "navigation" field (a Chrome/redirect-chain-wide ID, not the network request's own id).
+      # register_event_listeners already ran above, so network_events has been tracking since
+      # before the navigate command was even sent. Deliberately conservative: with no navigation
+      # ID, or no correlated *completed* request found, this stays silent rather than guessing -
+      # only a positively confirmed >= 400 status raises. max_by(&:start_timestamp) picks the last
+      # hop of a redirect chain (every hop shares the same navigation ID), matching the page the
+      # browser actually ended up on.
+      def check_navigation_http_status: (untyped url, untyped navigation_id) -> (nil | untyped)
+
+      # The last hop of a redirect chain (every hop shares the same navigation ID) - the page the
+      # browser actually ended up on, not wherever the chain started.
+      def correlated_navigation_response: (untyped navigation_id) -> untyped
+
       def register_event_listeners: () -> (nil | untyped)
 
       def handle_injection_exception: (untyped response, untyped url, untyped exception_class) -> untyped

data/sig/bidi2pdf/bidi/buffered_web_socket_client.rbs

@@ -0,0 +1,81 @@
+module Bidi2pdf
+  module Bidi
+    # A threaded WebSocket client on the `websocket` gem's framing - the same shape Selenium's Ruby
+    # BiDi client uses. It replaces websocket-client-simple, whose reader pulled one byte at a time
+    # (`getc`, then a frame-parse attempt per byte): a printed PDF comes back as one base64 message
+    # and every network event for a `data:` navigation echoes the whole URL, so that loop ran
+    # millions of times per render - ~730 ms to decode a 700 KB frame, against ~0.5 ms in 16 KB
+    # chunks.
+    #
+    # Emits :open, :message (a WebSocket frame, payload in #data), :error and :close.
+    class BufferedWebSocketClient
+      @listeners: untyped
+
+      @listeners_mutex: untyped
+
+      @write_mutex: untyped
+
+      # Re-entrant: a failed write inside #close closes again.
+      @close_monitor: untyped
+
+      @handshaked: untyped
+
+      @closed: untyped
+
+      @url: untyped
+
+      @socket: untyped
+
+      @handshake: untyped
+
+      @thread: untyped
+
+      READ_CHUNK_BYTES: 16384
+
+      attr_reader url: untyped
+
+      def self.connect: (untyped url, ?::Hash[untyped, untyped] options) ?{ (untyped) -> untyped } -> untyped
+
+      def initialize: () -> void
+
+      def on: (untyped event) { (?) -> untyped } -> untyped
+
+      def connect: (untyped url, ?::Hash[untyped, untyped] options) -> (nil | untyped)
+
+      # Commands are sent from whichever thread issues them. On a plain TCP socket one IO#write is
+      # already atomic, but OpenSSL::SSL::SSLSocket#write is not, so writes share a lock for wss://.
+      def send: (untyped data, ?type: ::Symbol) -> untyped
+
+      # Safe from any thread, including the reader's own: the reader sees the peer hang up and
+      # closes from inside its loop, so it must neither race a caller closing at the same moment
+      # nor be killed before :close has been emitted.
+      def close: (?untyped? error) -> untyped
+
+      def open?: () -> untyped
+
+      def closed?: () -> untyped
+
+      private
+
+      def emit: (untyped event, *untyped) -> untyped
+
+      def write: (untyped bytes) -> untyped
+
+      def say_goodbye: () -> untyped
+
+      def open_socket: (untyped uri, untyped options) -> untyped
+
+      def ssl_context: (untyped options) -> untyped
+
+      def read_loop: (untyped socket, untyped frame) -> untyped
+
+      def consume: (untyped chunk, untyped frame) -> (nil | untyped)
+
+      # WebSocket control frames (ping/pong/close) must never reach a JSON-parsing consumer -
+      # WebSocketDispatcher tries to parse every :message payload as JSON, so a raw close frame
+      # would raise JSON::ParserError, and an unanswered ping can make chromedriver or an
+      # intermediate proxy tear down an otherwise healthy connection on its own keepalive timeout.
+      def dispatch_frame: (untyped message) -> untyped
+    end
+  end
+end