pgbus 0.18.2 → 0.19.1

data/lib/pgbus/process/worker.rb

@@ -37,7 +37,9 @@ module Pgbus
                      notify_retry_backoff: NOTIFY_RETRY_BASE_SECONDS,
                      started_at_monotonic: nil, wake_pipe: nil, read_ahead: nil,
                      recycle_limits: {}, capsule: nil, process: nil)
-        @queues = Array(queues)
+        # The worker's own list: eviction deletes from it, and the queues it is
+        # handed come from a configuration frozen by Pgbus.finalize! at boot.
+        @queues = Array(queues).dup
         @initial_queues = @queues.dup.freeze
         @wildcard = @queues.include?("*")
         @threads = threads
@@ -237,7 +239,7 @@ module Pgbus
         Pgbus.stopping = true
         @lifecycle.transition_to!(:stopped)
         @wake_signal.notify!
-        @pool.kill
+        ExecutionPools.terminate(@pool, grace: config.immediate_shutdown_grace)
       end
 
       WILDCARD_REFRESH_INTERVAL = 30 # seconds
@@ -834,6 +836,7 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Heartbeat.new(
           kind: "worker",
+          config: @config,
           # capsule/process lead: the dashboard's metadata cell truncates.
           metadata: {
             capsule: @capsule, process: @process,

data/lib/pgbus/recurring/scheduler.rb

@@ -7,24 +7,33 @@ module Pgbus
     class Scheduler
       include Process::SignalHandler
 
-      attr_reader :schedule, :config
+      attr_reader :schedule, :config, :deploy_runner
 
       def initialize(config: Pgbus.configuration)
         @config = config
         @schedule = Schedule.new(config: config)
+        # Deploy tasks (issue #536) ride this loop: the scheduler is already
+        # the one-per-deployment process, dedup'd across the overlap window.
+        @deploy_runner = Deploy::Runner.new(config: config) if config.deploy_tasks_enabled && config.deploy_tasks&.any?
         @shutting_down = false
         @last_runs = {}
         @loop_tick_at = Concurrent::AtomicReference.new(nil)
+        @deploy_error = nil
       end
 
+      # The order is load-bearing: the heartbeat registers this scheduler's row
+      # before it arms deploy tasks, so an old-revision scheduler in the
+      # overlap window sees it as lagging. A failed registration is logged and
+      # sync still runs; the new release's workers keep the old gate closed.
       def run
         setup_signals
         start_heartbeat
         sync_recurring_tasks
+        deploy_runner&.sync!
 
         Pgbus.logger.info do
           "[Pgbus] Scheduler started: #{schedule.tasks.size} recurring tasks, " \
-            "interval=#{config.recurring_schedule_interval}s"
+            "#{deploy_task_count} deploy tasks, interval=#{config.recurring_schedule_interval}s"
         end
 
         loop do
@@ -44,22 +53,12 @@ module Pgbus
       end
 
       def tick(now)
-        schedule.due_tasks(now).each do |task, run_at|
-          Pgbus::Instrumentation.instrument(
-            "pgbus.recurring.enqueue",
-            task: task.key,
-            class_name: task.class_name,
-            queue: task.queue_name,
-            run_at: run_at
-          ) do
-            schedule.enqueue_task(task, run_at: run_at)
-            @last_runs[task.key] = now
-          end
-        rescue StandardError => e
-          Pgbus.logger.error do
-            "[Pgbus] Error scheduling recurring task #{task.key}: #{e.class}: #{e.message}"
-          end
-        end
+        tick_recurring(now) if config.recurring_enabled
+        tick_deploy_tasks(now)
+      end
+
+      def deploy_task_count
+        deploy_runner&.task_count || 0
       end
 
       def last_run_at(key)
@@ -94,9 +93,43 @@ module Pgbus
 
       private
 
+      def tick_recurring(now)
+        schedule.due_tasks(now).each do |task, run_at|
+          Pgbus::Instrumentation.instrument(
+            "pgbus.recurring.enqueue",
+            task: task.key,
+            class_name: task.class_name,
+            queue: task.queue_name,
+            run_at: run_at
+          ) do
+            schedule.enqueue_task(task, run_at: run_at)
+            @last_runs[task.key] = now
+          end
+        rescue StandardError => e
+          Pgbus.logger.error do
+            "[Pgbus] Error scheduling recurring task #{task.key}: #{e.class}: #{e.message}"
+          end
+        end
+      end
+
+      # A persistent failure (the tables missing, the database down) is logged
+      # and reported once per distinct error, then at debug, not every tick.
+      def tick_deploy_tasks(now)
+        deploy_runner&.tick(now)
+        @deploy_error = nil
+      rescue StandardError => e
+        signature = "#{e.class}: #{e.message}"
+        if signature == @deploy_error
+          Pgbus.logger.debug { "[Pgbus] Error running deploy tasks (repeated): #{signature}" }
+        else
+          @deploy_error = signature
+          ErrorReporter.report(e, { action: "deploy_tasks_tick" }) # logs at error itself
+        end
+      end
+
       def sync_recurring_tasks
         tasks = config.recurring_tasks
-        return if tasks.nil?
+        return if tasks.nil? || !config.recurring_enabled
 
         RecurringTask.sync_from_config!(tasks)
         Pgbus.logger.info { "[Pgbus] Synced #{tasks.size} recurring task(s) from configuration" }
@@ -116,8 +149,9 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Process::Heartbeat.new(
           kind: "scheduler",
+          config: @config,
           metadata: { pid: ::Process.pid, tasks: schedule.tasks.size, started_at: Time.now.to_f,
-                      supervisor_pid: ::Process.ppid },
+                      supervisor_pid: ::Process.ppid }.merge(deploy_runner ? { deploy_tasks: deploy_task_count } : {}),
           loop_tick_supplier: -> { @loop_tick_at.get }
         )
         @heartbeat.start

data/lib/pgbus/retry_backoff.rb

@@ -20,6 +20,9 @@ module Pgbus
     module JobMixin
       extend ActiveSupport::Concern
 
+      # Class-body macro: it runs while the job class loads (at boot, or under the
+      # autoloader's lock), stores a frozen Hash, and the reader only reads it.
+      # rubocop:disable-next ThreadSafety/ClassInstanceVariable
       class_methods do
         def pgbus_retry_backoff(base: nil, max: nil, jitter: nil)
           raise ArgumentError, "retry_backoff base must be > 0" if !base.nil? && (!base.is_a?(Numeric) || base <= 0)

data/lib/pgbus/shareable.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Deep-frozen, Ractor-shareable copies of plain data, for the settings
+  # Configuration#finalize! freezes at boot (issue #527).
+  module Shareable
+    # Leaves that are plain data. Modules and classes count too: they are
+    # shareable by nature.
+    LEAVES = [String, Symbol, Numeric, TrueClass, FalseClass, NilClass, Regexp, Module].freeze
+
+    module_function
+
+    # True when +value+ is plain data all the way down: the LEAVES, and Arrays,
+    # Sets, Ranges and default-less Hashes of them. A Proc, a Logger or any
+    # other object anywhere inside makes it false, and so does a collection
+    # that contains itself (+path+ holds the collections being walked), so
+    # finalizing leaves it as it is instead of recursing without end.
+    def data?(value, path = {}.compare_by_identity)
+      case value
+      when Array, Set, Hash, Range
+        return false if path.key?(value)
+
+        path[value] = true
+        begin
+          collection_data?(value, path)
+        ensure
+          path.delete(value)
+        end
+      else LEAVES.any? { |leaf| value.is_a?(leaf) }
+      end
+    end
+
+    def collection_data?(value, path)
+      case value
+      when Array, Set then value.all? { |item| data?(item, path) }
+      when Hash
+        value.default_proc.nil? && data?(value.default, path) && value.all? { |k, v| data?(k, path) && data?(v, path) }
+      else data?(value.begin, path) && data?(value.end, path)
+      end
+    end
+
+    # A deep-frozen copy of plain data (see data?), Ractor-shareable where the
+    # engine has Ractors. The caller's own objects are copied, never frozen in
+    # place.
+    def freeze_copy(value)
+      return ::Ractor.make_shareable(value, copy: true) if defined?(::Ractor) && ::Ractor.respond_to?(:make_shareable)
+
+      deep_freeze(value)
+    end
+
+    # The copy freeze_copy makes where the engine has no Ractor: everything
+    # data? accepts, a Hash's default and a Range's endpoints included.
+    def deep_freeze(value)
+      case value
+      when Array then value.map { |item| deep_freeze(item) }.freeze
+      when Set then value.to_set { |item| deep_freeze(item) }.freeze
+      when Hash then deep_freeze_hash(value)
+      when Range then Range.new(deep_freeze(value.begin), deep_freeze(value.end), value.exclude_end?).freeze
+      when String then value.frozen? ? value : value.dup.freeze
+      else value
+      end
+    end
+
+    def deep_freeze_hash(hash)
+      copy = hash.to_h { |k, v| [deep_freeze(k), deep_freeze(v)] }
+      copy.default = deep_freeze(hash.default)
+      copy.freeze
+    end
+  end
+end

data/lib/pgbus/streams/broadcastable_override.rb

@@ -56,6 +56,9 @@ module Pgbus
         end
       end
 
+      # broadcasts_to / broadcasts_refreshes_to are class-body macros: they write
+      # @pgbus_durable_streams while the model class loads, and it is only read after.
+      # rubocop:disable-next ThreadSafety/ClassInstanceVariable
       module ClassMethods
         def broadcasts_to(stream, durable: nil, inserts_by: :append, target: broadcast_target_default, **rendering)
           if durable.nil?

data/lib/pgbus/streams/presence.rb

@@ -77,11 +77,13 @@ module Pgbus
         # True when pgbus_presence_members has the seat columns (the
         # add_presence_seats migration ran). A true answer is kept for the
         # life of the process; a false one for SCHEMA_RECHECK_SECONDS.
+        #
+        # The answer is read and written under @schema_mutex only (issue
+        # #527). A successful probe is kept as above; a probe that raises is
+        # not, so the next call probes again.
         def seats_supported?
-          return @seats_supported if schema_answer_fresh?
-
           @schema_mutex.synchronize do
-            next @seats_supported if schema_answer_fresh?
+            next @seats_supported if schema_answer_fresh?(@seats_supported, @probed_at)
 
             rows = connection.exec_params(<<~SQL, [])
               SELECT 1 AS present FROM information_schema.columns
@@ -169,10 +171,7 @@ module Pgbus
 
         private
 
-        # Reads each ivar once: a concurrent reset_schema_cache! may nil them.
-        def schema_answer_fresh?
-          supported = @seats_supported
-          probed_at = @probed_at
+        def schema_answer_fresh?(supported, probed_at)
           return false if supported.nil? || probed_at.nil?
 
           supported || monotonic_now - probed_at < SCHEMA_RECHECK_SECONDS

data/lib/pgbus/streams.rb

@@ -33,38 +33,49 @@ module Pgbus
     # `message`. Broadcasts may override it with a typed name (issue #170).
     DEFAULT_SSE_EVENT = "turbo-stream"
 
-    # Process-wide registry of server-side audience filter predicates.
-    # Register filters at boot time via:
-    #   Pgbus::Streams.filters.register(:admin_only) { |user| user.admin? }
-    # See lib/pgbus/streams/filters.rb for the full API.
-    def self.filters
-      @filters ||= Filters.new
-    end
+    class << self
+      # Process-wide registry of server-side audience filter predicates.
+      # Register filters at boot time via:
+      #   Pgbus::Streams.filters.register(:admin_only) { |user| user.admin? }
+      # See lib/pgbus/streams/filters.rb for the full API.
+      #
+      # Process-wide publish-side coalescer for high-frequency broadcasts
+      # (issue #171); the flush re-enters the normal broadcast path so a
+      # coalesced frame is just a deferred ordinary broadcast.
+      #
+      # Both are built when this file loads, not by `||=` on first use: two
+      # first callers could each build a registry, and a filter registered on
+      # the one that lost was gone (issue #527). Replaced only by the resets.
+      attr_reader :filters, :coalescer
+
+      # Fresh filters registry. Used by tests; not intended for runtime.
+      def reset_filters!
+        @reset_lock.synchronize { @filters = Filters.new }
+      end
 
-    # Clears the filters registry. Used by tests; not intended for runtime.
-    def self.reset_filters!
-      @filters = nil
-    end
+      # Fresh coalescer. Used by tests; not intended for runtime.
+      def reset_coalescer!
+        @reset_lock.synchronize { @coalescer = build_coalescer }
+      end
 
-    # Process-wide publish-side coalescer for high-frequency broadcasts
-    # (issue #171). Lazily built; the flush re-enters the normal broadcast
-    # path so a coalesced frame is just a deferred ordinary broadcast.
-    def self.coalescer
-      # `target:` is part of the flush signature but unused here — it's only
-      # a coalescing key; the target is already encoded in the payload's
-      # turbo-stream tag. Absorbed via ** so it isn't a broadcast argument.
-      @coalescer ||= Coalescer.new(
-        flush: lambda do |stream_name:, payload:, opts:, **|
-          Pgbus.stream(stream_name).broadcast(payload, **opts)
-        end
-      )
-    end
+      private
 
-    # Clears the coalescer. Used by tests; not intended for runtime.
-    def self.reset_coalescer!
-      @coalescer = nil
+      def build_coalescer
+        # `target:` is part of the flush signature but unused here — it's only
+        # a coalescing key; the target is already encoded in the payload's
+        # turbo-stream tag. Absorbed via ** so it isn't a broadcast argument.
+        Coalescer.new(
+          flush: lambda do |stream_name:, payload:, opts:, **|
+            Pgbus.stream(stream_name).broadcast(payload, **opts)
+          end
+        )
+      end
     end
 
+    @reset_lock = Mutex.new
+    @filters = Filters.new
+    @coalescer = build_coalescer
+
     # A handle on a single logical stream. The name can be any string, an
     # object responding to `to_gid_param`, or an array of streamables (which
     # are joined with colons — turbo-rails-compatible).

data/lib/pgbus/testing.rb

@@ -71,6 +71,15 @@ module Pgbus
     # Eagerly initialize the store so concurrent access never races on creation.
     @store = EventStore.new
 
+    # The process-wide mode (`fake!` with no block). A module ivar under a lock
+    # built at load, not `Thread.main[]`: that reads the main thread's CURRENT
+    # fiber only, so a mode set inside a fiber (an Async task) or read while the
+    # main thread runs one was lost (issue #527). The block form stays
+    # `Thread.current[MODE_KEY]`, which is fiber-local on every Ruby: a `fake!`
+    # block inside one Async task must not leak to its siblings.
+    @mode_lock = Mutex.new
+    @default_mode = nil
+
     class << self
       def mode!(mode, &block)
         raise ArgumentError, "Unknown mode: #{mode}. Valid modes: #{MODES.join(", ")}" unless MODES.include?(mode)
@@ -78,7 +87,7 @@ module Pgbus
         # Record the mode BEFORE syncing streams: a StreamerLeakError raised
         # by the teardown must still leave the process in the requested mode.
         unless block
-          Thread.main[MODE_KEY] = mode
+          @mode_lock.synchronize { @default_mode = mode }
           sync_streams_test_mode!(mode)
           return
         end
@@ -90,12 +99,15 @@ module Pgbus
       ensure
         if block
           Thread.current[MODE_KEY] = old
-          sync_streams_test_mode!(old || :disabled)
+          # The mode in effect again: the outer block's, else the
+          # process-wide one (not :disabled, which would let the streamer
+          # into a fake-mode test's later SSE requests).
+          sync_streams_test_mode!(old || default_mode)
         end
       end
 
       def mode
-        Thread.current[MODE_KEY] || Thread.main[MODE_KEY] || :disabled
+        Thread.current[MODE_KEY] || default_mode
       end
 
       def fake!(&) = mode!(:fake, &)
@@ -110,6 +122,10 @@ module Pgbus
 
       private
 
+      def default_mode
+        @mode_lock.synchronize { @default_mode } || :disabled
+      end
+
       # When entering fake/inline mode, enable streams_test_mode to prevent
       # rack.hijack from spawning background threads that acquire DB
       # connections outside the test transaction (see issue #133). When

data/lib/pgbus/uniqueness.rb

@@ -52,6 +52,9 @@ module Pgbus
     VALID_STRATEGIES = %i[until_executed while_executing].freeze
     VALID_CONFLICTS = %i[reject discard log].freeze
 
+    # Class-body macro: it runs while the job class loads (at boot, or under the
+    # autoloader's lock), stores a frozen Hash, and the reader only reads it.
+    # rubocop:disable-next ThreadSafety/ClassInstanceVariable
     class_methods do
       def ensures_uniqueness(strategy: :until_executed, key: nil, on_conflict: :reject, **opts)
         # lock_ttl was validated and stored in message metadata but never read

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.18.2"
+  VERSION = "0.19.1"
 end

data/lib/pgbus/visibility_heartbeat.rb

@@ -45,7 +45,9 @@ module Pgbus
       extend ActiveSupport::Concern
 
       included do
-        class_attribute :pgbus_visibility_heartbeat_enabled, instance_writer: false, default: nil
+        # A per-class setting the job's own class body writes at load
+        # (`pgbus_visibility_heartbeat false`); jobs only read it while they run.
+        class_attribute :pgbus_visibility_heartbeat_enabled, instance_writer: false, default: nil # rubocop:disable ThreadSafety/ClassAndModuleAttributes
       end
 
       class_methods do
@@ -55,6 +57,14 @@ module Pgbus
       end
     end
 
+    # Built at load, never lazily: a `@mutex ||= Mutex.new` is itself a race in
+    # which two first callers each lock a Mutex of their own (issue #527). It
+    # guards @entries, @running, @thread and @pid, which are only touched inside
+    # #synchronize. A forked child can take it even when a parent thread held it
+    # at the fork: Ruby abandons a Mutex whose owner did not survive the fork.
+    @mutex = Mutex.new
+    @entries = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable -- only read or written inside #synchronize
+
     class << self
       # Track the message for the duration of the block.
       #
@@ -106,13 +116,13 @@ module Pgbus
       # can drive it.
       def tick!(now: monotonic_now, config: Pgbus.configuration)
         interval = config.effective_visibility_heartbeat_interval
-        due = synchronize { entries.values.select { |entry| now - entry.extended_at >= interval } }
+        due = synchronize { @entries.values.select { |entry| now - entry.extended_at >= interval } }
         due.each { |entry| extend!(entry, now: now, config: config) }
         due.size
       end
 
       def tracked_count
-        synchronize { entries.size }
+        synchronize { @entries.size }
       end
 
       # Stop the background thread. Tracked entries are kept: a job still
@@ -141,9 +151,20 @@ module Pgbus
 
       def register(entry, config)
         synchronize do
-          forget_parent_entries!
-          entries[key_for(entry)] = entry
-          ensure_thread(config)
+          # Entries registered before a fork belong to the parent's jobs; the
+          # thread did not survive the fork either.
+          unless @pid == ::Process.pid
+            @pid = ::Process.pid
+            @entries = {}
+            @running = false
+            @thread = nil
+          end
+          @entries[key_for(entry)] = entry
+          # Start the ticker once per process.
+          unless @running && @thread&.alive?
+            @running = true
+            @thread = start_ticker(config)
+          end
         end
       end
 
@@ -153,7 +174,7 @@ module Pgbus
       def unregister(entry)
         synchronize do
           key = key_for(entry)
-          entries.delete(key) if entries[key].equal?(entry)
+          @entries.delete(key) if @entries[key].equal?(entry)
         end
       end
 
@@ -186,31 +207,38 @@ module Pgbus
         end
       end
 
-      # Caller holds the mutex. Start the ticker once per process.
-      def ensure_thread(config)
-        return if @running && @thread&.alive?
+      # One ticker per process, owned by this module: #register starts it under
+      # the lock (at most one live thread, see @running/@thread) and #stop
+      # clears @running, wakes it and joins it; Worker#shutdown calls #stop.
+      def start_ticker(config)
+        thread = Thread.new { run_loop(config) } # rubocop:disable ThreadSafety/NewThread
+        thread.name = "pgbus-visibility-heartbeat"
+        thread
+      end
 
-        @running = true
-        @thread = Thread.new { run_loop(config) }
-        @thread.name = "pgbus-visibility-heartbeat"
+      # True while the calling thread is the ticker #register started last
+      # and #stop has not stopped it. A stopped ticker can wake after a
+      # #register has already started its successor; @running alone would be
+      # true again for it, and it would tick beside the new one.
+      def current_ticker?
+        synchronize { @running && @thread.equal?(Thread.current) }
       end
 
       def run_loop(config)
-        while @running
+        while current_ticker?
           # Half the interval keeps every extension inside [interval, 1.5 * interval]
           # of the previous one — at most half the visibility timeout.
           sleep([config.effective_visibility_heartbeat_interval / 2.0, 0.05].max)
-          break unless @running
+          break unless current_ticker?
 
           tick!(config: config)
         end
       rescue StandardError => e
         Pgbus.logger.error { "[Pgbus::VisibilityHeartbeat] ticker died: #{e.class}: #{e.message}" }
-        synchronize { @running = false }
+        # Only its own state: a stopped ticker must not stop its successor.
+        synchronize { @running = false if @thread.equal?(Thread.current) }
       end
 
-      # Entries registered before a fork belong to the parent's jobs; the
-      # thread did not survive the fork either.
       # A live holder keeps its semaphore from being swept, so `duration`
       # bounds heartbeat silence rather than run time. Its own rescue: a
       # failed touch must not cost the message its visibility extension.
@@ -236,29 +264,18 @@ module Pgbus
         end
       end
 
-      def forget_parent_entries!
-        return if @pid == ::Process.pid
-
-        @pid = ::Process.pid
-        @entries = {}
-        @running = false
-        @thread = nil
-      end
-
-      def entries
-        @entries ||= {}
-      end
-
       def registered?(entry)
-        synchronize { entries[key_for(entry)].equal?(entry) }
+        synchronize { @entries[key_for(entry)].equal?(entry) }
       end
 
       def key_for(entry)
         [entry.queue_name, entry.msg_id]
       end
 
-      def synchronize(&)
-        (@mutex ||= Mutex.new).synchronize(&)
+      # A literal block, not `(&)`: ThreadSafety/ClassInstanceVariable accepts
+      # @mutex as the receiver of a synchronize block only.
+      def synchronize
+        @mutex.synchronize { yield } # rubocop:disable Style/ExplicitBlockArgument
       end
 
       def monotonic_now

data/lib/pgbus/web/authentication.rb

@@ -9,8 +9,25 @@ module Pgbus
         before_action :authenticate_pgbus!
       end
 
+      # The "dashboard has no authentication" warning is logged once per
+      # process. Request threads check and set the flag under @warn_lock, so
+      # concurrent first requests cannot both log it (issue #527).
+      @warn_lock = Mutex.new
+      @auth_warned = false
+
       class << self
-        attr_accessor :auth_warned
+        def auth_warned
+          @warn_lock.synchronize { @auth_warned }
+        end
+
+        def auth_warned=(value)
+          @warn_lock.synchronize { @auth_warned = value }
+        end
+
+        # True for the one caller that flips the flag from false to true.
+        def claim_auth_warning!
+          @warn_lock.synchronize { @auth_warned ? false : (@auth_warned = true) }
+        end
       end
 
       # Default base controller — anything else means the app deliberately
@@ -40,13 +57,13 @@ module Pgbus
         # place; don't nag apps that gate the dashboard via a custom controller
         # (they had to set a redundant web_auth lambda just to silence us — #334).
         return unless default_base_controller?
+        return unless Pgbus::Web::Authentication.claim_auth_warning!
 
         Pgbus.logger.warn do
           "[Pgbus] Dashboard is accessible without authentication. " \
             "Configure Pgbus.configuration.web_auth to restrict access. " \
             "See: https://github.com/zoolutions/pgbus#dashboard-authentication"
         end
-        Pgbus::Web::Authentication.auth_warned = true
       end
 
       # True when base_controller_class is (still) the default ActionController::Base.