bidi2pdf 0.1.17 → 0.1.19

data/lib/bidi2pdf/chrome_sweeper.rb

@@ -0,0 +1,398 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "chromedriver_api"
+require_relative "session_registry"
+require_relative "chrome_sweeper/settings"
+require_relative "chrome_sweeper/inspector"
+
+module Bidi2pdf
+  # Closes Chrome sessions a shared chromedriver holds that nobody will close any more - left behind
+  # by a process that died, or stuck in a tab that never returns - and keeps the number of sessions
+  # below a limit. chromedriver keeps every session (a whole Chrome) until someone deletes it.
+  #
+  # Which sessions it looks at (+scope+):
+  # - +:recorded+ (default) - only sessions a SessionRegistry proves were opened through bidi2pdf.
+  # - +:all+ - every session on that chromedriver (+GET /sessions+), aged by its first tab. Only for
+  #   a chromedriver the application owns: on a shared one it closes other clients' old sessions.
+  #
+  # What it closes, in this order - never a session of +own_sessions+, never one whose lease a live
+  # process keeps renewing (SessionRegistry#hold - a render in flight or a warm spare of another
+  # worker), and never one younger than +min_age+, not even over the limit:
+  # 1. sessions older than +orphan_age+;
+  # 2. sessions that failed +unresponsive_checks+ checks in a row (no answer, or a renderer burning
+  #    CPU at full speed between two sweeps - an endless loop);
+  # 3. while more sessions exist than +max_sessions+, the oldest remaining ones. When that is not
+  #    enough, the sweep reports +limit_exceeded+ and closes nothing more.
+  #
+  # Run it once (#sweep!, ChromeSweeper.sweep!) - e.g. when the application suspects a leak - or
+  # periodically (+interval+, #start/#stop). As a last resort when a render fails for lack of
+  # resources, #with_retry sweeps under +pressure+ - every session nobody holds and older than
+  # +min_age+ goes - and tries once more. One sweep at a time, across processes too (a lock file
+  # next to the registry). Fail-open: a sweep never raises; errors land in the Result. See Settings
+  # for every setting and its default.
+  #
+  # @example A periodic sweeper for an application's own chromedriver
+  #   sweeper = Bidi2pdf::ChromeSweeper.new("http://remote-chrome:3000/session", scope: :all,
+  #                                         max_sessions: :auto, pids_limit: 1024, interval: 60)
+  #   sweeper.start
+  class ChromeSweeper
+    extend Forwardable
+
+    # One closed (or, in a dry run, would-be closed) session. +why+: :orphan, :unresponsive,
+    # :over_limit or :pressure.
+    Closed = Data.define(:id, :age, :why)
+
+    # What one sweep saw and did.
+    Result = Data.define(:reason, :sessions, :inspected, :closed, :unresponsive, :limit, :limit_exceeded,
+                         :dry_run, :skipped, :errors, :duration) do
+      def closed_count = closed.size
+    end
+
+    # A renderer that used at least this share of the wall-clock time between two sweeps counts as
+    # stuck in a loop.
+    BUSY_CPU_SHARE = 0.9
+
+    # Errors #with_retry sweeps and retries on by default: a session chromedriver refused, and a
+    # connection or command that died or timed out - what a Chrome out of memory or pids looks like.
+    # A command Chrome answered with an error (CmdError) is the page's problem, not a resource one.
+    RETRYABLE = ->(error) { error.is_a?(Bidi2pdf::SessionNotStartedError) || (error.is_a?(Bidi2pdf::WebsocketError) && !error.is_a?(Bidi2pdf::CmdError)) }
+
+    # The bookkeeping of one sweep.
+    Sweep = Struct.new(:total, :closed, :unresponsive, :errors, :limit_exceeded, :pressure) do
+      def initialize(total = 0, pressure: false) = super(total, [], [], [], false, pressure)
+
+      def remaining = total - closed.size
+    end
+
+    attr_reader :session_url, :settings, :registry
+
+    def_delegators :@settings, :scope, :orphan_age, :min_age, :unresponsive_checks, :interval, :dry_run, :limit, :lease_ttl
+
+    # One-shot sweep with a throw-away sweeper. Give it a +check_interval+ for the unresponsive rule
+    # to apply - see #sweep!.
+    #
+    # @return [Result]
+    def self.sweep!(session_url, reason: :manual, check_interval: nil, pressure: false, **)
+      new(session_url, **).sweep!(reason: reason, check_interval: check_interval, pressure: pressure)
+    end
+
+    # #with_retry with a throw-away sweeper.
+    def self.with_retry(session_url, retry_on: RETRYABLE, **, &)
+      new(session_url, **).with_retry(retry_on: retry_on, &)
+    end
+
+    # @param session_url [String] chromedriver's new-session URL (".../session").
+    # @param registry [SessionRegistry, nil] defaults to the one for +session_url+ in +registry_dir+.
+    # @param own_sessions [#call] returns the ids of the caller's live sessions - never touched.
+    # @param api [ChromedriverApi, nil], inspector [Inspector, nil], clock [#call] - for tests.
+    # @param settings see Settings.
+    # @raise [InvalidConfigError] for a setting out of range.
+    def initialize(session_url, registry: nil, registry_dir: nil, own_sessions: -> { [] },
+                   api: nil, inspector: nil, clock: -> { Time.now.to_f }, **settings)
+      @session_url = session_url.to_s
+      @settings = Settings.new(**settings)
+      @own_sessions = own_sessions
+      @clock = clock
+      @registry = registry || Bidi2pdf::SessionRegistry.new(@session_url, dir: registry_dir)
+      @api = api || Bidi2pdf::ChromedriverApi.new(@session_url)
+      @inspector = inspector || Inspector.new(clock: clock)
+      @mutex = Mutex.new
+      @wakeup = Thread::Queue.new
+      @failures = Hash.new(0)
+      @first_seen = {}
+      @cpu_samples = {}
+    end
+
+    # Every session in scope, inspected (age, tabs, responsive) - for diagnostics; closes nothing.
+    #
+    # @return [Array<Inspector::SessionInfo>]
+    def sessions
+      recorded = @registry.recorded
+      live = live_sessions
+      in_scope(@api.sessions, recorded).map do |entry|
+        next live_info(entry.id, recorded[entry.id]) if live.include?(entry.id)
+
+        @inspector.examine(entry, recorded_at: recorded[entry.id])
+      end
+    end
+
+    # Runs the block; when it fails with a resource error (+retry_on+: a callable or a list of error
+    # classes, RETRYABLE by default), sweeps under pressure and runs it once more. The block must
+    # be safe to run twice - it gets a new session the second time. Other errors, and a second
+    # failure, propagate unchanged.
+    def with_retry(retry_on: RETRYABLE)
+      yield
+    rescue StandardError => e
+      raise unless retryable?(retry_on, e)
+
+      Bidi2pdf.logger.warn "chrome_sweeper: #{e.class}: #{e.message} - sweeping #{@session_url} and trying once more"
+      Bidi2pdf.notification_service.instrument("chrome_sweeper.retry.bidi2pdf", { error: e.class.name })
+      sweep!(reason: :render_failed, pressure: true)
+      yield
+    end
+
+    # Inspects every session in scope and counts its checks, like a sweep, but closes nothing.
+    #
+    # @return [Array<Inspector::SessionInfo>]
+    def observe
+      @mutex.synchronize { observe_entries(@api.sessions) }
+    end
+
+    # Sweeps once. Skipped (Result#skipped) when another sweep - in this or another process - is
+    # still running.
+    #
+    # A session counts as hung only after +unresponsive_checks+ failed checks, one per sweep - a
+    # one-shot sweep never gets there. With +check_interval+ it first checks
+    # +unresponsive_checks - 1+ times, +check_interval+ seconds apart (#observe), so a single call
+    # applies every rule. The periodic thread doesn't need that: its sweeps are the checks.
+    #
+    # @param reason [Symbol] why - reported in the notification (:manual, :periodic, :create_failed…).
+    # Under +pressure+ - the last resort when a render failed - every eligible session is closed:
+    # nobody holds it, and it is older than +min_age+; +orphan_age+, the unresponsive checks and the
+    # limit no longer matter.
+    #
+    # @param check_interval [Numeric, nil] seconds between those checks; nil sweeps right away.
+    # @param pressure [Boolean] close everything nobody holds that is past +min_age+.
+    # @return [Result]
+    def sweep!(reason: :manual, check_interval: nil, pressure: false)
+      check_first(check_interval) if check_interval
+      started = monotonic
+      return result(reason, started, skipped: true) unless @mutex.try_lock
+
+      begin
+        with_lock_file { |locked| locked ? run(reason, started, pressure) : result(reason, started, skipped: true) }
+      ensure
+        @mutex.unlock
+      end
+    end
+
+    # Starts the periodic sweep thread (needs an +interval+). Idempotent.
+    def start
+      raise Bidi2pdf::InvalidConfigError, "chrome_sweeper: start needs an interval" unless interval
+
+      @thread ||= Thread.new { sweep!(reason: :periodic) until @wakeup.pop(timeout: interval) == :stop }
+      self
+    end
+
+    # Stops the periodic sweep thread and waits for a sweep in progress to finish.
+    def stop
+      return unless @thread
+
+      @wakeup << :stop
+      @thread.join
+      @thread = nil
+    end
+
+    private
+
+    def run(reason, started, pressure)
+      sweep, infos = sweep_sessions(pressure)
+      report(result(reason, started, sweep: sweep, inspected: infos))
+    rescue StandardError => e
+      Bidi2pdf.logger.warn "chrome_sweeper: sweep of #{@session_url} failed: #{e.message}"
+      Bidi2pdf.notification_service.instrument("chrome_sweeper.failed.bidi2pdf", { reason: reason, error: e.class.name })
+      result(reason, started, sweep: Sweep.new.tap { |failed| failed.errors << e.message })
+    end
+
+    # A config error raises; a failed check only means the sweep has fewer checks to go on.
+    def check_first(check_interval)
+      raise Bidi2pdf::InvalidConfigError, "chrome_sweeper: check_interval must be a positive number, got #{check_interval.inspect}" unless check_interval.is_a?(Numeric) && check_interval.positive?
+
+      (unresponsive_checks.to_i - 1).times { observe_then_wait(check_interval) }
+    end
+
+    def observe_then_wait(check_interval)
+      observe
+    rescue StandardError => e
+      Bidi2pdf.logger.warn "chrome_sweeper: checking #{@session_url} before the sweep failed: #{e.message}"
+    ensure
+      sleep check_interval
+    end
+
+    def sweep_sessions(pressure)
+      entries = @api.sessions
+      infos = observe_entries(entries)
+      sweep = Sweep.new(entries.size, pressure: pressure)
+      decide(infos.select { |info| info.age >= min_age }, sweep)
+      [sweep, infos]
+    end
+
+    # In-scope sessions not owned by the caller, not held by a live process and not known to be
+    # younger than min_age, with the registry time when there is one. None of the others is even
+    # attached to - a render in flight is left alone entirely.
+    def candidates(entries)
+      recorded = @registry.recorded
+      untouchable = Array(@own_sessions.call).map(&:to_s) + live_sessions
+      in_scope(entries, recorded).filter_map do |entry|
+        recorded_at = recorded[entry.id]
+        next if untouchable.include?(entry.id) || (recorded_at && now - recorded_at < min_age)
+
+        [entry, recorded_at]
+      end
+    end
+
+    def live_sessions
+      @registry.leased(now: now, ttl: lease_ttl)
+    end
+
+    def live_info(id, recorded_at)
+      Inspector::SessionInfo.new(id: id, age: recorded_at && (now - recorded_at), source: :registry, tabs: nil,
+                                 responsive: nil, cpu_times: {}, live: true)
+    end
+
+    def retryable?(retry_on, error)
+      retry_on.respond_to?(:call) ? retry_on.call(error) : Array(retry_on).any? { |klass| error.is_a?(klass) }
+    end
+
+    def in_scope(entries, recorded)
+      scope == :all ? entries : entries.select { |entry| recorded.key?(entry.id) }
+    end
+
+    def observe_entries(entries)
+      forget_gone(entries)
+      candidates(entries).map { |entry, recorded_at| track(@inspector.examine(entry, recorded_at: recorded_at)) }
+    end
+
+    # Sessions chromedriver no longer has are dropped from the registry and from this sweeper's own
+    # tracking - most sessions end normally, so a long-running sweeper would otherwise keep every id
+    # it ever saw.
+    def forget_gone(entries)
+      ids = entries.map(&:id)
+      (@registry.recorded.keys - ids).each { |id| @registry.forget(id) }
+      (@first_seen.keys - ids).each { |id| forget_tracking(id) }
+    end
+
+    def forget_tracking(id)
+      [@failures, @first_seen, @cpu_samples].each { |tracked| tracked.delete(id) }
+    end
+
+    # Counts failed checks per session across sweeps, and ages a session by when this sweeper first
+    # saw it when nothing better is known.
+    def track(info)
+      count_check(info)
+      @first_seen[info.id] ||= now
+      info.with(age: [info.age || 0, now - @first_seen[info.id]].max)
+    end
+
+    def count_check(info)
+      failed = !info.responsive || busy?(info)
+      @failures[info.id] = failed ? @failures[info.id] + 1 : 0
+      @cpu_samples[info.id] = [now, info.cpu_times]
+    end
+
+    def busy?(info)
+      sampled_at, times = @cpu_samples[info.id]
+      return false unless sampled_at && now > sampled_at
+
+      info.cpu_times.any? { |pid, cpu| times.key?(pid) && (cpu - times[pid]) / (now - sampled_at) >= BUSY_CPU_SHARE }
+    end
+
+    def decide(eligible, sweep)
+      eligible.each do |info|
+        why = close_reason(info, sweep) || (:pressure if sweep.pressure)
+        close_session(info, why, sweep) if why
+      end
+
+      enforce_limit(eligible, sweep)
+    end
+
+    def close_reason(info, sweep)
+      failed = @failures[info.id]
+      note_unresponsive(info, failed, sweep) if unresponsive_checks && failed.positive?
+      return :orphan if orphan_age && info.age > orphan_age
+
+      :unresponsive if unresponsive_checks && failed >= unresponsive_checks
+    end
+
+    def note_unresponsive(info, failed, sweep)
+      sweep.unresponsive << info.id
+      Bidi2pdf.notification_service.instrument("chrome_sweeper.unresponsive.bidi2pdf", { id: info.id, checks: failed })
+    end
+
+    def enforce_limit(eligible, sweep)
+      return unless over_limit?(sweep)
+
+      oldest_open(eligible, sweep).each do |info|
+        break unless over_limit?(sweep)
+
+        close_session(info, :over_limit, sweep)
+      end
+      limit_exceeded(sweep) if over_limit?(sweep)
+    end
+
+    def over_limit?(sweep) = !limit.nil? && sweep.remaining > limit
+
+    def oldest_open(eligible, sweep)
+      closed_ids = sweep.closed.map(&:id)
+      eligible.reject { |info| closed_ids.include?(info.id) }.sort_by { |info| -info.age }
+    end
+
+    def limit_exceeded(sweep)
+      sweep.limit_exceeded = true
+      Bidi2pdf.logger.warn "chrome_sweeper: #{sweep.remaining} sessions on #{@session_url}, limit #{limit} - none left old enough to close"
+      Bidi2pdf.notification_service.instrument("chrome_sweeper.limit_exceeded.bidi2pdf", { sessions: sweep.remaining, limit: limit })
+    end
+
+    # Adds the session to the sweep's closed list unless chromedriver refused to close it.
+    def close_session(info, why, sweep)
+      return sweep.errors << "closing #{info.id} failed" unless dry_run || gone_after_delete?(info.id)
+
+      sweep.closed << announce(Closed.new(id: info.id, age: info.age.round, why: why))
+    end
+
+    def announce(closed)
+      Bidi2pdf.notification_service.instrument("chrome_sweeper.closed.bidi2pdf", closed.to_h.merge(dry_run: dry_run))
+      closed
+    end
+
+    def gone_after_delete?(id)
+      return false if @api.delete_session(id) == :failed
+
+      @registry.forget(id)
+      forget_tracking(id)
+      true
+    end
+
+    def report(result)
+      verb = dry_run ? "would close" : "closed"
+      Bidi2pdf.logger.info "chrome_sweeper: #{verb} #{result.closed_count} of #{result.sessions} session(s) on #{@session_url}" if result.closed.any?
+      Bidi2pdf.notification_service.instrument("chrome_sweeper.sweep.bidi2pdf", sweep_payload(result))
+      result
+    end
+
+    def sweep_payload(result)
+      result.to_h.slice(:reason, :sessions, :limit, :limit_exceeded, :dry_run, :duration)
+            .merge(inspected: result.inspected.size, closed: result.closed_count)
+    end
+
+    def result(reason, started, sweep: Sweep.new, inspected: [], skipped: false)
+      Result.new(reason: reason, sessions: sweep.total, inspected: inspected, closed: sweep.closed,
+                 unresponsive: sweep.unresponsive, limit: limit, limit_exceeded: sweep.limit_exceeded,
+                 dry_run: dry_run, skipped: skipped, errors: sweep.errors, duration: monotonic - started)
+    end
+
+    # A lock file next to the registry, so processes sharing it never sweep at the same time. When
+    # the file cannot be created at all the sweep still runs (fail-open, like the registry itself).
+    def with_lock_file
+      file = open_lock_file
+      return yield(true) unless file
+
+      begin
+        yield file.flock(File::LOCK_EX | File::LOCK_NB)
+      ensure
+        file.close
+      end
+    end
+
+    def open_lock_file
+      File.open("#{@registry.path}.lock", File::RDWR | File::CREAT, 0o600)
+    rescue SystemCallError
+      nil
+    end
+
+    def now = @clock.call
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/bidi2pdf/chromedriver_api.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Bidi2pdf
+  # The two chromedriver HTTP endpoints session cleanup needs, next to the BiDi protocol: the
+  # non-standard +GET /sessions+ (every session on that chromedriver - WebDriver itself has no way to
+  # list them, BiDi neither) and +DELETE /session/{id}+ (ends a session and its Chrome even when that
+  # Chrome no longer answers BiDi).
+  #
+  # Built from the new-session URL every other part of bidi2pdf is configured with
+  # ("http://host:3000/session").
+  class ChromedriverApi
+    # One entry of +GET /sessions+: chromedriver gives no creation time, no owner, and no hint
+    # whether a client is still connected (checked against chromedriver 153/154).
+    Entry = Data.define(:id, :websocket_url, :process_id)
+
+    DEFAULT_TIMEOUT = 30
+
+    attr_reader :session_url
+
+    # @param session_url [String] chromedriver's new-session URL (".../session").
+    # @param http [#call, nil] (method, url) -> [status, body]; injectable for tests.
+    def initialize(session_url, http: nil, timeout: DEFAULT_TIMEOUT)
+      @session_url = session_url.to_s.chomp("/")
+      @timeout = timeout
+      @http = http || method(:net_http)
+    end
+
+    # @return [Array<Entry>] every session chromedriver holds right now.
+    def sessions
+      status, body = @http.call(:get, sessions_url)
+      raise Bidi2pdf::Error, "chromedriver answered #{status} to GET /sessions" unless status == 200
+
+      Array(JSON.parse(body)["value"]).map do |session|
+        capabilities = session["capabilities"] || {}
+        Entry.new(id: session["id"], websocket_url: capabilities["webSocketUrl"], process_id: capabilities["goog:processID"])
+      end
+    end
+
+    # Ends a session. chromedriver answers 404 ("invalid session id") for one it no longer has.
+    #
+    # @return [Symbol] :closed, :gone or :failed
+    def delete_session(id)
+      status, = @http.call(:delete, "#{session_url}/#{id}")
+      case status
+      when 200 then :closed
+      when 404 then :gone
+      else :failed
+      end
+    end
+
+    private
+
+    # "http://host:3000/session" -> "http://host:3000/sessions"; a chromedriver started with a
+    # --url-base keeps its prefix.
+    def sessions_url
+      "#{session_url.delete_suffix("/session")}/sessions"
+    end
+
+    def net_http(method, url)
+      uri = URI(url)
+      request = method == :delete ? Net::HTTP::Delete.new(uri) : Net::HTTP::Get.new(uri)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: @timeout) do |http|
+        response = http.request(request)
+        [response.code.to_i, response.body]
+      end
+    end
+  end
+end

