bidi2pdf 0.1.16 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3533d126bc13406c70b6931112c07952aac0c19b718f3100258fb2182da8fcea
-  data.tar.gz: a761495802d5507fba3469405a571555547ed58891b216575f947e2b6a0c63be
+  metadata.gz: b879e9c84ccd1584f5b2eb1b406972624cd8b64a50c92466e78f7275ef229441
+  data.tar.gz: 50d517dac875995c2a06ca39dcd8c521c0b18fd238b6950d5e0d9674187941dd
 SHA512:
-  metadata.gz: cb29c3bf90a6a6dbd6fcf488980c51b9f666206ea18748d0c670e6fc2a64c453ca0f20043dce113094e74eb34d4b45f6be8b7d7a433522a59ac6ebab2d6ba8bb
-  data.tar.gz: bb9c384545c42d45630576b523c3c82025b1df2a2fc8975b8959276566173ad684b9423e7f30fc46b7834c61328ef68f9ddb1ee73d83b08e0ec8ea10b93f117f
+  metadata.gz: 7fca9af905a088093ff4c8ac3a1c78b4f6138068c27ad4cf87616c7ded67f44b3d57aab73b40d83b6c9d8d63097f2851b10f5b0531a91bc22088ec15aab21769
+  data.tar.gz: 835727303208ada398c0ec7456e29d49201d2b798a34edac35007c40ae5123e2a382a6e325e978237fd328ef0d58e6f573d61b1447df54bae51f9188775ab4c6

data/CHANGELOG.md

