solid_objects 0.12.0 → 0.13.0

data/docs/roadmap.md

@@ -12,7 +12,8 @@
 - Bounded activation passes, idle cache, hot-actor yield, and process records
 - At-least-once retries, terminal domain rejection, strict poison ordering,
   dead letters, and tail retry
-- Transactional effects with success/failure actor messages
+- Transactional effects with success/failure actor messages carrying the
+  originally staged arguments for callback correlation
 - Actor-to-actor asynchronous outbox delivery. Effects and broadcasts use
   portable status rows with polling indexes and database check constraints on
   status, which works on all three adapters; a future version may add narrow
@@ -23,8 +24,11 @@
   listed here while broken in that worker: the scheduler reached a constant the
   caller path happened to load, so reminders never fired in production and
   every in-process test still passed
-- Durable observable invalidations, scalar Turbo replacement, keyed ERB
-  components, signed component locals, and authorized replace or morph refresh
+- Durable invalidation-only observable broadcasts by default, explicit
+  `broadcast: :value` scalar Turbo replacement, keyed ERB components, signed
+  component locals, and authorized replace or morph refresh. Default
+  observables retain component change detection while storing and broadcasting
+  no projected value
 - Batched component refreshes: components sharing a signed `batch:` collapse to
   one browser request per revision, served as HTML frames in a JSON envelope
 - Personalized state payload broadcasts computed per subscriber under that
@@ -45,7 +49,8 @@
 - Bounded message/process pruning, actor-type opt-in instance expiration,
   graceful caller shutdown, committed state snapshots, and an opt-in Minitest
   helper that clears every actor-owned table itself rather than relying on the
-  database cascade, which a host application may not enforce
+  database cascade, which a host application may not enforce, and runs due
+  reminders against an explicit test time without moving the database clock
 - Supervisor role replacement: a role whose thread dies is restarted until
   shutdown is requested, and dead process records plus expired message and
   process history are pruned on their own intervals without an application
@@ -103,8 +108,25 @@
   handing the block a raw Cable connection.
 - Backpressure: mailbox/payload/state/result caps and fair yields exist;
   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.
+- Administration: `SolidObjects::Web` is a mountable Rack dashboard covering
+  instances, mailbox, reminders, effects, broadcasts, dead letters, and
+  processes, with actor-type and actor-id filtering, status filters, paging, a
+  polled stats endpoint, Chart.js charts, and extension registration. The chart
+  library is fetched from a CDN with a subresource integrity hash, which a
+  deployment without outbound network access must replace with a vendored copy
+  or turn off. Every route declares its
+  own administration policy and a route declared without one raises at load
+  time, so the deny-by-default posture is enforced by construction rather than
+  by remembering to add a check. It changes only two things: an idempotent dead
+  letter retry and instance pause/resume. What does not exist is audit records
+  of who pressed what, and bulk-safe tools: retry is one dead letter at a time,
+  because `DeadLetterManager` exposes no bulk operation. Pause is an operator
+  brake and not a stop, since a pass already in flight finishes its turn and a
+  synchronous caller waiting on a paused instance times out. The page cost was
+  reasoned about rather than measured: the summary bar issues a fixed set of
+  indexed aggregate queries per page, which is why `HEAD /` exists for uptime
+  monitors, but no dashboard latency has been benchmarked against a large
+  table.
 
 ## Next milestones
 

data/docs/security.md

@@ -36,6 +36,14 @@ Opaque stream and DOM names reduce accidental disclosure but do not replace
 authorization. Signed stream tokens are readable by their recipient and prove
 integrity only.
 
+Observables are invalidation-only by default, so their durable rows and shared
+actor stream carry no projected value. `broadcast: :value` deliberately stores
+the value in the broadcast outbox and may send it to every subscriber that
+passes `authorize_subscription` for the actor. Never opt credentials, session
+identifiers, private cards, hidden library order, or any other
+subscriber-specific state into value broadcasting. Use `broadcast_payload` for
+a projection that must be computed separately for each authorized connection.
+
 ## Serialization
 
 The built-in serializer accepts JSON-compatible data, normalizes keys to

data/examples/application/README.md

@@ -10,8 +10,8 @@ key. The chat actor also gives every submitted chat message a caller-generated
 message ID and checks that ID in durable actor state, because actor handlers may
 be redelivered.
 
