wurk 0.0.5 → 1.0.0

data/lib/wurk/web/config.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'forwardable'
+require 'rack/builder'
+
 module Wurk
   class Web
     # Web UI configuration. Holds the authorization callback documented in
@@ -22,25 +25,87 @@ module Wurk
     # When no block is registered, every request is authorized (matches
     # Sidekiq's default — no auth until the user opts in).
     class Config
+      extend Forwardable
+
       # String forms that mean "off" — so `config.web.read_only = ENV[...]`
       # doesn't flip on when the env var is "0"/"false"/empty.
       FALSEY_STRINGS = ['', '0', 'false', 'no', 'off'].freeze
 
+      # Firefox-profiler endpoints for the Profiles pane (spec §25.2). The
+      # dashboard uploads a stored profile to `profile_store_url` and redirects
+      # the operator to `profile_view_url % <returned-hash>`. Overridable for
+      # self-hosted profiler instances.
+      PROFILE_VIEW_URL  = 'https://profiler.firefox.com/public/%s'
+      PROFILE_STORE_URL = 'https://api.profiler.firefox.com/compressed-store'
+
+      # Hash-style settings, same surface as Sidekiq::Web::Config (#204):
+      # gems and apps write `Sidekiq::Web.configure { |c| c[:csrf] = false }`.
+      # Seeded like upstream's OPTIONS; unknown keys are stored verbatim so a
+      # setting wurk doesn't consume still round-trips (e.g. :csrf — wurk's
+      # extension POST guard is the Sec-Fetch-Site check in
+      # ExtensionsController, spec §25.1, not a token).
+      OPTIONS = {
+        profile_view_url: PROFILE_VIEW_URL,
+        profile_store_url: PROFILE_STORE_URL
+      }.freeze
+
+      # Sidekiq's built-in dashboard tabs (spec §25.3). The `tabs` hash starts
+      # as a copy of this; extensions add to it via `register_extension` or by
+      # mutating `tabs` directly — the same surface third-party gems use.
+      DEFAULT_TABS = {
+        'Dashboard' => '', 'Busy' => 'busy', 'Queues' => 'queues',
+        'Retries' => 'retries', 'Scheduled' => 'scheduled', 'Dead' => 'morgue',
+        'Metrics' => 'metrics', 'Profiles' => 'profiles'
+      }.freeze
+
+      # Tab paths the SPA already renders natively (Sidekiq DEFAULT_TABS plus
+      # wurk's Pro/Ent extras). A gem re-registering one of these — e.g.
+      # sidekiq-cron's "cron" — must not produce a duplicate nav item, so
+      # `custom_tabs` filters them out.
+      NATIVE_TAB_PATHS = %w[
+        busy queues retries scheduled dead morgue metrics profiles
+        batches limiters cron search
+      ].freeze
+
       # Host-app Rack middleware stacked in front of the dashboard, newest
-      # last. Each entry is `[middleware, args, block]`. Returns a frozen copy
-      # so the memoized chain (`#rack_app`) can only be invalidated through
-      # `#use` — direct mutation can't silently desync it.
-      def middlewares
-        @middlewares.dup.freeze
-      end
+      # last. Each entry is `[middleware, args, block]`. The LIVE array, like
+      # Sidekiq::Web::Config#middlewares — callers mutate it directly
+      # (sidekiq-cron's tests do `c.middlewares.clear`), so `#rack_app`
+      # detects drift instead of this returning a frozen copy.
+      attr_reader :middlewares
 
       def initialize
+        @options = OPTIONS.dup
         @authorization = nil
         @read_only = env_read_only?
+        @read_only_message = nil
         @middlewares = []
         @rack_app = nil
+        init_extensions!
+      end
+
+      def_delegators :@options, :[], :[]=, :fetch, :key?, :has_key?, :merge!, :dig
+
+      # Firefox-profiler URLs — named views over the same @options keys the
+      # bracket surface exposes, so `c[:profile_view_url] = …` and
+      # `c.profile_view_url = …` can't drift apart.
+      def profile_view_url  = @options[:profile_view_url]
+      def profile_store_url = @options[:profile_store_url]
+
+      def profile_view_url=(value)
+        @options[:profile_view_url] = value
+      end
+
+      def profile_store_url=(value)
+        @options[:profile_store_url] = value
       end
 
