bidi2pdf 0.1.18 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa0fc469533226ce79d16bb401f4c47093dda42d4a68af67453fab79e086ad65
-  data.tar.gz: 9e4a1176ad42c03ced1544dcb9022a3dfe7d2663b0d8960f41bea863d3b0e788
+  metadata.gz: 60f338197fa95b778df1e96b3cb64c899e49c0a90b22ef9577b51f1a2eb85657
+  data.tar.gz: 13cded6812c061d65d0ac42579c29d5614007b08056094557b71902d347d6682
 SHA512:
-  metadata.gz: ddd7621c394b454a1df5b6071f474b1bd8699a4de4086e47c7185b01df66476ccad28d7e843b17e79aebf198489053bc237c345a3f638fb4e25e907aa4dc04f1
-  data.tar.gz: 134e15de59f8d5d7044be15308b1490988bc7eddd0134a9de05feed3accf3d56c52818125da49d36ad91263f6d16d8e58dc6549c85f5897316e9dfab7e60fb73
+  metadata.gz: c26da1531bd782b7e858eae98a53d3ec802f82f870b7649bcd40750dce747232ef2cb317a9881241e4ae49a08d70552be7e93923e84aad3837cd4dc1ce218359
+  data.tar.gz: 62ee4b751910b2631698797b38d91e2787f37d053d52b5af0e372fe5f76dcb27b06a10bcff43a630208916e7afadd8fee650877dfc2c6acbbfaa07814e0de025

data/CHANGELOG.md

@@ -8,10 +8,19 @@ 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.18..HEAD
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.19..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [0.1.19] - 2026-09-30
+
+### 🐛 Fixed
+- Keep lease times to the fraction of a second
+- Let every lease carry its own TTL
+
+### 🔄 Changed
+- Merge pull request #149 from dieter-medium/feat/lease-expiry
+
 ## [0.1.18] - 2026-09-30
 
 ### 🐛 Fixed
@@ -514,7 +523,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.18..HEAD)
+- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.19..HEAD)
+- [0.1.19](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.18..v0.1.19)
 - [0.1.18](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.17..v0.1.18)
 - [0.1.17](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.16..v0.1.17)
 - [0.1.16](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.15..v0.1.16)

data/README.md

@@ -572,7 +572,8 @@ Bidi2pdf::SessionWarmer.shutdown
 | `remote_browser_url` | `nil`                 | Connect each slot to a remote chromedriver instead of starting a local one.                               |
 | `orphan_age`         | `:auto`               | Remote only: on start, close sessions other warmers left behind older than this (`:auto` = 2 × `max_idle_age`, `nil` = off). |
 | `registry_dir`       | `Dir.tmpdir`          | Where the session registry file lives - every process that should clean up after the others must share it. |
