bidi2pdf 0.1.17 → 0.1.18

data/lib/bidi2pdf/session_registry/heartbeat.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  class SessionRegistry
+    # Keeps the leases of every session this process holds fresh: one thread per process renews
+    # them in their registry files every +interval+ seconds, so a sweeper in another process (a
+    # second Puma worker, a job worker sharing the registry directory) can tell a live session
+    # from one whose process died. The thread runs only while something is held.
+    #
+    # Fork-aware: a child process (Puma forks its workers) starts with nothing held and without the
+    # parent's thread - the parent's sessions are the parent's to renew.
+    module Heartbeat
+      DEFAULT_INTERVAL = DEFAULT_LEASE_TTL / 3.0
+
+      @mutex = Mutex.new
+
+      class << self
+        # @return [Numeric] seconds between renewals - keep it well below the sweeper's lease_ttl.
+        attr_writer :interval
+
+        def interval = @interval || DEFAULT_INTERVAL
+
+        def hold(registry, session_id)
+          synchronize do
+            (held[registry.path] ||= [registry, Set.new])[1] << session_id.to_s
+            @thread = Thread.new { beat_loop } unless @thread&.alive?
+          end
+        end
+
+        def release(registry, session_id)
+          synchronize do
+            ids = held.dig(registry.path, 1)
+            next unless ids
+
+            ids.delete(session_id.to_s)
+            held.delete(registry.path) if ids.empty?
+          end
+        end
+
+        # @return [Array<String>] the session ids this process holds in +registry+'s file.
+        def held_ids(registry)
+          synchronize { held.dig(registry.path, 1).to_a }
+        end
+
+        # Renews every held lease now.
+        def beat!(now: Time.now.to_i)
+          synchronize { held.values.map { |registry, ids| [registry, ids.to_a] } }
+            .each { |registry, ids| registry.renew(ids, at: now) }
+        end
+
+        private
+
+        def beat_loop
+          loop do
+            sleep interval
+            break if synchronize { held.empty? }
+
+            beat!
+          end
+        rescue StandardError => e
+          Bidi2pdf.logger.warn "session registry heartbeat stopped: #{e.message}"
+        end
+
+        def held
+          reset_after_fork
+          @held ||= {}
+        end
+
+        def reset_after_fork
+          return if @pid == Process.pid
+
+          @pid = Process.pid
+          @held = {}
+          @thread = nil
+        end
+
+        def synchronize(&)
+          @mutex.synchronize(&)
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/session_registry.rb

@@ -2,48 +2,94 @@
 
 require "digest"
 require "json"
+require "socket"
 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.
+  # Remembers which sessions bidi2pdf opened on a shared (remote) chromedriver, when, by which
+  # process, and whether that process is still alive - in a small JSON file per chromedriver URL - so
+  # a process started later, or a ChromeSweeper, can find and close the ones a process that died
+  # without a clean shutdown left behind (see SessionSweeper). chromedriver itself keeps a session
+  # until someone deletes it, and it drops any tag we could attach to one (a custom capability is
+  # accepted but echoed nowhere - checked against chromedriver 153), hence a file.
+  #
+  # Liveness is a lease: a session the process #hold s is renewed by its Heartbeat every
+  # Heartbeat.interval seconds. A session whose lease is fresh belongs to a live process - a render
+  # in flight or a warm spare - and no sweeper closes it; one whose lease ran out belongs to a dead
+  # process. #record alone writes an entry nobody renews.
   #
   # Everything here is best effort and fail-open: a directory that is not writable, a locked-out or
   # corrupt file only switches orphan tracking off for this process (one warning, one
   # +session_warmer.registry_unavailable.bidi2pdf+ notification) - rendering never depends on it.
   # The file is created 0600 and every change happens under an exclusive lock, so processes sharing
-  # the directory (a dev server, a job worker, a spec run) can record at the same time.
+  # the directory (Puma workers, a job worker, a spec run) can record at the same time.
   class SessionRegistry
     FILE_PREFIX = "bidi2pdf-sessions-"
+    # Seconds a lease stays fresh without a renewal.
+    DEFAULT_LEASE_TTL = 60
 
     attr_reader :path
 
+    def self.owner = "#{Socket.gethostname}:#{Process.pid}"
+
     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.
