dialecto-rails 0.1.0

data/lib/dialecto_rails/in_context/middleware.rb

@@ -0,0 +1,202 @@
+require "json"
+require "ipaddr"
+require "cgi"
+require_relative "overrides"
+require_relative "../version"
+
+module DialectoRails
+  module InContext
+    # The dev server's side of the in-context editor (spec-0023 §7.6; spec-0017 §1.4 for the endpoints). Pure
+    # Rack, inserted at position 0, so it sees every request and every response.
+    #
+    # Loopback only, by two independent checks: the socket's peer (`REMOTE_ADDR`, never `X-Forwarded-For`)
+    # must be a loopback address, and the `Host` must be `localhost`, `127.0.0.1` or `[::1]`, which also
+    # defeats DNS rebinding. A POST must carry this site's own `Origin`; a foreign `Origin` or
+    # `Sec-Fetch-Site: cross-site` is refused.
+    class Middleware
+      PREFIX = "/__dialecto".freeze
+      MAX_BODY = 256 * 1024
+      LOOPBACK_HOSTS = %w[localhost 127.0.0.1 [::1] ::1].freeze
+      LOOPBACK_NETS = [IPAddr.new("127.0.0.0/8"), IPAddr.new("::1"), IPAddr.new("::ffff:127.0.0.0/104")].freeze
+      JSON_HEADERS = {"content-type" => "application/json", "cache-control" => "no-store"}.freeze
+
+      # `settings`: url, url_valid?, project, paths (array or nil), catalogs. `store`, `git_context`: the
+      # runtime's. `logger` may be nil.
+      def initialize(app, settings:, store:, git_context:, logger: nil)
+        @app = app
+        @settings = settings
+        @store = store
+        @git_context = git_context
+        @logger = logger
+      end
+
+      def call(env)
+        path = env["PATH_INFO"].to_s
+        return endpoint(env, path.delete_prefix(PREFIX)) if path == PREFIX || path.start_with?(PREFIX + "/")
+
+        response = @app.call(env)
+        document_request?(env) && path_allowed?(path) ? inject(env, response) : response
+      end
+
+      private
+
+      ## Endpoints
+
+      def endpoint(env, route)
+        case route
+        when "/context" then context(env)
+        when "/overrides" then post(env) { |payload| overrides(payload) }
+        when "/marking" then post(env) { |payload| marking(payload) }
+        else json(404, error: "not_found")
+        end
+      rescue => error
+        @logger&.debug("dialecto-rails: endpoint failed (#{error.class})")
+        json(500, error: "internal")
+      end
+
+      def context(env)
+        return json(405, error: "method_not_allowed") unless %w[GET HEAD].include?(env["REQUEST_METHOD"])
+        return json(403, error: "forbidden_origin") unless read_allowed?(env)
+
+        json(200, @git_context.read)
+      end
+
+      def post(env)
+        return json(405, error: "method_not_allowed") unless env["REQUEST_METHOD"] == "POST"
+        return json(403, error: "forbidden_origin") unless write_allowed?(env)
+
+        body = env["rack.input"]&.read(MAX_BODY + 1).to_s
+        return json(413, error: "too_large") if body.bytesize > MAX_BODY
+
+        payload = begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          return json(400, error: "invalid_json")
+        end
+        status, result = yield payload
+        json(status, result)
+      end
+
+      def overrides(payload)
+        parsed = Overrides.parse(payload)
+        return [400, {error: "invalid_edits"}] unless parsed
+
+        @store.replace_overrides(parsed.applied)
+        [200, {ok: true, applied: parsed.applied.length, ignored: parsed.ignored}]
+      end
+
+      def marking(payload)
+        on = payload.is_a?(Hash) ? payload["on"] : nil
+        return [400, {error: "invalid_marking"}] unless on == true || on == false
+
+        [200, {ok: true, on: @store.set_marking(on), ttl_ms: @store.marking_ttl_ms}]
+      end
+
+      def json(status, body)
+        text = JSON.generate(body)
+        [status, JSON_HEADERS.merge("content-length" => text.bytesize.to_s), [text]]
+      end
+
+      ## Who may call
+
+      def read_allowed?(env)
+        loopback?(env) && origin_ok?(env, required: false) && [nil, "same-origin"].include?(env["HTTP_SEC_FETCH_SITE"])
+      end
+
+      def write_allowed?(env)
+        loopback?(env) && origin_ok?(env, required: true) && env["HTTP_SEC_FETCH_SITE"] != "cross-site"
+      end
+
+      def loopback?(env) = LOOPBACK_HOSTS.include?(host(env)) && loopback_peer?(env)
+
+      # `Host` is the client's to choose, so the peer address must be loopback too: a LAN peer of a server
+      # bound to 0.0.0.0 can send `Host: localhost`.
+      def loopback_peer?(env)
+        address = IPAddr.new(env["REMOTE_ADDR"].to_s)
+        LOOPBACK_NETS.any? { |net| net.family == address.family && net.include?(address) }
+      rescue IPAddr::Error
+        false
+      end
+
+      def host(env)
+        value = (env["HTTP_HOST"] || env["SERVER_NAME"]).to_s.downcase
+        value.start_with?("[") ? value[/\A\[[^\]]*\]/].to_s : value.sub(/:\d+\z/, "")
+      end
+
+      def origin_ok?(env, required:)
+        origin = env["HTTP_ORIGIN"]
+        return !required if origin.nil?
+
+        origin == "#{env["rack.url_scheme"] || "http"}://#{env["HTTP_HOST"]}"
+      end
+
+      ## The loader
+
+      def document_request?(env)
+        env["REQUEST_METHOD"] == "GET" && @settings.url_valid? && loopback?(env) &&
+          [nil, "document"].include?(env["HTTP_SEC_FETCH_DEST"]) &&
+          env["HTTP_X_REQUESTED_WITH"].to_s.empty? && env["HTTP_TURBO_FRAME"].to_s.empty?
+      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
+
+      def inject(env, response)
+        status, headers, body = response
+        return response unless html?(headers) && header(headers, "content-encoding").nil?
+
+        html = +""
+        body.each { |part| html << part.to_s }
+        body.close if body.respond_to?(:close)
+        html.force_encoding(Encoding::UTF_8)
+        add_loader(env, status, headers, html)
+      end
+
+      # Never breaks the page: any failure here returns the buffered document as it was.
+      def add_loader(env, status, headers, html)
+        at = html.index("</head>")
+        return [status, headers, [html]] unless at
+
+        out = html.dup.insert(at, loader_tag(env, headers))
+        headers = headers.dup
+        key = headers.keys.find { |name| name.casecmp?("content-length") }
+        headers[key] = out.bytesize.to_s if key
+        [status, headers, [out]]
+      rescue => error
+        @logger&.debug("dialecto-rails: loader skipped (#{error.class})")
+        [status, headers, [html]]
+      end
+
+      def html?(headers) = header(headers, "content-type").to_s.start_with?("text/html")
+
+      def header(headers, name)
+        key = headers.keys.find { |candidate| candidate.casecmp?(name) }
+        key && headers[key]
+      end
+
+      def loader_tag(env, headers)
+        base = "#{env["SCRIPT_NAME"]}#{PREFIX}"
+        csp = header(headers, "content-security-policy").to_s + header(headers, "content-security-policy-report-only").to_s
+        nonce = csp[/'nonce-([A-Za-z0-9+\/=_-]+)'/, 1]
+        attributes = {
+          "src" => @settings.url + "/assets/in-context/overlay.js",
+          "data-url" => @settings.url,
+          "data-context" => base + "/context",
+          "data-overrides" => base + "/overrides",
+          "data-marking" => base + "/marking",
+          "data-project" => @settings.project,
+          "nonce" => nonce
+        }.compact.map { |name, value| %( #{name}="#{CGI.escapeHTML(value.to_s)}") }.join
+        # Deferred: the page renders even when Dialecto is slow or unreachable.
+        "<script defer#{attributes}></script>"
+      end
+    end
+  end
+end

data/lib/dialecto_rails/in_context/overrides.rb

@@ -0,0 +1,61 @@
+module DialectoRails
+  module InContext
+    # The saved-drafts payload the overlay posts to `/__dialecto/overrides` (spec-0017 §1.2):
+    # `{edits: [{domain, key, locale, to}]}`, where a plural entry carries `forms: [text, …]` (in the entry's
+    # categories in canonical order, matching a marker's `__form`) instead of, or beside, `to`.
+    module Overrides
+      MAX_EDITS = 5_000
+      MAX_TEXT = 20_000
+      MAX_KEY = 20_000
+      MAX_FORMS = 10
+      LOCALE = /\A[a-z]{2,3}([-_][A-Za-z0-9]{2,8})*\z/
+
+      Result = Struct.new(:applied, :ignored, keyword_init: true)
+
+      module_function
+
+      # A Result, or nil when the payload isn't a well-formed edit list.
+      def parse(payload)
+        edits = payload.is_a?(Hash) ? payload["edits"] : nil
+        return nil unless edits.is_a?(Array) && edits.length <= MAX_EDITS
+
+        applied = []
+        ignored = 0
+        edits.each do |edit|
+          case (entry = edit_entry(edit))
+          when :error then return nil
+          when :ignored then ignored += 1
+          else applied << entry
+          end
+        end
+        Result.new(applied: applied, ignored: ignored)
+      end
+
+      def edit_entry(edit)
+        return :error unless edit.is_a?(Hash)
+
+        domain, key, locale = edit.values_at("domain", "key", "locale")
+        return :error unless [domain, key, locale].all?(String)
+        return :error unless domain.length <= 512 && !key.empty? && key.length <= MAX_KEY && locale.length <= 64
+
+        override = override_for(edit["to"], edit["forms"])
+        return :error unless override
+
+        locale.match?(LOCALE) ? {domain: domain, key: key, locale: locale, override: override} : :ignored
+      end
+
+      def override_for(to, forms)
+        return nil unless to.nil? || (to.is_a?(String) && to.length <= MAX_TEXT)
+        return nil unless forms.nil? || forms?(forms)
+        return nil if to.nil? && forms.nil?
+
+        {to: to, forms: forms}.compact
+      end
+
+      def forms?(forms)
+        forms.is_a?(Array) && !forms.empty? && forms.length <= MAX_FORMS &&
+          forms.all? { |form| form.is_a?(String) && form.length <= MAX_TEXT }
+      end
+    end
+  end
+end

data/lib/dialecto_rails/in_context/railtie_stub.rb

@@ -0,0 +1,76 @@
+module DialectoRails
+  # The Rails integration (spec-0023 §7.1). This file is all a production process loads: every initializer
+  # begins with a guard, and the in-context code is required only after one passes.
+  class Railtie < ::Rails::Railtie
+    config.dialecto = ActiveSupport::OrderedOptions.new
+
+    # The development guard: development only, so test, staging and any custom environment get nothing, and
+    # the environment or `config.dialecto.enabled = false` can switch it off. The mode may also say `:live` or
+    # `:off`; unset it is `:dev` here.
+    def self.active?(app)
+      return false unless ::Rails.env.development?
+
+      require "dialecto_rails/config"
+      config = DialectoRails::Config.new(app.config.dialecto.to_h)
+      config.enabled? && config.mode(:dev) == :dev
+    end
+
+    # The live guard (spec-0025 §4): any environment, but only when `mode` is `:live` and the repo, origin and
+    # public key are set. Unset, the mode is `:off` outside development, so a production app is inert until its
+    # config says otherwise.
+    def self.live?(app)
+      require "dialecto_rails/config"
+      DialectoRails::Config.new(app.config.dialecto.to_h).live?(:off)
+    end
+
+    initializer "dialecto_rails.middleware" do |app|
+      next unless DialectoRails::Railtie.active?(app)
+
+      require "dialecto_rails/in_context/runtime"
+      runtime = DialectoRails::InContext::Runtime.new(
+        root: app.root, config: DialectoRails::Config.new(app.config.dialecto.to_h), logger: ::Rails.logger
+      )
+      app.config.dialecto.runtime = runtime
+      app.middleware.insert_before 0, DialectoRails::InContext::Middleware, **runtime.middleware_options
+    end
+
+    initializer "dialecto_rails.live_middleware" do |app|
+      unless DialectoRails::Railtie.live?(app)
+        problems = DialectoRails::Config.new(app.config.dialecto.to_h).live_problems(:off)
+        unless problems.empty?
+          ::Rails.logger&.warn("dialecto-rails: mode :live stays off: #{problems.join("; ")}")
+        end
+        next
+      end
+
+      # The launch token travels in the URL of the first request; keep it out of the request log.
+      app.config.filter_parameters += [:dialecto_edit]
+
+      require "dialecto_rails/in_context/live_runtime"
+      runtime = DialectoRails::InContext::LiveRuntime.new(
+        root: app.root, config: DialectoRails::Config.new(app.config.dialecto.to_h), logger: ::Rails.logger
+      )
+      app.config.dialecto.live_runtime = runtime
+      # After the session middleware, which the middleware reads and writes; an API-only app has none.
+      if defined?(::ActionDispatch::Flash) && !app.config.api_only
+        app.middleware.insert_before ::ActionDispatch::Flash, DialectoRails::InContext::LiveMiddleware, **runtime.middleware_options
+      else
+        app.middleware.use DialectoRails::InContext::LiveMiddleware, **runtime.middleware_options
+      end
+    end
+
+    config.after_initialize do |app|
+      if DialectoRails::Railtie.active?(app) && (runtime = app.config.dialecto.runtime)
+        runtime.install_hook
+        runtime.allow_overlay_in([app.config.content_security_policy, app.config.content_security_policy_report_only]
+          .select { |policy| policy.respond_to?(:directives) })
+        if app.config.action_controller.perform_caching
+          ::Rails.logger.warn("dialecto-rails: fragment caching is on, so cached fragments carry no markers. " \
+            "Run `bin/rails dev:cache` to turn it off while editing.")
+        end
+      elsif (runtime = app.config.dialecto.live_runtime)
+        runtime.install_hook
+      end
+    end
+  end
+end

data/lib/dialecto_rails/in_context/runtime.rb

@@ -0,0 +1,52 @@
+require_relative "../config"
+require_relative "store"
+require_relative "key_index"
+require_relative "marking"
+require_relative "git_context"
+require_relative "backend_hook"
+require_relative "sanitizer"
+require_relative "middleware"
+require_relative "csp"
+
+module DialectoRails
+  module InContext
+    # The development-only machinery, built once the Railtie's guard has passed (spec-0023 §7.1).
+    # Nothing in this folder is required before that, so a production process holds none of it.
+    class Runtime
+      attr_reader :config, :store, :index, :marking, :git_context
+
+      def self.html_sanitizer = Sanitizer.build
+
+      def initialize(root:, config:, logger: nil, sanitizer: self.class.html_sanitizer)
+        @config = config
+        @logger = logger
+        @store = Store.new
+        @index = KeyIndex.new(root: root, catalog_paths: config.catalog_paths)
+        @marking = Marking.new(store: @store, index: @index, skip_keys: -> { config.skip_keys }, sanitizer: sanitizer)
+        @git_context = GitContext.new(root: root, project: config.project, catalogs: config.catalogs)
+      end
+
+      def middleware_options = {settings: config, store: store, git_context: git_context, logger: @logger}
+
+      # Prepends the hook on the class of each file-based backend. Returns the classes hooked.
+      def install_hook(backend = ::I18n.backend)
+        BackendHook.marking = marking
+        BackendHook.logger = @logger
+        backends = backend.is_a?(::I18n::Backend::Chain) ? backend.backends : [backend]
+        backends.filter_map do |member|
+          unless member.is_a?(::I18n::Backend::Simple)
+            @logger&.info("dialecto-rails: in-context editing skipped #{member.class}: it isn't a file backend")
+            next
+          end
+          klass = member.class
+          klass.prepend(BackendHook) unless klass.ancestors.include?(BackendHook)
+          klass
+        end
+      end
+
+      def allow_overlay_in(policies)
+        policies.each { |policy| Csp.allow(policy, config.url) if policy }
+      end
+    end
+  end
+end

data/lib/dialecto_rails/in_context/sanitizer.rb

@@ -0,0 +1,19 @@
+module DialectoRails
+  module InContext
+    # The safe-list sanitizer for `_html` drafts. ActionView depends on rails-html-sanitizer, but loads it
+    # lazily, so it is required here rather than found by `defined?`; if it can't load, the marking escapes
+    # drafts instead (it fails closed).
+    module Sanitizer
+      module_function
+
+      def build
+        require "rails-html-sanitizer"
+        klass = defined?(::Rails::HTML5::SafeListSanitizer) ? ::Rails::HTML5::SafeListSanitizer : ::Rails::Html::SafeListSanitizer
+        sanitizer = klass.new
+        ->(text) { sanitizer.sanitize(text) }
+      rescue LoadError, NameError
+        nil
+      end
+    end
+  end
+end

data/lib/dialecto_rails/in_context/store.rb

@@ -0,0 +1,41 @@
+module DialectoRails
+  module InContext
+    # The dev server's in-context state: whether marking is on (spec-0017 §1.3) and the saved drafts the
+    # overlay sent (§1.2). Marking lasts `MARKING_TTL_MS` after the last `set_marking(true)`: the overlay
+    # heartbeats while the editor is open, so a closed tab or a crashed overlay can't leave markers on.
+    class Store
+      MARKING_TTL_MS = 90_000
+
+      def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) })
+        @clock = clock
+        @mutex = Mutex.new
+        @marking_until = nil
+        @overrides = {}.freeze
+      end
+
+      def marking_ttl_ms = MARKING_TTL_MS
+
+      def marking?
+        until_ms = @marking_until
+        !until_ms.nil? && until_ms > @clock.call
+      end
+
+      def set_marking(on, ttl_ms = MARKING_TTL_MS)
+        @mutex.synchronize { @marking_until = on ? @clock.call + ttl_ms : nil }
+        on
+      end
+
+      # The draft for `{domain, key, locale}`, or nil: `{to: String}` and/or `{forms: [String]}`.
+      def override(domain, key, locale) = @overrides[[domain, key, locale]]
+
+      def overrides? = !@overrides.empty?
+
+      # Replaces every draft: the overlay always sends the full set, so an empty list restores the catalogs.
+      def replace_overrides(entries)
+        table = entries.to_h { |entry| [[entry[:domain], entry[:key], entry[:locale]], entry[:override]] }.freeze
+        @mutex.synchronize { @overrides = table }
+        nil
+      end
+    end
+  end
+end

