solid_objects 0.7.3 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de78ca94f2c12e3c08d50c7b2512d6dbda67a47571540390c7494c6a828f1d35
-  data.tar.gz: b194c137ff3110cabb6cb2f7319819fdd64f314a9ae2113868438a89acce36b8
+  metadata.gz: b7fee6db10af36996dbe9c8484fab405b53e2463a3fd7d2f7414310fedab68d5
+  data.tar.gz: 8b71bb8fbf0dc0359ce8a00097428dbbcd189e4d2b4071ba0339b9c3ec1cd933
 SHA512:
-  metadata.gz: 78834ecb346469854b6d21d938fe3a6ed2689cd60cb037b22b3ce00025466c172ceb3dacdfcf94f88b0e0739e3dcac1c3e84896c6685bc4fe53d4db565ab8513
-  data.tar.gz: 31fbae44dce542e1fc07fe218bf504eb8627583ecc64895e8d86a5805340aeea47531b5f08a6e844809c31b513998c53c28b90993ae9cd40b864e868323eee27
+  metadata.gz: 62f2ce7ecfa4899f82af3682c5a8fb97d7005e6ba9152a8a63433b2ec345d2edc3d795c29a7f6de24d25f275afd4857986ed34302359d0f3aab018f936656acd
+  data.tar.gz: 2114e1d8b7757bf598562fba6e1b8ecafeea852d6925a5161f74b1dcab6dab9b5750ca71327b0cfa23b927869cbeee348f1bd6d03cbfc5d964d2bfd53a625435

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.9.0 - 2026-08-10
+
+- Add a browser test suite running the refresh modules against real Chromium and
+  a real Turbo build, covering `component_refresh.js`, which previously had no
+  tests at all. Every batching defect that reached production passed the jsdom
+  suite, because jsdom cannot model Turbo applying a morph, task boundaries
+  between socket deliveries, or abort semantics.
+- Verify the database server. Each adapter reports its version against the
+  oldest one Solid Objects is exercised against, PostgreSQL 13, MySQL 8.0, and
+  SQLite 3.35, and MySQL additionally confirms that Solid Objects tables use
+  InnoDB, since a non-transactional engine would silently break fenced commits.
+  The doctor reports this as `database_server` and warns rather than failing:
+  refusing to run on an untested server would be a worse failure than running
+  on one.
+- Add `SolidObjects::WakeUpAdapters::Redis`, an optional cross-process wake-up
+  using Redis publish and subscribe. This is the option for MySQL, which has no
+  notification primitive. Measured cross-process wake-up latency drops from
+  103.8 ms to 5.7 ms at p50. One background subscription per process fans out to
+  every waiting role in memory. The `redis` gem is not a dependency of this gem,
+  and `WakeUpAdapters.for` does not select it, so adopting Redis stays explicit.
+
+## 0.8.0 - 2026-08-10
+
+- Replace a supervised role whose thread died. A role that raised left its
+  thread dead while the process kept running and quietly did less work; the
+  supervisor now restarts it until shutdown is requested. Prune dead process
+  records on an interval as part of the same monitor. Both intervals are
+  configurable through `supervisor_monitor_interval` and
+  `dead_process_cleanup_interval`.
+- Run compatibility CI across the span the gemspec advertises: Ruby 3.3 and 3.4
+  against Rails 8.0 and 8.1. The suite previously ran on one combination, so
+  `>= 8.0` was a claim rather than a tested guarantee. Set `RAILS_VERSION` to
+  pin a Rails line locally.
+- Stop a synchronous lock retry from asking for a negative wait when its
+  deadline expires between the check and the wait, which raised
+  `ArgumentError: time interval must not be negative` instead of the timeout
+  the caller expected. Found by the new compatibility matrix.
+- 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. `WakeUpAdapters.for` selects
+  notifications on PostgreSQL and the in-process default elsewhere; it is not
+  the default, because the adapter opens a connection per waiting thread
+  outside the pool and `LISTEN` does not survive a transaction-pooling proxy.
+
 ## 0.7.3 - 2026-08-09
 
 - Coordinate batched component refreshes by revision as well as scope and batch

data/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:

data/docs/local-testing.md

