waf

type Action int

type EvalEvent struct {
	// Request is the request that was evaluated. The hook may read it (e.g. to
	// derive a custom label) but must not mutate it; prom.WAF ignores it.
	Request *http.Request
	// Outcome is how evaluation terminated. Bounded; safe as a metric label.
	Outcome Outcome
	// Duration is the wall time spent evaluating rules — the SAME span as
	// MatchEvent.Elapsed. It is time.Since(start) where start is taken AFTER
	// body buffering, Country/ASN lookup and request-map construction, measured
	// at the terminating decision point BEFORE the request is handed to the next
	// handler. It therefore EXCLUDES client body I/O, geo/ASN/map-build cost, and
	// downstream-handler latency, and measures rule evaluation only.
	Duration time.Duration
}

type FailMode int

type Logger interface {
	Logf(format string, args ...any)
}

type LoggerFunc func(format string, args ...any)

type MatchEvent struct {
	Request *http.Request
	RuleID  string
	Action  Action
	// Status is the rule's configured Status field (defaulted to 403 when
	// the rule didn't set one). It is the HTTP status that *would be*
	// returned for an ActionBlock match; for ActionLog and ActionAllow it
	// carries the configured value but does not describe the actual response.
	Status     int
	Expression string
	ClientIP   string
	// Elapsed is the time spent inside the WAF up to and including this
	// match — i.e. evaluating every rule that ran before this one plus the
	// matching rule itself. It is NOT the per-rule evaluation latency.
	Elapsed time.Duration
}

type ObserveFunc func(EvalEvent)

type Outcome uint8

type Rule struct {
	// ID is a stable identifier used in logs. Required.
	ID string

	// Description is an optional human-readable summary recorded in match logs.
	Description string

	// Expression is a CEL expression that must evaluate to bool.
	// See package docs for the available variables and functions.
	Expression string

	// Action determines what to do when the expression returns true.
	Action Action

	// Status is the HTTP status returned for ActionBlock matches.
	// Defaults to 403 Forbidden when zero.
	Status int

	// Message is the response body for ActionBlock matches. Defaults to a
	// generic "Forbidden" string. Returned as text/plain.
	Message string

	// Priority controls evaluation order; lower values run first.
	// Allowlist rules should typically have the smallest Priority so they
	// short-circuit before any block rules are considered.
	Priority int
}

type WAF struct {
	// Logger receives one line per matched rule. nil disables logging.
	Logger Logger

	// OnMatch is invoked for every rule that fires (any Action). Optional.
	// Runs synchronously on the request goroutine — keep it cheap.
	OnMatch func(MatchEvent)

	// Observe is invoked exactly once per request that reaches rule evaluation,
	// after evaluation terminates, with the terminal Outcome and the rule-eval
	// Duration. Optional. Runs synchronously on the request goroutine just
	// before the request is forwarded or rejected — keep it cheap. Unlike
	// OnMatch (per matched rule, only on a match), it fires on every path, so it
	// answers "how much does the WAF cost per request". Wire prom.WAF() here for
	// a latency histogram. The no-rules fast path does NOT call Observe (no
	// evaluation happened).
	Observe func(EvalEvent)

	// EvalTimeout is the per-request deadline for evaluating the entire
	// ruleset. Defaults to 5ms. A timeout treats the request as Allow
	// (i.e. fails open) but logs the error — this is the safer default for
	// a reverse proxy because failing closed during a config bug would
	// drop legitimate traffic. Override with FailMode to change behaviour.
	EvalTimeout time.Duration

	// CostLimit caps CEL evaluator cost per rule. 0 = use defaultCostLimit.
	// Set explicitly to a smaller number when running untrusted rules.
	CostLimit uint64

	// FailMode controls behaviour when a rule errors at evaluation time
	// (panic recovered, timeout, cost exceeded, type mismatch).
	// Default is FailOpen: error rules are skipped and the request continues.
	FailMode FailMode

	// DisableMacros prevents rules from using all/exists/filter/map/etc.
	// when set to true. Recommended when rules come from less-trusted sources.
	DisableMacros bool

	// InspectBody enables body inspection up to N bytes. 0 = body is empty
	// in expressions (request.body == ""). The buffered body is restored
	// to r.Body so downstream handlers can still read it.
	InspectBody int64

	// Country resolves the client's ISO 3166-1 alpha-2 country code for a
	// request, exposed to rules as `request.country` (e.g. for GeoIP filtering:
	// `request.country == "TH"`). The WAF stays storage-agnostic — the caller
	// supplies the lookup (a GeoIP database, an edge header, etc.). nil leaves
	// `request.country` as the empty string; the field is always present in the
	// map, so a rule referencing it never errors on a missing key.
	Country func(r *http.Request) string

	// ASN resolves the client's autonomous system number for a request,
	// exposed to rules as `request.asn` (e.g. for ASN filtering:
	// `request.asn == 13335`). The WAF stays storage-agnostic — the caller
	// supplies the lookup (an IP-to-ASN database, an edge header, etc.). nil
	// leaves `request.asn` as 0; the field is always present in the map, so a
	// rule referencing it never errors on a missing key. The value is an int64
	// (not uint) so rules compare against plain CEL integer literals; valid
	// ASNs fit losslessly, and 0 — reserved by RFC 7607 — means unresolved.
	ASN func(r *http.Request) int64
	// contains filtered or unexported fields
}