Configuration
Every field of weir.Config with its default and range, rendered from the technical specification.
Configuration is one Go struct, weir.Config. Every field is optional and the zero value is valid. This table is rendered at build time from section 6 of the technical specification, which is the normative source.
On Caddy the same settings are Caddyfile keys; the Caddy guide lists which ones the directive exposes.
All fields are optional. The zero value of Config is valid and yields the defaults below.
| Field | Default | Notes |
|---|---|---|
Store | memory store, 16 shards (halved, down to 1, while a shard's small queue could not hold Storable.MaxObjectBytes, so the zero Config stays valid under a small GOMEMLIMIT), size per D35: 40% of GOMEMLIMIT clamped to [16 MiB, 8 GiB], or 256 MiB with a warning when GOMEMLIMIT is unset | engine closes it on Close only if it created it |
Key.QueryDrop, Key.QueryKeep | empty | patterns, trailing * allowed |
Key.QuerySort | false | |
Key.NormalizePath | false | |
Key.Headers, Key.Cookies | empty | deny by default. Key.Headers may name Accept-Encoding (the key then holds the bucket, §5.2.3); names that are never forwarded are rejected (FR-LCY-1) |
Key.Vary | VaryAuto | or VaryStrict |
Key.VaryAllow | empty | required for sensitive Vary names |
Key.MaxVaryHeaders / Key.MaxVariants | 8 / 8 | |
Key.AcceptEncoding | ["gzip"] | set to what the origin produces, e.g. ["br","gzip"] |
Forward.Mode | ForwardStrict | ForwardAll logs a warning |
Forward.Allow | empty | operator additions, on top of the trace defaults. New rejects an entry that names a Key.Headers field (it already goes, in its keyed form) or a field that is never forwarded (FR-LCY-1) |
Forward.NoTraceHeaders | false | D29: true stops forwarding traceparent, tracestate, X-Request-Id (a boolean, because nil-versus-empty slices do not survive JSON or Caddyfile round trips) |
Bypass.Cookies, Bypass.Headers | empty | |
Storable.Statuses | 200, 203, 204, 300, 301, 302, 307, 308, 404, 405, 410, 414, 501 | 302/307 need explicit freshness (D39) |
Storable.MaxObjectBytes | 1 MiB | body plus headers |
Storable.StripSetCookie | false | |
Freshness.Jitter | 0.10 | range [0, 0.5] |
Freshness.JitterMinLifetime | 10 s | |
Freshness.NoJitter, NoEarlyRefresh | false | |
Freshness.EarlyRefreshBeta | 1.0 | |
Freshness.HeuristicFraction / HeuristicMax | 0.1 / 1 h | |
Freshness.DefaultTTL | 0 | |
Freshness.DefaultStaleWhileRevalidate / DefaultStaleIfError | 0 / 0 | decision D6 |
Freshness.Keep | 5 min | extra retention after the last stale window, only for entries with a validator, so an expired entry can still be revalidated with a cheap 304 instead of refetched (the memory store evicts it earlier under pressure) |
Coalesce.LeaderMaxAge / FollowerMaxWait | 10 s / 10 s | a default is lowered to Timeouts.Origin when that is shorter; an explicit value above it is rejected (FR-LCY-1) |
Coalesce.HitForMissTTL | 30 s | |
Limiter.MaxConcurrent / MaxQueue / MaxQueueWait | 64 / 1024 / 2 s | |
Limiter.MaxPerPartition | 16 | |
Limiter.ReserveForeground | 25% of MaxConcurrent | at least 1 from 2 slots; an explicit value at or above MaxConcurrent is rejected (FR-LCY-1) |
Breaker.Window / MinRequests / FailureRatio | 10 s / 20 / 0.5 | |
Breaker.OpenFor / MaxOpenFor / HalfOpenProbes | 5 s / 60 s / 1 | MaxOpenFor defaults to OpenFor when that is longer |
Breaker.CountStatus500 | false | |
Breaker.Disable | false | |
Negative.TTL | 2 s | Negative.Disable turns it off |
MissRate.Window / TopK / MinMisses / MinRatio | 10 s / 64 / 500 / 0.9 | MinRatio above 1 is rejected: no partition could reach it |
MissRate.Throttle | false | |
MissRate.Disable | false | |
CacheGroups.Ignore | false | RFC 9875 honored by default. Set, it switches off Cache-Group-Invalidation (FR-INV-2); Cache-Groups is still read (FR-STO-10) |
Client.HonorRevalidation | false | decision D5 |
Timeouts.Origin / Background / Store | 30 s / 30 s / 50 ms | |
Warm.Concurrency | 4 | a default is lowered to MaxConcurrent − ReserveForeground when that is smaller; an explicit value above it is rejected (FR-LCY-1) |
Limiter.MaxPerHost | 0 (off) | M14; the Caddy adapter sets 25% for multi-host sites |
Limiter.MaxUpload | 25% of MaxConcurrent | D25, separate pool for requests with a body |
Timeouts.StreamIdle | 60 s | D26 |
Bypass.ReportStrippedCookies | 5 min | D31; a negative value disables |
Experiments.Cookie, Experiments.Header | weir_v, Weir-Variant | docs/10 §3. The header name has no underscore and is not a reserved name (T-35) |
Experiments.MaxActive | 4 | at most 8 |
Experiments.SigningKeys | none | required when experiments are configured: 1 to 4 keys of 32 to 256 bytes, the first signs and all verify |
Limits.* | see FR-VAL-1, FR-VAL-3, FR-STO-10 | |
CacheStatus | "Weir" | member name |
NoCacheStatus | false | true omits the header |
Observer | nil | |
Logger | discard handler | |
Rand | rand.Float64 from math/rand/v2 | test hook; must return [0, 1) and be safe for concurrent use |
Reading the table
- A setting written
A / Blists two fields with their defaults in the same order. - "D" numbers such as D6 are recorded design decisions; "FR" numbers are requirements. Both link to the specification.
- Fields that reverse a protective default are explained on the tuning page.
weir.New validates the whole struct and returns an error wrapping ErrInvalidConfig for a value out of range or a combination that cannot work, such as a Forward.Allow entry that names a keyed header. It never silently corrects a value you set.