@@ -8,10 +8,33 @@ 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.17..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [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 +495,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.16..HEAD)
+- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.17..HEAD)
+- [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,24 @@ 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. |
+
+#### 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`.
 
 > **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

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/session.rb

@@ -74,6 +74,10 @@ 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.
@@ -227,7 +231,7 @@ module Bidi2pdf
         value = session_data["value"]
         handle_error(value) if value.nil? || value["error"]
 
-        session_id = value["sessionId"]
+        @session_id = value["sessionId"]
         ws_url = value["capabilities"]["webSocketUrl"]
 
         Bidi2pdf.logger.info "Created session with ID: #{session_id}"

data/lib/bidi2pdf/session_registry.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "tmpdir"
+
+module Bidi2pdf
+  # Remembers which sessions a SessionWarmer opened on a shared (remote) chromedriver, and when, in a
+  # small JSON file per chromedriver URL - so a process started later can find and close the ones a
+  # process that died without a clean shutdown left behind (see SessionSweeper). chromedriver itself
+  # keeps a session until someone deletes it, and it drops any tag we could attach to one (a custom
+  # capability is accepted but echoed nowhere - checked against chromedriver 153), hence a file.
+  #
+  # Everything here is best effort and fail-open: a directory that is not writable, a locked-out or
+  # corrupt file only switches orphan tracking off for this process (one warning, one
+  # +session_warmer.registry_unavailable.bidi2pdf+ notification) - rendering never depends on it.
+  # The file is created 0600 and every change happens under an exclusive lock, so processes sharing
+  # the directory (a dev server, a job worker, a spec run) can record at the same time.
+  class SessionRegistry
+    FILE_PREFIX = "bidi2pdf-sessions-"
+
+    attr_reader :path
+
+    def initialize(session_url, dir: nil)
+      @path = File.join(dir || Dir.tmpdir, "#{FILE_PREFIX}#{Digest::SHA256.hexdigest(session_url.to_s)[0, 16]}.json")
+      @warned = false
+    end
+
+    # Records a session the caller just opened.
+    def record(session_id, created_at: Time.now.to_i)
+      return false if session_id.nil?
+
+      update { |entries| entries[session_id.to_s] = created_at.to_i }
+    end
+
+    # Forgets a session the caller closed itself (or found gone).
+    def forget(session_id)
+      return false if session_id.nil?
+
+      update { |entries| entries.delete(session_id.to_s) }
+    end
+
+    # The recorded session ids opened at or before +cutoff+ (epoch seconds).
+    def recorded_before(cutoff)
+      entries = read
+      entries.select { |_, created_at| created_at <= cutoff }.keys
+    end
+
+    private
+
+    def read
+      return {} unless File.exist?(path)
+
+      File.open(path, File::RDONLY) do |file|
+        file.flock(File::LOCK_SH)
+        parse(file.read)
+      end
+    rescue SystemCallError, IOError => e
+      unavailable!(e)
+      {}
+    end
+
+    def update
+      File.open(path, File::RDWR | File::CREAT, 0o600) do |file|
+        file.flock(File::LOCK_EX)
+        entries = parse(file.read)
+        yield entries
+        file.rewind
+        file.truncate(0)
+        file.write(JSON.generate(entries))
+        file.flush
+      end
+      true
+    rescue SystemCallError, IOError => e
+      unavailable!(e)
+      false
+    end
+
+    # A corrupt or foreign file counts as empty rather than as an error.
+    def parse(text)
+      data = text.to_s.empty? ? {} : JSON.parse(text)
+      return {} unless data.is_a?(Hash)
+
+      data.select { |id, created_at| id.is_a?(String) && created_at.is_a?(Integer) }
+    rescue JSON::ParserError
+      {}
+    end
+
+    def unavailable!(error)
+      return if @warned
+
+      @warned = true
+      Bidi2pdf.logger.warn "session_warmer: session registry #{path} unavailable, leftover sessions will not be tracked: #{error.message}"
+      Bidi2pdf.notification_service.instrument("session_warmer.registry_unavailable.bidi2pdf", { path: path, error: error.class.name })
+    end
+  end
+end

data/lib/bidi2pdf/session_sweeper.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Bidi2pdf
+  # Closes sessions a SessionWarmer recorded (SessionRegistry) on a shared chromedriver that are
+  # older than a cutoff - left behind by a process that died without a clean shutdown, and holding a
+  # whole Chrome each until someone deletes them. Run once when a warmer starts.
+  #
+  # Only recorded sessions are ever touched - another tool's sessions on the same chromedriver never
+  # are. A recorded session that is already gone ("invalid session id" / 404) is just forgotten.
+  # Fail-open: any error is logged and ends the sweep; it never raises.
+  class SessionSweeper
+    # @param session_url [String] the chromedriver's new-session URL (".../session").
+    # @param registry [SessionRegistry]
+    # @param http [#call, nil] (method, url) -> status code; injectable for tests.
+    def initialize(session_url, registry, http: nil)
+      @session_url = session_url.to_s.chomp("/")
+      @registry = registry
+      @http = http || method(:net_http)
+    end
+
+    # Closes recorded sessions opened more than +older_than+ seconds before +now+.
+    #
+    # @return [Integer] how many sessions were actually closed.
+    def sweep(older_than:, now: Time.now.to_i)
+      closed = @registry.recorded_before(now - older_than).count { |id| closed_now?(id) }
+      report(closed)
+      closed
+    rescue StandardError => e
+      Bidi2pdf.logger.warn "session_warmer: sweeping leftover sessions failed: #{e.message}"
+      Bidi2pdf.notification_service.instrument("session_warmer.sweep_failed.bidi2pdf", { error: e.class.name })
+      0
+    end
+
+    private
+
+    # True when this call closed the session; a session already gone is forgotten but not counted.
+    def closed_now?(id)
+      status = @http.call(:delete, "#{@session_url}/#{id}")
+      return false unless [200, 404].include?(status)
+
+      @registry.forget(id)
+      status == 200
+    end
+
+    def report(closed)
+      return if closed.zero?
+
+      Bidi2pdf.logger.info "session_warmer: closed #{closed} leftover session(s) on #{@session_url}"
+      Bidi2pdf.notification_service.instrument("session_warmer.orphans_closed.bidi2pdf", { count: closed })
+    end
+
+    # chromedriver answers a DELETE of a session it no longer has with 404 "invalid session id".
+    def net_http(method, url)
+      uri = URI(url)
+      request = method == :delete ? Net::HTTP::Delete.new(uri) : Net::HTTP::Get.new(uri)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 30) do |http|
+        http.request(request).code.to_i
+      end
+    end
+  end
+end

data/lib/bidi2pdf/session_warmer.rb