@@ -0,0 +1,91 @@
+# Local testing
+
+The default suite runs against SQLite and needs nothing extra:
+
+```bash
+bundle exec rake
+```
+
+Everything below is optional. Each adapter and each optional service skips its
+tests when the service is absent, so a missing container degrades coverage
+rather than breaking the run. That is convenient, and it is also a trap: a
+skipped test looks identical to a passing one in the summary line. Check the
+skip count when a change touches an adapter.
+
+## PostgreSQL
+
+```bash
+brew services start postgresql@17
+createuser -h 127.0.0.1 -s solid_objects
+psql -h 127.0.0.1 -d postgres -c "ALTER USER solid_objects WITH PASSWORD 'solid_objects';"
+createdb -h 127.0.0.1 -O solid_objects solid_objects_test
+
+SOLID_OBJECTS_DATABASE_URL=postgresql://solid_objects:solid_objects@127.0.0.1:5432/solid_objects_test \
+  bundle exec rake test
+```
+
+Running this locally is worth the setup: it is what caught the PostgreSQL
+version comparison reading a packed integer, where `170010` compared greater
+than any minimum and made the check useless on the adapter it mattered most for.
+
+## MySQL and Redis in Docker
+
+These use non-default ports so they cannot collide with a MySQL or Redis that
+another project is already running:
+
+```bash
+docker run -d --name so-mysql -p 3307:3306 \
+  -e MYSQL_ROOT_PASSWORD=solid_objects \
+  -e MYSQL_DATABASE=solid_objects_test \
+  -e MYSQL_USER=solid_objects \
+  -e MYSQL_PASSWORD=solid_objects \
+  mysql:8
+
+docker run -d --name so-redis -p 6380:6379 redis:7-alpine
+```
+
+```bash
+SOLID_OBJECTS_DATABASE_URL=mysql2://solid_objects:solid_objects@127.0.0.1:3307/solid_objects_test \
+  bundle exec rake test
+
+SOLID_OBJECTS_REDIS_URL=redis://127.0.0.1:6380/15 \
+  bundle exec rake test TEST=test/integration/redis_wake_up_test.rb
+```
+
+Stop them with `docker rm -f so-mysql so-redis`.
+
+## Recreating a database between runs
+
+The test helper migrates unconditionally, so a second run against a database
+that already has the tables fails with a duplicate-table error rather than a
+test failure. Recreate first:
+
+```bash
+dropdb -h 127.0.0.1 solid_objects_test && createdb -h 127.0.0.1 -O solid_objects solid_objects_test
+
+docker exec so-mysql mysql -u root -psolid_objects \
+  -e "DROP DATABASE IF EXISTS solid_objects_test; CREATE DATABASE solid_objects_test;
+      GRANT ALL ON solid_objects_test.* TO 'solid_objects'@'%';"
+```
+
+## Rails and Ruby span
+
+`RAILS_VERSION` pins the Rails line the gemspec advertises:
+
+```bash
+RAILS_VERSION=8.0 bundle install
+RAILS_VERSION=8.0 bundle exec rake test
+```
+
+## Browser modules
+
+```bash
+npm install
+npm test                                  # jsdom, fast
+npx playwright install chromium
+npm run test:browser                      # real Chromium and a real Turbo build
+```
+
+The jsdom suite covers logic; the browser suite covers integration with Turbo.
+Both matter: every batching defect that reached production passed the jsdom
+suite alone.

data/docs/realtime.md

