bidi2pdf-rails 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 648dea2d18715e2ae14536179a0cb92d1fac0c5c0f8a3687485adfceea6560a9
-  data.tar.gz: 91b1e9a29ae297e85cee25ef211a44ad8413eba3cbb305c7badc6a8025da0a47
+  metadata.gz: 74c1f65510817caf8e3b01167055b489bbfd70c018818865e3063eccab4eba01
+  data.tar.gz: 01d9b3124d923686e935cf5a6ce92424496a229e091148f7d828c5927b5c9256
 SHA512:
-  metadata.gz: e740afe0f44f9e15e65daf2a3b44c83114774e121f07b18907120a0f95d2c1d4614e694aa2a49036cc5295810f56e463e5c759c351c99ddb8a184df8a7021867
-  data.tar.gz: 8530fb496fc3d986c1925e85981f6596c0f1a28b8ab963f422ee2f8c878d09d907ee03854800b24e0d5e2b600af4353c37d0b180596841472647761e68afb087
+  metadata.gz: 60f0e9270cef332f9086de1bedde5e9462bb2789900ea3dc4c7017ca873f591084619ff277ab88fa2688b9f28cf2d1706f651c5e19e13abd3cc4b5dc4403e0d3
+  data.tar.gz: 8dfb6bdf5650cb0d4c4e92786a880b896a4cdfd3ca4825b74a4943d4048530a854d02442c82cbec33c6f8336042c8e98e93258b6b2296bd253707da75cf080d8

data/CHANGELOG.md

