bidi2pdf 0.1.25 → 0.1.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f000e35aacf91ebfd7691be7ce8e989ab8d384dd96075e9ef705692f5f68bc3b
-  data.tar.gz: ef370866fad4eacca3d74a23f4ea7b83caf157f498cae29c26fcdb19757ada9e
+  metadata.gz: f9f6c1ea872b0d4250ca35a59990f11f3d0c3599e55b3560e6c6ba925b045dd7
+  data.tar.gz: 8c4ae64d0944396a7eed9dc09288747a17491a1235d9f64f3bdb2ea5eb222bcb
 SHA512:
-  metadata.gz: 4a6025a10a1ebab333371dbf80e8d733e57052a08da043574e9b661551f02259c163afc7b0fe79580faafe5e4a1ad8bb03ab1655074eea77d77f02fd80b6c10f
-  data.tar.gz: efa593482aba4d15785007ac2612afafbe61f04c8dc6555b6052e7cb04d775661b2d0b2d286fe64a401fe22cc7050697b734aae1a2c97f0b4c88d28856134a6f
+  metadata.gz: dd5616ed110fe4018b78ce18f8403302e1bba37a41fc470a2ed03ce76fc879042a73528ecd81afd21d2fe824c08d5f0034bcbed1bd517ff00dc05b970dfe4eec
+  data.tar.gz: b50f99a5143f851b435325763d3b4c1a3817e459170c17ea652c6dbb10ce43ef5ce7a4eec34d01d4e3f4df8c58be51b358167dfe9a84615fbddb9bc948021a3e

data/CHANGELOG.md

@@ -8,10 +8,24 @@ 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.25..HEAD
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.26..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [0.1.26] - 2026-10-29
+
+### 🐛 Fixed
+- Check screenshot widths on a page that fits
+- Check screenshot widths on pages without Paged.js
+- Read the session start limit once per process
+- Keep session gate permits on every path
+
+### 🔄 Changed
+- Merge pull request #184 from dieter-medium/feat/session-start-gate
+
+### 🚀 Added
+- Limit concurrent Chrome session setups
+
 ## [0.1.25] - 2026-10-27
 
 ### 🐛 Fixed
@@ -633,7 +647,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 🔄 Released
 
-- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.25..HEAD)
+- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.26..HEAD)
+- [0.1.26](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.25..v0.1.26)
 - [0.1.25](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.24..v0.1.25)
 - [0.1.24](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.23..v0.1.24)
 - [0.1.23](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.22..v0.1.23)

data/README.md

@@ -725,6 +725,8 @@ Bidi2pdf.configure do |config|
   config.enable_default_logging_subscriber = true
   config.log_truncate_limit = 200 # bytes - see below
   config.chromedriver_log_level = "WARNING" # see below
