solid_objects 0.1.0

data/docs/security.md

@@ -0,0 +1,61 @@
+# Security guide
+
+## Policy hooks
+
+Solid Objects has separate hooks for sending messages, querying state,
+destroying actors, subscribing to actor streams, and administration. The host
+application supplies the authenticated request or connection as
+`authorization_context`. All five hooks deny by default.
+
+Method-style reference calls do not bypass these hooks. Public instance methods
+declared on an actor are part of its remotely addressable message surface and
+delegate to the authorized `tell` path. Keep implementation helpers private or
+protected. Query and attribute methods delegate to the authorized `ask` path.
+`reference.destroy` delegates to `authorize_destroy` before checking whether
+the actor exists, so denial does not reveal actor existence.
+
+Internal runtime delivery bypasses the public client only for rows already
+created by a committed actor turn. It never converts a database actor type into
+a Ruby constant.
+
+## Actor identity
+
+Actor IDs are identifiers, not capabilities. Treat user-supplied IDs as
+untrusted and verify tenancy/ownership in every public policy hook. The registry
+maps explicit type strings to actor classes; arbitrary constantization is
+forbidden.
+
+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.
+
+## Serialization
+
+The built-in serializer accepts JSON-compatible data, normalizes keys to
+strings, rejects colliding normalized keys, limits nesting and byte size, and
+rejects non-finite numbers. It never loads Ruby objects with `Marshal`.
+
+Database access is still privileged input. Restrict who can write runtime
+tables, because a malicious row can request registered messages or effects even
+without unsafe object deserialization.
+
+## Administration
+
+The engine controllers and dead-letter service deny access unless
+`authorize_administration` approves. Actor state, arguments, results, errors,
+and backtraces may contain sensitive application data. Keep admin routes behind
+host authentication and audit their use.
+
+Instrumentation excludes arguments, state, results, and effect payloads by
+default. Review custom logging and effect handlers for accidental disclosure.
+
+Actor destruction is not an administrative shortcut. Authorize tenancy and
+ownership explicitly in `authorize_destroy`; knowledge of an actor ID is never
+permission to delete its state or queued work.
+
+## Denial of service
+
+Configure mailbox and byte limits. Add host rate limiting before public actor
+calls. One actor is intentionally sequential, so an attacker who can target a
+single identity can create a hot-actor bottleneck even when the global worker
+pool has capacity.

data/docs/state-migrations.md

@@ -0,0 +1,46 @@
+# State migration guide
+
+Declare a monotonically increasing version and every adjacent migration:
+
+```ruby
+class ShoppingCartActor < SolidObjects::Actor
+  state_version 2
+
+  migrate_state from: 1, to: 2 do |state|
+    state["currency"] ||= "USD"
+    state
+  end
+end
+```
+
+Migration runs in memory during activation. The new version is persisted only
+with the next successful fenced message commit.
+
+## Runtime rules
+
+- Stored state newer than running code refuses activation.
+- Missing migration steps fail activation.
+- Every migration result must pass JSON serialization.
+- Additive representation changes that old and new code both understand need
+  no version bump.
+- Destructive changes require expand/contract releases.
+- Published actor migrations are never squashed. A year-idle actor may still
+  hold a year-old blob.
+
+## Rolling deploys
+
+A new worker can migrate state while an old worker still exists. If the old code
+cannot read the migrated shape, drain the old workers before allowing the new
+version to persist it.
+
+A safe destructive rollout normally uses:
+
+1. Expand readers to accept old and new shapes.
+2. Deploy that compatibility release everywhere.
+3. Add and enable the actor migration.
+4. Allow active and dormant actors to migrate over time, or run an authorized
+   message-based migration campaign.
+5. Remove old-shape support only after operational evidence says it is safe.
+
+Never update actor JSON in a bulk SQL migration. Use actor messages so fencing,
+ordering, observables, and outboxes remain intact.

data/examples/application/README.md

