openui-rails 0.1.0

data/lib/openui/rails/actions/dispatcher.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Actions
+      # The single authorization and execution path for every write-ish call,
+      # whether it originated from a component `onAction` or a browser
+      # `toolProvider` `Query()`/`Mutation()`. It fails closed: with no
+      # authorizer configured, an action is denied.
+      #
+      # Order of checks (all before any side effect):
+      #   1. resolve + validate the submission
+      #   2. action is registered (allowlist)
+      #   3. args match the schema
+      #   4. confirmation when the action is destructive
+      #   5. surface revision is current (stale protection)
+      #   6. authorizer allows it
+      #   7. idempotency claim (duplicates never execute twice)
+      class Dispatcher
+        # Outcome returned after an action executes or replays.
+        Result = Struct.new(:action, :surface_id, :version, :value, :replayed, keyword_init: true) do
+          def replayed? = replayed == true
+
+          def to_h
+            { action: action, surface_id: surface_id, version: version, value: value, replayed: replayed? }
+          end
+        end
+
+        # Build a dispatcher from the process-wide configuration.
+        #
+        # @param configuration [Configuration]
+        # @return [Dispatcher]
+        def self.from_configuration(configuration = OpenUI::Rails.configuration)
+          new(
+            registry: configuration.action_registry,
+            idempotency_store: configuration.idempotency_store || Idempotency::MemoryStore.new,
+            idempotency_ttl: configuration.idempotency_ttl,
+            authorize_action: configuration.authorize_action,
+            surface_resolver: configuration.surface_resolver,
+            idempotency_scope: configuration.idempotency_scope
+          )
+        end
+
+        # Build a dispatcher with explicit action and replay dependencies.
+        #
+        # @param registry [Registry]
+        #
+        # @param idempotency_store [#claim, #record]
+        #
+        # @param idempotency_ttl [Numeric]
+        #
+        # @param authorize_action [#call, nil]
+        #
+        # @param surface_resolver [#call, nil]
+        #
+        # @param idempotency_scope [#call, nil]
+        #
+        # @return [Dispatcher]
+        def initialize(registry:, idempotency_store:, idempotency_ttl:, authorize_action: nil, surface_resolver: nil,
+                       idempotency_scope: nil)
+          @registry = registry
+          @idempotency_store = idempotency_store
+          @idempotency_ttl = idempotency_ttl
+          @authorize_action = authorize_action
+          @surface_resolver = surface_resolver
+          @idempotency_scope = idempotency_scope
+        end
+
+        # @param payload [Hash, Submission]
+        #
+        # @param actor [Object, nil] authenticated host actor
+        #
+        # @param surface [Object, nil] already-resolved host surface
+        #
+        # @param tenant [Object, nil] trusted host tenant identity
+        #
+        # @param context [Hash] host-supplied request context
+        #
+        # @return [Result]
+        #
+        # @raise [OpenUI::Rails::Error] on any failed gate, before side effects
+        def call(payload, actor: nil, surface: nil, tenant: nil, context: {})
+          submission = Submission.parse(payload)
+          definition = @registry.fetch(submission.action)
+
+          definition.schema.validate!(submission.args)
+          check_confirmation!(definition, submission)
+
+          surface ||= resolve_surface(submission.surface_id, actor, context)
+          check_version!(submission, surface)
+
+          invocation = Invocation.new(
+            action: definition.name,
+            args: submission.args,
+            actor: actor,
+            surface: surface,
+            tenant: tenant,
+            context: context,
+            submission: submission
+          )
+
+          authorize!(definition, invocation)
+
+          replayed, stored, key, token = claim_idempotency(submission, invocation)
+          return result(submission, stored, replayed: true) if replayed
+
+          value = definition.handler.call(invocation)
+          @idempotency_store.record(key, value, claim_token: token)
+          result(submission, value, replayed: false)
+        end
+
+        private
+
+        def check_confirmation!(definition, submission)
+          return if !definition.confirmation || submission.confirmed?
+
+          raise InvalidActionError, "action #{definition.name} requires explicit confirmation"
+        end
+
+        def resolve_surface(surface_id, actor, context)
+          return nil if @surface_resolver.nil?
+
+          surface = @surface_resolver.call(surface_id, actor: actor, context: context)
+          return surface unless surface.nil?
+
+          raise UnauthorizedActionError, "unknown or inaccessible surface"
+        end
+
+        def check_version!(submission, surface)
+          if surface.respond_to?(:id) && surface.id.to_s != submission.surface_id
+            raise UnauthorizedActionError, "resolved surface does not match the submission"
+          end
+          return if surface.nil? || !surface.respond_to?(:version)
+          return if surface.version == submission.version
+
+          raise StaleSurfaceError,
+                "surface #{submission.surface_id} is at version #{surface.version}, " \
+                "action submitted for #{submission.version}"
+        end
+
+        def authorize!(definition, invocation)
+          authorizer = definition.authorize || @authorize_action
+          if authorizer.nil?
+            raise UnauthorizedActionError, "no authorizer configured for action #{definition.name}"
+          end
+
+          return if authorizer.call(invocation)
+
+          raise UnauthorizedActionError, "action #{definition.name} is not permitted"
+        end
+
+        def claim_idempotency(submission, invocation)
+          scope = if @idempotency_scope
+            @idempotency_scope.call(invocation)
+          else
+            [ identity(invocation.tenant), identity(invocation.actor) ]
+          end
+          key = Digest::SHA256.hexdigest(JSON.generate([ scope, submission.idempotency_key ]))
+          digest = Digest::SHA256.hexdigest(JSON.generate(submission.to_h.except(:idempotency_key)))
+          status, stored, stored_digest, token = @idempotency_store.claim(key, ttl: @idempotency_ttl, digest: digest)
+
+          return [ false, nil, key, token ] if status == :claimed
+
+          if stored_digest != digest
+            raise ReplayError, "idempotency key reused with different arguments"
+          end
+
+          raise ReplayError, "duplicate submission is still in progress" if status == :pending
+          raise ConfigurationError, "invalid idempotency store status #{status.inspect}" unless status == :replay
+
+          [ true, stored ]
+        end
+
+        def identity(record)
+          return nil if record.nil?
+          return [ record.class.name, record ] if record.is_a?(String) || record.is_a?(Symbol) || record.is_a?(Numeric)
+          return [ record.class.name, record.id.to_s ] if record.respond_to?(:id) && !record.id.nil?
+
+          raise ConfigurationError, "actor/tenant needs a stable id; configure idempotency_scope for other identities"
+        end
+
+        def result(submission, value, replayed:)
+          Result.new(
+            action: submission.action,
+            surface_id: submission.surface_id,
+            version: submission.version,
+            value: value,
+            replayed: replayed
+          )
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/actions/idempotency/memory_store.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module OpenUI
+  module Rails
+    module Actions
+      module Idempotency
+        # Default, single-process idempotency store. Hosts that run multiple
+        # processes should inject a shared store (e.g. Redis or the database)
+        # that implements the same contract.
+        #
+        # Contract:
+        #   claim(key, ttl:, digest:) -> [status, result, digest, claim_token]
+        #   status is :claimed, :pending or :replay (even for a nil result).
+        #   record(key, result, claim_token:) ignores an expired/replaced claim.
+        class MemoryStore
+          def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+            @entries = {}
+            @mutex = Mutex.new
+            @clock = clock
+          end
+
+          def claim(key, ttl:, digest: nil)
+            raise ConfigurationError, "idempotency ttl must be positive" unless ttl.is_a?(Numeric) && ttl.finite? && ttl > 0
+
+            @mutex.synchronize do
+              now = @clock.call
+              purge(now)
+
+              if (entry = @entries[key])
+                return [ entry[:completed] ? :replay : :pending, entry[:result], entry[:digest], entry[:token] ]
+              end
+
+              token = SecureRandom.hex(16)
+              @entries[key] = { digest: digest, result: nil, completed: false, token: token, expires_at: now + ttl }
+              [ :claimed, nil, digest, token ]
+            end
+          end
+
+          def record(key, result, claim_token:)
+            @mutex.synchronize do
+              entry = @entries[key]
+              if entry && entry[:token] == claim_token && entry[:expires_at] > @clock.call
+                entry[:result] = result
+                entry[:completed] = true
+              end
+            end
+          end
+
+          def size
+            @mutex.synchronize { @entries.size }
+          end
+
+          private
+
+          def purge(now)
+            @entries.reject! { |_key, entry| entry[:expires_at] <= now }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/actions/invocation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Actions
+      # Everything an authorizer or handler needs to decide and act, without
+      # handing them the raw client payload.
+      Invocation = Struct.new(
+        :action, :args, :actor, :surface, :tenant, :context, :submission,
+        keyword_init: true
+      ) do
+        def message_id = context[:message_id]
+      end
+    end
+  end
+end

