solid_objects 0.4.2 → 0.5.0

data/lib/solid_objects/component_renderer.rb

@@ -3,46 +3,44 @@
 module SolidObjects
   class ComponentRenderer
     # @rbs @snapshot: ActorSnapshot
-    # @rbs @component_name: String
-    # @rbs @dependencies: Array[String]
+    # @rbs @registration: ComponentRegistration
     # @rbs @view_context: untyped
     # @rbs @authorization_context: untyped
 
-    # @rbs (snapshot: ActorSnapshot, component_name: String, dependencies: Array[String], view_context: untyped, authorization_context: untyped) -> void
+    # @rbs (snapshot: ActorSnapshot, registration: ComponentRegistration, view_context: untyped, authorization_context: untyped) -> void
     def initialize(
       snapshot:,
-      component_name:,
-      dependencies:,
+      registration:,
       view_context:,
       authorization_context:
     )
       @snapshot = snapshot
-      @component_name = component_name
-      @dependencies = dependencies
+      @registration = registration
       @view_context = view_context
       @authorization_context = authorization_context
     end
 
     # @rbs () -> untyped
     def call
-      [ component_name, *dependencies ].uniq.each do |authorization_name|
+      [ registration.component_name, *registration.dependencies ].uniq.each do |authorization_name|
         authorize_read!(authorization_name)
       end
       actor = ComponentView.new(
         snapshot:,
-        dependencies:,
+        dependencies: registration.dependencies,
         authorization_context:
       )
       view_context.render(
         partial: default_partial,
-        locals: {
+        locals: registration.locals.transform_keys(&:to_sym).merge(
           actor:,
-          authorization_context:
-        }
+          authorization_context:,
+          component_key: registration.component_key
+        )
       )
     rescue ActionView::MissingTemplate
       raise UnknownComponent,
-        "unknown component #{component_name.inspect} for #{snapshot.reference.actor_type}"
+        "unknown component #{registration.component_name.inspect} for #{snapshot.reference.actor_type}"
     rescue ActionView::Template::Error => error
       raise error.cause if error.cause.is_a?(SolidObjects::Error)
 
@@ -52,8 +50,7 @@ module SolidObjects
     private
 
     attr_reader :snapshot,
-      :component_name,
-      :dependencies,
+      :registration,
       :view_context,
       :authorization_context
 
@@ -63,7 +60,7 @@ module SolidObjects
         actor_type: snapshot.reference.actor_type,
         actor_id: snapshot.reference.actor_id,
         message_name: observable_name,
-        arguments: {},
+        arguments: registration.authorization_arguments,
         authorization_context:
       )
       return if authorized
@@ -76,7 +73,7 @@ module SolidObjects
       actor_name = snapshot.actor_class.name
       raise InvalidActor, "anonymous actors cannot render reactive components" unless actor_name
 
-      "actors/#{actor_name.underscore}/#{component_name}"
+      "actors/#{actor_name.underscore}/#{registration.component_name}"
     end
   end
 end

data/lib/solid_objects/component_subscriptions.rb

@@ -28,7 +28,7 @@ module SolidObjects
           validate_identity!(registration, reference)
         end
       end
-      if registrations.map(&:component_name).uniq.length != registrations.length
+      if registrations.map(&:dom_id).uniq.length != registrations.length
         raise InvalidComponentToken, "duplicate actor component registration"
       end
 
@@ -39,7 +39,7 @@ module SolidObjects
     def initialize(registrations)
       @registrations = registrations
       @revisions = registrations.to_h do |registration|
-        [ registration.component_name, registration.revision_key ]
+        [ registration.dom_id, registration.revision_key ]
       end
     end
 
@@ -51,7 +51,7 @@ module SolidObjects
       registrations.filter_map do |registration|
         next unless registration.dependencies.include?(observable_name)
         next unless newer_revision?(
-          registration.component_name,
+          registration.dom_id,
           instance_id,
           revision
         )
@@ -64,7 +64,7 @@ module SolidObjects
     def reconnect_refreshes(snapshot)
       registrations.filter_map do |registration|
         next unless newer_revision?(
-          registration.component_name,
+          registration.dom_id,
           snapshot.instance_id,
           snapshot.revision
         )