-| `sweeper`            | `nil`                 | Remote only: settings for a [`ChromeSweeper`](#leaked-chrome-sessions-bidi2pdfchromesweeper) on the same chromedriver, e.g. `{ scope: :all, max_sessions: :auto, pids_limit: 1024, interval: 60 }`. The warmer's own sessions are never touched; `Bidi2pdf::SessionWarmer.sweep!` sweeps on demand. With a sweeper the warmer records its sessions even when `orphan_age` is `nil`. |
+| `sweeper`            | `nil`                 | Remote only: settings for a [`ChromeSweeper`](#leaked-chrome-sessions-bidi2pdfchromesweeper) on the same chromedriver, e.g. `{ scope: :all, max_sessions: :auto, pids_limit: 1024, interval: 60 }`. The warmer's own sessions are never touched; `Bidi2pdf::SessionWarmer.sweep!` sweeps on demand. |
+| `retry_refused_sessions` | `true`         | With a `sweeper`: when chromedriver refuses a new session, sweep under pressure and try once more. `false` leaves it to the caller. |
 
 #### Leftover sessions on a shared chromedriver
 
@@ -634,9 +635,11 @@ those, it closes nothing more and reports `limit_exceeded`. A session is closed
 **Live sessions of other processes (leases).** Several processes often share one chromedriver - Puma
 workers, a job worker - and each has renders in flight and warm spares the others know nothing
 about. So every session bidi2pdf opens is recorded in the registry with a lease, and a heartbeat
-thread in the owning process renews it every 20 s while the session is open. A session whose lease
-is younger than `lease_ttl` belongs to a live process: no sweeper in any process closes it, and it
-is not even inspected. When the process dies - killed, crashed, OOM - the lease runs out and the
+thread in the owning process renews it every 20 s (`SessionRegistry::Heartbeat.interval`) while the
+session is open. Every lease carries its own TTL - three heartbeats of the process that wrote it -
+so a sweeper never has to guess how often another process renews. A session whose lease is still
+fresh belongs to a live process: no sweeper in any process closes it, and it is not even inspected.
+The warmer leases its sessions in remote mode too, with or without a sweeper. When the process dies - killed, crashed, OOM - the lease runs out and the
 session becomes a leftover like any other. Only processes that share the registry directory see
 each other's leases: give job workers in another container the same `registry_dir` on a shared
 volume. Sessions other tools opened have no lease; under `scope: :all` only `min_age` protects them.
@@ -664,7 +667,7 @@ session is refused.
 | `dry_run`             | `false`     | Report what would be closed, close nothing.                                                                  |
 | `registry_dir`        | `Dir.tmpdir`| The registry to read and update - same meaning as the warmer's setting.                                      |
 | `own_sessions`        | `-> { [] }` | A callable returning the caller's live session ids; they are never touched.                                  |
-| `lease_ttl`           | `60`        | A recorded session renewed within this many seconds belongs to a live process and is never touched.         |
+| `lease_ttl`           | `60`        | Only for registry entries written by bidi2pdf 0.1.18, which carry no TTL of their own: renewed within this many seconds counts as live. |
 
 How it tells a session's age: chromedriver's `GET /sessions` lists every session but no start time,
 and Chrome keeps none either. So the sweeper uses the registry time when there is one and otherwise

data/lib/bidi2pdf/chrome_sweeper/settings.rb

@@ -23,8 +23,9 @@ module Bidi2pdf
     # @!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).
+    # @!attribute lease_ttl [Numeric] for registry entries without a TTL of their own (written by
+    #   bidi2pdf 0.1.18): renewed within this many seconds means a live process holds it. Entries
+    #   written since carry the TTL their owner's heartbeat promises (SessionRegistry#hold).
     Settings = Data.define(:scope, :orphan_age, :min_age, :unresponsive_checks, :max_sessions, :pids_limit,
                            :pids_budget, :threads_per_session, :interval, :dry_run, :lease_ttl) do
       # rubocop:disable-next Metrics/ParameterLists

data/lib/bidi2pdf/chrome_sweeper.rb

@@ -233,7 +233,7 @@ module Bidi2pdf
     end
 
     def live_sessions
-      @registry.leased(now: now.to_i, ttl: lease_ttl)
+      @registry.leased(now: now, ttl: lease_ttl)
     end
 
     def live_info(id, recorded_at)

data/lib/bidi2pdf/session_registry/heartbeat.rb

@@ -20,6 +20,9 @@ module Bidi2pdf
 
         def interval = @interval || DEFAULT_INTERVAL
 
+        # The TTL this process writes into its leases: three missed renewals and it is taken for dead.
+        def lease_ttl = interval * 3
+
         def hold(registry, session_id)
           synchronize do
             (held[registry.path] ||= [registry, Set.new])[1] << session_id.to_s
@@ -43,9 +46,9 @@ module Bidi2pdf
         end
 
         # Renews every held lease now.
-        def beat!(now: Time.now.to_i)
+        def beat!(now: Time.now.to_f)
           synchronize { held.values.map { |registry, ids| [registry, ids.to_a] } }
-            .each { |registry, ids| registry.renew(ids, at: now) }
+            .each { |registry, ids| registry.renew(ids, at: now, ttl: lease_ttl) }
         end
 
         private

data/lib/bidi2pdf/session_registry.rb

@@ -14,8 +14,10 @@ module Bidi2pdf
   # 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
+  # Heartbeat.interval seconds, and every entry carries its own TTL - the time the owner promises to
+  # renew it within (three heartbeats) - so a sweeper in another process never has to guess how
+  # often that owner renews. 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
@@ -25,7 +27,8 @@ module Bidi2pdf
   # 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.
+    # Seconds a lease stays fresh without a renewal when its entry carries no TTL of its own (written
+    # by bidi2pdf 0.1.18) - matches that version's fixed 20 s heartbeat.
     DEFAULT_LEASE_TTL = 60
 
     attr_reader :path
@@ -41,7 +44,7 @@ module Bidi2pdf
     def hold(session_id)
       return false if session_id.nil?
 
-      recorded = record(session_id)
+      recorded = record(session_id, ttl: Heartbeat.lease_ttl)
       Heartbeat.hold(self, session_id)
       recorded
     end
@@ -52,12 +55,15 @@ module Bidi2pdf
       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)
+    # Writes an entry, leased from +created_at+ on for +ttl+ seconds (nil: the reader's default) but
+    # not renewed (see #hold).
+    # Times are stored as fractions of a second: a whole-second timestamp could cost a short lease
+    # (0.5 s heartbeats: 1.5 s) up to a second of its life. Entries of whole seconds still read.
+    def record(session_id, created_at: Time.now.to_f, ttl: nil)
       return false if session_id.nil?
 
       update do |entries|
-        entries[session_id.to_s] = { "created_at" => created_at.to_i, "renewed_at" => created_at.to_i, "owner" => self.class.owner }
+        entries[session_id.to_s] = { "created_at" => created_at.to_f, "renewed_at" => created_at.to_f, "ttl" => ttl, "owner" => self.class.owner }.compact
       end
     end
 
@@ -69,10 +75,13 @@ module Bidi2pdf
       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)
