feat: add PostgreSQL cross-process wake-up

In-process signalling cannot reach another process, so a commit in a web process left a worker waiting out polling_interval and every reactive update paid up to 100ms before delivery began. The optional adapter listens on a dedicated connection and notifies through the pool, taking measured cross-process wake-up latency from 103.7ms to 2.9ms at p50 against PostgreSQL 17. Polling remains the upper bound, so a missed or failed notification costs latency rather than correctness, and neither signalling nor waiting raises into its caller.

Author: cardmagic

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## Unreleased
+
+- Add `SolidObjects::WakeUpAdapters::Postgresql`, an optional cross-process
+  wake-up using PostgreSQL notifications. In-process signalling cannot reach a
+  worker process, so reactive delivery waited out `polling_interval`. With the
+  adapter configured, measured cross-process wake-up latency drops from 103.7 ms
+  to 2.9 ms at p50. The polling interval remains the upper bound, and neither
+  signalling nor waiting raises into its caller.
+
 ## 0.7.3 - 2026-08-09
 
 - Coordinate batched component refreshes by revision as well as scope and batch

docs/benchmarks.md

@@ -76,6 +76,21 @@ Cable delivery, or browser rendering, which dominate wall-clock time in a real
 deployment and make the request-count difference matter more than it appears
 here. End-to-end latency against a deployed application has not been measured.
 
+## Cross-process wake-up
+
+Measured 2026-08-09 against PostgreSQL 17, 30 samples, with `polling_interval`
+at its 100 ms default and a signal sent 2 ms after the waiter began.
+
+| Wake-up strategy | p50 | p95 |
+| --- | ---: | ---: |
+| In-process `WakeUp` | 103.7 ms | 105.1 ms |
+| `WakeUpAdapters::Postgresql` | 2.9 ms | 5.1 ms |
+
+The in-process wake-up cannot reach another process, so a worker waits out the
+full polling interval no matter how quickly the web process committed. The
+notification adapter removes that floor rather than shrinking it, and the
+polling interval remains the upper bound if a notification is missed.
+
 ## Durable row growth
 
 The storage cost is deterministic even when latency is not:

docs/realtime.md

@@ -110,6 +110,29 @@ applications discover the namespaced engine asset. Applications created with
 explicitly serve the module. Turbo's normal morph rules still apply; use
 `data-turbo-permanent` for elements that must never be changed.
 
+## Cross-process wake-up
+
+Runtime roles poll for work and are woken early by an in-process signal. That
+signal cannot cross process boundaries, so a commit in a Puma process does not
+wake a broadcast executor in a worker process, and delivery waits out
+`polling_interval`, 100 ms by default.
+
+On PostgreSQL, install the notification adapter to remove that delay:
+
+```ruby
+# config/initializers/solid_objects.rb
+configuration.wake_up_adapter = SolidObjects::WakeUpAdapters::Postgresql.new
+```
+
+Measured latency for a cross-process wake-up drops from 103.7 ms to 2.9 ms at
+p50. The adapter keeps `polling_interval` as the upper bound: a missed or failed
+notification costs latency, never correctness, and signalling never raises into
+the caller that committed. `LISTEN` needs its own connection, so the adapter
+opens one outside the pool and releases it on `stop`.
+
+Applications on SQLite or MySQL, or that do not configure the adapter, keep the
+existing polling behaviour.
+
 ## Batched component refreshes
 
 A component refresh costs one browser request. When one actor mutation changes

lib/solid_objects.rb

@@ -46,6 +46,7 @@
 require "solid_objects/actor_channel"
 require "solid_objects/action_cable_broadcast_adapter"
 require "solid_objects/wake_up"
+require "solid_objects/wake_up_adapters/postgresql"
 require "solid_objects/effect_registry"
 require "solid_objects/commit_action_registry"
 require "solid_objects/lease"

lib/solid_objects/wake_up_adapters/postgresql.rb

