solid_objects 0.8.0 → 0.10.0

data/lib/solid_objects/wake_up_adapters/redis.rb

@@ -0,0 +1,183 @@
+# rbs_inline: enabled
+
+require "timeout"
+
+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 = "solid_objects_wake_up"
+      FAILED_WAIT_INTERVAL = 0.05
+      SUBSCRIBE_TIMEOUT = 5.0
+
+      # @rbs @channel: String
+      # @rbs @url: String?
+      # @rbs @client: untyped
+      # @rbs @mutex: Thread::Mutex
+      # @rbs @condition: Thread::ConditionVariable
+      # @rbs @subscriber: Thread?
+      # @rbs @subscription: untyped
+      # @rbs @signalled: Integer
+
+      attr_reader :channel
+
+      # @rbs (?channel: String, ?url: String?, ?client: untyped) -> void
+      def initialize(channel: CHANNEL, url: nil, client: nil)
+        @channel = channel
+        @url = url
+        @client = client
+        @mutex = Thread::Mutex.new
+        @condition = Thread::ConditionVariable.new
+        @subscriber = nil
+        @subscription = nil
+        @signalled = 0
+        validate_client!
+      end
+
+      # @rbs () -> bool
+      def signal
+        publisher.publish(channel, "1")
+        true
+      rescue => error
+        instrument_failure(:signal, error)
+        false
+      end
+
+      # 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:)
+        signalled = mutex.synchronize { @signalled }
+        return paced_failure(timeout) unless listen
+
+        mutex.synchronize do
+          return true unless @signalled == signalled
+
+          condition.wait(mutex, timeout.to_f)
+          @signalled != signalled
+        end
+      end
+
+      # 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
+        mutex.synchronize do
+          return true if @subscriber&.alive?
+
+          ready = Queue.new
+          @subscriber = Thread.new { subscribe_loop(ready) }
+          Timeout.timeout(SUBSCRIBE_TIMEOUT) { ready.pop } == :subscribed
+        end
+      rescue => error
+        instrument_failure(:listen, error)
+        false
+      end
+
+      # @rbs () -> bool
+      def stop
+        subscriber = mutex.synchronize do
+          thread = @subscriber
+          @subscriber = nil
+          thread
+        end
+        return false unless subscriber
+
+        disconnect(@subscription)
+        subscriber.join(SUBSCRIBE_TIMEOUT)
+        subscriber.kill if subscriber.alive?
+        true
+      end
+
+      private
+
+      attr_reader :mutex, :condition, :url
+
+      # @rbs (Queue) -> void
+      def subscribe_loop(ready)
+        connection = build_client
+        @subscription = connection
+        connection.subscribe(channel) do |on|
+          on.subscribe { ready << :subscribed }
+          on.message { broadcast }
+        end
+      rescue => error
+        instrument_failure(:subscribe, error)
+        ready << :failed
+      end
+
+      # @rbs () -> void
+      def broadcast
+        mutex.synchronize do
+          @signalled += 1
+          condition.broadcast
+        end
+      end
+
+      # @rbs (Numeric) -> bool
+      def paced_failure(timeout)
+        pace_after_failure(timeout)
+        false
+      end
+
+      # @rbs () -> untyped
+      def publisher
+        @publisher ||= build_client
+      end
+
+      # @rbs () -> untyped
+      def build_client
+        return @client.call if @client.respond_to?(:call)
+
+        require "redis"
+        url ? ::Redis.new(url:) : ::Redis.new
+      rescue LoadError
+        raise ArgumentError,
+          "the redis gem is required for SolidObjects::WakeUpAdapters::Redis"
+      end
+
+      # @rbs () -> void
+      def validate_client!
+        return if @client.nil? || @client.respond_to?(:call)
+
+        raise ArgumentError, "client must respond to call and return a Redis client"
+      end
+
+      # @rbs (untyped) -> void
+      def disconnect(connection)
+        connection&.close
+      rescue
+        nil
+      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: "redis",
+          operation: operation.to_s,
+          error_class: error.class.name,
+          error_message: error.message
+        )
+      end
+    end
+  end
+end

data/lib/solid_objects.rb

@@ -13,6 +13,7 @@ require "securerandom"
 require "solid_objects/version"
 require "solid_objects/errors"
 require "solid_objects/sync_deadline"
+require "solid_objects/callable_keywords"
 require "solid_objects/configuration"
 require "solid_objects/instrumentation"
 require "solid_objects/log_subscriber"
@@ -47,6 +48,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/wake_up_adapters/redis"
 require "solid_objects/wake_up_adapters"
 require "solid_objects/effect_registry"
 require "solid_objects/commit_action_registry"

data/sig/generated/controllers/solid_objects/components_controller.rbs

@@ -27,14 +27,6 @@ module SolidObjects
     # @rbs (Array[ComponentRegistration]) -> untyped
     def component_authorization_context: (Array[ComponentRegistration]) -> untyped
 