+    # Records a session the caller opened and keeps its lease fresh while this process lives.
+    def hold(session_id)
+      return false if session_id.nil?
+
+      recorded = record(session_id)
+      Heartbeat.hold(self, session_id)
+      recorded
+    end
+
+    # Stops renewing the lease but keeps the entry - for a session this process could not close, so
+    # a sweeper takes it once the lease ran out.
+    def release(session_id)
+      Heartbeat.release(self, session_id) unless session_id.nil?
+    end
+
+    # Writes an entry, leased from +created_at+ on but not renewed (see #hold).
     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 }
+      update do |entries|
+        entries[session_id.to_s] = { "created_at" => created_at.to_i, "renewed_at" => created_at.to_i, "owner" => self.class.owner }
+      end
     end
 
     # Forgets a session the caller closed itself (or found gone).
     def forget(session_id)
       return false if session_id.nil?
 
+      release(session_id)
       update { |entries| entries.delete(session_id.to_s) }
     end
 
+    # Renews the leases of +session_ids+ that are still recorded.
+    def renew(session_ids, at: Time.now.to_i)
+      update do |entries|
+        session_ids.each { |id| entries[id]["renewed_at"] = at.to_i if entries.key?(id) }
+      end
+    end
+
+    # Every recorded session: { id => opened at (epoch seconds) }.
+    def recorded
+      read.transform_values { |entry| entry["created_at"] }
+    end
+
+    # The recorded session ids whose lease was renewed within +ttl+ seconds before +now+ - sessions
+    # of a live process.
+    def leased(now: Time.now.to_i, ttl: DEFAULT_LEASE_TTL)
+      read.select { |_, entry| entry["renewed_at"].to_i >= now - ttl }.keys
+    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
+      recorded.select { |_, created_at| created_at <= cutoff }.keys
     end
 
     private
@@ -76,16 +122,23 @@ module Bidi2pdf
       false
     end
 
-    # A corrupt or foreign file counts as empty rather than as an error.
+    # A corrupt or foreign file counts as empty rather than as an error; an entry of the first
+    # format (just the creation time) has no lease.
     def parse(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) }
+      data.filter_map { |id, entry| [id, normalize(entry)] if id.is_a?(String) && normalize(entry) }.to_h
     rescue JSON::ParserError
       {}
     end
 
+    def normalize(entry)
+      return { "created_at" => entry } if entry.is_a?(Integer)
+
+      entry if entry.is_a?(Hash) && entry["created_at"].is_a?(Integer)
+    end
+
     def unavailable!(error)
       return if @warned
 
@@ -95,3 +148,5 @@ module Bidi2pdf
     end
   end
 end
+
+require_relative "session_registry/heartbeat"

data/lib/bidi2pdf/session_sweeper.rb

@@ -9,7 +9,8 @@ module Bidi2pdf
   # 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.
+  # are, and neither is one whose lease a live process keeps renewing (SessionRegistry#hold). A
+  # recorded session that is already gone ("invalid session id" / 404) is just forgotten.
   # Fail-open: any error is logged and ends the sweep; it never raises.
   class SessionSweeper
     # @param session_url [String] the chromedriver's new-session URL (".../session").
@@ -25,7 +26,8 @@ module Bidi2pdf
     #
     # @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) }
+      leftovers = @registry.recorded_before(now - older_than) - @registry.leased(now: now)
+      closed = leftovers.count { |id| closed_now?(id) }
       report(closed)
       closed
     rescue StandardError => e

data/lib/bidi2pdf/session_warmer.rb

@@ -61,6 +61,13 @@ module Bidi2pdf
       #   Dir.tmpdir. Every process that should clean up after the others must share it.
       attr_accessor :registry_dir
 
+      # @return [Hash, nil] Options for a ChromeSweeper on the remote chromedriver (+scope+,
+      #   +orphan_age+, +min_age+, +unresponsive_checks+, +max_sessions+, +pids_limit+, +interval+,
+      #   ...), or +nil+ (default) for none. This warmer's own sessions are never touched by it; with
+      #   an +interval+ it sweeps in the background, and a session that fails to start triggers one
+      #   sweep and one retry. Remote mode only.
+      attr_accessor :sweeper
+
       DEFAULT_MAX_IDLE_AGE = 300
 
       def initialize
@@ -72,6 +79,7 @@ module Bidi2pdf
         @max_idle_age = DEFAULT_MAX_IDLE_AGE
         @orphan_age = :auto
         @registry_dir = nil
+        @sweeper = nil
       end
 
       # The orphan age in seconds, or nil when the sweep is off (also when +:auto+ has no
