bidi2pdf 0.1.16 → 0.1.18

data/sig/bidi2pdf/bidi/session.rbs

@@ -27,12 +27,16 @@ module Bidi2pdf
 
       @chrome_args: untyped
 
+      @registry: untyped
+
       @client: untyped
 
       @browser: untyped
 
       @websocket_url: untyped
 
+      @session_id: untyped
+
       # Events to subscribe to during the session.
       SUBSCRIBE_EVENTS: ::Array["script"]
 
@@ -48,12 +52,19 @@ module Bidi2pdf
       # @return [Array<String>] The Chrome arguments for the session.
       attr_reader chrome_args: untyped
 
+      # @return [String, nil] chromedriver's id for this session, once it was created - what
+      #   SessionWarmer records so a later process can close it if this one dies uncleanly.
+      attr_reader session_id: untyped
+
       # Initializes a new session.
       #
       # @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: untyped, ?headless: bool, ?chrome_args: untyped) -> void
+      # @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: untyped, ?headless: bool, ?chrome_args: untyped, ?registry: untyped?) -> void
 
       # Starts the session and initializes the client.
       #
@@ -70,8 +81,8 @@ module Bidi2pdf
       # @return [Bidi2pdf::Bidi::Browser] The browser instance.
       def browser: () -> untyped
 
-      # 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: () -> untyped
 
       # Retrieves user contexts for the session.
@@ -158,6 +169,17 @@ module Bidi2pdf
       # @raise [SessionNotStartedError] If the session could not be started.
       def handle_error: (untyped value) -> (nil | untyped)
 
+      def end_via_bidi: () -> untyped
+
+      def record_session: (untyped id) -> untyped
+
+      # 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: () -> untyped
+
       # Cleans up resources associated with the session.
       def cleanup: () -> untyped
     end

data/sig/bidi2pdf/chrome_sweeper/inspector.rbs

@@ -0,0 +1,61 @@
+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
+      @timeout: untyped
+
+      @clock: untyped
+
+      @client_factory: untyped
+
+      # @!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: untyped
+
+      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: untyped, ?clock: untyped, ?client_factory: untyped?) -> void
+
+      # @param entry [ChromedriverApi::Entry]
+      # @param recorded_at [Numeric, nil] epoch seconds the registry has for it; wins over the tab.
+      # @return [SessionInfo]
+      def examine: (untyped entry, ?recorded_at: untyped?) -> untyped
+
+      private
+
+      def probe: (untyped client, untyped entry, untyped recorded_at) -> untyped
+
+      def tree: (untyped client) -> untyped
+
+      # A tab stuck in an endless loop never evaluates anything - nil then.
+      def time_origin: (untyped client, untyped context) -> untyped
+
+      # 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: () { () -> untyped } -> untyped
+
+      def cpu_times: (untyped client) -> untyped
+
+      def age_of: (untyped recorded_at, untyped origin) -> (::Array[untyped | :registry] | ::Array[untyped | :tab] | ::Array[nil | :unknown])
+
+      def unreachable: (untyped entry, untyped recorded_at) -> untyped
+
+      def command: (untyped client, untyped cmd) -> untyped
+
+      def connect: (untyped ws_url) -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/chrome_sweeper/settings.rbs

@@ -0,0 +1,34 @@
+module Bidi2pdf
+  class ChromeSweeper
+    SCOPES: ::Array[:recorded | :all]
+
+    DEFAULT_ORPHAN_AGE: 600
+
+    DEFAULT_MIN_AGE: 60
+
+    DEFAULT_UNRESPONSIVE_CHECKS: 2
+
+    DEFAULT_PIDS_BUDGET: ::Float
+
+    DEFAULT_THREADS_PER_SESSION: 110
+
+    DEFAULT_LEASE_TTL: untyped
+
+    # 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: untyped
+  end
+end

data/sig/bidi2pdf/chrome_sweeper.rbs