@@ -0,0 +1,16 @@
+# Example application source
+
+This directory contains the host-application pieces for the shopping cart and
+chat room examples. Copy them into a Rails application that has run
+`bin/rails generate solid_objects:install`, mount the engine for administration,
+and start the runtime with `bundle exec solid_objects start`.
+
+The payment adapter receives the durable effect ID as its provider idempotency
+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 initial `solid_object` rendering and live observable
+replacement. Live cart-summary replacement and chat-message append are
+deliberately not shown as working behavior because component broadcasts and
+Turbo append intents remain roadmap items.

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

@@ -0,0 +1,34 @@
+# rbs_inline: enabled
+
+class ChatRoomActor < SolidObjects::Actor
+  MAX_RECENT_MESSAGES = 100
+
+  attribute :members, default: -> { [] }
+  attribute :recent_messages, default: -> { [] }
+
+  observable :presence do
+    members.length
+  end
+
+  observable :recent_messages
+
+  def join(user_id:)
+    members << user_id unless members.include?(user_id)
+  end
+
+  def leave(user_id:)
+    members.delete(user_id)
+  end
+
+  def send_message(message_id:, user_id:, body:)
+    return if recent_messages.any? { |message| message.fetch("id") == message_id }
+    return unless members.include?(user_id)
+
+    recent_messages << {
+      "id" => message_id,
+      "user_id" => user_id,
+      "body" => body
+    }
+    recent_messages.shift while recent_messages.length > MAX_RECENT_MESSAGES
+  end
+end

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

@@ -0,0 +1,79 @@
+# rbs_inline: enabled
+
+class ShoppingCartActor < SolidObjects::Actor
+  attribute :items, default: -> { [] }
+  attribute :checkout_status, default: "open"
+  attribute :payment_id
+
+  observable :items_count do
+    items.sum { |item| item.fetch("quantity") }
+  end
+
+  observable :subtotal_cents do
+    items.sum do |item|
+      item.fetch("quantity") * item.fetch("unit_price_cents")
+    end
+  end
+
+  observable :checkout_status
+
+  def add_item(product_id:, unit_price_cents:, quantity: 1)
+    item = items.find do |candidate|
+      candidate.fetch("product_id") == product_id
+    end
+
+    if item
+      item["quantity"] += quantity
+    else
+      items << {
+        "product_id" => product_id,
+        "unit_price_cents" => unit_price_cents,
+        "quantity" => quantity
+      }
+    end
+  end
+
+  def remove_item(product_id:)
+    items.reject! do |item|
+      item.fetch("product_id") == product_id
+    end
+  end
+
+  def change_quantity(product_id:, quantity:)
+    item = items.find do |candidate|
+      candidate.fetch("product_id") == product_id
+    end
+    return unless item
+
+    item["quantity"] = quantity
+  end
+
+  def checkout(payment_id:)
+    return unless checkout_status == "open"
+
+    self.checkout_status = "pending"
+    self.payment_id = payment_id
+    emit(
+      :charge_payment,
+      payment_id:,
+      amount_cents: items.sum do |item|
+        item.fetch("quantity") * item.fetch("unit_price_cents")
+      end,
+      on_success: :payment_succeeded,
+      on_failure: :payment_failed
+    )
+  end
+
+  def payment_succeeded(effect_id:, result:)
+    return unless checkout_status == "pending"
+    return unless result.fetch("payment_id") == payment_id
+
+    self.checkout_status = "paid"
+  end
+
+  def payment_failed(effect_id:, error:)
+    return unless checkout_status == "pending"
+
+    self.checkout_status = "payment_failed"
+  end
+end

data/examples/application/app/controllers/cart_controller.rb