-    # A lambda answers `parameters` directly; a callable object answers it
-    # through its `call` method.
-    # @rbs (untyped) -> bool
-    def accepts_registrations?: (untyped) -> bool
-
-    # @rbs (untyped) -> Array[[ Symbol, Symbol ]]
-    def callable_parameters: (untyped) -> Array[[ Symbol, Symbol ]]
-
     # @rbs (ComponentRegistration) -> Hash[Symbol, untyped]
     def registration_payload: (ComponentRegistration) -> Hash[Symbol, untyped]
 

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

@@ -21,6 +21,25 @@ module SolidObjects
     # @rbs (ActorSnapshot) -> void
     def transmit_state_payloads: (ActorSnapshot) -> void
 
+    # A payload is one subscriber's view of one name. Letting it raise through
+    # here would reject the subscription or abandon the rest of a broadcast, so
+    # a failure is confined to the payload that caused it and reported. The
+    # exception message is deliberately not instrumented: a payload block reads
+    # actor state, so its message is the one place subscriber state could leak
+    # into logs.
+    #
+    # Returns whether this revision was settled for the name. An unauthorized
+    # payload is settled: the decision is stable, so retrying it would only
+    # re-deliver its authorized siblings.
+    # @rbs (ActorSnapshot, String) -> bool
+    def transmit_state_payload: (ActorSnapshot, String) -> bool
+
+    # Resolves the Cable connection to whatever the application uses as an
+    # authorization subject, so a payload block and `authorize_query` see the
+    # same object a controller render would pass.
+    # @rbs (String) -> untyped
+    def payload_authorization_context: (String) -> untyped
+
     # @rbs (ActorSnapshot) -> bool
     def newer_payload_revision?: (ActorSnapshot) -> bool
 

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

@@ -0,0 +1,16 @@
+# Generated from lib/solid_objects/callable_keywords.rb with RBS::Inline
+
+module SolidObjects
+  # Authorization context resolvers gained keywords after applications had
+  # already written them, so a resolver is called with what it declared it
+  # accepts rather than with everything the caller could offer.
+  module CallableKeywords
+    # @rbs (untyped, Symbol) -> bool
+    def self.accepts?: (untyped, Symbol) -> bool
+
+    # A lambda answers `parameters` directly; a callable object answers it
+    # through its `call` method.
+    # @rbs (untyped) -> Array[[ Symbol, Symbol ]]
+    private def self.parameters: (untyped) -> Array[[ Symbol, Symbol ]]
+  end
+end

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

@@ -31,6 +31,11 @@ module SolidObjects
 
     attr_reader revisions: untyped
 
+    # Live invalidations and reconnect replays share this, so a reconnecting
+    # client pays the same number of requests a connected one does.
+    # @rbs (Array[ComponentRegistration], Integer, Integer) -> Array[String]
+    def refresh_streams: (Array[ComponentRegistration], Integer, Integer) -> Array[String]
+
     # @rbs (ComponentRegistration, Integer, Integer) -> void
     def record_revision: (ComponentRegistration, Integer, Integer) -> void
 

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

@@ -2,10 +2,10 @@
 
 module SolidObjects
   class Configuration
-    @shutdown_timeout: Float
-
     @supervisor_monitor_interval: Float
 
+    @retention_interval: Float
+
     @dead_process_cleanup_interval: Float
 
     @message_retention: Numeric
@@ -40,6 +40,8 @@ module SolidObjects
 
     @component_authorization_context: Proc
 
+    @payload_authorization_context: Proc
+
     @authorize_message: Proc
 
     @authorize_query: Proc
@@ -86,6 +88,8 @@ module SolidObjects
 
     @process_alive_threshold: Float
 
+    @shutdown_timeout: Float
+
     attr_accessor table_name_prefix: untyped
 
     attr_accessor polling_interval: untyped
@@ -126,6 +130,8 @@ module SolidObjects
 
     attr_accessor supervisor_monitor_interval: untyped
 
+    attr_accessor retention_interval: untyped
+
     attr_accessor dead_process_cleanup_interval: untyped
 
     attr_accessor message_retention: untyped
@@ -160,6 +166,8 @@ module SolidObjects
 
     attr_accessor component_authorization_context: untyped
 
+    attr_accessor payload_authorization_context: untyped
+
     attr_accessor authorize_message: untyped
 
     attr_accessor authorize_query: untyped

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

@@ -16,6 +16,23 @@ module SolidObjects
     # @rbs (untyped) -> void
     def initialize: (untyped) -> void
 
+    # 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: () -> Gem::Version?
+
+    # @rbs () -> Gem::Version
+    def server_version: () -> Gem::Version
+
+    # 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: (?Gem::Version?) -> Array[String]
+
+    # @rbs () -> Array[String]
+    def additional_server_reasons: () -> Array[String]
+
     # @rbs () -> bool
     def supports_skip_locked?: () -> bool
 

data/sig/generated/lib/solid_objects/database_adapters/mysql.rbs

@@ -9,6 +9,17 @@ module SolidObjects
       # @rbs () -> String
       def claim_lock: () -> String
 