@@ -0,0 +1,117 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module WakeUpAdapters
+    # Wakes runtime roles across processes using PostgreSQL notifications.
+    #
+    # The in-process wake-up cannot reach another process, so a commit in a web
+    # process leaves a worker waiting out its polling interval. This adapter
+    # keeps that polling interval as the upper bound and delivers a notification
+    # when one is available, so a missed or failed notification costs latency
+    # rather than correctness.
+    class Postgresql
+      CHANNEL = "solid_objects_wake_up"
+      FAILED_WAIT_INTERVAL = 0.05
+
+      # @rbs @channel: String
+      # @rbs @mutex: Thread::Mutex
+      # @rbs @connection: untyped
+
+      attr_reader :channel
+
+      # @rbs (?channel: String) -> void
+      def initialize(channel: CHANNEL)
+        @channel = channel
+        @mutex = Thread::Mutex.new
+        @connection = nil
+      end
+
+      # @rbs () -> bool
+      def signal
+        notify_channel
+        true
+      rescue => error
+        instrument_failure(:signal, error)
+        false
+      end
+
+      # @rbs (timeout: Numeric) -> bool
+      def wait(timeout:)
+        connection = listening_connection
+        !connection.raw_connection.wait_for_notify(timeout.to_f).nil?
+      rescue => error
+        instrument_failure(:wait, error)
+        pace_after_failure(timeout)
+        false
+      end
+
+      # Starts listening before a caller blocks, so a notification sent between
+      # startup and the first wait is not missed.
+      # @rbs () -> bool
+      def listen
+        listening_connection
+        true
+      rescue => error
+        instrument_failure(:listen, error)
+        false
+      end
+
+      # @rbs () -> bool
+      def stop
+        mutex.synchronize do
+          connection = @connection
+          @connection = nil
+          return false unless connection
+
+          connection.disconnect!
+          true
+        end
+      rescue
+        false
+      end
+
+      private
+
+      attr_reader :mutex
+
+      # @rbs () -> void
+      def notify_channel
+        Record.connection_pool.with_connection do |connection|
+          connection.execute("NOTIFY #{connection.quote_table_name(channel)}")
+        end
+      end
+
+      # A listening connection is dedicated: `LISTEN` is per connection, and a
+      # blocking wait must not hold a connection the rest of the runtime needs.
+      # @rbs () -> untyped
+      def listening_connection
+        mutex.synchronize do
+          return @connection if @connection&.active?
+
+          @connection = Record.connection_pool.send(:new_connection)
+          @connection.execute("LISTEN #{@connection.quote_table_name(channel)}")
+          @connection
+        end
+      end
+
+      # @rbs (Numeric) -> void
+      def pace_after_failure(timeout)
+        interval = [ timeout.to_f, FAILED_WAIT_INTERVAL ].min
+        return unless interval.positive?
+
+        sleep interval
+      end
+
+      # @rbs (Symbol, Exception) -> void
+      def instrument_failure(operation, error)
+        SolidObjects.instrument(
+          :"wake_up.failed",
+          adapter: "postgresql",
+          operation: operation.to_s,
+          error_class: error.class.name,
+          error_message: error.message
+        )
+      end
+    end
+  end
+end

sig/generated/lib/solid_objects/wake_up_adapters/postgresql.rbs

@@ -0,0 +1,61 @@
+# Generated from lib/solid_objects/wake_up_adapters/postgresql.rb with RBS::Inline
+
+module SolidObjects
+  module WakeUpAdapters
+    # Wakes runtime roles across processes using PostgreSQL notifications.
+    #
+    # The in-process wake-up cannot reach another process, so a commit in a web
+    # process leaves a worker waiting out its polling interval. This adapter
+    # keeps that polling interval as the upper bound and delivers a notification
+    # when one is available, so a missed or failed notification costs latency
+    # rather than correctness.
+    class Postgresql
+      CHANNEL: ::String
+
+      FAILED_WAIT_INTERVAL: ::Float
+
+      @connection: untyped
+
+      @mutex: Thread::Mutex
+
+      @channel: String
+
+      attr_reader channel: untyped
+
+      # @rbs (?channel: String) -> void
+      def initialize: (?channel: String) -> void
+
+      # @rbs () -> bool
+      def signal: () -> bool
+
+      # @rbs (timeout: Numeric) -> bool
+      def wait: (timeout: Numeric) -> bool
+
+      # Starts listening before a caller blocks, so a notification sent between
+      # startup and the first wait is not missed.
+      # @rbs () -> bool
+      def listen: () -> bool
+
+      # @rbs () -> bool
+      def stop: () -> bool
+
+      private
+
+      attr_reader mutex: untyped
+
+      # @rbs () -> void
+      def notify_channel: () -> void
+
+      # A listening connection is dedicated: `LISTEN` is per connection, and a
+      # blocking wait must not hold a connection the rest of the runtime needs.
+      # @rbs () -> untyped
+      def listening_connection: () -> untyped
+
+      # @rbs (Numeric) -> void
+      def pace_after_failure: (Numeric) -> void
+
+      # @rbs (Symbol, Exception) -> void
+      def instrument_failure: (Symbol, Exception) -> void
+    end
+  end
+end