-The views demonstrate scalar observable replacement and a live chat-message
-ERB component. The chat component receives `recent_messages` as an ordinary
-Ruby array, rerenders its `<ol>` after committed changes, and refreshes through
-the authenticated host request context. Turbo append intents remain roadmap
-work.
+The views demonstrate explicit `broadcast: :value` scalar replacement and a
+default invalidation-only chat-message ERB component. The chat component
+receives `recent_messages` as an ordinary Ruby array, rerenders its `<ol>` after
+committed changes, and refreshes through the authenticated host request
+context. Turbo append intents remain roadmap work.

data/examples/application/app/actors/chat_room_actor.rb

@@ -6,7 +6,7 @@ class ChatRoomActor < SolidObjects::Actor
   attribute :members, default: -> { [] }
   attribute :recent_messages, default: -> { [] }
 
-  observable :presence do
+  observable :presence, broadcast: :value do
     members.length
   end
 

data/examples/application/app/actors/shopping_cart_actor.rb

@@ -5,11 +5,11 @@ class ShoppingCartActor < SolidObjects::Actor
   attribute :checkout_status, default: "open"
   attribute :payment_id
 
-  observable :items_count do
+  observable :items_count, broadcast: :value do
     items.sum { |item| item.fetch("quantity") }
   end
 
-  observable :subtotal_cents do
+  observable :subtotal_cents, broadcast: :value do
     items.sum do |item|
       item.fetch("quantity") * item.fetch("unit_price_cents")
     end
@@ -64,14 +64,14 @@ class ShoppingCartActor < SolidObjects::Actor
     )
   end
 
-  def payment_succeeded(effect_id:, result:)
+  def payment_succeeded(effect_id:, arguments:, result:)
     return unless checkout_status == "pending"
-    return unless result.fetch("payment_id") == payment_id
+    return unless arguments.fetch("payment_id") == payment_id
 
     self.checkout_status = "paid"
   end
 
-  def payment_failed(effect_id:, error:)
+  def payment_failed(effect_id:, arguments:, error:)
     return unless checkout_status == "pending"
 
     self.checkout_status = "payment_failed"

data/lib/solid_objects/actor.rb

@@ -52,9 +52,9 @@ module SolidObjects
         definition.add_query(name, block)
       end
 
-      # @rbs (Symbol | String) ?{ () -> untyped } -> ActorDefinition::Handler
-      def observable(name, &block)
-        definition.add_observable(name, block)
+      # @rbs (Symbol | String, ?broadcast: Symbol) ?{ () -> untyped } -> ActorDefinition::Handler
+      def observable(name, broadcast: :invalidation, &block)
+        definition.add_observable(name, block, broadcast:)
       end
 
       # @rbs (Symbol | String) { (untyped, untyped) -> untyped } -> ActorDefinition::Handler
@@ -163,8 +163,9 @@ module SolidObjects
     # @rbs (Symbol | String, String, ?details: Hash[String | Symbol, untyped]) -> bot
     def reject(code, message, details: {})
       rejection_code = code.to_s
-      unless rejection_code.match?(/\A[a-z][a-z0-9_]*\z/)
-        raise ArgumentError, "rejection code must contain lowercase letters, digits, and underscores"
+      unless rejection_code.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+        raise InvalidRejectionCode,
+          "invalid rejection code #{rejection_code.inspect}; expected a letter or underscore followed by letters, digits, or underscores"
       end
 
       raise Rejected.new(code: rejection_code, message:, details:)

data/lib/solid_objects/actor_channel.rb

@@ -165,13 +165,13 @@ module SolidObjects
     def validate_scalar_observables!
       return unless scalar_observables
 
-      observables = SolidObjects
+      definition = SolidObjects
         .registry
         .fetch(reference.actor_type)
         .definition
-        .observables
       unknown = scalar_observables.find do |name|
-        !observables.key?(name.to_sym)
+        !definition.observables.key?(name.to_sym) ||
+          !definition.broadcasts_observable_value?(name)
       end
       return unless unknown
 
@@ -182,7 +182,10 @@ module SolidObjects
     def scalar_observable_names(snapshot)
       return scalar_observables if scalar_observables
 
-      snapshot.actor_class.definition.observables.keys.map(&:to_s)
+      definition = snapshot.actor_class.definition
+      definition.observables.keys.filter_map do |name|
+        name.to_s if definition.broadcasts_observable_value?(name)
+      end
     end
   end
 end

data/lib/solid_objects/actor_definition.rb

@@ -9,6 +9,7 @@ module SolidObjects
     # @rbs @messages: Hash[Symbol, Handler]
     # @rbs @queries: Hash[Symbol, Handler]
     # @rbs @observables: Hash[Symbol, Handler]
