cronwatch 0.3.1

data/lib/cronwatch/js.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Cronwatch
+  # The few places JavaScript and Ruby disagree about text and numbers,
+  # settled the JavaScript way. The SDK writes the stored rows, alert text and
+  # webhook bodies, so the gem reproduces them byte for byte: Math.round,
+  # String(number), JSON.stringify, String.prototype.trim and lengths counted
+  # in UTF-16 code units.
+  module JS
+    # What JavaScript's \s and trim() treat as whitespace.
+    WHITESPACE = "\\t\\n\\v\\f\\r \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff"
+    SPACE = Regexp.new("[#{WHITESPACE}]")
+    SPACES = Regexp.new("[#{WHITESPACE}]+")
+    LEADING = Regexp.new("\\A[#{WHITESPACE}]+")
+    TRAILING = Regexp.new("[#{WHITESPACE}]+\\z")
+    NOT_SPACE = Regexp.new("[^#{WHITESPACE}]+")
+
+    ESCAPES = { '"' => '\\"', "\\" => "\\\\", "\b" => "\\b", "\f" => "\\f", "\n" => "\\n", "\r" => "\\r", "\t" => "\\t" }.freeze
+    # An array index is a canonical integer below 2**32 - 1; JavaScript lists those keys first.
+    INDEX_KEY = /\A(?:0|[1-9]\d{0,9})\z/
+    # Number.MAX_SAFE_INTEGER. Past it JavaScript holds an integer as the nearest double.
+    MAX_SAFE_INTEGER = (2**53) - 1
+
+    module_function
+
+    def trim(text)
+      text.sub(LEADING, "").sub(TRAILING, "")
+    end
+
+    def trim_end(text)
+      text.sub(TRAILING, "")
+    end
+
+    # Math.round: halves go up, toward positive infinity.
+    def round(value)
+      return value if value.is_a?(Integer)
+      return value unless value.finite?
+
+      floor = value.floor
+      value - floor >= 0.5 ? floor + 1 : floor
+    end
+
+    def finite?(value)
+      value.is_a?(Integer) || (value.is_a?(Numeric) && value.real? && value.to_f.finite?)
+    end
+
+    # Number.isInteger.
+    def integer?(value)
+      value.is_a?(Integer) || (value.is_a?(Float) && value.finite? && value == value.floor)
+    end
+
+    # String(number), the text a template literal or JSON.stringify gives a number.
+    def number(value)
+      return value.to_s if value.is_a?(Integer) && value.abs <= MAX_SAFE_INTEGER
+
+      value = value.to_f
+      return "NaN" if value.nan?
+      return (value.positive? ? "Infinity" : "-Infinity") if value.infinite?
+      return "0" if value.zero?
+
+      digits, point = decimal(value.abs)
+      k = digits.length
+      text =
+        if k <= point && point <= 21 then digits + ("0" * (point - k))
+        elsif point.positive? && point <= 21 then "#{digits[0, point]}.#{digits[point..]}"
+        elsif point > -6 && point <= 0 then "0.#{"0" * -point}#{digits}"
+        else
+          exponent = point - 1
+          mantissa = k == 1 ? digits : "#{digits[0]}.#{digits[1..]}"
+          "#{mantissa}e#{exponent.negative? ? "-" : "+"}#{exponent.abs}"
+        end
+      value.negative? ? "-#{text}" : text
+    end
+
+    # The shortest digits that round-trip, and where the decimal point goes:
+    # value = 0.DIGITS * 10**point. Ruby's Float#to_s already finds the digits.
+    def decimal(value)
+      text = value.to_s
+      if text.include?("e")
+        mantissa, exponent = text.split("e")
+        digits = mantissa.delete(".")
+        point = exponent.to_i + 1
+      else
+        whole, fraction = text.split(".")
+        if whole == "0"
+          stripped = fraction.sub(/\A0+/, "")
+          point = -(fraction.length - stripped.length)
+          digits = stripped
+        else
+          digits = whole + fraction.to_s
+          point = whole.length
+        end
+      end
+      digits = digits.sub(/0+\z/, "")
+      [digits.empty? ? "0" : digits, point]
+    end
+
+    # Length in UTF-16 code units, which is what String#length is in JavaScript.
+    def length16(text)
+      return text.length if text.ascii_only?
+
+      text.each_char.sum { |c| c.ord > 0xFFFF ? 2 : 1 }
+    end
+
+    # The first `units` UTF-16 code units. A character that would be cut in
+    # half is left out; JavaScript would keep a lone surrogate, Ruby cannot.
+    def head16(text, units)
+      return text[0, units] if text.ascii_only?
+
+      out = +""
+      used = 0
+      text.each_char do |c|
+        size = c.ord > 0xFFFF ? 2 : 1
+        break if used + size > units
+
+        out << c
+        used += size
+      end
+      out
+    end
+
+    # The last `units` UTF-16 code units, the same way.
+    def tail16(text, units)
+      return text[[text.length - units, 0].max..] if text.ascii_only?
+
+      chars = []
+      used = 0
+      text.each_char.reverse_each do |c|
+        size = c.ord > 0xFFFF ? 2 : 1
+        break if used + size > units
+
+        chars << c
+        used += size
+      end
+      chars.reverse.join
+    end
+
+    # JSON.stringify for plain data: hashes, arrays, strings, numbers, true,
+    # false and nil, and anything with a to_h (the gem's Structs) or as_json.
+    def json(value)
+      case value
+      when nil then "null"
+      when true then "true"
+      when false then "false"
+      when String then quote(value)
+      when Symbol then quote(value.to_s)
+      when Integer then number(value)
+      when Float then value.finite? ? number(value) : "null"
+      when Hash then "{#{object_keys(value).map { |k| "#{quote(k.to_s)}:#{json(value[k])}" }.join(",")}}"
+      when Array then "[#{value.map { |v| json(v) }.join(",")}]"
+      when Time then quote(iso(value))
+      when Numeric then json(value.to_f)
+      else
+        if value.respond_to?(:as_json) && !value.is_a?(Struct) then json(value.as_json)
+        elsif value.respond_to?(:to_h) then json(value.to_h)
+        else quote(value.to_s)
+        end
+      end
+    end
+
+    def quote(text)
+      text = text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless text.encoding == Encoding::UTF_8 && text.valid_encoding?
+      text = text.scrub unless text.valid_encoding?
+      escaped = text.gsub(/["\\\u0000-\u001f]/) { |c| ESCAPES[c] || format("\\u%04x", c.ord) }
+      "\"#{escaped}\""
+    end
+
+    # Property order: array-index keys ascending, then the rest as inserted.
+    def object_keys(hash)
+      keys = hash.keys
+      indexes = keys.select { |k| INDEX_KEY.match?(k.to_s) && k.to_s.to_i < 4_294_967_295 }
+      return keys if indexes.empty?
+
+      indexes.sort_by { |k| k.to_s.to_i } + (keys - indexes)
+    end
+
+    # Date#toISOString for epoch milliseconds or a Time.
+    def iso(at)
+      time = at.is_a?(Time) ? at.utc : Time.at(at.div(1000), at % 1000, :millisecond).utc
+      time.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    end
+
+    # JSON.parse. Ruby's parser keeps key order, as JavaScript does.
+    def parse(text)
+      ::JSON.parse(text)
+    end
+  end
+end

data/lib/cronwatch/monitored.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module Cronwatch
+  # What Cronwatch::ActiveJob and Cronwatch::Sidekiq share: the `cronwatch`
+  # class macro, the list of classes that called it, and when their jobs are
+  # declared on Cronwatch.client. Needs nothing beyond the core, so Sidekiq
+  # without Rails can use it. Loaded by cronwatch/scheduler, which schedule:
+  # :from_scheduler and declare_from_scheduler! need.
+  module Monitored
+    # What `cronwatch` is outside a monitored run: it takes log and metric
+    # calls and drops them, so the job's code runs the same either way.
+    class NullContext
+      def name = nil
+      def run_id = nil
+      def started_at = nil
+      def signal = nil
+      def log(*) = nil
+      def metric(_name, _value) = nil
+      def metrics(_values = nil, **) = nil
+      def aborted? = false
+    end
+    NULL_CONTEXT = NullContext.new.freeze
+
+    # Where the context goes for a job that has no `cronwatch` to hold it (one
+    # declared from the scheduler's config): nowhere.
+    module Discard
+      def self.cronwatch_with(_context) = yield
+    end
+
+    # One job's options and its handle on the current Cronwatch.client. The
+    # job is declared the first time it is needed and again whenever the
+    # client is replaced. `resolve`, when given, turns the options into the
+    # ones to declare (schedule: :from_scheduler reads the scheduler's config)
+    # the first time they are needed; its answer is kept.
+    class Declaration
+      attr_reader :name, :options, :where
+
+      def initialize(name, options, where:, resolve: nil)
+        @name = name
+        @options = options.freeze
+        @where = where
+        @resolve = resolve
+        @resolved = nil
+        @registration = nil
+        @lock = Mutex.new
+      end
+
+      # [client, handle] on Cronwatch.client. With strict: false a bad
+      # declaration goes to the client's on_error and the answer is nil.
+      def registration(strict: true)
+        client = Cronwatch.client
+        @lock.synchronize do
+          current = @registration
+          return current if current && current[0].equal?(client)
+
+          handle = client.job(@name, **resolve_locked)
+          @registration = [client, handle].freeze
+        end
+      rescue StandardError => e
+        raise if strict
+
+        client.report(e, "declaring #{@where}")
+        nil
+      end
+
+      private
+
+      def resolve_locked
+        @resolved ||= (@resolve ? @resolve.call(@options) : @options).freeze
+      end
+    end
+
+    @monitored = {}
+    @lock = Mutex.new
+    @ready = false
+
+    class << self
+      # The names of the classes that declared `cronwatch`, in the order they did.
+      def monitored
+        @lock.synchronize { @monitored.keys }
+      end
+
+      def track(klass)
+        @lock.synchronize { @monitored[klass.name] = true } if klass.name
+        nil
+      end
+
+      # Called once the app has booted (by the Railtie in Rails). From then on
+      # a class declares its job as soon as it calls `cronwatch`.
+      def ready!
+        @ready = true
+      end
+
+      def ready?
+        @ready
+      end
+
+      # Once the app has booted: from now on classes declare as they load,
+      # every class loaded so far declares now, and so does what
+      # Cronwatch.declare_from_scheduler! asked for. A bad declaration raises.
+      def boot!
+        ready!
+        register_all(strict: true)
+        Cronwatch::Scheduler.declare_pending! if defined?(Cronwatch::Scheduler)
+        nil
+      end
+
+      # Declares every monitored class's job on Cronwatch.client, and every
+      # job Cronwatch.declare_from_scheduler! took from the scheduler's
+      # config, so a check knows about jobs that have not run in this
+      # process. A class that no longer loads is skipped. With strict: false a
+      # bad declaration goes to the client's on_error instead of raising.
+      def register_all(strict: true)
+        monitored.each do |name|
+          klass = begin
+            Object.const_get(name)
+          rescue NameError
+            next
+          end
+          klass.cronwatch_registration(strict: strict) if klass.respond_to?(:cronwatch_registration)
+        end
+        Cronwatch::Scheduler.register_declared(strict: strict) if defined?(Cronwatch::Scheduler)
+        nil
+      end
+
+      # Loads app/jobs (and app/workers and app/sidekiq, where Sidekiq jobs
+      # often live) when the app does not eager load (development), so a check
+      # sees every monitored class, not only those used since boot.
+      def load_app_jobs
+        return unless defined?(::Rails) && ::Rails.respond_to?(:application) && (app = ::Rails.application)
+        return if app.config.eager_load
+
+        loader = ::Rails.respond_to?(:autoloaders) && ::Rails.autoloaders.main
+        return unless loader.respond_to?(:eager_load_dir)
+
+        dirs = Array(app.paths["app/jobs"]&.existent)
+        %w[app/workers app/sidekiq].each do |dir|
+          path = app.root.join(dir).to_s
+          dirs << path if File.directory?(path) && loader.dirs.include?(path)
+        end
+        dirs.uniq.each { |dir| loader.eager_load_dir(dir) }
+        nil
+      rescue StandardError, ScriptError => e
+        Cronwatch.client.report(e, "loading app/jobs")
+        nil
+      end
+
+      # NightlyReportJob is "nightly-report"; Reports::NightlyJob is "reports:nightly".
+      def default_name(klass)
+        raise ArgumentError, "cronwatch: an anonymous job class needs a name: option" if klass.name.nil?
+
+        dasherize(underscore(klass.name.delete_suffix("Job"))).tr("/", ":")
+      end
+
+      # Runs the block as a recorded run of the declaration's job, with the
+      # run's context as `cronwatch` on `job` (when it has one). A declaration that is broken
+      # runs the block unrecorded, with the error sent to on_error. The
+      # block's error is raised again after the run is recorded.
+      def record(declaration, trigger, job)
+        client, handle = declaration&.registration(strict: false)
+        return yield unless handle
+
+        holder = job.respond_to?(:cronwatch_with, true) ? job : Discard
+        outcome = client.execute(handle.definition, trigger) do |context|
+          holder.__send__(:cronwatch_with, context) { yield }
+        end
+        raise outcome.error if outcome.threw
+
+        outcome.result
+      end
+
+      private
+
+      # ActiveSupport's, when it is loaded, so the app's acronyms apply; the
+      # same rules without them otherwise.
+      def underscore(text)
+        return ::ActiveSupport::Inflector.underscore(text) if defined?(::ActiveSupport::Inflector)
+
+        text.gsub("::", "/").gsub(/(?<=[A-Z])(?=[A-Z][a-z])|(?<=[a-z\d])(?=[A-Z])/, "_").tr("-", "_").downcase
+      end
+
+      def dasherize(text)
+        text.tr("_", "-")
+      end
+    end
+
+    # The class side: `cronwatch` and what it declares.
+    module ClassMethods
+      # Monitor this job. Takes the options of Cronwatch::Client#job (schedule,
+      # timezone, grace, timeout, max_duration, budget, expect,
+      # failures_before_alert, description, tags) and name:, which defaults to
+      # the class name without "Job", dasherized. schedule: :from_scheduler
+      # takes the schedule (and its timezone) from the class's entry in Solid
+      # Queue's config/recurring.yml or sidekiq-cron's schedule.
+      def cronwatch(name: nil, **options)
+        name ||= Cronwatch::Monitored.default_name(self)
+        resolve = nil
+        if options[:schedule] == :from_scheduler
+          if options.key?(:timezone)
+            raise ArgumentError, "cronwatch: #{self.name || name} takes its timezone from the scheduler with schedule: :from_scheduler; " \
+                                 "drop timezone:"
+          end
+          klass = self
+          resolve = ->(given) { given.merge(Cronwatch::Scheduler.schedule_for(klass)) }
+        elsif options[:schedule].is_a?(Symbol)
+          raise ArgumentError, "cronwatch: schedule #{options[:schedule].inspect} is not a schedule; did you mean :from_scheduler?"
+        end
+        declaration = Declaration.new(name, options, where: self.name || name, resolve: resolve)
+        declaration.registration if Cronwatch::Monitored.ready? # a bad one raises here, leaving the class unmonitored
+        @cronwatch_declaration = declaration
+        Cronwatch::Monitored.track(self)
+        nil
+      end
+
+      # The options given to `cronwatch`, with the name. Nil when this class is not monitored.
+      def cronwatch_options
+        declaration = @cronwatch_declaration
+        declaration && declaration.options.merge(name: declaration.name).freeze
+      end
+
+      def cronwatch_name
+        @cronwatch_declaration&.name
+      end
+
+      def cronwatch_declaration
+        @cronwatch_declaration
+      end
+
+      # This class's job handle on the current Cronwatch.client.
+      def cronwatch_handle(strict: true)
+        cronwatch_registration(strict: strict)&.last
+      end
+
+      # [client, handle]: the job declared on Cronwatch.client, the first time
+      # and again whenever the client is replaced.
+      def cronwatch_registration(strict: true)
+        @cronwatch_declaration&.registration(strict: strict)
+      end
+    end
+
+    # The run's context during a monitored run: log, metric, metrics,
+    # aborted?, signal. Outside one, a stand-in that drops what it is given.
+    def cronwatch
+      @cronwatch || NULL_CONTEXT
+    end
+
+    private
+
+    def cronwatch_with(context)
+      previous = @cronwatch
+      @cronwatch = context
+      begin
+        yield
+      ensure
+        @cronwatch = previous
+      end
+    end
+  end
+end

data/lib/cronwatch/output.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Cronwatch
+  module Output
+    # Output is capped so a chatty job cannot fill the store. The tail is kept.
+    # Counted in UTF-16 code units, as the SDK counts it.
+    CAP = 16 * 1024
+
+    REDACTED = "[redacted]"
+
+    # The SDK's SECRET_PATTERNS, written so Onigmo matches exactly what
+    # JavaScript matches: (?a) keeps \b to ASCII word characters, \s is spelled
+    # out as JavaScript's whitespace, and the case-insensitive parts are
+    # spelled as [Ss][Ee]... because Ruby's /i also folds "ß" to "ss" and the
+    # Kelvin sign to "k", which JavaScript's /i does not. Bounded quantifiers
+    # throughout, so a long line cannot make these backtrack.
+    module Secrets
+      WS = JS::WHITESPACE
+
+      # "secret" as [Ss][Ee][Cc][Rr][Ee][Tt]: ASCII-only case folding.
+      def self.ci(word)
+        word.chars.map { |c| c.match?(/[a-z]/) ? "[#{c.upcase}#{c}]" : Regexp.escape(c) }.join
+      end
+
+      NAMES = [
+        ci("secret"), ci("token"), "#{ci("passw")}(?:#{ci("or")})?#{ci("d")}", ci("pwd"),
+        "#{ci("api")}[_-]?#{ci("key")}", "#{ci("access")}[_-]?#{ci("key")}", "#{ci("private")}[_-]?#{ci("key")}",
+        ci("credential"),
+      ].join("|").freeze
+
+      # "=", ":" or a hash rocket, between a name and its value.
+      ASSIGN = "(?:=>|[=:])"
+
+      # They apply in this order, each to the text the ones before it left.
+      PATTERNS = [
+        # A PEM private key, header to footer. Without a footer (the output was
+        # trimmed) it runs to the end of the base64 body. A "-" that starts five
+        # dashes ends the body, so the footer is never swallowed into it.
+        [Regexp.new("-----BEGIN (?:[A-Z0-9]{1,20} ){0,3}PRIVATE KEY-----(?:[A-Za-z0-9+/=#{WS},:]|-(?!----)){0,16384}" \
+                    "(?:-----END (?:[A-Z0-9]{1,20} ){0,3}PRIVATE KEY-----)?"), false],
+        # password=..., API_KEY: ..., "client_secret": "...", TOKEN='...', token=...,
+        # :password=>"..." (but not max_tokens: 800). A quoted value is blanked to
+        # its closing quote, spaces and all, and keeps its quotes.
+        [Regexp.new("(?a)\\b([A-Za-z0-9_-]{0,40}(?:#{NAMES})[A-Za-z0-9_-]{0,40}(?<![Tt][Oo][Kk][Ee][Nn][Ss])\"?[#{WS}]{0,3}#{ASSIGN}[#{WS}]{0,3})(?:(\")[^\"\\n]{1,4096}\"|(')[^'\\n]{1,4096}'|[\"']?[^#{WS}\"',;&]{1,4096})"), :quoted],
+        # Authorization: Basic <base64> and Authorization: Token <token>, also as a JSON or hash entry.
+        [Regexp.new("(?a)\\b((?:#{ci("proxy-")})?#{ci("authorization")}[\"']?[#{WS}]{0,3}#{ASSIGN}[#{WS}]{0,3}[\"']?[#{WS}]{0,3}" \
+                    "(?:#{ci("basic")}|#{ci("token")})[#{WS}]{1,3})[A-Za-z0-9._~+/=:-]{1,4096}"), true],
+        # Credentials inside a URL: postgres://user:password@host. The password
+        # runs to the last "@" before a "/" or a space, so one that contains "@"
+        # is blanked whole.
+        [Regexp.new("(?a)(\\b[A-Za-z][A-Za-z0-9+.-]{0,30}://[^#{WS}/:@]{0,256}:)[^#{WS}/]{1,256}@"), :url],
+        # Authorization: Bearer <token>
+        [Regexp.new("(?a)\\b(Bearer[#{WS}]{1,3})[A-Za-z0-9._~+/=-]{8,4096}"), true],
+        # A bare JWT: three base64url segments, the first starting eyJ.
+        [/(?a)\beyJ[A-Za-z0-9_-]{4,4096}\.[A-Za-z0-9_-]{4,4096}\.[A-Za-z0-9_-]{0,4096}/, false],
+        # Incoming webhook URLs carry their secret in the path.
+        [Regexp.new("(?a)(\\b#{ci("hooks.slack.com")}/(?:#{ci("services")}|#{ci("workflows")}|#{ci("triggers")})/)[A-Za-z0-9/_-]{1,255}"), true],
+        [Regexp.new("(?a)(\\b#{ci("discord")}(?:#{ci("app")})?#{ci(".com/api/")}(?:[Vv][0-9]{1,2}/)?#{ci("webhooks/")})[A-Za-z0-9/_-]{1,255}"), true],
+        # Well-known token shapes: AWS, GitHub, Slack, Stripe, Anthropic, OpenAI and Google style keys.
+        [/(?a)\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/, false],
+        [/(?a)\b(?:gh[pousr]_[A-Za-z0-9]{30,255}|github_pat_[A-Za-z0-9_]{20,255})\b/, false],
+        [/(?a)\bxox[abposr]-[A-Za-z0-9-]{10,255}/, false],
+        [/(?a)\b[rsp]k_(?:live|test)_[A-Za-z0-9]{10,255}\b/, false],
+        [%r{(?a)\bwhsec_[A-Za-z0-9+/=]{16,255}}, false],
+        [/(?a)\bsk-[A-Za-z0-9_-]{20,255}/, false],
+        [/(?a)\bAIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])/, false],
+      ].freeze
+
+      # Characters outside the Basic Multilingual Plane.
+      ASTRAL = /[\u{10000}-\u{10FFFF}]/
+      # Where a UTF-16 surrogate stands while the patterns run: U+10D800 to
+      # U+10DFFF, which cannot otherwise appear once every astral character
+      # has been split into its two surrogates.
+      SURROGATE_BASE = 0x100000
+      STANDIN = /[\u{10D800}-\u{10DFFF}]+/
+
+      # JavaScript's patterns (no u flag) see UTF-16 code units, so a
+      # character outside the BMP is two characters to a negated class and to
+      # a bounded quantifier. Text with such characters is matched with each
+      # one written as two stand-ins, then put back together.
+      def self.to_units(text)
+        text.encode(Encoding::UTF_16LE).unpack("v*").map { |u| (u >= 0xD800 && u <= 0xDFFF ? SURROGATE_BASE + u : u).chr(Encoding::UTF_8) }.join
+      end
+
+      # A surrogate a replacement cut from its partner becomes U+FFFD:
+      # JavaScript would keep it alone, Ruby's UTF-8 cannot.
+      def self.from_units(text)
+        text.gsub(STANDIN) do |run|
+          units = run.each_char.map { |c| c.ord - SURROGATE_BASE }
+          out = +""
+          i = 0
+          while i < units.length
+            high = units[i]
+            low = units[i + 1]
+            if high <= 0xDBFF && low && low >= 0xDC00
+              out << (0x10000 + ((high - 0xD800) << 10) + (low - 0xDC00)).chr(Encoding::UTF_8)
+              i += 2
+            else
+              out << 0xFFFD.chr(Encoding::UTF_8)
+              i += 1
+            end
+          end
+          out
+        end
+      end
+    end
+
+    module_function
+
+    # Text as valid UTF-8, whatever it was read as: bytes that are not UTF-8
+    # (binary output, a C extension's message) become U+FFFD, and text in
+    # another encoding is converted. JavaScript strings cannot hold anything
+    # else, and the store, the alerts and the redaction all expect UTF-8.
+    def utf8(text)
+      text = text.to_s
+      return text if text.encoding == Encoding::UTF_8 && text.valid_encoding?
+
+      if [Encoding::UTF_8, Encoding::BINARY, Encoding::US_ASCII].include?(text.encoding)
+        text.dup.force_encoding(Encoding::UTF_8).scrub
+      else
+        text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      end
+    end
+
+    # NUL characters are removed first, since Postgres refuses them in TEXT
+    # and JSONB and the whole run row would be lost. The cap then applies to
+    # what is left.
+    def cap(text)
+      text = strip_nul(utf8(text))
+      return text if JS.length16(text) <= CAP
+
+      "[earlier output trimmed]\n#{JS.tail16(text, CAP)}"
+    end
+
+    # Removes every U+0000.
+    def strip_nul(text)
+      text.include?("\0") ? text.delete("\0") : text
+    end
+
+    # "Name: message" and the first five backtrace lines, each written as
+    # "    at <line>" like the frames of a JavaScript stack, capped like output.
+    # An exception that stops the thread rather than reporting a problem
+    # (Interrupt, SystemExit, Sidekiq::Shutdown, a Timeout) is written
+    # "Interrupted: <class>", with its message when it says more.
+    def error_message(error)
+      cap(describe_error(error))
+    end
+
+    def describe_error(error)
+      if error.is_a?(Exception)
+        frames = (error.backtrace || []).first(5).map { |line| "    at #{utf8(line)}" }
+        name = error.class.name || error.class.to_s
+        message = utf8(error.message)
+        header =
+          if interruption?(error)
+            message.empty? || message == name ? "Interrupted: #{name}" : "Interrupted: #{name}: #{message}"
+          else
+            "#{name}: #{message}"
+          end
+        return frames.empty? ? header : "#{header}\n#{frames.join("\n")}"
+      end
+      return utf8(error) if error.is_a?(String)
+
+      begin
+        JS.json(error)
+      rescue StandardError
+        utf8(error)
+      end
+    end
+
+    # Outside StandardError, and not a ScriptError (NotImplementedError,
+    # LoadError), which is a problem in the code rather than a stop.
+    def interruption?(error)
+      !error.is_a?(StandardError) && !error.is_a?(ScriptError)
+    end
+
+    # The default `redact`: blanks values that look like secrets (key=value
+    # pairs with secret-ish names, Authorization headers, URL credentials,
+    # bearer tokens, JWTs, PEM private keys, webhook URLs and well-known token
+    # formats) before output or an error is stored, shown or sent anywhere. Matches exactly what the SDK's redactSecrets matches.
+    def redact_secrets(text)
+      astral = !text.ascii_only? && Secrets::ASTRAL.match?(text)
+      out = astral ? Secrets.to_units(text) : text
+      Secrets::PATTERNS.each do |pattern, keep|
+        out = out.gsub(pattern) do
+          case keep
+          when :url then "#{Regexp.last_match(1)}#{REDACTED}@"
+          when :quoted
+            quote = Regexp.last_match(2) || Regexp.last_match(3) || ""
+            "#{Regexp.last_match(1)}#{quote}#{REDACTED}#{quote}"
+          when true then "#{Regexp.last_match(1)}#{REDACTED}"
+          else REDACTED
+          end
+        end
+      end
+      astral ? Secrets.from_units(out) : out
+    end
+  end
+end