solid_objects 0.7.3 → 0.9.0

data/sig/generated/lib/solid_objects/supervisor.rbs

@@ -2,12 +2,18 @@
 
 module SolidObjects
   class Supervisor
-    @components: Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
+    @lifecycle: Thread::Mutex
 
-    @threads: Array[Thread]
+    @cleaned_up_at: Float
 
     @started: bool
 
+    @monitor: Thread?
+
+    @threads: Array[Thread]
+
+    @components: Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
+
     # @rbs (?worker_count: Integer, ?effect_worker_count: Integer, ?broadcast_worker_count: Integer, ?reminder_scheduler_count: Integer) -> void
     def initialize: (?worker_count: Integer, ?effect_worker_count: Integer, ?broadcast_worker_count: Integer, ?reminder_scheduler_count: Integer) -> void
 
@@ -26,6 +32,43 @@ module SolidObjects
 
     attr_reader threads: untyped
 
+    # A role that raises leaves its thread dead. Without replacement the
+    # process keeps running while quietly doing less work, so the supervisor
+    # watches its threads and restarts any that stopped before shutdown.
+    # A failing pass must not stop supervision, and must not retry without
+    # pacing either: a persistently failing database would otherwise spin.
+    # @rbs () -> void
+    def monitor_loop: () -> void
+
+    # A role that raises runs its own shutdown cleanup on the way out, so a
+    # crashed component reports itself stopped exactly like one that was asked
+    # to stop. While the supervisor is still running, a dead thread can only
+    # mean a crash, so replacement keys on the supervisor rather than on the
+    # component. The crashed instance has already released its process record,
+    # so a fresh one takes its place.
+    # @rbs () -> void
+    def replace_dead_roles: () -> void
+
+    # @rbs (Thread?) -> String?
+    def thread_error: (Thread?) -> String?
+
+    # @rbs () -> void
+    def cleanup_dead_processes: () -> void
+
+    # @rbs (untyped) -> Thread
+    def supervise: (untyped) -> Thread
+
+    # The monitor only performs maintenance, so shutdown must never return while
+    # it is still alive: a pass blocked on the database would otherwise outlive
+    # the supervisor that owns it.
+    # @rbs () -> void
+    def stop_monitor: () -> void
+
+    # A wake-up adapter may hold connections outside the pool, which would
+    # otherwise accumulate across restarts in one process.
+    # @rbs () -> void
+    def release_wake_up: () -> void
+
     # @rbs (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
     def build_components: (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
 

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

@@ -0,0 +1,75 @@
+# 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
+
+      @connections: Array[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
+
+      attr_reader connections: untyped
+
+      # @rbs () -> void
+      def notify_channel: () -> void
+
+      # A listening connection is dedicated and per thread. `LISTEN` is per
+      # connection, a blocking wait must not hold a connection the rest of the
+      # runtime needs, and one connection cannot serve concurrent waiters: the
+      # supervisor shares one adapter across roles, and a notification consumed
+      # by one waiter would leave the others asleep until their poll expired.
+      # @rbs () -> untyped
+      def listening_connection: () -> untyped
+
+      # @rbs () -> untyped
+      def open_listening_connection: () -> untyped
+
+      # @rbs () -> Symbol
+      def thread_key: () -> Symbol
+
+      # @rbs (untyped) -> void
+      def disconnect: (untyped) -> void
+
+      # @rbs (Numeric) -> void
+      def pace_after_failure: (Numeric) -> void
+
+      # @rbs (Symbol, Exception) -> void
+      def instrument_failure: (Symbol, Exception) -> void
+    end
+  end
+end

data/sig/generated/lib/solid_objects/wake_up_adapters/redis.rbs

@@ -0,0 +1,96 @@
+# Generated from lib/solid_objects/wake_up_adapters/redis.rb with RBS::Inline
+
+module SolidObjects
+  module WakeUpAdapters
+    # Wakes runtime roles across processes using Redis publish/subscribe.
+    #
+    # MySQL has no notification primitive, so this is the cross-process option
+    # for applications that cannot use PostgreSQL notifications. It is optional
+    # in every sense: the `redis` gem is not a dependency of this gem, and the
+    # polling interval remains the upper bound, so a missed or failed
+    # notification costs latency rather than correctness.
+    class Redis
+      CHANNEL: ::String
+
+      FAILED_WAIT_INTERVAL: ::Float
+
+      SUBSCRIBE_TIMEOUT: ::Float
+
+      @signalled: Integer
+
+      @subscription: untyped
+
+      @subscriber: Thread?
+
+      @condition: Thread::ConditionVariable
+
+      @mutex: Thread::Mutex
+
+      @client: untyped
+
+      @url: String?
+
+      @channel: String
+
+      attr_reader channel: untyped
+
+      # @rbs (?channel: String, ?url: String?, ?client: untyped) -> void
+      def initialize: (?channel: String, ?url: String?, ?client: untyped) -> void
+
+      # @rbs () -> bool
+      def signal: () -> bool
+
+      # The counter is snapshotted before subscribing, and re-checked before
+      # blocking, so a signal delivered while this caller was still getting
+      # ready is observed rather than absorbed into the new baseline.
+      # @rbs (timeout: Numeric) -> bool
+      def wait: (timeout: Numeric) -> bool
+
+      # Redis delivers to a subscribed connection only, and a subscribed
+      # connection cannot serve other callers, so one background subscription
+      # per process fans out to every waiting role in memory. Subscribing
+      # eagerly also closes the window where a signal sent during startup would
+      # be missed.
+      # @rbs () -> bool
+      def listen: () -> bool
+
+      # @rbs () -> bool
+      def stop: () -> bool
+
+      private
+
+      attr_reader mutex: untyped
+
+      attr_reader condition: untyped
+
+      attr_reader url: untyped
+
+      # @rbs (Queue) -> void
+      def subscribe_loop: (Queue) -> void
+
+      # @rbs () -> void
+      def broadcast: () -> void
+
+      # @rbs (Numeric) -> bool
+      def paced_failure: (Numeric) -> bool
+
+      # @rbs () -> untyped
+      def publisher: () -> untyped
+
+      # @rbs () -> untyped
+      def build_client: () -> untyped
+
+      # @rbs () -> void
+      def validate_client!: () -> void
+
+      # @rbs (untyped) -> void
+      def disconnect: (untyped) -> void
+
+      # @rbs (Numeric) -> void
+      def pace_after_failure: (Numeric) -> void
+
+      # @rbs (Symbol, Exception) -> void
+      def instrument_failure: (Symbol, Exception) -> void
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# Generated from lib/solid_objects/wake_up_adapters.rb with RBS::Inline
+
+module SolidObjects
+  module WakeUpAdapters
+    # Returns the best wake-up strategy for a connection: cross-process
+    # notifications where the database provides them, and the in-process
+    # default everywhere else.
+    #
+    # This is deliberately not the default. A notification adapter opens a
+    # connection per waiting thread outside the pool, and `LISTEN` does not
+    # survive a transaction-pooling proxy such as PgBouncer, so adopting it is
+    # a deployment decision rather than an upgrade side effect.
+    #
+    # @rbs (?untyped) -> untyped
+    def self?.for: (?untyped) -> untyped
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.9.0
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -319,6 +319,7 @@ files:
 - docs/development.md
 - docs/fit.md
 - docs/implementation-plan.md
+- docs/local-testing.md
 - docs/migrating-existing-state.md
 - docs/operations.md
 - docs/realtime.md
@@ -403,6 +404,9 @@ files:
 - lib/solid_objects/turbo_stream_renderer.rb
 - lib/solid_objects/version.rb
 - lib/solid_objects/wake_up.rb
+- lib/solid_objects/wake_up_adapters.rb
+- lib/solid_objects/wake_up_adapters/postgresql.rb
+- lib/solid_objects/wake_up_adapters/redis.rb
 - lib/solid_objects/worker.rb
 - lib/tasks/solid_objects_tasks.rake
 - sig/generated/controllers/solid_objects/application_controller.rbs
@@ -474,6 +478,9 @@ files:
 - sig/generated/lib/solid_objects/turbo_stream_renderer.rbs
 - sig/generated/lib/solid_objects/version.rbs
 - sig/generated/lib/solid_objects/wake_up.rbs
+- sig/generated/lib/solid_objects/wake_up_adapters.rbs
+- sig/generated/lib/solid_objects/wake_up_adapters/postgresql.rbs
+- sig/generated/lib/solid_objects/wake_up_adapters/redis.rbs
 - sig/generated/lib/solid_objects/worker.rbs
 - sig/generated/models/solid_objects/broadcast.rbs
 - sig/generated/models/solid_objects/claimed_message.rbs