cache_bro 0.1.0

data/app/views/cache_bro/keys/show.html.erb

@@ -0,0 +1,57 @@
+<% bro_hub_crumb "Keys", @key.truncate(60) %>
+<% content_for :bro_hub_crumb_actions do %>
+  <%= bro_hub_crumb_link "← All keys", root_path(store: cache_bro_store.name) %>
+<% end %>
+
+<%= bro_hub_hero eyebrow: "#{cache_bro_store.name} · #{cache_bro_ttl(@entry.ttl)} · #{cache_bro_size(@entry.size)}",
+      title: "Key", lead: @key %>
+
+<div class="bh-split">
+  <section class="bh-split-main">
+    <div class="bh-block-head"><h2 class="bh-h2">Value</h2></div>
+    <% if @value %>
+      <% if @value.error %>
+        <div class="bh-alert bh-alert-error">This value could not be read: <%= @value.error %></div>
+      <% else %>
+        <p class="bh-meta"><%= @value.klass %><%= " · shown up to #{number_with_delimiter(CacheBro.config.value_preview_length)} characters" if @value.truncated %></p>
+        <pre class="bh-cmd-code" style="white-space:pre-wrap;overflow-wrap:anywhere"><%= @value.preview %></pre>
+      <% end %>
+      <p class="bh-hint">This reveal was recorded in the audit log.</p>
+    <% elsif cache_bro_allows?(:view_values) %>
+      <p class="bh-hint">Values can hold personal data. Revealing one is recorded: who, which key, when.</p>
+      <%= form_with url: reveal_key_path, method: :post do %>
+        <%= hidden_field_tag :store, cache_bro_store.name %>
+        <%= hidden_field_tag :key, @key %>
+        <%= cache_bro_reason_field(:reveal) %>
+        <%= submit_tag "Reveal value", name: nil, class: "bh-btn is-auto", style: "margin-top:14px" %>
+      <% end %>
+    <% else %>
+      <p class="bh-hint">You may see that this key exists, not what it holds.</p>
+    <% end %>
+  </section>
+
+  <div class="bh-split-aside">
+    <section class="bh-block">
+      <h2 class="bh-h2">Details</h2>
+      <dl class="bh-dl">
+        <dt>Store</dt><dd><%= cache_bro_store.name %></dd>
+        <dt>Key</dt><dd><%= @key %></dd>
+        <dt>Expires</dt><dd><%= cache_bro_ttl(@entry.ttl) %></dd>
+        <dt>Size</dt><dd><%= cache_bro_size(@entry.size) %> serialized</dd>
+      </dl>
+    </section>
+
+    <% if cache_bro_allows?(:delete) %>
+      <section class="bh-block">
+        <h2 class="bh-h2">Delete</h2>
+        <p class="bh-hint">The next request that needs it will rebuild it. Recorded in the audit log.</p>
+        <%= form_with url: key_path, method: :delete do %>
+          <%= hidden_field_tag :store, cache_bro_store.name %>
+          <%= hidden_field_tag :key, @key %>
+          <%= cache_bro_reason_field(:delete) %>
+          <%= submit_tag "Delete key", name: nil, class: "bh-btn is-auto", style: "margin-top:14px;background:var(--bh-red)" %>
+        <% end %>
+      </section>
+    <% end %>
+  </div>
+</div>

data/app/views/cache_bro/purges/new.html.erb