+  config.session_start_concurrency = 2 # Chrome session setups at once in this process - see "Session start limit"
+  config.session_start_timeout = nil # seconds a setup waits for its turn; nil: default_timeout
 end
 ```
 
@@ -734,16 +736,115 @@ end
 | `enable_default_logging_subscriber` | `true`  | Subscribes a default logger to the gem's internal instrumentation events.                                                                                                                                                        |
 | `log_truncate_limit`                | `200`   | Max bytes kept when logging a value that can be large (e.g. a `data:` URL) - truncated at a byte, not character, boundary.                                                                                                       |
 | `chromedriver_log_level`            | `nil`   | ChromeDriver's own `--log-level` (`"ALL"`/`"INFO"`/`"WARNING"`/`"SEVERE"`). Unset mirrors `Bidi2pdf.logger.level`; set explicitly to quiet ChromeDriver's own (often very verbose) output independently of your app's log level. |
+| `session_start_concurrency`         | `2`     | How many Chrome session setups (session request to first open tab) may run at once in this process; `nil` turns the limit off. See "Session start limit".                                                                    |
+| `session_start_timeout`             | `nil`   | Seconds a setup waits for its turn before it fails with `SessionStartTimeoutError` (code `BROWSER_LAUNCH_FAILED`, retryable); `nil` uses `default_timeout`.                                                                 |
+| `session_gate`                      | `nil`   | An object of your own answering `with_permit { ... }` - e.g. a lock shared by several processes - instead of the per-process semaphore. See "Session start limit".                                                         |
 
 `Bidi2pdf.logger`, `Bidi2pdf.network_events_logger`, `Bidi2pdf.browser_console_logger`, and
 `Bidi2pdf.notification_service` are also configurable in the same block, for more advanced
 logging/instrumentation needs.
 
+### Session start limit
+
+When several new Chrome sessions are set up at the same moment, chromedriver/Chrome sometimes leaves one of the
+setup commands unanswered (the first `browsingContext.create` or `navigate` of a fresh session): the render waits
+out its command timeout, and the session is left behind unanswering, which wears the Chrome down for the renders
+after it. Measured on chromedriver/Chrome 156 against one remote chromedriver: two setups at once stayed clean in
+720 renders; three at once failed in the first round.
+
+So bidi2pdf lets at most `session_start_concurrency` setups run at once in a process - from the session request to
+the first open tab, in every path (the CLI, `Bidi2pdf::DSL.with_tab`, the session warmer). Rendering is never
+limited: eight PDFs can render side by side while their setups took turns. A setup that cannot get a turn within
+`session_start_timeout` fails with `SessionStartTimeoutError` instead of queueing for ever. Every turn instruments
+`session_gate.bidi2pdf` (`limit`, `wait` in seconds, `acquired`).
+
+**The limit holds per process.** Chrome sees the setups of every process that talks to it, so processes sharing one
+Chrome divide its budget: two processes with a limit of 1 each are as safe as one with 2 - two with 2 each failed in
+every run. With Puma workers and a job process on one remote chromedriver, set the limit so that limit x processes
+stays at about 2, or give the processes Chromes of their own.
+
+It is one budget per process, whichever Chrome a setup goes to: two independent chromedrivers (a local one and a
+remote one, or two remote endpoints) still take turns. The limit is read once per process, at its first session
+setup (and again in a forked child): set it at boot, in an initializer. A later change is logged and takes effect
+after a restart.
+
+**A gate across processes.** `config.session_gate` takes an object of your own instead of the per-process
+semaphore - anything answering `with_permit { ... }` - so several processes can share one budget. Every setup
+path (CLI, `Bidi2pdf::DSL`, the session warmer, bidi2pdf-rails) asks it, and `session_gate.bidi2pdf` is
+instrumented as before. Your gate has to run the block with a permit, give the permit back however the block ends,
+raise `Bidi2pdf::SessionStartTimeoutError` when none comes free in time, and not lose permits when a process dies
+or forks (`session_start_concurrency` and `session_start_timeout` apply only if it reads them). A sketch for
+processes on one host - the kernel drops a `flock` when its process ends:
+
+```ruby
+# N lock files in a directory every process can reach: one free file is one permit.
+class FileLockGate
+  def initialize(dir, slots: 2, timeout: 60)
+    @paths = Array.new(slots) { |index| File.join(dir, "session-start-#{index}.lock") }
+    @timeout = timeout
+  end
+
+  def with_permit
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
+    loop do
+      @paths.each do |path|
+        File.open(path, File::RDWR | File::CREAT, 0o600) do |file|
+          return yield if file.flock(File::LOCK_EX | File::LOCK_NB) # closing the file releases the lock
+        end
+      end
+      raise Bidi2pdf::SessionStartTimeoutError, "no session start permit free" if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+      sleep 0.05
+    end
+  end
+end
+
+Bidi2pdf.configure { |config| config.session_gate = FileLockGate.new("/var/lib/myapp/bidi2pdf", slots: 2) }
+```
+
+**The evidence.** bidi2pdf's own measurements come first (2026-10-28, chromedriver/Chrome 156, one remote
+chromedriver, the chromedriver swept between runs): at a limit of 2, 0 of 720 renders failed at 4, 6 and 8 renders at
+once in ten interleaved rounds; at 3, renders failed from the first round on a freshly started Chrome; ungated, 104 of
+160 failed. Every unanswered command was traced as written to an open WebSocket, with no reply carrying its id ever
+read and no error raised - the client loses nothing. `bin/session-start-repro` reproduces it against any chromedriver
+(`LIMIT=none` against `LIMIT=2`).
+
+**Related reports.** No upstream report of exactly this was found (searched 2026-10-29: chromium-bidi, ChromeDriver,
+Selenium, Puppeteer, WebdriverIO, Mozilla). What follows is context, not confirmation - no other project has
+reported this bug.
+
+Related concurrency and lifecycle defects in WebDriver BiDi:
+
+- [Mozilla bug 2019511](https://bugzilla.mozilla.org/show_bug.cgi?id=2019511) "browsingContext.setViewport can
+  timeout if several contexts are created in parallel" - the closest analogy. In Firefox's BiDi a context's active
+  state could change before a waiting command ran, so a command depending on it timed out under parallel context
+  creation; fixed in Firefox 150 by always updating the dimensions synchronously in `browsingContext.create`.
+  Another browser and another cause, but the same kind of race: parallel context creation leaving a command
+  waiting.
+- ChromeDriver 127, [crbug 341048786](https://crbug.com/341048786) and [crbug 1503101](https://crbug.com/1503101)
+  ([crrev.com/c/5575497](https://crrev.com/c/5575497)): a race between ChromeDriver and the BiDi mapper during
+  session creation, fixed by waiting for `browsingContext.getTree` to return a non-empty list. The same phase - a
+  session's start - but already fixed in the 156 measured here, so what bidi2pdf meets is a race still left there.
+- ChromeDriver 126, [crbug 4762](https://crbug.com/4762) ([crrev.com/c/5515013](https://crrev.com/c/5515013)), and
+  144, [crbug 458027819](https://crbug.com/458027819) ([crrev.com/c/7128058](https://crrev.com/c/7128058)): Chrome
+  throttling background and occluded windows in BiDi sessions. bidi2pdf already passes
+  `--disable-background-timer-throttling`, `--disable-renderer-backgrounding` and
+  `--disable-backgrounding-occluded-windows`.
+
+The same symptom, no shown common cause:
+
+- [puppeteer#4039](https://github.com/puppeteer/puppeteer/issues/4039) "browser.newPage freezes (never resolves)" -
+  a new page that never comes back; no root cause was found, closed as out of scope.
+- [webdriverio#16051](https://github.com/webdriverio/webdriverio/issues/16051) - pending BiDi commands waiting for
+  their whole timeout after the connection closed, because the client never rejected them; fixed in WebdriverIO
+  (PR #16054). A client-side cause of the same symptom, ruled out for bidi2pdf by the trace above.
+
 ### Pre-warmed sessions (`Bidi2pdf::SessionWarmer`)
 
 Optional. Keeps a few Chrome sessions started in the background so a render skips browser startup.
 Every slot is still used for exactly one render and then discarded - isolation is the same as
-launching a fresh Chrome per PDF.
+launching a fresh Chrome per PDF. A slot is warmed together with its user context, window and tab,
+under one turn of the session start limit, so a checkout sets up nothing.
 
 ```ruby
 Bidi2pdf::SessionWarmer.configure do |c|

