solid_objects 0.13.1 → 0.13.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5bd1724baaa40d79ec3693558ef7aa8e37830e4c5afd1da1d5774356d1e584e
-  data.tar.gz: 1e7a2307cae51316b9b4c4f56ea6fc986a622e3665541514137d87bbf72b2e9a
+  metadata.gz: c1043a832a75d5e7d2c9e59b332c3c6bce85a322204fdc2a056dc5198018d34d
+  data.tar.gz: 4b1505d23bab1aeb57dc722a8a613fd3c39911d2756e24c37714466e4c821b22
 SHA512:
-  metadata.gz: b1b5284ef616f306bea2136d7becf4a3c8e4aa2adbcc24eb5da08c3f33e85f34551f687ff7133cd3781abba79d4f0dac919657d9150bfe3ebd021417542d505b
-  data.tar.gz: 6971c0ee78d9eab66776a5ba6d60dcc403d3346c57cffca795797f50048fc419b6473d3d620c4d025238916757f52ed79ed1ec153feaa3dda84744d740b08045
+  metadata.gz: 2d7c216e135b8e34c19b9130a0fcad0df6246191ee097f9a560497d0dacc47fc480e549c1ddd6ab2bc6fe9bc513245236aa47cc1650a08906a04367d0e6bd008
+  data.tar.gz: d1dc2001e0b43a2df5eb24c5cd79c6e1df99b2d6c46c90146a349dd09a557db9dcdaa7c51e51a47f5db1667b364c2dfe64d5ba73fe877248a0143e022045c764

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.13.2 - 2026-08-17
+
+- Accept a `key:` on `schedule`, naming a reminder for the item it is waiting
+  on rather than for its operation, so one actor can hold an alarm per queued
+  item. Scheduling the same key again moves that item's alarm and leaves the
+  others alone. Without a key the name is still the operation, so existing
+  reminders keep their names and their coalescing behaviour. A reminder
+  operation may no longer hold the colon that separates a key, which keeps
+  keyed and unkeyed names disjoint, and the length is checked on the composed
+  name rather than the key alone.
+- Add an authorized `SolidObjects.administration.processes` query for
+  inspecting live and stale process rows through the runtime database adapter.
+- Document rolling-deployment overlap as a reason for the polling-only warning.
+
 ## 0.13.1 - 2026-08-16
 
 - Back idle actor, effect, reminder, and broadcast polling off exponentially