data/lib/bidi2pdf/cli/session_commands.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  class CLI < Thor
+    # Output of `bidi2pdf sessions` and `bidi2pdf sweep` (ChromeSweeper). Never prints a tab URL or
+    # any page content - only ids, ages, tab counts and what was done.
+    module SessionCommands
+      # CLI flag => ChromeSweeper setting, for the ones that are only passed when given.
+      SWEEP_FLAGS = { older_than: :orphan_age, max_sessions: :max_sessions, min_age: :min_age,
+                      unresponsive_checks: :unresponsive_checks }.freeze
+      # Settings that are counts - Thor hands every numeric over as a Float.
+      COUNT_SETTINGS = %i[max_sessions unresponsive_checks].freeze
+
+      private
+
+      def chrome_sweeper
+        url = options[:remote_browser_url]
+        raise Thor::Error, "--remote-browser-url is required" if url.to_s.empty?
+
+        Bidi2pdf::ChromeSweeper.new(url, scope: options[:scope].to_sym, dry_run: options[:dry_run], **sweep_flags)
+      rescue Bidi2pdf::InvalidConfigError => e
+        raise Thor::Error, e.message
+      end
+
+      def sweep_flags
+        SWEEP_FLAGS.filter_map do |flag, setting|
+          value = options[flag]
+          [setting, COUNT_SETTINGS.include?(setting) ? value.to_i : value] unless value.nil?
+        end.to_h
+      end
+
+      # --check-interval 0 means no checks before the sweep.
+      def run_sweep
+        interval = options[:check_interval].to_f
+        chrome_sweeper.sweep!(reason: :cli, check_interval: interval.zero? ? nil : interval, pressure: options[:pressure])
+      rescue Bidi2pdf::InvalidConfigError => e
+        raise Thor::Error, e.message
+      end
+
+      def session_hash(info)
+        { id: info.id, age: info.age&.round, source: info.source, tabs: info.tabs, responsive: info.responsive, live: info.live }
+      end
+
+      def print_sessions(infos)
+        return puts "no sessions" if infos.empty?
+
+        infos.each do |info|
+          age = info.age ? "#{info.age.round}s" : "?"
+          puts format("%-34<id>s %8<age>s  %-8<source>s %9<tabs>s  %<state>s",
+                      id: info.id, age: age, source: info.source, tabs: info.tabs ? "#{info.tabs} tab(s)" : "", state: session_state(info))
+        end
+      end
+
+      # A live session is not attached to, so there is nothing to say about its tabs.
+      def session_state(info)
+        return "live (a running process holds it)" if info.live
+
+        info.responsive ? "responsive" : "unresponsive"
+      end
+
+      def sweep_hash(result)
+        { reason: result.reason, sessions: result.sessions, dry_run: result.dry_run, skipped: result.skipped,
+          closed: result.closed.map(&:to_h), unresponsive: result.unresponsive, limit: result.limit,
+          limit_exceeded: result.limit_exceeded, errors: result.errors }
+      end
+
+      def print_sweep(result)
+        return puts "skipped: another sweep is running" if result.skipped
+
+        verb = result.dry_run ? "would close" : "closed"
+        result.closed.each { |closed| puts "#{verb} #{closed.id} (#{closed.why}, #{closed.age}s old)" }
+        puts "#{verb} #{result.closed_count} of #{result.sessions} session(s)"
+        print_sweep_problems(result)
+      end
+
+      def print_sweep_problems(result)
+        puts "limit #{result.limit} still exceeded - no session old enough to close" if result.limit_exceeded
+        result.errors.each { |error| warn "error: #{error}" }
+      end
+    end
+  end
+end