+    # Renews the leases of +session_ids+ that are still recorded, for +ttl+ seconds when given.
+    def renew(session_ids, at: Time.now.to_f, ttl: nil)
       update do |entries|
-        session_ids.each { |id| entries[id]["renewed_at"] = at.to_i if entries.key?(id) }
+        session_ids.select { |id| entries.key?(id) }.each do |id|
+          entries[id]["renewed_at"] = at.to_f
+          entries[id]["ttl"] = ttl if ttl
+        end
       end
     end
 
@@ -81,10 +90,10 @@ module Bidi2pdf
       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
+    # The recorded session ids whose lease is still fresh at +now+ - sessions of a live process. An
+    # entry's own TTL wins; +ttl+ is only for entries without one.
+    def leased(now: Time.now.to_f, ttl: DEFAULT_LEASE_TTL)
+      read.select { |_, entry| entry["renewed_at"].to_f + (entry["ttl"] || ttl) >= now }.keys
     end
 
     # The recorded session ids opened at or before +cutoff+ (epoch seconds).
@@ -134,9 +143,9 @@ module Bidi2pdf
     end
 
     def normalize(entry)
-      return { "created_at" => entry } if entry.is_a?(Integer)
+      return { "created_at" => entry } if entry.is_a?(Numeric)
 
-      entry if entry.is_a?(Hash) && entry["created_at"].is_a?(Integer)
+      entry if entry.is_a?(Hash) && entry["created_at"].is_a?(Numeric)
     end
 
     def unavailable!(error)

data/lib/bidi2pdf/session_sweeper.rb

@@ -25,7 +25,7 @@ module Bidi2pdf
     # 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)
+    def sweep(older_than:, now: Time.now.to_f)
       leftovers = @registry.recorded_before(now - older_than) - @registry.leased(now: now)
       closed = leftovers.count { |id| closed_now?(id) }
       report(closed)

data/lib/bidi2pdf/session_warmer.rb

@@ -65,9 +65,13 @@ module Bidi2pdf
       #   +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.
+      #   pressure sweep and one retry (see +retry_refused_sessions+). Remote mode only.
       attr_accessor :sweeper
 
+      # @return [Boolean] With a +sweeper+: when chromedriver refuses a new session, sweep under
+      #   pressure and try once more. Default true; false leaves a refused session to the caller.
+      attr_accessor :retry_refused_sessions
+
       DEFAULT_MAX_IDLE_AGE = 300
 
       def initialize
@@ -80,6 +84,7 @@ module Bidi2pdf
         @orphan_age = :auto
         @registry_dir = nil
         @sweeper = nil
+        @retry_refused_sessions = true
       end
 
       # The orphan age in seconds, or nil when the sweep is off (also when +:auto+ has no
@@ -306,7 +311,7 @@ module Bidi2pdf
     def new_slot
       @slot_factory.call
     rescue Bidi2pdf::SessionNotStartedError
-      raise unless @sweeper
+      raise unless @sweeper && @config.retry_refused_sessions
 
       @sweeper.sweep!(reason: :create_failed, pressure: true)
       @slot_factory.call
@@ -324,11 +329,12 @@ module Bidi2pdf
       Bidi2pdf::ChromeSweeper.new(@config.remote_browser_url, own_sessions: -> { @mutex.synchronize { @own_sessions.dup } }, **options)
     end
 
-    # 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.
+    # Remote mode: every session is leased, so no sweeper in any process takes a warm spare or a
+    # render in flight, and a later start (or a sweeper) 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 || @config.sweeper)
+      return unless @config.remote_browser_url
 
       Bidi2pdf::SessionRegistry.new(@config.remote_browser_url, dir: @config.registry_dir)
     end

data/lib/bidi2pdf/version.rb

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

data/sig/bidi2pdf/chrome_sweeper/settings.rbs

@@ -27,8 +27,9 @@ module Bidi2pdf
     # @!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).
+    # @!attribute lease_ttl [Numeric] for registry entries without a TTL of their own (written by
+    #   bidi2pdf 0.1.18): renewed within this many seconds means a live process holds it. Entries
+    #   written since carry the TTL their owner's heartbeat promises (SessionRegistry#hold).
     Settings: untyped
   end
 end