@@ -85,6 +93,7 @@ module Bidi2pdf
         validate_size!
         validate_max_idle_age!
         validate_orphan_age!
+        validate_sweeper!
       end
 
       private
@@ -106,6 +115,12 @@ module Bidi2pdf
 
         raise ArgumentError, "orphan_age must be :auto, nil or a positive number of seconds, got #{orphan_age.inspect}"
       end
+
+      def validate_sweeper!
+        return if sweeper.nil? || sweeper.is_a?(Hash)
+
+        raise ArgumentError, "sweeper must be nil or a Hash of ChromeSweeper options, got #{sweeper.inspect}"
+      end
     end
 
     class << self
@@ -166,6 +181,12 @@ module Bidi2pdf
         instance.with_tab(&)
       end
 
+      # Sweeps the remote chromedriver with the configured sweeper; nil when there is none (or no
+      # warmer yet - this never creates one).
+      def sweep!(reason: :manual)
+        @instance&.sweep!(reason: reason)
+      end
+
       # Retires every currently-warm spare and resets the singleton.
       def shutdown
         @instance&.shutdown
@@ -207,10 +228,19 @@ module Bidi2pdf
       @warming = 0
       @shutdown = false
       @reaper_wakeup = Thread::Queue.new
+      @own_sessions = []
       @registry = build_registry
       sweep_leftovers
+      @sweeper = build_sweeper
       prewarm
-      @reaper = Thread.new { reap_loop } if @config.max_idle_age
+      start_background_work
+    end
+
+    # Sweeps the remote chromedriver now - for an application that suspects leaked sessions.
+    #
+    # @return [ChromeSweeper::Result, nil] nil when no sweeper is configured.
+    def sweep!(reason: :manual)
+      @sweeper&.sweep!(reason: reason)
     end
 
     # Checks out a slot, creates an isolated UserContext/Window/Tab for one render, yields the tab,
@@ -246,6 +276,7 @@ module Bidi2pdf
 
       @reaper_wakeup << :stop
       @reaper&.join
+      @sweeper&.stop
       threads.each(&:join)
       spares.each { |slot| retire(slot) }
     end
@@ -263,19 +294,47 @@ module Bidi2pdf
     end
 
     def create_slot
-      @slot_factory.call.tap { |slot| @registry&.record(session_id_of(slot)) }
+      slot = new_slot
+      id = session_id_of(slot)
+      @registry&.hold(id)
+      @mutex.synchronize { @own_sessions << id } if id
+      slot
+    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.
+    def new_slot
+      @slot_factory.call
+    rescue Bidi2pdf::SessionNotStartedError
+      raise unless @sweeper
+
+      @sweeper.sweep!(reason: :create_failed, pressure: true)
+      @slot_factory.call
+    end
+
+    def start_background_work
+      @reaper = Thread.new { reap_loop } if @config.max_idle_age
+      @sweeper.start if @sweeper&.interval
+    end
+
+    def build_sweeper
+      return unless @config.remote_browser_url && @config.sweeper
+
+      options = { registry: @registry }.merge(@config.sweeper)
+      Bidi2pdf::ChromeSweeper.new(@config.remote_browser_url, own_sessions: -> { @mutex.synchronize { @own_sessions.dup } }, **options)
     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.
+    # Remote mode with an orphan age or a sweeper: sessions are recorded, so a later start (or the
+    # sweeper, whose default scope is :recorded) can close the ones this process leaves behind if it
+    # dies uncleanly. The start-up sweep itself needs the orphan age - see #sweep_leftovers.
     def build_registry
-      return unless @config.remote_browser_url && @config.effective_orphan_age
+      return unless @config.remote_browser_url && (@config.effective_orphan_age || @config.sweeper)
 
       Bidi2pdf::SessionRegistry.new(@config.remote_browser_url, dir: @config.registry_dir)
     end
 
     def sweep_leftovers
-      return unless @registry
+      return unless @registry && @config.effective_orphan_age
 
       Bidi2pdf::SessionSweeper.new(@config.remote_browser_url, @registry).sweep(older_than: @config.effective_orphan_age)
     end
@@ -417,7 +476,9 @@ module Bidi2pdf
     # 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))
+      id = session_id_of(slot)
+      @registry&.forget(id)
+      @mutex.synchronize { @own_sessions.delete(id) }
     end
 
     def safe_close(label, &)

