waf: add waf.events read API + collector.setWAFEvents contract#131
Open
acoshift wants to merge 2 commits into
Open
waf: add waf.events read API + collector.setWAFEvents contract#131acoshift wants to merge 2 commits into
acoshift wants to merge 2 commits into
Conversation
Contract leg of SPEC-waf-events: WAF.Events (sampled match events, newest-first, ULID keyset pagination via Before/Next, rule/action filters) and Collector.SetWAFEvents (append-only, ULID-deduped, synchronous — events have no healing second source). Shared caps and per-field length limits live in constraint.go for the apiserver's server-side validation. Wire field names are pinned by test against the engine's cursor-endpoint Event.
Review fixes: - Export ValidWAFEventID so the apiserver applies the same cursor-shape check to item IDs at ingest that the client applies to Before — a stored off-alphabet id would come back as Next and then wedge pagination when echoed as Before (spec §E.2 amended to reference it). - Trim Action and Before in WAFEvents.Valid() alongside RuleID; §G blesses hand-editing the query params these map onto. - Pin WAFEvent/WAFEventsResult JSON field names (console/MCP/CLI consume them by name), matching the existing collector-item wire pin.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Types-only contract PR for the WAF events feature (workstream #2 in SPEC-waf-events.md §J):
Collector.SetWAFEvents+WAF.Eventsinterfaces, request/response types withValid(), constants, and client methods. No server logic lives here.What
Collector.SetWAFEvents(collector.setWAFEvents) — internal ingest contract for sampled WAF match events shipped from the controller's event ring (CollectorSetWAFEvents/CollectorWAFEventItem). Documented as synchronous server-side: events have no healing second source, so the collector advances its ring cursor only on success.WAF.Events(waf.events,waf.getpermission) — read API (WAFEvents/WAFEventsResult/WAFEvent) with rule/action filters, keysetBeforecursor (id < beforeover controller-minted ULIDs),Table()for CLI output.constraint.go: page limits (default 50 / max 200), batch cap (5000), per-string item caps,WAFEventIDLength, and exportedValidWAFEventIDso the apiserver enforces the exact same cursor shape (26-char uppercase Crockford ULID) at ingest that the client enforces onBefore— a stored off-alphabet id would otherwise come back asNextand wedge pagination when echoed asBefore(spec §E.2 references this helper).collectorClient/wafClientfollowing the existing invoke pattern.Wire format matches the engine side exactly (moonrhythm/parapet-ingress-controller#182,
wafevent.Event): shared JSON namesid/at/ruleId/action/status/clientIp/country/asn/method/host/path; engine-onlyzoneand collector-addedprojectId(string-encoded) are the documented deltas. Wire-pin tests lock both the collector item and the read-API event field names.Spec:
SPEC-waf-events.md(§D contract, §E.2 ingest validation, §J rollout).Tests
gofmtclean;go build ./... && go vet ./... && go test ./...green — 65 tests in 2 packages. New coverage: request validation table (required/enum/case/limit/cursor-shape/trim),ValidWAFEventIDalphabet cases,Table()incl. empty result, wire pins forCollectorWAFEventItem(12 fields,projectIdstring encoding) andWAFEvent/WAFEventsResult(11 + 2 fields). All example data uses documentation IPs (203.0.113.0/24) — no real event data.Rollout (spec §J — every step inert alone)
WAF_EVENTS_TOKENSecret (PR 182; endpoint off until both envs set, inert until polled)waf_eventsDDL migration before binary (house rule), thencollector.setWAFEvents+waf.events+ mountssyncWAFEvents, enabled viawaf_events_target+waf_events_tokenenvs (unset = off, binary can ship early)Gate: downstream repos re-pin this module only after the tag; new interface methods break implementers at compile time on upgrade, per the established pattern.
Expected merge conflicts with open sibling branches
Branched from
origin/main; two other WAF branches are open and append to the same spots — whichever merges second gets trivial append-append conflicts:waf.go(WAF interface method + tail-of-file types afterWAFLimitMetricsSeries),client/waf.go(tail afterLimitMetrics),constraint.go(WAF constants block)constraint.go(same WAF constants block)All are additive; resolution is keep-both.