data/sig/bidi2pdf/session_registry/heartbeat.rbs

@@ -23,6 +23,9 @@ module Bidi2pdf
 
       def self.interval: () -> untyped
 
+      # The TTL this process writes into its leases: three missed renewals and it is taken for dead.
+      def self.lease_ttl: () -> untyped
+
       def self.hold: (untyped registry, untyped session_id) -> untyped
 
       def self.release: (untyped registry, untyped session_id) -> untyped

data/sig/bidi2pdf/session_registry.rbs

@@ -7,8 +7,10 @@ module Bidi2pdf
   # 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
+  # Heartbeat.interval seconds, and every entry carries its own TTL - the time the owner promises to
+  # renew it within (three heartbeats) - so a sweeper in another process never has to guess how
+  # often that owner renews. 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
@@ -23,7 +25,8 @@ module Bidi2pdf
 
     FILE_PREFIX: "bidi2pdf-sessions-"
 
-    # Seconds a lease stays fresh without a renewal.
+    # Seconds a lease stays fresh without a renewal when its entry carries no TTL of its own (written
+    # by bidi2pdf 0.1.18) - matches that version's fixed 20 s heartbeat.
     DEFAULT_LEASE_TTL: 60
 
     attr_reader path: untyped
@@ -39,20 +42,23 @@ module Bidi2pdf
     # a sweeper takes it once the lease ran out.
     def release: (untyped session_id) -> (untyped | nil)
 
-    # Writes an entry, leased from +created_at+ on but not renewed (see #hold).
-    def record: (untyped session_id, ?created_at: untyped) -> (false | untyped)
+    # Writes an entry, leased from +created_at+ on for +ttl+ seconds (nil: the reader's default) but
+    # not renewed (see #hold).
+    # Times are stored as fractions of a second: a whole-second timestamp could cost a short lease
+    # (0.5 s heartbeats: 1.5 s) up to a second of its life. Entries of whole seconds still read.
+    def record: (untyped session_id, ?created_at: untyped, ?ttl: untyped?) -> (false | untyped)
 
     # Forgets a session the caller closed itself (or found gone).
     def forget: (untyped session_id) -> (false | untyped)
 
-    # Renews the leases of +session_ids+ that are still recorded.
-    def renew: (untyped session_ids, ?at: untyped) -> untyped
+    # Renews the leases of +session_ids+ that are still recorded, for +ttl+ seconds when given.
+    def renew: (untyped session_ids, ?at: untyped, ?ttl: untyped?) -> untyped
 
     # Every recorded session: { id => opened at (epoch seconds) }.
     def recorded: () -> untyped
 
-    # The recorded session ids whose lease was renewed within +ttl+ seconds before +now+ - sessions
-    # of a live process.
+    # The recorded session ids whose lease is still fresh at +now+ - sessions of a live process. An
+    # entry's own TTL wins; +ttl+ is only for entries without one.
     def leased: (?now: untyped, ?ttl: untyped) -> untyped
 
     # The recorded session ids opened at or before +cutoff+ (epoch seconds).

data/sig/bidi2pdf/session_warmer.rbs

@@ -70,6 +70,8 @@ module Bidi2pdf
 
       @sweeper: untyped
 
+      @retry_refused_sessions: untyped
+
       # @return [Integer] Number of Chrome slots to keep pre-warmed.
       attr_accessor size: untyped
 
@@ -111,9 +113,13 @@ module Bidi2pdf
       #   +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.
+      #   pressure sweep and one retry (see +retry_refused_sessions+). Remote mode only.
       attr_accessor sweeper: untyped
 
+      # @return [Boolean] With a +sweeper+: when chromedriver refuses a new session, sweep under
+      #   pressure and try once more. Default true; false leaves a refused session to the caller.
+      attr_accessor retry_refused_sessions: untyped
+
       DEFAULT_MAX_IDLE_AGE: 300
 
       def initialize: () -> void
@@ -216,9 +222,10 @@ module Bidi2pdf
 
     def build_sweeper: () -> (nil | untyped)
 
-    # 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.
+    # Remote mode: every session is leased, so no sweeper in any process takes a warm spare or a
+    # render in flight, and a later start (or a sweeper) 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: () -> (nil | untyped)
 
     def sweep_leftovers: () -> (nil | untyped)

data/sig/bidi2pdf/version.rbs

@@ -1,3 +1,3 @@
 module Bidi2pdf
-  VERSION: "0.1.18"
+  VERSION: "0.1.19"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bidi2pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.18
+  version: 0.1.19
 platform: ruby
 authors:
 - Dieter S.