@@ -0,0 +1,54 @@
+# rbs_inline: enabled
+
+class CartController < ApplicationController
+  # @rbs () -> void
+  def show
+    @cart = ShoppingCartActor.ref(current_user.id)
+  end
+
+  # @rbs () -> void
+  def add_item
+    ShoppingCartActor.ref(current_user.id).add_item(
+      product_id: params.require(:product_id),
+      unit_price_cents: params.require(:unit_price_cents).to_i,
+      quantity: params.fetch(:quantity, 1).to_i,
+      authorization_context: self
+    )
+    redirect_to cart_path
+  end
+
+  # @rbs () -> void
+  def remove_item
+    current_cart.remove_item(
+      product_id: params.require(:product_id),
+      authorization_context: self
+    )
+    redirect_to cart_path
+  end
+
+  # @rbs () -> void
+  def change_quantity
+    current_cart.change_quantity(
+      product_id: params.require(:product_id),
+      quantity: params.require(:quantity).to_i,
+      authorization_context: self
+    )
+    redirect_to cart_path
+  end
+
+  # @rbs () -> void
+  def checkout
+    current_cart.checkout(
+      payment_id: SecureRandom.uuid,
+      authorization_context: self
+    )
+    redirect_to cart_path
+  end
+
+  private
+
+  # @rbs () -> SolidObjects::Reference
+  def current_cart
+    ShoppingCartActor.ref(current_user.id)
+  end
+end

data/examples/application/app/controllers/chat_rooms_controller.rb

@@ -0,0 +1,44 @@
+# rbs_inline: enabled
+
+class ChatRoomsController < ApplicationController
+  # @rbs () -> void
+  def show
+    @room = current_room
+  end
+
+  # @rbs () -> void
+  def join
+    current_room.join(
+      user_id: current_user.id.to_s,
+      authorization_context: self
+    )
+    redirect_to chat_room_path(params[:id])
+  end
+
+  # @rbs () -> void
+  def leave
+    current_room.leave(
+      user_id: current_user.id.to_s,
+      authorization_context: self
+    )
+    redirect_to chat_room_path(params[:id])
+  end
+
+  # @rbs () -> void
+  def create_message
+    current_room.send_message(
+      message_id: SecureRandom.uuid,
+      user_id: current_user.id.to_s,
+      body: params.require(:body),
+      authorization_context: self
+    )
+    redirect_to chat_room_path(params[:id])
+  end
+
+  private
+
+  # @rbs () -> SolidObjects::Reference
+  def current_room
+    ChatRoomActor.ref(params.require(:id))
+  end
+end

data/examples/application/app/views/actors/chat_room_actor/_messages.html.erb

@@ -0,0 +1,8 @@
+<ol>
+  <% actor.state.recent_messages.each do |message| %>
+    <li id="message_<%= message.fetch("id") %>">
+      <strong><%= message.fetch("user_id") %></strong>
+      <%= message.fetch("body") %>
+    </li>
+  <% end %>
+</ol>

data/examples/application/app/views/actors/shopping_cart_actor/_summary.html.erb

@@ -0,0 +1,10 @@
+<ul>
+  <% actor.state.items.each do |item| %>
+    <li>
+      <%= item.fetch("product_id") %>
+      × <%= item.fetch("quantity") %>
+    </li>
+  <% end %>
+</ul>
+
+<p>Checkout: <%= actor.state.checkout_status %></p>

data/examples/application/app/views/cart/show.html.erb

@@ -0,0 +1,13 @@
+<%= solid_object @cart do |cart| %>
+  <span>
+    Cart items:
+    <%= cart.items_count %>
+  </span>
+
+  <span>
+    Subtotal:
+    <%= cart.subtotal_cents %>
+  </span>
+
+  <%= cart.component :summary %>
+<% end %>

data/examples/application/app/views/chat_rooms/show.html.erb

@@ -0,0 +1,8 @@
+<%= solid_object @room do |room| %>
+  <p>
+    Present:
+    <%= room.presence %>
+  </p>
+
+  <%= room.component :messages %>
+<% end %>

data/examples/application/config/initializers/solid_objects.rb