data/lib/bidi2pdf/dsl.rb

@@ -40,6 +40,8 @@ module Bidi2pdf
     def self.with_tab(remote_browser_url: nil, port: 0, headless: true, chrome_args: Bidi2pdf::Bidi::Session::DEFAULT_CHROME_ARGS.dup)
       manager = nil
       session = nil
+      context = nil
+      window = nil
       tab = nil
 
       begin
@@ -56,13 +58,16 @@ module Bidi2pdf
                     manager.session
                   end
 
-        session.start
-        session.client.on_close { Bidi2pdf.logger.info "WebSocket session closed" }
+        # Only the setup waits for the session start limit, the work in the tab does not.
+        Bidi2pdf::SessionGate.with_permit do
+          session.start
+          session.client.on_close { Bidi2pdf.logger.info "WebSocket session closed" }
 
-        browser = session.browser
-        context = browser.create_user_context
-        window = context.create_browser_window
-        tab = window.create_browser_tab
+          browser = session.browser
+          context = browser.create_user_context
+          window = context.create_browser_window
+          tab = window.create_browser_tab
+        end
 
         yield(tab)
       ensure

data/lib/bidi2pdf/error_codes.rb

@@ -18,6 +18,7 @@ module Bidi2pdf
       InvalidRecipeError => "INVALID_RECIPE",
       PdfInspectionUnavailableError => "PDF_INSPECTION_UNAVAILABLE",
       SessionNotStartedError => "BROWSER_LAUNCH_FAILED",
+      SessionStartTimeoutError => "BROWSER_LAUNCH_FAILED",
       CmdTimeoutError => "COMMAND_TIMEOUT",
       WebsocketError => "BROWSER_DISCONNECTED",
       NavigationTimeoutError => "NAVIGATION_TIMEOUT",

