openui-rails 0.1.0

data/lib/openui/rails/adapters/ruby_llm.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "openui/rails/stream/bridge"
+
+module OpenUI
+  module Rails
+    module Adapters
+      # Optional RubyLLM adapter. It owns RubyLLM-specific event normalization
+      # and delegates sequencing, coalescing and size limits to the Stream
+      # bridge, so a host keeps using RubyLLM's own Rails streaming pattern
+      # (`chat.complete { |chunk| ... }` in a job) instead of replacing it.
+      #
+      # `ruby_llm` is never required by the Gem and no `RubyLLM` constant is
+      # referenced: failures are classified by class *name*, so this unit loads
+      # and is tested without the dependency installed. The supported RubyLLM
+      # version is pinned in the README compatibility matrix.
+      module RubyLLM
+        STRATEGIES = %i[complete ask].freeze
+
+        class << self
+          # Stream a RubyLLM completion, yielding ordered {Stream::Envelope}s.
+          #
+          # @param chat [#complete, #ask] a RubyLLM chat (or a duck type)
+          # @param question [String] the user prompt
+          # @param surface_id [String, #to_s] the target surface
+          # @param strategy [Symbol] :complete (default) or :ask
+          # @yieldparam envelope [Stream::Envelope]
+          # @return [Stream::Bridge::Writer] for inspection in tests
+          def stream(chat:, question:, surface_id:, message_id: nil, library_version: nil,
+                     instruction: nil, strategy: :complete,
+                     configuration: OpenUI::Rails.configuration, &block)
+            raise ConfigurationError, "surface_id is required" if surface_id.nil?
+            raise ConfigurationError, "a block is required" unless block
+            unless STRATEGIES.include?(strategy)
+              raise ConfigurationError, "unsupported strategy #{strategy.inspect}; expected one of #{STRATEGIES.inspect}"
+            end
+
+            instruction ||= PromptBuilder.load(configuration).system_instruction
+            library_version ||= configuration.library_fingerprint
+            chat = apply_instruction(chat, instruction)
+
+            writer = Stream::Bridge.new(
+              message_id: message_id || surface_id.to_s,
+              library_version: library_version,
+              configuration: configuration
+            ).writer
+
+            begin
+              consumer_failed = false
+              deliver = lambda do |envelope|
+                begin
+                  block.call(envelope)
+                rescue StandardError
+                  consumer_failed = true
+                  raise
+                end
+              end
+              consume(chat, question, strategy) do |chunk|
+                text = normalize_chunk(chunk)
+                next if text.nil?
+
+                writer.push(text).each(&deliver)
+              end
+              writer.finish.each(&deliver)
+            rescue StandardError => e
+              raise if consumer_failed
+
+              envelope = writer.error_for(e, code: error_code_for(e))
+              block.call(envelope) if envelope
+            end
+
+            writer
+          end
+
+          private
+
+          def apply_instruction(chat, instruction)
+            return chat unless chat.respond_to?(:with_instructions)
+
+            chat.with_instructions(instruction)
+          end
+
+          def consume(chat, question, strategy, &block)
+            case strategy
+            when :complete
+              # RubyLLM::Chat#complete only accepts a block. A user message is
+              # added explicitly; #ask is the convenient alternative strategy.
+              chat.add_message(role: :user, content: question) unless question.nil?
+              chat.complete(&block)
+            when :ask then chat.ask(question, &block)
+            end
+          end
+
+          def normalize_chunk(chunk)
+            return chunk if chunk.is_a?(String)
+            return nil unless chunk.respond_to?(:content)
+
+            content = chunk.content
+            content.nil? ? nil : content.to_s
+          end
+
+          def error_code_for(error)
+            name = error.class.name
+            return "stream_cancelled" if name == "RubyLLM::CancelledError"
+            return "provider_rejected" if name&.start_with?("RubyLLM::")
+
+            "stream_failed"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/configuration.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    # Global, process-wide configuration for the gem.
+    #
+    #   OpenUI::Rails.configure do |config|
+    #     config.transport = :turbo
+    #     config.library_spec_path = Rails.root.join("config/openui/library.spec.json")
+    #     config.runtime_assets = :self_hosted
+    #   end
+    class Configuration
+      # Transport names accepted by the host preference setting.
+      TRANSPORTS = %i[turbo action_cable none].freeze
+
+      # Runtime asset strategies supported by the gem.
+      ASSET_STRATEGIES = %i[self_hosted external].freeze
+
+      # Maximum response size passed through the stream bridge, in bytes.
+      DEFAULT_STREAM_BYTE_LIMIT = 1_048_576 # 1 MiB of OpenUI Lang per message
+
+      # Buffer size before the bridge emits a delta, in bytes.
+      DEFAULT_PENDING_BYTE_LIMIT = 32_768   # flush threshold while streaming
+
+      # Lifetime of an action idempotency claim, in seconds.
+      DEFAULT_IDEMPOTENCY_TTL = 15 * 60     # seconds
+
+      # Default engine endpoint for action submissions.
+      DEFAULT_ACTIONS_ENDPOINT = "/openui-rails/actions"
+
+      attr_reader :transport, :runtime_assets
+      attr_accessor :library_spec_path, :prompt_path, :library_name,
+                    :actions_endpoint, :surface_id_param,
+                    :stream_byte_limit, :pending_byte_limit, :idempotency_ttl,
+                    :authorize_action, :on_error, :action_registry, :surface_resolver, :actor_resolver,
+                    :runtime_version, :runtime_url, :runtime_integrity, :local_runtime_path,
+                    :idempotency_scope, :runtime_stylesheet_url, :runtime_stylesheet_integrity
+
+      # Create the default integration settings.
+      #
+      # @return [Configuration]
+      def initialize
+        @transport = :turbo
+        @runtime_assets = :self_hosted
+        @library_spec_path = nil
+        @prompt_path = nil
+        @library_name = :chat
+        @actions_endpoint = DEFAULT_ACTIONS_ENDPOINT
+        @surface_id_param = :surface_id
+        @stream_byte_limit = DEFAULT_STREAM_BYTE_LIMIT
+        @pending_byte_limit = DEFAULT_PENDING_BYTE_LIMIT
+        @idempotency_ttl = DEFAULT_IDEMPOTENCY_TTL
+        @idempotency_store = nil
+        @authorize_action = nil
+        @on_error = nil
+        @action_registry = nil
+        @surface_resolver = nil
+        @actor_resolver = nil
+        @runtime_version = nil
+        @runtime_url = nil
+        @runtime_integrity = nil
+        @local_runtime_path = "/openui"
+      end
+
+      # Set the preferred host stream transport.
+      #
+      # @param value [Symbol] `:turbo`, `:action_cable`, or `:none`
+      #
+      # @return [Symbol]
+      def transport=(value)
+        value = value.to_sym if value.respond_to?(:to_sym)
+        unless TRANSPORTS.include?(value)
+          raise ConfigurationError, "unsupported transport #{value.inspect}; expected one of #{TRANSPORTS.inspect}"
+        end
+
+        @transport = value
+      end
+
+      # Choose self-hosted or externally served runtime assets.
+      #
+      # @param value [Symbol] `:self_hosted` or `:external`
+      #
+      # @return [Symbol]
+      def runtime_assets=(value)
+        value = value.to_sym if value.respond_to?(:to_sym)
+        unless ASSET_STRATEGIES.include?(value)
+          raise ConfigurationError,
+                "unsupported runtime_assets #{value.inspect}; expected one of #{ASSET_STRATEGIES.inspect}"
+        end
+
+        @runtime_assets = value
+      end
+
+      # Set the store used to claim and record action idempotency keys.
+      # A shared store must implement the atomic contract described in the
+      # configuration guide.
+      #
+      # @param store [#claim, #record, nil]
+      #
+      # @return [#claim, #record]
+      def idempotency_store=(store)
+        unless store.nil? || (store.respond_to?(:claim) && store.respond_to?(:record))
+          raise ConfigurationError, "idempotency_store must respond to #claim and #record"
+        end
+
+        @idempotency_store = store
+      end
+
+      # Set the manifest path and clear the cached manifest.
+      #
+      # @param path [String, Pathname, nil]
+      #
+      # @return [String, Pathname, nil]
+      def library_spec_path=(path)
+        @library_spec_path = path
+        reset!
+      end
+
+      # Set a callable that returns a stable actor and tenant idempotency scope.
+      #
+      # @param callable [#call, nil] receives an Actions::Invocation
+      #
+      # @return [#call, nil]
+      def idempotency_scope=(callable)
+        unless callable.nil? || callable.respond_to?(:call)
+          raise ConfigurationError, "idempotency_scope must respond to #call"
+        end
+
+        @idempotency_scope = callable
+      end
+
+      # Set the global authorizer used when an action has no local authorizer.
+      #
+      # @param callable [#call, nil] receives an Actions::Invocation
+      #
+      # @return [#call, nil]
+      def authorize_action=(callable)
+        unless callable.nil? || callable.respond_to?(:call)
+          raise ConfigurationError, "authorize_action must respond to #call"
+        end
+
+        @authorize_action = callable
+      end
+
+      # Set the resolver that loads a surface inside the actor's permitted scope.
+      #
+      # @param callable [#call, nil] receives surface_id, actor, and context
+      #
+      # @return [#call, nil]
+      def surface_resolver=(callable)
+        unless callable.nil? || callable.respond_to?(:call)
+          raise ConfigurationError, "surface_resolver must respond to #call"
+        end
+
+        @surface_resolver = callable
+      end
+
+      # Set the callable that resolves the current actor from the engine controller.
+      #
+      # @param callable [#call, nil] receives the engine controller
+      #
+      # @return [#call, nil]
+      def actor_resolver=(callable)
+        unless callable.nil? || callable.respond_to?(:call)
+          raise ConfigurationError, "actor_resolver must respond to #call"
+        end
+
+        @actor_resolver = callable
+      end
+
+      # Return the configured store, creating a process-local memory store by default.
+      #
+      # @return [#claim, #record]
+      def idempotency_store
+        @idempotency_store ||= Actions::Idempotency::MemoryStore.new
+      end
+
+      # The registry of callable actions. Lazily created so require order does
+      # not matter and host apps can replace it if they wish.
+      #
+      # @return [Actions::Registry]
+      def action_registry
+        @action_registry ||= Actions::Registry.new
+      end
+
+      # Fingerprint of the pinned library manifest, or nil when unconfigured.
+      #
+      # @return [String, nil]
+      def library_fingerprint
+        library_manifest&.fingerprint
+      end
+
+      # Memoized manifest for the configured `library_spec_path`.
+      #
+      # @return [LibraryManifest, nil]
+      def library_manifest
+        return @library_manifest if defined?(@library_manifest) && @library_manifest
+
+        path = library_spec_path
+        return nil if path.nil?
+
+        @library_manifest = LibraryManifest.load(path)
+      end
+
+      # Drop memoized derived state (used after config changes and in tests).
+      # The action registry and idempotency store are runtime state and are
+      # preserved so re-configuring does not silently unregister actions.
+      #
+      # @return [self]
+      def reset!
+        remove_instance_variable(:@library_manifest) if defined?(@library_manifest)
+        self
+      end
+
+      # Explicit host readiness check. Not run during boot: the generator and
+      # runtime-fetch task must work before library files have been created.
+      #
+      # @return [true]
+      #
+      # @raise [ConfigurationError, ManifestError] when required settings or files are invalid
+      def validate!
+        raise ConfigurationError, "library_spec_path is not configured" if library_spec_path.nil?
+
+        if runtime_assets == :external && (runtime_url.nil? || runtime_url.empty?)
+          raise ConfigurationError, "runtime_assets :external requires an explicit, version-pinned runtime_url"
+        end
+
+        unless pending_byte_limit.is_a?(Integer) && stream_byte_limit.is_a?(Integer) &&
+            pending_byte_limit > 0 && stream_byte_limit > 0
+          raise ConfigurationError, "stream byte limits must be positive"
+        end
+
+        if pending_byte_limit > stream_byte_limit
+          raise ConfigurationError, "pending_byte_limit must not exceed stream_byte_limit"
+        end
+
+        unless idempotency_ttl.is_a?(Numeric) && idempotency_ttl.finite? && idempotency_ttl > 0
+          raise ConfigurationError, "idempotency_ttl must be positive"
+        end
+
+        reset!
+        library_manifest
+        PromptBuilder.load(self) if prompt_path
+        true
+      end
+    end
+
+    class << self
+      # Return the process-wide OpenUI Rails configuration.
+      #
+      # @return [Configuration]
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configure the process-wide integration and clear derived manifest state.
+      #
+      # @yieldparam config [Configuration]
+      #
+      # @return [Configuration]
+      def configure
+        yield configuration
+        configuration.reset!
+        configuration
+      end
+
+      # Discard the current configuration object. Primarily useful in tests.
+      #
+      # @return [nil]
+      def reset_configuration!
+        @configuration = nil
+      end
+
+      # Shorthand for the action registry.
+      #
+      # @return [Actions::Registry]
+      def actions
+        configuration.action_registry
+      end
+    end
+  end
+end

