bidi2pdf 0.1.17 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b879e9c84ccd1584f5b2eb1b406972624cd8b64a50c92466e78f7275ef229441
-  data.tar.gz: 50d517dac875995c2a06ca39dcd8c521c0b18fd238b6950d5e0d9674187941dd
+  metadata.gz: fa0fc469533226ce79d16bb401f4c47093dda42d4a68af67453fab79e086ad65
+  data.tar.gz: 9e4a1176ad42c03ced1544dcb9022a3dfe7d2663b0d8960f41bea863d3b0e788
 SHA512:
-  metadata.gz: 7fca9af905a088093ff4c8ac3a1c78b4f6138068c27ad4cf87616c7ded67f44b3d57aab73b40d83b6c9d8d63097f2851b10f5b0531a91bc22088ec15aab21769
-  data.tar.gz: 835727303208ada398c0ec7456e29d49201d2b798a34edac35007c40ae5123e2a382a6e325e978237fd328ef0d58e6f573d61b1447df54bae51f9188775ab4c6
+  metadata.gz: ddd7621c394b454a1df5b6071f474b1bd8699a4de4086e47c7185b01df66476ccad28d7e843b17e79aebf198489053bc237c345a3f638fb4e25e907aa4dc04f1
+  data.tar.gz: 134e15de59f8d5d7044be15308b1490988bc7eddd0134a9de05feed3accf3d56c52818125da49d36ad91263f6d16d8e58dc6549c85f5897316e9dfab7e60fb73

data/CHANGELOG.md

@@ -8,10 +8,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.17..HEAD
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.18..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [0.1.18] - 2026-09-30
+
+### 🐛 Fixed
+- Record warmer sessions for the sweeper
+- Let one-shot sweeps close hung sessions
+
+### 🔄 Changed
+- Merge pull request #146 from dieter-medium/feat/chrome-sweeper
+- Merge pull request #141 from dieter-medium/dependabot/bundler/main/rubyzip-3.7.0
+- Merge pull request #142 from dieter-medium/dependabot/bundler/main/simplecov-1.3.1
+
+### 🔧 Build
+- Bump rubyzip from 3.6.0 to 3.7.0
+- Bump simplecov from 1.3.0 to 1.3.1
+
+### 🚀 Added
+- Lease sessions so sweeps spare live workers
+- Add a Chrome sweeper for leaked sessions
+
 ## [0.1.17] - 2026-09-29
 
 ### 🐛 Fixed
@@ -495,7 +514,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 🔄 Released
 
-- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.17..HEAD)
+- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.18..HEAD)
+- [0.1.18](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.17..v0.1.18)
 - [0.1.17](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.16..v0.1.17)
 - [0.1.16](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.15..v0.1.16)
 - [0.1.15](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.14..v0.1.15)

data/README.md

@@ -572,6 +572,7 @@ Bidi2pdf::SessionWarmer.shutdown
 | `remote_browser_url` | `nil`                 | Connect each slot to a remote chromedriver instead of starting a local one.                               |
 | `orphan_age`         | `:auto`               | Remote only: on start, close sessions other warmers left behind older than this (`:auto` = 2 × `max_idle_age`, `nil` = off). |
 | `registry_dir`       | `Dir.tmpdir`          | Where the session registry file lives - every process that should clean up after the others must share it. |