+      # 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: () -> Array[String]
+
+      # @rbs () -> Array[String]
+      def non_innodb_tables: () -> Array[String]
+
+      # @rbs () -> Gem::Version?
+      def minimum_server_version: () -> Gem::Version?
+
       # @rbs () -> String
       def current_time_expression: () -> String
 

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

@@ -3,6 +3,14 @@
 module SolidObjects
   module DatabaseAdapters
     class Postgresql < DatabaseAdapter
+      # @rbs () -> Gem::Version?
+      def minimum_server_version: () -> Gem::Version?
+
+      # 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: () -> Gem::Version
+
       # @rbs () -> bool
       def supports_skip_locked?: () -> bool
 

data/sig/generated/lib/solid_objects/database_adapters/sqlite.rbs

@@ -11,6 +11,9 @@ module SolidObjects
 
       LOCK_RETRY_CONDITION: untyped
 
+      # @rbs () -> Gem::Version?
+      def minimum_server_version: () -> Gem::Version?
+
       # @rbs () -> String
       def current_time_expression: () -> String
 

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

@@ -72,6 +72,9 @@ module SolidObjects
     # @rbs () -> Check
     def check_authorization: () -> Check
 
+    # @rbs () -> Check
+    def check_database_server: () -> Check
+
     # @rbs () -> Check
     def check_runtime: () -> Check
 

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

@@ -29,6 +29,19 @@ module SolidObjects
     # @rbs (ActorDefinition::Handler) -> untyped
     def rendered_payload: (ActorDefinition::Handler) -> untyped
 
+    # The block runs against the actor instance, like every other block in the
+    # actor DSL, and still receives the actor and the resolved authorization
+    # context as arguments, so blocks written to the documented signature are
+    # unaffected.
+    # @rbs (ActorDefinition::Handler) -> untyped
+    def evaluated_payload: (ActorDefinition::Handler) -> untyped
+
+    # Distinguishes a block that relied on the old class-level receiver from an
+    # ordinary typo, so the one behaviour change reports itself instead of
+    # surfacing as an unexplained NameError.
+    # @rbs (NameError[untyped]) -> bool
+    def class_level_receiver?: (NameError[untyped]) -> bool
+
     # @rbs () -> void
     def authorize!: () -> void
   end

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

@@ -2,8 +2,12 @@
 
 module SolidObjects
   class Supervisor
+    MAXIMUM_RETENTION_BACKOFF_DOUBLINGS: ::Integer
+
     @lifecycle: Thread::Mutex
 
+    @retention: Thread?
+
     @cleaned_up_at: Float
 
     @started: bool
@@ -52,6 +56,34 @@ module SolidObjects
     # @rbs (Thread?) -> String?
     def thread_error: (Thread?) -> String?
 
+    # Retention gets its own thread rather than sharing the monitor's. A large
+    # backlog or a lock wait can make a pass slow, and role replacement must not
+    # wait behind housekeeping.
+    # @rbs () -> void
+    def retention_loop: () -> void
+
+    # Sleeping the whole interval would make shutdown wait out an hour-long
+    # nap, so the pause is taken in short steps that notice a stop request.
+    # @rbs (Integer) -> void
+    def wait_for_next_retention: (Integer) -> void
+
+    # Every actor call writes a durable message row, so retention that is only
+    # configured and never run leaves those rows to grow without bound. The
+    # supervisor runs it rather than requiring every application to schedule
+    # its own job.
+    # @rbs () -> void
+    def prune_expired_records: () -> void
+
+    # A transient lock or connection error must not defer retention for the
+    # whole interval, so a failed pass retries at monitor cadence. The pause
+    # then doubles per consecutive failure, capped by the interval, so a
+    # database that stays down is not polled once a second forever.
+    # @rbs (Integer) -> Float
+    def retention_pause: (Integer) -> Float
+
+    # @rbs () -> void
+    def stop_retention: () -> void
+
     # @rbs () -> void
     def cleanup_dead_processes: () -> void
 

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Lucas Carlson
@@ -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
@@ -353,6 +354,7 @@ files:
 - lib/solid_objects/application_actor_loader.rb
 - lib/solid_objects/application_write_guard.rb
 - lib/solid_objects/broadcast_executor.rb
+- lib/solid_objects/callable_keywords.rb
 - lib/solid_objects/caller_process.rb
 - lib/solid_objects/cli.rb
 - lib/solid_objects/client.rb
@@ -405,6 +407,7 @@ files:
 - 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
@@ -426,6 +429,7 @@ files:
 - sig/generated/lib/solid_objects/application_actor_loader.rbs
 - sig/generated/lib/solid_objects/application_write_guard.rbs
 - sig/generated/lib/solid_objects/broadcast_executor.rbs
+- sig/generated/lib/solid_objects/callable_keywords.rbs
 - sig/generated/lib/solid_objects/caller_process.rbs
 - sig/generated/lib/solid_objects/cli.rbs
 - sig/generated/lib/solid_objects/client.rbs
@@ -478,6 +482,7 @@ files:
 - 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