@@ -50,6 +50,17 @@ module Bidi2pdf
       #   1.25x this value even when no render ever comes. +nil+ disables the limit.
       attr_accessor :max_idle_age
 
+      # @return [Numeric, Symbol, nil] Seconds after which a session recorded by any warmer on the
+      #   same remote chromedriver counts as left behind - its process died without closing it - and
+      #   is closed when a warmer starts (SessionSweeper). +:auto+ (the default) is twice
+      #   max_idle_age: a live warmer recycles its own spares within ~1.25x of that, so no live
+      #   process's slot is ever taken. +nil+ disables the sweep. Remote mode only.
+      attr_accessor :orphan_age
+
+      # @return [String, nil] Directory for the session registry file (SessionRegistry); +nil+ means
+      #   Dir.tmpdir. Every process that should clean up after the others must share it.
+      attr_accessor :registry_dir
+
       DEFAULT_MAX_IDLE_AGE = 300
 
       def initialize
@@ -59,12 +70,21 @@ module Bidi2pdf
         @remote_browser_url = nil
         @slot_factory = nil
         @max_idle_age = DEFAULT_MAX_IDLE_AGE
+        @orphan_age = :auto
+        @registry_dir = nil
+      end
+
+      # The orphan age in seconds, or nil when the sweep is off (also when +:auto+ has no
+      # max_idle_age to derive it from).
+      def effective_orphan_age
+        orphan_age == :auto ? max_idle_age && (max_idle_age * 2) : orphan_age
       end
 
       # @raise [ArgumentError] if a setting can't be honored - checked once, at construction.
       def validate!
         validate_size!
         validate_max_idle_age!
+        validate_orphan_age!
       end
 
       private
@@ -80,6 +100,12 @@ module Bidi2pdf
 
         raise ArgumentError, "max_idle_age must be nil or a positive number of seconds, got #{max_idle_age.inspect}"
       end
+
+      def validate_orphan_age!
+        return if orphan_age.nil? || orphan_age == :auto || (orphan_age.is_a?(Numeric) && orphan_age.positive?)
+
+        raise ArgumentError, "orphan_age must be :auto, nil or a positive number of seconds, got #{orphan_age.inspect}"
+      end
     end
 
     class << self
@@ -181,6 +207,8 @@ module Bidi2pdf
       @warming = 0
       @shutdown = false
       @reaper_wakeup = Thread::Queue.new
+      @registry = build_registry
+      sweep_leftovers
       prewarm
       @reaper = Thread.new { reap_loop } if @config.max_idle_age
     end
@@ -235,7 +263,26 @@ module Bidi2pdf
     end
 
     def create_slot
-      @slot_factory.call
+      @slot_factory.call.tap { |slot| @registry&.record(session_id_of(slot)) }
+    end
+
+    # Remote mode with an orphan age: sessions are recorded, so a later start can close the ones
+    # this process leaves behind if it dies uncleanly - and this start closes others' leftovers.
+    def build_registry
+      return unless @config.remote_browser_url && @config.effective_orphan_age
+
+      Bidi2pdf::SessionRegistry.new(@config.remote_browser_url, dir: @config.registry_dir)
+    end
+
+    def sweep_leftovers
+      return unless @registry
+
+      Bidi2pdf::SessionSweeper.new(@config.remote_browser_url, @registry).sweep(older_than: @config.effective_orphan_age)
+    end
+
+    def session_id_of(slot)
+      session = slot[:session]
+      session.session_id if session.respond_to?(:session_id)
     end
 
     # Session#started? is just an internal flag set once at startup - it never flips back if Chrome,
@@ -366,8 +413,11 @@ module Bidi2pdf
       retire(slot) if discard
     end
 
+    # Forgotten only after closing: a process that dies in between leaves a record whose session is
+    # already gone - the next sweep just drops it - never an open session nobody knows about.
     def retire(slot)
       self.class.retire_slot(session: slot[:session], manager: slot[:manager])
+      @registry&.forget(session_id_of(slot))
     end
 
     def safe_close(label, &)

data/lib/bidi2pdf/version.rb

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

data/lib/bidi2pdf.rb

