feat(ai-moderation): shared ctx flag so stacked moderation plugins can short-circuit duplicate vendor calls

[janiussyafiq]

Context

APISIX currently ships moderation plugins that target the AI request/response path:

• ai-aws-content-moderation (priority 1050)
• ai-aliyun-content-moderation (priority 1029)
• ai-lakera-guard (priority 1028, proposed in feat: add ai-lakera-guard plugin for prompt injection and PII detection #13291)

They all run in the access and lua_body_filter phases.

Problem

When an operator configures multiple moderation plugins on the same route (defense-in-depth), each plugin independently calls its own vendor API for every request and every streaming body chunk. There is no shared signal that another moderation plugin has already decided "this content is OK" or "this content is flagged." Concrete consequences:

1. Vendor calls are additive — 2× or N× cost per request and per buffer flush.
2. Last-flagger-wins deny body shape. Each lua_body_filter plugin reads original upstream content from ctx.var.llm_response_text / ctx.llm_response_contents_in_chunk regardless of earlier plugins' body rewrites, makes its own independent flag decision, and rewrites the body if it flags. When multiple plugins flag, the client sees whichever plugin's deny shape ran last (Aliyun-shaped one moment, Lakera-shaped the next).
3. Operators get neither pass nor block coordination. No "fast pass" (skip remaining vendors on clean) nor "first block wins" (skip remaining vendors on flag).

Proposed design

Introduce shared ctx.var signals consumed by all moderation plugins:

• ctx.var.ai_moderation_decided (boolean) — set to true by the first plugin that produces a verdict, clean or flagged.
• ctx.var.ai_moderation_flagged (boolean) — set to true by the first plugin that flags.

Each moderation plugin gains a config knob coordinate_with_siblings: bool, default false to preserve current independent-scan behavior (no breaking change for existing setups). When set true:

• If ai_moderation_decided is already true, the plugin skips its scan and inherits the prior decision.
• If ai_moderation_flagged is true, the plugin lets the earlier plugin's deny shape stand (or returns its own — design decision worth a sub-discussion).
• If clean, the plugin lets the request through without calling its vendor.

Out of scope

Cross-vendor verdict reconciliation (e.g., Aliyun says clean but Lakera says flag — should the operator be alerted to disagreement, treated as flagged, treated as clean?). That's a follow-up if anyone deploys this pattern at scale and reports concrete needs.

Discovered

While designing the composition behavior for ai-lakera-guard (tracking issue: #13291); applies generally to any pair of moderation plugins stacked on the same route.

[janiussyafiq]

Closing this as not-planned — the problem framing was incorrect, and what's left after the correction isn't strong enough to justify the feature.

Correction: there is no "last-flagger-wins"

I claimed that each lua_body_filter plugin reads original content from ctx.var.llm_response_text, makes its own decision, rewrites the body if it flags, and the client sees whichever plugin's deny shape ran last. That's not what the dispatcher actually does.

apisix/plugin.lua:1488-1512 exits the entire response-filter phase as soon as any plugin's lua_body_filter returns a non-nil code — including (ngx.OK, body), because 0 is truthy in Lua:

local code, new_body = phase_func(conf, api_ctx, headers, body)
if code then
    if code ~= ngx_ok then
        ngx.status = code
    end
    ngx_print(new_body)
    ngx_exit(ngx_ok)    -- terminates the request; subsequent plugins never run
end

So the actual semantics are first-flagger-wins: the highest-priority plugin runs first, and if it flags, the dispatcher exits — every lower-priority plugin is skipped, never calls its vendor, and never gets a chance to "win." I verified this empirically by drafting the stacked-moderation test I had originally planned (ai-aliyun-content-moderation at 1029 + ai-lakera-guard at 1028) and observing that only the aliyun mock logged a scan request when both would have flagged; the lakera mock was never hit.

What's left of the original motivation

After removing the bogus "last-flagger-wins" framing, the only real residual problem is:

Additive vendor cost on the clean path when an operator stacks two moderation plugins.

That's true, but it's a weak motivation for plugin-internal coordination machinery:

• Operators who stack two moderation plugins implicitly opted in to paying both vendors on clean requests.
• If cost matters, the natural answer is to not stack — pick one primary, or order by cost ascending and accept the additive cost as the price of defense-in-depth.
• On the flagged path (which is typically the more interesting cost concern) the dispatcher already short-circuits — additional vendors don't get called.

A coordinate_with_siblings flag plus shared ai_moderation_decided ctx vars introduces real complexity (per-plugin opt-in, ordering rules, what happens if two flag, how to expose disagreement, etc.) for a fairly narrow optimization. Not worth carrying.

If anyone hits this in the future

The current first-flagger-wins behavior is sensible and well-defined. If you actually need both vendors' verdicts visible (observability, A/B comparison, etc.), a much lighter approach is per-plugin action: alert modes that log/observe but never inject a deny — no dispatcher coordination needed. Both ai-lakera-guard and ai-aliyun-content-moderation already support this pattern.