data/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/cardmagic/solid_objects/actions/workflows/ci.yml/badge.svg)](https://github.com/cardmagic/solid_objects/actions/workflows/ci.yml)
 
-**Cloudflare Durable Objects, ported to Rails.**
+**Self-hosted, distributed Durable Objects in Rails without a daemon using your existing SQL database.**
 
 Solid Objects brings the Durable Objects programming model—addressable objects,
 durable state, serialized turns, alarms, and live clients—to ordinary Rails
@@ -891,7 +891,7 @@ database enforces this with a unique index on `(instance_id, name)`.
 
 This is the same model as Orleans reminders and Durable Objects alarms, and it
 is what makes a reminder safe to re-arm from a handler that may run more than
-once. It also means this is a data-loss bug:
+once. Without a key the name is the operation, so this is a data-loss bug:
 
 ```ruby
 # Wrong. Every entry overwrites the previous entry's alarm.
@@ -904,8 +904,38 @@ end
 Two entries leave one reminder. The earlier wake-up never happens, nothing
 raises, and nothing is logged except a `solid_objects.reminder.replaced` event.
 
-Arm one alarm for the earliest item instead, and let the handler drain
-everything now due before arming the next:
+### An alarm per item, with `key:`
+
+Pass `key:` when an actor is waiting on several things at once. The key is your
+own identifier for the item, and it names that item's alarm, so each item gets
+one:
+
+```ruby
+def add(entry:)
+  self.entries = entries + [ entry ]
+  schedule(at: entry.fetch("wait_until"), key: entry.fetch("id")).deliver
+end
+```
+
+Two entries now leave two reminders. Scheduling the same key again moves that
+item's alarm and leaves the others alone, which is what makes a keyed reminder
+as safe to re-arm as an unkeyed one. The operation still decides which handler
+runs; the key only decides which alarm is which.
+
+A key must be non-empty, and the name it becomes must fit the 191-character
+column, which is checked on the composed name rather than the key alone so a
+long operation and a short key are caught too.
+
+The key is separated from the operation by a colon, so an operation may not hold
+one. Otherwise an unkeyed `deliver:item` and a `deliver` keyed `item` would be
+one name, and the second would silently take the first one's alarm. A key may
+hold colons of its own, because the operation before the first one cannot.
+
+### One alarm for a whole queue
+
+A key per item is not always what you want. An actor that only ever needs to
+know "what is next" can keep one alarm and let the handler drain everything now
+due before arming the next:
 
 ```ruby
 def add(entry:)
@@ -931,10 +961,10 @@ def arm_next
 end
 ```
 
-`deliver` drains every due item rather than one, so a single alarm serves a
-whole queue and a missed or coalesced occurrence cannot strand an entry. Use a
-distinct reminder name only when you genuinely need two independent alarms on
-one actor, such as `:deliver` and `:sweep`.
+That costs one reminder row instead of one per item, and a coalesced occurrence
+cannot strand an entry because the handler drains by time rather than by alarm.
+Prefer it when the queue is large and the items are interchangeable; prefer
+`key:` when an item needs its own alarm that can be moved on its own.
 
 Solid Objects has no `unschedule`. A reminder stops when its handler does not
 re-arm it, and destroying an actor removes its reminders.

data/docs/operations.md

@@ -98,6 +98,14 @@ adapter is configured, the runtime logs
 need prompt delivery. Without one, newly committed work can wait up to the
 current idle polling interval.
 
+The warning excludes process rows with the current hostname and PID. It can
+therefore appear during a rolling deployment or restart overlap when an older
+and newer process briefly share the database. A process that stopped without
+graceful cleanup remains live until its heartbeat exceeds
+`process_alive_threshold`; inspect `SolidObjects.administration.processes` to
+distinguish a live overlap from a stale row without opening a second SQLite
+connection.
+
 Each role exposes `current_polling_interval`.
 `solid_objects.polling.interval_changed` reports the role, reason, previous
 interval, and current interval. The polling-only warning is also emitted as

data/lib/solid_objects/actor.rb

@@ -4,7 +4,11 @@ module SolidObjects
   class Actor
     EffectIntent = Data.define(:name, :arguments, :success_operation, :failure_operation)
     CommitActionIntent = Data.define(:name, :arguments)
-    ReminderIntent = Data.define(:name, :at, :arguments, :interval_seconds, :missed_policy)
+    # The reminders table holds a name in 191 characters.
+    REMINDER_NAME_LIMIT = 191
+    REMINDER_KEY_SEPARATOR = ":"
+
+    ReminderIntent = Data.define(:name, :operation, :at, :arguments, :interval_seconds, :missed_policy)
     OutboundMessageIntent = Data.define(:actor_type, :actor_id, :operation, :arguments, :available_at, :idempotency_key)
 
     class << self
@@ -197,8 +201,13 @@ module SolidObjects
       nil
     end
 
-    # @rbs (at: Time, ?every: Numeric?, ?missed: Symbol | String) -> OperationDispatcher
-    def schedule(at:, every: nil, missed: :latest)
+    # A reminder is identified by its name, and without a key that name is the
+    # operation, so one actor holds one alarm per operation. A key gives an actor
+    # an alarm per item it is waiting on, which is what an actor holding a queue
+    # of scheduled work needs; the key is the caller's own identifier for the
+    # item, and scheduling the same key again moves that item's alarm.
+    # @rbs (at: Time, ?every: Numeric?, ?missed: Symbol | String, ?key: (String | Symbol | Integer)?) -> OperationDispatcher
+    def schedule(at:, every: nil, missed: :latest, key: nil)
       interval_seconds = every&.to_f
       if interval_seconds && !interval_seconds.positive?
         raise ArgumentError, "reminder interval must be positive"
@@ -207,13 +216,15 @@ module SolidObjects
       unless %w[all latest].include?(missed_policy)
         raise ArgumentError, "missed reminder policy must be all or latest"
       end
+      reminder_key = validated_reminder_key(key)
 
       OperationDispatcher.new(
         actor_type: self.class.actor_type,
         handlers: self.class.definition.messages
       ) do |operation, arguments|
         ReminderIntent.new(
-          name: operation.to_s,
+          name: reminder_name(operation:, key: reminder_key),
+          operation: operation.to_s,
           at:,
           arguments: Serialization.dump(arguments),
           interval_seconds:,
@@ -225,6 +236,45 @@ module SolidObjects
       end
     end
 
+    # @rbs ((String | Symbol | Integer)?) -> String?
+    def validated_reminder_key(key)
+      return nil if key.nil?
+
+      reminder_key = key.to_s
+      raise ArgumentError, "reminder key must not be empty" if reminder_key.empty?
+
+      reminder_key
+    end
+
+    # A keyed name is the operation, a colon, and the key, so an operation
+    # holding a colon of its own would make two different schedules produce one
+    # name: an unkeyed "deliver:item" and a "deliver" keyed "item" would share a
+    # row, and the second would silently take the first one's alarm. Refusing a
+    # colon in the operation keeps unkeyed names free of colons, which leaves
+    # the two kinds of name disjoint and lets a key hold colons of its own.
+    #
+    # The length is checked on the composed name rather than the key alone,
+    # because a long operation and a short key can exceed the column just as
+    # easily as the reverse. Both are refused here rather than at the insert,
+    # once the turn is already doing work.
+    # @rbs (operation: Symbol | String, key: String?) -> String
+    def reminder_name(operation:, key:)
+      operation_name = operation.to_s
+      if operation_name.include?(REMINDER_KEY_SEPARATOR)
+        raise ArgumentError,
+          "reminder operation #{operation_name.inspect} must not contain #{REMINDER_KEY_SEPARATOR.inspect}"
+      end
+      return operation_name if key.nil?
+
+      name = "#{operation_name}#{REMINDER_KEY_SEPARATOR}#{key}"
+      if name.length > REMINDER_NAME_LIMIT
+        raise ArgumentError,
+          "reminder name #{name.length} characters exceeds the #{REMINDER_NAME_LIMIT} the database holds"
+      end
+
+      name
+    end
+
     # @rbs (Reference, ?available_at: Time?, ?idempotency_key: String?) -> OperationDispatcher
     def send_to(reference, available_at: nil, idempotency_key: nil)
       actor_class = SolidObjects.registry.fetch(reference.actor_type)

data/lib/solid_objects/administration.rb

@@ -0,0 +1,44 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Administration
+    # @rbs (?authorization_context: untyped) -> Array[Hash[Symbol, untyped]]
+    def processes(authorization_context: nil)
+      authorize!(authorization_context:)
+      now = SolidObjects.database_adapter.database_now
+      stale_at = now - SolidObjects.configuration.process_alive_threshold
+
+      Process.order(:kind, :started_at).map do |process_record|
+        {
+          id: process_record.id,
+          kind: process_record.kind,
+          hostname: process_record.hostname,
+          pid: process_record.pid,
+          metadata: Serialization.readonly_copy(process_record.metadata),
+          shutdown_state: process_record.shutdown_state,
+          shutdown_requested_at: process_record.shutdown_requested_at,
+          started_at: process_record.started_at,
+          last_heartbeat_at: process_record.last_heartbeat_at,
+          stopped_at: process_record.stopped_at,
+          stale: process_record.shutdown_state != "stopped" &&
+            process_record.last_heartbeat_at <= stale_at
+        }.freeze
+      end.freeze
+    end
+
+    private
+
+    # @rbs (?authorization_context: untyped) -> void
+    def authorize!(authorization_context: nil)
+      authorized = SolidObjects.configuration.authorize_administration.call(
+        action: :inspect,
+        resource: "processes",
+        resource_id: nil,
+        authorization_context:
+      )
+      return if authorized
+
+      raise Unauthorized, "actor administration is not authorized"
+    end
+  end
+end

data/lib/solid_objects/executor.rb

@@ -223,10 +223,10 @@ module SolidObjects
     end
 
     # A reminder is one named alarm per actor, so scheduling a name that is
-    # already armed moves it rather than adding a second. An actor that arms a
-    # reminder per queued item therefore keeps only the last, and nothing else
-    # about that is visible: the write succeeds and the earlier wake-up simply
-    # never happens.
+    # already armed moves it rather than adding a second. Without a key that
+    # name is the operation, so an actor arming a reminder per queued item keeps
+    # only the last; passing schedule a key gives each item its own name and so
+    # its own alarm.
     # Moves are returned rather than reported here, so the report happens after
     # the turn commits. A rolled back turn would otherwise announce an alarm
     # that never moved, which is the opposite of the visibility this event
@@ -239,7 +239,7 @@ module SolidObjects
         reminder.assign_attributes(
           actor_type: instance.actor_type,
           actor_id: instance.actor_id,
-          operation: intent.name,
+          operation: intent.operation,
           arguments: intent.arguments,
           next_run_at: intent.at,
           interval_seconds: intent.interval_seconds,

data/lib/solid_objects/version.rb

@@ -1,5 +1,5 @@
 # rbs_inline: enabled
 
 module SolidObjects
-  VERSION = "0.13.1"
+  VERSION = "0.13.2"
 end

data/lib/solid_objects.rb

@@ -31,6 +31,7 @@ require "solid_objects/dead_letter_manager"
 require "solid_objects/message_pruner"
 require "solid_objects/instance_pruner"
 require "solid_objects/process_pruner"
+require "solid_objects/administration"
 require "solid_objects/stream_name"
 require "solid_objects/dom_identity"
 require "solid_objects/stream_token"
@@ -137,6 +138,11 @@ module SolidObjects
       @dead_letters ||= DeadLetterManager.new
     end
 
+    # @rbs () -> Administration
+    def administration
+      @administration ||= Administration.new
+    end
+
     # @rbs (String | Symbol) -> String
     def table_name(name)
       "#{configuration.table_name_prefix}#{name}"
@@ -164,6 +170,7 @@ module SolidObjects
       @effect_registry = EffectRegistry.new
       @commit_action_registry = CommitActionRegistry.new
       @dead_letters = nil
+      @administration = nil
     end
 
     # @rbs () -> DatabaseAdapter

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

@@ -32,9 +32,16 @@ module SolidObjects
       def members: () -> [ :name, :arguments ]
     end
 
+    # The reminders table holds a name in 191 characters.
+    REMINDER_NAME_LIMIT: ::Integer
+
+    REMINDER_KEY_SEPARATOR: ::String
+
     class ReminderIntent < Data
       attr_reader name(): untyped
 
+      attr_reader operation(): untyped
+
       attr_reader at(): untyped
 
       attr_reader arguments(): untyped
@@ -43,12 +50,12 @@ module SolidObjects
 
       attr_reader missed_policy(): untyped
 
-      def self.new: (untyped name, untyped at, untyped arguments, untyped interval_seconds, untyped missed_policy) -> instance
-                  | (name: untyped, at: untyped, arguments: untyped, interval_seconds: untyped, missed_policy: untyped) -> instance
+      def self.new: (untyped name, untyped operation, untyped at, untyped arguments, untyped interval_seconds, untyped missed_policy) -> instance
+                  | (name: untyped, operation: untyped, at: untyped, arguments: untyped, interval_seconds: untyped, missed_policy: untyped) -> instance
 
-      def self.members: () -> [ :name, :at, :arguments, :interval_seconds, :missed_policy ]
+      def self.members: () -> [ :name, :operation, :at, :arguments, :interval_seconds, :missed_policy ]
 
-      def members: () -> [ :name, :at, :arguments, :interval_seconds, :missed_policy ]
+      def members: () -> [ :name, :operation, :at, :arguments, :interval_seconds, :missed_policy ]
     end
 
     class OutboundMessageIntent < Data
@@ -157,8 +164,30 @@ module SolidObjects
     # @rbs (Symbol | String, **untyped) -> nil
     def commit_action: (Symbol | String, **untyped) -> nil
 
-    # @rbs (at: Time, ?every: Numeric?, ?missed: Symbol | String) -> OperationDispatcher
-    def schedule: (at: Time, ?every: Numeric?, ?missed: Symbol | String) -> OperationDispatcher
+    # A reminder is identified by its name, and without a key that name is the
+    # operation, so one actor holds one alarm per operation. A key gives an actor
+    # an alarm per item it is waiting on, which is what an actor holding a queue
+    # of scheduled work needs; the key is the caller's own identifier for the
+    # item, and scheduling the same key again moves that item's alarm.
+    # @rbs (at: Time, ?every: Numeric?, ?missed: Symbol | String, ?key: (String | Symbol | Integer)?) -> OperationDispatcher
+    def schedule: (at: Time, ?every: Numeric?, ?missed: Symbol | String, ?key: (String | Symbol | Integer)?) -> OperationDispatcher
+
+    # @rbs ((String | Symbol | Integer)?) -> String?
+    def validated_reminder_key: ((String | Symbol | Integer)?) -> String?
+
+    # A keyed name is the operation, a colon, and the key, so an operation
+    # holding a colon of its own would make two different schedules produce one
+    # name: an unkeyed "deliver:item" and a "deliver" keyed "item" would share a
+    # row, and the second would silently take the first one's alarm. Refusing a
+    # colon in the operation keeps unkeyed names free of colons, which leaves
+    # the two kinds of name disjoint and lets a key hold colons of its own.
+    #
+    # The length is checked on the composed name rather than the key alone,
+    # because a long operation and a short key can exceed the column just as
+    # easily as the reverse. Both are refused here rather than at the insert,
+    # once the turn is already doing work.
+    # @rbs (operation: Symbol | String, key: String?) -> String
+    def reminder_name: (operation: Symbol | String, key: String?) -> String
 
     # @rbs (Reference, ?available_at: Time?, ?idempotency_key: String?) -> OperationDispatcher
     def send_to: (Reference, ?available_at: Time?, ?idempotency_key: String?) -> OperationDispatcher

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

@@ -0,0 +1,13 @@
+# Generated from lib/solid_objects/administration.rb with RBS::Inline
+
+module SolidObjects
+  class Administration
+    # @rbs (?authorization_context: untyped) -> Array[Hash[Symbol, untyped]]
+    def processes: (?authorization_context: untyped) -> Array[Hash[Symbol, untyped]]
+
+    private
+
+    # @rbs (?authorization_context: untyped) -> void
+    def authorize!: (?authorization_context: untyped) -> void
+  end
+end

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

@@ -46,10 +46,10 @@ module SolidObjects
     def enqueue_effects: (message: Message, instance: Instance, intents: Array[Actor::EffectIntent]) -> Array[Effect]
 
     # A reminder is one named alarm per actor, so scheduling a name that is
-    # already armed moves it rather than adding a second. An actor that arms a
-    # reminder per queued item therefore keeps only the last, and nothing else
-    # about that is visible: the write succeeds and the earlier wake-up simply
-    # never happens.
+    # already armed moves it rather than adding a second. Without a key that
+    # name is the operation, so an actor arming a reminder per queued item keeps
+    # only the last; passing schedule a key gives each item its own name and so
+    # its own alarm.
     # Moves are returned rather than reported here, so the report happens after
     # the turn commits. A rolled back turn would otherwise announce an alarm
     # that never moved, which is the opposite of the visibility this event

data/sig/generated/lib/solid_objects.rbs

@@ -36,6 +36,9 @@ module SolidObjects
   # @rbs () -> DeadLetterManager
   def self.dead_letters: () -> DeadLetterManager
 
+  # @rbs () -> Administration
+  def self.administration: () -> Administration
+
   # @rbs (String | Symbol) -> String
   def self.table_name: (String | Symbol) -> String
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.13.2
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -382,6 +382,7 @@ files:
 - lib/solid_objects/actor_registry.rb
 - lib/solid_objects/actor_snapshot.rb
 - lib/solid_objects/actor_view.rb
+- lib/solid_objects/administration.rb
 - lib/solid_objects/application_actor_loader.rb
 - lib/solid_objects/application_write_guard.rb
 - lib/solid_objects/broadcast_executor.rb
@@ -468,6 +469,7 @@ files:
 - sig/generated/lib/solid_objects/actor_registry.rbs
 - sig/generated/lib/solid_objects/actor_snapshot.rbs
 - sig/generated/lib/solid_objects/actor_view.rbs
+- sig/generated/lib/solid_objects/administration.rbs
 - 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