@@ -0,0 +1,23 @@
+# rbs_inline: enabled
+
+SolidObjects.configure do |configuration|
+  configuration.authorize_message = lambda do |actor_type:, actor_id:, authorization_context:, **|
+    next false unless authorization_context.respond_to?(:current_user)
+
+    if actor_type == ShoppingCartActor.actor_type
+      authorization_context.current_user.id.to_s == actor_id
+    else
+      ChatRoomPolicy.new(authorization_context.current_user).access?(actor_id)
+    end
+  end
+  configuration.authorize_query = configuration.authorize_message
+  configuration.authorize_subscription = configuration.authorize_message
+end
+
+SolidObjects.register_effect(:charge_payment) do |arguments, context|
+  Payments.charge(
+    idempotency_key: context.id,
+    payment_id: arguments.fetch("payment_id"),
+    amount_cents: arguments.fetch("amount_cents")
+  )
+end

data/examples/application/config/routes.rb

@@ -0,0 +1,20 @@
+# rbs_inline: enabled
+
+Rails.application.routes.draw do
+  resource :cart, only: :show do
+    post :add_item
+    post :remove_item
+    post :change_quantity
+    post :checkout
+  end
+
+  resources :chat_rooms, only: :show do
+    member do
+      post :join
+      post :leave
+      post :create_message
+    end
+  end
+
+  mount SolidObjects::Engine => "/solid_objects"
+end

data/exe/solid_objects

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# rbs_inline: enabled
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "solid_objects"
+require "solid_objects/cli"
+
+SolidObjects::CLI.start(ARGV)

data/lib/generators/solid_objects/install_generator.rb

@@ -0,0 +1,21 @@
+# rbs_inline: enabled
+
+require "rails/generators"
+
+module SolidObjects
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      # @rbs () -> void
+      def copy_initializer
+        template "solid_objects.rb", "config/initializers/solid_objects.rb"
+      end
+
+      # @rbs () -> void
+      def copy_migrations
+        rake "railties:install:migrations FROM=solid_objects"
+      end
+    end
+  end
+end

data/lib/generators/solid_objects/templates/solid_objects.rb

@@ -0,0 +1,13 @@
+# rbs_inline: enabled
+
+SolidObjects.configure do |configuration|
+  configuration.worker_count = 1
+  configuration.effect_worker_count = 1
+  configuration.broadcast_worker_count = 1
+  configuration.reminder_scheduler_count = 1
+  configuration.authorize_message = ->(**) { false }
+  configuration.authorize_query = ->(**) { false }
+  configuration.authorize_destroy = ->(**) { false }
+  configuration.authorize_subscription = ->(**) { false }
+  configuration.authorize_administration = ->(**) { false }
+end

data/lib/solid_objects/action_cable_broadcast_adapter.rb

@@ -0,0 +1,19 @@
+# rbs_inline: enabled
+
+require "action_cable/engine"
+
+module SolidObjects
+  class ActionCableBroadcastAdapter
+    # @rbs (Broadcast) -> void
+    def call(broadcast)
+      reference = Reference.new(
+        actor_type: broadcast.instance.actor_type,
+        actor_id: broadcast.instance.actor_id
+      )
+      ActionCable.server.broadcast(
+        StreamName.for(reference),
+        TurboStreamRenderer.observable(broadcast)
+      )
+    end
+  end
+end

data/lib/solid_objects/activation.rb