+      # Optional banner copy shown by the dashboard in read-only mode. Nil →
+      # the SPA falls back to its localized default ("Read-only mode"). Lets a
+      # host explain *why* it's read-only — e.g. the public demo sets
+      # "This is a public demo — actions are disabled."
+      attr_accessor :read_only_message
+
       # Registers a `(env, method, path) -> truthy/falsey` block. Re-calling
       # overwrites; the spec exposes a single hook, not a chain.
       def authorization(&block)
@@ -48,6 +113,77 @@ module Wurk
         @authorization
       end
 
+      # Web-extension surface (spec §25.2). Third-party gems (sidekiq-cron,
+      # sidekiq-unique-jobs, sidekiq-status, …) register dashboard tabs at load
+      # time. `tabs` is a mutable name→path hash seeded from DEFAULT_TABS;
+      # `custom_job_info_rows` collects callables that add rows to the job
+      # detail view; `app_url` / `assets_path` mirror Sidekiq's accessors.
+      # `locales` is the mutable locale-directory list extensions append to
+      # (`Sidekiq::Web.configure.locales << dir`) — the Extension renderer's
+      # `t()` reads en.yml from every listed dir. Wurk's own SPA i18n is
+      # separate, so it starts empty.
+      attr_reader :tabs, :extensions, :locales
+      attr_accessor :custom_job_info_rows, :app_url, :assets_path
+
+      # Matches Sidekiq::Web::Config#register_extension (aliased `register`,
+      # spec §25.2): `tab` is the label(s), `index` the path(s), `name` the
+      # asset namespace. `tab`/`index` are zipped into the `tabs` hash
+      # (label => path) so the tab surfaces in the SPA nav via /api/meta, and
+      # the extension's `registered(app)` routes/ERB views are served by
+      # Wurk::Web::Extension::Renderer under `ext/:name/*` (#187) — the SPA's
+      # Extension page embeds the rendered HTML. Yields self to an optional
+      # block for further config, and returns self.
+      # rubocop:disable Metrics/ParameterLists -- signature matches Sidekiq::Web::Config#register_extension (spec §25.2)
+      def register_extension(extension, name:, tab:, index:, root_dir: nil,
+                             cache_for: 86_400, asset_paths: nil)
+        Array(tab).zip(Array(index)).each { |label, path| @tabs[label] = path if label }
+        # Upstream registers root_dir/locales automatically; extensions
+        # without a root_dir append their dir to `locales` themselves.
+        @locales << ::File.join(root_dir, 'locales') if root_dir
+        @extensions << {
+          extension: extension, name: name, tab: tab, index: index,
+          root_dir: root_dir, cache_for: cache_for, asset_paths: asset_paths
+        }
+        yield self if block_given?
+        self
+      end
+      # rubocop:enable Metrics/ParameterLists
+      alias register register_extension
+
+      # Tabs the SPA should render in the nav: everything registered beyond the
+      # Sidekiq defaults and wurk's own native pages, as `{ name:, path:,
+      # ext_name: }`. `ext_name` ties the tab back to a registered extension so
+      # the Extension page can fetch its server-rendered view from
+      # `ext/:ext_name/*`; nil for tabs added by bare `tabs[]=` mutation (the
+      # SPA falls back to the iframe embed for those).
+      def custom_tabs
+        @tabs.filter_map do |name, path|
+          # Same trailing-slash normalization as extension_for_index, so a
+          # native path registered as "cron/" doesn't duplicate the native tab.
+          next if DEFAULT_TABS.key?(name) || NATIVE_TAB_PATHS.include?(path.to_s.delete_suffix('/'))
+
+          { name: name, path: path.to_s, ext_name: extension_for_index(path)&.dig(:name)&.to_s }
+        end
+      end
+
+      # The registered extension whose `index` covers `path` ("locks/" and
+      # "locks" are the same index).
+      def extension_for_index(path)
+        norm = path.to_s.delete_suffix('/')
+        @extensions.find { |e| Array(e[:index]).any? { |i| i.to_s.delete_suffix('/') == norm } }
+      end
+
+      # Evaluate the registered `custom_job_info_rows` against a job (spec
+      # §25.2), returning `[[label, value], …]` for the SPA's job-detail modal.
+      # Each row is a callable (`call(job)`) or a Sidekiq-style `add_pair(job)`
+      # object; a row that raises or returns a non-pair is skipped so one bad
+      # extension can't break the job views.
+      def job_info_pairs(job)
+        return [] if @custom_job_info_rows.empty?
+
+        @custom_job_info_rows.filter_map { |row| job_info_pair(row, job) }
+      end
+
       # Sidekiq-compatible (`Sidekiq::Web.use`). Registers a Rack middleware
       # that wraps the dashboard, in front of the authorization hook, so a
       # host app can gate the UI with Devise/Warden/Sorcery/Rack::Auth::Basic