data/lib/bidi2pdf/version.rb

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

data/lib/bidi2pdf.rb

@@ -12,6 +12,8 @@ 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/chromedriver_api"
+require_relative "bidi2pdf/chrome_sweeper"
 require_relative "bidi2pdf/session_warmer"
 require_relative "bidi2pdf/verbose_logger"
 

data/sig/bidi2pdf/bidi/commands/browsing_context_get_tree.rbs

@@ -0,0 +1,12 @@
+module Bidi2pdf
+  module Bidi
+    module Commands
+      # browsingContext.getTree - the session's top-level browsing contexts (tabs/windows).
+      class BrowsingContextGetTree
+        include Base
+
+        def method_name: () -> "browsingContext.getTree"
+      end
+    end
+  end
+end

data/sig/bidi2pdf/bidi/commands/cdp_send_command.rbs

@@ -0,0 +1,23 @@
+module Bidi2pdf
+  module Bidi
+    module Commands
+      # goog:cdp.sendCommand - chromedriver's BiDi extension that runs one Chrome DevTools Protocol
+      # command; without a +session+ it runs at browser level (e.g. SystemInfo.getProcessInfo).
+      class CdpSendCommand
+        @cdp_method: untyped
+
+        @cdp_params: untyped
+
+        @session: untyped
+
+        include Base
+
+        def initialize: (method: untyped, ?params: ::Hash[untyped, untyped], ?session: untyped?) -> void
+
+        def params: () -> untyped
+
+        def method_name: () -> "goog:cdp.sendCommand"
+      end
+    end
+  end
+end

data/sig/bidi2pdf/bidi/session.rbs

@@ -27,6 +27,8 @@ module Bidi2pdf
 
       @chrome_args: untyped
 
+      @registry: untyped
+
       @client: untyped
 
       @browser: untyped
@@ -59,7 +61,10 @@ module Bidi2pdf
       # @param [String] session_url The URL for the session.
       # @param [Boolean] headless Whether to run the browser in headless mode. Defaults to true.
       # @param [Array<String>] chrome_args Additional Chrome arguments. Defaults to predefined arguments.
-      def initialize: (session_url: untyped, ?headless: bool, ?chrome_args: untyped) -> void
+      # @param [Bidi2pdf::SessionRegistry, nil] registry Records the session on a shared (remote)
+      #   chromedriver while it is open, so a sweep can close it if this process dies without
+      #   closing it (ChromeSweeper, SessionSweeper). nil records nothing.
+      def initialize: (session_url: untyped, ?headless: bool, ?chrome_args: untyped, ?registry: untyped?) -> void
 
       # Starts the session and initializes the client.
       #
@@ -76,8 +81,8 @@ module Bidi2pdf
       # @return [Bidi2pdf::Bidi::Browser] The browser instance.
       def browser: () -> untyped
 
-      # Closes the session and cleans up resources.
-      # rubocop:disable Metrics/AbcSize
+      # Closes the session and cleans up resources: BiDi +session.end+ first, and when Chrome does not
+      # answer that (a tab stuck in a loop), chromedriver's +DELETE /session/{id}+.
       def close: () -> untyped
 
       # Retrieves user contexts for the session.
@@ -164,6 +169,17 @@ module Bidi2pdf
       # @raise [SessionNotStartedError] If the session could not be started.
       def handle_error: (untyped value) -> (nil | untyped)
 
+      def end_via_bidi: () -> untyped
+
+      def record_session: (untyped id) -> untyped
+
+      # The BiDi session.end got no answer - typically a Chrome that hangs or crashed. chromedriver
+      # still ends the session (and kills its Chrome) on an HTTP DELETE, so a hung Chrome does not
+      # outlive this process. Only for a session this object created over HTTP (it knows the id).
+      #
+      # @return [Boolean] true when the session is gone.
+      def delete_via_chromedriver: () -> untyped
+
       # Cleans up resources associated with the session.
       def cleanup: () -> untyped
     end

data/sig/bidi2pdf/chrome_sweeper/inspector.rbs