data/lib/openui/rails/engine.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_support/inflector"
+require "rails/engine"
+
+# Register the acronym before the engine class is defined: `isolate_namespace`
+# computes the routing module scope with `underscore` at class-definition time,
+# so it must already know that `OpenUI` is `openui` (not `open_ui`).
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.acronym "OpenUI"
+end
+
+module OpenUI
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace OpenUI::Rails
+
+      # Inside `module OpenUI`, a bare `Rails` resolves to `OpenUI::Rails`, so
+      # every reference to the framework must be written `::Rails`.
+      #
+      # Zeitwerk would infer `Openui` from the `openui` path segment; the
+      # acronym must be declared explicitly before the main autoloader is set
+      # up, otherwise constants such as `OpenUI::Rails::ActionsController`
+      # cannot be resolved.
+      initializer "openui_rails.inflections", before: :setup_main_autoloader do
+        ::Rails.autoloaders.main.inflector.inflect("openui" => "OpenUI")
+      end
+
+      # Expose the surface helper to every host view.
+      initializer "openui_rails.view_helper" do
+        ActiveSupport.on_load(:action_view) do
+          include OpenUI::Rails::ViewHelper
+        end
+      end
+
+      # Make the Stimulus controller reachable by Propshaft/Sprockets/importmap.
+      initializer "openui_rails.assets" do |app|
+        next unless app.config.respond_to?(:assets)
+
+        assets = app.config.assets
+        assets.paths << root.join("app/javascript") if assets.respond_to?(:paths)
+      end
+    end
+  end
+end