@@ -59,17 +195,21 @@ module Wurk
         @rack_app = nil
       end
 
-      # Builds (once) the host-middleware chain wrapping `inner` and memoizes
-      # it on this Config. `reset_config!` swaps in a fresh Config, so each
-      # test rebuilds cleanly; production builds exactly once at boot.
+      # Builds the host-middleware chain wrapping `inner`, memoized against
+      # the middleware list it was built from — `middlewares` is the live
+      # array (upstream surface), so direct mutation after the first request
+      # triggers a rebuild instead of silently serving the stale chain.
+      # Production builds exactly once at boot; the per-request comparison is
+      # an == over a handful of entries.
       def rack_app(inner)
-        @rack_app ||= begin
-          stack = @middlewares
-          ::Rack::Builder.new do
-            stack.each { |middleware, args, block| use(middleware, *args, &block) }
-            run inner
-          end.to_app
-        end
+        return @rack_app if @rack_app && @rack_app_stack == @middlewares
+
+        @rack_app_stack = @middlewares.dup
+        stack = @middlewares
+        @rack_app = ::Rack::Builder.new do
+          stack.each { |middleware, args, block| use(middleware, *args, &block) }
+          run inner
+        end.to_app
       end
 
       # Read-only mode. When on, the Authorization middleware blocks every
@@ -86,10 +226,13 @@ module Wurk
       end
 
       def reset!
+        @options = OPTIONS.dup
         @authorization = nil
         @read_only = env_read_only?
+        @read_only_message = nil
         @middlewares = []
         @rack_app = nil
+        init_extensions!
       end
 
       # Returns true when no block is registered, otherwise the block's
@@ -107,6 +250,30 @@ module Wurk
       def env_read_only?
         ENV['WURK_WEB_READ_ONLY'] == '1'
       end
+
+      def init_extensions!
+        @tabs = DEFAULT_TABS.dup
+        @extensions = []
+        @locales = []
+        @custom_job_info_rows = []
+        @app_url = nil
+        @assets_path = nil
+      end
+
+      def job_info_pair(row, job)
+        pair = job_info_row_value(row, job)
+        return unless pair.is_a?(::Array) && pair.size == 2
+
+        [pair[0].to_s, pair[1].to_s]
+      rescue ::StandardError
+        nil
+      end
+
+      def job_info_row_value(row, job)
+        return row.call(job) if row.respond_to?(:call)
+
+        row.add_pair(job) if row.respond_to?(:add_pair)
+      end
     end
 
     class << self
@@ -114,8 +281,11 @@ module Wurk
         @config ||= Config.new
       end
 
+      # With a block: yields the config (the documented configure form).
+      # Without: returns it — upstream's blockless-getter form, which gems
+      # use as `Sidekiq::Web.configure.tabs` (#204).
       def configure
-        yield config
+        block_given? ? yield(config) : config
       end
 
       # Class-level shorthand for `config.use` — mirrors `Sidekiq::Web.use`.
@@ -123,6 +293,38 @@ module Wurk
         config.use(...)
       end
 
