bidi2pdf 0.1.16 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3533d126bc13406c70b6931112c07952aac0c19b718f3100258fb2182da8fcea
-  data.tar.gz: a761495802d5507fba3469405a571555547ed58891b216575f947e2b6a0c63be
+  metadata.gz: fa0fc469533226ce79d16bb401f4c47093dda42d4a68af67453fab79e086ad65
+  data.tar.gz: 9e4a1176ad42c03ced1544dcb9022a3dfe7d2663b0d8960f41bea863d3b0e788
 SHA512:
-  metadata.gz: cb29c3bf90a6a6dbd6fcf488980c51b9f666206ea18748d0c670e6fc2a64c453ca0f20043dce113094e74eb34d4b45f6be8b7d7a433522a59ac6ebab2d6ba8bb
-  data.tar.gz: bb9c384545c42d45630576b523c3c82025b1df2a2fc8975b8959276566173ad684b9423e7f30fc46b7834c61328ef68f9ddb1ee73d83b08e0ec8ea10b93f117f
+  metadata.gz: ddd7621c394b454a1df5b6071f474b1bd8699a4de4086e47c7185b01df66476ccad28d7e843b17e79aebf198489053bc237c345a3f638fb4e25e907aa4dc04f1
+  data.tar.gz: 134e15de59f8d5d7044be15308b1490988bc7eddd0134a9de05feed3accf3d56c52818125da49d36ad91263f6d16d8e58dc6549c85f5897316e9dfab7e60fb73

data/CHANGELOG.md

@@ -8,10 +8,52 @@ 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.16..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
+- Let Chromium start on a read-only root
+- Do not raise when our own close ends a write
+
+### 📝 Docs
+- Describe latest as the newest Chromium build
+
+### 🔄 Changed
+- Merge pull request #143 from dieter-medium/feat/chromedriver-sha-tags
+- Merge pull request #140 from dieter-medium/fix/chromium-read-only-root
+- Merge pull request #139 from dieter-medium/fix/websocket-close-during-write
+- Merge pull request #138 from dieter-medium/feat/session-warmer-orphan-sweep
+- Merge pull request #132 from dieter-medium/dependabot/bundler/main/rubyzip-3.6.0
+
+### 🔧 Build
+- Update rubyzip requirement from ~> 2.4 to >= 2.4, < 4.0
+
+### 🚀 Added
+- Tag every chromedriver image build by commit
+- Close leftover warm sessions on start
+
 ## [0.1.16] - 2026-09-22
 
 ### 🐛 Fixed
@@ -472,7 +514,9 @@ 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.16..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)
 - [0.1.14](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.13..v0.1.14)

data/README.md

@@ -435,11 +435,30 @@ docker run -it --rm \
 
 ✅ Tip: Mount your local directory (e.g. ./output) to /reports in the container to easily access the generated PDFs.
 