+    # @rbs @observable_broadcasts: Hash[Symbol, Symbol]
     # @rbs @payload_broadcasts: Hash[Symbol, Handler]
     # @rbs @state_version: Integer
     # @rbs @state_migrations: Array[StateMigration]
@@ -33,6 +34,7 @@ module SolidObjects
       @messages = {}
       @queries = {}
       @observables = {}
+      @observable_broadcasts = {}
       @payload_broadcasts = {}
       @state_version = 1
       @state_migrations = []
@@ -76,17 +78,26 @@ module SolidObjects
       add_handler(collection: queries, name:, block:)
     end
 
-    # @rbs (Symbol | String, Proc?) -> Handler
-    def add_observable(name, block = nil)
+    # @rbs (Symbol | String, Proc?, broadcast: Symbol) -> Handler
+    def add_observable(name, block = nil, broadcast:)
       observable_name = name.to_sym
       raise InvalidActor, "#{observable_name.inspect} observable is already defined" if observables.key?(observable_name)
+      unless %i[value invalidation].include?(broadcast)
+        raise InvalidActor, "observable broadcast must be :value or :invalidation"
+      end
 
       observable_block = block || -> { state.fetch(observable_name) }
       Handler.new(name: observable_name, block: observable_block).tap do |handler|
         observables[observable_name] = handler
+        observable_broadcasts[observable_name] = broadcast
       end
     end
 
+    # @rbs (Symbol | String) -> bool
+    def broadcasts_observable_value?(name)
+      observable_broadcasts.fetch(name.to_sym) == :value
+    end
+
     # @rbs (Symbol | String, Proc) -> Handler
     def add_payload_broadcast(name, block)
       payload_name = name.to_sym
@@ -168,6 +179,7 @@ module SolidObjects
         copy.instance_variable_set(:@messages, messages.dup)
         copy.instance_variable_set(:@queries, queries.dup)
         copy.instance_variable_set(:@observables, observables.dup)
+        copy.instance_variable_set(:@observable_broadcasts, observable_broadcasts.dup)
         copy.instance_variable_set(:@payload_broadcasts, payload_broadcasts.dup)
         copy.instance_variable_set(:@state_version, state_version)
         copy.instance_variable_set(:@state_migrations, state_migrations.dup)
@@ -180,7 +192,7 @@ module SolidObjects
 
     private
 
-    attr_reader :attribute_queries, :method_messages
+    attr_reader :attribute_queries, :method_messages, :observable_broadcasts
 
     # @rbs (Symbol) -> Handler
     def add_method_message(name)

data/lib/solid_objects/actor_view.rb

@@ -24,8 +24,13 @@ module SolidObjects
     # @rbs (Symbol | String) -> untyped
     def value(name)
       observable_name = name.to_sym
-      handler = snapshot.actor_class.definition.observables[observable_name]
+      definition = snapshot.actor_class.definition
+      handler = definition.observables[observable_name]
       raise UnknownMessage, "unknown observable #{name.inspect}" unless handler
+      unless definition.broadcasts_observable_value?(observable_name)
+        raise ArgumentError,
+          "invalidation-only observable #{observable_name.inspect} cannot render as a scalar target"
+      end
 
       authorize_read!(observable_name)
       value = snapshot.observable_value(observable_name)

data/lib/solid_objects/effect_executor.rb

@@ -153,7 +153,11 @@ module SolidObjects
           effect: locked_effect,
           operation: locked_effect.success_operation,
           outcome: "success",
