maquina_stream 0.1.0

data/lib/maquina_stream/text_direction.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module MaquinaStream
+  # Which way a piece of text reads.
+  #
+  # A message is one document but not necessarily one direction: an assistant
+  # answering in Arabic quotes an English identifier, a Hebrew paragraph sits
+  # next to a Ruby fence. Direction is therefore decided per block, the way the
+  # bidi algorithm decides it — by the FIRST STRONG character — and not by the
+  # document, the locale or the host.
+  #
+  # `dir="auto"` on every block would let the browser do exactly this, at the
+  # cost of eleven bytes on every block of every frame for the majority of
+  # documents that are left-to-right and need nothing. So the strong character
+  # is found here and the attribute is emitted only when it changes something.
+  #
+  # The render pipeline calls this per block. A host calls it when it renders
+  # text of its own — a message header, an attachment filename — that came from
+  # the same place the buffer did.
+  module TextDirection
+    # The scripts written right to left, as Ruby knows them.
+    RTL = /[\p{Hebrew}\p{Arabic}\p{Syriac}\p{Thaana}\p{Nko}\p{Samaritan}\p{Mandaic}\p{Adlam}]/
+
+    # Only a letter is strong. Digits, punctuation and whitespace take their
+    # direction from what surrounds them, which is why "١٢٣ Ruby" reads
+    # left-to-right and "مرحبا 123" does not.
+    STRONG = /[\p{L}\p{Nl}]/
+
+    # Explicit bidi controls. They are what a Trojan Source attack is made of:
+    # an override inside a comment reorders the rendering of code that the
+    # parser reads in a different order entirely.
+    CONTROLS = /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/
+
+    # The direction `text` reads in: `:rtl`, `:ltr`, or nil when nothing in it
+    # is strong either way.
+    #
+    # Nil is a real answer, not a failure — a block of digits or punctuation
+    # has no direction of its own, and stamping one on it would be a guess. The
+    # caller emits no `dir` attribute for it.
+    def self.of(text)
+      strong = text.to_s[STRONG]
+      return nil unless strong
+
+      strong.match?(RTL) ? :rtl : :ltr
+    end
+
+    # Whether `text` contains an explicit bidi control character.
+    #
+    # True is a reason to be suspicious, not to render differently: see
+    # CONTROLS. Code that displays a filename or a link target unescaped should
+    # check this first.
+    def self.controls?(text)
+      text.to_s.match?(CONTROLS)
+    end
+  end
+end

data/lib/maquina_stream/themes.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "rouge"
+
+module MaquinaStream
+  # Two stylesheets, one per scheme, generated from the Rouge themes named in
+  # the configuration.
+  #
+  # Highlighting emits classes and never inline colour, so switching to dark
+  # mode is a stylesheet concern and needs no re-render — which matters, because
+  # a re-render mid-stream would mean re-broadcasting sealed blocks to change a
+  # colour.
+  #
+  # The two files are generated, not written: `rake maquina_stream:themes`
+  # rewrites them from `config.themes`. A host that changes those theme names
+  # re-runs that task.
+  module Themes
+    # Every generated rule is scoped to a code block, so the themes cannot
+    # reach anything else on a host's page.
+    SCOPE = "[data-ms-code]"
+
+    # An explicitly chosen dark theme.
+    DARK_SELECTOR = '[data-theme="dark"]'
+
+    # An explicitly chosen light theme, and the default.
+    LIGHT_SELECTOR = ':root:not([data-theme="dark"])'
+
+    # Raised when `config.themes` names a theme Rouge does not define. Raising
+    # rather than falling back silently is how the `github_dark` typo in the
+    # original default was found.
+    class UnknownTheme < Error; end
+
+    class << self
+      # The generated CSS for one scheme, as a String.
+      #
+      # `scheme` is `:light` or `:dark`; anything else raises ArgumentError.
+      # An unknown Rouge theme name raises UnknownTheme.
+      def stylesheet(scheme, config: MaquinaStream.config)
+        case scheme.to_sym
+        when :light then light(config)
+        when :dark then dark(config)
+        else raise ArgumentError, "scheme must be :light or :dark"
+        end
+      end
+
+      # Where the generated stylesheet for `scheme` lives on disk. What the
+      # rake task writes to.
+      def path(scheme)
+        File.expand_path("../../app/assets/stylesheets/maquina_stream/themes/#{scheme}.css", __dir__)
+      end
+
+      private
+        def light(config)
+          <<~CSS
+            /* Generated by `rake maquina_stream:themes`. Do not edit by hand. */
+            #{render(config.themes.fetch(:light), "#{LIGHT_SELECTOR} #{SCOPE}")}
+          CSS
+        end
+
+        # The dark rules are written twice on purpose: once behind the media
+        # query for a viewer who never chose, and once behind the explicit
+        # attribute so a chosen theme beats the system preference.
+        def dark(config)
+          rules = render(config.themes.fetch(:dark), "#{DARK_SELECTOR} #{SCOPE}")
+          system = render(config.themes.fetch(:dark), ":root:not([data-theme=\"light\"]) #{SCOPE}")
+
+          <<~CSS
+            /* Generated by `rake maquina_stream:themes`. Do not edit by hand. */
+            #{rules}
+            @media (prefers-color-scheme: dark) {
+            #{system}
+            }
+          CSS
+        end
+
+        def render(name, scope)
+          theme = Rouge::Theme.find(name.to_s)
+          raise UnknownTheme, "Rouge has no theme named #{name.inspect}" unless theme
+
+          theme.render(scope: scope)
+        end
+    end
+  end
+end