@@ -10,6 +10,8 @@ require_relative "bidi2pdf/dsl"
 require_relative "bidi2pdf/notifications"
 require_relative "bidi2pdf/notifications/logging_subscriber"
 require_relative "bidi2pdf/notifications/json_subscriber"
+require_relative "bidi2pdf/session_registry"
+require_relative "bidi2pdf/session_sweeper"
 require_relative "bidi2pdf/session_warmer"
 require_relative "bidi2pdf/verbose_logger"
 

data/sig/bidi2pdf/bidi/buffered_web_socket_client.rbs

@@ -59,6 +59,13 @@ module Bidi2pdf
 
       def emit: (untyped event, *untyped) -> untyped
 
+      # 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: (untyped bytes) -> untyped
 
       def say_goodbye: () -> untyped

data/sig/bidi2pdf/bidi/session.rbs

@@ -33,6 +33,8 @@ module Bidi2pdf
 
       @websocket_url: untyped
 
+      @session_id: untyped
+
       # Events to subscribe to during the session.
       SUBSCRIBE_EVENTS: ::Array["script"]
 
@@ -48,6 +50,10 @@ module Bidi2pdf
       # @return [Array<String>] The Chrome arguments for the session.
       attr_reader chrome_args: untyped
 
+      # @return [String, nil] chromedriver's id for this session, once it was created - what
+      #   SessionWarmer records so a later process can close it if this one dies uncleanly.
+      attr_reader session_id: untyped
+
       # Initializes a new session.
       #
       # @param [String] session_url The URL for the session.

data/sig/bidi2pdf/session_registry.rbs

@@ -0,0 +1,44 @@
+module Bidi2pdf
+  # Remembers which sessions a SessionWarmer opened on a shared (remote) chromedriver, and when, in a
+  # small JSON file per chromedriver URL - so a process started later can find and close the ones a
+  # process that died without a clean shutdown left behind (see SessionSweeper). chromedriver itself
+  # keeps a session until someone deletes it, and it drops any tag we could attach to one (a custom
+  # capability is accepted but echoed nowhere - checked against chromedriver 153), hence a file.
+  #
+  # Everything here is best effort and fail-open: a directory that is not writable, a locked-out or
+  # corrupt file only switches orphan tracking off for this process (one warning, one
+  # +session_warmer.registry_unavailable.bidi2pdf+ notification) - rendering never depends on it.
+  # The file is created 0600 and every change happens under an exclusive lock, so processes sharing
+  # the directory (a dev server, a job worker, a spec run) can record at the same time.
+  class SessionRegistry
+    @path: untyped
+
+    @warned: untyped
+
+    FILE_PREFIX: "bidi2pdf-sessions-"
+
+    attr_reader path: untyped
+
+    def initialize: (untyped session_url, ?dir: untyped?) -> void
+
+    # Records a session the caller just opened.
+    def record: (untyped session_id, ?created_at: untyped) -> (false | untyped)
+
+    # Forgets a session the caller closed itself (or found gone).
+    def forget: (untyped session_id) -> (false | untyped)
+
+    # The recorded session ids opened at or before +cutoff+ (epoch seconds).
+    def recorded_before: (untyped cutoff) -> untyped
+
+    private
+
+    def read: () -> untyped
+
+    def update: () { (untyped) -> untyped } -> untyped
+
+    # A corrupt or foreign file counts as empty rather than as an error.
+    def parse: (untyped text) -> untyped
+
+    def unavailable!: (untyped error) -> (nil | untyped)
+  end
+end

data/sig/bidi2pdf/session_sweeper.rbs

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

data/sig/bidi2pdf/session_warmer.rbs

@@ -42,6 +42,8 @@ module Bidi2pdf
 
     @reaper_wakeup: untyped
 
+    @registry: untyped
+
     @reaper: untyped
 
     # Configuration for the session warmer.
@@ -58,6 +60,10 @@ module Bidi2pdf
 
       @max_idle_age: untyped
 
+      @orphan_age: untyped
+
+      @registry_dir: untyped
+
       # @return [Integer] Number of Chrome slots to keep pre-warmed.
       attr_accessor size: untyped
 
@@ -84,10 +90,25 @@ module Bidi2pdf
       #   1.25x this value even when no render ever comes. +nil+ disables the limit.
       attr_accessor max_idle_age: untyped
 
