Documentation
¶
Overview ¶
Package badgergc provides a small standalone Caddy app module that periodically runs Badger's value-log garbage collection on the *same* in-process *badger.DB handle that Souin's badger storage already holds open.
Souin (the Caddy HTTP cache) stores its cache in a Badger value-log DB. Badger never reclaims dead value-log space on its own — RunValueLogGC has to be called explicitly — so a long-lived cache steadily accumulates garbage vlog files (tens of gigabytes in our case) that never shrink. This module reclaims that space with zero downtime and no fork of Souin.
It works because darkweak/storages exports everything we need:
- github.com/darkweak/storages/core → core.GetRegisteredStorers() []Storer
- github.com/darkweak/storages/badger → *badger.Badger, whose embedded *badger.DB is the very handle Souin opened.
Compiled into the same Caddy binary as Souin, the type assertion resolves to the identical type, so we reuse Souin's own handle: no second Open(), no lock fight, and RunValueLogGC (which Badger serializes internally and is designed to run alongside live traffic) does its work with zero contention.
The storer set is re-resolved from the registry on every tick, so a Souin config reload (which calls ResetRegisteredStorages and reopens the DB) can't leave us pinned to a closed handle — a stale handle just yields an error and we move on to the next cycle.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type App ¶
type App struct {
// Interval is how often to run a GC sweep. Default: 10m.
Interval caddy.Duration `json:"interval,omitempty"`
// DiscardRatio is passed to Badger's RunValueLogGC: a value-log file is
// rewritten only if it can discard at least this fraction of its space.
// Must be in (0.0, 1.0). Default: 0.5.
DiscardRatio float64 `json:"discard_ratio,omitempty"`
// MaxRewritesPerSweep caps how many value-log files a single sweep will
// rewrite (across all Badger storers), spreading a large backlog -- e.g. the
// tens of gigabytes reclaimed on the first sweep after deploy -- across
// several ticks instead of one long, I/O-heavy sweep. 0 (default) means no
// cap: reclaim everything reclaimable each sweep.
MaxRewritesPerSweep int `json:"max_rewrites_per_sweep,omitempty"`
// contains filtered or unexported fields
}
App is the badger_gc Caddy app. It runs a single background goroutine that, on a fixed interval, walks every registered Souin storer and — for each one backed by Badger — runs value-log GC until Badger reports nothing left to reclaim.
func (App) CaddyModule ¶
func (App) CaddyModule() caddy.ModuleInfo
CaddyModule returns the Caddy module information. badger_gc is a top-level app module (not an HTTP handler), so its ID has no dotted namespace prefix.
func (*App) Start ¶
Start launches the background GC goroutine and immediately confirms whether it is actually attached to a Badger storer. Caddy provisions every app (including Souin's HTTP handler, which registers the badger storer) before it starts any app, so by the time Start runs the storer is already in the registry -- letting us surface the SILENT-NO-OP case at deploy time instead of one interval later. A no-op almost always means this module was built against storages/badger versions that differ from the running binary (so the *badger.Badger assertion never matches) or Souin isn't using the badger backend.
func (*App) Stop ¶
Stop signals the background goroutine to exit AND waits (bounded) for it to actually return. Blocking here is deliberate: on a config reload Caddy stops the old app before the new Souin reopens the DB, so if we returned while a sweep were still running we could leave the OLD goroutine calling RunValueLogGC on a handle the new Souin is closing/reopening -- the exact race we otherwise only paper over with recover(). The sweep loop checks `done` between value-log rewrites, so this wait is normally near-instant; the timeout only guards a single in-flight file rewrite that cannot be interrupted.