@@ -92,7 +92,7 @@ module SolidObjects
 
     # @rbs (ComponentRegistration, Integer, Integer) -> String
     def refresh(registration, instance_id, revision)
-      revisions[registration.component_name] = [ instance_id, revision ]
+      revisions[registration.dom_id] = [ instance_id, revision ]
       TurboStreamRenderer.component_refresh(
         registration,
         instance_id,
@@ -101,8 +101,8 @@ module SolidObjects
     end
 
     # @rbs (String, Integer, Integer) -> bool
-    def newer_revision?(component_name, instance_id, revision)
-      current = revisions.fetch(component_name)
+    def newer_revision?(dom_id, instance_id, revision)
+      current = revisions.fetch(dom_id)
       (current <=> [ instance_id, revision ]) == -1
     end
   end

data/lib/solid_objects/component_token.rb

@@ -7,23 +7,38 @@ module SolidObjects
     PURPOSE = "solid_objects.actor_component"
     MAXIMUM_TOKEN_BYTES = 16_384
     MAXIMUM_DEPENDENCIES = 50
+    MAXIMUM_LOCALS = 50
+    MAXIMUM_COMPONENT_KEY_BYTES = 512
+    REFRESH_METHODS = %w[replace morph].freeze
+    RESERVED_LOCALS = %w[actor authorization_context component_key].freeze
+    RUBY_KEYWORDS = %w[
+      alias and begin break case class def defined do else elsif end ensure
+      false for if in module next nil not or redo rescue retry return self
+      super then true undef unless until when while yield
+    ].freeze
 
     module_function
 
-    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String) -> String
+    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, ?component_key: untyped, ?locals: Hash[untyped, untyped], ?refresh_method: String | Symbol) -> String
     def generate(
       reference:,
       component_name:,
       dependencies:,
       instance_id:,
       revision:,
-      refresh_path:
+      refresh_path:,
+      component_key: nil,
+      locals: {},
+      refresh_method: "replace"
     )
       payload = {
         "actor_type" => reference.actor_type,
         "actor_id" => reference.actor_id,
         "component_name" => component_name,
+        "component_key" => Serialization.dump(component_key),
         "dependencies" => dependencies,
+        "locals" => Serialization.dump(locals),
+        "refresh_method" => refresh_method.to_s,
         "instance_id" => instance_id,
         "revision" => revision,
         "refresh_path" => refresh_path
@@ -41,6 +56,7 @@ module SolidObjects
       end
 
       payload = verifier.verified(token, purpose: PURPOSE)
+      apply_defaults!(payload)
       validate_payload!(payload)
       payload
     rescue ActiveSupport::MessageVerifier::InvalidSignature
@@ -54,6 +70,8 @@ module SolidObjects
           payload["actor_id"].is_a?(String) &&
           payload["component_name"].is_a?(String) &&
           payload["dependencies"].is_a?(Array) &&
+          payload["locals"].is_a?(Hash) &&
+          payload["refresh_method"].is_a?(String) &&
           payload["instance_id"].is_a?(Integer) &&
           payload["revision"].is_a?(Integer) &&
           payload["refresh_path"].is_a?(String)
@@ -61,7 +79,10 @@ module SolidObjects
       end
 
       validate_component_name!(payload.fetch("component_name"))
+      validate_component_key!(payload["component_key"])
       validate_dependencies!(payload.fetch("dependencies"))
+      validate_locals!(payload.fetch("locals"))
+      validate_refresh_method!(payload.fetch("refresh_method"))
       validate_revision!(
         payload.fetch("instance_id"),
         payload.fetch("revision")
@@ -71,6 +92,16 @@ module SolidObjects
     end
     private_class_method :validate_payload!
 
+    # @rbs (Hash[String, untyped]?) -> void
+    def apply_defaults!(payload)
+      return unless payload.is_a?(Hash)
+
+      payload["component_key"] = nil unless payload.key?("component_key")
+      payload["locals"] = {} unless payload.key?("locals")
+      payload["refresh_method"] = "replace" unless payload.key?("refresh_method")
+    end
+    private_class_method :apply_defaults!
+
     # @rbs (String) -> void
     def validate_component_name!(component_name)
       return if component_name.match?(/\A[a-zA-Z0-9_]+\z/)
@@ -79,6 +110,20 @@ module SolidObjects
     end
     private_class_method :validate_component_name!
 
+    # @rbs (untyped) -> void
+    def validate_component_key!(component_key)
+      return if component_key.nil?
+      return if component_key.is_a?(Integer)
+      if component_key.is_a?(String) &&
+          component_key.bytesize.positive? &&
+          component_key.bytesize <= MAXIMUM_COMPONENT_KEY_BYTES
+        return
+      end
+
+      raise InvalidComponentToken, "invalid actor component key"
+    end
+    private_class_method :validate_component_key!
+
     # @rbs (Array[untyped]) -> void
     def validate_dependencies!(dependencies)
       valid = dependencies.any? &&
@@ -91,6 +136,29 @@ module SolidObjects
     end
     private_class_method :validate_dependencies!
 
+    # @rbs (Hash[untyped, untyped]) -> void
+    def validate_locals!(locals)
+      valid = locals.length <= MAXIMUM_LOCALS &&
+        locals.keys.all? do |name|
+          name.is_a?(String) &&
+            name.match?(/\A[a-z_][a-zA-Z0-9_]*\z/) &&
+            !RESERVED_LOCALS.include?(name) &&
+            !RUBY_KEYWORDS.include?(name)
+        end
+      return if valid
+
+      raise InvalidComponentToken, "invalid actor component locals"
+    end
+    private_class_method :validate_locals!
+
+    # @rbs (String) -> void
+    def validate_refresh_method!(refresh_method)
+      return if REFRESH_METHODS.include?(refresh_method)
+
+      raise InvalidComponentToken, "invalid actor component refresh method"
+    end
+    private_class_method :validate_refresh_method!
+
     # @rbs (Integer, Integer) -> void
     def validate_revision!(instance_id, revision)
       return unless instance_id.negative? || revision.negative?

data/lib/solid_objects/database_adapter.rb

@@ -52,6 +52,16 @@ module SolidObjects
       value.is_a?(Time) ? value.utc : Time.parse("#{value} UTC").utc
     end
 
+    # @rbs () { () -> untyped } -> untyped
+    def with_lock_retry
+      yield
+    end
+
+    # @rbs () { () -> untyped } -> untyped
+    def with_lock_probe
+      yield
+    end
+
     # @rbs () { () -> untyped } -> untyped
     def transaction(&block)
       raise DatabaseDeadlineExceeded, "synchronous invocation deadline expired" if SyncDeadline.expired?

data/lib/solid_objects/database_adapters/sqlite.rb

@@ -4,6 +4,8 @@ module SolidObjects
   module DatabaseAdapters
     class Sqlite < DatabaseAdapter
       LOCK_RETRY_INTERVAL = 0.001
+      LOCK_RETRY_MUTEX = Thread::Mutex.new
+      LOCK_RETRY_CONDITION = Thread::ConditionVariable.new
 
       # @rbs () -> String
       def current_time_expression
@@ -14,14 +16,51 @@ module SolidObjects
       def transaction(&block)
         return super unless SyncDeadline.active?
 
-        super
+        with_lock_retry { super }
+      end
+
+      # @rbs () { () -> untyped } -> untyped
+      def with_lock_retry
+        return yield unless SyncDeadline.active?
+
+        raise DatabaseDeadlineExceeded, "synchronous invocation deadline expired" if SyncDeadline.expired?
+
+        with_connection do |connection|
+          with_transaction_deadline(connection) { yield }
+        end
       rescue DatabaseDeadlineExceeded
         raise if SyncDeadline.expired?
 
-        sleep [ LOCK_RETRY_INTERVAL, SyncDeadline.remaining ].min
+        wait_before_retry
+        retry
+      rescue => error
+        raise unless deadline_error?(error)
+
+        if SyncDeadline.expired?
+          raise DatabaseDeadlineExceeded,
+            "database lock wait exceeded the synchronous invocation deadline",
+            cause: error
+        end
+
+        wait_before_retry
         retry
       end
 
+      # @rbs () { () -> untyped } -> untyped
+      def with_lock_probe
+        return yield unless SyncDeadline.active?
+
+        with_connection do |connection|
+          with_transaction_deadline(connection) { yield }
+        end
+      rescue => error
+        raise unless deadline_error?(error)
+
+        raise DatabaseDeadlineExceeded,
+          "database remained locked at the synchronous invocation deadline",
+          cause: error
+      end
+
       private
 
       # @rbs (untyped) { () -> untyped } -> untyped
@@ -47,6 +86,16 @@ module SolidObjects
         end
         false
       end
+
+      # @rbs () -> void
+      def wait_before_retry
+        LOCK_RETRY_MUTEX.synchronize do
+          LOCK_RETRY_CONDITION.wait(
+            LOCK_RETRY_MUTEX,
+            [ LOCK_RETRY_INTERVAL, SyncDeadline.remaining ].min
+          )
+        end
+      end
     end
   end
 end

data/lib/solid_objects/dom_identity.rb

@@ -16,9 +16,12 @@ module SolidObjects
       "#{scope(reference)}_observable_#{normalized_name(name)}"
     end
 
-    # @rbs (Reference, Symbol | String) -> String
-    def component(reference, name)
-      "#{scope(reference)}_component_#{normalized_name(name)}"
+    # @rbs (Reference, Symbol | String, ?key: String | Integer?) -> String
+    def component(reference, name, key: nil)
+      identity = "#{scope(reference)}_component_#{normalized_name(name)}"
+      return identity unless key
+
+      "#{identity}_#{component_key_digest(key)}"
     end
 
     # @rbs (Reference) -> String
@@ -34,5 +37,11 @@ module SolidObjects
       name.to_s.gsub(/[^a-zA-Z0-9_-]/, "_")
     end
     private_class_method :normalized_name
+
+    # @rbs (String | Integer) -> String
+    def component_key_digest(key)
+      Digest::SHA256.hexdigest(JSON.generate(key)).first(24)
+    end
+    private_class_method :component_key_digest
   end
 end

data/lib/solid_objects/engine.rb

@@ -26,6 +26,13 @@ module SolidObjects
       end
     end
 
+    initializer "solid_objects.assets" do |application|
+      next unless application.config.respond_to?(:assets)
+      next unless application.config.assets.respond_to?(:precompile)
+
+      application.config.assets.precompile << "solid_objects/component_refresh.js"
+    end
+
     rake_tasks do
       tasks_path = File.expand_path("../tasks", __dir__)
       Dir[File.join(tasks_path, "**/*.rake")].sort.each { |task| load task }

data/lib/solid_objects/process_registry.rb

@@ -80,18 +80,21 @@ module SolidObjects
 
     # @rbs (?kind: String, ?metadata: Hash[String | Symbol, untyped]) -> Process
     def register(kind: "worker", metadata: {})
-      now = SolidObjects.database_adapter.database_now
-      @process_record = Process.create!(
-        id: SecureRandom.uuid,
-        kind:,
-        hostname: Socket.gethostname,
-        pid: ::Process.pid,
-        started_at: now,
-        last_heartbeat_at: now,
-        metadata: Serialization.dump(default_metadata.merge(metadata))
-      )
+      process_record = SolidObjects.database_adapter.with_lock_retry do
+        now = SolidObjects.database_adapter.database_now
+        Process.create!(
+          id: SecureRandom.uuid,
+          kind:,
+          hostname: Socket.gethostname,
+          pid: ::Process.pid,
+          started_at: now,
+          last_heartbeat_at: now,
+          metadata: Serialization.dump(default_metadata.merge(metadata))
+        )
+      end
+      @process_record = process_record
       @last_heartbeat_at = monotonic_now
-      @process_record
+      process_record
     end
 
     # @rbs () -> bool
@@ -99,9 +102,13 @@ module SolidObjects
       return false unless process_record
       return false if heartbeat_recent?
 
-      process_record.update(
-        last_heartbeat_at: SolidObjects.database_adapter.database_now
-      ).tap { @last_heartbeat_at = monotonic_now }
+      updated = SolidObjects.database_adapter.with_lock_retry do
+        process_record.update(
+          last_heartbeat_at: SolidObjects.database_adapter.database_now
+        )
+      end
+      @last_heartbeat_at = monotonic_now if updated
+      updated
     end
 
     # @rbs () -> bool

data/lib/solid_objects/sync_diagnostics.rb

@@ -10,6 +10,62 @@ module SolidObjects
       status = message_status(message)
       waiting_on = waiting_reason(message, instance, blocker)
       activation = activation_details(instance)
+      build_error(
+        message,
+        timeout:,
+        status:,
+        waiting_on:,
+        activation:,
+        blocker: blocker_details(blocker)
+      )
+    end
+
+    # @rbs (Message, timeout: Numeric) -> SyncTimeout
+    def database_contention(message, timeout:)
+      build_error(
+        message,
+        timeout:,
+        status: "unknown",
+        waiting_on: "database_contention",
+        activation: {},
+        blocker: nil
+      )
+    end
+
+    # @rbs (MessageReference, timeout: Numeric) -> SyncTimeout
+    def database_contention_for(message_reference, timeout:)
+      error = SyncTimeout.new(
+        timeout:,
+        actor_type: message_reference.actor_type,
+        actor_id: message_reference.actor_id,
+        message_name: "unknown",
+        message_id: message_reference.id,
+        request_id: message_reference.request_id,
+        sequence: message_reference.sequence,
+        status: "unknown",
+        waiting_on: "database_contention",
+        activation: {},
+        blocker: nil
+      )
+      SolidObjects.instrument(
+        :"sync.timeout",
+        message_id: message_reference.id,
+        request_id: message_reference.request_id,
+        actor_type: message_reference.actor_type,
+        actor_id: message_reference.actor_id,
+        sequence: message_reference.sequence,
+        status: "unknown",
+        waiting_on: "database_contention",
+        activation_owner_id: nil,
+        activation_generation: nil
+      )
+      error
+    end
+
+    private
+
+    # @rbs (Message, timeout: Numeric, status: String, waiting_on: String, activation: Hash[String, untyped], blocker: Hash[String, untyped]?) -> SyncTimeout
+    def build_error(message, timeout:, status:, waiting_on:, activation:, blocker:)
       error = SyncTimeout.new(
         timeout:,
         actor_type: message.actor_type,
@@ -21,7 +77,7 @@ module SolidObjects
         status:,
         waiting_on:,
         activation:,
-        blocker: blocker_details(blocker)
+        blocker:
       )
       SolidObjects.instrument(
         :"sync.timeout",
@@ -38,8 +94,6 @@ module SolidObjects
       error
     end
 
-    private
-
     # @rbs (Message) -> String
     def message_status(message)
       return "rejected" if message.rejected?

data/lib/solid_objects/synchronous_invocation.rb

@@ -22,33 +22,49 @@ module SolidObjects
     # @rbs (MessageReference, timeout: Numeric) -> untyped
     def call_before_deadline(message_reference, timeout:)
       deadline = monotonic_now + SyncDeadline.remaining
+      message = nil
 
       loop do
-        message = load_message(message_reference)
-        return completed_result(message) if message.completed? || message.dead?
-
-        remaining = deadline - monotonic_now
-        unless remaining.positive?
-          message = load_message(message_reference)
-          return completed_result(message) if message.completed? || message.dead?
+        unless (deadline - monotonic_now).positive?
+          final_message = load_message_at_deadline(message_reference)
+          return completed_result(final_message) if final_message&.completed? || final_message&.dead?
 
-          raise SyncDiagnostics.new.call(message, timeout:)
+          raise final_message ?
+            diagnose_timeout(final_message, timeout:) :
+            contention_timeout(message, message_reference, timeout:)
         end
 
+        message = load_message(message_reference)
+        return completed_result(message) if message.completed? || message.dead?
+
         processed = assist(message, deadline:)
         remaining = deadline - monotonic_now
         wait(remaining) if processed.zero? && remaining.positive?
       end
     rescue DatabaseDeadlineExceeded
-      message = load_message(message_reference)
-      return completed_result(message) if message.completed? || message.dead?
-
-      raise SyncDiagnostics.new.call(message, timeout:)
+      raise message ?
+        diagnose_timeout(message, timeout:) :
+        contention_timeout(message, message_reference, timeout:)
     end
 
     # @rbs (MessageReference) -> Message
     def load_message(message_reference)
-      Message.uncached { Message.find(message_reference.id) }
+      SolidObjects.database_adapter.with_lock_retry do
+        Message.uncached do
+          Message.includes(:dead_letter).find(message_reference.id)
+        end
+      end
+    end
+
+    # @rbs (MessageReference) -> Message?
+    def load_message_at_deadline(message_reference)
+      SolidObjects.database_adapter.with_lock_probe do
+        Message.uncached do
+          Message.includes(:dead_letter).find(message_reference.id)
+        end
+      end
+    rescue DatabaseDeadlineExceeded
+      nil
     end
 
     # @rbs (Message) -> untyped
@@ -104,6 +120,22 @@ module SolidObjects
       )
     end
 
+    # @rbs (Message, timeout: Numeric) -> SyncTimeout
+    def diagnose_timeout(message, timeout:)
+      SolidObjects.database_adapter.with_lock_probe do
+        SyncDiagnostics.new.call(message, timeout:)
+      end
+    rescue DatabaseDeadlineExceeded
+      SyncDiagnostics.new.database_contention(message, timeout:)
+    end
+
+    # @rbs (Message?, MessageReference, timeout: Numeric) -> SyncTimeout
+    def contention_timeout(message, message_reference, timeout:)
+      return SyncDiagnostics.new.database_contention(message, timeout:) if message
+
+      SyncDiagnostics.new.database_contention_for(message_reference, timeout:)
+    end
+
     # @rbs () -> Float
     def monotonic_now
       ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)

data/lib/solid_objects/turbo_stream_renderer.rb

@@ -40,15 +40,14 @@ module SolidObjects
 
     # @rbs (ComponentRegistration, Integer, Integer) -> String
     def component_refresh(registration, instance_id, revision)
-      target = DomIdentity.component(
-        registration.reference,
-        registration.component_name
-      )
+      return morph_component_refresh(registration, instance_id, revision) if registration.morph?
+
+      target = registration.dom_id
       source = ERB::Util.html_escape(
         registration.refresh_url(instance_id, revision)
       )
       revision_value = "#{instance_id}:#{revision}"
-      %(<turbo-stream action="replace" target="#{target}"><template><turbo-frame id="#{target}" src="#{source}" data-solid-objects-revision="#{revision_value}"></turbo-frame></template></turbo-stream>)
+      %(<turbo-stream action="replace" target="#{target}"><template><turbo-frame id="#{target}" src="#{source}" data-solid-objects-revision="#{revision_value}" data-solid-objects-refresh="replace"></turbo-frame></template></turbo-stream>)
     end
 
     # @rbs (String) -> Hash[String, untyped]?
@@ -75,5 +74,15 @@ module SolidObjects
       JSON.generate(value)
     end
     private_class_method :display_value
+
+    # @rbs (ComponentRegistration, Integer, Integer) -> String
+    def morph_component_refresh(registration, instance_id, revision)
+      source = ERB::Util.html_escape(
+        registration.refresh_url(instance_id, revision)
+      )
+      scope = DomIdentity.scope(registration.reference)
+      %(<turbo-stream action="append" target="#{scope}"><template><solid-objects-refresh data-target="#{registration.dom_id}" data-source="#{source}" data-refresh-method="morph"></solid-objects-refresh></template></turbo-stream>)
+    end
+    private_class_method :morph_component_refresh
   end
 end

data/lib/solid_objects/version.rb

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