data/lib/dialecto_rails/scan/catalogs.rb

@@ -0,0 +1,46 @@
+module DialectoRails
+  module Scan
+    # Which files are catalogs: the project's catalog paths, matched the way Dialecto matches them
+    # (ADR-0020): `**` spans folders, `*` stays in one folder or file name, `?` is one character, and no
+    # wildcard reaches a folder or file whose name starts with a dot.
+    class Catalogs
+      def initialize(patterns)
+        @patterns = patterns.map { |pattern| pattern.split("/") }
+      end
+
+      def match?(path)
+        segments = path.split("/")
+        @patterns.any? { |pattern| match_segments?(pattern, segments) }
+      end
+
+      private
+
+      def match_segments?(pattern, path)
+        return path.empty? if pattern.empty?
+
+        head, *rest = pattern
+        if head == "**"
+          (0..path.length).any? do |taken|
+            path.first(taken).none? { |segment| segment.start_with?(".") } &&
+              match_segments?(rest, path.drop(taken))
+          end
+        else
+          !path.empty? && match_segment?(head, path.first) && match_segments?(rest, path.drop(1))
+        end
+      end
+
+      def match_segment?(pattern, segment)
+        return false if segment.start_with?(".") && pattern.start_with?("*", "?")
+
+        regex = pattern.each_char.map do |char|
+          case char
+          when "*" then "[^/]*"
+          when "?" then "[^/]"
+          else Regexp.escape(char)
+          end
+        end.join
+        Regexp.new("\\A#{regex}\\z").match?(segment)
+      end
+    end
+  end
+end