dialecto-rails 0.1.0

data/lib/dialecto_rails/in_context/live_middleware.rb

@@ -0,0 +1,307 @@
+require "cgi"
+require "json"
+require_relative "../config"
+require_relative "../unmarked"
+require_relative "../version"
+require_relative "launch_token"
+require_relative "csp"
+
+module DialectoRails
+  module InContext
+    # Live-site editing for the Rack stack (spec-0025 §4): inert for visitors, on only for an editor who
+    # arrived with a launch link. Insert it after the session middleware.
+    #
+    # * Start: a `GET` with `?dialecto_edit=<token>` is verified (signature, `start_by`, origin). A good token
+    #   becomes the `dialecto_edit` cookie (`HttpOnly; Secure; SameSite=Lax; Path=/`, `Max-Age` to `exp`). Either
+    #   way the answer is `303` to this request's own path and query without the parameter. The session is never
+    #   touched: nothing reads a copy, and a token in a cookie-store session risks CookieOverflow.
+    # * Each request: a valid cookie marks a document `GET` or `HEAD` (the thread's flag is on while the app
+    #   renders), injects the overlay loader and sets `Cache-Control: private, no-store`, `Vary: Cookie` and
+    #   `X-Robots-Tag: noindex`, and widens `frame-src` to Dialecto. An invalid cookie is cleared. A visitor's
+    #   request goes to the app untouched.
+    # * `POST /__dialecto/stop` clears the cookie.
+    #
+    # `/__dialecto/context`, `/overrides` and `/marking` do not exist here: they answer 404, and nothing in
+    # this class consults the development store, the loopback checks, or any header for the origin.
+    class LiveMiddleware
+      PREFIX = "/__dialecto".freeze
+      PARAM = "dialecto_edit".freeze
+      COOKIE = "dialecto_edit".freeze
+      OVERLAY = File.expand_path("assets/overlay.js", __dir__)
+      JSON_HEADERS = {"content-type" => "application/json", "cache-control" => "no-store"}.freeze
+
+      # `settings`: a DialectoRails::Config with live mode on. `clock` returns Unix seconds.
+      def initialize(app, settings:, logger: nil)
+        @app = app
+        @settings = settings
+        @logger = logger
+        @origin = settings.origin
+        @key = settings.public_key
+        @clock = settings.clock
+      end
+
+      def call(env)
+        # One thread serves many requests: never inherit a flag.
+        ::DialectoRails.live_marking = false
+
+        early = intercept(env)
+        return early if early
+
+        cookie, valid = session_state(env)
+        return @app.call(env) unless cookie
+
+        valid ? editor(env, cookie, valid) : visitor_with_stale_cookie(env)
+      end
+
+      private
+
+      ## Answers that never reach the app
+
+      def intercept(env)
+        path = env["PATH_INFO"].to_s
+        return overlay(env) if path == "#{PREFIX}/overlay.js"
+        return stop(env) if path == "#{PREFIX}/stop"
+        return json(404, error: "not_found") if path == PREFIX || path.start_with?("#{PREFIX}/")
+
+        token = start_token(env)
+        token ? start(env, token) : nil
+      rescue => error
+        @logger&.debug("dialecto-rails: live request skipped (#{error.class})")
+        nil
+      end
+
+      ## 1. Start
+
+      def start_token(env)
+        return nil unless %w[GET HEAD].include?(env["REQUEST_METHOD"]) && !env["QUERY_STRING"].to_s.empty?
+
+        env["QUERY_STRING"].split("&").each do |pair|
+          name, value = pair.split("=", 2)
+          return CGI.unescape(value.to_s) if CGI.unescape(name.to_s) == PARAM
+        end
+        nil
+      end
+
+      def start(env, token)
+        headers = {"location" => own_url_without_param(env), "cache-control" => "private, no-store", "content-length" => "0"}
+        begin
+          now = @clock.call
+          result = verify(token, now, :start)
+          if result.ok?
+            cookie = "#{COOKIE}=#{token}; path=/; max-age=#{result.claims["exp"] - now}; secure; httponly; samesite=lax"
+            add_set_cookie(headers, cookie)
+          else
+            @logger&.info("dialecto-rails: launch link refused (#{result.reason})")
+          end
+        rescue => error
+          # Whatever goes wrong, the answer still takes the token out of the address bar and the Referer.
+          headers.delete("set-cookie")
+          @logger&.debug("dialecto-rails: launch link not started (#{error.class})")
+        end
+        [303, headers, []]
+      end
+
+      # This request's own path and query, never a URL taken from input. A path that a browser could read as
+      # another host ("//host", "/\host") is collapsed to the root.
+      def own_url_without_param(env)
+        path = "#{env["SCRIPT_NAME"]}#{env["PATH_INFO"]}"
+        path = "/" unless path.match?(%r{\A/(?![/\\])[^\\\x00-\x1f\x7f]*\z})
+        query = env["QUERY_STRING"].to_s.split("&").reject { |pair| CGI.unescape(pair.split("=", 2).first.to_s) == PARAM }.join("&")
+        query.empty? ? path : "#{path}?#{query}"
+      end
+
+      ## 2. Each request
+
+      # `[cookie, claims]`: the cookie's token and its verified claims, or `[token, nil]` when invalid.
+      def session_state(env)
+        token = cookies(env)[COOKIE]
+        return nil unless token
+
+        result = verify(token, @clock.call, :session)
+        [token, result.ok? ? result.claims : nil]
+      end
+
+      def verify(token, now, phase) = LaunchToken.verify(token, @key, @origin, now, phase, repo: @settings.repo)
+
+      def cookies(env)
+        env["HTTP_COOKIE"].to_s.split(/;\s*/).each_with_object({}) do |pair, found|
+          name, value = pair.split("=", 2)
+          found[name] ||= value
+        end
+      end
+
+      def editor(env, _token, claims)
+        marked = marking_request?(env)
+        ::DialectoRails.live_marking = marked
+        response = begin
+          @app.call(env)
+        ensure
+          ::DialectoRails.live_marking = false
+        end
+        marked ? finish(env, response, claims["exp"]) : response
+      end
+
+      def visitor_with_stale_cookie(env)
+        status, headers, body = @app.call(env)
+        headers = headers.dup
+        add_set_cookie(headers, "#{COOKIE}=; path=/; max-age=0; expires=Thu, 01 Jan 1970 00:00:00 GMT; secure; httponly; samesite=lax")
+        [status, headers, body]
+      end
+
+      # Navigations (a document or an iframe) and Turbo-style visits (a same-origin fetch that asks for HTML),
+      # never forms, cross-site fetches or JSON.
+      def marking_request?(env)
+        %w[GET HEAD].include?(env["REQUEST_METHOD"]) && navigation?(env) &&
+          env["HTTP_ACCEPT"].to_s.include?("text/html") && path_allowed?(env["PATH_INFO"].to_s)
+      end
+
+      def navigation?(env)
+        case env["HTTP_SEC_FETCH_DEST"]
+        when "document", "iframe" then true
+        when "empty" then env["HTTP_SEC_FETCH_SITE"] == "same-origin"
+        else false
+        end
+      end
+
+      def path_allowed?(path)
+        prefixes = @settings.paths
+        return true if prefixes.nil?
+
+        prefixes.any? do |prefix|
+          base = prefix.chomp("/")
+          path == base || path.start_with?(base + "/")
+        end
+      end
+
+      # The cache headers come first and depend on nothing after them: a marked page must never reach a
+      # shared cache, even when the editor can't be added to it.
+      def finish(env, response, exp)
+        status, headers, body = response
+        headers = headers.dup
+        set_header(headers, "cache-control", "private, no-store")
+        vary_cookie(headers)
+        set_header(headers, "x-robots-tag", "noindex")
+        # A validator from a response with markers must never revalidate another.
+        headers.delete_if { |name, _| name.casecmp?("etag") || name.casecmp?("last-modified") }
+        [status, headers, editor_page(env, headers, body, exp)]
+      end
+
+      # The CSP and the loader. If either fails, the page is served marked and uncached, without the editor.
+      def editor_page(env, headers, body, exp)
+        widen_csp(headers)
+        inject(env, headers, body, exp)
+      rescue => error
+        @logger&.debug("dialecto-rails: editor not added to a marked response (#{error.class})")
+        body
+      end
+
+      # Buffers an HTML page to put the loader before `</head>`; anything else passes through.
+      def inject(env, headers, body, exp)
+        return body unless header(headers, "content-type").to_s.start_with?("text/html") && header(headers, "content-encoding").nil?
+
+        html = +""
+        body.each { |part| html << part.to_s }
+        body.close if body.respond_to?(:close)
+        [with_loader(env, headers, html.force_encoding(Encoding::UTF_8), exp)]
+      end
+
+      # Once the body is buffered, a failure must return the buffer, not the spent body.
+      def with_loader(env, headers, html, exp)
+        at = html.index("</head>")
+        return html unless at
+
+        out = html.dup.insert(at, loader_tag(env, headers, exp))
+        key = headers.keys.find { |name| name.casecmp?("content-length") }
+        headers[key] = out.bytesize.to_s if key
+        out
+      rescue => error
+        @logger&.debug("dialecto-rails: loader not added (#{error.class})")
+        html
+      end
+
+      def loader_tag(env, headers, exp)
+        base = "#{env["SCRIPT_NAME"]}#{PREFIX}"
+        nonce = Csp.script_nonce(header(headers, "content-security-policy"))
+        attributes = {
+          "src" => "#{base}/overlay.js?v=#{DialectoRails::VERSION}",
+          "data-url" => @settings.url,
+          "data-stop" => "#{base}/stop",
+          "data-project" => @settings.repo,
+          "data-exp" => exp.to_s,
+          "nonce" => nonce
+        }.compact.map { |name, value| %( #{name}="#{CGI.escapeHTML(value.to_s)}") }.join
+        "<script defer#{attributes}></script>"
+      end
+
+      def widen_csp(headers)
+        key = headers.keys.find { |name| name.casecmp?("content-security-policy") }
+        return unless key
+
+        origin = Config.normalize_origin(@settings.url) || "https://app.dialecto.eu"
+        headers[key] = Csp.widen_frame_src(headers[key], origin)
+      end
+
+      def vary_cookie(headers)
+        key = headers.keys.find { |name| name.casecmp?("vary") }
+        values = key ? headers[key].to_s.split(",").map(&:strip) : []
+        return if values.include?("*") || values.any? { |value| value.casecmp?("cookie") }
+
+        set_header(headers, "vary", (values + ["Cookie"]).join(", "))
+      end
+
+      ## 3. Stop, the overlay, and the routes that don't exist
+
+      def stop(env)
+        return json(405, error: "method_not_allowed") unless env["REQUEST_METHOD"] == "POST"
+        return json(403, error: "forbidden_origin") unless same_origin?(env)
+
+        headers = {"cache-control" => "no-store", "content-length" => "0"}
+        add_set_cookie(headers, "#{COOKIE}=; path=/; max-age=0; expires=Thu, 01 Jan 1970 00:00:00 GMT; secure; httponly; samesite=lax")
+        [204, headers, []]
+      end
+
+      def same_origin?(env)
+        origin = env["HTTP_ORIGIN"]
+        origin.nil? ? env["HTTP_SEC_FETCH_SITE"] == "same-origin" : origin == @origin
+      end
+
+      def overlay(env)
+        return json(405, error: "method_not_allowed") unless %w[GET HEAD].include?(env["REQUEST_METHOD"])
+        return json(404, error: "not_found") unless File.file?(OVERLAY)
+
+        source = File.binread(OVERLAY)
+        [200, {"content-type" => "text/javascript; charset=utf-8", "cache-control" => "public, max-age=31536000, immutable",
+               "x-content-type-options" => "nosniff", "content-length" => source.bytesize.to_s},
+          [(env["REQUEST_METHOD"] == "HEAD") ? "" : source]]
+      end
+
+      def json(status, body)
+        text = JSON.generate(body)
+        [status, JSON_HEADERS.merge("content-length" => text.bytesize.to_s), [text]]
+      end
+
+      ## Headers
+
+      def header(headers, name)
+        key = headers.keys.find { |candidate| candidate.casecmp?(name) }
+        key && headers[key]
+      end
+
+      def set_header(headers, name, value)
+        headers.delete_if { |key, _| key.casecmp?(name) }
+        headers[name] = value
+      end
+
+      def add_set_cookie(headers, cookie)
+        key = headers.keys.find { |name| name.casecmp?("set-cookie") } || "set-cookie"
+        existing = headers[key]
+        headers[key] =
+          case existing
+          when nil then cookie
+          when Array then existing + [cookie]
+          else "#{existing}\n#{cookie}"
+          end
+      end
+    end
+  end
+end

data/lib/dialecto_rails/in_context/live_runtime.rb

@@ -0,0 +1,53 @@
+require_relative "../config"
+require_relative "../unmarked"
+require_relative "live_store"
+require_relative "key_index"
+require_relative "marking"
+require_relative "backend_hook"
+require_relative "sanitizer"
+require_relative "live_middleware"
+
+module DialectoRails
+  module InContext
+    # The production machinery of live-site editing, built only after the Railtie has checked that live mode
+    # is configured (spec-0025 §4). It holds none of the development pieces: no store of drafts, no git
+    # context, no endpoints.
+    class LiveRuntime
+      # A marked request neither reads nor writes fragments: a cold fragment rendered for an editor would be
+      # cached with its markers and served to every visitor.
+      module NoFragmentCaching
+        def perform_caching = ::DialectoRails.live_marking? ? false : super
+      end
+
+      attr_reader :config, :marking
+
+      def initialize(root:, config:, logger: nil, sanitizer: Sanitizer.build)
+        @config = config
+        @logger = logger
+        index = KeyIndex.new(root: root, catalog_paths: config.catalog_paths)
+        @marking = Marking.new(store: LiveStore.new, index: index, skip_keys: -> { config.skip_keys }, sanitizer: sanitizer)
+      end
+
+      def middleware_options = {settings: config, logger: @logger}
+
+      # Prepends the hook on each file-based backend, gated on the thread's flag so a visitor's lookups take
+      # the plain path.
+      def install_hook(backend = ::I18n.backend)
+        BackendHook.marking = marking
+        BackendHook.logger = @logger
+        BackendHook.gate = -> { ::DialectoRails.live_marking? }
+        ::ActiveSupport.on_load(:action_controller_base) do
+          prepend NoFragmentCaching unless ancestors.include?(NoFragmentCaching)
+        end
+        backends = backend.is_a?(::I18n::Backend::Chain) ? backend.backends : [backend]
+        backends.filter_map do |member|
+          next unless member.is_a?(::I18n::Backend::Simple)
+
+          klass = member.class
+          klass.prepend(BackendHook) unless klass.ancestors.include?(BackendHook)
+          klass
+        end
+      end
+    end
+  end
+end

data/lib/dialecto_rails/in_context/live_store.rb

@@ -0,0 +1,14 @@
+module DialectoRails
+  module InContext
+    # What `Marking` reads in live mode, in the shape of the development `Store`: marking is the rendering
+    # thread's own flag (`DialectoRails.live_marking?`), never a process-wide switch, and there are no saved
+    # drafts. Nothing here can be written to, so nothing a stranger sends can change a visitor's text.
+    class LiveStore
+      def marking? = ::DialectoRails.live_marking?
+
+      def override(_domain, _key, _locale) = nil
+
+      def overrides? = false
+    end
+  end
+end

data/lib/dialecto_rails/in_context/marker.rb

@@ -0,0 +1,106 @@
+require "json"
+
+module DialectoRails
+  module InContext
+    # The in-context marker codec v1 (spec-0016 §3), byte-identical to the overlay's `codec.js`, the Astro
+    # add-on's encoder and `DialectoInContext.Marker`: `OPEN + header + HEADER_END + text + CLOSE`, where
+    # the header is the UTF-8 payload `domain US key US locale` (optionally `RS argsJSON`) with each byte
+    # written as four base-4 digits, most significant first. Every marker codepoint is Default_Ignorable, so
+    # the text renders unchanged. The codepoints are written by number, never as literal invisible characters.
+    module Marker
+      OPEN = [0x2062].pack("U").freeze
+      HEADER_END = [0x2063].pack("U").freeze
+      CLOSE = [0x2064].pack("U").freeze
+      DIGITS = [0x200C, 0x200D, 0x2060, 0x2061].map { |code| [code].pack("U").freeze }.freeze
+      FIELD_SEP = "\u001F".freeze
+      RECORD_SEP = "\u001E".freeze
+
+      DIGIT_VALUES = DIGITS.each_with_index.to_h.freeze
+      Segment = Struct.new(:domain, :key, :locale, :args, :text, :open, keyword_init: true)
+
+      module_function
+
+      # Everything that precedes the marked text: OPEN, the header digits, HEADER_END.
+      def prefix(domain, key, locale, args_json = nil)
+        identity = [domain, key, locale].join(FIELD_SEP)
+        payload = args_json ? identity + RECORD_SEP + args_json : identity
+        digits = payload.b.each_byte.flat_map { |byte| [byte >> 6, (byte >> 4) & 3, (byte >> 2) & 3, byte & 3] }
+        OPEN + digits.map { |digit| DIGITS[digit] }.join + HEADER_END
+      end
+
+      def mark(domain, key, locale, text, args_json = nil)
+        prefix(domain, key, locale, args_json) + text + CLOSE
+      end
+
+      def marked?(text) = text.is_a?(String) && text.include?(OPEN)
+
+      # `text` without markers. Digit codepoints outside a header (a real ZWJ in an emoji) are kept.
+      def strip(text)
+        return text unless text.include?(OPEN) || text.include?(HEADER_END) || text.include?(CLOSE)
+
+        chars = text.chars
+        out = +""
+        index = 0
+        while index < chars.length
+          char = chars[index]
+          if char == OPEN && (header = read_header(chars, index + 1))
+            index = header[:next]
+          elsif char == OPEN || char == HEADER_END || char == CLOSE
+            index += 1
+          else
+            out << char
+            index += 1
+          end
+        end
+        out
+      end
+
+      # Every well-formed marked segment, outer before inner, with its clean text. Malformed headers and
+      # unbalanced CLOSEs are ignored; an OPEN never closed extends to the end and is flagged `open`.
+      def parse(text)
+        chars = text.chars
+        done = []
+        stack = []
+        index = 0
+        while index < chars.length
+          char = chars[index]
+          if char == OPEN && (header = read_header(chars, index + 1))
+            stack << {header: header, order: index, text: +""}
+            index = header[:next]
+          elsif char == CLOSE && !stack.empty?
+            done << segment(stack.pop, false)
+            index += 1
+          else
+            stack.each { |open| open[:text] << char } unless char == HEADER_END
+            index += 1
+          end
+        end
+        (done + stack.reverse.map { |open| segment(open, true) }).sort_by { |entry| entry[:order] }.map { |entry| entry[:segment] }
+      end
+
+      def segment(open, unclosed)
+        identity, _sep, args = open[:header][:payload].partition(RECORD_SEP)
+        domain, key, locale = identity.split(FIELD_SEP, 3)
+        parsed = args.empty? ? nil : (JSON.parse(args) rescue nil)
+        {order: open[:order],
+         segment: Segment.new(domain: domain, key: key, locale: locale, args: parsed, text: strip(open[:text]),
+           open: unclosed)}
+      end
+
+      # The header after an OPEN at `from`: digits up to HEADER_END, a multiple of four of them.
+      def read_header(chars, from)
+        digits = []
+        index = from
+        while index < chars.length && (value = DIGIT_VALUES[chars[index]])
+          digits << value
+          index += 1
+        end
+        return nil unless chars[index] == HEADER_END && (digits.length % 4).zero?
+
+        bytes = digits.each_slice(4).map { |a, b, c, d| (a << 6) | (b << 4) | (c << 2) | d }
+        payload = bytes.pack("C*").force_encoding(Encoding::UTF_8)
+        payload.valid_encoding? ? {payload: payload, next: index + 1} : nil
+      end
+    end
+  end
+end

data/lib/dialecto_rails/in_context/marking.rb

@@ -0,0 +1,122 @@
+require "cgi"
+require_relative "marker"
+require_relative "args"
+
+module DialectoRails
+  module InContext
+    # Turns an I18n lookup's result into a marked string (spec-0023 §7.2, §7.4, §7.5). Pure apart from the
+    # store and index it is given, so it is tested without a Rails app.
+    class Marking
+      CATEGORIES = %i[zero one two few many other].freeze
+      SKIPPED_PREFIXES = %w[date. datetime. time. number. support. i18n.].freeze
+      SKIPPED_SUFFIX = /(\.(url|path|href|format)|_format)\z/
+
+      def initialize(store:, index:, skip_keys: -> { [] }, fallbacks: nil, sanitizer: nil)
+        @store = store
+        @index = index
+        @skip_keys = skip_keys
+        @fallbacks = fallbacks || method(:i18n_fallbacks)
+        @sanitizer = sanitizer
+      end
+
+      # `plural` is `[entry, chosen_text]` recorded by the pluralize wrapper, or nil.
+      def call(locale, key, options, result, plural)
+        return result unless @store.marking? && result.is_a?(String) && !result.start_with?(Marker::OPEN)
+        return result if key.is_a?(Array) || key.nil?
+
+        absolute = absolute_key(locale, key, options)
+        return result if absolute.empty? || skipped?(absolute)
+
+        found_locale, domain = resolve(locale, absolute)
+        return result unless domain
+
+        form, count = plural_form(options, plural)
+        html = html_key?(absolute) || safe?(result)
+        text = draft(domain, absolute, found_locale, options, form, html) || result
+        extras = {}
+        extras["__n"] = count if form
+        extras["__form"] = form if form
+        extras["__html"] = true if html_key?(absolute)
+        marked = Marker.mark(domain, absolute, found_locale, text, Args.json(options, extras))
+        safe?(result) && marked.respond_to?(:html_safe) ? marked.html_safe : marked
+      end
+
+      def absolute_key(locale, key, options)
+        parts = ::I18n.normalize_keys(locale, key, options[:scope], options[:separator] || ::I18n.default_separator)
+        parts.drop(1).join(".")
+      end
+
+      def skipped?(absolute)
+        SKIPPED_PREFIXES.any? { |prefix| absolute.start_with?(prefix) } || absolute.match?(SKIPPED_SUFFIX) ||
+          @skip_keys.call.any? { |pattern| skip_match?(pattern, absolute) }
+      end
+
+      def html_key?(absolute) = absolute.end_with?("_html") || absolute.split(".").last == "html"
+
+      private
+
+      # The first of the locale and its fallbacks whose files hold the key, so a page showing English
+      # fallback text is marked `en`.
+      def resolve(locale, absolute)
+        candidates = [locale.to_s] + Array(@fallbacks.call(locale)).map(&:to_s)
+        candidates.uniq.each do |candidate|
+          domain = @index.domain(candidate, absolute)
+          return [candidate, domain] if domain
+        end
+        nil
+      end
+
+      def i18n_fallbacks(locale)
+        ::I18n.respond_to?(:fallbacks) ? ::I18n.fallbacks[locale] : []
+      end
+
+      # The index of the chosen category among the entry's categories in canonical order (what the sidebar
+      # lists for the plural), and the count.
+      def plural_form(options, plural)
+        return nil unless options.key?(:count) && plural
+
+        entry, chosen = plural
+        categories = CATEGORIES.select { |category| entry.key?(category) || entry.key?(category.to_s) }
+        chosen_key = entry.find { |_name, value| value.equal?(chosen) }&.first ||
+          entry.find { |_name, value| value == chosen }&.first
+        index = categories.index(chosen_key&.to_sym)
+        index ? [index, options[:count]] : nil
+      end
+
+      # A draft is not yet reviewed, and may come from another person in the org. Where the page will treat the
+      # text as HTML (an `_html` key, or a result that is already html_safe) it is sanitized after
+      # interpolation, and escaped when there is no sanitizer: it fails closed.
+      def draft(domain, absolute, locale, options, form, html)
+        override = @store.override(domain, absolute, locale)
+        return nil unless override
+
+        template = form && override[:forms] ? override[:forms][form] : override[:to]
+        template ||= override[:forms]&.first
+        return nil unless template
+
+        values = options.reject { |name, _value| Args::RESERVED.include?(name) }
+        text = begin
+          ::I18n.interpolate(template, values)
+        rescue ::I18n::ArgumentError
+          template
+        end
+        html ? clean_html(text) : text
+      end
+
+      def clean_html(text)
+        @sanitizer ? @sanitizer.call(text).to_s : CGI.escapeHTML(text)
+      rescue StandardError
+        CGI.escapeHTML(text)
+      end
+
+      def safe?(result) = result.respond_to?(:html_safe?) && result.html_safe?
+
+      def skip_match?(pattern, absolute)
+        case pattern
+        when Regexp then pattern.match?(absolute)
+        else Regexp.new("\\A" + Regexp.escape(pattern.to_s).gsub("\\*", ".*") + "\\z").match?(absolute)
+        end
+      end
+    end
+  end
+end