@@ -0,0 +1,220 @@
+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
+    @session_url: untyped
+
+    @settings: untyped
+
+    @own_sessions: untyped
+
+    @clock: untyped
+
+    @registry: untyped
+
+    @api: untyped
+
+    @inspector: untyped
+
+    @mutex: untyped
+
+    @wakeup: untyped
+
+    @failures: untyped
+
+    @first_seen: untyped
+
+    @cpu_samples: untyped
+
+    @thread: untyped
+
+    extend Forwardable
+
+    # One closed (or, in a dry run, would-be closed) session. +why+: :orphan, :unresponsive,
+    # :over_limit or :pressure.
+    Closed: untyped
+
+    # What one sweep saw and did.
+    Result: untyped
+
+    # 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: ::Float
+
+    # 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: untyped
+
+    # The bookkeeping of one sweep.
+    Sweep: untyped
+
+    attr_reader session_url: untyped
+
+    attr_reader settings: untyped
+
+    attr_reader registry: untyped
+
+    # 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!: (untyped session_url, ?reason: ::Symbol, ?check_interval: untyped?, ?pressure: bool, **untyped) -> untyped
+
+    # #with_retry with a throw-away sweeper.
+    def self.with_retry: (untyped session_url, ?retry_on: untyped, **untyped) { (?) -> untyped } -> untyped
+
+    # @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: (untyped session_url, ?registry: untyped?, ?registry_dir: untyped?, ?own_sessions: untyped, ?api: untyped?, ?inspector: untyped?, ?clock: untyped, **untyped settings) -> void
+
+    # Every session in scope, inspected (age, tabs, responsive) - for diagnostics; closes nothing.
+    #
+    # @return [Array<Inspector::SessionInfo>]
+    def sessions: () -> untyped
+
+    # 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: untyped) { () -> untyped } -> untyped
+
+    # Inspects every session in scope and counts its checks, like a sweep, but closes nothing.
+    #
+    # @return [Array<Inspector::SessionInfo>]
+    def observe: () -> untyped
+
+    # 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: ::Symbol, ?check_interval: untyped?, ?pressure: bool) -> untyped
+
+    # Starts the periodic sweep thread (needs an +interval+). Idempotent.
+    def start: () -> self
+
+    # Stops the periodic sweep thread and waits for a sweep in progress to finish.
+    def stop: () -> (nil | untyped)
+
+    private
+
+    def run: (untyped reason, untyped started, untyped pressure) -> untyped
+
+    # A config error raises; a failed check only means the sweep has fewer checks to go on.
+    def check_first: (untyped check_interval) -> untyped
+
+    def observe_then_wait: (untyped check_interval) -> untyped
+
+    def sweep_sessions: (untyped pressure) -> ::Array[untyped]
+
+    # 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: (untyped entries) -> untyped
+
+    def live_sessions: () -> untyped
+
+    def live_info: (untyped id, untyped recorded_at) -> untyped
+
+    def retryable?: (untyped retry_on, untyped error) -> untyped
+
+    def in_scope: (untyped entries, untyped recorded) -> untyped
+
+    def observe_entries: (untyped entries) -> untyped
+
+    # 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: (untyped entries) -> untyped
+
+    def forget_tracking: (untyped id) -> untyped
+
+    # 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: (untyped info) -> untyped
+
+    def count_check: (untyped info) -> untyped
+
+    def busy?: (untyped info) -> (false | untyped)
+
+    def decide: (untyped eligible, untyped sweep) -> untyped
+
+    def close_reason: (untyped info, untyped sweep) -> (:orphan | untyped)
+
+    def note_unresponsive: (untyped info, untyped failed, untyped sweep) -> untyped
+
+    def enforce_limit: (untyped eligible, untyped sweep) -> (nil | untyped)
+
+    def over_limit?: (untyped sweep) -> untyped
+
+    def oldest_open: (untyped eligible, untyped sweep) -> untyped
+
+    def limit_exceeded: (untyped sweep) -> untyped
+
+    # Adds the session to the sweep's closed list unless chromedriver refused to close it.
+    def close_session: (untyped info, untyped why, untyped sweep) -> untyped
+
+    def announce: (untyped closed) -> untyped
+
+    def gone_after_delete?: (untyped id) -> (false | true)
+
+    def report: (untyped result) -> untyped
+
+    def sweep_payload: (untyped result) -> untyped
+
+    def result: (untyped reason, untyped started, ?sweep: untyped, ?inspected: untyped, ?skipped: bool) -> untyped
+
+    # 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: () { (untyped) -> untyped } -> untyped
+
+    def open_lock_file: () -> untyped
+
+    def now: () -> untyped
+
+    def monotonic: () -> untyped
+  end
+end

data/sig/bidi2pdf/chromedriver_api.rbs

