solid_objects 0.2.1 → 0.4.0

data/lib/solid_objects/client.rb

@@ -50,16 +50,57 @@ module SolidObjects
         arguments,
         authorization_context:
       )
-      message_reference = mailbox.enqueue(
+      reject_sync_inside_transaction!(reference, message_name)
+      SyncDeadline.with(timeout:) do
+        message_reference = enqueue_sync(
+          reference,
+          message_name,
+          arguments,
+          idempotency_key:,
+          timeout:
+        )
+        SynchronousInvocation.new.call(message_reference, timeout:)
+      end
+    end
+
+    # @rbs (MessageReference, timeout: Numeric, ?authorization_context: untyped) -> untyped
+    def wait(message_reference, timeout:, authorization_context: nil)
+      message = Message.find(message_reference.id)
+      validate_message_reference!(message_reference, message)
+      reference = Reference.new(
+        actor_type: message.actor_type,
+        actor_id: message.actor_id
+      )
+      actor_class = SolidObjects.registry.fetch(reference.actor_type)
+      query = actor_class.definition.queries.key?(message.message_name.to_sym)
+      actor_message = actor_class.definition.messages.key?(message.message_name.to_sym)
+      unless query || actor_message
+        raise UnknownMessage, "unknown message #{message.message_name.inspect}"
+      end
+      authorize!(
+        query ? SolidObjects.configuration.authorize_query : SolidObjects.configuration.authorize_message,
         reference,
-        message_name,
-        arguments,
-        kind: "sync",
-        idempotency_key:
+        message.message_name,
+        message.arguments,
+        authorization_context:
       )
+      reject_sync_inside_transaction!(reference, message.message_name)
       SynchronousInvocation.new.call(message_reference, timeout:)
     end
 
+    # @rbs (Reference, ?authorization_context: untyped) -> StateSnapshot
+    def snapshot(reference, authorization_context: nil)
+      SolidObjects.registry.fetch(reference.actor_type)
+      authorize!(
+        SolidObjects.configuration.authorize_query,
+        reference,
+        "__snapshot__",
+        {},
+        authorization_context:
+      )
+      StateSnapshot.new(reference)
+    end
+
     # @rbs (Reference, ?authorization_context: untyped) -> bool
     def destroy(reference, authorization_context: nil)
       raise ActorCallCycle, "actors cannot synchronously destroy another actor" if Context.current_actor
@@ -93,6 +134,58 @@ module SolidObjects
 
     attr_reader :mailbox
 
+    # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], idempotency_key: String?, timeout: Numeric) -> MessageReference
+    def enqueue_sync(reference, message_name, arguments, idempotency_key:, timeout:)
+      mailbox.enqueue(
+        reference,
+        message_name,
+        arguments,
+        kind: "sync",
+        idempotency_key:
+      )
+    rescue DatabaseDeadlineExceeded
+      SolidObjects.instrument(
+        :"sync.enqueue_timeout",
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s
+      )
+      raise SyncEnqueueTimeout.new(
+        timeout:,
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s
+      )
+    end
+
+    # @rbs (MessageReference, Message) -> void
+    def validate_message_reference!(message_reference, message)
+      valid = message_reference.request_id == message.request_id &&
+        message_reference.actor_type == message.actor_type &&
+        message_reference.actor_id == message.actor_id &&
+        message_reference.sequence == message.sequence
+      return if valid
+
+      raise ActorDestroyed, "message reference no longer identifies this invocation"
+    end
+
+    # @rbs (Reference, Symbol | String) -> void
+    def reject_sync_inside_transaction!(reference, message_name)
+      return unless SolidObjects::Record.connection.transaction_open?
+
+      SolidObjects.instrument(
+        :"sync.transaction_rejected",
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s
+      )
+      raise SyncInsideTransaction.new(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s
+      )
+    end
+
     # @rbs (Proc, Reference, Symbol | String, Hash[Symbol | String, untyped], authorization_context: untyped) -> void
     def authorize!(hook, reference, message_name, arguments, authorization_context:)
       authorized = hook.call(

data/lib/solid_objects/commit_action_registry.rb

@@ -0,0 +1,42 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  CommitActionContext = Data.define(
+    :message_id,
+    :request_id,
+    :actor_type,
+    :actor_id,
+    :activation_generation
+  )
+
+  class CommitActionRegistry
+    # @rbs @handlers: Hash[String, Proc]
+    # @rbs @mutex: Mutex
+
+    # @rbs () -> void
+    def initialize
+      @handlers = {}
+      @mutex = Mutex.new
+    end
+
+    # @rbs (String | Symbol, Proc) -> Proc
+    def register(name, handler)
+      action_name = name.to_s
+      raise ArgumentError, "commit action name cannot be empty" if action_name.empty?
+
+      mutex.synchronize { handlers[action_name] = handler }
+      handler
+    end
+
+    # @rbs (String | Symbol) -> Proc
+    def fetch(name)
+      handlers.fetch(name.to_s) do
+        raise UnknownCommitAction, "no commit action registered for #{name.inspect}"
+      end
+    end
+
+    private
+
+    attr_reader :handlers, :mutex
+  end
+end

data/lib/solid_objects/component_path_resolver.rb

@@ -0,0 +1,27 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ComponentPathResolver
+    # @rbs (view_context: untyped) -> String
+    def call(view_context:)
+      unless mounted?
+        raise UnsupportedComponentRendering,
+          "reactive components require the SolidObjects::Engine to be mounted in the host routes"
+      end
+
+      SolidObjects::Engine.routes.url_helpers.components_path
+    end
+
+    private
+
+    # @rbs () -> bool
+    def mounted?
+      return false unless defined?(Rails) && Rails.application
+
+      Rails.application.routes.routes.any? do |route|
+        route.app.respond_to?(:app) &&
+          route.app.app.equal?(SolidObjects::Engine)
+      end
+    end
+  end
+end

data/lib/solid_objects/component_registration.rb

@@ -0,0 +1,117 @@
+# rbs_inline: enabled
+
+require "uri"
+
+module SolidObjects
+  class ComponentRegistration
+    # @rbs @reference: Reference
+    # @rbs @component_name: String
+    # @rbs @dependencies: Array[String]
+    # @rbs @instance_id: Integer
+    # @rbs @revision: Integer
+    # @rbs @refresh_path: String
+    # @rbs @token: String
+
+    attr_reader :reference,
+      :component_name,
+      :dependencies,
+      :instance_id,
+      :revision,
+      :refresh_path,
+      :token
+
+    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, token: String) -> void
+    def initialize(
+      reference:,
+      component_name:,
+      dependencies:,
+      instance_id:,
+      revision:,
+      refresh_path:,
+      token:
+    )
+      @reference = reference
+      @component_name = component_name
+      @dependencies = dependencies.freeze
+      @instance_id = instance_id
+      @revision = revision
+      @refresh_path = refresh_path
+      @token = token
+    end
+
+    class << self
+      # @rbs (reference: Reference, component_name: String, dependencies: Array[String], snapshot: ActorSnapshot, refresh_path: String) -> ComponentRegistration
+      def issue(reference:, component_name:, dependencies:, snapshot:, refresh_path:)
+        token = ComponentToken.generate(
+          reference:,
+          component_name:,
+          dependencies:,
+          instance_id: snapshot.instance_id,
+          revision: snapshot.revision,
+          refresh_path:
+        )
+        new(
+          reference:,
+          component_name:,
+          dependencies:,
+          instance_id: snapshot.instance_id,
+          revision: snapshot.revision,
+          refresh_path:,
+          token:
+        )
+      end
+
+      # @rbs (String) -> ComponentRegistration
+      def from_token(token)
+        payload = ComponentToken.verify(token)
+        reference = Reference.new(
+          actor_type: payload.fetch("actor_type"),
+          actor_id: payload.fetch("actor_id")
+        )
+        dependencies = payload.fetch("dependencies")
+        validate_dependencies!(reference, dependencies)
+        new(
+          reference:,
+          component_name: payload.fetch("component_name"),
+          dependencies:,
+          instance_id: payload.fetch("instance_id"),
+          revision: payload.fetch("revision"),
+          refresh_path: payload.fetch("refresh_path"),
+          token:
+        )
+      rescue UnknownActorType, UnknownComponentDependency => error
+        raise InvalidComponentToken, error.message
+      end
+
+      private
+
+      # @rbs (Reference, Array[String]) -> void
+      def validate_dependencies!(reference, dependencies)
+        actor_class = SolidObjects.registry.fetch(reference.actor_type)
+        observables = actor_class.definition.observables
+        unknown = dependencies.find do |dependency|
+          !observables.key?(dependency.to_sym)
+        end
+        return unless unknown
+
+        raise UnknownComponentDependency,
+          "unknown observable dependency #{unknown.inspect} for #{reference.actor_type}"
+      end
+    end
+
+    # @rbs () -> Array[Integer]
+    def revision_key
+      [ instance_id, revision ]
+    end
+
+    # @rbs (Integer, Integer) -> String
+    def refresh_url(instance_id, revision)
+      query = URI.encode_www_form(
+        token:,
+        instance_id:,
+        revision:
+      )
+      "#{refresh_path}?#{query}"
+    end
+  end
+end

data/lib/solid_objects/component_renderer.rb

@@ -0,0 +1,82 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ComponentRenderer
+    # @rbs @snapshot: ActorSnapshot
+    # @rbs @component_name: String
+    # @rbs @dependencies: Array[String]
+    # @rbs @view_context: untyped
+    # @rbs @authorization_context: untyped
+
+    # @rbs (snapshot: ActorSnapshot, component_name: String, dependencies: Array[String], view_context: untyped, authorization_context: untyped) -> void
+    def initialize(
+      snapshot:,
+      component_name:,
+      dependencies:,
+      view_context:,
+      authorization_context:
+    )
+      @snapshot = snapshot
+      @component_name = component_name
+      @dependencies = dependencies
+      @view_context = view_context
+      @authorization_context = authorization_context
+    end
+
+    # @rbs () -> untyped
+    def call
+      [ component_name, *dependencies ].uniq.each do |authorization_name|
+        authorize_read!(authorization_name)
+      end
+      actor = ComponentView.new(
+        snapshot:,
+        dependencies:,
+        authorization_context:
+      )
+      view_context.render(
+        partial: default_partial,
+        locals: {
+          actor:,
+          authorization_context:
+        }
+      )
+    rescue ActionView::MissingTemplate
+      raise UnknownComponent,
+        "unknown component #{component_name.inspect} for #{snapshot.reference.actor_type}"
+    rescue ActionView::Template::Error => error
+      raise error.cause if error.cause.is_a?(SolidObjects::Error)
+
+      raise
+    end
+
+    private
+
+    attr_reader :snapshot,
+      :component_name,
+      :dependencies,
+      :view_context,
+      :authorization_context
+
+    # @rbs (String) -> void
+    def authorize_read!(observable_name)
+      authorized = SolidObjects.configuration.authorize_query.call(
+        actor_type: snapshot.reference.actor_type,
+        actor_id: snapshot.reference.actor_id,
+        message_name: observable_name,
+        arguments: {},
+        authorization_context:
+      )
+      return if authorized
+
+      raise Unauthorized, "actor component query is not authorized"
+    end
+
+    # @rbs () -> String
+    def default_partial
+      actor_name = snapshot.actor_class.name
+      raise InvalidActor, "anonymous actors cannot render reactive components" unless actor_name
+
+      "actors/#{actor_name.underscore}/#{component_name}"
+    end
+  end
+end

data/lib/solid_objects/component_subscriptions.rb

@@ -0,0 +1,109 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ComponentSubscriptions
+    MAXIMUM_COMPONENTS = 50
+    MAXIMUM_SERIALIZED_BYTES = 1_048_576
+
+    # @rbs @registrations: Array[ComponentRegistration]
+    # @rbs @revisions: Hash[String, Array[Integer]]
+
+    # @rbs (String?, reference: Reference) -> ComponentSubscriptions
+    def self.parse(serialized, reference:)
+      return new([]) unless serialized
+      unless serialized.is_a?(String) &&
+          serialized.bytesize <= MAXIMUM_SERIALIZED_BYTES
+        raise InvalidComponentToken, "invalid actor component registrations"
+      end
+
+      tokens = JSON.parse(serialized)
+      unless tokens.is_a?(Array) &&
+          tokens.length <= MAXIMUM_COMPONENTS &&
+          tokens.all? { |token| token.is_a?(String) }
+        raise InvalidComponentToken, "invalid actor component registrations"
+      end
+
+      registrations = tokens.map do |token|
+        ComponentRegistration.from_token(token).tap do |registration|
+          validate_identity!(registration, reference)
+        end
+      end
+      if registrations.map(&:component_name).uniq.length != registrations.length
+        raise InvalidComponentToken, "duplicate actor component registration"
+      end
+
+      new(registrations)
+    end
+
+    # @rbs (Array[ComponentRegistration]) -> void
+    def initialize(registrations)
+      @registrations = registrations
+      @revisions = registrations.to_h do |registration|
+        [ registration.component_name, registration.revision_key ]
+      end
+    end
+
+    # @rbs (Hash[String, untyped]) -> Array[String]
+    def refreshes_for(invalidation)
+      observable_name = invalidation.fetch("observable_name")
+      instance_id = invalidation.fetch("instance_id")
+      revision = invalidation.fetch("revision")
+      registrations.filter_map do |registration|
+        next unless registration.dependencies.include?(observable_name)
+        next unless newer_revision?(
+          registration.component_name,
+          instance_id,
+          revision
+        )
+
+        refresh(registration, instance_id, revision)
+      end
+    end
+
+    # @rbs (ActorSnapshot) -> Array[String]
+    def reconnect_refreshes(snapshot)
+      registrations.filter_map do |registration|
+        next unless newer_revision?(
+          registration.component_name,
+          snapshot.instance_id,
+          snapshot.revision
+        )
+
+        refresh(registration, snapshot.instance_id, snapshot.revision)
+      end
+    end
+
+    class << self
+      private
+
+      # @rbs (ComponentRegistration, Reference) -> void
+      def validate_identity!(registration, reference)
+        return if registration.reference.actor_type == reference.actor_type &&
+          registration.reference.actor_id == reference.actor_id
+
+        raise InvalidComponentToken,
+          "actor component identity does not match its subscription"
+      end
+    end
+
+    private
+
+    attr_reader :registrations, :revisions
+
+    # @rbs (ComponentRegistration, Integer, Integer) -> String
+    def refresh(registration, instance_id, revision)
+      revisions[registration.component_name] = [ instance_id, revision ]
+      TurboStreamRenderer.component_refresh(
+        registration,
+        instance_id,
+        revision
+      )
+    end
+
+    # @rbs (String, Integer, Integer) -> bool
+    def newer_revision?(component_name, instance_id, revision)
+      current = revisions.fetch(component_name)
+      (current <=> [ instance_id, revision ]) == -1
+    end
+  end
+end

data/lib/solid_objects/component_token.rb

@@ -0,0 +1,139 @@
+# rbs_inline: enabled
+
+require "active_support/message_verifier"
+
+module SolidObjects
+  module ComponentToken
+    PURPOSE = "solid_objects.actor_component"
+    MAXIMUM_TOKEN_BYTES = 16_384
+    MAXIMUM_DEPENDENCIES = 50
+
+    module_function
+
+    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String) -> String
+    def generate(
+      reference:,
+      component_name:,
+      dependencies:,
+      instance_id:,
+      revision:,
+      refresh_path:
+    )
+      payload = {
+        "actor_type" => reference.actor_type,
+        "actor_id" => reference.actor_id,
+        "component_name" => component_name,
+        "dependencies" => dependencies,
+        "instance_id" => instance_id,
+        "revision" => revision,
+        "refresh_path" => refresh_path
+      }
+      validate_payload!(payload)
+      verifier.generate(payload, purpose: PURPOSE).tap do |token|
+        raise InvalidComponentToken, "component token is too large" if token.bytesize > MAXIMUM_TOKEN_BYTES
+      end
+    end
+
+    # @rbs (String) -> Hash[String, untyped]
+    def verify(token)
+      unless token.is_a?(String) && token.bytesize <= MAXIMUM_TOKEN_BYTES
+        raise InvalidComponentToken, "invalid actor component token"
+      end
+
+      payload = verifier.verified(token, purpose: PURPOSE)
+      validate_payload!(payload)
+      payload
+    rescue ActiveSupport::MessageVerifier::InvalidSignature
+      raise InvalidComponentToken, "invalid actor component token"
+    end
+
+    # @rbs (Hash[String, untyped]) -> Hash[String, untyped]
+    def validate_payload!(payload)
+      unless payload.is_a?(Hash) &&
+          payload["actor_type"].is_a?(String) &&
+          payload["actor_id"].is_a?(String) &&
+          payload["component_name"].is_a?(String) &&
+          payload["dependencies"].is_a?(Array) &&
+          payload["instance_id"].is_a?(Integer) &&
+          payload["revision"].is_a?(Integer) &&
+          payload["refresh_path"].is_a?(String)
+        raise InvalidComponentToken, "invalid actor component token"
+      end
+
+      validate_component_name!(payload.fetch("component_name"))
+      validate_dependencies!(payload.fetch("dependencies"))
+      validate_revision!(
+        payload.fetch("instance_id"),
+        payload.fetch("revision")
+      )
+      validate_refresh_path!(payload.fetch("refresh_path"))
+      payload
+    end
+    private_class_method :validate_payload!
+
+    # @rbs (String) -> void
+    def validate_component_name!(component_name)
+      return if component_name.match?(/\A[a-zA-Z0-9_]+\z/)
+
+      raise InvalidComponentToken, "invalid actor component name"
+    end
+    private_class_method :validate_component_name!
+
+    # @rbs (Array[untyped]) -> void
+    def validate_dependencies!(dependencies)
+      valid = dependencies.any? &&
+        dependencies.length <= MAXIMUM_DEPENDENCIES &&
+        dependencies.uniq.length == dependencies.length &&
+        dependencies.all? { |dependency| dependency.is_a?(String) && dependency.match?(/\A[a-zA-Z0-9_]+\z/) }
+      return if valid
+
+      raise InvalidComponentToken, "invalid actor component dependencies"
+    end
+    private_class_method :validate_dependencies!
+
+    # @rbs (Integer, Integer) -> void
+    def validate_revision!(instance_id, revision)
+      return unless instance_id.negative? || revision.negative?
+
+      raise InvalidComponentToken, "invalid actor component revision"
+    end
+    private_class_method :validate_revision!
+
+    # @rbs (String) -> void
+    def validate_refresh_path!(refresh_path)
+      valid = refresh_path.bytesize <= 2_048 &&
+        refresh_path.start_with?("/") &&
+        !refresh_path.start_with?("//") &&
+        !refresh_path.include?("\0") &&
+        !refresh_path.include?("?") &&
+        !refresh_path.include?("#")
+      return if valid
+
+      raise InvalidComponentToken, "invalid actor component refresh path"
+    end
+    private_class_method :validate_refresh_path!
+
+    # @rbs () -> ActiveSupport::MessageVerifier
+    def verifier
+      ActiveSupport::MessageVerifier.new(
+        signing_secret,
+        digest: "SHA256",
+        serializer: JSON
+      )
+    end
+    private_class_method :verifier
+
+    # @rbs () -> String
+    def signing_secret
+      configured_secret = SolidObjects.configuration.stream_signing_secret
+      return configured_secret if configured_secret
+
+      if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+        return Rails.application.key_generator.generate_key(PURPOSE, 64)
+      end
+
+      raise ArgumentError, "configure stream_signing_secret outside a Rails application"
+    end
+    private_class_method :signing_secret
+  end
+end