@@ -0,0 +1,183 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Activation
+    # @rbs @lease: Lease
+    # @rbs @actor_class: Class
+    # @rbs @actor: Actor
+    # @rbs @last_used_at: Float
+    # @rbs @pass_exhausted: bool
+
+    attr_reader :lease, :actor
+
+    # @rbs (lease: Lease) -> void
+    def initialize(lease:)
+      @lease = lease
+      instance = Instance.find(lease.instance_id)
+      @actor_class = SolidObjects.registry.fetch(instance.actor_type)
+      @actor = build_actor(instance)
+      @last_used_at = monotonic_now
+      @pass_exhausted = false
+      actor.activate
+      SolidObjects.instrument(
+        :"activation.started",
+        instance_id: instance.id,
+        actor_type: instance.actor_type,
+        actor_id: instance.actor_id,
+        owner_id: lease.owner_id,
+        generation: lease.generation
+      )
+    end
+
+    # @rbs () -> Integer
+    def drain
+      processed_count = 0
+      started_at = monotonic_now
+      @pass_exhausted = false
+
+      loop do
+        if processed_count >= SolidObjects.configuration.max_messages_per_activation_pass ||
+            monotonic_now - started_at >= SolidObjects.configuration.max_activation_duration
+          @pass_exhausted = true
+          break
+        end
+
+        message = claim_next_message
+        break unless message
+
+        Executor.new(activation: self, message:).call
+        processed_count += 1
+        @last_used_at = monotonic_now
+      end
+
+      processed_count
+    end
+
+    # @rbs () -> bool
+    def ready?
+      now = SolidObjects.database_adapter.database_now
+      ReadyMessage.where(instance_id: lease.instance_id, available_at: ..now).exists? ||
+        ClaimedMessage.where(
+          instance_id: lease.instance_id,
+          process_id: lease.owner_id,
+          activation_generation: lease.generation
+        ).exists?
+    end
+
+    # @rbs () -> bool
+    def pass_exhausted?
+      @pass_exhausted
+    end
+
+    # @rbs () -> bool
+    def idle?
+      monotonic_now - @last_used_at >= SolidObjects.configuration.idle_deactivation_timeout
+    end
+
+    # @rbs () -> void
+    def renew_lease
+      @lease = lease.renew
+    end
+
+    # @rbs () -> bool
+    def lease_renewal_due?
+      lease.expires_at - SolidObjects.database_adapter.database_now <=
+        SolidObjects.configuration.lease_renewal_interval
+    end
+
+    # @rbs () -> void
+    def yield_ready_messages
+      now = SolidObjects.database_adapter.database_now
+      ReadyMessage
+        .where(instance_id: lease.instance_id, available_at: ..now)
+        .update_all(available_at: now)
+    end
+
+    # @rbs (Hash[String, untyped]) -> void
+    def restore_state(state_data)
+      @actor = actor_class.new(
+        actor_id: actor.actor_id,
+        state: State.new(actor_class.definition.state_definition, state_data)
+      )
+    end
+
+    # @rbs () -> void
+    def deactivate
+      actor.deactivate
+      lease.release
+    rescue LostActivation
+      nil
+    end
+
+    private
+
+    attr_reader :actor_class
+
+    # @rbs (Instance) -> Actor
+    def build_actor(instance)
+      state_data = actor_class.definition.migrate_state(instance.state_version, instance.state)
+      actor_class.new(
+        actor_id: instance.actor_id,
+        state: State.new(actor_class.definition.state_definition, state_data)
+      )
+    end
+
+    # @rbs () -> Message?
+    def claim_next_message
+      lease.fenced_transaction do |instance|
+        recover_stale_claim(instance)
+        ready_message = ReadyMessage
+          .where(instance_id: instance.id)
+          .order(:sequence)
+          .first
+        next unless ready_message
+
+        now = SolidObjects.database_adapter.database_now
+        next if ready_message.available_at > now
+
+        message = Message.lock.find(ready_message.message_id)
+        ready_message.destroy!
+        message.update!(
+          attempt_count: message.attempt_count + 1,
+          started_at: now
+        )
+        ClaimedMessage.create!(
+          message:,
+          instance:,
+          process_id: lease.owner_id,
+          activation_generation: lease.generation,
+          claimed_at: now
+        )
+        message
+      end
+    end
+
+    # @rbs (Instance) -> void
+    def recover_stale_claim(instance)
+      claimed_message = ClaimedMessage
+        .joins(:message)
+        .where(instance_id: instance.id)
+        .order("#{Message.table_name}.sequence")
+        .first
+      return unless claimed_message
+      return if claimed_message.process_id == lease.owner_id &&
+        claimed_message.activation_generation == lease.generation
+
+      message = claimed_message.message
+      claimed_message.destroy!
+      return if message.completed? || message.dead?
+
+      ReadyMessage.create!(
+        message:,
+        instance:,
+        sequence: message.sequence,
+        available_at: SolidObjects.database_adapter.database_now
+      )
+    end
+
+    # @rbs () -> Float
+    def monotonic_now
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+  end
+end