@@ -0,0 +1,44 @@
+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
+    @session_url: untyped
+
+    @timeout: untyped
+
+    @http: untyped
+
+    # 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: untyped
+
+    DEFAULT_TIMEOUT: 30
+
+    attr_reader session_url: untyped
+
+    # @param session_url [String] chromedriver's new-session URL (".../session").
+    # @param http [#call, nil] (method, url) -> [status, body]; injectable for tests.
+    def initialize: (untyped session_url, ?http: untyped?, ?timeout: untyped) -> void
+
+    # @return [Array<Entry>] every session chromedriver holds right now.
+    def sessions: () -> untyped
+
+    # Ends a session. chromedriver answers 404 ("invalid session id") for one it no longer has.
+    #
+    # @return [Symbol] :closed, :gone or :failed
+    def delete_session: (untyped id) -> untyped
+
+    private
+
+    # "http://host:3000/session" -> "http://host:3000/sessions"; a chromedriver started with a
+    # --url-base keeps its prefix.
+    def sessions_url: () -> ::String
+
+    def net_http: (untyped method, untyped url) -> untyped
+  end
+end

data/sig/bidi2pdf/cli/session_commands.rbs

@@ -0,0 +1,35 @@
+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 }
+
+      # Settings that are counts - Thor hands every numeric over as a Float.
+      COUNT_SETTINGS: ::Array[:max_sessions | :unresponsive_checks]
+
+      private
+
+      def chrome_sweeper: () -> untyped
+
+      def sweep_flags: () -> untyped
+
+      # --check-interval 0 means no checks before the sweep.
+      def run_sweep: () -> untyped
+
+      def session_hash: (untyped info) -> { id: untyped, age: untyped, source: untyped, tabs: untyped, responsive: untyped, live: untyped }
+
+      def print_sessions: (untyped infos) -> untyped
+
+      # A live session is not attached to, so there is nothing to say about its tabs.
+      def session_state: (untyped info) -> ("live (a running process holds it)" | untyped)
+
+      def sweep_hash: (untyped result) -> { reason: untyped, sessions: untyped, dry_run: untyped, skipped: untyped, closed: untyped, unresponsive: untyped, limit: untyped, limit_exceeded: untyped, errors: untyped }
+
+      def print_sweep: (untyped result) -> untyped
+
+      def print_sweep_problems: (untyped result) -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/cli.rbs

@@ -13,6 +13,8 @@ module Bidi2pdf
 
     include JsonOutput
 
+    include SessionCommands
+
     def self.exit_on_failure?: () -> true
 
     def render: () -> (nil | untyped)
@@ -28,6 +30,10 @@ module Bidi2pdf
     # below is what makes `bidi2pdf run recipe.yml` dispatch here.
     def run_recipe: (untyped recipe_path) -> untyped
 
+    def sessions: () -> untyped
+
+    def sweep: () -> untyped
+
     def template: () -> untyped
 
     private

data/sig/bidi2pdf/session_registry/heartbeat.rbs

@@ -0,0 +1,47 @@
+module Bidi2pdf
+  class SessionRegistry
+    # Keeps the leases of every session this process holds fresh: one thread per process renews
+    # them in their registry files every +interval+ seconds, so a sweeper in another process (a
+    # second Puma worker, a job worker sharing the registry directory) can tell a live session
+    # from one whose process died. The thread runs only while something is held.
+    #
+    # Fork-aware: a child process (Puma forks its workers) starts with nothing held and without the
+    # parent's thread - the parent's sessions are the parent's to renew.
+    module Heartbeat
+      self.@mutex: untyped
+
+      self.@held: untyped
+
+      self.@pid: untyped
+
+      self.@thread: untyped
+
+      DEFAULT_INTERVAL: untyped
+
+      # @return [Numeric] seconds between renewals - keep it well below the sweeper's lease_ttl.
+      attr_writer self.interval: untyped
+
+      def self.interval: () -> untyped
+
+      def self.hold: (untyped registry, untyped session_id) -> untyped
+
+      def self.release: (untyped registry, untyped session_id) -> untyped
+
+      # @return [Array<String>] the session ids this process holds in +registry+'s file.
+      def self.held_ids: (untyped registry) -> untyped
+
+      # Renews every held lease now.
+      def self.beat!: (?now: untyped) -> untyped
+
+      private
+
+      def self.beat_loop: () -> untyped
+
+      def self.held: () -> untyped
+
+      def self.reset_after_fork: () -> (nil | untyped)
+
+      def self.synchronize: () { (?) -> untyped } -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/session_registry.rbs

