openui-rails 0.1.0

data/lib/openui/rails/stream/accumulator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Stream
+      # Client-side (Ruby) sequence accumulator mirroring what the browser must
+      # do: apply ordered deltas, ignore duplicates, and treat a missing
+      # sequence as "fetch the authoritative snapshot" rather than executing a
+      # malformed partial. Used by server tests and by hosts that consume their
+      # own stream.
+      class Accumulator
+        attr_reader :message_id, :source
+
+        def initialize(message_id:)
+          @message_id = message_id
+          @source = +""
+          @next_sequence = 0
+          @completed = false
+          @error = nil
+          @needs_snapshot = false
+        end
+
+        # @return [Symbol] one of :applied, :duplicate, :snapshot, :completed,
+        #   :error, :ignored
+        def apply(envelope)
+          return :ignored unless envelope.message_id == message_id
+          unless envelope.snapshot?
+            return :duplicate if envelope.sequence < @next_sequence
+            return :ignored if @completed || error?
+            return :gap if @needs_snapshot
+            if envelope.sequence > @next_sequence
+              @needs_snapshot = true
+              return :gap
+            end
+          end
+
+          case envelope.type
+          when Envelope::DELTA then apply_delta(envelope)
+          when Envelope::SNAPSHOT then apply_snapshot(envelope)
+          when Envelope::COMPLETED then apply_completed(envelope)
+          when Envelope::ERROR then apply_error(envelope)
+          else :ignored
+          end
+        end
+
+        def next_sequence = @next_sequence
+        def completed? = @completed
+        def error? = !@error.nil?
+        def needs_snapshot? = @needs_snapshot
+        def error = @error
+
+        private
+
+        def apply_delta(envelope)
+          @source << envelope.delta
+          @next_sequence += 1
+          :applied
+        end
+
+        def apply_snapshot(envelope)
+          minimum = @needs_snapshot ? @next_sequence - 1 : @next_sequence
+          return :duplicate if envelope.sequence < minimum
+
+          @source = +envelope.response.dup
+          @next_sequence = envelope.sequence + 1
+          @needs_snapshot = false
+          @completed = !envelope.streaming?
+          @error = nil
+          :snapshot
+        end
+
+        def apply_completed(envelope)
+          @completed = true
+          @next_sequence = [ @next_sequence, envelope.sequence + 1 ].max
+          :completed
+        end
+
+        def apply_error(envelope)
+          @error = envelope
+          @next_sequence += 1
+          :error
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/stream/bridge.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Stream
+      # Turns model output into an ordered sequence of {Envelope}s, coalescing
+      # small chunks up to `pending_byte_limit` and enforcing `stream_byte_limit`.
+      # Transport-agnostic: a caller broadcasts the yielded envelopes over Turbo
+      # Streams or Action Cable.
+      #
+      # Pull sources (an Enumerable of chunks) go through {#each_envelope};
+      # push sources (a streaming callback) use a {Writer} directly.
+      class Bridge
+        attr_reader :message_id, :library_version
+
+        # Create a bridge with message metadata and configured byte limits.
+        #
+        # @param message_id [String] stable id shared by all frames in the stream
+        #
+        # @param library_version [String, nil] manifest fingerprint attached to frames
+        #
+        # @param configuration [Configuration]
+        #
+        # @return [Bridge]
+        def initialize(message_id:, library_version: nil, configuration: OpenUI::Rails.configuration)
+          @message_id = message_id
+          @library_version = library_version
+          @configuration = configuration
+        end
+
+        # @param source [#each] yields String chunks
+        #
+        # @return [Enumerator<Envelope>]
+        def envelopes(source)
+          to_enum(:each_envelope, source)
+        end
+
+        # Yield ordered envelopes for every chunk from a pull-based source.
+        # Provider errors become a structured error envelope. Exceptions raised
+        # by the consumer block propagate to the caller.
+        #
+        # @param source [#each] yields String chunks
+        # @yieldparam envelope [Envelope]
+        def each_envelope(source)
+          writer = writer()
+          source = source.to_enum
+          loop do
+            begin
+              chunk = source.next
+              envelopes = writer.push(chunk)
+            rescue StopIteration
+              break
+            rescue StandardError => error
+              envelope = writer.error_for(error)
+              yield envelope if envelope
+              return
+            end
+            # Transport/consumer failures are not provider failures. Let the
+            # host retry or report them without recursively broadcasting errors.
+            envelopes.each { |envelope| yield envelope }
+          end
+          writer.finish.each { |envelope| yield envelope }
+        end
+
+        # Build a stateful writer for push-based providers.
+        #
+        # @return [Writer]
+        def writer
+          Writer.new(
+            message_id: message_id,
+            library_version: library_version,
+            pending_byte_limit: @configuration.pending_byte_limit,
+            stream_byte_limit: @configuration.stream_byte_limit,
+            on_error: @configuration.on_error
+          )
+        end
+
+        # Accumulates pushed chunks and emits envelopes. Stateful across calls.
+        class Writer
+          attr_reader :sequence
+
+          # Create a writer that buffers chunks up to the pending byte limit.
+          #
+          # @param message_id [String]
+          #
+          # @param library_version [String, nil]
+          #
+          # @param pending_byte_limit [Integer]
+          #
+          # @param stream_byte_limit [Integer]
+          #
+          # @param on_error [#call, nil]
+          #
+          # @return [Writer]
+          def initialize(message_id:, library_version: nil, pending_byte_limit:, stream_byte_limit:, on_error: nil)
+            Envelope.completed(message_id: message_id, sequence: 0, library_version: library_version)
+            unless pending_byte_limit.is_a?(Integer) && stream_byte_limit.is_a?(Integer) &&
+                pending_byte_limit > 0 && stream_byte_limit >= pending_byte_limit
+              raise ConfigurationError, "stream limits must be positive integers with pending <= total"
+            end
+            @message_id = message_id
+            @library_version = library_version
+            @pending_byte_limit = pending_byte_limit
+            @stream_byte_limit = stream_byte_limit
+            @on_error = on_error
+            @sequence = 0
+            @total_bytes = 0
+            @pending = +""
+            @terminated = false
+          end
+
+          # Append a chunk and return a delta once the pending threshold is reached.
+          # A chunk that exceeds the total stream limit returns an error envelope.
+          #
+          # @param chunk [String, nil]
+          #
+          # @return [Array<Envelope>] zero or more envelopes to emit
+          def push(chunk)
+            return [] if @terminated || chunk.nil?
+            raise StreamError, "stream chunks must be strings" unless chunk.is_a?(String)
+            return [] if chunk.empty?
+
+            @total_bytes += chunk.bytesize
+            if @total_bytes > @stream_byte_limit
+              return [ error_envelope("stream_too_large", "stream exceeded #{@stream_byte_limit} bytes") ]
+            end
+
+            @pending << chunk
+            return [] if @pending.bytesize < @pending_byte_limit
+
+            [ flush_delta ]
+          end
+
+          # Flush pending text and emit the completion envelope once.
+          #
+          # @return [Array<Envelope>] the final delta, if any, and completion
+          def finish
+            return [] if @terminated
+
+            envelopes = []
+            envelopes << flush_delta unless @pending.empty?
+            envelopes << Envelope.completed(
+              message_id: @message_id, sequence: @sequence, library_version: @library_version
+            )
+            @sequence += 1
+            @terminated = true
+            envelopes
+          end
+
+          # Structured, PII-free error envelope for a provider/consumer failure.
+          #
+          # @param error [Exception]
+          #
+          # @param code [String] a supported stream error code
+          #
+          # @return [Envelope, nil] nil when the writer already terminated
+          def error_for(error, code: "stream_failed")
+            return nil if @terminated
+
+            @on_error&.call(error, message_id: @message_id)
+
+            message = "stream failed (#{error.class})"
+            message = "stream cancelled" if code == "stream_cancelled"
+            error_envelope(code, message)
+          end
+
+          private
+
+          def flush_delta
+            envelope = Envelope.delta(
+              message_id: @message_id, sequence: @sequence, delta: @pending.dup,
+              library_version: @library_version, streaming: true
+            )
+            @sequence += 1
+            @pending = +""
+            envelope
+          end
+
+          def error_envelope(code, message)
+            envelope = Envelope.error(
+              message_id: @message_id, sequence: @sequence, library_version: @library_version,
+              code: code, message: message
+            )
+            @sequence += 1
+            @terminated = true
+            @pending.clear
+            envelope
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/stream/broadcaster.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Stream
+      # Binds the ordered {Bridge} to a transport and broadcasts every envelope
+      # as it is produced.
+      #
+      # The transport is a seam: any object that responds to
+      # `#broadcast(envelope)` works, and {Transports} ships wrappers for Action
+      # Cable, Turbo Streams and an in-memory collector. Delivery is best effort:
+      # Action Cable and Turbo Streams do not promise order or delivery. The
+      # client applies sequence numbers and recovers from an
+      # authoritative snapshot on a gap (see the Stimulus controller).
+      #
+      #   broadcaster = Broadcaster.new(
+      #     transport: Transports::ActionCable.new("openui:surface:42"),
+      #     message_id: "msg-1",
+      #     library_version: OpenUI::Rails.configuration.library_fingerprint
+      #   )
+      #   chat.complete { |chunk| broadcaster.push(chunk.content) }
+      #   broadcaster.finish
+      class Broadcaster
+        attr_reader :transport, :message_id, :library_version
+
+        # Broadcast every envelope produced by an enumerable source of chunks.
+        #
+        # @param source [#each] yields String chunks
+        # @param options [Hash] arguments forwarded to the constructor
+        #
+        # @return [Broadcaster]
+        def self.broadcast(source, **options)
+          broadcaster = new(**options)
+          source.each { |chunk| broadcaster.push(chunk) }
+          broadcaster.finish
+        end
+
+        # Bind a bridge writer to a transport that responds to `broadcast`.
+        #
+        # @param transport [#broadcast]
+        #
+        # @param message_id [String]
+        #
+        # @param library_version [String, nil]
+        #
+        # @param configuration [Configuration]
+        #
+        # @return [Broadcaster]
+        def initialize(transport:, message_id:, library_version: nil, configuration: OpenUI::Rails.configuration)
+          raise ConfigurationError, "a transport is required" if transport.nil?
+          unless transport.respond_to?(:broadcast)
+            raise ConfigurationError, "transport must respond to #broadcast"
+          end
+
+          @transport = transport
+          @message_id = message_id
+          @library_version = library_version
+          @configuration = configuration
+          @writer = Bridge.new(
+            message_id: message_id,
+            library_version: library_version,
+            configuration: configuration
+          ).writer
+        end
+
+        # Push a chunk; broadcasts any envelopes the writer flushes.
+        #
+        # @param chunk [String, nil]
+        #
+        # @return [self]
+        def push(chunk)
+          @writer.push(chunk).each { |envelope| @transport.broadcast(envelope) }
+          self
+        end
+
+        # Broadcast the final delta (if any) and the completion marker.
+        #
+        # @return [self]
+        def finish
+          @writer.finish.each { |envelope| @transport.broadcast(envelope) }
+          self
+        end
+
+        # Broadcast a structured, PII-free error envelope and stop.
+        #
+        # @param error [Exception]
+        #
+        # @param code [String]
+        #
+        # @return [self]
+        def fail(error, code: "stream_failed")
+          envelope = @writer.error_for(error, code: code)
+          @transport.broadcast(envelope) if envelope
+          self
+        end
+
+        # The next sequence number the writer will assign.
+        #
+        def sequence = @writer.sequence
+
+        # The underlying writer, for callers that need finer control.
+        attr_reader :writer
+      end
+    end
+  end
+end