data/lib/bidi2pdf/session_gate.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Bidi2pdf
+  # At most Bidi2pdf.session_start_concurrency Chrome session setups at once in this process - from the session
+  # request to the first open tab (README "Session start limit"). When several new sessions are set up at the same
+  # moment, chromedriver/Chrome sometimes leaves a setup command unanswered and the session hangs until the command
+  # times out (measured on chromedriver/Chrome 156: three setups at once failed, two did not). Rendering is never
+  # limited, only the setup before it.
+  #
+  # The limit holds per process: processes sharing one Chrome (Puma workers, a job process) divide its budget
+  # between them. It is one budget for the process, whichever Chrome a setup goes to - two independent chromedrivers
+  # still take turns (an endpoint-scoped gate would not; not built). nil turns the gate off.
+  #
+  # The limit is read once per process - at its first setup, and again in a forked child, whose semaphore is its own
+  # so permits held by the parent's threads at the fork cannot be lost in it. A later change takes effect after a
+  # restart and is logged: set it at boot (an initializer), not while setups run. Changing it live would have to
+  # keep the setups in flight counted, which needs an API Concurrent::Semaphore does not document.
+  #
+  # Bidi2pdf.session_gate replaces the semaphore with an object of your own, to share the budget across processes
+  # (a file lock, a database or Redis lock). Its contract: +with_permit+ runs the block only while it holds a permit,
+  # gives the permit back however the block ends, raises Bidi2pdf::SessionStartTimeoutError when none comes free in
+  # time, and loses no permit when a process dies or forks. Every setup path still comes through here, so the
+  # notification below is sent either way - it trusts that the block runs under a permit. session_start_concurrency
+  # and session_start_timeout then apply only if that object reads them.
+  module SessionGate
+    LOCK = Mutex.new
+
+    class << self
+      # Runs the block with a permit, released however the block ends. Waits for one at most
+      # Bidi2pdf.session_start_timeout (default: Bidi2pdf.default_timeout) seconds, then raises
+      # SessionStartTimeoutError - a queue behind a hung setup fails loudly instead of growing.
+      def with_permit(&)
+        return with_custom_gate(Bidi2pdf.session_gate, &) if Bidi2pdf.session_gate
+
+        semaphore, limit = current
+        return yield unless semaphore
+
+        acquired, waited = acquire(semaphore)
+        refuse(limit, waited) unless acquired
+
+        # Everything after the permit is taken sits inside the ensure - a raising subscriber must not keep it.
+        begin
+          Bidi2pdf.notification_service.instrument("session_gate.bidi2pdf", { limit: limit, wait: waited, acquired: true })
+          yield
+        ensure
+          semaphore.release(1)
+        end
+      end
+
+      # Forgets the semaphore; the next permit builds one for the configured limit. For specs.
+      def reset!
+        LOCK.synchronize { @semaphore = @limit = @pid = @warned_limit = nil }
+      end
+
+      private
+
+      # The wait is the time until the custom gate runs the block - it reports a timeout itself, by raising.
+      def with_custom_gate(gate)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        gate.with_permit do
+          waited = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round(3)
+          Bidi2pdf.notification_service.instrument("session_gate.bidi2pdf", { limit: nil, wait: waited, acquired: true, gate: gate.class.name })
+          yield
+        end
+      end
+
+      # The semaphore of this process, built for the limit configured at its first setup (and in a forked child).
+      def current
+        LOCK.synchronize do
+          if @pid == Process.pid
+            warn_changed_limit
+          else
+            @limit = Bidi2pdf.session_start_concurrency
+            @semaphore = @limit && Concurrent::Semaphore.new(@limit)
+            @pid = Process.pid
+          end
+          [@semaphore, @limit]
+        end
+      end
+
+      # Once per new value: the limit in force stays until a restart.
+      def warn_changed_limit
+        configured = Bidi2pdf.session_start_concurrency
+        return if [@limit, @warned_limit].include?(configured)
+
+        @warned_limit = configured
+        Bidi2pdf.logger.warn "session_gate: session_start_concurrency changed to #{configured.inspect} after the first session " \
+                             "setup - #{@limit.inspect} stays in force until the process restarts"
+      end
+
+      def refuse(limit, waited)
+        Bidi2pdf.notification_service.instrument("session_gate.bidi2pdf", { limit: limit, wait: waited, acquired: false })
+        raise SessionStartTimeoutError.new(timeout_message(limit, waited), details: { limit: limit, waited: waited })
+      end
+
+      def acquire(semaphore)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        acquired = semaphore.try_acquire(1, Bidi2pdf.session_start_timeout || Bidi2pdf.default_timeout)
+        [acquired, (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round(3)]
+      end
+
+      def timeout_message(limit, waited)
+        "No Chrome session could start within #{waited}s: #{limit} other session setup(s) in this process held every permit"
+      end
+    end
+  end
+end

data/lib/bidi2pdf/session_runner.rb

@@ -56,9 +56,7 @@ module Bidi2pdf
     # rubocop: enable Metrics/ParameterLists
 
     def run
-      @session.start
-      @session.client.on_close { Bidi2pdf.logger.info "WebSocket closed" }
-
+      open_tab
       setup_browser
       run_flow
     end
@@ -69,9 +67,7 @@ module Bidi2pdf
     #
     # @return [Bidi2pdf::Bidi::BrowserTab] the navigated tab.
     def run_diagnose
-      @session.start
-      @session.client.on_close { Bidi2pdf.logger.info "WebSocket closed" }
-
+      open_tab
       setup_browser
       navigate_and_wait
 
@@ -88,18 +84,21 @@ module Bidi2pdf
 
     private
 
-    def setup_browser
-      browser = @session.browser
-      user_context = browser.create_user_context
-
-      window = user_context.create_browser_window
-      tab = window.create_browser_tab
+    # The session's setup, up to its first tab, waits for the session start limit (Bidi2pdf::SessionGate);
+    # everything after it does not.
+    def open_tab
+      Bidi2pdf::SessionGate.with_permit do
+        @session.start
+        @session.client.on_close { Bidi2pdf.logger.info "WebSocket closed" }
 
-      @window = window
-      @tab = tab
-      @user_context = user_context
+        @user_context = @session.browser.create_user_context
+        @window = @user_context.create_browser_window
+        @tab = @window.create_browser_tab
+      end
+    end
 
-      add_cookies(tab)
+    def setup_browser
+      add_cookies(@tab)
 
       add_headers
       add_basic_auth

data/lib/bidi2pdf/session_warmer.rb

@@ -326,23 +326,17 @@ module Bidi2pdf
       @sweeper&.sweep!(reason: reason)
     end
 
-    # Checks out a slot, creates an isolated UserContext/Window/Tab for one render, yields the tab,
-    # then unconditionally closes those resources and retires the underlying slot.
+    # Checks out a slot, yields its tab - in a UserContext of its own, created with the slot (#new_slot) - for one
+    # render, then unconditionally closes the tab, window and user context and retires the slot.
     def with_tab
       slot = checkout
-      user_context = nil
-      window = nil
-      tab = nil
 
       begin
-        user_context = slot[:browser].create_user_context
-        window = user_context.create_browser_window
-        tab = window.create_browser_tab
-        yield tab
+        yield slot[:tab]
       ensure
-        safe_close("tab") { tab&.close }
-        safe_close("window") { window&.close }
-        safe_close("user context") { user_context&.close }
+        safe_close("tab") { slot[:tab]&.close }
+        safe_close("window") { slot[:window]&.close }
+        safe_close("user context") { slot[:user_context]&.close }
         retire(slot)
       end
     end
@@ -446,14 +440,28 @@ module Bidi2pdf
     end
 
     # A chromedriver out of room for another Chrome refuses the session; with a sweeper, close
-    # everything nobody holds (a pressure sweep) and try once more.
+    # everything nobody holds (a pressure sweep) and try once more. Each attempt waits for the session
+    # start limit (Bidi2pdf::SessionGate), the sweep between them does not.
     def new_slot
-      @slot_factory.call
+      Bidi2pdf::SessionGate.with_permit { with_first_tab(@slot_factory.call) }
     rescue Bidi2pdf::SessionNotStartedError
       raise unless @sweeper && @config.retry_refused_sessions
 
       @sweeper.sweep!(reason: :create_failed, pressure: true)
-      @slot_factory.call
+      Bidi2pdf::SessionGate.with_permit { with_first_tab(@slot_factory.call) }
+    end
+
+    # The slot's user context, window and tab, opened together with its session under one permit: what the limit
+    # has to bound is the number of sessions between their request and their first tab - split into two permits,
+    # sessions started in between waited for their tab side by side, and chromedriver left setups unanswered
+    # (docs: README "Session start limit"). A slot whose tab cannot be opened is retired at once.
+    def with_first_tab(slot)
+      user_context = slot[:browser].create_user_context
+      window = user_context.create_browser_window
+      slot.merge(user_context: user_context, window: window, tab: window.create_browser_tab)
+    rescue StandardError
+      self.class.retire_slot(session: slot[:session], manager: slot[:manager])
+      raise
     end
 
     def start_background_work

data/lib/bidi2pdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
-  VERSION = "0.1.25"
+  VERSION = "0.1.26"
 end

data/lib/bidi2pdf.rb

@@ -15,6 +15,7 @@ require_relative "bidi2pdf/session_registry"
 require_relative "bidi2pdf/session_sweeper"
 require_relative "bidi2pdf/chromedriver_api"
 require_relative "bidi2pdf/chrome_sweeper"
+require_relative "bidi2pdf/session_gate"
 require_relative "bidi2pdf/session_warmer"
 require_relative "bidi2pdf/verbose_logger"
 
@@ -56,6 +57,14 @@ module Bidi2pdf # rubocop:disable Metrics/ModuleLength
     def hint = "Check Chrome/chromedriver are installed and reachable, or that --remote-browser-url points at a running instance"
   end
 
+  # No permit of the session start limit (Bidi2pdf::SessionGate) came free in time: other session setups in this
+  # process held them all. Reported like a session that did not start (BROWSER_LAUNCH_FAILED).
+  class SessionStartTimeoutError < Error
+    def retryable? = true
+
+    def hint = "Start fewer renders at once, or raise session_start_concurrency / session_start_timeout"
+  end
+
   class WebsocketError < Error
     def retryable? = true
   end
@@ -176,7 +185,29 @@ module Bidi2pdf # rubocop:disable Metrics/ModuleLength
 
   class << self
     attr_accessor :default_timeout, :enable_default_logging_subscriber, :log_truncate_limit, :chromedriver_log_level
-    attr_reader :logging_subscriber, :logger, :network_events_logger, :browser_console_logger, :notification_service
+    attr_reader :session_start_concurrency, :session_start_timeout, :session_gate, :logging_subscriber, :logger, :network_events_logger, :browser_console_logger, :notification_service
+
+    # How many Chrome session setups may run at once in this process (Bidi2pdf::SessionGate); nil: no limit.
+    def session_start_concurrency=(limit)
+      raise InvalidConfigError, "session_start_concurrency must be nil or a positive Integer, got #{limit.inspect}" unless limit.nil? || (limit.is_a?(Integer) && limit.positive?)
+
+      @session_start_concurrency = limit
+    end
+
+    # An object of your own for the session start limit - anything answering +with_permit { ... }+, e.g. a lock shared
+    # by several processes (Bidi2pdf::SessionGate); nil: the built-in per-process semaphore.
+    def session_gate=(gate)
+      raise InvalidConfigError, "session_gate must be nil or respond to with_permit, got #{gate.inspect}" unless gate.nil? || gate.respond_to?(:with_permit)
+
+      @session_gate = gate
+    end
+
+    # Seconds a setup waits for a permit; nil: default_timeout.
+    def session_start_timeout=(seconds)
+      raise InvalidConfigError, "session_start_timeout must be nil or a positive number, got #{seconds.inspect}" unless seconds.nil? || (seconds.is_a?(Numeric) && seconds.positive?)
+
+      @session_start_timeout = seconds
+    end
 
     # Allow configuration through a block
     def configure
@@ -271,6 +302,11 @@ module Bidi2pdf # rubocop:disable Metrics/ModuleLength
 
     config.default_timeout = 60
 
+    # Two setups at once: measured clean on chromedriver/Chrome 156, three were not (README "Session start limit").
+    config.session_start_concurrency = 2
+    config.session_start_timeout = nil
+    config.session_gate = nil
+
     config.log_truncate_limit = 200
 
     config.notification_service = Notifications

data/sig/bidi2pdf/session_gate.rbs

@@ -0,0 +1,53 @@
+module Bidi2pdf
+  # At most Bidi2pdf.session_start_concurrency Chrome session setups at once in this process - from the session
+  # request to the first open tab (README "Session start limit"). When several new sessions are set up at the same
+  # moment, chromedriver/Chrome sometimes leaves a setup command unanswered and the session hangs until the command
+  # times out (measured on chromedriver/Chrome 156: three setups at once failed, two did not). Rendering is never
+  # limited, only the setup before it.
+  #
+  # The limit holds per process: processes sharing one Chrome (Puma workers, a job process) divide its budget
+  # between them. It is one budget for the process, whichever Chrome a setup goes to - two independent chromedrivers
+  # still take turns (an endpoint-scoped gate would not; not built). nil turns the gate off.
+  #
+  # The limit is read once per process - at its first setup, and again in a forked child, whose semaphore is its own
+  # so permits held by the parent's threads at the fork cannot be lost in it. A later change takes effect after a
+  # restart and is logged: set it at boot (an initializer), not while setups run. Changing it live would have to
+  # keep the setups in flight counted, which needs an API Concurrent::Semaphore does not document.
+  #
+  # Bidi2pdf.session_gate replaces the semaphore with an object of your own, to share the budget across processes
+  # (a file lock, a database or Redis lock). Its contract: +with_permit+ runs the block only while it holds a permit,
+  # gives the permit back however the block ends, raises Bidi2pdf::SessionStartTimeoutError when none comes free in
+  # time, and loses no permit when a process dies or forks. Every setup path still comes through here, so the
+  # notification below is sent either way - it trusts that the block runs under a permit. session_start_concurrency
+  # and session_start_timeout then apply only if that object reads them.
+  module SessionGate
+    self.@warned_limit: untyped
+
+    LOCK: untyped
+
+    # Runs the block with a permit, released however the block ends. Waits for one at most
+    # Bidi2pdf.session_start_timeout (default: Bidi2pdf.default_timeout) seconds, then raises
+    # SessionStartTimeoutError - a queue behind a hung setup fails loudly instead of growing.
+    def self.with_permit: () { () -> untyped } -> untyped
+
+    # Forgets the semaphore; the next permit builds one for the configured limit. For specs.
+    def self.reset!: () -> untyped
+
+    private
+
+    # The wait is the time until the custom gate runs the block - it reports a timeout itself, by raising.
+    def self.with_custom_gate: (untyped gate) { () -> untyped } -> untyped
+
+    # The semaphore of this process, built for the limit configured at its first setup (and in a forked child).
+    def self.current: () -> untyped
+
+    # Once per new value: the limit in force stays until a restart.
+    def self.warn_changed_limit: () -> (nil | untyped)
+
+    def self.refuse: (untyped limit, untyped waited) -> untyped
+
+    def self.acquire: (untyped semaphore) -> ::Array[untyped]
+
+    def self.timeout_message: (untyped limit, untyped waited) -> ::String
+  end
+end

data/sig/bidi2pdf/session_runner.rbs

@@ -58,12 +58,6 @@ module Bidi2pdf
 
     @emulate_media: untyped
 
-    @window: untyped
-
-    @tab: untyped
-
-    @user_context: untyped
-
     @uri: untyped
 
     # rubocop: disable Metrics/ParameterLists
@@ -84,6 +78,10 @@ module Bidi2pdf
 
     private
 
+    # The session's setup, up to its first tab, waits for the session start limit (Bidi2pdf::SessionGate);
+    # everything after it does not.
+    def open_tab: () -> untyped
+
     def setup_browser: () -> untyped
 
     def add_cookies: (untyped tab) -> untyped

data/sig/bidi2pdf/session_warmer.rbs

@@ -248,8 +248,8 @@ module Bidi2pdf
     # @return [ChromeSweeper::Result, nil] nil when no sweeper is configured.
     def sweep!: (?reason: ::Symbol) -> untyped
 
-    # Checks out a slot, creates an isolated UserContext/Window/Tab for one render, yields the tab,
-    # then unconditionally closes those resources and retires the underlying slot.
+    # Checks out a slot, yields its tab - in a UserContext of its own, created with the slot (#new_slot) - for one
+    # render, then unconditionally closes the tab, window and user context and retires the slot.
     def with_tab: () { (untyped) -> untyped } -> untyped
 
     # Retires every currently-warm spare and waits for any in-flight background replenishment to
@@ -297,9 +297,16 @@ module Bidi2pdf
     def create_slot: () -> untyped
 
     # A chromedriver out of room for another Chrome refuses the session; with a sweeper, close
-    # everything nobody holds (a pressure sweep) and try once more.
+    # everything nobody holds (a pressure sweep) and try once more. Each attempt waits for the session
+    # start limit (Bidi2pdf::SessionGate), the sweep between them does not.
     def new_slot: () -> untyped
 
+    # The slot's user context, window and tab, opened together with its session under one permit: what the limit
+    # has to bound is the number of sessions between their request and their first tab - split into two permits,
+    # sessions started in between waited for their tab side by side, and chromedriver left setups unanswered
+    # (docs: README "Session start limit"). A slot whose tab cannot be opened is retired at once.
+    def with_first_tab: (untyped slot) -> untyped
+
     def start_background_work: () -> untyped
 
     def build_sweeper: () -> (nil | untyped)

data/sig/bidi2pdf/version.rbs

@@ -1,3 +1,3 @@
 module Bidi2pdf
-  VERSION: "0.1.25"
+  VERSION: "0.1.26"
 end

data/sig/bidi2pdf.rbs

@@ -1,4 +1,10 @@
 module Bidi2pdf
+  self.@session_start_concurrency: untyped
+
+  self.@session_gate: untyped
+
+  self.@session_start_timeout: untyped
+
   self.@logger: untyped
 
   self.@network_events_logger: untyped
@@ -33,6 +39,14 @@ module Bidi2pdf
     def hint: () -> "Check Chrome/chromedriver are installed and reachable, or that --remote-browser-url points at a running instance"
   end
 
+  # No permit of the session start limit (Bidi2pdf::SessionGate) came free in time: other session setups in this
+  # process held them all. Reported like a session that did not start (BROWSER_LAUNCH_FAILED).
+  class SessionStartTimeoutError < Error
+    def retryable?: () -> true
+
+    def hint: () -> "Start fewer renders at once, or raise session_start_concurrency / session_start_timeout"
+  end
+
   class WebsocketError < Error
     def retryable?: () -> true
   end
@@ -155,6 +169,12 @@ module Bidi2pdf
 
   attr_accessor self.chromedriver_log_level: untyped
 
+  attr_reader self.session_start_concurrency: untyped
+
+  attr_reader self.session_start_timeout: untyped
+
+  attr_reader self.session_gate: untyped
+
   attr_reader self.logging_subscriber: untyped
 
   attr_reader self.logger: untyped
@@ -165,6 +185,16 @@ module Bidi2pdf
 
   attr_reader self.notification_service: untyped
 
+  # How many Chrome session setups may run at once in this process (Bidi2pdf::SessionGate); nil: no limit.
+  def self.session_start_concurrency=: (untyped limit) -> untyped
+
+  # An object of your own for the session start limit - anything answering +with_permit { ... }+, e.g. a lock shared
+  # by several processes (Bidi2pdf::SessionGate); nil: the built-in per-process semaphore.
+  def self.session_gate=: (untyped gate) -> untyped
+
+  # Seconds a setup waits for a permit; nil: default_timeout.
+  def self.session_start_timeout=: (untyped seconds) -> untyped
+
   # Allow configuration through a block
   def self.configure: () ?{ (untyped) -> untyped } -> untyped
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bidi2pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.25
+  version: 0.1.26
 platform: ruby
 authors:
 - Dieter S.
@@ -497,6 +497,7 @@ files:
 - lib/bidi2pdf/result.rb
 - lib/bidi2pdf/result_collector.rb
 - lib/bidi2pdf/schema.rb
+- lib/bidi2pdf/session_gate.rb
 - lib/bidi2pdf/session_registry.rb
 - lib/bidi2pdf/session_registry/heartbeat.rb
 - lib/bidi2pdf/session_runner.rb
@@ -605,6 +606,7 @@ files:
 - sig/bidi2pdf/result.rbs
 - sig/bidi2pdf/result_collector.rbs
 - sig/bidi2pdf/schema.rbs
+- sig/bidi2pdf/session_gate.rbs
 - sig/bidi2pdf/session_registry.rbs
 - sig/bidi2pdf/session_registry/heartbeat.rbs
 - sig/bidi2pdf/session_runner.rbs