data/lib/openui/rails/actions/registry.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Actions
+      # The allowlist of actions a model-generated surface may invoke. Only
+      # handlers registered here are reachable: there is no reflection from a
+      # model-provided name to a Ruby method.
+      class Registry
+        # Immutable definition stored by the registry and passed to dispatch.
+        Definition = Struct.new(:name, :handler, :authorize, :schema, :confirmation, :description, keyword_init: true)
+
+        # Pattern accepted for action names sent over the wire.
+        NAME_PATTERN = /\A[a-zA-Z][a-zA-Z0-9_.:-]{0,63}\z/
+
+        # Create an empty action allowlist.
+        #
+        # @return [Registry]
+        def initialize
+          @definitions = {}
+          @mutex = Mutex.new
+        end
+
+        # Register a callable action.
+        #
+        # @param name [String, Symbol] the wire name the surface emits
+        #
+        # @param handler [#call] receives an Invocation, performs the work
+        #
+        # @param authorize [#call, nil] receives an Invocation, returns truthy
+        #   when allowed. Required at dispatch time (fail closed).
+        #
+        # @param schema [Schema, Hash, #call, nil] arg validation
+        #
+        # @param confirmation [Boolean] require `confirmed: true` on the payload
+        #
+        # @param description [String, nil] text describing the action
+        #
+        # @return [Definition]
+        def register(name, handler: nil, authorize: nil, schema: nil, confirmation: false, description: nil, &block)
+          handler ||= block
+          raise ConfigurationError, "handler is required for action #{name.inspect}" unless handler.respond_to?(:call)
+          unless authorize.nil? || authorize.respond_to?(:call)
+            raise ConfigurationError, "authorize must respond to #call"
+          end
+
+          definition = Definition.new(
+            name: normalize_name(name).dup.freeze,
+            handler: handler,
+            authorize: authorize,
+            schema: Schema.from(schema),
+            confirmation: confirmation ? true : false,
+            description: description
+          ).freeze
+
+          @mutex.synchronize { @definitions[definition.name] = definition }
+          definition
+        end
+
+        # Find a registered action or raise when it is not allowlisted.
+        #
+        # @param name [String, Symbol]
+        #
+        # @return [Definition]
+        #
+        # @raise [UnknownActionError] when no action has this name
+        def fetch(name)
+          definition = @mutex.synchronize { @definitions[normalize_name(name)] }
+          raise UnknownActionError, "unknown action #{name.inspect}" if definition.nil?
+
+          definition
+        rescue ConfigurationError => error
+          raise InvalidActionError, error.message
+        end
+
+        # Whether an action name is present in the allowlist.
+        #
+        # @param name [String, Symbol]
+        #
+        # @return [Boolean]
+        def registered?(name)
+          @mutex.synchronize { @definitions.key?(normalize_name(name)) }
+        end
+
+        # Return the registered action names.
+        #
+        # @return [Array<String>]
+        def names
+          @mutex.synchronize { @definitions.keys }
+        end
+
+        # Remove all registered actions.
+        #
+        # @return [self]
+        def clear!
+          @mutex.synchronize { @definitions.clear }
+          self
+        end
+
+        private
+
+        def normalize_name(name)
+          name = name.to_s
+          unless name.match?(NAME_PATTERN)
+            raise ConfigurationError, "invalid action name #{name.inspect}"
+          end
+
+          name
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/actions/schema.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Actions
+      # Validates the `args` of an action submission against a small, explicit
+      # contract. It is intentionally not a general-purpose schema language: it
+      # only ensures the shape a host handler relies on, so a malformed payload
+      # is rejected before any side effect.
+      class Schema
+        # Wraps a host predicate. Returning false (or raising) rejects the args.
+        class Callable
+          def initialize(callable)
+            @callable = callable
+          end
+
+          def validate!(args)
+            raise InvalidActionError, "action arguments must be an object" unless args.is_a?(Hash)
+            raise InvalidActionError, "action arguments failed validation" unless @callable.call(args)
+
+            args
+          end
+        end
+
+        # A schema that accepts any JSON object.
+        def self.any
+          new(required: {}, optional: {}, allow_extra: true)
+        end
+
+        def self.define(required: {}, optional: {}, allow_extra: false)
+          new(required: required || {}, optional: optional || {}, allow_extra: allow_extra)
+        end
+
+        # Build a schema from a Hash of required types, an existing Schema or a
+        # callable predicate.
+        def self.from(value)
+          case value
+          when nil then any
+          when Schema, Callable then value
+          when Hash then new(required: value, allow_extra: false)
+          else
+            unless value.respond_to?(:call)
+              raise ConfigurationError, "schema must be a Hash, Schema, or respond to #call"
+            end
+
+            Callable.new(value)
+          end
+        end
+
+        attr_reader :required, :optional
+
+        def initialize(required: {}, optional: {}, allow_extra: false)
+          @required = required
+          @optional = optional
+          @allow_extra = allow_extra
+        end
+
+        def allow_extra? = @allow_extra
+
+        def validate!(args)
+          raise InvalidActionError, "action arguments must be an object" unless args.is_a?(Hash)
+
+          values = normalize(args)
+          validate_required(values)
+          validate_optional(values)
+          validate_extras(values.keys) unless allow_extra?
+          args
+        end
+
+        private
+
+        def normalize(args)
+          args.each_with_object({}) { |(key, value), memo| memo[key.to_s] = value }
+        end
+
+        def validate_required(values)
+          required.each do |key, expected|
+            name = key.to_s
+            raise InvalidActionError, "missing required argument #{name}" unless values.key?(name)
+            next if type_matches?(values[name], expected)
+
+            raise InvalidActionError, "argument #{name} has an invalid value"
+          end
+        end
+
+        def validate_optional(values)
+          optional.each do |key, expected|
+            name = key.to_s
+            next unless values.key?(name)
+            next if type_matches?(values[name], expected)
+
+            raise InvalidActionError, "argument #{name} has an invalid value"
+          end
+        end
+
+        def validate_extras(keys)
+          allowed = (required.keys + optional.keys).map(&:to_s)
+          extra = keys - allowed
+          return if extra.empty?
+
+          raise InvalidActionError, "unexpected arguments: #{extra.join(", ")}"
+        end
+
+        def type_matches?(value, expected)
+          case expected
+          when Array then expected.any? { |candidate| type_matches?(value, candidate) }
+          when Regexp then value.is_a?(String) && expected.match?(value)
+          when Module then value.is_a?(expected)
+          else expected.respond_to?(:call) ? expected.call(value) == true : false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/actions/submission.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module OpenUI
+  module Rails
+    module Actions
+      # Validated, immutable view of the payload emitted by a component
+      # `onAction` or a browser `toolProvider` `Query()`/`Mutation()` call:
+      #
+      #   { action:, args:, surface_id:, version:, idempotency_key: }
+      #
+      # `confirmed` is the Gem's explicit-confirmation flag for destructive
+      # actions. Unknown keys are ignored; known keys are validated strictly.
+      class Submission
+        MAX_IDEMPOTENCY_KEY_BYTES = 200
+
+        attr_reader :action, :args, :surface_id, :version, :idempotency_key, :confirmed
+
+        def self.parse(payload)
+          return payload if payload.is_a?(Submission)
+
+          raise InvalidActionError, "action payload must be an object" unless payload.is_a?(Hash)
+
+          values = payload.each_with_object({}) { |(key, value), memo| memo[key.to_s] = value }
+
+          new(
+            action: values["action"],
+            args: values.fetch("args", {}),
+            surface_id: values["surface_id"] || values["surfaceId"],
+            version: values["version"],
+            idempotency_key: values["idempotency_key"] || values["idempotencyKey"],
+            confirmed: values["confirmed"] == true
+          )
+        end
+
+        def initialize(action:, surface_id:, version:, idempotency_key:, args: {}, confirmed: false)
+          @action = validate_string(action, "action")
+          @surface_id = validate_string(surface_id, "surface_id")
+          @idempotency_key = validate_idempotency_key(idempotency_key)
+          @version = validate_version(version)
+          @args = validate_args(args)
+          @confirmed = confirmed == true
+          @args_digest = Digest::SHA256.hexdigest(JSON.generate(@args)).freeze
+          freeze
+        end
+
+        def confirmed? = confirmed
+
+        # Stable digest of the args, used for idempotency conflict detection.
+        attr_reader :args_digest
+
+        def to_h
+          {
+            action: action,
+            args: args,
+            surface_id: surface_id,
+            version: version,
+            idempotency_key: idempotency_key,
+            confirmed: confirmed
+          }
+        end
+
+        private
+
+        def validate_string(value, name)
+          string = value.to_s
+          raise InvalidActionError, "#{name} is required" if string.empty?
+          raise InvalidActionError, "#{name} must be a scalar" unless value.is_a?(String) || value.is_a?(Symbol)
+
+          string.dup.freeze
+        end
+
+        def validate_idempotency_key(value)
+          key = validate_string(value, "idempotency_key")
+          if key.bytesize > MAX_IDEMPOTENCY_KEY_BYTES
+            raise InvalidActionError, "idempotency_key exceeds #{MAX_IDEMPOTENCY_KEY_BYTES} bytes"
+          end
+
+          key
+        end
+
+        def validate_version(value)
+          unless value.is_a?(Integer) && value >= 0
+            raise InvalidActionError, "version must be a non-negative Integer"
+          end
+
+          value
+        end
+
+        def validate_args(value)
+          raise InvalidActionError, "args must be an object" unless value.is_a?(Hash)
+
+          JsonValue.copy(value)
+        rescue ArgumentError => error
+          raise InvalidActionError, error.message
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/actions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "openui/rails/actions/schema"
+require "openui/rails/actions/registry"
+require "openui/rails/actions/submission"
+require "openui/rails/actions/invocation"
+require "openui/rails/actions/idempotency/memory_store"
+require "openui/rails/actions/dispatcher"
+
+module OpenUI
+  module Rails
+    # Server-authoritative action loop: an allowlist registry, arg validation,
+    # a host authorizer, stale-surface protection and idempotency, shared by
+    # both component actions and browser tool calls.
+    module Actions
+    end
+  end
+end