test/integration/postgresql_wake_up_test.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "database_test_helper"
+require "timeout"
+
+class PostgresqlWakeUpTest < ActiveSupport::TestCase
+  setup do
+    skip unless postgresql?
+
+    @adapter = SolidObjects::WakeUpAdapters::Postgresql.new
+  end
+
+  teardown { @adapter&.stop }
+
+  test "a signal from another connection wakes a waiter" do
+    waiting = Queue.new
+    woken = Queue.new
+    waiter = Thread.new do
+      @adapter.listen
+      waiting << true
+      started = monotonic_now
+      @adapter.wait(timeout: 5)
+      woken << monotonic_now - started
+    end
+    Timeout.timeout(5) { waiting.pop }
+
+    signal_from_another_connection
+
+    elapsed = Timeout.timeout(5) { woken.pop }
+    waiter.join(5)
+    assert_operator elapsed, :<, 1.0,
+      "a cross-connection signal should wake the waiter well before the timeout"
+  end
+
+  test "waiting returns after the timeout when nothing signals" do
+    @adapter.listen
+    started = monotonic_now
+
+    @adapter.wait(timeout: 0.2)
+
+    elapsed = monotonic_now - started
+    assert_operator elapsed, :>=, 0.15
+    assert_operator elapsed, :<, 2.0
+  end
+
+  test "every waiter wakes on one signal" do
+    waiters = 3
+    waiting = Queue.new
+    woken = Queue.new
+    adapters = Array.new(waiters) { SolidObjects::WakeUpAdapters::Postgresql.new }
+    threads = adapters.map do |adapter|
+      Thread.new do
+        adapter.listen
+        waiting << true
+        adapter.wait(timeout: 5)
+        woken << true
+      end
+    end
+    waiters.times { Timeout.timeout(5) { waiting.pop } }
+
+    signal_from_another_connection
+
+    waiters.times { Timeout.timeout(5) { woken.pop } }
+    threads.each { |thread| thread.join(5) }
+    assert_equal 0, woken.size
+  ensure
+    adapters&.each(&:stop)
+  end
+
+  test "signalling never raises into the caller" do
+    broken = SolidObjects::WakeUpAdapters::Postgresql.new(channel: "solid_objects_missing")
+    broken.define_singleton_method(:notify_channel) { raise "boom" }
+
+    assert_nothing_raised { broken.signal }
+  ensure
+    broken&.stop
+  end
+
+  test "waiting never raises into the caller" do
+    broken = SolidObjects::WakeUpAdapters::Postgresql.new
+    broken.define_singleton_method(:listening_connection) { raise "boom" }
+    started = monotonic_now
+
+    assert_nothing_raised { broken.wait(timeout: 0.1) }
+
+    assert_operator monotonic_now - started, :>=, 0.05,
+      "a failed wait must still pace itself rather than spin"
+  ensure
+    broken&.stop
+  end
+
+  test "the adapter satisfies the wake-up contract" do
+    assert_respond_to @adapter, :signal
+    assert_respond_to @adapter, :wait
+    SolidObjects.configuration.wake_up_adapter = @adapter
+
+    assert_same @adapter, SolidObjects.wake_up
+  ensure
+    SolidObjects.configuration.wake_up_adapter = nil
+    SolidObjects.instance_variable_set(:@wake_up, nil)
+  end
+
+  private
+
+  def postgresql?
+    SolidObjects::Record.connection.adapter_name.match?(/postgres/i)
+  end
+
+  def monotonic_now
+    ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+  end
+
+  # Models a commit in a different process: a plain NOTIFY on its own connection.
+  def signal_from_another_connection
+    Thread.new { SolidObjects::WakeUpAdapters::Postgresql.new.signal }.join(5)
+  end
+end