@@ -8,10 +8,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-[unreleased]: https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.6..HEAD
+[unreleased]: https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.7..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [0.1.7] - 2026-09-30
+
+### 🐛 Fixed
+
+- Match only the stable example.com sentence by @dieter-medium
+  in [#27](https://github.com/dieter-medium/bidi2pdf-rails/pull/27)
+- Keep sweeper leases and retries consistent by @dieter-medium
+  in [#27](https://github.com/dieter-medium/bidi2pdf-rails/pull/27)
+- Keep the first original in the settings helpers by @dieter-medium
+  in [#27](https://github.com/dieter-medium/bidi2pdf-rails/pull/27)
+- Document and address blank PDFs from Chrome's network checks by @dieter-medium
+  in [#25](https://github.com/dieter-medium/bidi2pdf-rails/pull/25)
+
+### 📝 Docs
+
+- Name bidi2pdf's lease_ttl option by @dieter-medium
+  in [#27](https://github.com/dieter-medium/bidi2pdf-rails/pull/27)
+
+### 🚀 Added
+
+- Sweep leaked Chrome sessions on the remote browser by @dieter-medium
+  in [#27](https://github.com/dieter-medium/bidi2pdf-rails/pull/27)
+
+[0.1.7]: https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.6..v0.1.7
+
 ## [0.1.6] - 2026-09-21
 
 ### 🎨 Refactored
@@ -140,7 +165,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 🔄 Released
 
-- [unreleased](https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.4..HEAD)
+- [unreleased](https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.7..HEAD)
+- [0.1.7](https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.6..v0.1.7)
+- [0.1.6](https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.5..v0.1.6)
+- [0.1.5](https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.4..v0.1.5)
 - [0.1.4](https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.3..v0.1.4)
 - [0.1.3](https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.2..v0.1.3)
 - [0.1.2](https://github.com/dieter-medium/bidi2pdf-rails/compare/v0.1.1..v0.1.2)

data/README.md

@@ -216,6 +216,56 @@ Implementing these steps helps avoid interlock-induced deadlocks when generating
 
 ---
 
+## 🕳️ Blank PDFs: Chrome's Local Network Access Check
+
+**Symptom.** `render pdf:` of a Rails view returns a PDF with no styling and, with a JS-driven layout
+(Paged.js, Stimulus, ...), no content at all. Nothing raises. In the log every asset request ends in
+`state="error"`, the wait for the page runs into its timeout, and - the telltale part - **your app
+never logs a single `GET /assets/...` for that render**.
+
+**Cause.** A rendered view is handed to Chrome as a `data:` URL. Chrome treats that document as a
+*public* origin, while its stylesheets and scripts point back at your app - which in development, CI
+and most Docker setups is a *private* address (`localhost`, `host.docker.internal`, a Compose service
+name). Recent Chrome versions (confirmed with Chrome 153) block a public document from requesting
+private-network resources, before the request ever leaves the browser. That is why CORS settings
+make no difference here: there is no request for your app to answer.
+
+**Fix.** Opt out of that one check where your asset host is private:
+
+```ruby
+# config/initializers/bidi2pdf_rails.rb
+chrome_args = Bidi2pdf::Bidi::Session::DEFAULT_CHROME_ARGS.dup
+
+unless Rails.env.production?
+  chrome_args.map! do |arg|
+    arg.start_with?("--disable-features=") ? "#{arg},LocalNetworkAccessChecks" : arg
+  end
+end
+
+config.general_options.chrome_session_args = chrome_args
+```
+
+- **Merge, don't append.** `DEFAULT_CHROME_ARGS` already carries a `--disable-features=` list, and
+  Chrome only honors the *last* occurrence of that switch - a second one silently drops bidi2pdf's
+  own defaults.
+- `BlockInsecurePrivateNetworkRequests` alone does **not** help; `LocalNetworkAccessChecks` is the
+  feature that matters.
+- **Leave the check on in production** when your assets come from a public `https://` asset host -
+  nothing is blocked there, and it is a real browser protection.
+- Rendering a remote `url:` that is served from the same private host as its assets is not
+  affected - document and assets then share one address space.
+- With the session warmer enabled, restart the app after changing Chrome arguments - warm sessions
+  were started with the old ones.
+
+The second half of the same problem is the name itself: the asset host has to be one the *browser*
+can resolve back to your app (`pdf_settings.asset_host`, or your own `config.asset_host`), which for
+a remote or containerized Chrome is rarely the URL you typed into your own browser.
+
+> This repo's own dummy app never runs into the check because it starts Chrome with
+> `--disable-web-security` - fine for a test fixture, not something to copy into an application.
+
+---
+
 ## 🧪 Acceptance Examples
 
 This repo includes **real integration tests** that serve as usage documentation:
@@ -230,6 +280,7 @@ This repo includes **real integration tests** that serve as usage documentation:
 - [Rendering with a pre-warmed session pool (
   `Bidi2pdf::SessionWarmer`)](spec/acceptance/user_can_render_with_a_warm_session_spec.rb)
 - [Using the session warmer against a remote chromedriver](spec/acceptance/user_can_render_with_a_warm_session_using_remote_chromedriver_spec.rb)
+- [Closing Chrome sessions left behind on a remote chromedriver](spec/acceptance/user_can_have_leaked_chrome_sessions_swept_spec.rb)
 
 ---
 
@@ -245,7 +296,7 @@ bin/rails generate bidi2pdf_rails:initializer
 
 Or explore [Bidi2pdfRails::Config::CONFIG_OPTIONS](lib/bidi2pdf_rails/config.rb) in the source.
 
-Requires **bidi2pdf >= 0.1.15**. Settings that came with it:
+Requires **bidi2pdf >= 0.1.20**. Settings that came with it:
 
 | Setting                                | Default | Description                                                                                                                                                                         |
 |----------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -264,12 +315,70 @@ when the warmer is on.
 
 **Session warmer settings are boot-time immutable.** `Bidi2pdf::SessionWarmer` is configured once, on
 the first `ChromedriverManagerSingleton.initialize_manager` call. A later change to
-`session_warmer_settings`, `general_options.headless`/`chrome_session_args`, or
+`session_warmer_settings`, `sweeper_settings`, `general_options.headless`/`chrome_session_args`, or
 `render_remote_settings.browser_url` is logged as a warning and otherwise ignored until you call
 `ChromedriverManagerSingleton.shutdown` followed by `.initialize_manager` again to re-apply it.
 Outside a server process (specs, a console) both calls return early unless you pass `force: true`;
 `initialize_manager force: true` on its own also works - it stops whatever is running first.
 
+### 🧹 Leaked Chrome sessions (remote browser)
+
+A remote chromedriver keeps every session - a whole Chrome - until someone deletes it, and a worker
+that is killed or crashes leaves its sessions open until the container runs out of room for new
+ones. With a remote browser, every session a render opens is **leased** in a small registry file:
+the rendering process renews the lease while the session is open, so no sweeper in any process
+closes it - not another Puma worker's, not a job worker's. When a process dies, its leases run out
+and its sessions become leftovers.
+
+`sweeper_settings.enabled` puts a `Bidi2pdf::ChromeSweeper` in every process:
+
+- a render that fails for lack of resources - chromedriver refusing a session, Chrome dying or not
+  answering - is **retried once after a last-resort sweep**, which closes every session nobody holds
+  that is older than `min_age` (`retry_on_failure`); a page error (navigation, script) is not retried;
+- with an `interval`, it sweeps in the background by its rules: sessions older than `orphan_age`,
+  unresponsive ones, and the oldest ones over `max_sessions`;
+- the warmer, when enabled, leases its sessions and sweeps before retrying a refused session.
+
+```ruby
+config.render_remote_settings.browser_url = "http://remote-chrome:3000/session"
+config.sweeper_settings.enabled = true
+config.sweeper_settings.scope = "all"          # the chromedriver belongs to this app
+config.sweeper_settings.max_sessions = "auto"  # floor(pids_limit * 0.8 / 110)
+config.sweeper_settings.pids_limit = 1024      # the chromedriver container's pids limit
+config.sweeper_settings.interval = 60
+config.sweeper_settings.registry_dir = "/shared/bidi2pdf" # web and job containers must share it
+```
+
+| Setting                                 | Default      | Description                                                                                                                                  |
+|-----------------------------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| `sweeper_settings.enabled`              | `false`      | Run a sweeper against `render_remote_settings.browser_url`, and retry a render that failed for lack of resources.                           |
+| `sweeper_settings.scope`                | `"recorded"` | `"recorded"`: only sessions bidi2pdf recorded. `"all"`: every session on the chromedriver - only for a chromedriver your application owns.  |
+| `sweeper_settings.orphan_age`           | `600`        | Close sessions nobody holds that are older than this many seconds; `nil` turns the rule off.                                                |
+| `sweeper_settings.min_age`              | `60`         | Never close a session younger than this.                                                                                                     |
+| `sweeper_settings.unresponsive_checks`  | `2`          | Close a session nobody holds after this many failed checks in a row; `nil` turns the rule off.                                               |
+| `sweeper_settings.max_sessions`         | `nil`        | Close the oldest sessions nobody holds while more exist; `"auto"` derives it from `pids_limit`.                                              |
+| `sweeper_settings.pids_limit`           | `nil`        | The chromedriver container's pids limit, for `max_sessions = "auto"`.                                                                        |
+| `sweeper_settings.interval`             | `nil`        | Seconds between background sweeps in every process; `nil` sweeps only when a render fails or on demand.                                      |
+| `sweeper_settings.registry_dir`         | `Dir.tmpdir` | Where the registry lives. Processes only see each other's leases when they share it.                                                          |
+| `sweeper_settings.retry_on_failure`     | `true`       | Retry a render once after a last-resort sweep; with the warmer, also a session it was refused. Off: no retry anywhere.                        |
+
+On demand, e.g. when the application suspects a leak, or from a shell during an incident:
+
+```ruby
+Bidi2pdfRails.chrome_sessions                                  # ids, ages, live or not - no page content
+Bidi2pdfRails.sweep_sessions!                                  # one sweep by the configured rules
+Bidi2pdfRails.sweep_sessions!(pressure: true, dry_run: true)   # what a last-resort sweep would close
+```
+
+```bash
+bin/rails bidi2pdf_rails:sessions
+bin/rails bidi2pdf_rails:sweep                 # PRESSURE=1, DRY_RUN=1, CHECK_INTERVAL=10
+```
+
+Both work whether or not `sweeper_settings.enabled` is set. Sessions other tools opened carry no
+lease: with `scope = "all"`, only `min_age` protects them. See bidi2pdf's README ("Leaked Chrome
+sessions") for how sessions are aged and checked.
+
 **Rails 8.1.3.1 and `json` 3.** `json` 3 accepts options as keywords only, while Rails 8.1.3.1 still
 passes `JSON.parse` a positional options hash. With both in one bundle, Active Storage attachments
 and signed cookies fail with `ArgumentError: wrong number of arguments (given 2, expected 1)` - this

data/lib/bidi2pdf_rails/chrome_sweeping.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Bidi2pdfRails
+  # Connects bidi2pdf's leased session registry and Bidi2pdf::ChromeSweeper to the Rails settings
+  # (sweeper_settings) - remote browser only, there is no shared chromedriver otherwise.
+  #
+  # Every remote session a render opens is leased in the registry (#registry), sweeper or not: a
+  # sweeper in another process - another Puma worker, a job worker - then knows it is in use. With
+  # sweeper_settings.enabled, each process gets one sweeper (#sweeper): it sweeps every
+  # sweeper_settings.interval seconds when set, and #with_retry makes it the last resort for a
+  # render that failed for lack of resources.
+  module ChromeSweeping
+    # sweeper_settings keys passed to Bidi2pdf::ChromeSweeper as they are.
+    # Bidi2pdf::ChromeSweeper's lease_ttl option is deliberately not passed: every lease carries the
+    # TTL its owner's heartbeat promises, and that option only covers entries written by bidi2pdf
+    # 0.1.18.
+    PASSED_THROUGH = %i[orphan_age min_age unresponsive_checks pids_limit registry_dir].freeze
+
+    # With the warmer, a refused session was already swept for and retried by the warmer itself -
+    # retrying the whole render on top would stack a second pair of attempts.
+    RETRYABLE_WITH_WARMER = ->(error) { !error.is_a?(Bidi2pdf::SessionNotStartedError) && Bidi2pdf::ChromeSweeper::RETRYABLE.call(error) }
+
+    class << self
+      def enabled?
+        Bidi2pdfRails.use_remote_browser? && settings.enabled_value
+      end
+
+      # The registry remote sessions are leased in; nil without a remote browser.
+      def registry
+        return unless Bidi2pdfRails.use_remote_browser?
+
+        Bidi2pdf::SessionRegistry.new(browser_url, dir: settings.registry_dir_value)
+      end
+
+      # Bidi2pdf::ChromeSweeper settings from sweeper_settings (without the background interval).
+      def options
+        PASSED_THROUGH.to_h { |key| [key, settings.public_send("#{key}_value")] }
+                      .merge(scope: settings.scope_value.to_s.to_sym, max_sessions: max_sessions)
+      end
+
+      # The sweeper settings for Bidi2pdf::SessionWarmer - nil unless it should retry a refused
+      # session, which is all its own sweeper does (background sweeps belong to #sweeper).
+      def warmer_sweeper_options
+        options if enabled? && settings.retry_on_failure_value
+      end
+
+      # This process's sweeper, nil when sweeping is off. Built on first use, never before - that is
+      # a render or a sweep in a worker, not the Puma master that forks it, whose background thread
+      # would not survive the fork. A forked process builds its own.
+      def sweeper
+        return unless enabled?
+
+        @mutex.synchronize do
+          reset_after_fork
+          @sweeper ||= build_sweeper
+        end
+      end
+
+      # Runs a render; when it fails for lack of resources, sweeps under pressure and runs it once
+      # more (Bidi2pdf::ChromeSweeper#with_retry). Without sweeping, or with retry_on_failure off,
+      # just runs it.
+      def with_retry(&)
+        current = settings.retry_on_failure_value ? sweeper : nil
+        return yield unless current
+
+        retry_on = ChromedriverManagerSingleton.session_warmer_active? ? RETRYABLE_WITH_WARMER : Bidi2pdf::ChromeSweeper::RETRYABLE
+        current.with_retry(retry_on: retry_on, &)
+      end
+
+      # One sweep now, with the configured rules - whether or not sweeper_settings.enabled.
+      #
+      # @param pressure [Boolean] the last resort: close everything nobody holds past min_age.
+      # @param dry_run [Boolean] report what would be closed, close nothing.
+      # @param check_interval [Numeric, nil] check twice this many seconds apart first, so the
+      #   unresponsive rule applies too.
+      # @return [Bidi2pdf::ChromeSweeper::Result]
+      def sweep!(pressure: false, dry_run: false, check_interval: nil)
+        one_shot(dry_run: dry_run).sweep!(reason: :manual, pressure: pressure, check_interval: check_interval)
+      end
+
+      # Every session on the remote chromedriver in the configured scope; live ones are marked.
+      #
+      # @return [Array<Bidi2pdf::ChromeSweeper::Inspector::SessionInfo>]
+      def sessions
+        one_shot.sessions
+      end
+
+      # Stops the background sweeps of this process.
+      def stop
+        current = @mutex.synchronize { @sweeper.tap { @sweeper = nil } }
+        current&.stop
+      end
+
+      private
+
+      def settings
+        Bidi2pdfRails.config.sweeper_settings
+      end
+
+      def browser_url
+        Bidi2pdfRails.config.render_remote_settings.browser_url_value
+      end
+
+      def max_sessions
+        value = settings.max_sessions_value
+        value.to_s == "auto" ? :auto : value&.to_i
+      end
+
+      def build_sweeper
+        Bidi2pdf::ChromeSweeper.new(browser_url, interval: settings.interval_value, **options).tap do |built|
+          built.start if built.interval
+        end
+      end
+
+      def one_shot(dry_run: false)
+        raise ArgumentError, "sweeping needs render_remote_settings.browser_url" unless Bidi2pdfRails.use_remote_browser?
+
+        Bidi2pdf::ChromeSweeper.new(browser_url, dry_run: dry_run, **options)
+      end
+
+      # A forked child starts without the parent's sweeper - its thread did not survive the fork.
+      def reset_after_fork
+        return if @pid == Process.pid
+
+        @pid = Process.pid
+        @sweeper = nil
+      end
+    end
+
+    @mutex = Mutex.new
+  end
+end

data/lib/bidi2pdf_rails/chromedriver_manager_singleton.rb

@@ -66,10 +66,12 @@ module Bidi2pdfRails
       def session
         Thread.current.bidi2pdf_rails_session ||= begin
                                                     if Bidi2pdfRails.use_remote_browser?
+                                                      # Leased while open, so no other process's sweeper takes it.
                                                       session = Bidi2pdf::Bidi::Session.new(
                                                         session_url: Bidi2pdfRails.config.render_remote_settings.browser_url_value,
                                                         headless: Bidi2pdfRails.config.general_options.headless_value,
-                                                        chrome_args: Bidi2pdfRails.config.general_options.chrome_session_args_value
+                                                        chrome_args: Bidi2pdfRails.config.general_options.chrome_session_args_value,
+                                                        registry: ChromeSweeping.registry
                                                       )
                                                     else
                                                       session = @manager.session
@@ -115,6 +117,8 @@ module Bidi2pdfRails
       # session_warmer_enabled? says right now - a setting flipped in between must not leave the
       # thing that is really running alive. Callers hold @mutex.
       def teardown
+        ChromeSweeping.stop
+
         case @active_mode
         when :warmer
           Bidi2pdfRails.logger.info "Shutting down Bidi2pdf::SessionWarmer"
@@ -154,7 +158,14 @@ module Bidi2pdfRails
           c.max_idle_age = @session_warmer_settings_snapshot[:max_idle_age]
           c.headless = @session_warmer_settings_snapshot[:headless]
           c.chrome_args = @session_warmer_settings_snapshot[:chrome_args]
-          c.remote_browser_url = @session_warmer_settings_snapshot[:remote_browser_url] if Bidi2pdfRails.use_remote_browser?
+          next unless Bidi2pdfRails.use_remote_browser?
+
+          c.remote_browser_url = @session_warmer_settings_snapshot[:remote_browser_url]
+          c.registry_dir = @session_warmer_settings_snapshot[:registry_dir]
+          # The warmer leases its sessions in remote mode on its own. Its sweeper exists only to sweep
+          # under pressure and retry when a new session is refused - so only with
+          # sweeper_settings.retry_on_failure; background sweeps belong to ChromeSweeping#sweeper.
+          c.sweeper = @session_warmer_settings_snapshot[:sweeper]
         end
       end
 
@@ -171,7 +182,9 @@ module Bidi2pdfRails
           max_idle_age: Bidi2pdfRails.config.session_warmer_settings.max_idle_age_value,
           headless: Bidi2pdfRails.config.general_options.headless_value,
           chrome_args: Bidi2pdfRails.config.general_options.chrome_session_args_value,
-          remote_browser_url: Bidi2pdfRails.use_remote_browser? ? Bidi2pdfRails.config.render_remote_settings.browser_url_value : nil
+          remote_browser_url: Bidi2pdfRails.use_remote_browser? ? Bidi2pdfRails.config.render_remote_settings.browser_url_value : nil,
+          registry_dir: Bidi2pdfRails.config.sweeper_settings.registry_dir_value,
+          sweeper: ChromeSweeping.warmer_sweeper_options
         }
       end
 
@@ -181,7 +194,7 @@ module Bidi2pdfRails
 
         Bidi2pdfRails.logger.warn(
           "Bidi2pdf::SessionWarmer is already configured; session_warmer_settings/general_options/" \
-            "render_remote_settings changes are boot-time immutable and were ignored. Call " \
+            "render_remote_settings/sweeper_settings changes are boot-time immutable and were ignored. Call " \
             "ChromedriverManagerSingleton.shutdown then .initialize_manager to apply them."
         )
       end

data/lib/bidi2pdf_rails/config.rb

@@ -66,6 +66,54 @@ module Bidi2pdfRails
         ]
       },
 
+      sweeper_settings: {
+        name: "Chrome Sweeper Settings (remote browser only)",
+        ask: "Close Chrome sessions left behind on the remote browser, and retry a render that failed for lack of resources? (y/n)",
+        options: [
+          {
+            name: :enabled,
+            desc: "Run a Bidi2pdf::ChromeSweeper against render_remote_settings.browser_url: sessions of dead " \
+              "processes are closed, and a render that failed for lack of resources is retried once after a " \
+              "last-resort sweep. Sessions a running process holds (every worker's renders and warm spares) " \
+              "are never touched",
+            default: false,
+            ask: true,
+            color: :green
+          },
+          {
+            name: :scope,
+            desc: "recorded: only sessions bidi2pdf recorded in the registry; all: every session on the " \
+              "chromedriver - only for a chromedriver your application owns",
+            default: "recorded",
+            limited_to: %w[recorded all],
+            ask: true,
+            color: :yellow
+          },
+          { name: :orphan_age, desc: "Close sessions nobody holds that are older than this many seconds; nil turns the rule off", default: 600, ask: true, color: :yellow },
+          { name: :min_age, desc: "Never close a session younger than this many seconds", default: 60, ask: true, color: :yellow },
+          { name: :unresponsive_checks, desc: "Close a session nobody holds after this many failed checks in a row; nil turns the rule off", default: 2, ask: false, color: :yellow },
+          {
+            name: :max_sessions,
+            desc: "Close the oldest sessions nobody holds while more than this many exist; \"auto\" derives it " \
+              "from pids_limit, nil turns the limit off",
+            default: nil,
+            ask: true,
+            color: :yellow
+          },
+          { name: :pids_limit, desc: "The chromedriver container's pids limit, for max_sessions = \"auto\"", default: nil, ask: true, color: :yellow },
+          { name: :interval, desc: "Seconds between background sweeps in every process; nil sweeps only when a render fails or on demand", default: nil, ask: true, color: :yellow },
+          {
+            name: :registry_dir,
+            desc: "Directory of the session registry; every process that renders against the same chromedriver " \
+              "(web and job containers) must share it, nil means Dir.tmpdir",
+            default: nil,
+            ask: false,
+            color: :yellow
+          },
+          { name: :retry_on_failure, desc: "Retry a render once after a last-resort sweep when it failed for lack of resources", default: true, ask: true, color: :green }
+        ]
+      },
+
       proxy_settings: {
         name: "Proxy Settings",
         ask: "Use a proxy server? (y/n)",

data/lib/bidi2pdf_rails/railtie.rb

@@ -39,6 +39,10 @@ module Bidi2pdfRails
   #
   #
   class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load File.expand_path("tasks/sessions.rake", __dir__)
+    end
+
     initializer "bidi2pdf_rails.add_mime_type" do
       Mime::Type.register "application/pdf", :pdf unless Mime::Type.lookup_by_extension(:pdf)
     end

data/lib/bidi2pdf_rails/services/pdf_browser_session.rb

@@ -3,7 +3,16 @@
 module Bidi2pdfRails
   module Services
     module PdfBrowserSession
+      # With sweeper_settings.enabled, a render that fails for lack of resources (chromedriver
+      # refused the session, Chrome died or stopped answering) is run once more after a last-resort
+      # sweep - see ChromeSweeping.with_retry. Each run opens and cleans up its own tab and session.
       def run_browser_session
+        ChromeSweeping.with_retry { run_browser_session_once }
+      end
+
+      private
+
+      def run_browser_session_once
         future = Concurrent::Promises.future do
           Rails.application.executor.wrap do
             if ChromedriverManagerSingleton.session_warmer_active?
@@ -17,28 +26,27 @@ module Bidi2pdfRails
         future.value!
       end
 
-      private
-
       # Bidi2pdf::SessionWarmer#with_tab already checks out, closes the tab/window/user_context, and
       # retires the underlying Chrome session on its own - nothing left for this method to clean up.
       def run_with_session_warmer
         Bidi2pdf::SessionWarmer.with_tab { |tab| print_and_notify(tab) }
       end
 
+      # The session is covered by the ensure too: when its browser cannot be created, it is still
+      # closed - a half-started session left in the pooled thread's slot would be reused broken, by
+      # the retry among others.
       def run_with_chromedriver_manager_singleton
         browser = ChromedriverManagerSingleton.session.browser
         context = browser.create_user_context
         window = context.create_browser_window
         tab = window.create_browser_tab
 
-        begin
-          print_and_notify(tab)
-        ensure
-          tab&.close
-          window&.close
-          context&.close
-          ChromedriverManagerSingleton.session_close
-        end
+        print_and_notify(tab)
+      ensure
+        tab&.close
+        window&.close
+        context&.close
+        ChromedriverManagerSingleton.session_close
       end
 
       def print_and_notify(tab)

data/lib/bidi2pdf_rails/tasks/sessions.rake

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+namespace :bidi2pdf_rails do
+  desc "List the Chrome sessions the remote browser holds (id, age, live or not - no page content)"
+  task sessions: :environment do
+    sessions = Bidi2pdfRails.chrome_sessions
+    puts "no sessions" if sessions.empty?
+    sessions.each do |info|
+      state = if info.live then "live"
+              elsif info.responsive then "responsive"
+              else "unresponsive"
+              end
+      puts format("%-34<id>s %8<age>s  %<state>s", id: info.id, age: info.age ? "#{info.age.round}s" : "?", state: state)
+    end
+  end
+
+  desc "Close leaked Chrome sessions on the remote browser (PRESSURE=1: last resort, DRY_RUN=1: report only, " \
+       "CHECK_INTERVAL=10: check twice first)"
+  task sweep: :environment do
+    check_interval = ENV["CHECK_INTERVAL"].presence&.to_f
+    result = Bidi2pdfRails.sweep_sessions!(pressure: ENV["PRESSURE"] == "1", dry_run: ENV["DRY_RUN"] == "1",
+                                           check_interval: check_interval)
+    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.size} of #{result.sessions} session(s)"
+    puts "limit #{result.limit} still exceeded" if result.limit_exceeded
+    result.errors.each { |error| warn "error: #{error}" }
+    exit(1) if result.errors.any? || result.limit_exceeded
+  end
+end

data/lib/bidi2pdf_rails/test_helpers/settings_helper.rb

@@ -8,7 +8,7 @@ module Bidi2pdfRails
       # @param [Symbol] key the setting key to override
       # @param [Object] value the new value to set
       def with_render_setting(key, value)
-        overridden_render_settings[key] = Bidi2pdfRails.config.render_remote_settings.public_send(key)
+        overridden_render_settings[key] = Bidi2pdfRails.config.render_remote_settings.public_send(key) unless overridden_render_settings.key?(key)
         Bidi2pdfRails.config.render_remote_settings.public_send("#{key}=", value)
       end
 
@@ -17,7 +17,7 @@ module Bidi2pdfRails
       # @param [Symbol] key the setting key to override
       # @param [Object] value the new value to set
       def with_pdf_settings(key, value)
-        overridden_pdf_settings[key] = Bidi2pdfRails.config.pdf_settings.public_send(key)
+        overridden_pdf_settings[key] = Bidi2pdfRails.config.pdf_settings.public_send(key) unless overridden_pdf_settings.key?(key)
         Bidi2pdfRails.config.pdf_settings.public_send("#{key}=", value)
       end
 
@@ -26,7 +26,7 @@ module Bidi2pdfRails
       # @param [Symbol] key the setting key to override
       # @param [Object] value the new value to set
       def with_lifecycle_settings(key, value)
-        overridden_lifecycle_settings[key] = Bidi2pdfRails.config.lifecycle_settings.public_send(key)
+        overridden_lifecycle_settings[key] = Bidi2pdfRails.config.lifecycle_settings.public_send(key) unless overridden_lifecycle_settings.key?(key)
         Bidi2pdfRails.config.lifecycle_settings.public_send("#{key}=", value)
       end
 
@@ -35,7 +35,7 @@ module Bidi2pdfRails
       # @param [Symbol] key the setting key to override
       # @param [Object] value the new value to set
       def with_chromedriver_settings(key, value)
-        overridden_chromedriver_settings[key] = Bidi2pdfRails.config.chromedriver_settings.public_send(key)
+        overridden_chromedriver_settings[key] = Bidi2pdfRails.config.chromedriver_settings.public_send(key) unless overridden_chromedriver_settings.key?(key)
         Bidi2pdfRails.config.chromedriver_settings.public_send("#{key}=", value)
       end
 
@@ -44,7 +44,7 @@ module Bidi2pdfRails
       # @param [Symbol] key the setting key to override
       # @param [Object] value the new value to set
       def with_proxy_settings(key, value)
-        overridden_proxy_settings[key] = Bidi2pdfRails.config.proxy_settings.public_send(key)
+        overridden_proxy_settings[key] = Bidi2pdfRails.config.proxy_settings.public_send(key) unless overridden_proxy_settings.key?(key)
         Bidi2pdfRails.config.proxy_settings.public_send("#{key}=", value)
       end
 
@@ -89,6 +89,29 @@ module Bidi2pdfRails
         @__overridden_proxy_settings ||= {}
       end
 
+      # Temporarily overrides a sweeper setting with a new value; the first override of a key keeps
+      # the original for #reset_sweeper_settings.
+      # @param [Symbol] key the setting key to override
+      # @param [Object] value the new value to set
+      def with_sweeper_settings(key, value)
+        overridden_sweeper_settings[key] = Bidi2pdfRails.config.sweeper_settings.public_send(key) unless overridden_sweeper_settings.key?(key)
+        Bidi2pdfRails.config.sweeper_settings.public_send("#{key}=", value)
+      end
+
+      # @return [Hash] the overridden sweeper settings with their original values
+      def overridden_sweeper_settings
+        @__overridden_sweeper_settings ||= {}
+      end
+
+      # Resets every overridden sweeper setting to its original value.
+      def reset_sweeper_settings
+        overridden_sweeper_settings.each do |key, original_value|
+          Bidi2pdfRails.config.sweeper_settings.public_send("#{key}=", original_value)
+        end
+
+        @__overridden_sweeper_settings = {}
+      end
+
       # Retrieves the hash of overridden session warmer settings.
       # @return [Hash] a hash of overridden session warmer settings
       def overridden_session_warmer_settings
@@ -168,6 +191,7 @@ module Bidi2pdfRails
         reset_chromedriver_settings if respond_to?(:reset_chromedriver_settings)
         reset_proxy_settings if respond_to?(:reset_proxy_settings)
         reset_session_warmer_settings if respond_to?(:reset_session_warmer_settings)
+        reset_sweeper_settings if respond_to?(:reset_sweeper_settings)
       end
     end
   end

data/lib/bidi2pdf_rails/version.rb

@@ -1,3 +1,3 @@
 module Bidi2pdfRails
-  VERSION = "0.1.6"
+  VERSION = "0.1.7"
 end