+      # @return [Numeric, Symbol, nil] Seconds after which a session recorded by any warmer on the
+      #   same remote chromedriver counts as left behind - its process died without closing it - and
+      #   is closed when a warmer starts (SessionSweeper). +:auto+ (the default) is twice
+      #   max_idle_age: a live warmer recycles its own spares within ~1.25x of that, so no live
+      #   process's slot is ever taken. +nil+ disables the sweep. Remote mode only.
+      attr_accessor orphan_age: untyped
+
+      # @return [String, nil] Directory for the session registry file (SessionRegistry); +nil+ means
+      #   Dir.tmpdir. Every process that should clean up after the others must share it.
+      attr_accessor registry_dir: untyped
+
       DEFAULT_MAX_IDLE_AGE: 300
 
       def initialize: () -> void
 
+      # The orphan age in seconds, or nil when the sweep is off (also when +:auto+ has no
+      # max_idle_age to derive it from).
+      def effective_orphan_age: () -> untyped
+
       # @raise [ArgumentError] if a setting can't be honored - checked once, at construction.
       def validate!: () -> untyped
 
@@ -96,6 +117,8 @@ module Bidi2pdf
       def validate_size!: () -> (nil | untyped)
 
       def validate_max_idle_age!: () -> (nil | untyped)
+
+      def validate_orphan_age!: () -> (nil | untyped)
     end
 
     # Configures the warmer and eagerly (re)creates the singleton, warming config.size slots right
@@ -161,6 +184,14 @@ module Bidi2pdf
 
     def create_slot: () -> untyped
 
+    # Remote mode with an orphan age: sessions are recorded, so a later start can close the ones
+    # this process leaves behind if it dies uncleanly - and this start closes others' leftovers.
+    def build_registry: () -> (nil | untyped)
+
+    def sweep_leftovers: () -> (nil | untyped)
+
+    def session_id_of: (untyped slot) -> untyped
+
     # Session#started? is just an internal flag set once at startup - it never flips back if Chrome,
     # ChromeDriver, or the WebSocket dies externally while a slot sits idle in the cache. The
     # client's own #open? is kept live by the reader thread noticing a real socket error, so
@@ -214,6 +245,8 @@ module Bidi2pdf
     # reservation is released here, in the same critical section as the stash.
     def stash_or_retire: (untyped slot) -> untyped
 
+    # Forgotten only after closing: a process that dies in between leaves a record whose session is
+    # already gone - the next sweep just drops it - never an open session nobody knows about.
     def retire: (untyped slot) -> untyped
 
     def safe_close: (untyped label) { (?) -> untyped } -> untyped

data/sig/bidi2pdf/version.rbs

@@ -1,3 +1,3 @@
 module Bidi2pdf
-  VERSION: "0.1.16"
+  VERSION: "0.1.17"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bidi2pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.16
+  version: 0.1.17
 platform: ruby
 authors:
 - Dieter S.
@@ -87,16 +87,22 @@ dependencies:
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: sys-proctable
   requirement: !ruby/object:Gem::Requirement
@@ -481,7 +487,9 @@ files:
 - lib/bidi2pdf/result.rb
 - lib/bidi2pdf/result_collector.rb
 - lib/bidi2pdf/schema.rb
+- lib/bidi2pdf/session_registry.rb
 - lib/bidi2pdf/session_runner.rb
+- lib/bidi2pdf/session_sweeper.rb
 - lib/bidi2pdf/session_warmer.rb
 - lib/bidi2pdf/test_helpers.rb
 - lib/bidi2pdf/test_helpers/configuration.rb
@@ -579,7 +587,9 @@ files:
 - sig/bidi2pdf/result.rbs
 - sig/bidi2pdf/result_collector.rbs
 - sig/bidi2pdf/schema.rbs
+- sig/bidi2pdf/session_registry.rbs
 - sig/bidi2pdf/session_runner.rbs
+- sig/bidi2pdf/session_sweeper.rbs
 - sig/bidi2pdf/session_warmer.rbs
 - sig/bidi2pdf/test_helpers.rbs
 - sig/bidi2pdf/test_helpers/configuration.rbs