+| `sweeper`            | `nil`                 | Remote only: settings for a [`ChromeSweeper`](#leaked-chrome-sessions-bidi2pdfchromesweeper) on the same chromedriver, e.g. `{ scope: :all, max_sessions: :auto, pids_limit: 1024, interval: 60 }`. The warmer's own sessions are never touched; `Bidi2pdf::SessionWarmer.sweep!` sweeps on demand. With a sweeper the warmer records its sessions even when `orphan_age` is `nil`. |
 
 #### Leftover sessions on a shared chromedriver
 
@@ -589,12 +590,119 @@ Everything here is fail-open: if the registry directory is not writable, the war
 warning, instruments `session_warmer.registry_unavailable.bidi2pdf`, and keeps rendering - only the
 cleanup is off. Closed leftovers are reported as `session_warmer.orphans_closed.bidi2pdf`.
 
+With a `sweeper` configured, the warmer also sweeps in the background every `interval` seconds,
+and when chromedriver refuses a new session ("session not created" - typically a container out of
+room for another Chrome) it sweeps once and tries once more.
+
 > **Security note:** an idle warm session is an open, unauthenticated automation endpoint
 > (chromedriver's port, Chrome's debugging port - loopback only for a local chromedriver) for as
 > long as it waits. `max_idle_age` bounds that window; keep it set unless the process runs somewhere
 > nothing else can reach those ports. With `remote_browser_url`, who can reach that endpoint on the
 > network is what matters, exactly as it does without the warmer.
 
+### Leaked Chrome sessions (`Bidi2pdf::ChromeSweeper`)
+
+The registry above only catches what a warmer recorded and only when the next warmer starts. A
+`ChromeSweeper` covers the rest: sessions a crashed process never recorded, a Chrome stuck in a tab
+that never returns, and too many sessions for the container. Run it once, when the application
+suspects a leak, or periodically:
+
+```ruby
+sweeper = Bidi2pdf::ChromeSweeper.new("http://remote-chrome:3000/session",
+                                      scope: :all, max_sessions: :auto, pids_limit: 1024, interval: 60)
+sweeper.start                        # background sweeps until sweeper.stop
+result = sweeper.sweep!              # or one sweep right now
+result.closed                        # => [#<data Closed id="…", age=734, why=:orphan>]
+
+# one-shot: checks twice, 10 s apart, so the unresponsive rule applies too
+Bidi2pdf::ChromeSweeper.sweep!("http://remote-chrome:3000/session", check_interval: 10, dry_run: true)
+
+# last resort: a render failed for lack of resources - sweep under pressure, try once more
+Bidi2pdf::ChromeSweeper.with_retry("http://remote-chrome:3000/session", scope: :all) do
+  render_the_pdf # must be safe to run twice
+end
+```
+
+It closes, in this order: sessions older than `orphan_age`; sessions that failed
+`unresponsive_checks` checks in a row (no answer, or a renderer burning a whole CPU between two
+sweeps - an endless loop in a page); and while more than `max_sessions` exist, the oldest ones.
+It never closes a session a live bidi2pdf process holds (below), a session in `own_sessions`, or
+one younger than `min_age` - not even over the limit. When the limit can only be kept by closing
+those, it closes nothing more and reports `limit_exceeded`. A session is closed with chromedriver's
+`DELETE /session/{id}`, which also ends a Chrome that no longer answers BiDi.
+
+**Live sessions of other processes (leases).** Several processes often share one chromedriver - Puma
+workers, a job worker - and each has renders in flight and warm spares the others know nothing
+about. So every session bidi2pdf opens is recorded in the registry with a lease, and a heartbeat
+thread in the owning process renews it every 20 s while the session is open. A session whose lease
+is younger than `lease_ttl` belongs to a live process: no sweeper in any process closes it, and it
+is not even inspected. When the process dies - killed, crashed, OOM - the lease runs out and the
+session becomes a leftover like any other. Only processes that share the registry directory see
+each other's leases: give job workers in another container the same `registry_dir` on a shared
+volume. Sessions other tools opened have no lease; under `scope: :all` only `min_age` protects them.
+
+**Last resort: pressure.** `sweep!(pressure: true)` closes every session nobody holds that is past
+`min_age`, without waiting for `orphan_age`, the unresponsive checks or the limit. `with_retry` does
+that when its block fails with a resource error - chromedriver refusing a session
+(`SessionNotStartedError`), or a connection or command dying or timing out (`WebsocketError`, but
+not `CmdError`, which is the page's problem) - and runs the block once more; `retry_on:` takes other
+error classes. It frees exactly what belongs to no live process: if the chromedriver is full of live
+renders, the second attempt fails too, and that error is raised. The warmer does the same when a new
+session is refused.
+
+| Setting               | Default     | Description                                                                                                  |
+|-----------------------|-------------|--------------------------------------------------------------------------------------------------------------|
+| `scope`               | `:recorded` | `:recorded`: only sessions a bidi2pdf process recorded in the registry. `:all`: every session on that chromedriver - only for a chromedriver your application owns, since on a shared one it closes other clients' old sessions. |
+| `orphan_age`          | `600`       | Close sessions older than this many seconds. `nil` = off.                                                    |
+| `min_age`             | `60`        | Never close a session younger than this.                                                                     |
+| `unresponsive_checks` | `2`         | Close a session after this many failed checks in a row. `nil` = off.                                         |
+| `max_sessions`        | `nil`       | Session limit. `:auto` = floor(`pids_limit` × `pids_budget` / `threads_per_session`), e.g. 1024 → 7, 512 → 3. |
+| `pids_limit`          | `nil`       | The chromedriver container's pids limit (Docker counts threads). `:auto` without it means no limit.         |
+| `pids_budget`         | `0.8`       | Share of `pids_limit` the Chrome sessions may use.                                                           |
+| `threads_per_session` | `110`       | Threads one Chrome session uses.                                                                             |
+| `interval`            | `nil`       | Seconds between background sweeps (`start`/`stop`).                                                          |
+| `dry_run`             | `false`     | Report what would be closed, close nothing.                                                                  |
+| `registry_dir`        | `Dir.tmpdir`| The registry to read and update - same meaning as the warmer's setting.                                      |
+| `own_sessions`        | `-> { [] }` | A callable returning the caller's live session ids; they are never touched.                                  |
+| `lease_ttl`           | `60`        | A recorded session renewed within this many seconds belongs to a live process and is never touched.         |
+
+How it tells a session's age: chromedriver's `GET /sessions` lists every session but no start time,
+and Chrome keeps none either. So the sweeper uses the registry time when there is one and otherwise
+attaches a second BiDi connection to the session and reads its first tab's
+`performance.timeOrigin` - that tab is created with the session. It only asks for the tab tree,
+that one value and the renderer CPU times; it never reads page content or logs a tab's URL.
+
+A session counts as unresponsive only after `unresponsive_checks` failed checks, and every sweep is
+one check. A periodic sweeper gets there by itself; a single `sweep!` does only with
+`check_interval:` - it then checks `unresponsive_checks - 1` times first (`observe`, which closes
+nothing), that many seconds apart. Without it a one-shot sweep closes only old sessions and those
+over the limit.
+
+Only one sweep runs at a time, across processes too (a lock file next to the registry). A sweep never
+raises: failures are logged and returned in `Result#errors`. Every remote `Bidi2pdf::Bidi::Session`
+is now recorded and leased in the registry, not only warmer slots, and its `close` falls back to the
+HTTP `DELETE` when Chrome does not answer; a session it still could not close keeps its entry but
+loses its lease, so a sweeper takes it.
+
+Notifications: `chrome_sweeper.sweep.bidi2pdf` (every sweep: counts, reason, duration),
+`chrome_sweeper.closed.bidi2pdf` (id, age, why), `chrome_sweeper.unresponsive.bidi2pdf`,
+`chrome_sweeper.limit_exceeded.bidi2pdf`, `chrome_sweeper.failed.bidi2pdf`,
+`chrome_sweeper.retry.bidi2pdf` (`with_retry` sweeps and tries again), and
+`session_close_fallback.bidi2pdf` when a close needed the HTTP `DELETE`.
+
+From the command line:
+
+```bash
+# id, age, where the age comes from, tabs, responsive or live - no URLs
+bidi2pdf sessions --remote-browser-url http://remote-chrome:3000/session [--scope recorded] [--json]
+
+# exits 1 when a close failed or the limit is still exceeded; checks each session
+# --unresponsive-checks times, --check-interval seconds apart (default 10; 0 = sweep at once)
+bidi2pdf sweep --remote-browser-url http://remote-chrome:3000/session \
+  [--scope all] [--older-than 600] [--max-sessions 3] [--min-age 60] \
+  [--unresponsive-checks 2] [--check-interval 10] [--pressure] [--dry-run] [--json]
+```
+
 ### Customizing Chrome arguments (and blank PDFs from inline HTML)
 
 `Bidi2pdf::Bidi::Session::DEFAULT_CHROME_ARGS` already contains one `--disable-features=...` entry,

data/lib/bidi2pdf/bidi/commands/browsing_context_get_tree.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module Bidi
+    module Commands
+      # browsingContext.getTree - the session's top-level browsing contexts (tabs/windows).
+      class BrowsingContextGetTree
+        include Base
+
+        def method_name
+          "browsingContext.getTree"
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/bidi/commands/cdp_send_command.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module Bidi
+    module Commands
+      # goog:cdp.sendCommand - chromedriver's BiDi extension that runs one Chrome DevTools Protocol
+      # command; without a +session+ it runs at browser level (e.g. SystemInfo.getProcessInfo).
+      class CdpSendCommand
+        include Base
+
+        def initialize(method:, params: {}, session: nil)
+          @cdp_method = method
+          @cdp_params = params
+          @session = session
+        end
+
+        def params = { method: @cdp_method, params: @cdp_params, session: @session }.compact
+
+        def method_name
+          "goog:cdp.sendCommand"
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/bidi/commands.rb

@@ -4,6 +4,8 @@ module Bidi2pdf
   module Bidi
     module Commands
       require_relative "commands/base"
+      require_relative "commands/browsing_context_get_tree"
+      require_relative "commands/cdp_send_command"
       require_relative "commands/create_window"
       require_relative "commands/create_tab"
       require_relative "commands/add_intercept"

data/lib/bidi2pdf/bidi/session.rb

@@ -6,6 +6,7 @@ require "json"
 require_relative "client"
 require_relative "browser"
 require_relative "user_context"
+require_relative "../chromedriver_api"
 
 # Represents a session for managing browser interactions and communication
 # using the Bidi2pdf library. This class handles the setup, configuration,
@@ -83,11 +84,15 @@ module Bidi2pdf
       # @param [String] session_url The URL for the session.
       # @param [Boolean] headless Whether to run the browser in headless mode. Defaults to true.
       # @param [Array<String>] chrome_args Additional Chrome arguments. Defaults to predefined arguments.
-      def initialize(session_url:, headless: true, chrome_args: DEFAULT_CHROME_ARGS)
+      # @param [Bidi2pdf::SessionRegistry, nil] registry Records the session on a shared (remote)
+      #   chromedriver while it is open, so a sweep can close it if this process dies without
+      #   closing it (ChromeSweeper, SessionSweeper). nil records nothing.
+      def initialize(session_url:, headless: true, chrome_args: DEFAULT_CHROME_ARGS, registry: nil)
         @session_uri = URI(session_url)
         @headless = headless
         @started = false
         @chrome_args = chrome_args.dup
+        @registry = registry
       end
 
       # Starts the session and initializes the client.
@@ -117,34 +122,18 @@ module Bidi2pdf
         @browser ||= create_browser
       end
 
-      # Closes the session and cleans up resources.
-      # rubocop:disable Metrics/AbcSize
+      # Closes the session and cleans up resources: BiDi +session.end+ first, and when Chrome does not
+      # answer that (a tab stuck in a loop), chromedriver's +DELETE /session/{id}+.
       def close
         return unless started?
 
-        2.times do |attempt|
-          success = Bidi2pdf.notification_service.instrument("session_close.bidi2pdf", { session_uri: session_uri.to_s, attempt: attempt + 1 }) do |payload|
-            client&.send_cmd_and_wait(Bidi2pdf::Bidi::Commands::SessionEnd.new, timeout: 1) do |response|
-              payload[:response] = response
-              cleanup
-            end
-
-            true
-          rescue CmdTimeoutError => e
-            payload[:error] = e
-            payload[:retry] = attempt < 1 # whether we'll retry again
-
-            false
-          end
-
-          break if success
-        end
+        closed = end_via_bidi || delete_via_chromedriver
+        # Not closed: the entry stays, its lease runs out, and a sweeper takes the session.
+        closed ? @registry&.forget(session_id) : @registry&.release(session_id)
       ensure
         @started = false
       end
 
-      # rubocop: enable Metrics/AbcSize
-
       # Retrieves user contexts for the session.
       def user_contexts
         send_cmd(Bidi2pdf::Bidi::Commands::GetUserContexts.new) { |resp| Bidi2pdf.logger.debug "User contexts: #{resp}" }
@@ -231,10 +220,9 @@ module Bidi2pdf
         value = session_data["value"]
         handle_error(value) if value.nil? || value["error"]
 
-        @session_id = value["sessionId"]
+        record_session(value["sessionId"])
         ws_url = value["capabilities"]["webSocketUrl"]
 
-        Bidi2pdf.logger.info "Created session with ID: #{session_id}"
         Bidi2pdf.logger.info "WebSocket URL: #{ws_url}"
         ws_url
       end
@@ -353,6 +341,47 @@ module Bidi2pdf
               "Session not started. Check logs for more details. Error: #{error} message: #{msg}"
       end
 
+      def end_via_bidi
+        2.times.any? do |attempt|
+          Bidi2pdf.notification_service.instrument("session_close.bidi2pdf", { session_uri: session_uri.to_s, attempt: attempt + 1 }) do |payload|
+            client&.send_cmd_and_wait(Bidi2pdf::Bidi::Commands::SessionEnd.new, timeout: 1) do |response|
+              payload[:response] = response
+              cleanup
+            end
+
+            true
+          rescue WebsocketError => e
+            payload[:error] = e
+            payload[:retry] = attempt < 1 # whether we'll retry again
+
+            false
+          end
+        end
+      end
+
+      def record_session(id)
+        @session_id = id
+        @registry&.hold(id)
+        Bidi2pdf.logger.info "Created session with ID: #{id}"
+      end
+
+      # The BiDi session.end got no answer - typically a Chrome that hangs or crashed. chromedriver
+      # still ends the session (and kills its Chrome) on an HTTP DELETE, so a hung Chrome does not
+      # outlive this process. Only for a session this object created over HTTP (it knows the id).
+      #
+      # @return [Boolean] true when the session is gone.
+      def delete_via_chromedriver
+        return false unless session_id
+
+        outcome = Bidi2pdf::ChromedriverApi.new(session_uri.to_s).delete_session(session_id)
+        Bidi2pdf.notification_service.instrument("session_close_fallback.bidi2pdf", { session_uri: session_uri.to_s, outcome: outcome })
+        cleanup
+        %i[closed gone].include?(outcome)
+      rescue StandardError => e
+        Bidi2pdf.logger.warn "Closing session #{session_id} over HTTP failed: #{e.message}"
+        false
+      end
+
       # Cleans up resources associated with the session.
       def cleanup
         @client&.close

data/lib/bidi2pdf/chrome_sweeper/inspector.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  class ChromeSweeper
+    # Looks at one session on a chromedriver from the outside: attaches a second BiDi connection to
+    # its +webSocketUrl+ (chromedriver allows that for any session), asks for the tab tree, the first
+    # tab's +performance.timeOrigin+ (Chrome keeps no session start time anywhere - the first tab is
+    # created with the session, so its time origin is the session's age to within a few hundred ms)
+    # and the renderer CPU times (CDP +SystemInfo.getProcessInfo+ through +goog:cdp.sendCommand+).
+    #
+    # Read-only, and never reads page content: tab URLs are counted, not returned or logged (a
+    # +data:+ URL carries the whole rendered document). Closes its own connection every time.
+    class Inspector
+      # @!attribute age [Float, nil] seconds since the session started, nil when nothing tells.
+      # @!attribute source [Symbol] :registry, :tab or :unknown - where +age+ comes from.
+      # @!attribute responsive [Boolean] whether the session answered the checks.
+      # @!attribute cpu_times [Hash{Integer => Float}] renderer pid => CPU seconds.
+      # @!attribute live [Boolean] a live process holds its lease (never inspected, never closed).
+      SessionInfo = Data.define(:id, :age, :source, :tabs, :responsive, :cpu_times, :live) do
+        def initialize(live: false, **) = super
+      end
+
+      DEFAULT_TIMEOUT = 5
+
+      # @param clock [#call] epoch seconds as a Float.
+      # @param client_factory [#call] ws_url -> a started, open Bidi::Client; injectable for tests.
+      def initialize(timeout: DEFAULT_TIMEOUT, clock: -> { Time.now.to_f }, client_factory: nil)
+        @timeout = timeout
+        @clock = clock
+        @client_factory = client_factory || method(:connect)
+      end
+
+      # @param entry [ChromedriverApi::Entry]
+      # @param recorded_at [Numeric, nil] epoch seconds the registry has for it; wins over the tab.
+      # @return [SessionInfo]
+      def examine(entry, recorded_at: nil)
+        return unreachable(entry, recorded_at) if entry.websocket_url.nil?
+
+        client = @client_factory.call(entry.websocket_url)
+        probe(client, entry, recorded_at)
+      rescue StandardError => e
+        Bidi2pdf.logger.debug "chrome_sweeper: inspecting session #{entry.id} failed: #{e.message}"
+        unreachable(entry, recorded_at)
+      ensure
+        client&.close
+      end
+
+      private
+
+      def probe(client, entry, recorded_at)
+        contexts = tree(client)
+        return unreachable(entry, recorded_at) if contexts.nil?
+
+        origin = contexts.empty? ? nil : time_origin(client, contexts.first["context"])
+        age, source = age_of(recorded_at, origin)
+
+        SessionInfo.new(id: entry.id, age: age, source: source, tabs: contexts.size,
+                        responsive: contexts.empty? || !origin.nil?, cpu_times: cpu_times(client))
+      end
+
+      def tree(client)
+        once_more_on_timeout { command(client, Bidi2pdf::Bidi::Commands::BrowsingContextGetTree.new).dig("result", "contexts") || [] }
+      rescue Bidi2pdf::CmdTimeoutError
+        nil
+      end
+
+      # A tab stuck in an endless loop never evaluates anything - nil then.
+      def time_origin(client, context)
+        evaluate = Bidi2pdf::Bidi::Commands::ScriptEvaluate.new(expression: "performance.timeOrigin", context: context, await_promise: false)
+        value = once_more_on_timeout { command(client, evaluate) }.dig("result", "result", "value")
+        value.is_a?(Numeric) ? value / 1000.0 : nil
+      rescue Bidi2pdf::CmdError, Bidi2pdf::CmdTimeoutError
+        nil
+      end
+
+      # On a freshly attached connection the first command to a session - and, seen once in the
+      # acceptance run, to a tab - can time out although the session is healthy (chromedriver
+      # 153/154); the second one answers. Only a second timeout counts.
+      def once_more_on_timeout
+        yield
+      rescue Bidi2pdf::CmdTimeoutError
+        yield
+      end
+
+      def cpu_times(client)
+        processes = command(client, Bidi2pdf::Bidi::Commands::CdpSendCommand.new(method: "SystemInfo.getProcessInfo"))
+                    .dig("result", "result", "processInfo") || []
+        processes.select { |process| process["type"] == "renderer" }.to_h { |process| [process["id"], process["cpuTime"].to_f] }
+      rescue Bidi2pdf::CmdError, Bidi2pdf::CmdTimeoutError
+        {}
+      end
+
+      def age_of(recorded_at, origin)
+        return [@clock.call - recorded_at, :registry] if recorded_at
+        return [@clock.call - origin, :tab] if origin
+
+        [nil, :unknown]
+      end
+
+      def unreachable(entry, recorded_at)
+        age, source = age_of(recorded_at, nil)
+        SessionInfo.new(id: entry.id, age: age, source: source, tabs: 0, responsive: false, cpu_times: {})
+      end
+
+      def command(client, cmd)
+        client.send_cmd_and_wait(cmd, timeout: @timeout)
+      end
+
+      def connect(ws_url)
+        client = Bidi2pdf::Bidi::Client.new(ws_url)
+        client.start
+        client.wait_until_open(timeout: @timeout)
+        client
+      end
+    end
+  end
+end

data/lib/bidi2pdf/chrome_sweeper/settings.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  class ChromeSweeper
+    SCOPES = %i[recorded all].freeze
+    DEFAULT_ORPHAN_AGE = 600
+    DEFAULT_MIN_AGE = 60
+    DEFAULT_UNRESPONSIVE_CHECKS = 2
+    DEFAULT_PIDS_BUDGET = 0.8
+    DEFAULT_THREADS_PER_SESSION = 110
+    DEFAULT_LEASE_TTL = SessionRegistry::DEFAULT_LEASE_TTL
+
+    # What a ChromeSweeper closes and when - validated on construction; an unknown setting raises
+    # ArgumentError.
+    #
+    # @!attribute scope [Symbol] :recorded (sessions a SessionRegistry knows) or :all.
+    # @!attribute orphan_age [Numeric, nil] close sessions older than this; nil turns the rule off.
+    # @!attribute min_age [Numeric] never close a session younger than this.
+    # @!attribute unresponsive_checks [Integer, nil] close after this many failed checks in a row.
+    # @!attribute max_sessions [Integer, Symbol, nil] the limit; +:auto+ derives it from pids_limit.
+    # @!attribute pids_limit [Integer, nil] the chromedriver container's pids limit, for +:auto+.
+    # @!attribute pids_budget [Float] share of +pids_limit+ Chrome sessions may use.
+    # @!attribute threads_per_session [Integer] threads (Docker counts them as pids) of one session.
+    # @!attribute interval [Numeric, nil] seconds between sweeps of ChromeSweeper#start's thread.
+    # @!attribute dry_run [Boolean] report what would be closed, close nothing.
+    # @!attribute lease_ttl [Numeric] a recorded session renewed within this many seconds belongs to
+    #   a live process and is never closed (SessionRegistry#hold).
+    Settings = Data.define(:scope, :orphan_age, :min_age, :unresponsive_checks, :max_sessions, :pids_limit,
+                           :pids_budget, :threads_per_session, :interval, :dry_run, :lease_ttl) do
+      # rubocop:disable-next Metrics/ParameterLists
+      def initialize(scope: :recorded, orphan_age: DEFAULT_ORPHAN_AGE, min_age: DEFAULT_MIN_AGE,
+                     unresponsive_checks: DEFAULT_UNRESPONSIVE_CHECKS, max_sessions: nil, pids_limit: nil,
+                     pids_budget: DEFAULT_PIDS_BUDGET, threads_per_session: DEFAULT_THREADS_PER_SESSION,
+                     interval: nil, dry_run: false, lease_ttl: DEFAULT_LEASE_TTL)
+        super
+        validate_scope!
+        validate_numbers!
+      end
+
+      # The session limit in force: +max_sessions+, or for +:auto+ floor(pids_limit x pids_budget /
+      # threads_per_session), at least 1 - nil (no limit) when +:auto+ has no pids_limit.
+      def limit
+        return max_sessions unless max_sessions == :auto
+        return nil unless pids_limit
+
+        [(pids_limit * pids_budget / threads_per_session).floor, 1].max
+      end
+
+      private
+
+      def validate_scope!
+        return if SCOPES.include?(scope)
+
+        raise Bidi2pdf::InvalidConfigError, "chrome_sweeper: scope must be one of #{SCOPES.inspect}, got #{scope.inspect}"
+      end
+
+      def validate_numbers!
+        to_h.slice(:orphan_age, :interval, :pids_limit).each { |name, value| positive!(name, value, allow_nil: true) }
+        to_h.slice(:pids_budget, :threads_per_session, :lease_ttl).each { |name, value| positive!(name, value) }
+        positive!(:min_age, min_age, allow_zero: true)
+        count!(:unresponsive_checks, unresponsive_checks)
+        count!(:max_sessions, max_sessions) unless max_sessions == :auto
+      end
+
+      def positive!(name, value, allow_nil: false, allow_zero: false)
+        return if value.nil? && allow_nil
+        return if value.is_a?(Numeric) && (value.positive? || (allow_zero && value.zero?))
+
+        raise Bidi2pdf::InvalidConfigError, "chrome_sweeper: #{name} must be a positive number, got #{value.inspect}"
+      end
+
+      def count!(name, value)
+        return if value.nil? || (value.is_a?(Integer) && value.positive?)
+
+        raise Bidi2pdf::InvalidConfigError, "chrome_sweeper: #{name} must be nil or a positive Integer, got #{value.inspect}"
+      end
+    end
+  end
+end