pgbus 0.18.2 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83064d02cef8b5b1e2da6a8fb229d3968a93b59e34d7072babe9a7968f9100dd
-  data.tar.gz: 7a7095fee01a7e8c9f68f1284dd4b3e849bb1e50d12455b45830b2e96d854cc9
+  metadata.gz: a11cc47f884c4d3a845e019d2b526ca865be0d8f94851dda955d6163f4c822da
+  data.tar.gz: 6e560c1140a12ae2dc192f59f01898f291f4ea3c2265dd85c08d4ab115257f82
 SHA512:
-  metadata.gz: f4112de787c0eda83491b5b8bc4217c7a98111f4cbdd7304de601accc2795a08af5f5c192e09951a7ce2fc289f5f48950bea619540c200c41464f203a8a7d2b6
-  data.tar.gz: 8e28ba86d1ccbe8e323dd5dc6168f9466c791fa5d93b286a312a2b929885c5db43e42092136bb6035ec57b2adabb3f3b1e002e509d057a24a9bec0b23ba0aaef
+  metadata.gz: aa6702c6b5a46bb4a939726e3776b01ea7bbbc2c002e7f9a248b1d0c963c904d6dd034fcadcbfd90ec6f2209bccc32f05fde57e7e12727477e9166c1b5d15778
+  data.tar.gz: 9f4730ff62b0050eef7246ce9919f22f6c4400d8ee2f982eb3cc7ea25eb90e8eed83b70e6adb006bba8e79ea7b8e78850c83d8af3be495fe708605bde3b456ac

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+## [0.19.0]
+
+### Added
+
+- **RBS signatures for the public surface** in `sig/`, shipped with the gem: the `Pgbus` facade (`configure`, `stream`, `publish`, …), `Streams::Stream` (`broadcast`, `broadcast_render`, …), the ActiveJob adapter and the job-class options (`limits_concurrency`, `ensures_uniqueness`, `pgbus_retry_backoff`, `pgbus_visibility_heartbeat`), with `Configuration` and `Client` generated from reflection. CI runs `rbs -I sig validate`, and `spec/pgbus/rbs_spec.rb` fails when a public method has no signature or a signature outlives its method. Refs #527.
+- **`Pgbus.finalize!`: the configuration is finalized at boot.** It runs on its own, with no app code calling it: in a Rails app the engine calls it from `after_initialize`, after the app's own initializer files and `after_initialize` blocks; without Rails, each `Pgbus.configure` finalizes at its end; and `pgbus start` finalizes again once its flags are applied, before the supervisor forks. Call it yourself only when you configure pgbus through setters alone, without Rails. It validates the configuration (unless `eager_validation` is off) and replaces every plain-data setting (Strings, Symbols, numbers, booleans, Regexps, classes, and Arrays/Hashes/Sets of those) with a deep-frozen, Ractor-shareable copy, so every such reader is `Ractor.shareable?` after boot. Settings that hold callables or objects (the logger, `error_reporters`, `web_auth`, `web_data_source`, `fair_share`, `event_fair_share`, `metrics_backend`, `streams_presence_member`, `streams_presence_on_change`, `streams_authorize`) stay as they are, on the main Ractor, and so does any other value that cannot be made shareable (a lambda that closes over app state, a filter list holding a proc, a collection that contains itself): finalizing never raises for one. `Configuration#finalize!`/`#finalized?` are the per-object halves. Refs #527.
+
+### Changed
+
+- **The configuration is validated at boot, also without `Pgbus.configure`.** `Pgbus.finalize!` runs `validate!` from the engine's `after_initialize` (unless `eager_validation` is off), so an invalid value set through direct setters (`Pgbus.configuration.visibility_timeout = 0`) now raises `Pgbus::ConfigurationError` at boot instead of surfacing later in a worker. `pgbus start` validates again after applying its flags. Refs #527.
+- **After boot, the configuration's collections are frozen.** Setters keep working (they assign a new value, and a later `Pgbus.configure` finalizes again), but changing a collection setting in place once the app has booted, e.g. `Pgbus.configuration.streams_durable_patterns << "x"` in an `after_initialize` block that runs after pgbus's, now raises `FrozenError`: assign a new value instead (`c.streams_durable_patterns = [...]`), or configure in an initializer. Without Rails the configuration is finalized at the end of each `Pgbus.configure`, so the same holds from then on, also between two `configure` calls. `config.error_reporters << reporter` is unaffected. The app's own arrays and hashes are copied, never frozen. Refs #527.
+- **The streamer's dispatch values are Ractor-shareable.** `Listener::WakeMessage`, `StreamEventDispatcher::StreamEnvelope` and `Client::ReadAfter::Envelope`, the values handed from the LISTEN thread (or the master hub) to the dispatcher and from the dispatcher to `Connection#enqueue`, freeze their Strings where they are built, so a future Ractor dispatcher could pass them by reference. Nothing else changes (`StreamEnvelope#exclude` is the String it was already compared as). `rake bench:one[streams_frame_bench]` measures the frame path. Refs #527.
+
+### Fixed
+
+- **Smaller check-then-act races at the process level.** Each event handler class's `dedup_cache` is built when the class is defined instead of by a lazy `||=` (two first deliveries could each build one); the dashboard's "no authentication" warning is claimed under a lock, so concurrent first requests log it once; the batch schema probes and their warn-once flag are read and written under a lock. Refs #527.
+- **The metrics and AppSignal subscribers install once, even when two threads install at once.** `Metrics::Subscriber.install!`, `Integrations::Appsignal.install!` and its `Subscriber`/`Probe` checked `@installed` and then subscribed without a lock, so concurrent installs subscribed every event twice (double-counted metrics), and `reset!` then only detached the last set. The check and the install now happen under one lock per module. Refs #527.
+- **`Pgbus::Streams.filters` and `.coalescer` are one per process.** Both were lazy `@x ||= X.new` memos: two threads making the first call at once could each build one, and an audience filter registered on the registry that lost was gone. They are now built when `pgbus/streams` loads (the test resets replace them with fresh ones). `StreamQueue.all_names` hands out a frozen set that `record!` replaces whole instead of mutating in place, so the dispatcher iterating the set it got can no longer see it change under it (or raise mid-iteration) while a broadcast thread registers a stream, and a cold load of that set publishes its snapshot only when no stream was recorded and no `reset_cache!` ran while it loaded (the load itself runs outside the lock), so neither is lost. `Presence.seats_supported?` reads and writes its schema answer under its lock only. Refs #527.
+- **`DedupCache#mark!` is atomic.** It checked whether the key was present and whether the cache was full, then inserted, without a lock: two threads marking at once could both pass the checks, recording the key twice in the eviction order or growing the cache past `max_size`. The check and the insert (and an expired key's eviction) now happen under one lock; `seen?` still reads without it. Refs #527.
+- **`Client#wait_for_notify` no longer stalls the client while it waits.** On the shared ActiveRecord connection path it held the client's PGMQ mutex, which serializes every PGMQ call, across the whole blocking wait (indefinitely with `timeout: nil`); on the dedicated path it held a pool connection. It now LISTENs on a dedicated connection of its own (`worker_notify_connection_options`), opened for the wait and closed after. On the shared path that needs `worker_notify_database_url` (or a base `database_url`), and it raises `Pgbus::ConfigurationError` without one instead of borrowing the shared connection. A dedicated connection found dead before use is replaced and the wait starts again, as the pooled wait's stale-connection retry did. Refs #527.
+- **An immediate shutdown (QUIT) no longer leaves ActiveRecord connections checked out by killed jobs.** `Worker#immediate_shutdown` and `Consumer#immediate_shutdown` killed the execution pool outright: a job that held a connection died with it checked out, and the pool stayed that many connections short until ActiveRecord's reaper ran. They now stop taking work, give the running jobs `config.immediate_shutdown_grace` seconds (new, default 2) to finish, kill only what is still running after that, and then reclaim every connection whose thread or fiber is gone. Thread and async pools both wait for the jobs they kill to unwind first (the thread pool also for a job that started while it was killing, all of them within one join budget), and the connections are reclaimed also when the wait itself raises. `immediate_shutdown_grace` must be a finite number >= 0. Refs #527.
+- **`Pgbus.client`, `Pgbus.configuration` and `Pgbus.stream` hand every thread the same object.** All three were unlocked `||=` memos, so threads making the first call at once could each build their own: a second `Client` (whose connection pool was orphaned and never closed), a second `Configuration`, or a second stream cache. The configuration and the stream cache are now built when the gem loads (and `reset!` replaces them with fresh ones instead of `nil`), and the client is built on first use under a lock; `Pgbus.stopping` is read and written under the same lock. Because the configuration now exists before Rails sets `Rails.logger`, an unset `config.logger` is resolved on every read (Rails.logger when there is one, else `$stdout`) instead of once when the configuration is built; a `log_format` set before Rails.logger exists (`config/application.rb`) is applied to it once the engine initializes. Refs #527.
+- **The visibility heartbeat's lock can no longer split in two.** `Pgbus::VisibilityHeartbeat` built its Mutex lazily (`@mutex ||= Mutex.new`), so the first jobs of a process could each build and lock a Mutex of their own and register, extend and drop entries without excluding each other. A ticker stopped while a new job started another also exits now, instead of ticking beside the new one. The lock is now built when the module loads, and every read of the entry table and the ticker state happens under it (the ticker loop used to read `@running` unlocked). Refs #527.
+- **`Process::NotifyListener#start` and `#stop` no longer interleave.** A `stop` that ran while `start` was still creating the listener thread found no thread to join, and `start` then started one nobody joined (a restart could run a second LISTEN loop beside it on the same connection). Both now run whole under one lock that the listener thread never takes. Refs #527.
+- **A `Pgbus::Client` subclass can ensure the PGMQ schema.** The install lock is `Client`'s class state, which a subclass does not inherit, so a subclass raised `NoMethodError` on the schema check; it now takes `Client`'s lock. Refs #527.
+- **`Pgbus::Testing.fake!`/`inline!`/`disabled!` without a block are process-wide again from any fiber.** The mode was stored with `Thread.main[]=`, which writes the main thread's *current fiber*, and read back with `Thread.main[]`, which reads whichever fiber the main thread is running at that moment. A mode set inside an Async task (a Falcon test, `Sync { }`) vanished when the task ended, and a sibling task never saw it. The default mode is now a module-level value behind a lock built at load, so every thread and fiber sees it; the block form still scopes the mode to the fiber that set it (`Thread.current[]`), so a `fake! do … end` inside one task does not leak to its siblings. When such a block ends, `streams_test_mode` follows the mode in effect again; under a process-wide `fake!`/`inline!` it used to be switched off, letting later SSE requests reach the real streamer. Refs #527.
+
 ## [Unreleased]
 
 ### Added

data/README.md

@@ -139,6 +139,8 @@ The capsule string DSL is the shortest form for the common case. Use `c.capsule`
 
 Configuration is validated eagerly: `Pgbus.configure` runs `Configuration#validate!` right after your block yields, so an invalid value (`visibility_timeout = 0`, for example) raises `Pgbus::ConfigurationError` at boot instead of failing later inside a worker. Set `c.eager_validation = false` for the rare setup that intentionally holds a transiently-invalid config across sequential `configure` calls.
 
+Configuration is finalized at boot: once the app's initializers have run, the engine calls `Pgbus.finalize!`, which freezes every plain-data setting (strings, symbols, numbers, regexps, and arrays and hashes of those) into a Ractor-shareable value. Callables and the logger are left as they are. Setters keep working, and a later `Pgbus.configure` finalizes again, but changing a collection in place after boot (`Pgbus.configuration.streams_durable_patterns << "x"`) raises `FrozenError`: assign a new value instead. `c.error_reporters << reporter` keeps working. Without Rails, each `Pgbus.configure` finalizes at its end; `pgbus start` finalizes again once its flags are applied. Call `Pgbus.finalize!` yourself only when you configure pgbus through setters alone. A value that cannot be made shareable (a lambda that closes over app state, a logger, a filter list holding a proc) never makes finalizing raise: it is kept as it is, for the main Ractor. More in [docs/concurrency.md](docs/concurrency.md).
+
 > **Upgrading from an older pgbus?** Run `rails generate pgbus:update`. It inspects your live database and adds any missing pgbus migrations to `db/migrate` (or `db/pgbus_migrate` if you use `connects_to`). The generator detects your separate-database config automatically from `Pgbus.configuration.connects_to` or by scanning the initializer / `config/application.rb`, so you don't have to re-specify `--database=pgbus` every time.
 >
 > Useful flags: `--dry-run` (print the plan without creating files), `--skip-migrations`, `--quiet`. Running it on a database with no pgbus tables at all will redirect you to `pgbus:install` instead of stacking individual add_* migrations.
@@ -691,6 +693,8 @@ end
 
 **Not recommended for:** CPU-bound jobs (image processing, heavy computation). These block the single reactor thread and should use thread mode.
 
+Which state is fiber-local (broadcast options, the batch a job joins, the uniqueness key an enqueue holds) and what that means when work hops between fibers is in [docs/concurrency.md](docs/concurrency.md), with the threads each process runs and pgbus's Ractor readiness.
+
 ## Routing and ordering
 
 How messages flow between producers and the workers that handle them: priority sub-queues, consumer priority for active/standby workers, and single-active-consumer for strict ordering.
@@ -2369,6 +2373,7 @@ Curated headline options for the README. The full operator reference (with types
 | `zombie_detection` | `true` | Detect and reclaim work from crashed workers |
 | `read_timeout` | `30` | Seconds before a single PGMQ read is bounded (libpq `statement_timeout` + `tcp_user_timeout` on a dedicated connection; nil disables) |
 | `drain_timeout` | `30` | Seconds to wait for in-flight jobs during graceful shutdown before abandoning them |
+| `immediate_shutdown_grace` | `2` | On QUIT, seconds a worker or consumer gives running jobs to finish before killing them; killed jobs' ActiveRecord connections are reclaimed |
 | `shutdown_timeout` | `drain_timeout + 5` | Seconds the supervisor waits for children after TERM before SIGKILL; an orchestrator's stop grace period must exceed it |
 | `stall_threshold` | `300` | Seconds without progress before a worker is considered stalled |
 | `priority_levels` | `nil` | Number of priority sub-queues (nil = disabled, 2-10) |

data/app/controllers/pgbus/frontends_controller.rb

@@ -5,27 +5,29 @@ module Pgbus
     protect_from_forgery with: :exception
     skip_after_action :verify_same_origin_request, raise: false
 
-    FRONTEND_ROOT = Engine.root.join("app", "frontend", "pgbus")
+    FRONTEND_ROOT = Engine.root.join("app", "frontend", "pgbus").freeze
 
     STATIC_ASSETS = {
       css: {
-        style: FRONTEND_ROOT.join("style.css")
-      }
+        style: FRONTEND_ROOT.join("style.css").freeze
+      }.freeze
     }.freeze
 
     # Modules are served minified (rake frontend:js), each with its .min.js.map
     # beside it. ApexCharts ships minified already; charts.js imports it on
     # demand, so only Insights downloads it.
     MODULE_OVERRIDES = {
-      application: FRONTEND_ROOT.join("application.min.js"),
-      turbo: FRONTEND_ROOT.join("vendor", "turbo.min.js"),
-      apexcharts: FRONTEND_ROOT.join("vendor", "apexcharts.js")
+      application: FRONTEND_ROOT.join("application.min.js").freeze,
+      turbo: FRONTEND_ROOT.join("vendor", "turbo.min.js").freeze,
+      apexcharts: FRONTEND_ROOT.join("vendor", "apexcharts.js").freeze
     }.freeze
 
+    # An idempotent memo: concurrent first requests glob the same files and
+    # build equal Hashes; whichever is stored, every reader gets a frozen one.
     def self.js_modules
-      @js_modules ||= FRONTEND_ROOT.join("modules").glob("*.min.js").sort
+      @js_modules ||= FRONTEND_ROOT.join("modules").glob("*.min.js").sort # rubocop:disable ThreadSafety/ClassInstanceVariable
                                    .to_h { |f| [f.basename(".min.js").to_s.to_sym, f] }
-                                   .merge(MODULE_OVERRIDES)
+                                   .merge(MODULE_OVERRIDES).freeze
     end
 
     CURRENT_VERSION = Pgbus::VERSION.tr(".", "-").freeze

data/app/helpers/pgbus/application_helper.rb

@@ -94,10 +94,11 @@ module Pgbus
     end
 
     BATCH_BADGE_BASE = "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium"
+    # Interpolated strings are not frozen by the magic comment: freeze each.
     BATCH_BADGE_CSS = {
-      "finished" => "#{BATCH_BADGE_BASE} bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400",
-      "processing" => "#{BATCH_BADGE_BASE} bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400",
-      "pending" => "#{BATCH_BADGE_BASE} bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400"
+      "finished" => "#{BATCH_BADGE_BASE} bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400".freeze,
+      "processing" => "#{BATCH_BADGE_BASE} bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400".freeze,
+      "pending" => "#{BATCH_BADGE_BASE} bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400".freeze
     }.freeze
 
     def pgbus_batch_status_badge(status)

data/app/models/pgbus/job_stat.rb

@@ -37,6 +37,9 @@ module Pgbus
     # false on the first hiccup would permanently disable job stats
     # for the process lifetime, which is a worse failure mode than
     # a few retries. See issue #98 / PR #91 (StreamStat fix).
+    # An idempotent schema memo: concurrent first callers probe the same
+    # schema and store the same Boolean, so the unlocked read/write is safe.
+    # rubocop:disable ThreadSafety/ClassInstanceVariable
     def self.table_exists?
       return @table_exists if defined?(@table_exists)
 
@@ -59,6 +62,7 @@ module Pgbus
       Pgbus.logger.debug { "[Pgbus] Failed to check job stat latency columns: #{e.message}" }
       false
     end
+    # rubocop:enable ThreadSafety/ClassInstanceVariable
 
     # Throughput: jobs per minute bucketed by minute for the last N minutes
     def self.throughput(minutes: 60)

data/app/models/pgbus/processed_event.rb

@@ -21,7 +21,9 @@ module Pgbus
       # failure path leaves the message for VT redelivery — and the next
       # delivery probes again.
       def completion_column?
-        detected = @completion_column
+        # Double-checked: the unlocked read only skips the lock once the
+        # answer is set; it is written under @completion_column_mutex.
+        detected = @completion_column # rubocop:disable ThreadSafety/ClassInstanceVariable
         return detected unless detected.nil?
 
         @completion_column_mutex.synchronize do

data/app/models/pgbus/stream_queue.rb

@@ -30,6 +30,15 @@ module Pgbus
     # unsynchronized check-and-set could WARN more than once per process.
     @record_failure_mutex = Mutex.new
 
+    # Guards the @all_names memo and its generation (issue #527). The memo is a frozen Set,
+    # replaced whole (record! publishes a copy with the new name), so a
+    # caller iterating the set it got can never see it change underneath:
+    # record! runs on broadcast threads while the dispatcher iterates it.
+    @names_lock = Mutex.new
+    # Bumped by every record! and reset_cache! (under @names_lock): a cold
+    # load publishes its snapshot only if no such change happened while it ran.
+    @names_generation = 0
+
     class << self
       # Inserts the physical queue name. Idempotent and cheap to call on
       # every broadcast; the caller (`ensure_stream_queue`) also memoizes
@@ -61,7 +70,10 @@ module Pgbus
         # already-registered stream until the next reset_cache!. Leaving it
         # nil lets the next all_names call do a real load, which already
         # includes this row since the insert above has committed.
-        @all_names&.add(queue_name)
+        @names_lock.synchronize do
+          @names_generation += 1
+          @all_names = (@all_names | [queue_name]).freeze if @all_names
+        end
         true
       rescue ActiveRecord::ActiveRecordError => e
         Pgbus.logger.debug { "[Pgbus] Failed to record stream queue #{queue_name}: #{e.message}" }
@@ -76,8 +88,21 @@ module Pgbus
       # not one per queue. Callers that need freshness (a long-lived process
       # picking up newly-created streams) call `reset_cache!` at the top of
       # their loop.
+      # A cold load runs outside the lock (record! takes a connection before
+      # the lock, so a load holding the lock while it waits for a connection
+      # could deadlock an exhausted pool) and is published only when no
+      # record! or reset_cache! ran meanwhile: its snapshot could predate
+      # them, and publishing it would lose their change. Otherwise the caller
+      # gets the snapshot and the memo stays empty, so the next call reloads.
       def all_names
-        @all_names ||= load_names
+        cached, generation = @names_lock.synchronize { [@all_names, @names_generation] }
+        return cached if cached
+
+        loaded = load_names.freeze
+        @names_lock.synchronize do
+          @all_names ||= loaded if @names_generation == generation
+          @all_names || loaded
+        end
       end
 
       # Registry ∪ fingerprint-matched names. Use this for classification
@@ -128,11 +153,17 @@ module Pgbus
       # wildcard resolution so freshly-created streams are picked up without
       # a process restart.
       def reset_cache!
-        @all_names = nil
+        @names_lock.synchronize do
+          @names_generation += 1
+          @all_names = nil
+        end
       end
 
       # Memoized like StreamStat: a successful probe sticks; a transient
       # error returns false without caching, so the next call retries.
+      # An idempotent memo: concurrent first callers probe the same schema
+      # and store the same Boolean, so the unlocked read/write is safe.
+      # rubocop:disable-next ThreadSafety/ClassInstanceVariable
       def table_exists?
         return @table_exists if defined?(@table_exists) && @table_exists
 

data/app/models/pgbus/stream_stat.rb

@@ -49,6 +49,9 @@ module Pgbus
     # false on the first hiccup would permanently disable stream
     # stats for the process lifetime, which is a worse failure mode
     # than a few retries.
+    # An idempotent schema memo: concurrent first callers probe the same
+    # schema and store the same Boolean, so the unlocked read/write is safe.
+    # rubocop:disable-next ThreadSafety/ClassInstanceVariable
     def self.table_exists?
       return @table_exists if defined?(@table_exists)
 

data/lib/pgbus/active_job/current_attributes.rb

@@ -28,7 +28,9 @@ module Pgbus
       included do
         attr_accessor :pgbus_current_attributes
 
-        class_attribute :pgbus_persist_current_attributes, instance_writer: false, default: nil
+        # A per-class setting the job's own class body writes at load; jobs
+        # only read it while they serialize.
+        class_attribute :pgbus_persist_current_attributes, instance_writer: false, default: nil # rubocop:disable ThreadSafety/ClassAndModuleAttributes
       end
 
       def serialize

data/lib/pgbus/batch.rb

@@ -209,22 +209,28 @@ module Pgbus
       0
     end
 
+    # Schema-probe memos (a true answer is kept for the life of the process)
+    # and the warn-once flag, read and written under @schema_lock (issue
+    # #527). The probes run outside it: a duplicate probe on a race is
+    # harmless, a lock held across a query is not.
+    @schema_lock = Mutex.new
+
     def self.executions_migrated?
-      return true if @executions_migrated
+      return true if @schema_lock.synchronize { @executions_migrated }
 
       result = begin
         BatchExecution.table_exists?
       rescue StandardError
         false
       end
-      @executions_migrated = true if result
+      @schema_lock.synchronize { @executions_migrated = true } if result
       result
     end
 
     def self.warn_callback_jobs_unmigrated
-      return if @warned_callback_jobs_unmigrated
+      first = @schema_lock.synchronize { @warned_callback_jobs_unmigrated ? false : (@warned_callback_jobs_unmigrated = true) }
+      return unless first
 
-      @warned_callback_jobs_unmigrated = true
       Pgbus.logger.warn do
         "[Pgbus] Batch callback configured as an ActiveJob instance, but pgbus_batches has no " \
           "on_*_job columns yet — .set options (queue, wait, priority) are ignored until " \
@@ -233,23 +239,25 @@ module Pgbus
     end
 
     def self.reset_executions_migrated_cache!
-      @executions_migrated = nil
-      @callback_jobs_migrated = nil
-      @warned_callback_jobs_unmigrated = nil
+      @schema_lock.synchronize do
+        @executions_migrated = nil
+        @callback_jobs_migrated = nil
+        @warned_callback_jobs_unmigrated = nil
+      end
     end
 
     # True once the on_finish_job / on_success_job / on_failure_job jsonb
     # columns exist (issue #415). Until then, configured callback instances
     # have nowhere to live and only bare classes are stored.
     def self.callback_jobs_migrated?
-      return true if @callback_jobs_migrated
+      return true if @schema_lock.synchronize { @callback_jobs_migrated }
 
       result = begin
         BatchEntry.column_names.include?("on_finish_job")
       rescue StandardError
         false
       end
-      @callback_jobs_migrated = true if result
+      @schema_lock.synchronize { @callback_jobs_migrated = true } if result
       result
     end
 

data/lib/pgbus/cli.rb

@@ -37,6 +37,9 @@ module Pgbus
 
     def start_supervisor(args = [])
       apply_start_options(args)
+      # The flags go through setters, after boot finalized the configuration:
+      # finalize their values too before the supervisor forks.
+      Pgbus.finalize!
       Pgbus.logger.info { "[Pgbus] Starting Pgbus #{Pgbus::VERSION}..." }
 
       supervisor = Process::Supervisor.new

data/lib/pgbus/client/read_after.rb

@@ -9,7 +9,16 @@ module Pgbus
     # The cursor is the highest msg_id the client has already seen. Replay returns
     # everything strictly greater, ordered by msg_id ASC, capped by `limit`.
     module ReadAfter
-      Envelope = Data.define(:msg_id, :enqueued_at, :payload, :source)
+      # Ractor-shareable like the streamer's other dispatch values (issue
+      # #527): the Strings are frozen in place, they are the read's own.
+      Envelope = Data.define(:msg_id, :enqueued_at, :payload, :source) do
+        def initialize(msg_id:, enqueued_at:, payload:, source:)
+          enqueued_at&.freeze
+          payload&.freeze
+          source&.freeze
+          super
+        end
+      end
 
       DEFAULT_LIMIT = 500
 

data/lib/pgbus/client.rb

@@ -20,9 +20,6 @@ module Pgbus
 
     attr_reader :pgmq, :config, :connection_health
 
-    PGMQ_REQUIRE_MUTEX = Mutex.new
-    private_constant :PGMQ_REQUIRE_MUTEX
-
     # Fixed advisory-lock key serializing pgmq schema installation across
     # processes (issue #397). "pgmqinst" in ASCII hex — arbitrary but stable;
     # it only has to be identical in every process that can install.
@@ -55,6 +52,11 @@ module Pgbus
     # (issue #397, forensics in getzazu/app#3413).
     @pgmq_install_mutex = Mutex.new
 
+    # Serializes the one-time `require "pgmq"` (see load_pgmq_gem!). Class
+    # state built at load, not a constant: a constant holding a Mutex is
+    # unreadable from a non-main Ractor (issue #527).
+    @pgmq_require_mutex = Mutex.new
+
     class << self
       attr_reader :pgmq_install_mutex
     end
@@ -82,7 +84,10 @@ module Pgbus
     # instead of the global Kernel#require, which — if stubbed before pgmq is
     # genuinely loaded — permanently prevents the real gem from ever loading.
     def self.load_pgmq_gem!
-      PGMQ_REQUIRE_MUTEX.synchronize do
+      # The lock is Client's class state, which a subclass does not inherit.
+      return Client.load_pgmq_gem! unless equal?(Client)
+
+      @pgmq_require_mutex.synchronize do
         Object.const_set(:PGMQ, Module.new) unless defined?(::PGMQ)
         require "pgmq"
       end
@@ -920,10 +925,33 @@ module Pgbus
 
     # --- LISTEN/NOTIFY management (PGMQ v1.11.0+) ---
 
-    def wait_for_notify(queue_name, timeout: nil, &block)
-      full_name = config.queue_name(queue_name)
-      with_stale_connection_retry do
-        synchronized { @pgmq.wait_for_notify(full_name, timeout: timeout, &block) }
+    # Blocks until PGMQ's insert trigger notifies +queue_name+ or +timeout+
+    # seconds pass (nil waits indefinitely); returns the channel, or nil on a
+    # timeout, and yields (channel, pid, payload) like
+    # PG::Connection#wait_for_notify. The wait gets a dedicated connection of
+    # its own (worker_notify_connection_options), opened for it and closed
+    # after: never a pool connection, and never under @pgmq_mutex, which on
+    # the shared-AR path serializes every PGMQ call, so holding it across a
+    # blocking wait stalled the whole client (issue #527). The shared-AR path
+    # therefore needs worker_notify_database_url (or a base database_url).
+    # A connection found dead before it was used (STALE_CONNECTION_PATTERNS)
+    # is replaced and the wait starts again, as with_stale_connection_retry
+    # did for the pooled wait; a connection lost mid-wait is not retried.
+    def wait_for_notify(queue_name, timeout: nil, &)
+      channel = "pgmq.q_#{config.queue_name(queue_name)}.INSERT"
+      attempts = 0
+      begin
+        listen_on_dedicated_connection(channel, timeout, &)
+      rescue StandardError => e
+        attempts += 1
+        raise unless attempts <= STALE_RETRY_ATTEMPTS && stale_pg_error?(e)
+
+        sleep STALE_RETRY_DELAYS[[attempts - 1, STALE_RETRY_DELAYS.size - 1].min]
+        Pgbus.logger.warn do
+          "[Pgbus::Client] Retrying wait_for_notify after a stale connection " \
+            "(attempt #{attempts}/#{STALE_RETRY_ATTEMPTS}): #{e.message}"
+        end
+        retry
       end
     end
 
@@ -1199,7 +1227,8 @@ module Pgbus
     def ensure_pgmq_schema
       return if @schema_ensured
 
-      self.class.pgmq_install_mutex.synchronize do
+      # Client's lock, also for a subclass: it serializes every client's install.
+      Client.pgmq_install_mutex.synchronize do
         return if @schema_ensured
 
         # Cache only a durable result: true only when this call owned the
@@ -2069,6 +2098,22 @@ module Pgbus
       end
     end
 
+    def listen_on_dedicated_connection(channel, timeout, &)
+      conn = DedicatedConnection.connect(config.worker_notify_connection_options)
+      begin
+        conn.exec("LISTEN #{conn.quote_ident(channel)}")
+        conn.wait_for_notify(timeout, &)
+      ensure
+        DedicatedConnection.close_quietly(conn)
+      end
+    end
+
+    # A raw PG::Error (the dedicated connection is not wrapped by pgmq-ruby)
+    # whose message says the connection was dead before it was used.
+    def stale_pg_error?(error)
+      defined?(::PG::Error) && error.is_a?(::PG::Error) && stale_connection_error?(error)
+    end
+
     def stale_connection_error?(error)
       # Substring match against any stale-connection pattern. Deliberately a
       # single Regexp rather than `STALE_CONNECTION_PATTERNS.any? { |p| msg.include?(p) }`:

data/lib/pgbus/concurrency.rb

@@ -12,6 +12,9 @@ module Pgbus
     # parked job whose class no longer resolves.
     DEFAULT_DURATION = 15 * 60
 
+    # 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
       # Limit concurrent execution of jobs with the same key.
       #