feat(pipeline): Add Finisher lifecycle hook for stateful plugin cleanup

[huang195]

Summary

Adds pipeline.Finisher, an optional lifecycle hook that lets stateful
plugins pair OnRequest acquires with guaranteed releases — fired
once per request regardless of whether the pipeline allowed, denied,
or errored.

Closes the "cleanup leaks on denial" class of bugs flagged in
Evaline Ju's plugin-framework feedback: a rate-limiter that reserves
a slot in OnRequest and releases in OnResponse silently leaks
whenever a later plugin denies, because OnResponse is only walked on
pipelines that returned Continue. Same shape hits audit plugins
(orphaned "request started" events), distributed tracers (unclosed
spans), and any plugin that holds a lease across phases. Today no
in-tree plugin is stateful on response so the gap is latent — that
makes it a framework correctness trap worth resolving before a
second stateful plugin ships.

API

type Finisher interface {
    OnFinish(ctx context.Context, pctx *Context)
}

type Outcome struct {
    FinalAction   OutcomeAction  // allow | deny | error
    StatusCode    int
    DenyingPlugin string
    Duration      time.Duration
}

Plugins that implement Finisher get OnFinish called once per
request. The dispatcher walks in LIFO over plugins whose OnRequest
actually ran (including the denier, if any). Stateless plugins don't
implement the interface; the dispatcher skips them. During
OnFinish, pctx.Outcome() returns a non-nil *Outcome carrying
the terminal state; everywhere else the getter returns nil.

Canonical use:

func (p *RateLimiter) OnRequest(_ context.Context, pctx *pipeline.Context) pipeline.Action {
    tenant := pctx.Identity.ClientID()
    p.slots.Reserve(tenant)
    pipeline.SetState(pctx, "rate-limiter", &rlState{tenant: tenant})
    return pipeline.Action{Type: pipeline.Continue}
}

func (p *RateLimiter) OnFinish(ctx context.Context, pctx *pipeline.Context) {
    s, ok := pipeline.GetState[*rlState](pctx, "rate-limiter")
    if !ok { return }
    p.slots.Release(s.tenant)
    p.metrics.RecordOutcome(pctx.Outcome().FinalAction)
}

Design decisions

Answers to the 9 design questions worked through in the pre-
implementation discussion:

#	Question	Answer
1	Timing	Always fires after OnResponse if it ran. One release site, not an error-only hook.
2	API shape	Separate opt-in interface. Symmetric with Initializer / Shutdowner / Readier.
3	Participation	Only plugins whose OnRequest actually ran. Includes the denier.
4	Outcome visibility	pctx.Outcome() getter returns non-nil ONLY during OnFinish. Consistent (ctx, pctx) signature; namespaced to avoid god-struct drift.
5	Context	Fresh ctx from context.Background() with a framework-set deadline (DefaultFinishTimeout = 2s, WithFinishTimeout overrides). Client disconnect never cancels cleanup I/O.
6	Dispatch order	LIFO, consistent with Shutdowner and RunResponse.
7	State	Full pctx including response body. Framework holds the buffer through the finish window.
8	Errors	Best-effort: panic recovered per plugin, LIFO chain continues. One misbehaving plugin cannot leak state in every other plugin.
9	Invocations	OnFinish is silent. pctx.Record / SetBody / SetResponseBody dropped with WARN logs (SessionEvent is published, response on the wire).

Commits

1. feat(pipeline): Add Finisher hook for stateful plugin cleanup — interface + Outcome + dispatcher + full godoc; framework-only, no listener changes (dormant until listeners wire it). Tests: 13 unit tests in finisher_test.go covering LIFO, participation, outcome visibility, panic recovery, fresh-ctx-not-cancelled, deadline, off-policy skip, non-Finisher skip, Record-drop, SetBody-drop. Docs: framework-architecture.md §6 "Per-request finish hook", §12 versioning entry, §13 cross-reference; plugin-reference.md "Finishing requests (stateful plugins)" section.

2. feat(listener): Wire RunFinish in all four listeners — one defer per listener (reverseproxy, forwardproxy, extauthz, extproc) with an OutcomeFromContext helper keeping each wiring to a one-liner. Holder.RunFinish delegate. End-to-end integration test in reverseproxy/finisher_test.go verifying the allow path, the deny path, and the "non-dispatched plugins don't get OnFinish" contract.

Risk assessment

Behavior change for existing chains: none. No in-tree plugin implements Finisher, so RunFinish walks an empty subset of pctx.dispatched and returns. The only per-request cost is one atomic Holder.Load + the no-op RunFinish body.

Test plan

• go test -race ./... in authbridge/authlib — passes
• go test -race ./... in authbridge/cmd/authbridge — passes
• gofmt -l on touched files — clean (unrelated pre-existing drift in session.go / session_test.go not touched)
• Unit: 13 dispatcher tests + 6 OutcomeFromContext cases
• Integration: reverseproxy Allow + Deny end-to-end with stub Finisher plugins
• -race detector clean

Out of scope (possible followups)

• Reference rate-limiter plugin using Finisher — would be the first in-tree consumer and a concrete example. Deferred because arbitration design is orthogonal (in-memory vs distributed, per-tenant vs global).
• Per-request Duration accounting in Invocation — the Outcome.Duration derived in RunFinish is available; exposing it as part of the existing Invocation vocabulary is a separate design choice.
• Surface OnFinish failures back to operators — today a panicking OnFinish is logged at WARN but not exposed in /v1/sessions. If operators need to debug sink-down conditions, adding a per-plugin finish-failure count to /stats is a small follow-on.

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

[esnible]

Careful design, thorough tests, and honest scope discipline (out-of-scope items called out explicitly in the PR body). Framework-only change with no behavior impact on existing chains since no in-tree plugin implements Finisher. The 9 design-decision table in the PR description shows the trade-offs were worked through before coding. LIFO walk, panic recovery, fresh-but-values-preserving context (via WithoutCancel + WithFinishTimeout), and the double-call guard are all in place and covered by the 13 unit tests plus the reverseproxy allow/deny integration tests.

Areas reviewed: Go (pipeline/*, 4 listener servers, 13 unit tests, 1 integration test), Go docs
Commits: 3 commits, all signed off (DCO passes)
CI status: All required checks pass