Skip to content

feat(proxy): kamal proxy cache CLI — stats and purge - #102

Merged
mhenrixon merged 1 commit into
dashfrom
issue-99-proxy-cache-cli
Aug 3, 2026
Merged

feat(proxy): kamal proxy cache CLI — stats and purge#102
mhenrixon merged 1 commit into
dashfrom
issue-99-proxy-cache-cli

Conversation

@mhenrixon

Copy link
Copy Markdown
Collaborator

Summary

The last F4 follow-up: kamal-proxy ships a full cache admin subsystem (cache stats, cache purge) with zero gem surface — the docs pointed operators at raw proxy logs to find out why nothing was caching.

  • kamal proxy cache stats — what the cache is holding; --count measures entries/bytes per service (walks a shared store's keyspace, per the proxy's own flag help), --json for the raw report
  • kamal proxy cache purge — drops this app's cached responses, --path-prefix /assets to narrow; audited via the usual auditor record
  • Layer routing follows the layering contract: with a loadbalancer, cache policy is edge-only, so both subcommands exec on the LB container against the bare service name; without one, they run on each proxy host — purge walks every proxied role's registered service (app-web, …)
  • Docs: the cache section's "when it is not caching" guidance now starts with kamal proxy cache stats, and a new "Administering it" paragraph replaces the raw-logs-only pointer

Closes #99

Test plan

  • Command shapes on Commands::Proxy and Commands::Loadbalancer (with/without --count/--json/--path-prefix)
  • CLI routing: proxy hosts vs loadbalancer for both subcommands; flag passthrough; unknown-subcommand message
  • bundle exec rubocop --parallel clean; full unit suite green (1311 runs)
  • CI

Deviations & judgment calls

  • Purge scope is app roles only — accessories also register proxy services, but they are never LB-fronted and their cache policy is their own; purging them from an app-scoped command felt like surprise blast radius. kamal proxy cache purge walks roles_on(host).select(&:running_proxy?). If accessory purging is wanted, it fits better as an kamal accessory concern later.
  • No deploy lock on purge — it mutates the runtime cache, not deploy state, and can't race a deploy meaningfully; it does write an audit record (Purged the response cache), matching the mutation/observation split elsewhere in the file.
  • Purging a service with no cache enabled is allowed — kamal-proxy answers "Purged 0 cached responses", which is more informative than a gem-side guard.
  • --path-prefix validation is left to the proxy (it rejects prefixes not starting with / in preRun) — one validator, one error message, no drift between the two.
  • Thor options are declared once on the cache command for both subcommands (--count/--json are stats-only, --path-prefix purge-only), matching how boot_config handles its subcommand options.

## Summary

kamal-proxy ships a full cache admin subsystem with zero gem surface - the
docs pointed operators at raw proxy logs to find out why nothing was
caching. `kamal proxy cache <stats|purge>` closes the gap:

- `stats` (--count, --json) reports what the cache is holding
- `purge` (--path-prefix) drops this app's cached responses, audited

Both run on the layer that owns the cache per the layering contract: the
loadbalancer when load balancing (registered under the bare service name),
otherwise each proxy host (walking every proxied role's service). The docs'
"when it is not caching" section now starts with the stats command instead
of raw logs.

## Test Coverage

- command shapes on Commands::Proxy and Commands::Loadbalancer, with and
  without flags
- CLI routing: proxy hosts vs loadbalancer for both subcommands, flag
  passthrough, unknown-subcommand message

## Verification

- [x] bundle exec rubocop --parallel passes
- [x] unit suite passes

Closes #99
@mhenrixon
mhenrixon merged commit 6cca504 into dash Aug 3, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

kamal proxy cache CLI: stats and purge

1 participant