@@ -0,0 +1,75 @@
+module Bidi2pdf
+  # Remembers which sessions bidi2pdf opened on a shared (remote) chromedriver, when, by which
+  # process, and whether that process is still alive - in a small JSON file per chromedriver URL - so
+  # a process started later, or a ChromeSweeper, can find and close the ones a process that died
+  # without a clean shutdown left behind (see SessionSweeper). chromedriver itself keeps a session
+  # until someone deletes it, and it drops any tag we could attach to one (a custom capability is
+  # accepted but echoed nowhere - checked against chromedriver 153), hence a file.
+  #
+  # Liveness is a lease: a session the process #hold s is renewed by its Heartbeat every
+  # Heartbeat.interval seconds. A session whose lease is fresh belongs to a live process - a render
+  # in flight or a warm spare - and no sweeper closes it; one whose lease ran out belongs to a dead
+  # process. #record alone writes an entry nobody renews.
+  #
+  # Everything here is best effort and fail-open: a directory that is not writable, a locked-out or
+  # corrupt file only switches orphan tracking off for this process (one warning, one
+  # +session_warmer.registry_unavailable.bidi2pdf+ notification) - rendering never depends on it.
+  # The file is created 0600 and every change happens under an exclusive lock, so processes sharing
+  # the directory (Puma workers, a job worker, a spec run) can record at the same time.
+  class SessionRegistry
+    @path: untyped
+
+    @warned: untyped
+
+    FILE_PREFIX: "bidi2pdf-sessions-"
+
+    # Seconds a lease stays fresh without a renewal.
+    DEFAULT_LEASE_TTL: 60
+
+    attr_reader path: untyped
+
+    def self.owner: () -> ::String
+
+    def initialize: (untyped session_url, ?dir: untyped?) -> void
+
+    # Records a session the caller opened and keeps its lease fresh while this process lives.
+    def hold: (untyped session_id) -> (false | untyped)
+
+    # Stops renewing the lease but keeps the entry - for a session this process could not close, so
+    # a sweeper takes it once the lease ran out.
+    def release: (untyped session_id) -> (untyped | nil)
+
+    # Writes an entry, leased from +created_at+ on but not renewed (see #hold).
+    def record: (untyped session_id, ?created_at: untyped) -> (false | untyped)
+
+    # Forgets a session the caller closed itself (or found gone).
+    def forget: (untyped session_id) -> (false | untyped)
+
+    # Renews the leases of +session_ids+ that are still recorded.
+    def renew: (untyped session_ids, ?at: untyped) -> untyped
+
+    # Every recorded session: { id => opened at (epoch seconds) }.
+    def recorded: () -> untyped
+
+    # The recorded session ids whose lease was renewed within +ttl+ seconds before +now+ - sessions
+    # of a live process.
+    def leased: (?now: untyped, ?ttl: untyped) -> untyped
+
+    # The recorded session ids opened at or before +cutoff+ (epoch seconds).
+    def recorded_before: (untyped cutoff) -> untyped
+
+    private
+
+    def read: () -> untyped
+
+    def update: () { (untyped) -> untyped } -> untyped
+
+    # A corrupt or foreign file counts as empty rather than as an error; an entry of the first
+    # format (just the creation time) has no lease.
+    def parse: (untyped text) -> untyped
+
+    def normalize: (untyped entry) -> ({ "created_at" => untyped } | untyped)
+
+    def unavailable!: (untyped error) -> (nil | untyped)
+  end
+end

data/sig/bidi2pdf/session_sweeper.rbs

@@ -0,0 +1,37 @@
+module Bidi2pdf
+  # Closes sessions a SessionWarmer recorded (SessionRegistry) on a shared chromedriver that are
+  # older than a cutoff - left behind by a process that died without a clean shutdown, and holding a
+  # whole Chrome each until someone deletes them. Run once when a warmer starts.
+  #
+  # Only recorded sessions are ever touched - another tool's sessions on the same chromedriver never
+  # are, and neither is one whose lease a live process keeps renewing (SessionRegistry#hold). A
+  # recorded session that is already gone ("invalid session id" / 404) is just forgotten.
+  # Fail-open: any error is logged and ends the sweep; it never raises.
+  class SessionSweeper
+    @session_url: untyped
+
+    @registry: untyped
+
+    @http: untyped
+
+    # @param session_url [String] the chromedriver's new-session URL (".../session").
+    # @param registry [SessionRegistry]
+    # @param http [#call, nil] (method, url) -> status code; injectable for tests.
+    def initialize: (untyped session_url, untyped registry, ?http: untyped?) -> void
+
+    # Closes recorded sessions opened more than +older_than+ seconds before +now+.
+    #
+    # @return [Integer] how many sessions were actually closed.
+    def sweep: (older_than: untyped, ?now: untyped) -> untyped
+
+    private
+
+    # True when this call closed the session; a session already gone is forgotten but not counted.
+    def closed_now?: (untyped id) -> (false | untyped)
+
+    def report: (untyped closed) -> (nil | untyped)
+
+    # chromedriver answers a DELETE of a session it no longer has with 404 "invalid session id".
+    def net_http: (untyped method, untyped url) -> untyped
+  end
+end