data/lib/maquina_stream/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MaquinaStream
+  VERSION = "0.1.0"
+end

data/lib/maquina_stream.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "maquina_stream/version"
+require "maquina_stream/errors"
+require "maquina_stream/configuration"
+require "maquina_stream/registries"
+require "maquina_stream/streamable"
+require "maquina_stream/renderer"
+require "maquina_stream/document"
+require "maquina_stream/block"
+require "maquina_stream/broadcaster"
+require "maquina_stream/frame"
+require "maquina_stream/manifest"
+require "maquina_stream/sanitizer"
+require "maquina_stream/text_direction"
+require "maquina_stream/themes"
+require "maquina_stream/export"
+require "maquina_stream/component_cache"
+require "maquina_stream/components"
+require "maquina_stream/components/contract"
+require "maquina_stream/engine" if defined?(Rails::Engine)
+
+# Server-rendered streaming markdown for Rails, over Turbo, with a repair path.
+#
+# A model writes markdown a token at a time. The engine renders it on the
+# server, broadcasts small patches as it grows, and reconciles the browser with
+# the truth when frames go missing — which they do, because Action Cable offers
+# no delivery guarantee. **Only rendered HTML reaches the browser**; the client
+# never parses markdown.
+#
+# ## The whole integration
+#
+# ```ruby
+# class Message < ApplicationRecord
+#   include MaquinaStream::Streamable
+#
+#   maquina_stream buffer: :content,
+#                  stream_for: ->(m) { [m.conversation, :messages] }
+# end
+#
+# broadcaster = MaquinaStream::Broadcaster.new(message)
+# model.stream { |token| broadcaster.append(token) }
+# broadcaster.seal!
+# ```
+#
+# ```erb
+# <%= MaquinaStream.render(message) %>
+# ```
+#
+# ## What a host owns
+#
+# The engine resolves nothing and authorizes nothing on its own. Three things
+# are the host's, and none of them has a default the engine could guess:
+#
+# | Host responsibility | Where it goes |
+# |---|---|
+# | Looking a record up by its stream id | Configuration#find_stream |
+# | Deciding whether a request may see it | Configuration#authorize |
+# | Persisting the buffer, sequence and status | MaquinaStream::Streamable |
+#
+# **With no `authorize` configured, every repair request is refused.** That is
+# deliberate: an engine that guesses is an engine that leaks.
+#
+# ## Where to look next
+#
+# | Object | Responsibility |
+# |---|---|
+# | MaquinaStream::Configuration | Every option, its default and what changing it costs |
+# | MaquinaStream::Streamable | The host contract, and the macro that generates it |
+# | MaquinaStream::Broadcaster | Frame coalescing and Turbo Stream emission |
+# | MaquinaStream::Renderer | Markdown in, sanitized HTML out. A pure function |
+# | MaquinaStream::Document | Splits a rendered message into blocks and decides which may freeze |
+# | MaquinaStream::Block | One top-level block: id, markdown, HTML, digest |
+# | MaquinaStream::Frame | One broadcast: what changed since the last one |
+# | MaquinaStream::Manifest | What the browser is told the message currently is |
+# | MaquinaStream::Sanitizer | Allowlist plus URL hardening, the last pass before output |
+# | MaquinaStream::Export | A whole message, back out as markdown |
+# | MaquinaStream::TextDirection | Which way a piece of text reads |
+# | MaquinaStream::Components::Contract | The engine's half of a vendored component |
+#
+# Longer-form documentation ships in `docs/`: `getting-started.md`,
+# `configuration.md`, `streaming.md`, `repair.md`, `registries.md`,
+# `javascript.md`, `security.md` and `deferred-renderers.md`.
+module MaquinaStream
+  extend Registries
+
+  # Components destined for maquina_components, vendored inside the engine for
+  # now. Everything renders through MaquinaStream::Components, so extraction is
+  # a matter of publishing the partial there and dropping the name from here.
+  VENDORED_COMPONENTS = %i[attachment code_block suggestion snippet].freeze
+
+  class << self
+    # The current Configuration. Memoized; the same object `configure`
+    # yields.
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Configures the engine. Yields the Configuration and returns it.
+    #
+    # ```ruby
+    # MaquinaStream.configure do |c|
+    #   c.find_stream = ->(sid) { Message.find_by(id: sid) }
+    #   c.authorize   = ->(record, request) { record.conversation.readable_by?(request) }
+    # end
+    # ```
+    #
+    # Every option, with its default and the consequence of changing it, is
+    # documented on Configuration. Call this once from an initializer:
+    # configuration is global and read on every render, so changing it
+    # mid-stream changes what later frames of an open message look like.
+    def configure
+      yield config
+      config
+    end
+
+    # Throws away the configuration and starts again from the defaults.
+    #
+    # For tests. A host that calls this in production loses its `find_stream`
+    # and `authorize` seams, and every repair request after it is refused.
+    def reset_configuration!
+      @config = Configuration.new
+    end
+
+    # Renders a whole message to HTML, cached once it is sealed. Returns an
+    # `html_safe` String.
+    #
+    # ```erb
+    # <%= MaquinaStream.render(message) %>
+    # ```
+    #
+    # This is the history path — one call, one finished message on a page. It
+    # is not what a live stream uses: an open stream goes out frame by frame
+    # through Broadcaster. Pagination stays the host's; the engine renders the
+    # messages the host chose, in the order it chose them.
+    #
+    # `record` must satisfy MaquinaStream::Streamable. `config:` defaults to
+    # the global MaquinaStream.config.
+    #
+    # A sealed message is immutable, so its HTML is a pure function of its
+    # buffer and can be cached by digest — which is what makes a page of history
+    # cheap: re-rendering fifty finished messages on every page load is work
+    # nobody asked for. An open message is never cached; it is about to change.
+    #
+    # The digest is of the buffer, so a host that edits a message gets a new key
+    # rather than a stale render.
+    def render(record, config: self.config)
+      markdown = record.maquina_stream_buffer
+
+      # Through Document, not Renderer. Renderer produces the HTML; Document is
+      # what stamps each block with the id and digest the DOM contract requires,
+      # and without those a page cannot be repaired at all — ms-repair would
+      # have nothing to compare a manifest against.
+      return document_html(record, markdown, config) if record.maquina_stream_open?
+
+      ComponentCache.fetch("document", record.maquina_stream_id, Digest::SHA256.hexdigest(markdown.to_s)) do
+        document_html(record, markdown, config)
+      end
+    end
+
+    private
+
+    def document_html(record, markdown, config)
+      blocks = Document.new(
+        markdown,
+        config: config,
+        sid: record.maquina_stream_id,
+        mode: record.maquina_stream_open? ? :streaming : :static
+      ).blocks
+
+      html = blocks.map(&:html).join("\n")
+      html.respond_to?(:html_safe) ? html.html_safe : html
+    end
+  end
+end

