expo_turbo-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 63dbea7a9148945dfb80e069492b057b96a6dd831f80f5a99c9f9ae0eb64757a
+  data.tar.gz: d8e65c67fe6fcc44861cb3cd9c56c98ba4e7edb9b4c205618bd4a207d8326bbf
+SHA512:
+  metadata.gz: de668ead0d2d6ca7167168a265d3224963683e766d611295be54a8cd1e2851426b4d34374aee8e8c74d73bdd714cb63bc1705c7792d4bc1cb093f74c4d2b523f
+  data.tar.gz: 3131f093848678238706514bb4ec397a40c19e0a1a655b824c67fb327f93c1e57eeec47e3d0f47b169f959fdd9eea2fd30de083d51b2d23790617429ea113f27

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NoScrubs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,207 @@
+# expo_turbo-rails
+
+The Rails package for Expo Turbo. It registers the distinct `application/vnd.expo-turbo+xml` MIME type and provides an opt-in controller concern for rendering host-owned XML documents, matching native Frame responses, standard Turbo Stream response fragments, and immediate or queued public Stream broadcasts. Use `ExpoTurbo::Rails::Controller` rather than including its helper modules directly. The Engine remains route-free.
+
+The package validates rendered Expo Turbo documents structurally and rejects blank or duplicate literal IDs across the complete response, including Frame IDs. A controller must declare the components and style tokens it is allowed to render documents; when it does, the same policy also applies to its Frame, Stream, and raw controller-broadcast output. Its optional protected Cable boundary delegates all credentials and resource policy to the host.
+
+> [!IMPORTANT]
+> Version [`0.1.0`](https://rubygems.org/gems/expo_turbo-rails) is the stable
+> release published on 2026-07-27. Manual VoiceOver, TalkBack, and browser
+> screen-reader evidence remains an explicit follow-up and is not claimed by
+> the `0.1.0` compatibility surface.
+
+```ruby
+gem "expo_turbo-rails"
+```
+
+```ruby
+require "expo_turbo/rails"
+```
+
+Opt a controller into XML rendering and confine it to one host-owned view root:
+
+```ruby
+class ExpoTurboController < ActionController::API
+  include ExpoTurbo::Rails::Controller
+
+  expo_turbo_view_root Rails.root.join("app/views/expo_turbo")
+  expo_turbo_template_capabilities(
+    components: {
+      "Gallery" => {},
+      "DemoCard" => {style_tokens: true},
+      "DemoText" => {}
+    },
+    max_style_tokens: 5,
+    style_tokens: {
+      "space:compact" => {components: ["DemoCard"], group: "space"},
+      "tone:info" => {components: ["DemoCard"], group: "tone"}
+    }
+  )
+
+  def show
+    render_expo_turbo "documents/show"
+  end
+end
+```
+
+The template argument is relative to the configured root; absolute paths, traversal, missing files, and symlink escapes are rejected. The resolved `.xml.erb` source is evaluated as ERB with layouts disabled, rather than served as raw file content. Before it renders, the exact output must be a strict UTF-8 XML document: one root, valid namespaces and attributes, no DTD or processing instruction, and an optional leading UTF-8 XML declaration only. Every literal `id` must also be nonblank and unique across the complete rendered document, including nested Frames. The capability declaration then admits only its exact components (and explicit aliases), exact unprefixed `turbo-frame`, `turbo-stream`, `template`, and `turbo-cable-stream-source` wrappers (including default-namespace elements), and declared `style-tokens`. Style-token lists use the same JavaScript whitespace split, count, duplicate, component, and group-conflict rules as the native adapter. A component must opt into the `style-tokens` attribute, and style-token component lists are canonicalized through aliases. The host declaration must mirror its installed registry and style adapter; it deliberately does not attempt to derive or validate arbitrary Zod props/codecs. Validation never serializes the output, so it does not alter preserved XML text.
+
+For a native Frame GET, read the validated request header and emit an exact matching Frame from the host-owned XML template. `expo_turbo_frame_tag` accepts a nonblank UTF-8 literal ID without control characters, or a model class that it normalizes with Rails' `dom_id`, then delegates tag generation to `turbo-rails`. It deliberately does not install `Turbo::Frames::FrameRequest`, so it does not alter HTML layouts or adopt its raw-header behavior. Before returning, it parses the exact Frame output under a private synthetic root and applies the same configured component/style admission: markup must be valid UTF-8 XML without declarations, DTDs, or processing instructions, and any XML prefix must be declared by the Frame fragment itself. Validation does not serialize or alter the returned `SafeBuffer`, so inline `xml:space="preserve"` text keeps its authored bytes for the native parser.
+
+```ruby
+def show
+  return head :bad_request unless expo_turbo_frame_request_id == "account-details"
+
+  render_expo_turbo "accounts/details"
+end
+```
+
+```erb
+<%= expo_turbo_frame_tag "account-details" do %>
+  <AccountDetails id="account-details-content">...</AccountDetails>
+<% end %>
+```
+
+For records, use the opt-in `expo_turbo_dom_id` helper to derive literal target IDs before passing them to a Frame or Stream helper. It supports only the shared `record`, `document`, `frame`, `list`, `form`, `error`, and `loading` roles, so every role stays deterministic and distinct:
+
+```erb
+<%= expo_turbo_frame_tag expo_turbo_dom_id(@account, :frame) do %>
+  <AccountDetails id="<%= expo_turbo_dom_id(@account) %>">...</AccountDetails>
+<% end %>
+```
+
+For a persisted `Account` with ID `7`, those values are `account_7`, `document_account_7`, `frame_account_7`, `list_account_7`, `form_account_7`, `error_account_7`, and `loading_account_7`. Only `:list` accepts a model class, producing `list_account`; every record role requires `persisted?` plus a complete `to_key`, so unpersisted or incomplete records fail instead of producing a shared `new_*` target. Generated IDs must still be unique within each host document; the helper does not add tenant scope or accept a caller-supplied raw target segment.
+
+`expo_turbo_frame_request?` and `expo_turbo_frame_request_id` are also available in the XML view. For an endpoint that can emit a full document or a Frame, pass `expo_turbo_cache_key` to the host's existing conditional-GET API:
+
+```ruby
+def show
+  representation = expo_turbo_frame_request? ? "accounts/details-frame-v1" : "accounts/details-document-v1"
+  fresh_when etag: expo_turbo_cache_key(@account, representation)
+  return if performed?
+
+  return render_expo_turbo("accounts/details") unless expo_turbo_frame_request?
+
+  render_expo_turbo "accounts/details_frame"
+end
+```
+
+The helper preserves existing `Vary` dimensions and adds `Turbo-Frame`. Its returned key distinguishes a document from each valid Frame ID, so Rails generates separate validators for representations whose bodies differ. Because Expo Turbo renders its configured XML source as inline ERB, the host-supplied key must also include a representation version or digest that changes with every template, partial, layout, or other rendered-byte change. `expo_turbo_vary_by_frame!` and `expo_turbo_cache_variant` are available when a host needs to compose another cache API directly. The gem does not make a response public, set a TTL, or infer tenant/user variation; the host must add every other representation input.
+
+Use the same opt-in concern to emit one or more standard Stream siblings. The builder supports `append`, `prepend`, `before`, `after`, `replace`, `update`, `remove`, `refresh`, and their `*_all` selector variants:
+
+```ruby
+def update
+  render_expo_turbo_stream(
+    expo_turbo_stream.update(
+      "notice",
+      partial: "notices/notice",
+      locals: {message: "Saved"}
+    ),
+    expo_turbo_stream.remove("new_notice")
+  )
+end
+```
+
+`partial: "notices/notice"` resolves only `app/views/expo_turbo/notices/_notice.xml.erb`; it never searches normal host view paths or falls back to `.html.erb`. Raw positional content, keyword `content:`, and captured blocks are inserted as XML template payloads, so hosts must provide valid XML. For target and selector actions, keyword `content:` is consumed as the `<template>` payload rather than emitted as a `<turbo-stream content>` attribute; provide exactly one of positional content, keyword content, a block, or a partial. A record with `to_partial_path` is rendered through the same confined XML partial resolver and receives its conventional local; `layout:` accepts the same XML partial path only with a captured block. A positional renderable must implement `render_in`, declare `format: :xml`, and receives a limited context that exposes only `render(partial:, locals:)` plus `capture`; its partial render is likewise confined to the Expo XML root. These boundaries prevent ordinary lookup from selecting host HTML, but templates and renderables remain trusted host code rather than a Ruby sandbox. Record-compatible Stream targets use Turbo 8.0.23's `dom_id` rules on every supported `turbo-rails` version: a record becomes its `dom_id`, a bare model class becomes `new_*`, and a selector gets the corresponding `#` prefix; raw string IDs and selectors remain unchanged. `refresh` omits a blank or `false` request ID while preserving all other attributes. `remove`, `remove_all`, and `refresh` have no template and reject `content:`. Each generated tag and final response is parsed as a self-contained sibling Stream fragment before it is returned; output built through the configured controller also receives the same component/style admission. Use `head :no_content` when there is no Stream action. The response uses `text/vnd.turbo-stream.html` and keeps multiple Stream actions as normal siblings without a custom wrapper.
+
+For a public Action Cable stream, render the source inside an Expo Turbo XML document and broadcast pre-rendered Stream markup from an explicit controller/view context:
+
+```erb
+<%= expo_turbo_stream_from @room, id: "room-stream" %>
+```
+
+```ruby
+broadcast_expo_turbo_stream_to @room do |stream|
+  stream.append("messages", partial: "messages/message", locals: {message: @message})
+end
+
+broadcast_expo_turbo_stream_later_to @room do |stream|
+  stream.append("messages", partial: "messages/message", locals: {message: @message})
+end
+
+broadcast_expo_turbo_refresh_to @room, request_id: Turbo.current_request_id, method: "morph", scroll: "preserve"
+broadcast_expo_turbo_refresh_later_to @room, request_id: Turbo.current_request_id, method: "morph", scroll: "preserve"
+```
+
+All three operations use the same normalized streamables and append the fixed `:expo` suffix. For example, the literal streamables `:room, "42"` map to `room:42:expo`, keeping Expo XML distinct from the browser HTML stream `room:42`. `expo_turbo_stream_from` emits the standard `Turbo::StreamsChannel` descriptor with a matching signed stream name and reserves its channel/signature attributes. `ExpoTurbo::Rails::Streams.broadcast_to(*streamables, content:)` is available when the host already owns a rendered nonblank UTF-8 Stream payload; it parses that payload as a self-contained sibling Stream fragment before sending or enqueueing it, and the queued job validates again before delivery.
+
+`broadcast_expo_turbo_stream_to` sends immediately to the host's Action Cable pubsub. `broadcast_expo_turbo_stream_later_to` uses the host-configured Active Job adapter and enqueues `ExpoTurbo::Rails::Streams::BroadcastJob` with only the resolved stream-name string and already-rendered payload; it does not serialize a host model or render a template when the job runs. The dedicated refresh variants build and validate their tag before sending or deferring it. The later variant uses Turbo's caller-thread debouncer for an identical resolved Expo stream name plus request ID, so repeated refreshes on that thread collapse to the newest pre-rendered XML while different streams or request IDs remain independent. It does not coordinate across threads or processes. The job disables Active Job argument logging and discards an argument-deserialization failure rather than retrying it. Context-free `ExpoTurbo::Rails::Streams.broadcast_to` remains structural-only because it has no host capability declaration; render a payload through a configured controller before sending when component/style admission is required. The host owns Action Cable configuration (including its logger, adapter, and any mounted client endpoint) plus its Active Job adapter. This API does not establish a client connection, prove receipt, provide replay, issue credentials, or authorize protected resources. Do not use this public-stream API for sensitive XML.
+
+## Protected Cable streams
+
+For a protected resource, configure host-owned credential, subject, authorization, and redacted callback-error hooks during application boot. Include the connection module in the host's chosen Cable connection; it resolves and caches the subject only when a protected subscription asks for it, and does not add an Action Cable connection identifier.
+
+The callback receives the included connection. Use its public `expo_turbo_request` bridge for request headers/cookies because Action Cable keeps `request` private.
+
+```ruby
+ExpoTurbo::Rails::Cable.configure(
+  credential_extractor: ->(connection) {
+    host_extract_short_lived_credential(connection.expo_turbo_request)
+  },
+  subject_resolver: ->(credential) { host_resolve_subject(credential) },
+  subscription_authorizer: ->(subject:, stream_name:, grant:) {
+    host_authorize_expo_stream(subject:, stream_name:, grant:)
+  },
+  subscription_error_reporter: ->(code:, error_class:) {
+    host_report_expo_turbo_cable_error(code:, error_class:)
+  }
+)
+
+class ApplicationCable::Connection < ActionCable::Connection::Base
+  include ExpoTurbo::Rails::Cable::Connection
+end
+```
+
+Render a protected source with a short-lived, resource-bound client-visible grant, then publish only through the matching protected API:
+
+```erb
+<%= expo_turbo_protected_stream_from @room, grant: expo_stream_grant(@room) %>
+```
+
+```ruby
+ExpoTurbo::Rails::Cable.broadcast_protected_to(
+  @room,
+  content: expo_turbo_stream.remove("notice").to_s
+)
+```
+
+The helper renders `ExpoTurbo::Rails::Cable::ProtectedStreamsChannel`, a token from the gem's own verifier, and `data-grant`. The Channel decodes that token to the canonical Expo stream name only for the host authorizer, but subscribes and broadcasts on the opaque token itself. The generic `Turbo::StreamsChannel` cannot verify the token, so it cannot bypass the host authorizer or receive protected broadcasts through the public `:expo` topic. Invalid descriptors, missing subjects, invalid grants, and false authorization reject only that subscription. Callback failures reject and send only a code and exception class to the configured reporter; grant, credential, token, and exception message are never passed to it.
+
+The gem deliberately does not choose a WebSocket header, ticket encoding, identity type, grant schema, expiry, rotation, tenant policy, or native reconnect policy. The grant is delivered in XML and is therefore client-visible: make it short-lived, resource-bound, and safe to send to that client. The host must authenticate the socket, validate grant expiry and resource ownership in `subscription_authorizer`, and recreate/reconnect the native Cable client when identity or credentials change.
+
+`subscription_authorizer` is evaluated when the subscription is admitted; it is not a reauthorization lease. When a grant expires or is revoked, the host must terminate the affected subscription or connection and require a fresh admission. If targeted disconnect is needed, the host may use its own safe Action Cable connection identity or channel mechanism; this gem intentionally adds no connection identifier.
+
+## Structural XML test helpers
+
+Host tests can opt into strict structural XML assertions without relying on raw-string matching:
+
+```ruby
+require "expo_turbo/rails/testing"
+
+document = ExpoTurbo::Rails::Testing.parse_document(response.body)
+streams = ExpoTurbo::Rails::Testing.parse_stream_fragment(response.body)
+  .xpath("/expo-turbo-test-root/turbo-stream")
+```
+
+`parse_document` returns a strict `Nokogiri::XML::Document` for one XML document. `parse_stream_fragment` returns a document with a private synthetic root so one or more sibling `<turbo-stream>` elements retain their authored order. Both accept only nonblank UTF-8 input (including binary HTTP bytes that validate as UTF-8), reject recovery parsing, DTDs, entity declarations, processing instructions, malformed namespaces, and non-Stream top-level fragment content, and never make network requests.
+
+This entrypoint is deliberately opt-in: `require "expo_turbo/rails"` does not load Nokogiri. Production Frame/Stream fragments use the same strict parser lazily at their output boundaries, but this entrypoint remains test support: it does not admit complete XML document templates or perform component, style, duplicate-ID, or other semantic protocol validation.
+
+Run the gem against both supported server pins with:
+
+```sh
+bundle exec appraisal ruby "$(bundle show rake)/exe/rake"
+```
+
+## Changelog
+
+**2026-07-21**:
+
+- Changed: Added an opt-in protected Cable source, Channel, verifier namespace, and immediate/queued broadcast APIs.
+- Why: Public Turbo stream signatures cannot carry host resource authorization safely.
+- Impact: Protected hosts must configure the four callbacks above and terminate affected subscriptions or connections after grant expiry/revocation; public stream behavior remains unchanged.
+
+See the repository
+[README](https://github.com/noscrubs-dev/expo-turbo#readme) for project status
+and development commands.

data/lib/expo_turbo/rails/cable/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ExpoTurbo
+  module Rails
+    module Cable
+      class Configuration
+        attr_reader :credential_extractor, :subject_resolver, :subscription_authorizer, :subscription_error_reporter
+
+        def initialize(credential_extractor:, subject_resolver:, subscription_authorizer:, subscription_error_reporter:)
+          @credential_extractor = callable!(credential_extractor, "credential_extractor")
+          @subject_resolver = callable!(subject_resolver, "subject_resolver")
+          @subscription_authorizer = callable!(subscription_authorizer, "subscription_authorizer")
+          @subscription_error_reporter = callable!(subscription_error_reporter, "subscription_error_reporter")
+          freeze
+        end
+
+        private
+
+        def callable!(value, name)
+          return value if value.respond_to?(:call)
+
+          raise ConfigurationError, "Expo Turbo Cable #{name} must respond to #call"
+        end
+      end
+    end
+  end
+end

data/lib/expo_turbo/rails/cable/connection.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ExpoTurbo
+  module Rails
+    module Cable
+      module Connection
+        def expo_turbo_request
+          request
+        end
+
+        def expo_turbo_subject
+          return @expo_turbo_subject if defined?(@expo_turbo_subject_resolved)
+
+          @expo_turbo_subject = ExpoTurbo::Rails::Cable.resolve_subject(self)
+          @expo_turbo_subject_resolved = true
+          @expo_turbo_subject
+        end
+      end
+    end
+  end
+end

data/lib/expo_turbo/rails/cable/protected_broadcast_job.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ExpoTurbo
+  module Rails
+    module Cable
+      class ProtectedBroadcastJob < ::ActiveJob::Base
+        discard_on ActiveJob::DeserializationError
+
+        self.log_arguments = false
+
+        def perform(token, content:)
+          ExpoTurbo::Rails::Cable.broadcast_to_protected_token(token, content:)
+        end
+      end
+    end
+  end
+end

data/lib/expo_turbo/rails/cable/protected_streams_channel.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ExpoTurbo
+  module Rails
+    module Cable
+      class ProtectedStreamsChannel < ::ActionCable::Channel::Base
+        CALLBACK_FAILURE = Object.new.freeze
+
+        def subscribed
+          return reject unless ExpoTurbo::Rails::Cable.configured?
+
+          token = params[:signed_stream_name]
+          stream_name = ExpoTurbo::Rails::Cable.verified_protected_stream_name(token)
+          return reject unless stream_name && valid_grant?(params[:grant])
+
+          subject = resolved_subject
+          return if subject.equal?(CALLBACK_FAILURE)
+          return reject unless subject.present?
+
+          authorized = subscription_authorized?(subject, stream_name, params[:grant])
+          return if authorized.equal?(CALLBACK_FAILURE)
+          return reject unless authorized
+
+          stream_from token
+        end
+
+        private
+
+        def valid_grant?(grant)
+          grant.is_a?(String) && grant.encoding == Encoding::UTF_8 && grant.valid_encoding? && grant.present?
+        end
+
+        def resolved_subject
+          connection.expo_turbo_subject
+        rescue => error
+          callback_failure(:subject_resolution_failed, error)
+        end
+
+        def subscription_authorized?(subject, stream_name, grant)
+          ExpoTurbo::Rails::Cable.subscription_authorized?(subject:, stream_name:, grant:)
+        rescue => error
+          callback_failure(:subscription_authorization_failed, error)
+        end
+
+        def callback_failure(code, error)
+          ExpoTurbo::Rails::Cable.report_subscription_error(code:, error:)
+          reject
+          CALLBACK_FAILURE
+        end
+      end
+    end
+  end
+end

data/lib/expo_turbo/rails/cable.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "cable/configuration"
+require_relative "cable/connection"
+require_relative "cable/protected_broadcast_job"
+require_relative "cable/protected_streams_channel"
+
+module ExpoTurbo
+  module Rails
+    module Cable
+      PROTECTED_STREAM_VERIFIER_NAME = "expo_turbo/protected_stream"
+      PROTECTED_STREAM_PURPOSE = "expo_turbo.protected_stream"
+
+      class << self
+        def configure(credential_extractor:, subject_resolver:, subscription_authorizer:, subscription_error_reporter:)
+          @configuration = Configuration.new(
+            credential_extractor:,
+            subject_resolver:,
+            subscription_authorizer:,
+            subscription_error_reporter:
+          )
+        end
+
+        def configured?
+          defined?(@configuration)
+        end
+
+        def configuration
+          @configuration || raise(
+            ConfigurationError,
+            "configure ExpoTurbo::Rails::Cable before rendering or accepting protected Expo Turbo subscriptions"
+          )
+        end
+
+        def protected_stream_token_for(*streamables)
+          protected_stream_verifier.generate(
+            Streams.stream_name_for(*streamables),
+            purpose: PROTECTED_STREAM_PURPOSE
+          ).encode(Encoding::UTF_8)
+        end
+
+        def verified_protected_stream_name(token)
+          return unless valid_token?(token)
+
+          stream_name = protected_stream_verifier.verified(token, purpose: PROTECTED_STREAM_PURPOSE)
+          stream_name if Streams.valid_stream_name?(stream_name)
+        end
+
+        def broadcast_protected_to(*streamables, content:)
+          broadcast_to_protected_token(protected_stream_token_for(*streamables), content:)
+        end
+
+        def broadcast_protected_later_to(*streamables, content:)
+          ProtectedBroadcastJob.perform_later(
+            protected_stream_token_for(*streamables),
+            content: Streams.valid_content!(content)
+          )
+        end
+
+        def broadcast_to_protected_token(token, content:)
+          unless verified_protected_stream_name(token)
+            raise ArgumentError, "protected stream token must be a valid Expo Turbo protected stream token"
+          end
+
+          ::Turbo::StreamsChannel.broadcast_stream_to(token, content: Streams.valid_content!(content))
+        end
+
+        def resolve_subject(connection)
+          credential = configuration.credential_extractor.call(connection)
+          configuration.subject_resolver.call(credential)
+        end
+
+        def subscription_authorized?(subject:, stream_name:, grant:)
+          configuration.subscription_authorizer.call(subject:, stream_name:, grant:) == true
+        end
+
+        def report_subscription_error(code:, error:)
+          configuration.subscription_error_reporter.call(code:, error_class: error.class.name)
+        rescue
+          # A failing observer must not make Action Cable log a descriptor containing the client-visible grant.
+        end
+
+        private
+
+        def protected_stream_verifier
+          ::Rails.application.message_verifier(PROTECTED_STREAM_VERIFIER_NAME)
+        end
+
+        def valid_token?(token)
+          token.is_a?(String) && token.encoding == Encoding::UTF_8 && token.valid_encoding? && token.present?
+        end
+      end
+    end
+  end
+end

data/lib/expo_turbo/rails/controller.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/module/attr_internal"
+require "action_controller/metal/helpers"
+require "action_view/rendering"
+require "pathname"
+
+module ExpoTurbo
+  module Rails
+    module Controller
+      extend ActiveSupport::Concern
+      include ActionController::Helpers
+      include ActionView::Rendering
+
+      included do
+        class_attribute :expo_turbo_views_path, instance_accessor: false
+        class_attribute :expo_turbo_template_capabilities_config, instance_accessor: false
+        helper ExpoTurbo::Rails::Frames::Helper
+        helper ExpoTurbo::Rails::DomIds::Helper
+        helper ExpoTurbo::Rails::Streams::Helper
+        helper_method :expo_turbo_frame_request?, :expo_turbo_frame_request_id
+      end
+
+      class_methods do
+        def expo_turbo_view_root(path)
+          self.expo_turbo_views_path = Pathname(path).expand_path
+        end
+
+        def expo_turbo_template_capabilities(components:, style_tokens: {}, max_style_tokens: 5)
+          self.expo_turbo_template_capabilities_config = TemplateCapabilities.new(
+            components:,
+            style_tokens:,
+            max_style_tokens:
+          )
+        end
+      end
+
+      def render_expo_turbo(template, locals: {}, status: :ok)
+        body = render_to_string(
+          inline: File.read(expo_turbo_template_file(template)),
+          type: :erb,
+          formats: [:xml],
+          layout: false,
+          locals: locals
+        )
+        raise TemplateError, "Expo Turbo templates must render valid UTF-8" unless body.encoding == Encoding::UTF_8 && body.valid_encoding?
+
+        document = XmlFragments.parse_document(body)
+        XmlFragments.validate_document_ids!(document)
+        expo_turbo_validate_document!(document)
+
+        render plain: body, content_type: MIME_TYPE, status: status
+      rescue XmlFragments::DocumentIdError
+        raise TemplateError, "Expo Turbo templates must use unique nonblank literal ids"
+      rescue XmlFragments::ParseError
+        raise TemplateError, "Expo Turbo templates must render well-formed UTF-8 XML"
+      end
+
+      def expo_turbo_frame_request?
+        expo_turbo_frame_request_id.present?
+      end
+
+      def expo_turbo_frame_request_id
+        frame_id = request.get_header("HTTP_TURBO_FRAME")
+        frame_id = frame_id.dup.force_encoding(Encoding::UTF_8) if frame_id.is_a?(String)
+        Frames.valid_id?(frame_id) ? frame_id : nil
+      end
+
+      def expo_turbo_cache_variant
+        Frames.cache_variant(expo_turbo_frame_request_id)
+      end
+
+      def expo_turbo_vary_by_frame!
+        values = response.headers["Vary"].to_s.split(",").map(&:strip).reject(&:blank?)
+        return response.headers["Vary"] if values.include?("*")
+
+        values << "Accept" if request.should_apply_vary_header? && values.none? { |value| value.casecmp?("Accept") }
+        values << "Turbo-Frame" if values.none? { |value| value.casecmp?("Turbo-Frame") }
+        response.set_header "Vary", values.join(", ")
+      end
+
+      def expo_turbo_cache_key(*keys)
+        expo_turbo_vary_by_frame!
+        [*keys, *expo_turbo_cache_variant]
+      end
+
+      def expo_turbo_stream
+        view_context.expo_turbo_stream
+      end
+
+      def render_expo_turbo_stream(*streams, status: :ok)
+        streams << yield(expo_turbo_stream) if block_given?
+        body = streams.flatten.compact.join
+        raise TemplateError, "Expo Turbo Stream responses must render valid UTF-8" unless body.encoding == Encoding::UTF_8 && body.valid_encoding?
+
+        document = XmlFragments.parse_stream_fragment(body)
+        expo_turbo_validate_stream_fragment!(document)
+
+        render plain: body, content_type: TURBO_STREAM_MIME_TYPE, status: status
+      rescue XmlFragments::ParseError
+        raise TemplateError, "Expo Turbo Stream responses must contain well-formed XML Stream fragments"
+      end
+
+      def broadcast_expo_turbo_stream_to(*streamables, content: nil)
+        raise ArgumentError, "provide content or a block, not both" if block_given? && !content.nil?
+
+        content = yield(expo_turbo_stream) if block_given?
+        expo_turbo_validate_broadcast_stream!(content)
+        ExpoTurbo::Rails::Streams.broadcast_to(*streamables, content: content)
+      end
+
+      def broadcast_expo_turbo_stream_later_to(*streamables, content: nil)
+        raise ArgumentError, "provide content or a block, not both" if block_given? && !content.nil?
+
+        content = yield(expo_turbo_stream) if block_given?
+        expo_turbo_validate_broadcast_stream!(content)
+        ExpoTurbo::Rails::Streams.broadcast_later_to(*streamables, content: content)
+      end
+
+      def broadcast_expo_turbo_refresh_to(*streamables, request_id: ::Turbo.current_request_id, **attributes)
+        ExpoTurbo::Rails::Streams.broadcast_refresh_to(*streamables, request_id:, **attributes)
+      end
+
+      def broadcast_expo_turbo_refresh_later_to(*streamables, request_id: ::Turbo.current_request_id, **attributes)
+        ExpoTurbo::Rails::Streams.broadcast_refresh_later_to(*streamables, request_id:, **attributes)
+      end
+
+      private
+
+      def expo_turbo_validate_document!(document)
+        expo_turbo_template_capabilities!.validate_document!(document)
+      rescue TemplateCapabilities::ValidationError
+        raise TemplateError, "Expo Turbo templates must use declared components and valid style tokens"
+      end
+
+      def expo_turbo_validate_frame_fragment!(document)
+        capabilities = self.class.expo_turbo_template_capabilities_config
+        return document unless capabilities
+
+        capabilities.validate_frame_fragment!(document)
+      rescue TemplateCapabilities::ValidationError
+        raise TemplateError, "Expo Turbo templates must use declared components and valid style tokens"
+      end
+
+      def expo_turbo_validate_stream_fragment!(document)
+        capabilities = self.class.expo_turbo_template_capabilities_config
+        return document unless capabilities
+
+        capabilities.validate_stream_fragment!(document)
+      rescue TemplateCapabilities::ValidationError
+        raise TemplateError, "Expo Turbo templates must use declared components and valid style tokens"
+      end
+
+      def expo_turbo_template_capabilities!
+        self.class.expo_turbo_template_capabilities_config || raise(
+          ConfigurationError,
+          "configure expo_turbo_template_capabilities before rendering Expo Turbo templates"
+        )
+      end
+
+      def expo_turbo_validate_broadcast_stream!(content)
+        return content unless self.class.expo_turbo_template_capabilities_config
+        return content unless content.is_a?(String) && content.encoding == Encoding::UTF_8 && content.valid_encoding? && content.present?
+
+        expo_turbo_validate_stream_fragment!(XmlFragments.parse_stream_fragment(content))
+        content
+      rescue XmlFragments::ParseError
+        raise TemplateError, "Expo Turbo Stream broadcasts must contain well-formed XML Stream fragments"
+      end
+
+      def expo_turbo_template_file(template)
+        expo_turbo_view_file("#{template}.xml.erb")
+      end
+
+      def expo_turbo_partial_file(partial)
+        relative_path = Pathname(partial.to_s)
+        raise TemplateError, "Expo Turbo partial must be named" if partial.blank? || relative_path.absolute? || relative_path.extname.present?
+
+        expo_turbo_view_file(relative_path.dirname.join("_#{relative_path.basename}").to_s + ".xml.erb")
+      end
+
+      def expo_turbo_view_file(relative_path)
+        root = self.class.expo_turbo_views_path
+        raise ConfigurationError, "configure expo_turbo_view_root before rendering" unless root
+
+        root = root.realpath
+        relative_path = Pathname(relative_path)
+        raise TemplateError, "Expo Turbo template is outside the configured view root" if relative_path.absolute?
+
+        candidate = root.join(relative_path).cleanpath
+        raise TemplateError, "Expo Turbo template does not exist" unless candidate.file?
+
+        candidate = candidate.realpath
+        raise TemplateError, "Expo Turbo template is outside the configured view root" unless candidate.to_s.start_with?("#{root}#{File::SEPARATOR}")
+
+        candidate.to_s
+      end
+    end
+  end
+end