Keep a keyed reminder name from colliding or overflowing

A keyed name is the operation, a colon, and the key, so an operation
holding a colon of its own made two different schedules produce one name.
An unkeyed "deliver:item" and a "deliver" keyed "item" shared a row, and
the second silently took the first one's alarm along with its operation
and arguments. Refusing a colon in the operation keeps unkeyed names free
of colons, which leaves the two kinds disjoint, and a key may still hold
colons of its own because the operation before the first one cannot.

The length was checked on the key alone, so a long operation with a valid
key composed a name past the 191 characters the column holds and raised
on the insert with the turn already doing work. It is checked on the
composed name now, which catches both ends.

Author: cardmagic

CHANGELOG.md

@@ -6,7 +6,10 @@
   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.
+  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.
 
 ## 0.13.1 - 2026-08-16
 

README.md

@@ -922,8 +922,14 @@ 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 at most 128 characters, because the name it becomes
-shares a 191-character column with the operation.
+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
 

lib/solid_objects/actor.rb

@@ -4,9 +4,9 @@ module SolidObjects
   class Actor
     EffectIntent = Data.define(:name, :arguments, :success_operation, :failure_operation)
     CommitActionIntent = Data.define(:name, :arguments)
-    # The reminders table holds a name in 191 characters, and a name is an
-    # operation, a colon, and a key.
-    REMINDER_KEY_LIMIT = 128
+    # 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)
@@ -223,7 +223,7 @@ def schedule(at:, every: nil, missed: :latest, key: nil)
         handlers: self.class.definition.messages
       ) do |operation, arguments|
         ReminderIntent.new(
-          name: reminder_key ? "#{operation}:#{reminder_key}" : operation.to_s,
+          name: reminder_name(operation:, key: reminder_key),
           operation: operation.to_s,
           at:,
           arguments: Serialization.dump(arguments),
@@ -236,24 +236,45 @@ def schedule(at:, every: nil, missed: :latest, key: nil)
       end
     end
 
-    # The key becomes part of the reminder name, which the database holds in 191
-    # characters alongside the operation, so it is bounded here rather than
-    # failing on the insert once the turn is already doing work.
     # @rbs ((String | Symbol | Integer)?) -> String?
     def validated_reminder_key(key)
       return nil if key.nil?
 
       reminder_key = key.to_s
-      if reminder_key.empty?
-        raise ArgumentError, "reminder key must not be empty"
-      end
-      if reminder_key.length > REMINDER_KEY_LIMIT
-        raise ArgumentError, "reminder key must be at most #{REMINDER_KEY_LIMIT} characters"
-      end
+      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)

sig/generated/lib/solid_objects/actor.rbs

@@ -32,9 +32,10 @@ module SolidObjects
       def members: () -> [ :name, :arguments ]
     end
 
-    # The reminders table holds a name in 191 characters, and a name is an
-    # operation, a colon, and a key.
-    REMINDER_KEY_LIMIT: ::Integer
+    # The reminders table holds a name in 191 characters.
+    REMINDER_NAME_LIMIT: ::Integer
+
+    REMINDER_KEY_SEPARATOR: ::String
 
     class ReminderIntent < Data
       attr_reader name(): untyped
@@ -171,12 +172,23 @@ module SolidObjects
     # @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
 
-    # The key becomes part of the reminder name, which the database holds in 191
-    # characters alongside the operation, so it is bounded here rather than
-    # failing on the insert once the turn is already doing work.
     # @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
 

test/unit/actor_test.rb

@@ -69,6 +69,28 @@ def reset
     assert CartActor.definition.queries.key?(:items)
   end
 
+  class ColonOperationActor < SolidObjects::Actor
+    actor_type "test-colon-operation"
+
+    message("fire:item") { nil }
+
+    def arm
+      schedule(at: Time.now.utc + 60).public_send(:"fire:item")
+    end
+  end
+
+  class LongOperationActor < SolidObjects::Actor
+    actor_type "test-long-operation"
+
+    LONG_OPERATION = ("o" * 100).freeze
+
+    message(LONG_OPERATION) { nil }
+
+    def arm(key:)
+      schedule(at: Time.now.utc + 60, key:).public_send(LONG_OPERATION.to_sym)
+    end
+  end
+
   class KeyedReminderActor < SolidObjects::Actor
     actor_type "test-keyed-reminders"
 
@@ -104,12 +126,38 @@ def fire
     assert_raises(ArgumentError) { actor.invoke("arm", { "key" => "" }) }
   end
 
-  test "a reminder key too long for the name column is refused" do
+  test "a composed reminder name too long for the column is refused" do
     actor = keyed_reminder_actor
 
     assert_raises(ArgumentError) { actor.invoke("arm", { "key" => "k" * 200 }) }
   end
 
+  # An unkeyed "fire:item" and a "fire" keyed "item" would otherwise be one name.
+  test "a reminder operation holding the key separator is refused" do
+    actor = SolidObjects::State.new(ColonOperationActor.definition.state_definition).then do |state|
+      ColonOperationActor.new(actor_id: "unit", state:)
+    end
+
+    assert_raises(ArgumentError) { actor.invoke("arm", {}) }
+  end
+
+  test "a key may hold the separator, since the operation may not" do
+    actor = keyed_reminder_actor
+    actor.invoke("arm", { "key" => "group:7" })
+    intent = actor.drain_reminder_intents.sole
+
+    assert_equal "fire:group:7", intent.name
+    assert_equal "fire", intent.operation
+  end
+
+  test "a long operation with a short key is refused when together they overflow" do
+    actor = SolidObjects::State.new(LongOperationActor.definition.state_definition).then do |state|
+      LongOperationActor.new(actor_id: "unit", state:)
+    end
+
+    assert_raises(ArgumentError) { actor.invoke("arm", { "key" => "k" * 120 }) }
+  end
+
   test "reads and writes attributes through actor methods" do
     actor = SolidObjects::State.new(CounterActor.definition.state_definition).then do |state|
       CounterActor.new(actor_id: "global", state:)