-          arguments: { "effect_id" => locked_effect.effect_id, "result" => serialized_result }
+          arguments: {
+            "effect_id" => locked_effect.effect_id,
+            "arguments" => locked_effect.arguments,
+            "result" => serialized_result
+          }
         )
         locked_effect.update!(
           status: "completed",
@@ -191,7 +195,11 @@ module SolidObjects
             effect: locked_effect,
             operation: locked_effect.failure_operation,
             outcome: "failure",
-            arguments: { "effect_id" => locked_effect.effect_id, "error" => error_details }
+            arguments: {
+              "effect_id" => locked_effect.effect_id,
+              "arguments" => locked_effect.arguments,
+              "error" => error_details
+            }
           )
         end
         locked_effect.update!(

data/lib/solid_objects/errors.rb

@@ -205,6 +205,9 @@ module SolidObjects
   class UnknownCommitAction < NonRetryableError
   end
 
+  class InvalidRejectionCode < NonRetryableError
+  end
+
   class Rejected < Error
     # @rbs @code: String
     # @rbs @details: Hash[String, untyped]

data/lib/solid_objects/executor.rb

@@ -301,12 +301,18 @@ module SolidObjects
       end
 
       broadcasts.each do |observable_name, value|
+        stored_value = if observable_name != PayloadBroadcast::REVISION_OBSERVABLE &&
+            actor.class.definition.broadcasts_observable_value?(observable_name)
+          value
+        else
+          {}
+        end
         Broadcast.create!(
           message:,
           instance:,
           broadcast_id: SecureRandom.uuid,
           observable_name:,
-          value:,
+          value: stored_value,
           state_version: actor.class.state_version,
           activation_generation: activation.lease.generation,
           status: "pending",

data/lib/solid_objects/reminder_scheduler.rb

@@ -19,15 +19,16 @@ module SolidObjects
       @shutdown_requested = false
     end
 
-    # @rbs () -> bool
-    def run_once
+    # @rbs (?now: Time?) -> bool
+    def run_once(now: nil)
       return false if stopped?
 
+      now = normalize_test_time(now)
       process_registry.heartbeat
-      reminder = claim_next
+      reminder = claim_next(now:)
       return false unless reminder
 
-      enqueue(reminder).present?
+      enqueue(reminder, now:).present?
     rescue
       release(reminder) if reminder
       raise
@@ -74,13 +75,14 @@ module SolidObjects
 
     attr_reader :process_registry, :database_adapter
 
-    # @rbs () -> Reminder?
-    def claim_next
+    # @rbs (now: Time?) -> Reminder?
+    def claim_next(now:)
       database_adapter.transaction do
-        now = database_adapter.database_now
-        stale_at = now - SolidObjects.configuration.process_alive_threshold
+        database_now = database_adapter.database_now
+        due_at = now || database_now
+        stale_at = database_now - SolidObjects.configuration.process_alive_threshold
         relation = Reminder
-          .where(status: "scheduled", next_run_at: ..now)
+          .where(status: "scheduled", next_run_at: ..due_at)
           .where("claimed_by IS NULL OR claimed_at <= ?", stale_at)
           .order(:next_run_at, :id)
         reminder = database_adapter.lock_candidates(relation).first
@@ -88,14 +90,14 @@ module SolidObjects
 
         reminder.update!(
           claimed_by: process_registry.process_record.id,
-          claimed_at: now
+          claimed_at: database_now
         )
         reminder
       end
     end
 
-    # @rbs (Reminder) -> MessageReference?
-    def enqueue(reminder)
+    # @rbs (Reminder, now: Time?) -> MessageReference?
+    def enqueue(reminder, now:)
       actor_class = SolidObjects.registry.fetch(reminder.actor_type)
       unless actor_class.definition.messages.key?(reminder.operation.to_sym)
         raise UnknownMessage, "unknown reminder operation #{reminder.operation.inspect}"
@@ -109,7 +111,7 @@ module SolidObjects
         locked_reminder = Reminder.lock.find_by(id: reminder.id)
         next unless locked_reminder
         verify_claim!(locked_reminder)
-        now = database_adapter.database_now
+        schedule_now = now || database_adapter.database_now
         message = mailbox.enqueue_in_transaction(
           reference: Reference.new(actor_type: instance.actor_type, actor_id: instance.actor_id),
           operation: locked_reminder.operation,
@@ -122,7 +124,7 @@ module SolidObjects
         locked_reminder.update!(
           status: recurring ? "scheduled" : "completed",
           occurrence: locked_reminder.occurrence + 1,
-          next_run_at: recurring ? next_run_at(locked_reminder, now) : locked_reminder.next_run_at,
+          next_run_at: recurring ? next_run_at(locked_reminder, schedule_now) : locked_reminder.next_run_at,
           claimed_by: nil,
           claimed_at: nil
         )
@@ -164,5 +166,17 @@ module SolidObjects
       missed_intervals = ((now - next_run) / interval).floor + 1
       next_run + (missed_intervals * interval)
     end
+
+    # @rbs (Time?) -> Time?
+    def normalize_test_time(now)
+      return unless now
+
+      time = now.to_time
+      return time if time.to_f.finite?
+
+      raise ArgumentError
+    rescue ArgumentError, NoMethodError, RangeError
+      raise ArgumentError, "reminder test time must be a valid time"
+    end
   end
 end

data/lib/solid_objects/test_helper.rb

@@ -68,6 +68,22 @@ module SolidObjects
       runners&.uniq&.each(&:stop)
     end
 
+    # @rbs (now: Time, ?max_reminders: Integer) -> Integer
+    def run_due_reminders(now:, max_reminders: 10_000)
+      unless max_reminders.is_a?(Integer) && max_reminders.positive?
+        raise ArgumentError, "max_reminders must be a positive integer"
+      end
+
+      scheduler = ReminderScheduler.new
+      processed = 0
+      while processed < max_reminders && scheduler.run_once(now:)
+        processed += 1
+      end
+      processed
+    ensure
+      scheduler&.stop
+    end
+
     private
 
     # @rbs (Array[Symbol]) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]

data/lib/solid_objects/turbo_stream_renderer.rb

@@ -16,14 +16,14 @@ module SolidObjects
         actor_type: broadcast.instance.actor_type,
         actor_id: broadcast.instance.actor_id
       )
-      stream = if broadcast.observable_name == PayloadBroadcast::REVISION_OBSERVABLE
-        ""
-      else
+      stream = if broadcast.broadcasts_value?
         observable_value(
           reference:,
           name: broadcast.observable_name,
           value: broadcast.value
         )
+      else
+        ""
       end
       metadata = Base64.urlsafe_encode64(
         JSON.generate(

data/lib/solid_objects/version.rb

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

data/lib/solid_objects/web/action.rb

@@ -0,0 +1,109 @@
+# rbs_inline: enabled
+
+require "erb"
+require "rack/request"
+require "rack/utils"
+
+module SolidObjects
+  class Web
+    # One request. A route handler runs inside an instance of this class, so a
+    # handler and the template it renders share the same helpers and the same
+    # request.
+    class Action
+      include Helpers
+
+      # @rbs @env: Hash[String, untyped]
+      # @rbs @route: Route
+      # @rbs @captures: Hash[Symbol, String?]
+      # @rbs @request: untyped
+      # @rbs @layout_rendered: bool
+      # @rbs @response_status: Integer
+
+      attr_reader :env, :route, :response_status
+
+      # @rbs (env: Hash[String, untyped], route: Route) -> void
+      def initialize(env:, route:)
+        @env = env
+        @route = route
+        @captures = route.capture(env["PATH_INFO"].to_s)
+        @layout_rendered = false
+        @response_status = 200
+      end
+
+      # Sets the status a rendered page is served with. `halt` and `redirect`
+      # stop the handler, so a page that must render its own body and still
+      # report a failure needs this instead.
+      # @rbs (Integer) -> void
+      def status(code)
+        @response_status = code
+      end
+
+      # @rbs () -> untyped
+      def request
+        @request ||= ::Rack::Request.new(env)
+      end
+
+      # @rbs () -> Hash[untyped, untyped]?
+      def session
+        env["rack.session"]
+      end
+
+      # @rbs (Symbol) -> String?
+      def route_params(key)
+        @captures[key]
+      end
+
+      # @rbs (String) -> untyped
+      def url_params(key)
+        request.params[key]
+      end
+
+      # @rbs () -> untyped
+      def call
+        instance_exec(&route.handler)
+      end
+
+      # The layout is rendered once per request. The flag is raised before the
+      # page body runs so a partial the body renders returns its own fragment
+      # rather than a second whole page. The layout reads the page it wraps
+      # from `locals.fetch(:content)`.
+      # @rbs (Symbol, ?Hash[Symbol, untyped]) -> String
+      def erb(name, locals = {})
+        return evaluate(Web.template(name), locals) if @layout_rendered
+
+        @layout_rendered = true
+        content = evaluate(Web.template(name), locals)
+        evaluate(Web.template(:layout), { content: })
+      end
+
+      # @rbs (Integer, ?String) -> void
+      def halt(status, body = ::Rack::Utils::HTTP_STATUS_CODES.fetch(status, "Error"))
+        throw :halt, [ status, { "content-type" => "text/plain" }, [ body ] ]
+      end
+
+      # @rbs (String) -> void
+      def redirect(path)
+        throw :halt, [ 302, { "location" => path_to(path) }, [] ]
+      end
+
+      # @rbs (untyped) -> void
+      def json(payload)
+        throw :halt, [
+          200,
+          { "content-type" => "application/json", "cache-control" => "private, no-store" },
+          [ JSON.generate(payload) ]
+        ]
+      end
+
+      private
+
+      # `locals` is a local variable of this method, so a template reads it by
+      # name, and every helper is reachable because the template runs against
+      # this object.
+      # @rbs (untyped, Hash[Symbol, untyped]) -> String
+      def evaluate(template, locals)
+        template.result(binding)
+      end
+    end
+  end
+end