@@ -110,6 +110,49 @@ 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.for
+```
+
+`WakeUpAdapters.for` returns notifications on PostgreSQL and the in-process
+default on SQLite and MySQL, so the same line is safe across adapters. Name
+`SolidObjects::WakeUpAdapters::Postgresql.new` directly to require it.
+
+MySQL has no notification primitive. MySQL applications either keep polling and
+tune `polling_interval`, or configure the Redis adapter:
+
+```ruby
+configuration.wake_up_adapter = SolidObjects::WakeUpAdapters::Redis.new(
+  url: ENV["REDIS_URL"]
+)
+```
+
+Measured latency for a cross-process wake-up drops from 103.8 ms to 5.7 ms at
+p50. The `redis` gem is not a dependency of this gem, so applications add it
+themselves. One background subscription per process fans out to every waiting
+role in memory, rather than one connection per thread, and `WakeUpAdapters.for`
+does not select it: Redis is infrastructure this gem otherwise does not require,
+so choosing it is explicit.
+
+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

data/docs/roadmap.md

@@ -24,6 +24,9 @@
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook
+- Database server verification: each adapter reports its version against a
+  tested minimum, MySQL confirms Solid Objects tables use InnoDB, and the
+  doctor warns rather than refusing to run on an untested server
 - Handler Active Record write isolation, same-database commit actions, ambient
   transaction rejection, adapter lock/query deadlines, bounded SQLite lock
   retries outside those deadlines, structured sync timeout diagnostics, and
@@ -31,23 +34,37 @@
 - Bounded message/process pruning, actor-type opt-in instance expiration,
   graceful caller shutdown, committed state snapshots, and an opt-in Minitest
   helper
+- Supervisor role replacement: a role whose thread dies is restarted until
+  shutdown is requested, and dead process records are pruned on an interval
 - SQLite, PostgreSQL, and MySQL integration suites
+- Opt-in cross-process wake-up on PostgreSQL through `WakeUpAdapters.for`, with
+  a listening connection per waiting thread and release on supervisor shutdown
+- Opt-in cross-process wake-up on Redis, the option for MySQL applications,
+  measured at 103.8 ms to 5.7 ms at p50; the `redis` gem stays outside this
+  gem's dependencies
 - Inline RBS generation/validation, Steep, Standard Ruby, Solid Queue's exact
   RuboCop policy, and a warning-free Brakeman scan
-- A JavaScript suite covering the state payload and batched refresh browser
-  modules, run in CI with Node's test runner and jsdom, with every GitHub
-  Actions reference pinned to a commit SHA
+- Compatibility CI across the supported span: Ruby 3.3 and 3.4 against Rails 8.0
+  and 8.1, pinned through `RAILS_VERSION` so the advertised range is verified
+  rather than assumed
+- A JavaScript suite covering every browser module, run in CI with Node's test
+  runner and jsdom, plus a browser suite running the same modules against real
+  Chromium and a real Turbo build, with every GitHub Actions reference pinned to
+  a commit SHA
 
 ## Partially implemented
 
-- Supervisor: starts and drains thread roles, but does not replace a crashed
-  role or run periodic maintenance automatically.
-- Wake-up strategy: in-process signaling plus durable polling and injection are
-  implemented; PostgreSQL `LISTEN/NOTIFY` and optional Redis adapters are not.
-  Signaling cannot cross process boundaries, so a commit in a web process does
-  not wake a broadcast executor in a worker process; that delivery waits up to
-  `polling_interval`, 100 ms by default. This is the largest remaining term in
-  reactive update latency, and neither batching nor state payloads reduce it.
+- Wake-up strategy: in-process signaling, durable polling, injection, and an
+  opt-in PostgreSQL notification adapter are implemented; a Redis adapter is
+  not. In-process signaling cannot cross process boundaries, so without the
+  adapter a commit in a web process does not wake a broadcast executor in a
+  worker process and that delivery waits up to `polling_interval`, 100 ms by
+  default. `WakeUpAdapters.for` removes that delay on PostgreSQL, measured at
+  103.7 ms to 2.9 ms at p50. It is opt-in rather than automatic: it opens a
+  connection per waiting thread outside the pool, and `LISTEN` does not survive
+  a transaction-pooling proxy such as PgBouncer. MySQL has no notification
+  primitive, so MySQL applications keep polling unless they configure the Redis
+  adapter.
 - Realtime: scalar and dependency-driven keyed ERB component replacement or
   morphing, personalized refresh authorization, revision fencing, coalescing,
   reconnect convergence, batched refreshes, and personalized state payloads are
@@ -59,27 +76,19 @@
   distributed per-actor rate limits and global admission control do not.
 - Administration: actor and dead-letter views plus policy hooks exist; richer
   filtering, audit records, and bulk-safe tools do not.
-- Browser module coverage: the state payload and batched refresh modules have
-  JavaScript tests; `component_refresh.js`, which drives individual morph
-  refreshes, does not.
 - Outboxes use portable status rows with polling indexes; future versions may
   introduce narrow ready/claimed membership tables for very large outboxes.
 
 ## Next milestones
 
-1. Add automatic supervisor role replacement and periodic dead-process cleanup.
-2. Add PostgreSQL notification and optional Redis wake-up adapters with latency
-   benchmarks and polling-race tests, removing the cross-process polling delay
-   rather than shrinking it with a smaller `polling_interval`.
-3. Add result lookup by request ID and broader deadlock retry classification.
-4. Add scheduled retention and stale-process maintenance.
-5. Add database/server-version checks and MySQL InnoDB verification at boot.
-6. Add Turbo append intents and expand reconnect coverage in a full browser.
-7. Add distributed rate limits, global admission hooks, and cache-capacity
+1. Add result lookup by request ID and broader deadlock retry classification.
+2. Add scheduled retention and stale-process maintenance.
+3. Add Turbo append intents and expand reconnect coverage in a full browser.
+4. Add distributed rate limits, global admission hooks, and cache-capacity
    eviction.
-8. Expand security scanning and run compatibility CI across supported Rails and
-   Ruby versions.
-9. Benchmark all workloads under documented hardware/database settings and
+5. Expand security scanning. Compatibility CI across supported Rails and Ruby
+   versions is implemented; Ruby 4.0 is not yet in the matrix.
+6. Benchmark all workloads under documented hardware/database settings and
    publish adapter-specific adoption measurements. Throughput, synchronous
    latency, query counts, and the three reactive delivery paths are measured on
    SQLite; adapter-specific and end-to-end browser measurements are not.

data/lib/generators/solid_objects/templates/solid_objects.rb

@@ -58,4 +58,12 @@ SolidObjects.configure do |configuration|
   # configuration.authorize_administration = lambda do |authorization_context:, **|
   #   authorization_context.is_a?(Hash) && authorization_context[:source] == "cli"
   # end
+
+  # Runtime roles poll for work and are woken early by an in-process signal,
+  # which cannot reach another process. On PostgreSQL, notifications remove that
+  # delay. This opens a connection per waiting thread outside the pool and does
+  # not work through a transaction-pooling proxy such as PgBouncer, so it is
+  # opt-in:
+  #
+  # configuration.wake_up_adapter = SolidObjects::WakeUpAdapters.for
 end

data/lib/solid_objects/configuration.rb

@@ -21,6 +21,8 @@ module SolidObjects
     # @rbs @process_heartbeat_interval: Float
     # @rbs @process_alive_threshold: Float
     # @rbs @shutdown_timeout: Float
+    # @rbs @supervisor_monitor_interval: Float
+    # @rbs @dead_process_cleanup_interval: Float
     # @rbs @message_retention: Numeric
     # @rbs @message_retention_by_actor_type: Hash[String, Numeric]
     # @rbs @instance_retention_by_actor_type: Hash[String, Numeric]
@@ -62,6 +64,8 @@ module SolidObjects
       :process_heartbeat_interval,
       :process_alive_threshold,
       :shutdown_timeout,
+      :supervisor_monitor_interval,
+      :dead_process_cleanup_interval,
       :message_retention,
       :message_retention_by_actor_type,
       :instance_retention_by_actor_type,
@@ -102,6 +106,8 @@ module SolidObjects
       @max_attempts = 5
       @retry_delay = ->(attempt) { [ 2**(attempt - 1), 60 ].min.to_f }
       @lock_retry_attempts = 10
+      @supervisor_monitor_interval = 1.0
+      @dead_process_cleanup_interval = 60.0
       @process_heartbeat_interval = 15.0
       @process_alive_threshold = 60.0
       @shutdown_timeout = 15.0
@@ -138,6 +144,10 @@ module SolidObjects
         raise ArgumentError, "table_name_prefix must contain lowercase letters, digits, and underscores"
       end
 
+      unless supervisor_monitor_interval.positive?
+        raise ArgumentError, "supervisor_monitor_interval must be positive"
+      end
+
       unless lease_duration > lease_renewal_interval
         raise ArgumentError, "lease_duration must be greater than lease_renewal_interval"
       end

data/lib/solid_objects/database_adapter.rb

@@ -32,6 +32,43 @@ module SolidObjects
       @fixed_connection = connection_pool ? nil : connection
     end
 
+    # The oldest server the adapter has been exercised against. Reported rather
+    # than enforced: refusing to boot on an untested server would be a worse
+    # failure than running on one.
+    # @rbs () -> Gem::Version?
+    def minimum_server_version
+      nil
+    end
+
+    # @rbs () -> Gem::Version
+    def server_version
+      with_connection do |connection|
+        Gem::Version.new(connection.database_version.to_s)
+      end
+    end
+
+    # One observed version decides both the status and the message. Reading it
+    # again could let a transient failure replace an already determined result.
+    # @rbs (?Gem::Version?) -> Array[String]
+    def unsupported_server_reasons(observed = nil)
+      observed ||= server_version
+      reasons = []
+      minimum = minimum_server_version
+      if minimum && observed < minimum
+        reasons << "#{self.class.name.demodulize} #{observed} is older than " \
+          "Solid Objects requires, which is #{minimum}"
+      end
+      reasons.concat(additional_server_reasons)
+      reasons
+    rescue => error
+      [ "the database server could not be verified: #{error.class}: #{error.message}" ]
+    end
+
+    # @rbs () -> Array[String]
+    def additional_server_reasons
+      []
+    end
+
     # @rbs () -> bool
     def supports_skip_locked?
       false

data/lib/solid_objects/database_adapters/mysql.rb

@@ -13,6 +13,34 @@ module SolidObjects
         "FOR UPDATE SKIP LOCKED"
       end
 
+      # A non-transactional engine would silently break fenced commits, so the
+      # storage engine is verified rather than assumed.
+      # @rbs () -> Array[String]
+      def additional_server_reasons
+        tables = non_innodb_tables
+        return [] if tables.empty?
+
+        [ "these Solid Objects tables do not use InnoDB, so their commits are " \
+          "not transactional: #{tables.join(", ")}" ]
+      end
+
+      # @rbs () -> Array[String]
+      def non_innodb_tables
+        names = SolidObjects::Doctor::EXPECTED_COLUMNS.keys.map { |name| SolidObjects.table_name(name) }
+        with_connection do |connection|
+          connection.select_rows(<<~SQL.squish).filter_map { |table, engine| table if engine != "InnoDB" }
+            SELECT table_name, engine FROM information_schema.tables
+            WHERE table_schema = DATABASE()
+              AND table_name IN (#{names.map { |name| connection.quote(name) }.join(", ")})
+          SQL
+        end
+      end
+
+      # @rbs () -> Gem::Version?
+      def minimum_server_version
+        Gem::Version.new("8.0")
+      end
+
       # @rbs () -> String
       def current_time_expression
         "CURRENT_TIMESTAMP(6)"

data/lib/solid_objects/database_adapters/postgresql.rb

@@ -3,6 +3,21 @@
 module SolidObjects
   module DatabaseAdapters
     class Postgresql < DatabaseAdapter
+      # @rbs () -> Gem::Version?
+      def minimum_server_version
+        Gem::Version.new("13")
+      end
+
+      # PostgreSQL reports a packed integer, 170010 for 17.10, so comparing it
+      # directly would make every server look newer than any minimum.
+      # @rbs () -> Gem::Version
+      def server_version
+        packed = with_connection { |connection| connection.database_version.to_i }
+        return super unless packed.positive?
+
+        Gem::Version.new("#{packed / 10_000}.#{packed % 10_000}")
+      end
+
       # @rbs () -> bool
       def supports_skip_locked?
         true

data/lib/solid_objects/database_adapters/sqlite.rb

@@ -8,6 +8,11 @@ module SolidObjects
       LOCK_RETRY_MUTEX = Thread::Mutex.new
       LOCK_RETRY_CONDITION = Thread::ConditionVariable.new
 
+      # @rbs () -> Gem::Version?
+      def minimum_server_version
+        Gem::Version.new("3.35")
+      end
+
       # @rbs () -> String
       def current_time_expression
         "STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')"
@@ -160,13 +165,15 @@ module SolidObjects
         end
       end
 
+      # The deadline can expire between the check above and this wait, which
+      # would otherwise ask for a negative interval.
       # @rbs () -> void
       def wait_before_retry
+        interval = [ LOCK_RETRY_INTERVAL, SyncDeadline.remaining ].min
+        return unless interval.positive?
+
         LOCK_RETRY_MUTEX.synchronize do
-          LOCK_RETRY_CONDITION.wait(
-            LOCK_RETRY_MUTEX,
-            [ LOCK_RETRY_INTERVAL, SyncDeadline.remaining ].min
-          )
+          LOCK_RETRY_CONDITION.wait(LOCK_RETRY_MUTEX, interval)
         end
       end
     end

data/lib/solid_objects/doctor.rb

@@ -111,6 +111,7 @@ module SolidObjects
         configuration_check,
         schema_check,
         check_authorization,
+        check_database_server,
         schema_check.failed? ? skipped_runtime : check_runtime,
         ready_for_round_trip?(configuration_check, schema_check) ?
           check_sync_round_trip :
@@ -191,6 +192,21 @@ module SolidObjects
       pass(:authorization, "#{allowed.length} of 5 policies allowed a neutral context")
     end
 
+    # @rbs () -> Check
+    def check_database_server
+      adapter = SolidObjects.database_adapter
+      observed = adapter.server_version
+      reasons = adapter.unsupported_server_reasons(observed)
+      return warn_check(:database_server, reasons.join("; ")) unless reasons.empty?
+
+      pass(
+        :database_server,
+        "#{adapter.class.name.demodulize} #{observed} meets the tested minimum"
+      )
+    rescue => error
+      warn_check(:database_server, "#{error.class}: #{error.message}")
+    end
+
     # @rbs () -> Check
     def check_runtime
       cutoff = SolidObjects.database_adapter.database_now -