metadata

@@ -0,0 +1,204 @@
+--- !ruby/object:Gem::Specification
+name: maquina_stream
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mario Alberto Chávez
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: maquina_remend
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: commonmarker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Rails engine that renders a streaming markdown buffer to HTML on the
+  server and broadcasts it over Turbo Streams. Only rendered HTML reaches the browser.
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+files:
+- ".rdoc_options"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/assets/stylesheets/maquina_stream/components/attachment.css
+- app/assets/stylesheets/maquina_stream/components/code_block.css
+- app/assets/stylesheets/maquina_stream/components/shimmer.css
+- app/assets/stylesheets/maquina_stream/components/snippet.css
+- app/assets/stylesheets/maquina_stream/components/source_citation.css
+- app/assets/stylesheets/maquina_stream/components/suggestion.css
+- app/assets/stylesheets/maquina_stream/reveal.css
+- app/assets/stylesheets/maquina_stream/themes/dark.css
+- app/assets/stylesheets/maquina_stream/themes/light.css
+- app/controllers/maquina_stream/application_controller.rb
+- app/controllers/maquina_stream/blocks_controller.rb
+- app/controllers/maquina_stream/manifests_controller.rb
+- app/helpers/maquina_stream/components_helper.rb
+- app/javascript/maquina_stream/controllers/application_controller.js
+- app/javascript/maquina_stream/controllers/ms_autoscroll_controller.js
+- app/javascript/maquina_stream/controllers/ms_code_controller.js
+- app/javascript/maquina_stream/controllers/ms_deferred_controller.js
+- app/javascript/maquina_stream/controllers/ms_diagram_controller.js
+- app/javascript/maquina_stream/controllers/ms_link_safety_controller.js
+- app/javascript/maquina_stream/controllers/ms_math_controller.js
+- app/javascript/maquina_stream/controllers/ms_repair_controller.js
+- app/javascript/maquina_stream/controllers/ms_reveal_controller.js
+- app/javascript/maquina_stream/controllers/ms_table_controller.js
+- app/javascript/maquina_stream/index.js
+- app/views/maquina_stream/components/_attachment.html.erb
+- app/views/maquina_stream/components/_code_block.html.erb
+- app/views/maquina_stream/components/_shimmer.html.erb
+- app/views/maquina_stream/components/_snippet.html.erb
+- app/views/maquina_stream/components/_source_citation.html.erb
+- app/views/maquina_stream/components/_suggestion.html.erb
+- config/importmap.rb
+- config/locales/en.yml
+- config/locales/es.yml
+- config/routes.rb
+- docs/configuration.md
+- docs/deferred-renderers.md
+- docs/getting-started.md
+- docs/javascript.md
+- docs/registries.md
+- docs/repair.md
+- docs/security.md
+- docs/streaming.md
+- lib/generators/maquina_stream/install/USAGE
+- lib/generators/maquina_stream/install/install_generator.rb
+- lib/generators/maquina_stream/install/templates/initializer.rb.tt
+- lib/generators/maquina_stream/streamable/USAGE
+- lib/generators/maquina_stream/streamable/streamable_generator.rb
+- lib/generators/maquina_stream/streamable/templates/migration.rb.tt
+- lib/generators/maquina_stream/streamable/templates/model.rb.tt
+- lib/maquina_stream.rb
+- lib/maquina_stream/block.rb
+- lib/maquina_stream/broadcaster.rb
+- lib/maquina_stream/component_cache.rb
+- lib/maquina_stream/components.rb
+- lib/maquina_stream/components/contract.rb
+- lib/maquina_stream/configuration.rb
+- lib/maquina_stream/document.rb
+- lib/maquina_stream/engine.rb
+- lib/maquina_stream/errors.rb
+- lib/maquina_stream/export.rb
+- lib/maquina_stream/frame.rb
+- lib/maquina_stream/manifest.rb
+- lib/maquina_stream/registries.rb
+- lib/maquina_stream/renderer.rb
+- lib/maquina_stream/renderer/fence.rb
+- lib/maquina_stream/renderer/post_pass.rb
+- lib/maquina_stream/renderer/tag_blocks.rb
+- lib/maquina_stream/renderer/view_context.rb
+- lib/maquina_stream/sanitizer.rb
+- lib/maquina_stream/streamable.rb
+- lib/maquina_stream/text_direction.rb
+- lib/maquina_stream/themes.rb
+- lib/maquina_stream/version.rb
+homepage: https://github.com/maquina-app/maquina_stream
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://maquina.app
+  source_code_uri: https://github.com/maquina-app/maquina_stream
+  changelog_uri: https://github.com/maquina-app/maquina_stream/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/maquina_stream/0.1.0
+  rubygems_mfa_required: 'true'
+rdoc_options:
+- "--markup"
+- markdown
+- "--main"
+- README.md
+- "--title"
+- maquina_stream 0.1.0
+- "--exclude"
+- "(?:\\A|/)test/"
+- "--exclude"
+- "(?:\\A|/)sdd/"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.17
+specification_version: 4
+summary: Streaming markdown rendering for Rails, server-side.
+test_files: []