roundhouse_ui 0.9.1 → 0.11.0

data/lib/roundhouse_ui/filter_query.rb

@@ -0,0 +1,504 @@
+# frozen_string_literal: true
+
+module RoundhouseUi
+  # One search box, parsed into the exact filters the scan already understands.
+  #
+  #   class=Billing::SyncWorker error=Timeout::Error stripe
+  #
+  # `key=value` tokens become structured, EXACT filters; whatever follows them is
+  # one verbatim substring needle. That is the whole point: the box becomes the
+  # single visible, editable, shareable home for filter state, without a class name
+  # in it silently widening the "delete all matching" button below it.
+  #
+  # Two rules do the work:
+  #
+  #   1. Split on the FIRST `=` only. Colons are never a delimiter, so
+  #      `Billing::SyncWorker` and `Timeout::Error` need no escaping — which is why
+  #      the separator is `=` and not Datadog's `:`. Ruby names are colon-dense.
+  #   2. Facets lead. Parsing walks from index 0; the first position where a facet
+  #      cannot be read ends the facet region, and everything from that byte to the
+  #      end is the text needle, as one contiguous slice. With no facets the slice
+  #      starts at 0, so `text` is byte-identical to the old `params[:q].strip`,
+  #      interior double spaces included. That is not a special case — it falls out
+  #      of the rule, which is what keeps parse/to_s compositional.
+  #
+  # Everything invalid is REFUSED, whole. Never "ignore the token I did not
+  # understand": discarding is the only resolution that can select MORE than what
+  # was typed, and this feeds a destructive action. `clas=Foo` becoming a substring
+  # search for the literal text "clas=Foo" would find nothing and read as "no such
+  # jobs exist"; worse, dropping it entirely would widen a delete.
+  class FilterQuery
+    KEYS = %w[class error queue tag text].freeze
+
+    # Checked before any comparison runs, the same ordering as
+    # RoundhouseUi.job_class: a length test first, so a pathological input is
+    # bounded before anything walks it. Regexp.timeout is Ruby 3.2+ and the
+    # gemspec floor is 3.1, so bounding the input is the only portable defence.
+    MAX_LENGTH = 500
+    # No facet count cap, deliberately. There are five keys and a conflicting
+    # duplicate is refused, so the maximum number of facets in any accepted query
+    # is five. A cap of eight was written, could never fire, and its test was
+    # actually exercising the duplicate rule — a bound that cannot be reached
+    # reads as a risk that does not exist. MAX_LENGTH bounds the total work.
+    # Same bound as RoundhouseUi::MAX_JOB_CLASS_NAME, written out because this file
+    # is required before that constant is defined — the entry point's require block
+    # runs above its own module body.
+    MAX_VALUE  = 200
+
+    # Things a Datadog-trained operator will type. Refused BY NAME rather than
+    # matched literally: entry_selected? is a pure conjunction, which is exactly
+    # what makes a stray token harmless, and every one of these is disjunction or
+    # a substring in a facet's clothing.
+    # Refused by name, because a Datadog-trained operator will type them and a
+    # literal match reads as "no such jobs exist". Narrow on purpose: only a
+    # NEGATED KNOWN FACET is unambiguous. A bare "-1" or "*" or "OR" in free text
+    # is legitimate text — an error message can contain any of them — and refusing
+    # those would break searching for what is actually in the data.
+    UNSUPPORTED = [
+      [ /\A-(?:#{KEYS.join('|')})=/,
+        "Negation is not supported. Every filter narrows; none excludes." ]
+    ].freeze
+
+    # `class=Roundhouse%`, `class=%oundhouse%`, `class=%Worker`, `class=A%B%C`.
+    #
+    # `%` only. NOT `_`: SQL's single-character wildcard would silently turn
+    # `queue=default_low` into a pattern matching `defaultXlow`, and every Ruby name
+    # in this console is underscore-dense. A wildcard nobody typed is the one thing
+    # that must never happen here, because the same predicate scopes a Delete.
+    #
+    # An index walk rather than a Regexp. The pattern comes from a URL and is matched
+    # against every entry in a set that can hold fifty thousand of them, so a
+    # backtracking engine is both a performance and a ReDoS question. This is linear
+    # in the value and provably terminates.
+    class Pattern
+      MAX_WILDCARDS = 6
+
+      def self.for(value)
+        value.to_s.include?("%") ? new(value) : nil
+      end
+
+      attr_reader :source
+
+      def initialize(value)
+        @source = value.to_s
+        @segments = @source.split("%", -1)
+        @lead = @segments.first
+        @tail = @segments.last
+        @mids = @segments[1..-2] || []
+      end
+
+      # Literal characters the pattern insists on. Zero means it matches every
+      # possible value, which is not a filter — see the refusal in the parser.
+      def literals = @segments.sum(&:length)
+      def wildcards = @segments.length - 1
+      def too_many? = wildcards > MAX_WILDCARDS
+
+      def match?(value)
+        v = value.to_s
+        return false unless v.start_with?(@lead)
+        # The tail must not reuse characters the lead already consumed, or `A%A`
+        # would match "A" — one literal doing double duty.
+        return false unless v.end_with?(@tail) && v.length >= @lead.length + @tail.length
+
+        cursor = @lead.length
+        stop = v.length - @tail.length
+        @mids.each do |mid|
+          next if mid.empty?
+
+          at = v.index(mid, cursor)
+          return false if at.nil? || at + mid.length > stop
+
+          cursor = at + mid.length
+        end
+        true
+      end
+    end
+
+    attr_reader :klass, :error, :queue, :tag, :text, :raw, :message, :ignored
+
+    class << self
+      # Never raises. A refusal is a value, not an exception, because this runs in a
+      # before_action on every page including the ones that only browse.
+      # `keys` restricts which facets this PAGE honours. Errors groups by class and
+      # error, so queue= has nothing to apply to there — and a facet that renders as
+      # a pill while filtering nothing is precisely the invisible/phantom filter this
+      # whole bar exists to prevent. Out of scope refuses, and says where it works.
+      def parse(raw, keys: KEYS)
+        return refused(raw, "Search is not a single value.") unless raw.nil? || raw.is_a?(String)
+
+        str = raw.to_s
+        # Encoding first, then length, then anything that inspects characters.
+        # String#strip raises Encoding::CompatibilityError on invalid bytes, so
+        # checking validity third meant a malformed query crashed the page instead
+        # of being refused — the same ordering trap RoundhouseUi.job_class avoids by
+        # testing length before it matches.
+        return refused("", "That search contains invalid characters.") unless str.valid_encoding?
+        return refused(str, "That search is too long (#{str.length} characters, limit #{MAX_LENGTH}).") if str.length > MAX_LENGTH
+        return none if str.strip.empty?
+
+        Parser.new(str, keys).call
+      end
+
+      # Old links and bookmarks. `?class=X&error=Y` predates the grammar, and
+      # find_like_link, the tag chips and the queue pills all emitted it — so
+      # somebody's saved URL, and somebody's shared one, is that shape.
+      #
+      # Folded by RE-PARSING rather than by assignment. build() does not validate,
+      # so a legacy `?error=A"B` assigned straight in would produce a query whose
+      # own to_s the parser then refuses — displayed one filter, applied another.
+      # Going back through parse means nothing can enter that the grammar would
+      # not accept, and conflicts (`?q=class=A&class=B`) hit the parser's existing
+      # refusal instead of a second, differently-written precedence rule.
+      LEGACY = { class: "class", error: "error", queue: "queue", tag: "tag" }.freeze
+
+      def from_params(params, keys: KEYS)
+        # `qf` is the search FORM's facet companion. The bar renders each facet as a
+        # pill and leaves the visible input holding only the free text, so the facets
+        # need a way back — joined here, facets first, at the single parse point.
+        #
+        # `q` stays the canonical parameter on its own: a bookmark or a shared link
+        # carries the whole filter in q and never mentions qf. If both arrive and
+        # they disagree, the parser's existing duplicate rule refuses.
+        facets = params[:qf].to_s.strip
+        typed = params[:q].to_s.strip
+        q = parse(facets.empty? ? params[:q] : [ facets, typed ].reject(&:empty?).join(" "), keys: keys)
+        return q if q.invalid?
+
+        extra = LEGACY.filter_map do |param, key|
+          next unless keys.include?(key)
+
+          value = params[param].to_s.strip
+          next if value.empty?
+
+          "#{key}=#{value.match?(/\s/) ? %("#{value}") : value}"
+        end
+        return q if extra.empty?
+
+        parse((q.facet_parts + extra + q.text_parts).join(" "), keys: keys)
+      end
+
+      def build(klass: nil, error: nil, queue: nil, tag: nil, text: nil, ignored: [])
+        new(klass: klass, error: error, queue: queue, tag: tag, text: text.to_s, ignored: ignored)
+      end
+
+      def none = @none ||= build.freeze
+
+      def refused(raw, message)
+        q = build
+        q.instance_variable_set(:@raw, raw.to_s)
+        q.instance_variable_set(:@message, message)
+        q.freeze
+      end
+    end
+
+    def initialize(klass: nil, error: nil, queue: nil, tag: nil, text: "", raw: nil, ignored: [])
+      @klass = presence(klass)
+      @error = presence(error)
+      @queue = presence(queue)
+      @tag   = tag
+      @text  = text.to_s
+      @raw   = raw || to_s
+      @ignored = ignored.freeze
+      @message = nil
+    end
+
+    def invalid? = !@message.nil?
+
+    # A matcher per facet, compiled once. `nil` where the value has no `%`, which is
+    # the overwhelming case and stays a plain string comparison.
+    def pattern_for(field)
+      @patterns ||= {}
+      return @patterns[field] if @patterns.key?(field)
+
+      @patterns[field] = Pattern.for(public_send(field))
+    end
+
+    # Does this facet's value match? Exact when there is no wildcard — `queue=default`
+    # must never also select `default_low`, which is the invariant the whole facet
+    # design rests on.
+    def matches_facet?(field, value)
+      wanted = public_send(field)
+      return true if wanted.nil?
+
+      pattern = pattern_for(field)
+      pattern ? pattern.match?(value) : value.to_s == wanted
+    end
+
+    def wildcard? = %i[klass error queue tag].any? { |f| pattern_for(f) }
+
+    # Was any facet dropped? A degraded query browses normally — the point of
+    # dropping rather than refusing — but authorises no bulk action, because the
+    # filter that survived selects a SUPERSET of what was asked for.
+    def degraded? = !ignored.empty?
+
+    # One sentence per dropped facet, for the banner above the table.
+    def notes = ignored.map { |token, why| %(Ignored "#{token}" — #{why}.) }
+
+    # What the search box shows. Canonical when the query parsed, but the RAW input
+    # when it did not: a refused query has no canonical form, and rendering the
+    # empty one would swallow the typo along with any chance of fixing it.
+    def display = invalid? ? raw : to_s
+    def any_facets? = !(klass.nil? && error.nil? && queue.nil? && tag.nil?)
+    def any? = any_facets? || !text.empty?
+
+    # The tag filter's existing two-element shape, so entry_tagged? is untouched.
+    def tag_pair
+      return nil if tag.nil?
+
+      key, value = tag.split(":", 2)
+      return nil if key.to_s.empty? || value.to_s.empty?
+
+      [ key, value ]
+    end
+
+    # Canonical, and round-trips: parse(q.to_s) == q. Facets in KEYS order so the
+    # box does not reshuffle itself when you press Enter.
+    def to_s
+      @canonical ||= (facet_parts + text_parts).join(" ")
+    end
+
+    # The facet region alone, in KEYS order. Public because from_params splices
+    # more facets in here — between the facets and the text, never after it.
+    def facet_parts
+      parts = []
+      parts << "class=#{quoted(klass)}" if klass
+      parts << "error=#{quoted(error)}" if error
+      parts << "queue=#{quoted(queue)}" if queue
+      parts << "tag=#{quoted(tag)}"     if tag
+      parts
+    end
+
+    def text_parts
+      text.empty? ? [] : [ serialized_text ]
+    end
+    alias to_param to_s
+
+    def chips
+      [ [ :class, klass ], [ :error, error ], [ :queue, queue ], [ :tag, tag ] ]
+        .select { |_k, v| v }
+    end
+
+    def merge(**over)
+      self.class.build(
+        klass: over.key?(:klass) ? over[:klass] : klass,
+        error: over.key?(:error) ? over[:error] : error,
+        queue: over.key?(:queue) ? over[:queue] : queue,
+        tag:   over.key?(:tag)   ? over[:tag]   : tag,
+        text:  over.key?(:text)  ? over[:text].to_s : text
+      )
+    end
+
+    def without(*keys)
+      over = keys.to_h { |k| [ k, k == :text ? "" : nil ] }
+      merge(**over)
+    end
+
+    def ==(other) = other.is_a?(FilterQuery) && to_s == other.to_s && invalid? == other.invalid?
+    alias eql? ==
+    def hash = [ self.class, to_s, invalid? ].hash
+
+    private
+
+    def presence(v)
+      s = v.to_s.strip
+      s.empty? ? nil : s
+    end
+
+    # A value needs quoting when it holds whitespace, or the box would reparse it
+    # as a facet boundary and the next Enter would mean something different.
+    def quoted(value)
+      value.match?(/\s/) ? %("#{value}") : value
+    end
+
+    # Text whose first token looks like `key=` has to go back out through the
+    # `text=` escape hatch, or re-parsing it would read that token as a facet —
+    # and since the key would be an unknown one, refuse the whole query. Pressing
+    # Enter twice would then mean something different from pressing it once.
+    #
+    # Always representable, and worth knowing why: text can only BEGIN with a
+    # facet-shaped token if it arrived as text="…" in the first place (a known key
+    # would have been parsed as a facet, an unknown one refused), and a quoted
+    # value cannot contain a quote, because reading one stops at the first closing
+    # quote. So there is no text needing the wrapper that also breaks it.
+    public def serialized_text
+      text.match?(/\A[a-z][a-z0-9_]*=/) ? %(text="#{text}") : text
+    end
+
+    # An index walk. No regex over the input, so there is nothing to backtrack.
+    class Parser
+      def initialize(str, keys = FilterQuery::KEYS)
+        @s = str
+        @keys = keys
+        @i = 0
+        @seen = {}
+        @ignored = []
+      end
+
+      def call
+        loop do
+          skip_space
+          break if @i >= @s.length
+
+          key = read_key
+          # An unrecognised key refuses the whole query. Falling through to free
+          # text is the one resolution that can select MORE than was typed, and a
+          # literal substring search for "clas=Foo" would find nothing and read as
+          # "no such jobs exist".
+          return refuse(nil) if key == :unknown
+          break if key.nil?
+
+          value = read_value
+          return refuse("Unclosed quote in #{key}=. Quote both ends, or drop the quotes.") if value == :unterminated
+          return refuse(bad_value_message(key, value)) unless value_ok?(value)
+          # A tag is a key:value pair or it is nothing. Rather than refuse the whole
+          # query, the facet is DROPPED and recorded — a typo should not stop you
+          # browsing. What it does stop is a bulk action: `tag=garbage queue=default`
+          # drops to `queue=default`, which selects the whole queue, and the Delete
+          # beneath it would then be scoped wider than what was typed. Dropping a
+          # facet can only ever widen, so a degraded query authorises nothing.
+          # Both halves must be non-empty. `tag=squad:` has a colon, so a
+          # colon-only check let it through: the pill rendered, tag_pair came back nil,
+          # and entry_selected?'s `return true if tag.nil?` selected everything — with
+          # bulk authorised, because any_facets? was true.
+          if key == "tag" && value.split(":", 2).reject(&:empty?).size != 2
+            @ignored << [ "#{key}=#{value}", "tag= takes key:value, like tag=squad:core" ]
+            next
+          end
+
+          if @seen.key?(key) && @seen[key] != value
+            return refuse(%(Two different values for #{key}: "#{@seen[key]}" and "#{value}". Pick one.))
+          end
+
+          @seen[key] = value
+        end
+
+        residue = @s[@i..].to_s.strip
+
+        # text= is the escape hatch for facet-shaped free text. Having BOTH is two
+        # ways of saying the same thing, and picking one would discard the other
+        # silently — `text=foo bar` would have kept "foo" and thrown "bar" away.
+        if @seen.key?("text") && !residue.empty?
+          return refuse(%(Text is given twice: text="#{@seen['text']}" and "#{residue}". ) +
+                        %(Quote the whole thing: text="#{@seen['text']} #{residue}"))
+        end
+
+        unsupported = unsupported_in(residue)
+        return refuse(unsupported) if unsupported
+
+        FilterQuery.new(klass: @seen["class"], error: @seen["error"], queue: @seen["queue"],
+                        tag: @seen["tag"], text: @seen.fetch("text", residue), raw: @s,
+                        ignored: @ignored)
+      end
+
+      private
+
+      def skip_space = (@i += 1 while @i < @s.length && @s[@i].match?(/[ \t\n\r]/))
+
+      # A facet candidate is a lowercase key followed immediately by `=`. Anything
+      # else ends the facet region and begins the text — which is why pasting a
+      # whole error message like `SSL_connect returned=1 errno=0` is unaffected:
+      # `SSL_connect` fails the charset at `S`, so the residue starts at 0.
+      def read_key
+        start = @i
+        return nil unless @i < @s.length && @s[@i].match?(/[a-z]/)
+
+        @i += 1 while @i < @s.length && @s[@i].match?(/[a-z0-9_]/)
+        unless @i < @s.length && @s[@i] == "="
+          @i = start
+          return nil
+        end
+
+        key = @s[start...@i]
+        unless FilterQuery::KEYS.include?(key)
+          @i = start
+          @unknown = key
+          return :unknown
+        end
+        # Known everywhere, not honoured here. A distinct refusal from "unknown",
+        # because the fix is different: go to the page where it applies.
+        unless @keys.include?(key)
+          @i = start
+          @out_of_scope = key
+          return :unknown
+        end
+
+        @i += 1
+        key
+      end
+
+      def read_value
+        if @s[@i] == '"'
+          close = @s.index('"', @i + 1)
+          return :unterminated if close.nil?
+
+          value = @s[(@i + 1)...close]
+          @i = close + 1
+          return :unterminated unless @i >= @s.length || @s[@i].match?(/[ \t\n\r]/)
+
+          value
+        else
+          start = @i
+          @i += 1 while @i < @s.length && !@s[@i].match?(/[ \t\n\r]/)
+          @s[start...@i]
+        end
+      end
+
+      def value_ok?(value)
+        v = value.to_s.strip
+        return false if v.empty? || v.length > FilterQuery::MAX_VALUE
+        return false if v.match?(/["\x00-\x1f]/)
+        # `*` and `?` still refuse, and the message points at `%`. Two spellings for
+        # one idea is how you end up with one of them silently doing nothing.
+        return false if v.match?(/[*?]/)
+        # A pattern with no literal characters matches every possible value. It is
+        # not a filter, but it renders as a pill that looks like one — the unfiltered
+        # bulk hole wearing a facet's clothing. Refused, so it selects nothing.
+        pattern = Pattern.for(v)
+        return false if pattern && (pattern.literals.zero? || pattern.too_many?)
+
+        true
+      end
+
+      def bad_value_message(key, value)
+        v = value.to_s
+        return "#{key}= needs a value. To search for the text instead: text=\"#{key}=\"" if v.strip.empty?
+        return "That #{key} filter is too long (limit #{FilterQuery::MAX_VALUE})." if v.length > FilterQuery::MAX_VALUE
+        if v.match?(/[*?]/)
+          return "Use % for a wildcard, not #{v[/[*?]/]} — for example " \
+                 "#{key}=#{v.tr('*?', '%%')}."
+        end
+        if (pattern = Pattern.for(v))
+          if pattern.literals.zero?
+            return "#{key}=#{v} matches everything, which is not a filter. Give it " \
+                   "something to match, like #{key}=Something%, or drop it."
+          end
+          if pattern.too_many?
+            return "#{key}= takes at most #{Pattern::MAX_WILDCARDS} wildcards."
+          end
+        end
+
+        "That #{key} filter contains invalid characters."
+      end
+
+      def unsupported_in(text)
+        text.split(/[ \t\n\r]+/).each do |token|
+          FilterQuery::UNSUPPORTED.each do |pattern, why|
+            return "#{why} (#{token})" if token.match?(pattern)
+          end
+        end
+        nil
+      end
+
+      def refuse(message)
+        if @out_of_scope
+          message = %(#{@out_of_scope}= does not narrow anything on this page. ) +
+                    %(Filters here: #{@keys.reject { |k| k == "text" }.join(', ')}.)
+        elsif @unknown
+          message = %(Unknown filter "#{@unknown}". Known filters: #{FilterQuery::KEYS.join(', ')}. ) +
+                    %(To search for it as text: text="#{@unknown}=…")
+        end
+        FilterQuery.refused(@s, message)
+      end
+    end
+  end
+end

data/lib/roundhouse_ui/health.rb

@@ -14,6 +14,17 @@ module RoundhouseUi
       @metrics = metrics
     end
 
+    # Signals worst-first, the same rule the Queues page sorts by: the order is
+    # information, so a failing check should never sit below a healthy one.
+    # Ties break on label, so the order is stable between polls.
+    def ranked_signals
+      signals.sort_by { |s| [ -RANK.fetch(s.status, 0), s.label.to_s ] }
+    end
+
+    def failing_count
+      signals.count { |s| s.status != :ok }
+    end
+
     def signals
       @signals ||= [ error_rate_signal, latency_signal, utilization_signal ].compact
     end
@@ -49,17 +60,45 @@ module RoundhouseUi
 
       lat = worst.latency
       status = if lat > 600 then :crit elsif lat > 60 then :warn else :ok end
-      detail = status == :ok ? "all queues fresh (< 60s)" : "#{worst.name}: oldest job #{lat.round}s"
+      detail = status == :ok ? "all queues fresh (< 60s)" : "#{worst.name}: oldest job #{RoundhouseUi.duration(lat)}"
       Signal.new(key: "latency", label: "Queue latency", status: status, detail: detail)
     end
 
+    # A fully-busy fleet is what you want. It is only a problem when the work is
+    # also backing up — so this used to cry wolf: a healthy app running flat out
+    # reported Critical, and an alarm that fires when nothing is wrong is how
+    # people learn to ignore the banner.
+    #
+    # What makes saturation bad is that it is *sustained*, and queue latency is
+    # already the memory of that: if you have been at capacity long enough to
+    # matter, the oldest job is old. So a momentary spike stays a warning and
+    # only saturation with a backlog behind it escalates — no stored history
+    # needed to tell them apart.
+    SATURATED = 1.0
+    BUSY = 0.85
+
     def utilization_signal
       util = @metrics.utilization
       return nil if util.nil? # no processes reporting in — can't judge
 
-      status = if util >= 1.0 then :crit elsif util >= 0.85 then :warn else :ok end
-      Signal.new(key: "utilization", label: "Worker utilization", status: status,
-                 detail: "#{(util * 100).round}% of worker threads busy")
+      pct = "#{(util * 100).round}% of worker threads busy"
+      return Signal.new(key: "utilization", label: "Worker utilization", status: :ok, detail: pct) if util < BUSY
+      return Signal.new(key: "utilization", label: "Worker utilization", status: :warn, detail: pct) if util < SATURATED
+
+      if falling_behind?
+        Signal.new(key: "utilization", label: "Worker utilization", status: :crit,
+                   detail: "#{pct} and queues are falling behind")
+      else
+        Signal.new(key: "utilization", label: "Worker utilization", status: :warn,
+                   detail: "#{pct} — at capacity, keeping up")
+      end
+    end
+
+    # Saturation is only critical alongside a queue that is not being kept up
+    # with, which is the same threshold the latency signal escalates on.
+    def falling_behind?
+      worst = @queues.max_by { |q| q.latency.to_f }
+      worst && worst.latency.to_f > 60
     end
   end
 end

data/lib/roundhouse_ui/history.rb

@@ -0,0 +1,54 @@
+module RoundhouseUi
+  # Daily processed and failed counts, for the one question every other number on
+  # the dashboard cannot answer: is this normal?
+  #
+  # 30,655 failures is alarming or unremarkable depending on the day, and a live
+  # throughput chart that starts empty on every page load cannot tell you which.
+  #
+  # Sidekiq already records this — `Sidekiq::Stats::History` keeps a counter per
+  # day and Roundhouse ignored it entirely. So this needs no storage of its own,
+  # no migration, and it works on every Sidekiq install. See #61.
+  Day = Struct.new(:date, :processed, :failed, keyword_init: true) do
+    # Share of the day's work that failed. The line worth drawing: counts move
+    # with traffic, so a busy Monday looks worse than a quiet Sunday even when
+    # nothing changed. A rate does not.
+    def failure_rate
+      total = processed.to_i + failed.to_i
+      return 0.0 if total.zero?
+
+      failed.to_i / total.to_f
+    end
+
+    def quiet? = processed.to_i.zero? && failed.to_i.zero?
+  end
+
+  module History
+    RANGES = { "7" => "1 week", "30" => "1 month", "90" => "3 months", "180" => "6 months" }.freeze
+    DEFAULT_DAYS = 30
+    MAX_DAYS = 180
+
+    module_function
+
+    # Oldest first, so a chart can plot it without reversing.
+    def days(count = DEFAULT_DAYS, backend: RoundhouseUi.backend)
+      return [] unless backend.respond_to?(:history) && backend.supports?(:history)
+
+      backend.history(clamp(count))
+    rescue StandardError => e
+      Rails.logger&.warn("[roundhouse] history unavailable: #{e.message}") if defined?(Rails)
+      []
+    end
+
+    def clamp(count) = count.to_i.clamp(1, MAX_DAYS)
+
+    # A baseline to compare today against. The median rather than the mean: one
+    # incident day would drag a mean up and make the following week look calm.
+    def typical_failure_rate(days)
+      rates = days.reject(&:quiet?).map(&:failure_rate).sort
+      return nil if rates.empty?
+
+      mid = rates.size / 2
+      rates.size.odd? ? rates[mid] : (rates[mid - 1] + rates[mid]) / 2.0
+    end
+  end
+end