+      # Class-level extension surface — gems call these straight off
+      # `Sidekiq::Web` (e.g. `Sidekiq::Web.register(Ext, name:, tab:)` or
+      # `Sidekiq::Web.tabs["Locks"] = "locks"`), not only inside `configure`.
+      def register(extension, **, &)
+        config.register_extension(extension, **, &)
+      end
+      alias register_extension register
+
+      def tabs
+        config.tabs
+      end
+
+      def custom_job_info_rows
+        config.custom_job_info_rows
+      end
+
+      def app_url
+        config.app_url
+      end
+
+      def app_url=(value)
+        config.app_url = value
+      end
+
+      def assets_path
+        config.assets_path
+      end
+
+      def assets_path=(value)
+        config.assets_path = value
+      end
+
       # Test helper — exposed for parity with `Wurk::Limiter.reset_config!`.
       # Production callers should not need to drop the auth block at runtime.
       def reset_config!

data/lib/wurk/web/enterprise.rb

@@ -132,6 +132,20 @@ module Wurk
         def history(bucket, window:, now: ::Time.now)
           Wurk::Metrics::Query.history(bucket, window, now: now)
         end
+
+        # Per-queue size/latency gauge time-series for the Historical tab.
+        # `bucket` is '1m'/'5m'/'1h'; `window` is in seconds (clamped to the
+        # bucket's retention). `queues:` narrows to one queue (else every live
+        # queue). Returns `[{name:, points: [{at:, size:, latency:}, …]}, …]`.
+        def queue_history(bucket, window:, queues: nil, now: ::Time.now)
+          Wurk::Metrics::Query.queue_history(bucket, window, queues: queues, now: now)
+        end
+
+        # Ent §5.3 Historical snapshots from the `history:metrics` stream,
+        # oldest→newest. Returns `[{at:, processed:, failures:, …}, …]`.
+        def snapshots(limit: Wurk::History::STREAM_DEFAULT_LIMIT)
+          Wurk::History.recent(limit: limit)
+        end
       end
     end
   end