data/lib/bidi2pdf/cli.rb

@@ -5,11 +5,13 @@ require "yaml"
 require "tempfile"
 
 require_relative "cli/json_output"
+require_relative "cli/session_commands"
 
 module Bidi2pdf
   # rubocop:disable Metrics/AbcSize
   class CLI < Thor
     include JsonOutput
+    include SessionCommands
 
     class_option :config, type: :string, desc: "Load configuration from YAML file"
 
@@ -183,6 +185,47 @@ module Bidi2pdf
     end
     map "run" => :run_recipe
 
+    desc "sessions", "List the Chrome sessions a remote chromedriver holds: id, age, tabs, responsive (no URLs)"
+    option :remote_browser_url, type: :string, required: true, desc: "The chromedriver's new-session URL (http://host:3000/session)"
+    option :scope, type: :string, default: "all", enum: %w[all recorded], desc: "all sessions, or only those bidi2pdf recorded"
+    option :json, type: :boolean, default: false, desc: "Emit a JSON array instead of a table"
+
+    def sessions
+      return print_sessions(chrome_sweeper.sessions) unless options[:json]
+
+      reserve_stdout_for_machine_output { puts JSON.generate(chrome_sweeper.sessions.map { |info| session_hash(info) }) }
+    end
+
+    desc "sweep", "Close leaked Chrome sessions on a remote chromedriver (too old, unresponsive, or over a limit)"
+    long_desc <<~USAGE, wrap: false
+      Closes sessions older than --older-than seconds, sessions that failed --unresponsive-checks
+      checks in a row (taken --check-interval seconds apart, so a sweep takes that long), and while
+      more than --max-sessions exist, the oldest ones. A session younger than --min-age seconds is
+      never closed, and neither is one a running bidi2pdf process holds (its lease is renewed). --scope all looks at
+      every session on that chromedriver - use it only for a chromedriver your application owns;
+      --scope recorded (default) only at sessions bidi2pdf recorded on this machine.
+      Exits 1 when a close failed or the limit is still exceeded.
+    USAGE
+    option :remote_browser_url, type: :string, required: true, desc: "The chromedriver's new-session URL (http://host:3000/session)"
+    option :scope, type: :string, default: "recorded", enum: %w[recorded all], desc: "Which sessions may be closed"
+    option :older_than, type: :numeric, desc: "Close sessions older than this many seconds (default 600)"
+    option :max_sessions, type: :numeric, desc: "Close the oldest sessions while more than this many exist"
+    option :min_age, type: :numeric, desc: "Never close a session younger than this many seconds (default 60)"
+    option :unresponsive_checks, type: :numeric, desc: "Close a session after this many failed checks in a row (default 2)"
+    option :check_interval, type: :numeric, default: 10, desc: "Seconds between those checks; 0 sweeps at once, without the unresponsive rule"
+    option :pressure, type: :boolean, default: false, desc: "Last resort: close every session no live process holds that is past --min-age"
+    option :dry_run, type: :boolean, default: false, desc: "Report what would be closed, close nothing"
+    option :json, type: :boolean, default: false, desc: "Emit the sweep result as JSON"
+
+    def sweep
+      result = if options[:json]
+                 reserve_stdout_for_machine_output { run_sweep.tap { |swept| puts JSON.generate(sweep_hash(swept)) } }
+               else
+                 run_sweep.tap { |swept| print_sweep(swept) }
+               end
+      exit(1) if result.errors.any? || result.limit_exceeded
+    end
+
     desc "template", "Generate a config file template"
     option :output, default: "bidi2pdf.yml", desc: "Output configuration filename"
 

data/lib/bidi2pdf/dsl.rb

@@ -47,7 +47,8 @@ module Bidi2pdf
                     Bidi2pdf::Bidi::Session.new(
                       session_url: remote_browser_url,
                       headless: true, # remote is always headless
-                      chrome_args: chrome_args
+                      chrome_args: chrome_args,
+                      registry: Bidi2pdf::SessionRegistry.new(remote_browser_url)
                     )
                   else
                     manager = Bidi2pdf::ChromedriverManager.new(port: port, headless: headless, chrome_args: chrome_args)

data/lib/bidi2pdf/launcher.rb

@@ -109,7 +109,8 @@ module Bidi2pdf
 
     def session
       if @remote_browser_url
-        @custom_session = Bidi::Session.new(session_url: @remote_browser_url, headless: @headless, chrome_args: @chrome_args)
+        @custom_session = Bidi::Session.new(session_url: @remote_browser_url, headless: @headless, chrome_args: @chrome_args,
+                                            registry: Bidi2pdf::SessionRegistry.new(@remote_browser_url))
       else
         @manager = ChromedriverManager.new(port: @port, headless: @headless, chrome_args: @chrome_args)
         @manager.start