feat(pipeline): Structured rejections + lifecycle hooks + plugin spec docs

[huang195]

Summary

Hardens the plugin-pipeline contract ahead of exposing it to third-party plugin authors. Three landing points:

1. Rejection contract (breaking for anyone manually constructing Action{Reject, ...}): replaces flat Action.Status/Action.Reason with a structured *Violation, adds default body synthesis, custom headers/body overrides, CPEX-aligned fields (Code, Reason, Description, Details, PluginName), and helper constructors (Deny, DenyStatus, DenyWithDetails, Challenge, RateLimited).
2. Plugin lifecycle hooks (additive, opt-in): optional Initializer / Shutdowner interfaces with Pipeline.Start(ctx) / Pipeline.Stop(ctx) driving them. Existing plugins are unaffected — the interfaces are opt-in via type-assertion.
3. Docs: the full pipeline spec at authbridge/authlib/pipeline/README.md now covers both new surfaces, with a worked RateLimiter example exercising Init, Shutdown, and the RateLimited helper. The cpex-bridge integration spec in the same file got its CPEX↔authbridge mapping table updated — the two Violation shapes are now near-isomorphic. Also includes a new abctl walkthrough at authbridge/demos/weather-agent/demo-with-abctl.md.

Motivated by the plugin-interface gap analysis discussed in-session; fulfills must-fix #1 (richer rejection) and #3 (lifecycle hooks) from that list.

New plugin shape (what this enables)

type ContentFilter struct {
    model  *classifier
    metric prometheus.Counter
}

// Lifecycle: safe place to load model + register metrics before traffic flows.
func (p *ContentFilter) Init(ctx context.Context) error {
    p.model = classifier.Load("/models/pii-v2")
    p.metric = prometheus.NewCounter(...)
    return prometheus.DefaultRegisterer.Register(p.metric)
}

func (p *ContentFilter) OnResponse(ctx context.Context, pctx *pipeline.Context) pipeline.Action {
    if p.model.ContainsPII(pctx.ResponseBody) {
        p.metric.Inc()
        // Rejection: structured reason + details, plus automatic plugin-name
        // attribution in the response body ("plugin":"content-filter").
        return pipeline.DenyWithDetails("policy.content-blocked",
            "Response redacted due to PII",
            map[string]any{"rule": "no_pii", "classifier_version": "v2"})
    }
    return pipeline.Action{Type: pipeline.Continue}
}

func (p *ContentFilter) Shutdown(ctx context.Context) error { return p.model.Close() }

Previously impossible without sync.Once-inside-OnRequest and goroutine leaks at shutdown.

Behaviors fixed / improved

Before	After
Each listener hardcoded the error code ("unauthorized", "response_blocked", etc.) regardless of plugin intent	Plugin sets Violation.Code; listener passes through
TestExtProc_Outbound_Deny asserted 503 because the listener forced it, hiding the plugin's actual 401	Plugin's status (401 for "no token available") flows through — test now asserts 401
Plugin-name was lost by the time the body reached the client	Violation.PluginName auto-stamped by pipeline from Plugin.Name(); default body includes "plugin": "<name>"
Custom headers (WWW-Authenticate, Retry-After) had nowhere to go	All four listeners preserve Violation.Headers through their respective wire formats
No place for a plugin to load a model, warm a cache, or register metrics	Init(ctx) called before listeners accept traffic, fail-fast with named plugin
No place for a plugin to flush / close on SIGTERM	Shutdown(ctx) called after listeners drain, reverse order, best-effort

Test plan

• go test ./... in authlib — all green (18 new tests across action + lifecycle)
• go test ./... in cmd/authbridge — all green; one test assertion corrected to reflect the now-correct pass-through status behavior
• go test ./... in cmd/abctl — unaffected, all green
• Built authbridge-envoy image locally (podman build -f cmd/authbridge/Dockerfile), loaded into kind, rolled the weather-agent pod, verified pod reaches Ready and chat requests flow through unchanged

Files changed

File	Purpose
pipeline/action.go	New Action/Violation shape + 5 helpers + codeToStatus + Render()
pipeline/action_test.go	13 tests
pipeline/plugin.go	Added Initializer, Shutdowner optional interfaces
pipeline/pipeline.go	Start(ctx) / Stop(ctx); internal cancellation uses Deny(); auto-stamps PluginName
pipeline/pipeline_test.go	5 new lifecycle tests + migration of existing tests to new shape
pipeline/README.md	§5 rewritten, §6 extended, §10 CPEX mapping updated, §12 versioning entries, §13 cross-refs
plugins/jwtvalidation.go	Uses DenyStatus with status→code derivation
plugins/tokenexchange.go	Same shape; picks between upstream.token-exchange-failed and policy.forbidden
plugins/plugins_test.go	Updated 4 assertions to Violation.Render()
listener/extproc/server.go	rejectFromAction helper preserves headers via HeaderMutation.SetHeaders
listener/extproc/server_test.go	One assertion corrected to reflect correct pass-through behavior
listener/extauthz/server.go	deniedFromAction helper for the DeniedResponse path
listener/forwardproxy/server.go	writeRejection helper
listener/reverseproxy/server.go	responseRejectedError now carries the full Action; writeRejection helper
cmd/authbridge/main.go	Start(initCtx) after pipeline construction; Stop(shutdownCtx) in SIGTERM path

Related

• Branch still includes two earlier doc-only commits (pipeline spec, abctl walkthrough) that live alongside this work. Happy to split into separate PRs if reviewers prefer — say the word.
• Must-fixes feature: Remove initContainer and Replace it with Kagenti Sidecar Containers #4 (observability conventions) and Add Helm Chart and CI/CD Pipeline #5 (testing harness) to follow in separate PRs.

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

[pdettori]

Well-structured PR that hardens the plugin-pipeline contract with a rich rejection model (Violation struct, helpers, code-to-status table) and opt-in lifecycle interfaces. The code is clean, backward-compatible for existing plugins, and comprehensive in test coverage (18 new tests). All four listeners consistently use Render() for reject handling, eliminating the prior inconsistency where each listener hardcoded different error codes.

Areas reviewed: Go (pipeline, plugins, listeners, main.go), Docs
Commits: 4 commits, all signed-off (DCO: pass)
CI status: All 17 checks passing

[pdettori]

suggestion: Start fails fast on Init error but does not call Shutdown on plugins whose Init already succeeded. If plugin A allocates resources in Init and plugin B's Init fails, A leaks. The contract is documented ("No Shutdown is invoked — the intent is hard-fail on startup, not unwind") so this is a known design choice, and since main.go calls log.Fatalf the process exits anyway (OS reclaims resources). Worth considering an unwind for a future iteration where Start callers might want to retry or recover rather than exit.

[pdettori]

nit: Multi-statement on one line (status, _, _ := action.Violation.Render(); if status != ...) is valid Go but unconventional — consider splitting to two lines for readability.