data/lib/wurk/web/extension.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'cgi'
+require 'securerandom'
+
+module Wurk
+  class Web
+    # Server-side renderer for third-party Web extensions (spec §25, #187).
+    #
+    # Sidekiq extensions register Sinatra-style routes + ERB views via
+    # `Sidekiq::Web.register(Ext, name:, tab:, index:, root_dir:, asset_paths:)`,
+    # where `Ext.registered(app)` calls `app.get "/path" do … end` and
+    # `app.helpers SomeModule`. wurk's dashboard is a React SPA with no Sinatra
+    # render path, so this module provides a minimal, Sidekiq-Web-compatible
+    # renderer: it captures the routes, runs the matched block in an `Action`
+    # context (a `WebHelpers` subset + the ext's own helpers + `erb`), and
+    # returns the rendered HTML for the SPA's Extension page to embed.
+    #
+    # It does NOT depend on the `sidekiq` gem — extensions registered through
+    # wurk's own `Sidekiq::Web.register` alias render unchanged. (Running a
+    # real third-party gem unmodified additionally needs the shim in #204.)
+    module Extension
+      # Captures the routes + helpers an extension declares in `registered`.
+      # Quacks like the slice of `Sidekiq::Web::Application` extensions touch.
+      class App
+        attr_reader :routes, :helper_modules, :helper_blocks
+
+        HTTP_METHODS = %i[get post put patch delete head].freeze
+
+        def initialize
+          @routes = [] # [[method_string, Route, block], …]
+          @helper_modules = []
+          @helper_blocks = []
+        end
+
+        HTTP_METHODS.each do |verb|
+          define_method(verb) do |path, &block|
+            @routes << [verb.to_s.upcase, Route.new(path), block]
+          end
+        end
+
+        # Sidekiq extensions add helpers via `app.helpers(Mod)` and/or a block.
+        def helpers(*mods, &block)
+          @helper_modules.concat(mods)
+          @helper_blocks << block if block
+          self
+        end
+
+        # Sinatra settings calls some extensions make — accepted no-op.
+        def set(*); end
+        def settings = self
+        def configure(*) = (yield self if block_given?)
+      end
+
+      # Compiles a Sinatra-style path ("/locks/:digest") into a matcher that
+      # extracts Symbol-keyed route params. A trailing "*" matches the rest.
+      class Route
+        NAMED = %r{/([^/]*):([^./:$]+)}
+
+        attr_reader :path
+
+        def initialize(path)
+          @path = path.to_s
+          @keys = []
+          @regex = compile(@path)
+        end
+
+        # Returns a `{key => value}` Hash of route params, or nil if no match.
+        def match(path)
+          m = @regex.match(path)
+          return nil unless m
+
+          @keys.each_with_index.to_h { |k, i| [k, m[i + 1] && CGI.unescape(m[i + 1])] }
+        end
+
+        private
+
+        def compile(path)
+          return /\A#{::Regexp.escape(path[0..-2])}.*\z/ if path.end_with?('*')
+
+          %r{\A#{escaped_pattern(path)}/?\z}
+        end
+
+        # Escape every literal fragment so route text like ".json" or "+"
+        # matches itself instead of acting as a regex metacharacter.
+        def escaped_pattern(path)
+          pattern = +''
+          pos = 0
+          path.scan(NAMED) { pos = append_param(pattern, path, pos, ::Regexp.last_match) }
+          pattern << ::Regexp.escape(path[pos..])
+        end
+
+        def append_param(pattern, path, pos, match)
+          @keys << match[2].to_sym
+          pattern << ::Regexp.escape(path[pos...match.begin(0)]) << "/#{::Regexp.escape(match[1])}([^/?#]+)"
+          match.end(0)
+        end
+      end
+
+      # The `WebHelpers` subset real extension views/routes call. Mixed into
+      # every `Action`. Anything an exotic gem needs beyond this can be added
+      # incrementally; the common surface (escaping, paths, time, i18n) is here.
+      module Helpers
+        def h(text) = ::CGI.escapeHTML(text.to_s)
+
+        # Truncate long text (display safety) — mirrors Sidekiq's default cap.
+        def truncate(text, max = 2000)
+          str = text.to_s
+          str.size > max ? "#{str[0, max]}…" : str
+        end
+
+        # Best-effort arg display, matching Sidekiq's `to_display`.
+        def to_display(arg)
+          str = arg.inspect
+          str.size > 100 ? "#{str[0, 100]}…" : str
+        end
+
+        # i18n: look up the extension's own locale strings if present, else the
+        # humanized key (so a missing translation degrades, never raises).
+        def t(key, options = {})
+          val = (@ext_strings || {}).dig(*key.to_s.split('.'))
+          str = val.is_a?(::String) ? val : key.to_s.tr('_', ' ').capitalize
+          options.each { |k, v| str = str.gsub("%{#{k}}", v.to_s) }
+          str
+        end
+
+        # Base path for this extension, trailing slash. Embedded in the
+        # engine, ext links must land back on the embed endpoint
+        # (`/wurk/ext/<name>/…`); standalone (`run Sidekiq::Web`, #204) the
+        # ext's routes ARE the URL space, so it's the app root — upstream's
+        # `"#{env['SCRIPT_NAME']}/"` semantics.
+        def root_path = @embed ? "#{@mount}/ext/#{@ext_name}/" : "#{@mount}/"
+        def current_path = @subpath.to_s.sub(%r{\A/}, '')
+
+        def asset_path(file)
+          @embed ? "#{@mount}/ext-assets/#{@ext_name}/#{file}" : "#{@mount}/#{@ext_name}/#{file}"
+        end
+
+        # GET-form embeds don't need CSRF; return an empty, benign tag.
+        def csrf_tag = ''
+        def csp_nonce = (@csp_nonce ||= ::SecureRandom.hex(8))
+
+        # `<time>` element like Sidekiq's relative_time; JS upgrades it client-side.
+        def relative_time(time)
+          t = time.is_a?(::Time) ? time : ::Time.at(time.to_f)
+          iso = t.utc.iso8601
+          %(<time class="ltr" dir="ltr" title="#{iso}" datetime="#{iso}">#{iso}</time>)
+        end
+
+        def redis(&) = ::Wurk.redis(&)
+        def product_version = ::Wurk::VERSION
+        def number_with_delimiter(num) = num.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      end
+
+      # Per-request render context: instance-evals a matched route block, then
+      # renders ERB with the block's ivars + helpers in scope.
+      class Action
+        include Helpers
+
+        # Internal-redirect signal carried out of a route block via throw/catch.
+        Redirect = ::Struct.new(:location)
+
+        def initialize(env:, route_params:, ext:, mount:, embed: true)
+          @env = env
+          @request = ::Rack::Request.new(env)
+          @route_params = route_params
+          @ext_name = ext[:name].to_s
+          @root_dir = ext[:root_dir]
+          @ext_strings = ext[:strings]
+          @mount = mount.to_s
+          @embed = embed
+          @subpath = env['wurk.ext.subpath']
+          extend_helpers(ext[:helpers])
+        end
+
+        attr_reader :env, :request
+
+        def params = @params ||= symbolize(@request.params).merge(@route_params)
+        def url_params(key) = @request.params[key.to_s]
+        def route_params(key = nil) = key ? @route_params[key.to_sym] : @route_params
+        def session = (@env['rack.session'] ||= {})
+        def logger = ::Wurk.logger
+        def redirect(location) = throw(:wurk_ext_halt, Redirect.new(location))
+
+        # Render an ERB template. `content` is either the template String (the
+        # common path — the ext's own helper reads the file) or a Symbol naming
+        # a `*.erb` under the ext's root_dir/views.
+        def erb(content, _options = {})
+          template = content.is_a?(::Symbol) ? read_view(content) : content.to_s
+          ::ERB.new(template, trim_mode: '-').result(binding)
+        end
+
+        # Run the route block in this context, capturing redirects. Returns the
+        # rendered HTML String, or a Redirect.
+        def run(block)
+          catch(:wurk_ext_halt) { instance_exec(&block) }
+        end
+
+        private
+
+        def read_view(name)
+          raise ::ArgumentError, "extension #{@ext_name} has no root_dir" unless @root_dir
+
+          ::File.read(::File.join(@root_dir, 'views', "#{name}.erb"))
+        end
+
+        def extend_helpers(helpers)
+          Array(helpers && helpers[:modules]).each { |mod| extend(mod) }
+          Array(helpers && helpers[:blocks]).each { |blk| instance_eval(&blk) if blk }
+        end
+
+        def symbolize(hash) = hash.to_h.transform_keys(&:to_sym)
+      end
+
+      # Ties it together: finds a registered extension by name, captures its
+      # routes once (`registered(app)`), matches the request, and renders.
+      class Renderer
+        class << self
+          # @return [Array(Integer, Hash, String)] Rack-ish [status, headers,
+          #   body] — 200 HTML, 302 redirect, or 404 — or nil when no extension
+          #   with `name` is registered (so the engine can fall through).
+          # `embed: true` (the engine's ext/:name/* endpoint) rewrites links
+          # and redirects into the embed URL space; `embed: false` (the
+          # standalone `run Sidekiq::Web` Rack app, #204) leaves the
+          # extension's own route paths as the URL space, like upstream.
+          # rubocop:disable Metrics/ParameterLists -- request facts (name/verb/path/env) + URL-space (mount/embed); bundling them would just rename the list
+          def call(name:, method:, subpath:, env:, mount:, embed: true)
+            ext = registered_extension(name)
+            return nil unless ext
+
+            verb = method.to_s.upcase
+            route, block, route_params = match_route(ext, verb, subpath)
+            return [404, html_headers, "No #{verb} route #{subpath} in extension #{name}"] unless route
+
+            env['wurk.ext.subpath'] = subpath
+            render(ext, route_params, block, env, { mount: mount, embed: embed })
+          end
+          # rubocop:enable Metrics/ParameterLists
+
+          # `[absolute_path, cache_for_seconds]` of an asset under the
+          # extension's asset_paths, or nil if the extension/file isn't found.
+          # The expand_path prefix check rejects `../` traversal out of the dir.
+          def asset_file(name, file)
+            ext = registered_extension(name)
+            return nil unless ext
+
+            Array(ext[:asset_paths]).each do |dir|
+              path = ::File.expand_path(::File.join(dir, file.to_s))
+              next unless path.start_with?("#{::File.expand_path(dir)}/") && ::File.file?(path)
+
+              return [path, ext[:cache_for] || 86_400]
+            end
+            nil
+          end
+
+          private
+
+          def registered_extension(name)
+            ::Wurk::Web.config.extensions.find { |e| e[:name].to_s == name.to_s }
+          end
+
+          # `ctx` is `{ mount:, embed: }` — the URL-space the response renders
+          # into (engine embed vs standalone root).
+          def render(ext, route_params, block, env, ctx)
+            result = action_for(ext, route_params, env, ctx).run(block)
+            if result.is_a?(Action::Redirect)
+              [302, { 'Location' => redirect_target(result.location, ext, ctx) }, '']
+            else
+              [200, html_headers, result.to_s]
+            end
+          rescue ::StandardError => e
+            ::Wurk.configuration.handle_exception(e, context: 'web-extension-render')
+            [500, html_headers, "Extension render error: #{::CGI.escapeHTML(e.message)}"]
+          end
+
+          def action_for(ext, route_params, env, ctx)
+            app = captured_app(ext)
+            Action.new(
+              env: env, route_params: route_params, mount: ctx[:mount], embed: ctx[:embed],
+              ext: ext.merge(helpers: { modules: app.helper_modules, blocks: app.helper_blocks },
+                             strings: strings_for(ext))
+            )
+          end
+
+          def match_route(ext, verb, subpath)
+            captured_app(ext).routes.each do |meth, route, block|
+              next unless meth == verb
+
+              params = route.match(subpath)
+              return [route, block, params] if params
+            end
+            [nil, nil, nil]
+          end
+
+          # Capture the ext's routes/helpers once; memoize on the config entry.
+          def captured_app(ext)
+            ext[:_app] ||= App.new.tap do |app|
+              ext[:extension].registered(app) if ext[:extension].respond_to?(:registered)
+            end
+          end
+
+          # An ext's redirect target is relative to its mount ("locks" → the
+          # embed endpoint; standalone → the app root, where root_path-built
+          # targets already carry the mount). Absolute URLs pass through.
+          def redirect_target(location, ext, ctx)
+            loc = location.to_s
+            return loc if loc.match?(%r{\A[a-z]+://}i)
+            return "#{ctx[:mount]}/ext/#{ext[:name]}/#{loc.sub(%r{\A/}, '')}" if ctx[:embed]
+
+            loc.start_with?('/') ? loc : "#{ctx[:mount]}/#{loc}"
+          end
+
+          # The ext's own root_dir/locales plus every dir appended to
+          # `config.locales` (the upstream protocol for extensions without a
+          # root_dir — sidekiq-cron does `Sidekiq::Web.configure.locales <<
+          # dir` inside `registered`, which `captured_app` has already run by
+          # the time we land here).
+          def strings_for(ext)
+            ext.fetch(:_strings) do
+              ext[:_strings] = locale_dirs(ext).each_with_object({}) do |dir, acc|
+                file = ::File.join(dir.to_s, 'en.yml')
+                acc.merge!(load_yaml(file)) if ::File.exist?(file)
+              end
+            end
+          end
+
+          def locale_dirs(ext)
+            dirs = []
+            dirs << ::File.join(ext[:root_dir], 'locales') if ext[:root_dir]
+            dirs.concat(::Wurk::Web.config.locales)
+            dirs.uniq
+          end
+
+          def load_yaml(file)
+            require 'yaml'
+            data = ::YAML.safe_load_file(file)
+            data.is_a?(::Hash) ? (data.values.first || data) : {}
+          rescue ::StandardError
+            {}
+          end
+
+          def html_headers = { 'Content-Type' => 'text/html; charset=utf-8' }
+        end
+      end
+    end
+  end
+end