maquina_stream 0.1.0

data/lib/generators/maquina_stream/streamable/streamable_generator.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+require "rails/generators/migration"
+require "maquina_stream/streamable"
+
+module MaquinaStream
+  module Generators
+    # Makes one model streamable: the migration carrying the columns the
+    # contract requires, and the `include` plus macro in the model.
+    #
+    # ```sh
+    # bin/rails generate maquina_stream:streamable Message
+    # ```
+    #
+    # Per model, because a host may have several — an assistant message and a
+    # tool call are two streams, not one.
+    #
+    # The columns come from MaquinaStream::Streamable itself rather than from a
+    # list copied out of the documentation, so a contract that gains a column
+    # gains it here too. A column the contract requires and this generator has
+    # no definition for raises rather than being quietly left out.
+    class StreamableGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds the maquina_stream contract columns and the model macro to one model."
+
+      class_option :buffer, type: :string, default: "content",
+        desc: "The column holding the raw markdown"
+      class_option :stream_for, type: :string, default: "record",
+        desc: "Ruby for the Turbo broadcast target, written against `record`"
+
+      INITIALIZER = "config/initializers/maquina_stream.rb"
+
+      # The stub the install generator writes, and what replaces it.
+      FIND_STREAM_STUB = /^(\s*)c\.find_stream = ->\(sid\) \{ raise NotImplementedError.*\}$/
+
+      # How to create each column the contract asks for. Keyed by the column
+      # name Streamable declares, plus `:buffer` for the one the host names.
+      # Streamable::Generated::REQUIRED_COLUMNS is the source of truth for
+      # *which* columns; this is the source of truth for their shape.
+      COLUMN_DEFINITIONS = {
+        :buffer => {type: :text, default: "", null: false},
+        Streamable::SEQUENCE_COLUMN => {type: :integer, default: 0, null: false},
+        Streamable::STATUS_COLUMN => {type: :string, default: Streamable::OPEN_STATUS, null: false}
+      }.freeze
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Migration.next_migration_number(current_migration_number(dirname) + 1)
+      end
+
+      def create_migration_file
+        return say_status(:skip, "db/migrate: #{table_name} already has every contract column", :yellow) if missing_columns.empty?
+        return say_status(:skip, "db/migrate: #{migration_name} already generated", :yellow) if migration_generated?
+
+        migration_template "migration.rb.tt", "db/migrate/#{migration_name}.rb"
+      end
+
+      def create_or_update_model
+        if File.exist?(File.join(destination_root, model_path))
+          return say_status(:skip, "#{model_path}: already streamable", :yellow) if model_source.include?("MaquinaStream::Streamable")
+
+          inject_into_class model_path, class_name, model_macro
+        else
+          template "model.rb.tt", model_path
+        end
+      end
+
+      # The install generator leaves `find_stream` raising. Now there is a
+      # model to point it at — but only the generated stub is ever replaced, so
+      # a host that already wrote its own is never clobbered.
+      def fill_in_find_stream
+        return say_status(:skip, "#{INITIALIZER}: not found — set c.find_stream yourself", :yellow) unless File.exist?(File.join(destination_root, INITIALIZER))
+
+        source = File.read(File.join(destination_root, INITIALIZER))
+        unless source.match?(FIND_STREAM_STUB)
+          return say_status(:skip, "#{INITIALIZER}: find_stream is not the generated stub", :yellow)
+        end
+
+        gsub_file INITIALIZER, FIND_STREAM_STUB, "\\1c.find_stream = ->(sid) { #{class_name}.find_by(id: sid) }"
+      end
+
+      def report_what_is_left
+        say ""
+        say "#{class_name} streams. What is still yours:", :green
+        say ""
+        say "  - `stream_for:` in #{model_path} — the Turbo broadcast target."
+        say "    Who may subscribe to a stream is your question, not the engine's."
+        say "  - `c.authorize` in #{INITIALIZER}, which still denies everything."
+        say ""
+        say "  Assert the contract in your own suite, so a missing column fails at"
+        say "  test time rather than mid-stream:"
+        say ""
+        say "      assert_empty #{class_name}.maquina_stream_contract_gaps"
+        say ""
+      end
+
+      private
+        # Every column the contract needs, resolved against the buffer name the
+        # host chose. Derived from Streamable, never from a copied list.
+        def contract_columns
+          Streamable::Generated::REQUIRED_COLUMNS.values.uniq.map do |column|
+            definition = COLUMN_DEFINITIONS.fetch(column) do
+              raise Rails::Generators::Error, <<~MESSAGE
+                MaquinaStream::Streamable requires a `#{column}` column and this
+                generator has no definition for it. The contract moved; teach
+                COLUMN_DEFINITIONS the new column rather than leaving hosts to
+                find out mid-stream.
+              MESSAGE
+            end
+
+            definition.merge(name: (column == :buffer) ? buffer_column : column)
+          end
+        end
+
+        def missing_columns
+          contract_columns.reject { |column| existing_columns.include?(column[:name].to_s) }
+        end
+
+        def buffer_column
+          options[:buffer].to_sym
+        end
+
+        def create_table?
+          table_definition.nil?
+        end
+
+        def migration_name
+          create_table? ? "create_#{table_name}" : "add_maquina_stream_to_#{table_name}"
+        end
+
+        def migration_generated?
+          Dir.glob(File.join(destination_root, "db/migrate/*_#{migration_name}.rb")).any?
+        end
+
+        def migration_version
+          ActiveRecord::Migration.current_version.to_s
+        end
+
+        # What db/schema.rb says this table already has. A host with no schema
+        # yet gets a create_table; one whose table exists gets add_column for
+        # the columns it is actually missing.
+        def existing_columns
+          @existing_columns ||= table_definition.to_s.scan(/t\.\w+\s+[:"']([a-z0-9_]+)/).flatten
+        end
+
+        def table_definition
+          return @table_definition if defined?(@table_definition)
+
+          @table_definition = schema[/create_table [:"']#{Regexp.escape(table_name)}["']?[^\n]*\n(.*?)\n\s*end/m, 1]
+        end
+
+        def schema
+          @schema ||= begin
+            path = File.join(destination_root, "db/schema.rb")
+            File.exist?(path) ? File.read(path) : ""
+          end
+        end
+
+        def model_path
+          File.join("app/models", class_path, "#{file_name}.rb")
+        end
+
+        def model_source
+          File.read(File.join(destination_root, model_path))
+        end
+
+        def model_macro
+          <<~RUBY.indent(2)
+            include MaquinaStream::Streamable
+
+            # `buffer:` names the column holding the raw markdown. `stream_for:`
+            # returns the Turbo broadcast target — the engine never guesses one,
+            # because who may subscribe to a stream is the host's question. This
+            # gives every #{singular_name} a stream of its own; a conversation-wide
+            # target is usually what you want:
+            #
+            #   stream_for: ->(record) { [:conversation, record.conversation_id, :#{table_name}] }
+            maquina_stream buffer: :#{buffer_column},
+              stream_for: ->(record) { #{options[:stream_for]} }
+          RUBY
+        end
+    end
+  end
+end

data/lib/generators/maquina_stream/streamable/templates/migration.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# The columns MaquinaStream::Streamable generates its contract methods from.
+# `<%= buffer_column %>` holds the raw markdown the model writes; the other two are the
+# contract's own, and their names come from Streamable rather than from here.
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+<% if create_table? -%>
+    create_table :<%= table_name %> do |t|
+<% missing_columns.each do |column| -%>
+      t.<%= column[:type] %> :<%= column[:name] %>, null: <%= column[:null] %>, default: <%= column[:default].inspect %>
+<% end -%>
+      t.timestamps
+    end
+<% else -%>
+<% missing_columns.each do |column| -%>
+    add_column :<%= table_name %>, :<%= column[:name] %>, :<%= column[:type] %>, null: <%= column[:null] %>, default: <%= column[:default].inspect %>
+<% end -%>
+<% end -%>
+  end
+end

data/lib/generators/maquina_stream/streamable/templates/model.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < ApplicationRecord
+<%= model_macro %>end

data/lib/maquina_stream/block.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module MaquinaStream
+  # One top-level block of a message: the slice of raw markdown it came from,
+  # the HTML it rendered to, and whether it is safe to freeze.
+  #
+  # The id is derived from the index and never from the content. Idiomorph keys
+  # on id, so a content-derived id turns every edit into a delete-and-recreate,
+  # which loses scroll position, animation state and anything the client owns.
+  #
+  # Blocks come from Document. Building one by hand is possible but rarely
+  # useful: the id and digest a repair needs are stamped on during that split.
+  # Instances are immutable — #seal returns a new Block rather than mutating.
+  class Block
+    # This block's position in the document, zero-based. The id is derived from
+    # it.
+    attr_reader :index
+
+    # The slice of raw markdown this block was rendered from.
+    attr_reader :markdown
+
+    # The rendered HTML for this block alone, including its own element and the
+    # `id`, `data-ms-block` and `data-ms-block-digest` attributes.
+    attr_reader :html
+
+    # The Range of 1-based source lines this block covers. Coverage has gaps —
+    # an HTML block reports no source position at all — so a block with no
+    # range of its own inherits the lines between its neighbours.
+    attr_reader :line_range
+
+    # The stream id this block belongs to, or nil for an anonymous render.
+    attr_reader :sid
+
+    # Builds a block. Document does this; a host normally reads blocks rather
+    # than constructing them.
+    def initialize(index:, markdown:, html:, line_range:, sid: nil, sealed: false, digest: nil)
+      @index = index
+      @markdown = markdown
+      @html = html
+      @line_range = line_range
+      @sid = sid
+      @sealed = sealed
+      @digest = digest
+    end
+
+    # The DOM id, `ms-<sid>-b<index>`. Index-derived, never content-derived:
+    # idiomorph keys on it.
+    def id
+      sid ? "ms-#{sid}-b#{index}" : "ms-b#{index}"
+    end
+
+    # Whether this block is frozen — far enough behind the tail that nothing
+    # can reinterpret it, and therefore never re-broadcast.
+    def sealed? = @sealed
+
+    # Whether this block can still change, and can therefore still be patched.
+    def open? = !sealed?
+
+    # Digest of the block's rendered CONTENT, not of the source and not of the
+    # whole element.
+    #
+    # The manifest compares what the browser actually has, so two different
+    # sources that render alike need no repair between them. Element-level
+    # attributes are excluded on purpose: a block gains `data-ms-block-state`
+    # when it seals and loses `data-ms-caret` when the tail moves past it, and
+    # neither changes what the block says. Digesting them would make every block
+    # in every message fetch itself once, for nothing.
+    def digest
+      @digest ||= Digest::SHA256.hexdigest(html.to_s)[0, 16]
+    end
+
+    # A copy of this block, sealed. Returns a new Block; the receiver is
+    # unchanged.
+    def seal
+      self.class.new(
+        index: index, markdown: markdown, html: html,
+        line_range: line_range, sid: sid, sealed: true, digest: digest
+      )
+    end
+
+    # `[id, digest]` — one row of a Manifest, and the unit the client diffs
+    # its own DOM against.
+    def to_manifest_entry = [id, digest]
+
+    # Two blocks are equal when they hold the same index and the same HTML.
+    # Sealing is deliberately not part of it: a block that sealed between two
+    # frames is the same block, and the seal is a decision about it rather than
+    # a property of it.
+    def ==(other)
+      other.is_a?(Block) && other.index == index && other.html == html
+    end
+    alias_method :eql?, :==
+
+    # Hashed on the same two fields #== compares.
+    def hash = [index, html].hash
+  end
+end

data/lib/maquina_stream/broadcaster.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module MaquinaStream
+  # Turns a growing buffer into a stream of small patches.
+  #
+  # ```ruby
+  # broadcaster = MaquinaStream::Broadcaster.new(message)
+  # model.stream { |token| broadcaster.append(token) }
+  # broadcaster.seal!                 # final frame, always
+  # ```
+  #
+  # It remembers what the browser already has — block id to digest — and sends
+  # only what moved. A block that has not changed is never re-sent, which is the
+  # difference between bandwidth tracking drift and bandwidth tracking message
+  # length.
+  #
+  # Transport is a seam. It defaults to Turbo Streams over whatever cable the
+  # host configured, and a test can hand it a recorder instead; that recorder is
+  # how the bandwidth budget is asserted rather than estimated.
+  #
+  # One broadcaster per stream, held for the life of that stream: what the
+  # browser already has lives in the instance, so a fresh broadcaster mid-stream
+  # re-sends every block. It is not thread-safe; drive one stream from one
+  # place.
+  #
+  # **Deltas do not converge on their own, and are not meant to.** Only the open
+  # tail is patched; a block that changes after it stops being the tail is fixed
+  # by the repair path. Correctness lives there.
+  class Broadcaster
+    # The host record being streamed. Must satisfy MaquinaStream::Streamable.
+    attr_reader :record
+
+    # The Configuration this broadcaster reads — `frame_budget_ms` and
+    # `seal_lag` in particular.
+    attr_reader :config
+
+    # The object frames are emitted through. Responds to
+    # `call(record:, frame:, config:)`.
+    attr_reader :transport
+
+    # Builds a broadcaster over one record.
+    #
+    # `transport:` defaults to TurboTransport. It is a seam: anything answering
+    # `call(record:, frame:, config:)` will do, which is how the bandwidth
+    # budget is asserted against a recorder rather than estimated.
+    def initialize(record, config: MaquinaStream.config, transport: nil)
+      @record = record
+      @config = config
+      @transport = transport || TurboTransport.new
+      @known = {}
+      @tail_id = nil
+      @last_flush = nil
+    end
+
+    # Appends `text` to the record's buffer and broadcasts if the frame budget
+    # has elapsed. Returns the Frame that went out, or nil when this append was
+    # coalesced into the next one.
+    #
+    # This is the method a streaming loop calls, once per token or per chunk.
+    #
+    # Host owns persistence: it appends to its own column, and only then is
+    # there anything to broadcast.
+    def append(text, now: monotonic_ms)
+      record.maquina_stream_append(text)
+      broadcast(now: now)
+    end
+
+    # Seals the record and emits the final frame. Returns that Frame.
+    #
+    # `status:` is one of Streamable::SEAL_STATUSES. Call this exactly once,
+    # including when a stream failed: an errored message still has text worth
+    # keeping, and the client has no other way to learn the stream is over.
+    #
+    # The final frame is never coalesced and never skipped. Every intra-stream
+    # drift becomes cosmetic and self-correcting because of this one.
+    def seal!(status: :complete)
+      record.maquina_stream_seal!(status: status)
+      emit(now: monotonic_ms, final: true)
+    end
+
+    # Broadcasts a frame if the budget has elapsed, without appending
+    # anything. Returns the Frame or nil.
+    #
+    # Useful when the buffer moved by some other route — a host that writes to
+    # the column itself and wants the browser told about it.
+    #
+    # Coalescing happens BEFORE the render, not after it. Building a frame means
+    # rendering the whole buffer, so doing that per token and then throwing the
+    # result away is how a stream becomes quadratic in message length.
+    #
+    # Skipping a frame costs nothing: the next one is computed against what the
+    # browser actually has, so it carries the accumulated difference.
+    def broadcast(now: monotonic_ms)
+      return nil unless due?(now)
+
+      emit(now: now)
+    end
+
+    # A Document over the record's current buffer, rendered in the mode its
+    # status implies. Rebuilt on every call, because the buffer moves.
+    #
+    # A sealed message renders in static mode, which is what takes the caret
+    # off the last block.
+    def document
+      Document.new(
+        record.maquina_stream_buffer,
+        config: config,
+        sid: record.maquina_stream_id,
+        mode: record.maquina_stream_open? ? :streaming : :static
+      )
+    end
+
+    private
+      # Coalescing: frames inside the budget accumulate instead of going out one
+      # per token. The budget is the host's to tune; 60ms is roughly a frame.
+      def due?(now)
+        return true if @last_flush.nil?
+
+        now - @last_flush >= config.frame_budget_ms
+      end
+
+      def emit(now:, final: false)
+        frame = build_frame
+        return nil if frame.empty? && !final
+
+        @last_flush = now
+        frame.blocks.each { |block| @known[block.id] = sent_digest(block) }
+
+        # The sequence belongs to the host's row and moves once per frame that
+        # actually goes out, not once per append.
+        sequenced = Frame.new(
+          seq: record.maquina_stream_advance,
+          appends: frame.appends,
+          patch: frame.patch,
+          final: final
+        )
+        transport.call(record: record, frame: sequenced, config: config)
+        sequenced
+      end
+
+      # Append what the browser has never seen; patch the open tail, and nothing
+      # else.
+      #
+      # A block often takes its final form in the very frame that opens the one
+      # below it — a heading completes as the paragraph after it begins — and so
+      # stops being the tail while the client still holds "Status rep".
+      # Sending it once more at that handover was measured: it costs a full
+      # extra copy of the message, 1.248x -> 2.41x, because it happens once per
+      # block. The repair path already fixes it for free, because that change is
+      # a CONTENT change and content is exactly what a manifest digest covers.
+      #
+      # What repair does not fix is presentation chrome (data-ms-reveal, the
+      # block state) on a block that sealed after it stopped being the tail: the
+      # digest ignores chrome by design. That divergence is left, and corrected
+      # by the next reload. See the Phase 7 progress notes.
+      def build_frame
+        current = document
+        tail = current.blocks.last
+
+        appends = current.blocks.reject { |block| @known.key?(block.id) }
+        patch = []
+
+        if tail && changed?(tail)
+          patch << tail
+          appends.delete_if { |block| block.id == tail.id }
+        end
+
+        Frame.new(seq: record.maquina_stream_sequence, appends: appends, patch: patch)
+      end
+
+      # What the client holds is bytes, so "changed" is measured on the bytes.
+      # The manifest's digest answers a different question — what the block says
+      # — and ignores state and caret attributes on purpose.
+      def changed?(block)
+        @known.key?(block.id) && @known[block.id] != sent_digest(block)
+      end
+
+      def sent_digest(block)
+        Digest::SHA256.hexdigest(block.html.to_s)[0, 16]
+      end
+
+      def monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1_000
+      end
+
+    # Default transport. Turbo Streams today; the seam is here so SSE is
+    # possible without the broadcaster knowing about it.
+    #
+    # Appends go out as `broadcast_append_to` against the message element;
+    # patches as `broadcast_replace_to` with `method: "morph"`, so idiomorph
+    # pairs the node by id instead of recreating it. Every stream action carries
+    # `data-ms-seq` and `data-ms-frame`.
+    #
+    # A no-op when Turbo is not loaded, so the engine's Ruby side stays usable
+    # without it.
+    class TurboTransport
+      # Emits one Frame. The transport contract is this method and nothing
+      # else.
+      def call(record:, frame:, config:)
+        return unless defined?(Turbo::StreamsChannel)
+
+        target = record.maquina_stream_target
+
+        frame.appends.each do |block|
+          Turbo::StreamsChannel.broadcast_append_to(
+            target,
+            target: "ms-msg-#{record.maquina_stream_id}",
+            content: block.html,
+            attributes: frame_attributes(frame, :append)
+          )
+        end
+
+        frame.patch.each do |block|
+          Turbo::StreamsChannel.broadcast_replace_to(
+            target,
+            target: block.id,
+            content: block.html,
+            attributes: frame_attributes(frame, :patch).merge("method" => "morph")
+          )
+        end
+      end
+
+      private
+        # The final seal is marked as such, whatever it happens to carry. The
+        # repair path triggers on it.
+        def frame_attributes(frame, kind)
+          {"data-ms-seq" => frame.seq, "data-ms-frame" => frame.final? ? :final : kind}
+        end
+    end
+  end
+end