Documentation
¶
Overview ¶
Package rules implements the merlon rule grammar (spec §5): structured, AND-ed matchers with bypass/deny/redirect/challenge/coraza/route/queue/score actions across four phases (score nudge is phase 4 — an enum label that evaluates *before* phases 1–3, see Rule.Phase). Deliberately not an expression language; machine-checkable and UI-form-friendly. All three late action families are live: route invokes the named worker (handlers/workerrouter.go), coraza runs the embedded WAF request-phase (handlers/waf.go), and queue grants a per-rule concurrency permit (app/queues.go, handlers/waf.go).
Rule and its sub-structs are the admin-API wire shape: their json tags are admin API JSON keys — FROZEN per docs/dev/style.md, never renamed or re-spelled; the mode, action-type and sensor_state strings are the same wire-visible enums on the value side.
Index ¶
- Constants
- func DetectWS(r *http.Request) bool
- func IsReservedSiteKey(key string) bool
- func NormalizeSite(v string) string
- func ValidListName(s string) bool
- type Action
- type BotScoreCond
- type Compiled
- type Counters
- type KVMatcher
- type MatchInput
- type Matchers
- type PathMatcher
- type Rule
- type RuleCounts
- type Rulesets
- type Snapshot
Constants ¶
const ListNameGrammar = `^[a-z0-9][a-z0-9_-]{0,63}$`
ListNameGrammar is the textual form of the name grammar below. Exported because the refusal messages quoting it live in two packages (this one and adminapi's list lane): with the matcher compiled here and the message text spelled out in three places, a grammar change could ship a 400 that described a different rule than the one that fired (final-review Minor 6). The pattern is a frozen surface — docs/usage/{rules,admin-api}.md quote it verbatim — so regex and messages now read it from this one definition.
const SiteUnmatched = "unmatched host"
SiteUnmatched is the sentinel site key of Merlon's unmatched-traffic bucket (item 39, R-39-else): requests whose Host matches no configured site are rated and tallied in bot_rollups under this one honest key, so the denominator never silently excludes them. It is NOT a site — no CRUD door may store anything under it (see IsReservedSiteKey), and the WAF's unmatched arm is its only writer. The value doubles as the display label in /stats rows and the Grafana legend, rendered verbatim.
The value carries a SPACE, and the vhost hostname grammar refuses spaces (adminapi/vhosts.go validateVhostBody), so no configured site key can ever equal it and no Configured() hit can impersonate the bucket. It is also a fixed point of NormalizeSite (no port, no trailing dots, no brackets, already lowercase), so doors that fold first stay exact.
Variables ¶
This section is empty.
Functions ¶
func DetectWS ¶
DetectWS reports whether the request is a WebSocket upgrade. Two shapes: the h1 GET + `Upgrade: websocket` handshake (case-insensitive — this path also carries the deliberate h2/h3 GET-Upgrade spoof class, semantics unchanged since M1), and the RFC 8441 extended-CONNECT handshake (B9-T1 F1 gap): h2 CONNECT with the `:protocol` pseudo-header, h3 CONNECT where quic-go surfaces the protocol as r.Proto (ExtendedConnect defaults on). The EC half mirrors Caddy's own recognition so ws_upgrade rules see exactly the handshakes Caddy will proxy as WebSocket (reverseproxy.go:521-522).
func IsReservedSiteKey ¶
IsReservedSiteKey reports whether key is the reserved sentinel. Exact match on the NORMALIZED form by design: every CRUD door runs the candidate through NormalizeSite BEFORE this check, so case and trailing-dot spellings ("Unmatched Host.") have already folded to the sentinel at the door — calling this on a raw spelling is a door-ordering bug, and hiding a second fold in here would break the single-normalizer law. No store lane calls it either — the cascade never consults the sentinel (its bot_rollups skip is structural: the plane is out of the rename list whatever the site is, pinned by literal in store/cascade_test.go). That is a CALL-SITE law, not an import-graph one: store/bridge.go imports rules for the wire types (the old parenthetical here claimed the import graph, and the import graph said otherwise — backlog 63.2 honesty fix).
func NormalizeSite ¶
NormalizeSite canonicalizes a Host header or admin-supplied site path value into the single key form shared by every plane: port stripped, bracketed IPv6 literals unwrapped, case folded to lowercase. SQLite collates TEXT as BINARY and Rulesets keys are case-sensitive, so the control plane (rule CRUD) and the data plane (WAF default-site lookup) MUST funnel site keys through this function or lookups silently miss stored rules (M2 review finding C1: Host-case WAF bypass).
Item 39 (R-39-dot) amends the contract: ALL trailing dots are stripped, so a trailing-dot (fully-qualified) Host is the same site key as its bare spelling and the function stays idempotent — `foo..` → `foo`, and a lone `.` becomes `""`, which stays an honest miss. The strip order is pinned: port strip, dot strip, bracket unwrap, lowercase — order is pinned by `[::1].`, which must answer `::1` (trimming after the bracket unwrap would strand an unterminated `[::1`).
func ValidListName ¶
ValidListName reports whether s is a legal client_lists name (item 32) — the same workerNameRe grammar, exported so adminapi validates list names with a single source of truth (no second regex to drift).
Types ¶
type Action ¶
type Action struct {
Type string `json:"type"`
Policy string `json:"policy,omitempty"` // challenge only: ""|"progressive" (spec §6)
Status int `json:"status,omitempty"` // deny default 403; redirect default 302; queue: 0⇒429 | 429 | 503
URL string `json:"url,omitempty"` // required for redirect
Worker string `json:"worker,omitempty"` // route only: per-site worker name
Delta int `json:"delta,omitempty"` // score only: nudge amount, non-zero and |delta| <= 19
Reason string `json:"reason,omitempty"` // score only: free-form audit provenance, <= 200 bytes
// Profile (B9-T6) selects a named coraza rule-set profile to run the
// request through; "" runs the default engine. coraza-only: rejected
// non-empty on every other action type. The name must match the frozen
// pool grammar, but profile EXISTENCE is not validated here — profiles
// live in settings, and an unknown/removed profile fails open at request
// time exactly like a nil engine (handlers/waf.go case "coraza").
Profile string `json:"profile,omitempty"`
// queue only (B7-T6): capacity = concurrent permits (default 20),
// max_wait_ms = wait budget for a permit (default 5000), max_waiters =
// hard bound on parked arrivals (default 4×capacity, capped at 1000),
// retry_after_s = Retry-After seconds on rejection (default 5 for 429;
// a 503 rule omits the header unless set).
Capacity int `json:"capacity,omitempty"`
MaxWaitMs int `json:"max_wait_ms,omitempty"`
MaxWaiters int `json:"max_waiters,omitempty"`
RetryAfterS int `json:"retry_after_s,omitempty"`
}
Action is one of bypass | deny | redirect | challenge | coraza | route | queue | score. Coraza (M5b) is phase-2 only: the request runs through the embedded Coraza WAF when it matches; B9-T6 adds the coraza-only Profile field (named rule-set profile, "" = default). Route is phase-3 only and names the worker to invoke (Worker field, ruling R4). Queue (B7-T6) is phase-2 only — a concurrency permit with bounded waiters (design §3); its four knobs are optional (zero = unset, defaults computed at use in app/queues.go + handlers/waf.go, never stored). Score (item 32, R-32) is phase-4 (nudge) only and type⇔phase both ways: Delta shifts the effective bot score (non-zero, |delta| ≤ 19) and Reason is free-form audit provenance for it.
type BotScoreCond ¶
type BotScoreCond struct {
Min int `json:"min"`
}
BotScoreCond matches requests whose computed bot_score >= Min.
type Compiled ¶
type Compiled struct {
Rule
// contains filtered or unexported fields
}
Compiled is a validated rule with precompiled regexes/prefixes.
func Compile ¶
Compile validates and precompiles a rule. Equivalent to CompileWith with no resolver: list-free rules compile exactly as before, while any rule with a client_lists condition errors — a reference nobody resolved must not boot.
func CompileWith ¶
CompileWith validates and precompiles, resolving client_lists against lists (map list name → canonical prefixes). A named list absent from the map is a compile ERROR: a dangling reference must never compile into a rule that silently means something else (ReplaceFromWire keep-old law does the rest). Resolution arrives as a plain map so this package stays store-free; the snapshot build (T3) owns producing it from the net_lists table.
func (*Compiled) Match ¶
func (c *Compiled) Match(in MatchInput) bool
Match reports whether the input satisfies every present condition (AND).
type Counters ¶
type Counters struct {
// contains filtered or unexported fields
}
Counters accumulates per-rule match statistics in memory (M2: no SQLite rollup; restart resets them — accepted per spec §10 ephemeral state).
func (*Counters) IncObserve ¶
IncObserve records a would-have-matched observation for rule id.
func (*Counters) Snapshot ¶
func (c *Counters) Snapshot() []RuleCounts
Snapshot returns counters sorted by rule id.
type MatchInput ¶
type MatchInput struct {
R *http.Request
BotScore int // 0 when no rating handler ran
IP netip.Addr
JA4 string // lowercase JA4 string, "" when unknown
JA4H string // lowercase JA4H string, "" when unknown
JA4T string // lowercase JA4T string, "" when unknown
JA4X []string // per-element JA4X chain (internal/ja4x.Chain, chain order); nil when the lane is dark
WSUpgrade bool // advisory hint; request header detection wins when present (effective WS = hint || DetectWS(R), ruling R11)
SensorState string // Result.SensorState; "" when trust not configured — never matches a sensor_state cond
ASN uint32 // origin ASN from feeds; 0 = unknown (asn cond never matches)
Country string // lowercased ISO country from feeds; "" = unknown
}
MatchInput carries everything matchers need; the WAF handler fills it once.
type Matchers ¶
type Matchers struct {
Path *PathMatcher `json:"path,omitempty"`
Methods []string `json:"methods,omitempty"`
Header *KVMatcher `json:"header,omitempty"`
Cookie *KVMatcher `json:"cookie,omitempty"`
BotScore *BotScoreCond `json:"bot_score,omitempty"`
ClientCIDRs []string `json:"client_cidrs,omitempty"`
ClientLists []string `json:"client_lists,omitempty"` // named network lists (item 32); resolved at compile via CompileWith — existence lives outside this package
JA4Prefixes []string `json:"ja4_prefixes,omitempty"`
JA4HPrefixes []string `json:"ja4h_prefixes,omitempty"` // lowercase JA4H prefixes (MatchInput.JA4H; wired in T6)
JA4TPrefixes []string `json:"ja4t_prefixes,omitempty"` // lowercase JA4T prefixes (MatchInput.JA4T; wired in T6)
JA4XPrefixes []string `json:"ja4x_prefixes,omitempty"` // lowercase JA4X chain-element prefixes (MatchInput.JA4X, any element; M14-T4)
ASNs []uint32 `json:"asn,omitempty"` // origin ASN set (feeds)
Countries []string `json:"country,omitempty"` // ISO 3166-1 alpha-2, case-insensitive
SensorState string `json:"sensor_state,omitempty"` // absent|valid|stale|replayed (spec §5 L3)
WSUpgrade *bool `json:"ws_upgrade,omitempty"` // true|false; negation landed in M5a (ruling R11)
}
Matchers is a conjunction of conditions; an absent condition passes. At least one condition must be present (no match-all rules).
type PathMatcher ¶
type PathMatcher struct {
Exact string `json:"exact,omitempty"`
Prefix string `json:"prefix,omitempty"`
Regex string `json:"regex,omitempty"`
}
PathMatcher matches the request path; its exact, prefix and regex variants are OR-ed within the condition.
type Rule ¶
type Rule struct {
ID int64 `json:"id,omitempty"`
Site string `json:"site,omitempty"`
Position int `json:"position,omitempty"`
// Phase is an ENUM LABEL, not an evaluation order: phase-4 nudge rules
// are a pre-pass that runs BEFORE phases 1–3 (Snapshot.Nudge), so the
// integer reads after route while evaluation does not (R-32).
Phase int `json:"phase"` // 1 bypass, 2 enforce, 3 route, 4 nudge
Name string `json:"name,omitempty"`
Enabled bool `json:"enabled"`
Mode string `json:"mode"` // "enforce" (default) | "observe"
Matchers Matchers `json:"matchers"`
Action Action `json:"action"`
Version int64 `json:"version,omitempty"`
}
Rule is the wire/storage shape of one rule.
func (Rule) ActionJSON ¶
ActionJSON encodes the action sub-struct for storage.
func (Rule) MatchersJSON ¶
MatchersJSON encodes the matcher sub-struct for storage.
type RuleCounts ¶
type RuleCounts struct {
RuleID int64 `json:"rule_id"`
Observed uint64 `json:"observed"`
Actions uint64 `json:"actions"`
}
RuleCounts is one observe-counter row for the admin API.
type Rulesets ¶
type Rulesets struct {
// contains filtered or unexported fields
}
Rulesets holds per-site snapshots with atomic replacement.
func (*Rulesets) ReplaceFromWire ¶
ReplaceFromWire compiles rs and atomically swaps in the new snapshot for site with a nil list resolver (behavior-identical delegate for existing callers). See ReplaceFromWireWith for the law.
func (*Rulesets) ReplaceFromWireWith ¶
func (rs *Rulesets) ReplaceFromWireWith(site string, r []Rule, lists map[string][]netip.Prefix) error
ReplaceFromWireWith compiles rs — resolving every client_lists condition against lists (name → canonical prefixes, produced by the caller: rules stays store-free) — and atomically swaps in the new snapshot for site, bumping its generation. An empty rs clears the site's rules. The generation read, compile and swap all happen under the write lock so concurrent writers can never mint two snapshots sharing one generation.
type Snapshot ¶
type Snapshot struct {
// contains filtered or unexported fields
}
Snapshot is an immutable compiled rule set for one site. Readers get the pointer; writers replace it wholesale (spec §5 atomic hot-swap), so an immutable snapshot is safe for concurrent readers.
func NewSnapshot ¶
NewSnapshot compiles rules into a snapshot; any compile error fails the whole build. Rules are ordered by (phase, position, id). It passes a nil list resolver: list-free rules compile as always, any client_lists rule fails — a reference nobody resolved must not boot.
func (*Snapshot) Evaluate ¶
func (s *Snapshot) Evaluate(in MatchInput) (act *Compiled, observed []*Compiled)
Evaluate walks phases 1→2 only (route phase 3 is invisible to the WAF path, ruling R4; see Route; the nudge pre-pass is likewise invisible here — it lives in Nudge). Within each phase the first enabled matching rule wins that phase. An enforce-mode match acts immediately and stops evaluation (returned as act). An observe-mode match is appended to observed and evaluation continues with the next phase. Returns (nil, observed) when nothing enforces.
func (*Snapshot) Nudge ¶
func (s *Snapshot) Nudge(in MatchInput) (sum int, applied, shadow []*Compiled)
Nudge walks EVERY enabled phase-4 rule and returns the summed delta, the enforcing matches, and the observe-mode (shadow) matches. This walk is DELIBERATELY cumulative — every match contributes — deliberately inverting the house first-match-wins rule: "it's me −8" and "known scraper +6" must compose. Nudging is applied by the caller (handlers/waf.go), never here: the handler owns rating vs effective score.
func (*Snapshot) Route ¶
func (s *Snapshot) Route(in MatchInput) (act *Compiled, observed []*Compiled)
Route returns the first matching phase-3 rule (worker routing, spec §5). Phase-4 nudges are invisible here too — the nudge pre-pass lives in Nudge. Disabled and non-matching rules are skipped; observe-mode matches join observed and iteration continues past them (unlike Evaluate, which takes only the first observe match per phase).