@@ -0,0 +1,17 @@
+<% bro_hub_crumb "Purge" %>
+<%= render "cache_bro/shared/store_tabs", path: ->(name) { purge_path(store: name) } %>
+
+<%= bro_hub_hero eyebrow: cache_bro_store.name, title: "Purge", tone: :red,
+      lead: "Delete every key that matches a pattern. You see how many match before anything is deleted, and the purge is recorded." %>
+
+<% unless cache_bro_store.namespaced? %>
+  <div class="bh-alert bh-alert-error">This cache store has no namespace: a pattern can match keys that aren't the cache's. Check the preview carefully.</div>
+<% end %>
+
+<%= form_with url: purge_preview_path, method: :post, class: "bh-filters" do %>
+  <%= hidden_field_tag :store, cache_bro_store.name %>
+  <%= text_field_tag :pattern, nil, placeholder: "Pattern, e.g. posts/* or views/posts/*", class: "bh-input is-strong", "aria-label": "Pattern", required: true, autofocus: true, autocomplete: "off" %>
+  <%= cache_bro_reason_field(:purge) %>
+  <%= submit_tag "Preview", name: nil, class: "bh-chip" %>
+<% end %>
+<p class="bh-hint" style="padding:0 var(--bh-pad)">The pattern is used as typed: <code>posts/*</code> means keys starting with <code>posts/</code>. <code>*</code> is any run of characters, <code>?</code> is one.</p>

data/app/views/cache_bro/purges/preview.html.erb

@@ -0,0 +1,37 @@
+<% bro_hub_crumb "Purge", "Confirm" %>
+<% content_for :bro_hub_crumb_actions do %>
+  <%= bro_hub_crumb_link "← Change pattern", purge_path(store: cache_bro_store.name) %>
+<% end %>
+
+<%= bro_hub_hero eyebrow: "#{cache_bro_store.name} · #{@pattern}",
+      title: "#{number_with_delimiter(@matches.count)}#{"+" if @matches.truncated}",
+      subtitle: @matches.count == 1 ? "key matches" : "keys match", tone: (@matches.count.zero? ? nil : :red),
+      lead: @matches.count.zero? ? "Nothing matches. Nothing to delete." : "Nothing has been deleted yet." %>
+
+<% if @matches.count.positive? %>
+  <div class="bh-split">
+    <section class="bh-split-main">
+      <div class="bh-block-head"><h2 class="bh-h2">For example</h2></div>
+      <div class="bh-log">
+        <% @matches.sample.each do |key| %>
+          <div class="bh-cmd"><pre class="bh-cmd-code" style="white-space:pre-wrap;overflow-wrap:anywhere"><%= key %></pre></div>
+        <% end %>
+      </div>
+      <% if @matches.truncated %>
+        <p class="bh-hint is-error">More than <%= number_with_delimiter(CacheBro.config.max_purge_keys) %> keys match. One purge deletes at most that many, so run it again for the rest.</p>
+      <% end %>
+    </section>
+    <div class="bh-split-aside">
+      <section class="bh-block">
+        <h2 class="bh-h2">Delete them</h2>
+        <p class="bh-hint">The count can change by the time you confirm. What is deleted is recorded, with this pattern<%= " and your reason" if @reason %>.</p>
+        <%= form_with url: purge_path, method: :post do %>
+          <%= hidden_field_tag :store, cache_bro_store.name %>
+          <%= hidden_field_tag :pattern, @pattern %>
+          <%= hidden_field_tag :reason, @reason %>
+          <%= submit_tag "Purge #{cache_bro_count(@matches.count, "key")}#{"+" if @matches.truncated}", name: nil, class: "bh-btn is-auto", style: "margin-top:14px;background:var(--bh-red)" %>
+        <% end %>
+      </section>
+    </div>
+  </div>
+<% end %>

data/app/views/cache_bro/shared/_store_tabs.html.erb

@@ -0,0 +1,9 @@
+<%# Tabs on the right of the breadcrumb bar when there is more than one cache store. `path` builds the link for a store name. %>
+<% if CacheBro.config.store_names.size > 1 %>
+  <% current = params[:store].presence || CacheBro.config.store_names.first %>
+  <% content_for :bro_hub_crumb_actions do %>
+    <% CacheBro.config.store_names.each do |name| %>
+      <%= bro_hub_crumb_link name, path.call(name), active: name == current %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/cache_bro/shared/forbidden.html.erb

@@ -0,0 +1,3 @@
+<% bro_hub_crumb "Not allowed" %>
+<%= bro_hub_hero eyebrow: "Cache", title: "Not allowed", tone: :red,
+      lead: "You don't have permission to do that. Ask an admin if you need access." %>

data/app/views/cache_bro/shared/unsupported.html.erb

@@ -0,0 +1,3 @@
+<% bro_hub_crumb "Unsupported store" %>
+<%= render "cache_bro/shared/store_tabs", path: ->(name) { root_path(store: name) } %>
+<%= bro_hub_hero eyebrow: "Cache", title: "Can't manage this store", tone: :amber, lead: @unsupported %>

data/config/routes.rb

@@ -0,0 +1,18 @@
+CacheBro::Engine.routes.draw do
+  root "keys#index"
+
+  # Keys can contain slashes, so they travel as a parameter, not in the path.
+  get "key" => "keys#show", as: :key
+  post "key/reveal" => "keys#reveal", as: :reveal_key
+  delete "key" => "keys#destroy"
+
+  get "purge" => "purges#new", as: :purge
+  post "purge/preview" => "purges#preview", as: :purge_preview
+  post "purge" => "purges#create"
+
+  get "flush" => "flushes#new", as: :flush
+  post "flush" => "flushes#create"
+
+  get "audit" => "audit_events#index", as: :audit
+  get "audit/:id" => "audit_events#show", as: :audit_event
+end

data/db/migrate/20261115130000_create_cache_bro_audit_events.rb

@@ -0,0 +1,25 @@
+class CreateCacheBroAuditEvents < ActiveRecord::Migration[7.1]
+  def change
+    create_table :cache_bro_audit_events do |t|
+      t.string :event, null: false
+      t.string :user_label
+      t.string :environment, null: false
+      t.string :store, null: false
+
+      # The key (reveal, delete) or the pattern (purge). Empty for a flush.
+      t.text :target
+      # How many keys the action touched.
+      t.integer :count
+      t.text :reason
+
+      # No column default: MySQL rejects defaults on JSON columns. Audit.record always sets it.
+      t.json :details, null: false
+
+      t.datetime :created_at, null: false
+    end
+
+    add_index :cache_bro_audit_events, :created_at
+    add_index :cache_bro_audit_events, [ :event, :created_at ]
+    add_index :cache_bro_audit_events, [ :user_label, :created_at ]
+  end
+end

data/lib/cache_bro/audit.rb

@@ -0,0 +1,25 @@
+module CacheBro
+  # Records who did what in CacheBro::AuditEvent. Keys and patterns are recorded, never values.
+  module Audit
+    module_function
+
+    # target: the key, or the pattern. count: how many keys the action touched.
+    def record(event, user:, store:, target: nil, count: nil, reason: nil, **details)
+      attributes = {
+        event: event.to_s,
+        user_label: user.is_a?(String) ? user : CacheBro.config.user_label.call(user).to_s,
+        environment: Rails.env.to_s,
+        store: store.to_s,
+        target: target,
+        count: count,
+        reason: reason.presence,
+        details: details.deep_stringify_keys
+      }
+      CacheBro::AuditEvent.create!(**attributes)
+    rescue StandardError => error
+      # The action already happened (or, for a reveal, is about to be refused): at least leave a trace in the log.
+      Rails.logger&.error("CacheBro: could not write the audit log (#{error.class}: #{error.message}). Entry: #{attributes.inspect}")
+      raise
+    end
+  end
+end

data/lib/cache_bro/configuration.rb

@@ -0,0 +1,113 @@
+module CacheBro
+  class Configuration
+    # --- Who may do what ------------------------------------------------------------------
+
+    # Permission checks, each ->(user) { true/false }. Everything is denied until you change them.
+    #   can_view_keys   - open CacheBro, search keys, see TTL and size
+    #   can_view_values - reveal what a key holds (every reveal is audited)
+    #   can_delete      - delete a single key
+    #   can_purge       - delete every key matching a pattern (includes delete)
+    #   can_flush       - delete everything in a store's namespace (includes purge and delete)
+    #   can_audit       - read the audit log
+    #
+    # Higher permissions include the lower ones, so you don't have to repeat yourself.
+    # Revealing values and auditing are separate on purpose: values can hold personal data.
+    attr_accessor :can_view_keys, :can_view_values, :can_delete, :can_purge, :can_flush, :can_audit
+
+    PERMISSIONS = %i[ view_keys view_values delete purge flush audit ].freeze
+
+    # Permissions that also grant the key.
+    IMPLIED_BY = {
+      view_keys: %i[ view_values delete purge flush ],
+      view_values: [],
+      delete: %i[ purge flush ],
+      purge: %i[ flush ],
+      flush: [],
+      audit: []
+    }.freeze
+
+    # Actions that can require a reason.
+    ACTIONS = %i[ reveal delete purge flush ].freeze
+
+    # --- Which caches ---------------------------------------------------------------------
+
+    # { "Name" => -> { store } }. The name appears in the UI and the audit log. Stores that aren't a
+    # Rails :redis_cache_store are listed as unsupported.
+    attr_accessor :stores
+
+    # --- Limits ---------------------------------------------------------------------------
+
+    # SCAN COUNT hint per Redis call, and how many calls one page of search results may spend before it
+    # hands you a cursor to keep going. Redis scans the whole keyspace either way, in small steps.
+    attr_accessor :scan_count, :scan_budget
+
+    # A page of keys is "at least this many" (a SCAN step can return a few more).
+    attr_accessor :page_size
+
+    # A single purge deletes at most this many keys, then says so and stops. Run it again to continue.
+    attr_accessor :max_purge_keys
+
+    # Characters of a value shown after revealing it.
+    attr_accessor :value_preview_length
+
+    # How many affected keys the audit log keeps as an example for a purge or flush.
+    attr_accessor :audit_sample_size
+
+    # Which actions need a reason typed in (stored in the audit log): any of :reveal, :delete, :purge, :flush.
+    attr_accessor :reason_required_for
+
+    # --- Hosting --------------------------------------------------------------------------
+
+    # Controller the engine controllers inherit from (gives access to your authentication).
+    attr_accessor :parent_controller
+
+    # ->(controller) { user or nil }. Defaults to BroHub.config.current_user, so configuring BroHub once is enough.
+    attr_accessor :current_user
+
+    # ->(user) { "label" } shown in the UI and stored in the audit log. Defaults to BroHub.config.user_label.
+    attr_accessor :user_label
+
+    # Refuse plain HTTP requests.
+    attr_accessor :require_ssl
+
+    def initialize
+      @can_view_keys = ->(_user) { false }
+      @can_view_values = ->(_user) { false }
+      @can_delete = ->(_user) { false }
+      @can_purge = ->(_user) { false }
+      @can_flush = ->(_user) { false }
+      @can_audit = ->(_user) { false }
+
+      @stores = { "Rails.cache" => -> { Rails.cache } }
+
+      @scan_count = 500
+      @scan_budget = 200
+      @page_size = 100
+      @max_purge_keys = 100_000
+      @value_preview_length = 5_000
+      @audit_sample_size = 25
+      @reason_required_for = %i[ purge flush ]
+
+      @parent_controller = "::ApplicationController"
+      @current_user = ->(controller) { BroHub.config.current_user.call(controller) }
+      @user_label = ->(user) { BroHub.config.user_label.call(user) }
+      @require_ssl = defined?(Rails) && Rails.respond_to?(:env) ? Rails.env.production? : false
+    end
+
+    # Does the user hold this permission, directly or through a higher one?
+    def allows?(user, permission)
+      return false if user.nil?
+      raise ArgumentError, "Unknown permission #{permission.inspect}" unless PERMISSIONS.include?(permission)
+
+      [ permission, *IMPLIED_BY.fetch(permission) ].any? { |name| !!public_send(:"can_#{name}").call(user) }
+    end
+
+    def reason_required?(action)
+      Array(reason_required_for).map(&:to_sym).include?(action.to_sym)
+    end
+
+    def store_names
+      stores.keys.map(&:to_s)
+    end
+  end
+end

data/lib/cache_bro/engine.rb

@@ -0,0 +1,25 @@
+module CacheBro
+  class Engine < ::Rails::Engine
+    isolate_namespace CacheBro
+
+    # Cache values and the reason people type are never worth logging.
+    initializer "cache_bro.filter_parameters" do |app|
+      app.config.filter_parameters += %i[ reason ]
+    end
+
+    # The UI is a section of the BroHub dashboard. Registered before routes are drawn, so BroHub can mount this
+    # engine under <hub>/cache_bro. Showing a section is navigation only: every controller authorizes each request.
+    initializer "cache_bro.bro_hub" do
+      BroHub.register :cache_bro,
+        name: "CacheBro", label: "CacheBro · cache", accent: :blue, order: 30,
+        engine: "CacheBro::Engine",
+        visible_to: ->(user) { CacheBro.config.allows?(user, :view_keys) || CacheBro.config.allows?(user, :audit) },
+        items: [
+          { label: "Keys", path: "/", match: %r{\A/(key(/|\z)|\z)}, visible_to: ->(user) { CacheBro.config.allows?(user, :view_keys) } },
+          { label: "Purge", path: "/purge", match: %r{\A/purge}, visible_to: ->(user) { CacheBro.config.allows?(user, :purge) } },
+          { label: "Flush", path: "/flush", visible_to: ->(user) { CacheBro.config.allows?(user, :flush) } },
+          { label: "Audit log", path: "/audit", match: %r{\A/audit}, visible_to: ->(user) { CacheBro.config.allows?(user, :audit) } }
+        ]
+    end
+  end
+end

data/lib/cache_bro/errors.rb

@@ -0,0 +1,29 @@
+module CacheBro
+  class Error < StandardError; end
+
+  # The person lacks a permission.
+  class NotAllowed < Error; end
+
+  # config.stores has no store with that name.
+  class UnknownStore < Error; end
+
+  # The store isn't one CacheBro can manage (only Redis for now), or is set up in a way it can't handle.
+  class UnsupportedStore < Error; end
+
+  # Destructive actions need a reason (see config.reason_required_for).
+  class ReasonRequired < Error; end
+
+  # A pattern the action refuses (empty, or everything).
+  class InvalidPattern < Error; end
+
+  # A purge or flush failed part way (Redis went away, say). `matches` is what was deleted before that,
+  # so the audit log can still say so. The original error is `cause`.
+  class SweepFailed < Error
+    attr_reader :matches
+
+    def initialize(message, matches)
+      super(message)
+      @matches = matches
+    end
+  end
+end

data/lib/cache_bro/redis_store.rb

@@ -0,0 +1,220 @@
+module CacheBro
+  # Everything CacheBro does to one Rails :redis_cache_store.
+  #
+  # Keys are shown without the store's namespace, and every key the person types is put back under it, so
+  # nothing outside the namespace can be reached. Redis is only ever walked with SCAN (never KEYS), in small steps.
+  class RedisStore
+    Entry = Struct.new(:key, :ttl, :size, keyword_init: true)
+
+    # One page of search results. `cursor` is where to continue (nil when the whole keyspace was covered).
+    Listing = Struct.new(:entries, :cursor, keyword_init: true) do
+      def more? = !cursor.nil?
+    end
+
+    # What a pattern matches (or, after a purge, what it deleted). `truncated`: there are more than the limit.
+    Matches = Struct.new(:count, :sample, :truncated, keyword_init: true)
+
+    # A revealed value: what it is, and as much of it as is safe to render. `error` when it couldn't be read.
+    Value = Struct.new(:klass, :preview, :truncated, :error, keyword_init: true)
+
+    REDIS_CACHE_STORE = "ActiveSupport::Cache::RedisCacheStore".freeze
+
+    # Looked up by name so nothing is loaded (and no redis gem is required) for apps on another store.
+    def self.supports?(cache)
+      cache.class.ancestors.any? { |klass| klass.name == REDIS_CACHE_STORE }
+    end
+
+    attr_reader :name
+
+    def initialize(name, cache)
+      @name = name.to_s
+      @cache = cache
+      unless self.class.supports?(cache)
+        raise UnsupportedStore, "#{@name} is a #{cache.class.name}. CacheBro manages Redis cache stores (:redis_cache_store) for now."
+      end
+      raise UnsupportedStore, "#{@name} spreads keys over several Redis servers. CacheBro needs a single one." if distributed?
+    end
+
+    def namespace
+      value = @cache.options[:namespace]
+      value = value.call if value.respond_to?(:call)
+      value.to_s.presence
+    end
+
+    def namespaced?
+      !namespace.nil?
+    end
+
+    # --- Reading --------------------------------------------------------------------------
+
+    # Searches keys. Plain text matches anywhere in the key, `*` and `?` make it a pattern. One call walks part of
+    # the keyspace: pass the returned cursor back in to continue.
+    def list(query: nil, cursor: "0")
+      config = CacheBro.config
+      cursor = cursor.to_s
+      raws = []
+      calls = 0
+
+      entries = with_redis do |redis|
+        loop do
+          cursor, batch = redis.scan(cursor, match: search_match(query), count: config.scan_count)
+          raws.concat(batch)
+          calls += 1
+          break if cursor == "0" || raws.size >= config.page_size || calls >= config.scan_budget
+        end
+        describe(redis, raws)
+      end
+
+      Listing.new(entries: entries, cursor: (cursor == "0" ? nil : cursor))
+    end
+
+    # TTL and size of one key (nil when it doesn't exist).
+    def stat(key)
+      raw = prefix + key
+      ttl, size = with_redis { |redis| stats_for(redis, [ raw ]).first }
+      build_entry(key, ttl, size)
+    end
+
+    # What the key holds, for display. Never raises for a value that can't be read: that is shown instead.
+    def read(key)
+      value = @cache.read(key)
+      text = value.inspect
+      limit = CacheBro.config.value_preview_length
+      Value.new(klass: value.class.name, preview: text.first(limit), truncated: text.length > limit)
+    rescue StandardError => error
+      Value.new(klass: nil, preview: nil, truncated: false, error: "#{error.class}: #{error.message.first(300)}")
+    end
+
+    # --- Deleting -------------------------------------------------------------------------
+
+    def delete(key)
+      with_redis { |redis| redis.unlink(prefix + key) }
+    end
+
+    # How many keys the pattern matches, up to `limit`.
+    def preview(pattern)
+      sweep(purge_match(pattern), limit: CacheBro.config.max_purge_keys, delete: false)
+    end
+
+    # Deletes the keys matching the pattern, at most config.max_purge_keys of them.
+    def purge(pattern)
+      sweep(purge_match(pattern), limit: CacheBro.config.max_purge_keys, delete: true)
+    end
+
+    # Deletes everything under the namespace. Refused without one: that would be the whole Redis database.
+    def flush
+      raise UnsupportedStore, "#{name} has no namespace, so flushing it would touch keys that aren't the cache's. Set `namespace:` on the cache store." unless namespaced?
+
+      sweep("#{glob_escape(prefix)}*", limit: nil, delete: true)
+    end
+
+    private
+      def with_redis(&)
+        @cache.redis.then(&)
+      end
+
+      def distributed?
+        with_redis { |redis| redis.respond_to?(:nodes) }
+      end
+
+      def prefix
+        namespaced? ? "#{namespace}:" : ""
+      end
+
+      # Redis glob: * ? [ ] and \ are special. Everything but the wildcards is matched literally.
+      def glob_escape(text)
+        text.gsub(/[\\*?\[\]]/) { |char| "\\#{char}" }
+      end
+
+      # Only * and ? are wildcards for people. [ ] and \ stay literal, so a key like "a[1]" can be found.
+      def with_wildcards(text)
+        text.gsub(/[\\\[\]]/) { |char| "\\#{char}" }
+      end
+
+      def pattern?(text)
+        text.match?(/[*?]/)
+      end
+
+      def search_match(query)
+        text = query.to_s.strip
+        return "#{glob_escape(prefix)}*" if text.empty?
+
+        pattern?(text) ? "#{glob_escape(prefix)}#{with_wildcards(text)}" : "#{glob_escape(prefix)}*#{glob_escape(text)}*"
+      end
+
+      # Purge patterns are used as typed (so "posts/*" is a prefix), never widened.
+      def purge_match(pattern)
+        text = pattern.to_s.strip
+        raise InvalidPattern, "Give a pattern, like posts/*" if text.empty?
+        raise InvalidPattern, "That matches everything. Use Flush for that." if text.match?(/\A\*+\z/)
+
+        "#{glob_escape(prefix)}#{with_wildcards(text)}"
+      end
+
+      # The key as people see it: valid text, without the namespace. Nil for keys that aren't text.
+      def display_key(raw)
+        key = raw.dup.force_encoding(Encoding::UTF_8)
+        key.delete_prefix(prefix) if key.valid_encoding?
+      end
+
+      def describe(redis, raws)
+        raws = raws.uniq.select { |raw| display_key(raw) }
+        return [] if raws.empty?
+
+        raws.zip(stats_for(redis, raws)).filter_map { |raw, (ttl, size)| build_entry(display_key(raw), ttl, size) }
+      end
+
+      def build_entry(key, pttl, size)
+        return if pttl.nil? || pttl == -2 # gone since it was found, or not a cache entry
+
+        Entry.new(key: key, ttl: (pttl / 1000.0 if pttl >= 0), size: size)
+      end
+
+      # [ [ pttl, bytes ], ... ] in one round trip. A key holding something other than a string (a shared Redis
+      # database) makes the pipeline fail, so fall back to asking one by one and leaving those out.
+      def stats_for(redis, raws)
+        redis.pipelined { |pipeline| raws.each { |raw| pipeline.pttl(raw); pipeline.strlen(raw) } }.each_slice(2).to_a
+      rescue ::Redis::CommandError
+        raws.map { |raw| redis.type(raw) == "string" ? [ redis.pttl(raw), redis.strlen(raw) ] : [ nil, nil ] }
+      end
+
+      # Walks the keyspace for `match`, optionally deleting what it finds, stopping at `limit` keys.
+      # A failure part way raises SweepFailed with what was done so far.
+      def sweep(match, limit:, delete:)
+        count = 0
+        sample = []
+        truncated = false
+        sample_size = CacheBro.config.audit_sample_size
+
+        catch(:done) do
+          with_redis do |redis|
+            cursor = "0"
+            loop do
+              cursor, batch = redis.scan(cursor, match: match, count: CacheBro.config.scan_count)
+              batch = batch.uniq
+              unless batch.empty?
+                room = limit ? limit - count : batch.size
+                if room <= 0
+                  truncated = true
+                  throw :done
+                end
+                taken = batch.first(room)
+                truncated = taken.size < batch.size
+                redis.unlink(*taken) if delete
+                count += taken.size
+                sample.concat(taken.filter_map { |raw| display_key(raw) }.first(sample_size - sample.size)) if sample.size < sample_size
+                throw :done if truncated
+              end
+              break if cursor == "0"
+            end
+          end
+        end
+
+        Matches.new(count: count, sample: sample, truncated: truncated)
+      rescue StandardError => error
+        raise error if error.is_a?(CacheBro::Error)
+
+        raise SweepFailed.new("#{error.class}: #{error.message}", Matches.new(count: count, sample: sample, truncated: truncated))
+      end
+  end
+end

data/lib/cache_bro/version.rb

@@ -0,0 +1,3 @@
+module CacheBro
+  VERSION = "0.1.0"
+end

data/lib/cache_bro.rb

@@ -0,0 +1,43 @@
+require "bro_hub"
+require "cache_bro/version"
+require "cache_bro/errors"
+require "cache_bro/configuration"
+require "cache_bro/redis_store"
+require "cache_bro/audit"
+require "cache_bro/engine"
+
+# = CacheBro
+#
+# Browse, inspect and purge a Rails Redis cache from the BroHub dashboard.
+#
+# * Search keys (TTL, size), reveal a value, delete a key, purge a pattern, flush a namespace.
+# * Permissions are lambdas, like the other Bro gems. Revealing values is its own permission.
+# * Everything that reveals or deletes is recorded, append-only, with who, what, how many and (optionally) why.
+#
+# This is a convenience for people who already have a console, not a sandbox: it makes the same actions easier
+# to do and impossible to do unrecorded through the UI.
+module CacheBro
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_config!
+      @config = nil
+    end
+
+    # The store with that name (the first one when nil), wrapped for CacheBro.
+    # Raises UnknownStore, or UnsupportedStore for a cache that isn't a Redis cache store.
+    def store(name = nil)
+      name = name.presence&.to_s || config.store_names.first
+      source = config.stores.find { |key, _| key.to_s == name }&.last
+      raise UnknownStore, "No cache store named #{name.inspect}" unless source
+
+      RedisStore.new(name, source.respond_to?(:call) ? source.call : source)
+    end
+  end
+end