@@ -0,0 +1,61 @@
+module Bidi2pdf
+  class ChromeSweeper
+    # Looks at one session on a chromedriver from the outside: attaches a second BiDi connection to
+    # its +webSocketUrl+ (chromedriver allows that for any session), asks for the tab tree, the first
+    # tab's +performance.timeOrigin+ (Chrome keeps no session start time anywhere - the first tab is
+    # created with the session, so its time origin is the session's age to within a few hundred ms)
+    # and the renderer CPU times (CDP +SystemInfo.getProcessInfo+ through +goog:cdp.sendCommand+).
+    #
+    # Read-only, and never reads page content: tab URLs are counted, not returned or logged (a
+    # +data:+ URL carries the whole rendered document). Closes its own connection every time.
+    class Inspector
+      @timeout: untyped
+
+      @clock: untyped
+
+      @client_factory: untyped
+
+      # @!attribute age [Float, nil] seconds since the session started, nil when nothing tells.
+      # @!attribute source [Symbol] :registry, :tab or :unknown - where +age+ comes from.
+      # @!attribute responsive [Boolean] whether the session answered the checks.
+      # @!attribute cpu_times [Hash{Integer => Float}] renderer pid => CPU seconds.
+      # @!attribute live [Boolean] a live process holds its lease (never inspected, never closed).
+      SessionInfo: untyped
+
+      DEFAULT_TIMEOUT: 5
+
+      # @param clock [#call] epoch seconds as a Float.
+      # @param client_factory [#call] ws_url -> a started, open Bidi::Client; injectable for tests.
+      def initialize: (?timeout: untyped, ?clock: untyped, ?client_factory: untyped?) -> void
+
+      # @param entry [ChromedriverApi::Entry]
+      # @param recorded_at [Numeric, nil] epoch seconds the registry has for it; wins over the tab.
+      # @return [SessionInfo]
+      def examine: (untyped entry, ?recorded_at: untyped?) -> untyped
+
+      private
+
+      def probe: (untyped client, untyped entry, untyped recorded_at) -> untyped
+
+      def tree: (untyped client) -> untyped
+
+      # A tab stuck in an endless loop never evaluates anything - nil then.
+      def time_origin: (untyped client, untyped context) -> untyped
+
+      # On a freshly attached connection the first command to a session - and, seen once in the
+      # acceptance run, to a tab - can time out although the session is healthy (chromedriver
+      # 153/154); the second one answers. Only a second timeout counts.
+      def once_more_on_timeout: () { () -> untyped } -> untyped
+
+      def cpu_times: (untyped client) -> untyped
+
+      def age_of: (untyped recorded_at, untyped origin) -> (::Array[untyped | :registry] | ::Array[untyped | :tab] | ::Array[nil | :unknown])
+
+      def unreachable: (untyped entry, untyped recorded_at) -> untyped
+
+      def command: (untyped client, untyped cmd) -> untyped
+
+      def connect: (untyped ws_url) -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/chrome_sweeper/settings.rbs

@@ -0,0 +1,34 @@
+module Bidi2pdf
+  class ChromeSweeper
+    SCOPES: ::Array[:recorded | :all]
+
+    DEFAULT_ORPHAN_AGE: 600
+
+    DEFAULT_MIN_AGE: 60
+
+    DEFAULT_UNRESPONSIVE_CHECKS: 2
+
+    DEFAULT_PIDS_BUDGET: ::Float
+
+    DEFAULT_THREADS_PER_SESSION: 110
+
+    DEFAULT_LEASE_TTL: untyped
+
+    # What a ChromeSweeper closes and when - validated on construction; an unknown setting raises
+    # ArgumentError.
+    #
+    # @!attribute scope [Symbol] :recorded (sessions a SessionRegistry knows) or :all.
+    # @!attribute orphan_age [Numeric, nil] close sessions older than this; nil turns the rule off.
+    # @!attribute min_age [Numeric] never close a session younger than this.
+    # @!attribute unresponsive_checks [Integer, nil] close after this many failed checks in a row.
+    # @!attribute max_sessions [Integer, Symbol, nil] the limit; +:auto+ derives it from pids_limit.
+    # @!attribute pids_limit [Integer, nil] the chromedriver container's pids limit, for +:auto+.
+    # @!attribute pids_budget [Float] share of +pids_limit+ Chrome sessions may use.
+    # @!attribute threads_per_session [Integer] threads (Docker counts them as pids) of one session.
+    # @!attribute interval [Numeric, nil] seconds between sweeps of ChromeSweeper#start's thread.
+    # @!attribute dry_run [Boolean] report what would be closed, close nothing.
+    # @!attribute lease_ttl [Numeric] a recorded session renewed within this many seconds belongs to
+    #   a live process and is never closed (SessionRegistry#hold).
+    Settings: untyped
+  end
+end