data/lib/openui/rails/stream/envelope.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenUI
+  module Rails
+    module Stream
+      # A single, gem-defined stream frame. This is *not* an OpenUI protocol:
+      # it is the wire shape the Gem normalizes chunks into over Turbo Streams
+      # or Action Cable. Ordering is per message and starts at sequence 0.
+      #
+      # Payloads never carry tools, credentials or server secrets.
+      class Envelope
+        DELTA = "openui.delta"
+        SNAPSHOT = "openui.snapshot"
+        COMPLETED = "openui.completed"
+        ERROR = "openui.error"
+        TYPES = [ DELTA, SNAPSHOT, COMPLETED, ERROR ].freeze
+
+        MAX_MESSAGE_ID_BYTES = 200
+        ERROR_CODES = %w[
+          stream_too_large
+          stream_failed
+          stream_cancelled
+          provider_rejected
+          library_version_mismatch
+          renderer_error
+        ].freeze
+
+        attr_reader :message_id, :sequence, :type, :library_version, :data
+
+        def initialize(type:, message_id:, sequence:, library_version: nil, data: {})
+          @type = validate_type(type).dup.freeze
+          @message_id = validate_message_id(message_id).dup.freeze
+          @sequence = validate_sequence(sequence)
+          unless library_version.nil? || library_version.is_a?(String)
+            raise StreamError, "library_version must be a String"
+          end
+          @library_version = library_version&.dup&.freeze
+          unless data.is_a?(Hash) && (data.keys.map(&:to_s) & %w[type message_id sequence library_version]).empty?
+            raise StreamError, "envelope data cannot override routing metadata"
+          end
+          @data = JsonValue.copy(data)
+          validate_data!
+          freeze
+        end
+
+        class << self
+          def delta(message_id:, sequence:, delta:, library_version: nil, streaming: true)
+            validate_string!(delta, "delta")
+            new(
+              type: DELTA, message_id: message_id, sequence: sequence, library_version: library_version,
+              data: { "delta" => delta, "streaming" => streaming }
+            )
+          end
+
+          def snapshot(message_id:, sequence:, response:, library_version: nil, streaming: false)
+            validate_string!(response, "response")
+            new(
+              type: SNAPSHOT, message_id: message_id, sequence: sequence, library_version: library_version,
+              data: { "response" => response, "streaming" => streaming }
+            )
+          end
+
+          def completed(message_id:, sequence:, library_version: nil)
+            new(
+              type: COMPLETED, message_id: message_id, sequence: sequence, library_version: library_version,
+              data: { "streaming" => false }
+            )
+          end
+
+          def error(message_id:, sequence:, code:, message: nil, library_version: nil)
+            code = code.to_s
+            unless ERROR_CODES.include?(code)
+              raise StreamError, "unknown error code #{code.inspect}; expected one of #{ERROR_CODES.inspect}"
+            end
+
+            new(
+              type: ERROR, message_id: message_id, sequence: sequence, library_version: library_version,
+              data: { "code" => code, "message" => message, "streaming" => false }.compact
+            )
+          end
+
+          def validate_string!(value, name)
+            return if value.is_a?(String)
+
+            raise StreamError, "#{name} must be a String"
+          end
+        end
+
+        def delta = data["delta"]
+        def response = data["response"]
+        def code = data["code"]
+        def streaming? = data["streaming"] == true
+        def delta? = type == DELTA
+        def snapshot? = type == SNAPSHOT
+        def completed? = type == COMPLETED
+        def error? = type == ERROR
+
+        def to_h
+          hash = { "message_id" => message_id, "sequence" => sequence, "type" => type }
+          hash["library_version"] = library_version if library_version
+          hash.merge!(data)
+          hash
+        end
+
+        def to_json(*) = JSON.generate(to_h)
+
+        def ==(other)
+          other.is_a?(Envelope) && other.to_h == to_h
+        end
+        alias eql? ==
+
+        def hash = to_h.hash
+
+        private
+
+        def validate_data!
+          case type
+          when DELTA then self.class.validate_string!(delta, "delta")
+          when SNAPSHOT then self.class.validate_string!(response, "response")
+          when ERROR
+            raise StreamError, "unknown error code #{code.inspect}" unless ERROR_CODES.include?(code)
+          end
+          if data.key?("streaming") && ![ true, false ].include?(data["streaming"])
+            raise StreamError, "streaming must be boolean"
+          end
+        end
+
+        def validate_type(type)
+          type = type.to_s
+          raise StreamError, "unknown envelope type #{type.inspect}" unless TYPES.include?(type)
+
+          type
+        end
+
+        def validate_message_id(message_id)
+          unless message_id.is_a?(String) && !message_id.empty?
+            raise StreamError, "message_id must be a non-empty String"
+          end
+
+          if message_id.bytesize > MAX_MESSAGE_ID_BYTES
+            raise StreamError, "message_id exceeds #{MAX_MESSAGE_ID_BYTES} bytes"
+          end
+
+          message_id
+        end
+
+        def validate_sequence(sequence)
+          unless sequence.is_a?(Integer) && sequence >= 0
+            raise StreamError, "sequence must be a non-negative Integer"
+          end
+
+          sequence
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/stream/transports/action_cable.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Stream
+      module Transports
+        # Broadcasts envelope hashes over Action Cable.
+        #
+        # The stream name is supplied by the host (the Gem does not invent a
+        # tenant-scoping scheme). Pair it with a channel that dispatches each
+        # received payload as an `openui:envelope` event on the page. See the
+        # "Transports" section of the README. Authorization for the subscription
+        # stays in the host's channel.
+        #
+        # `cable:` is the Action Cable server (or a test double that responds to
+        # `#broadcast`), injectable so this can be exercised without a running
+        # Action Cable server.
+        class ActionCable
+          attr_reader :stream_name
+
+          def initialize(stream_name, cable: nil)
+            if stream_name.nil? || stream_name.to_s.empty?
+              raise ConfigurationError, "a stream_name is required"
+            end
+
+            @stream_name = stream_name.to_s
+            @cable = cable
+          end
+
+          # @return [Object] the result of the underlying broadcast
+          def broadcast(envelope)
+            server.broadcast(stream_name, envelope.to_h)
+          end
+
+          private
+
+          def server
+            return @cable if @cable
+
+            unless defined?(::ActionCable) && ::ActionCable.respond_to?(:server)
+              raise StreamError, "Action Cable is not loaded; add actioncable or use another transport"
+            end
+
+            ::ActionCable.server
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/stream/transports/memory.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Stream
+      module Transports
+        # In-memory transport for tests and examples. It keeps every broadcast
+        # envelope, so a caller can assert on the exact ordered sequence.
+        class Memory
+          attr_reader :envelopes
+
+          def initialize
+            @envelopes = []
+          end
+
+          def broadcast(envelope)
+            @envelopes << envelope
+            envelope
+          end
+
+          def to_a = @envelopes.dup
+
+          def clear
+            @envelopes.clear
+            self
+          end
+
+          def empty? = @envelopes.empty?
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/stream/transports/turbo_streams.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+
+module OpenUI
+  module Rails
+    module Stream
+      module Transports
+        # Broadcasts each envelope as a Turbo Stream that appends an
+        # `openui-envelope` element to a target already in the DOM.
+        #
+        # The small `openui-envelope` Stimulus controller turns that element
+        # into an `openui:envelope` event and removes itself, so no inline
+        # script is used and no Content Security Policy relaxation is needed.
+        #
+        # turbo-rails is looked up lazily and may be injected via `turbo:`; the
+        # Gem never hard-depends on it.
+        class TurboStreams
+          ELEMENT_TAG = "div"
+
+          attr_reader :stream, :target
+
+          def initialize(stream, target:, turbo: nil)
+            raise ConfigurationError, "a stream is required" if stream.nil?
+            if target.nil? || target.to_s.empty?
+              raise ConfigurationError, "a target is required"
+            end
+
+            @stream = stream
+            @target = target.to_s
+            @turbo = turbo
+          end
+
+          def broadcast(envelope)
+            channel.broadcast_append_to(stream, target: target, content: element(envelope))
+          end
+
+          # The HTML fragment a Turbo Stream appends. Kept public so tests can
+          # assert on escaping without a Turbo dependency.
+          def element(envelope)
+            payload = ERB::Util.html_escape(JSON.generate(envelope.to_h))
+            %(<#{ELEMENT_TAG} data-controller="openui-envelope" data-openui-envelope-payload="#{payload}"></#{ELEMENT_TAG}>)
+          end
+
+          private
+
+          def channel
+            return @turbo if @turbo
+
+            unless defined?(::Turbo::StreamsChannel)
+              raise StreamError, "Turbo Streams is not loaded; add turbo-rails or use another transport"
+            end
+
+            ::Turbo::StreamsChannel
+          end
+        end
+      end
+    end
+  end
+end