data/lib/openui/rails/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    # Base class for every error raised by openui-rails. Rescuing
+    # `OpenUI::Rails::Error` rescues the whole taxonomy.
+    class Error < StandardError; end
+
+    # Raised when configuration is invalid or an unsupported option is set.
+    class ConfigurationError < Error; end
+
+    # Raised when a library manifest cannot be loaded, parsed or validated.
+    class ManifestError < Error; end
+
+    # Raised when a browser-rendered response targets a library version that
+    # does not match the pinned library fingerprint.
+    class LibraryVersionError < Error; end
+
+    # Raised when an action name is not present in the registry.
+    class UnknownActionError < Error; end
+
+    # Raised when the host authorizer denies an action.
+    class UnauthorizedActionError < Error; end
+
+    # Raised when an action payload fails schema/presence validation.
+    class InvalidActionError < Error; end
+
+    # Raised when a submitted action targets a surface revision that is no
+    # longer current.
+    class StaleSurfaceError < Error; end
+
+    # Raised when an action submission replays a known idempotency key.
+    class ReplayError < Error; end
+
+    # Raised for malformed or unsafe stream payloads.
+    class StreamError < Error; end
+
+    # Raised when a caller requests an unsupported protocol/library version.
+    class UnsupportedVersionError < Error; end
+  end
+end

data/lib/openui/rails/json_value.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    # Internal canonical JSON copy. Never freezes caller-owned values or lets
+    # mutable input change a fingerprint after validation.
+    module JsonValue # :nodoc:
+      def self.copy(value, depth = 0)
+        raise ArgumentError, "JSON nesting exceeds 100 levels" if depth > 100
+
+        case value
+        when Hash
+          pairs = value.map do |key, entry|
+            raise ArgumentError, "JSON object keys must be strings or symbols" unless key.is_a?(String) || key.is_a?(Symbol)
+
+            [ key.to_s, entry ]
+          end
+          raise ArgumentError, "duplicate JSON object keys" unless pairs.map(&:first).uniq.size == pairs.size
+
+          pairs.sort_by(&:first).to_h.transform_values { |entry| copy(entry, depth + 1) }.freeze
+        when Array then value.map { |entry| copy(entry, depth + 1) }.freeze
+        when String then value.dup.freeze
+        when Integer, TrueClass, FalseClass, NilClass then value
+        when Float
+          raise ArgumentError, "JSON numbers must be finite" unless value.finite?
+
+          value
+        else raise ArgumentError, "unsupported JSON value #{value.class}"
+        end
+      end
+    end
+  end
+end