feat: BAN ACL + handler (#39)

[jensens]

Summary

spec.invalidation.ban was wired through the CRD + webhook validator but never reached the generated VCL. Users who set ban.enabled: true saw the field accepted on the CR and their allowedSources CIDRs validated, but BAN requests fell through to the regular cache-miss path — never invalidating anything.

Fix

When spec.invalidation.ban.enabled: true:

• vinyl_ban_allowed ACL is emitted containing:
  • 127.0.0.1 (always)
  • the operator pod IP (when set — invalidation-proxy source, via #40)
  • entries from spec.invalidation.ban.allowedSources
• vcl_recv BAN handler:
  • 403 if client.ip not in vinyl_ban_allowed
  • 400 if the X-Vinyl-Ban header is missing
  • ban(req.http.X-Vinyl-Ban) + synth(200, "Banned") otherwise

Default behaviour is unchanged — when ban.enabled is unset/false, neither the ACL nor the handler are emitted.

Usage

spec:
  invalidation:
    ban:
      enabled: true
      allowedSources:
        - "10.0.0.0/8"

# From any IP in the ACL:
curl -X BAN -H 'X-Vinyl-Ban: obj.http.X-Cache-Tag ~ "user-42"' http://varnish.svc/

Tests

• TestGenerate_BAN_DisabledByDefault — ACL + handler absent when disabled.
• TestGenerate_BAN_EnabledEmitsACLAndHandler — both present, correct shape.
• TestGenerate_BAN_OperatorIPInACL — operator IP lands in BAN ACL too.
• TestGenerate_BAN_AllowedSourcesHonored — user CIDRs present.
• TestGenerate_BAN_EnabledButNotConfigured_OnlyLocalhost — minimal ACL shape.

Full go test ./... green.

Out of scope

• Rate limiting (spec.invalidation.ban.rateLimitPerMinute): still inert. Left as follow-up in the issue — needs decision on mechanism (Varnish-side vmod_ratelimit vs. operator-proxy-side). BAN expressions are idempotent so unchecked rate is usually fine, but production may want enforcement.
• Docs: no new how-to yet. The CRD reference table documents the field; a how-to example can follow.
• E2E chainsaw test: the e2e Varnish image is agent-only (no real Varnish), so end-to-end BAN exercising isn't possible in CI today.

Closes #39

🤖 Generated with Claude Code

[jensens]

Critical fixes from end-to-end review pushed in ed5b06f. Scope expanded beyond BAN-only:

Critical (were blockers for v0.4.2):

• C1 (was in feat: include operator pod IP in vinyl_purge_allowed ACL (#18) #40 but only discovered now): cmd/operator/main.go now reads POD_IP from env and sets Reconciler.OperatorIP. The field existed but was never populated → the ACL plumbing from feat: include operator pod IP in vinyl_purge_allowed ACL (#18) #40 was a production no-op.
• C2: BAN handler uses std.ban() + std.ban_error() (the project's architecture docs required this — I had emitted the deprecated bare ban()). Malformed expressions now return 400 with the compiler error instead of silently 200-ing.

Important:

• Ban-lurker-friendly x-url/x-host headers are now also emitted when HasBAN (previously only HasXkey). Prevents the O(n*m) ban accumulation pattern when users write ban("obj.http.x-url ...") with xkey disabled.
• Template whitespace trim on the BAN block.
• Reference docs updated: BAN fields documented, shard.by/healthy note clarified (cluster-peer auto, per-backend user-snippet), security caveat + X-Vinyl-Ban usage example added.

Test tightening:

• BAN-handler test extracts the handler block and asserts on that substring (tighter).
• Regression guard: bare ban(req.http...) must never be emitted.
• New TestGenerate_BAN_BanLurkerHeadersEmitted and TestGenerate_BAN_RateLimit_CurrentlyInert.

Flake:

• vcl-validation cleanup timeout bumped from default (30s) to 60s — the context deadline exceeded CI fail was the same symptom from before v0.4.0.

Still deferred (noted as future work):

• spec.invalidation.ban.rateLimitPerMinute enforcement — needs design decision (Varnish vmod_vsthrottle vs operator-proxy-side).
• Cluster-peer behaviour change (C3 from the review): by=HASH / healthy=CHOSEN as defaults instead of the previous hardcoded by=URL. This will go into the v0.4.2 release notes as a user-observable change.

CI rerun incoming.