+✅ All images run with a read-only root filesystem (`--read-only`) as long as `/tmp` is writable,
+e.g. `--tmpfs /tmp`: they point Chromium's `XDG_CONFIG_HOME`/`XDG_CACHE_HOME` there, without
+which Chromium's crash handler fails to start and every launch aborts with
+`chrome_crashpad_handler: --database is required`.
+
 ✅ Both published images also install [`pdf-reader`](https://github.com/yob/pdf-reader) - not a
 runtime dependency of the gem itself (see [Agent and Automation Usage](#agent-and-automation-usage)) -
 so `pages` and the `page_count`/`pdf_text_present`/`pdf_not_blank` recipe assertions work out of
 the box in either image, no extra install step needed.
 
+### ChromeDriver image tags
+
+[`dieters877565/chromedriver`](https://hub.docker.com/r/dieters877565/chromedriver) is built for
+`linux/amd64` and `linux/arm64` with these tags:
+
+| Tag | Moves? | Use |
+|---|---|---|
+| `0.1.17` (a release) | no | a fixed Chromium, pinned together with the gem version |
+| `sha-<short commit>` | only if that commit is built again by hand | a fix on `main` not released yet |
+| `latest`, `main` | yes, every push to `main` | the newest build and its Chromium security fixes |
+
+Chromium comes from Debian's packages at build time, so every build can carry a different
+Chromium - for a byte-exact pin use the digest (`docker buildx imagetools inspect <image:tag>`).
+
 ### Docker Compose
 
 ```bash
@@ -551,6 +570,29 @@ Bidi2pdf::SessionWarmer.shutdown
 | `headless`           | `true`                | Run Chrome headless.                                                                                      |
 | `chrome_args`        | `DEFAULT_CHROME_ARGS` | Chrome launch arguments.                                                                                  |
 | `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
+
+A remote chromedriver keeps a session - a whole Chrome - until someone deletes it. A warmer closes
+its own sessions when they idle past `max_idle_age` and when the process shuts down cleanly, but a
+process that is killed or crashes leaves its sessions open, and enough of them stop the container
+from starting any new Chrome. So in remote mode each warmer records the sessions it opens in a small
+registry file (`<registry_dir>/bidi2pdf-sessions-<hash of the URL>.json`, mode 0600), and on start
+closes recorded sessions older than `orphan_age`. The default, twice `max_idle_age`, is beyond the
+point where any live warmer would already have recycled its own spare, so a running process never
+loses one. Sessions nobody recorded (other tools on the same chromedriver) are never touched.
+chromedriver drops custom capabilities, so a session cannot carry a tag of its own - hence the file.
+
+Everything here is fail-open: if the registry directory is not writable, the warmer logs one
+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
@@ -558,6 +600,109 @@ Bidi2pdf::SessionWarmer.shutdown
 > 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/docker/Dockerfile

@@ -42,6 +42,13 @@ RUN gem install ./bidi2pdf-*.gem && \
     chown -R appuser:appuser /app
 
 # Switch to non-root user
+# Chromium's crash handler gets its database path from the XDG config dir. On a read-only root
+# (docker run --read-only) that dir cannot be created, the handler refuses to start
+# ("--database is required") and Chrome aborts on every launch. /tmp is the one place such a
+# container is expected to mount writable (--tmpfs /tmp).
+ENV XDG_CONFIG_HOME=/tmp/xdg-config \
+    XDG_CACHE_HOME=/tmp/xdg-cache
+
 USER appuser
 
 CMD ["/usr/bin/bash"]

data/docker/Dockerfile.chromedriver

@@ -53,6 +53,13 @@ WORKDIR /app
 RUN mkdir -p /tmp/.X11-unix && chmod 1777 /tmp/.X11-unix
 
 # Switch to non-root user
+# Chromium's crash handler gets its database path from the XDG config dir. On a read-only root
+# (docker run --read-only) that dir cannot be created, the handler refuses to start
+# ("--database is required") and Chrome aborts on every launch. /tmp is the one place such a
+# container is expected to mount writable (--tmpfs /tmp).
+ENV XDG_CONFIG_HOME=/tmp/xdg-config \
+    XDG_CACHE_HOME=/tmp/xdg-cache
+
 USER appuser
 
 # RUN gem install chromedriver-binary && ruby -e 'require "chromedriver/binary"; puts Chromedriver::Binary::ChromedriverDownloader.update'

data/docker/Dockerfile.slim

@@ -73,6 +73,13 @@ WORKDIR /app
 RUN chown -R appuser:appuser /app
 
 # Switch to non-root user
+# Chromium's crash handler gets its database path from the XDG config dir. On a read-only root
+# (docker run --read-only) that dir cannot be created, the handler refuses to start
+# ("--database is required") and Chrome aborts on every launch. /tmp is the one place such a
+# container is expected to mount writable (--tmpfs /tmp).
+ENV XDG_CONFIG_HOME=/tmp/xdg-config \
+    XDG_CACHE_HOME=/tmp/xdg-cache
+
 USER appuser
 
 CMD ["/usr/bin/bash"]

data/lib/bidi2pdf/bidi/buffered_web_socket_client.rb

@@ -92,8 +92,17 @@ module Bidi2pdf
         @listeners_mutex.synchronize { @listeners[event].dup }.each { |listener| listener.call(*) }
       end
 
+      # The reader closes the socket from its own thread when the peer hangs up, and #close does not
+      # wait for a write in flight - so a write can fail with "stream closed in another thread" (or
+      # EPIPE) because *we* closed it. By then the connection is over and :close has been emitted;
+      # there is nothing left to report. Seen in the handshake write of #connect, which had no
+      # rescue: a server that answered and hung up at once made #connect raise although the
+      # handshake went through. Any other write failure still raises (#send and #say_goodbye
+      # handle it).
       def write(bytes)
         @write_mutex.synchronize { @socket&.write bytes }
+      rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+        raise unless @closed
       end
 
       def say_goodbye

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,
@@ -74,16 +75,24 @@ module Bidi2pdf
       # @return [Array<String>] The Chrome arguments for the session.
       attr_reader :chrome_args
 
+      # @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
+
       # 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:, 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.
@@ -113,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}" }
@@ -227,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
@@ -349,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