Plugin Ecosystem

80 Built-in Plugins

Every capability built in, tested together, and executed in a deterministic priority pipeline — no plugin marketplace roulette, no version matrices.

Authentication Authorization WAF Rate Limiting AI / LLM Governance Agent Gateways Service Mesh Transformation Testing Observability

Deterministic Pipeline

Plugins execute in priority order (lower runs first) through bands: early traffic control → authentication → authorization & admission → transformation → response → logging. Ordering is predictable and documented.

Protocol Aware

Each plugin declares which protocols it supports — HTTP, gRPC, WebSocket, TCP, UDP — and the gateway automatically skips plugins that don't apply to the current request's protocol.

Three Scopes

Global applies to all proxies, proxy to one, and proxy_group shares a single stateful instance (e.g. one rate-limit budget) across a set of proxies. Scoped plugins override global ones of the same name.

🔐 Authentication — 10 plugins

Establish who is calling. Multiple authentication plugins can run on one proxy in first-match mode, and consumers can hold multiple active credentials of the same type for zero-downtime rotation.

mtls_auth

Priority: 950

Mutual TLS client certificate identity mapping to consumers, with per-proxy CA filtering. Works on HTTP and raw TCP/UDP streams.

HTTPTCPUDP

jwks_auth

Priority: 1000

Multi-provider JWKS JWT validation with claim-based authorization, optional mTLS certificate binding, single-use DPoP proof checks (RFC 9449), and claim header fan-out.

HTTPgRPC

oauth2_introspection

Priority: 1050

RFC 7662 bearer token introspection with multi-provider routing, token caching, scope/role checks, and claim header injection.

HTTPgRPC

oidc_relying_party

Priority: 1075

Full browser login: authorization code + PKCE, encrypted gateway sessions, ID token validation, optional UserInfo merge, and logout. Gateway-managed SSO for web apps.

HTTP

jwt_auth

Priority: 1100

Stateless HS256 JWT validation with a shared secret and configurable claim fields. Simple and fast for internal services.

HTTPgRPCWebSocket

key_auth

Priority: 1200

API key lookup via header or query parameter with per-consumer keys, credential hiding, and rotation support. Zero-copy credential resolution keeps it effectively free.

HTTPWebSocket

ldap_auth

Priority: 1250

LDAP / Active Directory authentication via direct bind or search-then-bind, with optional AD group filtering and result caching.

HTTP

basic_auth

Priority: 1300

HTTP Basic Authentication with HMAC-SHA256 password verification and per-consumer credentials.

HTTP

hmac_auth

Priority: 1400

Versioned request signature verification with body integrity protection and single-use nonce replay defense — each accepted request can never be replayed.

HTTPReplay-Proof

soap_ws_security

Priority: 1500

WS-Security validation for SOAP: UsernameToken, X.509 signature verification, SAML 2.0 assertion validation, timestamp freshness, and nonce replay protection.

HTTPEnterprise

🛡 Authorization & Admission — 7 plugins

Decide what an authenticated (or anonymous) caller may do, and protect backends from being overwhelmed.

access_control

Priority: 2000

Consumer and group-based allow/deny lists. Consumers declare ACL group membership; proxies match on allowed or disallowed groups.

HTTPgRPCStreams

opa

Priority: 2080

Open Policy Agent authorization via the OPA Data API — centralize policy in Rego with fail-closed defaults and request-header redaction.

HTTPgRPC

ip_restriction

Priority: 150

IP allow/deny lists with CIDR support, applied before authentication for zero-cost blocking across every protocol.

HTTPTCPUDP

geo_restriction

Priority: 175

GeoIP country allow/deny lists using MaxMind database files — enforce data residency and sanctions boundaries at the edge.

HTTPTCPUDP

bot_detection

Priority: 200

User-Agent pattern blocking with allowlist support — keep scrapers and unwanted automation off your backends.

HTTP

tcp_connection_throttle

Priority: 2050

Caps active TCP connections per consumer or client IP with leak-free permit tracking for the connection lifetime.

TCP

adaptive_concurrency

Priority: 2090

Target-aware backend admission control — shrinks per-target in-flight limits when latency or failures rise, protecting backends before they collapse.

HTTPgRPCWebSocket

⏳ Rate & Size Limits — 6 plugins

Bound request volume and payload size per protocol. Rate limiting supports centralized Redis-backed coordination across gateway instances (Redis, Valkey, DragonflyDB, KeyDB, or Garnet).

rate_limiting

Priority: 2900

Per-IP or per-consumer limits with configurable windows, optional response headers, and centralized Redis mode with fail-closed or local-fallback policies.

HTTPgRPCStreams

ws_rate_limiting

Priority: 2910

Per-connection frame rate limiting with a token bucket; closes with code 1008 on sustained violation. Optional Redis-externalized counters.

WebSocket

udp_rate_limiting

Priority: 2915

Per-client-IP datagram and byte rate limiting for UDP proxies, with centralized Redis support.

UDP

request_size_limiting

Priority: 2800

Per-proxy request body size limits with a Content-Length fast path plus buffered body verification. Returns 413 early.

HTTPgRPC

response_size_limiting

Priority: 3490

Per-proxy response body size limits — stop oversized upstream responses before they reach clients.

HTTP

ws_message_size_limiting

Priority: 2810

Enforces maximum WebSocket frame and reassembled-message sizes, closing with code 1009 on violation.

WebSocket

🔒 Security & Validation — 5 plugins

Inspect content for threats and enforce API contracts before traffic touches your backends.

waf

Priority: 2930

Content-pattern threat detection: SQLi, NoSQLi, XSS, command/template injection, Log4Shell, path traversal, SSRF, XXE, and response-side data-leak rules. Paranoia levels, monitor/enforce posture, WebSocket message inspection, and optional raw TCP/UDP inspection.

HTTPWebSocketTCPUDP

security_headers

Priority: 4080

Injects response security headers with safe defaults plus opt-in HSTS, CSP, and Permissions-Policy; strips fingerprinting headers like Server and X-Powered-By.

HTTP

cors

Priority: 100

Cross-Origin Resource Sharing with configurable origins, methods, headers, and preflight caching.

HTTP

body_validator

Priority: 2950

JSON Schema, XML, and gRPC protobuf validation of request and response bodies — reject malformed payloads at the edge.

HTTPgRPC

openapi_validator

Priority: 2960

Request/response contract enforcement generated from attached OpenAPI or Swagger specs, with block, log-only, and disabled modes plus emergency bypass.

HTTP

🤖 AI / LLM / Agents — 14 plugins

A complete AI gateway: provider routing with streaming, cost control, safety guardrails, compliance capture, and gateways for MCP tool servers and Agent-to-Agent traffic. Provider formats auto-detected for OpenAI, Anthropic, Google Gemini, Cohere, Mistral, and AWS Bedrock.

ai_federation

Priority: 4060

OpenAI-compatible AI gateway routing to 11 providers (OpenAI, Anthropic, Gemini/Vertex, Azure OpenAI, Bedrock, Mistral, Cohere, xAI, DeepSeek, Meta Llama, Hugging Face) with model mapping, priority fallback, and per-provider circuit breakers.

AI GatewayHTTP

ai_stream_router

Priority: 2984

Streaming counterpart to federation: routes "stream": true requests to the matched provider and normalizes provider-native SSE (Anthropic, Gemini) to OpenAI chunk events — true end-to-end streaming, no buffering.

AI GatewaySSE

ai_semantic_firewall

Priority: 2968

Semantic request/response firewall: prompt injection, jailbreaks, system-prompt exfiltration, data-exfiltration intent, tool abuse, and topic allow/deny policy — with dry-run rollout.

SecurityHTTP

ai_semantic_cache

Priority: 4057

LLM response caching with normalized exact-match keys and optional embedding-based semantic similarity — serve repeat questions without paying the provider twice.

Cost SavingsHTTP

ai_rate_limiter

Priority: 4200

Token-aware rate limiting per consumer or IP with pre-request reservation and response reconciliation. Redis-coordinated budgets across gateway instances.

Cost ControlHTTP

ai_token_metrics

Priority: 4100

Extracts prompt/completion/total token usage from LLM responses — including streaming — into transaction metadata for cost attribution and observability.

ObservabilityHTTP

ai_request_guard

Priority: 2975

Request policy: model allow/block lists, max_tokens enforcement (reject or clamp), message count and prompt length limits, temperature ranges, system-prompt blocking.

HTTP

ai_prompt_shield

Priority: 2925

PII detection in prompts — SSN, credit cards, emails, phone numbers, API keys, AWS keys, IBAN, plus custom patterns — with reject, redact, or warn actions.

PrivacyHTTP

ai_prompt_compressor

Priority: 4055

Bounded, model-free prompt compression that preserves code blocks, URLs, numbers, identifiers, and negations — cut token spend without an external service.

Cost SavingsHTTP

ai_response_guard

Priority: 4075

Output-side guardrails: PII detection in responses, blocked phrase filtering, and response format validation — including gRPC response inspection for enrolled methods.

GuardrailsHTTP

ai_tool_governor

Priority: 2978

Deterministic allow/deny/redact/approval policy for AI tool and function calls — by name, arguments, JSON Schema, regex, risk, and identity — enforced on buffered and streaming responses, with an optional approval webhook.

Agent SafetyHTTP

ai_transcript_audit

Priority: 2740

Compliance-grade AI payload capture: redacted excerpts, canonical hashes, model/provider and token metadata, sampling rules, and async batched export to your collector.

ComplianceHTTP

mcp_gateway

Priority: 2992

MCP / Agent Tool Gateway for JSON-RPC MCP traffic: transparent proxying, aggregate discovery across servers, namespaced tool routing, session mediation, argument validation, and mcp.* metadata for downstream policy.

AgentsSSE

a2a_gateway

Priority: 2993

Agent-to-Agent gateway for JSON-RPC, REST, and gRPC A2A traffic: method detection and policy, Agent Card URL rewriting, streaming-safe pass-through, and a2a.* metadata.

AgentsgRPC

🏳 Traffic Control & Protocol — 13 plugins

Shape, test, mirror, mock, and route traffic — including protocol-specific handling for gRPC, GraphQL, and Server-Sent Events.

request_termination

Priority: 125

Return static responses without proxying — maintenance mode, kill switches, and staged rollouts.

HTTP

response_mock

Priority: 3030

Configurable mock responses by method and path pattern with status, headers, body, and latency simulation — with optional passthrough for unmatched requests. Ideal for contract testing and local development.

HTTPTesting

fault_injection

Priority: 2940

Probabilistic aborts and latency injection for HTTP/gRPC, TCP connect rejection/delay, and UDP session/datagram faults — chaos-test your clients' resilience.

HTTPTCPUDPChaos

request_mirror

Priority: 3075

Duplicate live traffic to a secondary destination for shadow testing and migration validation. Fire-and-forget with percentage sampling — mirror latency never touches the client.

HTTPgRPCShadow Testing

load_testing

Priority: 3070

On-demand load tests triggered by a header key: concurrent virtual clients exercise the full gateway pipeline, with ramp-up and multi-node fan-out to remote gateways.

HTTPTesting

request_deduplication

Priority: 3010

Idempotency-key deduplication for POST/PUT/PATCH with in-memory or centralized Redis storage — stop double-charges from client retries.

HTTP

serverless_function

Priority: 3025

Invoke AWS Lambda, Azure Functions, or Google Cloud Functions as middleware — enrich requests pre-proxy or return function responses directly.

HTTPgRPC

grpc_method_router

Priority: 275

Per-method access control (allow/deny) and per-method rate limiting for gRPC services, with metadata enrichment.

gRPC

grpc_deadline

Priority: 3050

gRPC deadline enforcement: default injection, maximum capping, and gateway processing time subtraction.

gRPC

grpc_web

Priority: 260

Bidirectional gRPC-Web ⇄ native gRPC translation for browser clients, supporting binary and base64 modes with proper trailer embedding.

gRPCBrowser

graphql

Priority: 2850

GraphQL-aware controls: query depth/complexity limits, alias limits, introspection control, and per-operation rate limiting.

HTTP

sse

Priority: 250

Server-Sent Events handler: validates SSE clients, shapes backend requests, guarantees correct streaming headers, and can wrap non-SSE responses into event framing.

HTTPStreaming

spec_expose

Priority: 210

Serves API specification documents (OpenAPI, Swagger, WSDL, WADL) on a /specz sub-path with hardened fetch admission and egress screening.

HTTP

🔄 Transformation & Caching — 4 plugins

Reshape requests and responses in flight, and avoid backend work entirely when a cached answer will do.

request_transformer

Priority: 3000

Add, remove, update, or rename headers, query parameters, and JSON body fields with dot-notation paths, array indexing, and rollback-safe renames.

HTTPgRPC

response_transformer

Priority: 4000

The same operations for response headers and JSON bodies — header rules even apply to gateway-generated rejection responses.

HTTP

compression

Priority: 4050

On-the-fly gzip/brotli response compression with Accept-Encoding negotiation, plus optional request decompression with zip-bomb protection.

HTTP

response_caching

Priority: 3500

Backend response caching with TTL, cache key rules, conditional caching, and a cacheability predictor that skips lookups for keys that never cache.

HTTP

🗽 Service Mesh — 5 plugins

Mesh-mode building blocks — mostly auto-injected from mesh configuration, but several are usable on ordinary gateways too.

spiffe_identity

Priority: 940

Extracts peer SPIFFE identities from mTLS client certificates and HBONE baggage headers — the identity foundation for mesh policy.

HTTPTCPUDP

mesh_authz

Priority: 2075

Identity-based mesh authorization with mesh-wide, namespace, and workload scopes — DENY-first evaluation with Istio-compatible semantics.

HTTPStreams

mesh_outbound_registry

Priority: 130

Host allowlist powering REGISTRY_ONLY outbound policy — also usable standalone as a generic egress Host allowlist on non-mesh gateways.

HTTP

mesh_route_dispatch

Priority: 2995

Applies mesh route splits (Gateway API and VirtualService weighted backends) at dispatch time.

HTTPgRPC

workload_metrics

Priority: 9360

Istio/GAMMA-compatible RED metrics with source/destination workload labels, plus mesh span export to Zipkin, Datadog, Lightstep, or OpenTelemetry providers.

HTTPStreams

📊 Observability — 16 plugins

Traces, metrics, logs, alerts, and billing-grade usage data — shipped to whatever you already run. Log output schemas are fully customizable per sink.

otel_tracing

Priority: 25

W3C Trace Context propagation with OTLP/HTTP span export, batching, rich semantic attributes, and a propagation-only mode.

HTTPgRPCStreams

correlation_id

Priority: 50

UUID request ID generation and propagation across upstream calls and log entries.

HTTPgRPCStreams

prometheus_metrics

Priority: 9300

Prometheus exposition endpoint: request counts, latency histograms, stream connection metrics, upstream health, and pool statistics.

HTTPgRPCAll Protocols

stdout_logging

Priority: 9000

Structured JSON transaction summaries to stdout through bounded non-blocking writers — logging never stalls request threads.

All Protocols

http_logging

Priority: 9100

Batched log delivery to HTTP collectors — Datadog, Splunk, New Relic, Sumo Logic, Axiom, Elastic, Azure Monitor, and more — with retry and custom headers.

All Protocols

loki_logging

Priority: 9155

Batched delivery to Grafana Loki with label-based stream grouping, gzip compression, and multi-tenant support.

All Protocols

kafka_logging

Priority: 9150

Transaction log delivery to Kafka topics for stream-processing pipelines and long-term retention.

All Protocols

tcp_logging

Priority: 9125

Log shipping to TCP/TLS endpoints (e.g. Logstash) with persistent connections and reconnect.

All Protocols

udp_logging

Priority: 9160

Batched delivery to UDP/DTLS endpoints with optional encryption and client certificates — fire-and-forget, zero request latency impact.

All Protocols

ws_logging

Priority: 9175

Log delivery over a WebSocket connection to real-time collectors and dashboards.

All Protocols

ws_frame_logging

Priority: 9050

Logs WebSocket frame metadata — direction, type, size, connection ID — without transforming frames.

WebSocket

statsd_logging

Priority: 9075

Metric emission via StatsD over UDP — compatible with Datadog, InfluxDB, Telegraf, and standard collectors, with customizable tags.

All Protocols

proxy_alerts

Priority: 9250

In-gateway anomaly notifications to Slack, Teams, Discord, PagerDuty/webhooks, or email — error rates, status spikes, latency percentiles, gRPC status codes, and disconnect causes, with cooldowns and quiet hours.

All ProtocolsAlerting

api_chargeback

Priority: 9350

Per-consumer usage charging across three dimensions — per-call by status code, bandwidth per byte, and per-stream-session — exposed via a /charges admin endpoint in Prometheus and JSON formats.

All ProtocolsBilling

api_chargeback_sink

Priority: 9351

Exports durable charge events and snapshot deltas to ClickHouse for billing-grade retention and analytics.

All ProtocolsBilling

transaction_debugger

Priority: 9200

Verbose per-request diagnostics with header redaction — every plugin decision and timing, for development troubleshooting.

All ProtocolsDev Only

ℹ️

Also included: a config-only transaction_log_schema plugin lets you rename, drop, reorder, and derive fields in every log sink's output without forking the gateway. The canonical execution order and per-protocol support matrix live in the plugin execution order docs, with detailed per-plugin configuration in docs/plugins.md.

Putting It Together

Common Plugin Stacks

Plugins compose — here are four stacks teams deploy most often.

🔐 Securing a Public API

Layered defense from cheap checks to deep inspection:

ip_restriction → bot_detection → cors → jwks_auth → access_control → rate_limiting (Redis) → waf → openapi_validator → security_headers → prometheus_metrics + http_logging

🤖 Production AI Gateway

Cost, safety, and compliance for LLM traffic:

key_auth → ai_transcript_audit → ai_prompt_shield → ai_semantic_firewall → ai_request_guard → ai_tool_governor → ai_stream_router + ai_semantic_cache + ai_federation → ai_token_metrics → ai_rate_limiter

🛡 Protecting Fragile Backends

Keep legacy or capacity-limited services healthy:

rate_limiting → adaptive_concurrency → request_size_limiting → request_deduplication → response_caching → compression → proxy_alerts

🔬 Zero-Risk Migration Testing

Validate a new backend against production traffic:

request_mirror (sampled shadow traffic to the new service) + response_mock (stub unfinished endpoints) + fault_injection (verify client resilience) + load_testing (on-demand full-pipeline load) → otel_tracing + transaction_debugger

Configuration Examples

Plugin Config Reference

Plugins are defined as plugin_configs entries and attached globally, per proxy, or per proxy group.

Attaching plugins to a proxy

yaml

proxies:
  - id: "orders-api"
    listen_path: "/orders"
    backend_scheme: http
    backend_host: "orders-service"
    backend_port: 3000
    plugins:
      - plugin_config_id: "team-key-auth"
      - plugin_config_id: "team-rate-limit"

plugin_configs:
  - id: "team-key-auth"
    plugin_name: "key_auth"
    scope: proxy
    enabled: true
    config:
      key_names: ["X-API-Key"]
      hide_credentials: true

rate_limiting — centralized across instances

yaml

plugin_configs:
  - id: "team-rate-limit"
    plugin_name: "rate_limiting"
    scope: proxy_group   # shared budget across the group
    enabled: true
    config:
      limit_by: consumer   # ip | consumer
      requests_per_minute: 1000
      sync_mode: redis     # coordinate across DPs
      redis_url: "redis://redis:6379"
      redis_failure_policy: fail_closed
      expose_headers: true

waf — monitor first, then enforce

yaml

plugin_configs:
  - id: "edge-waf"
    plugin_name: "waf"
    scope: global
    enabled: true
    config:
      mode: monitor        # monitor | enforce
      paranoia_level: 2
      decode_body: true
      rule_overrides:
        - rule: sqli_generic
          action: enforce

ai_prompt_shield — PII redaction

yaml

plugin_configs:
  - id: "pii-shield"
    plugin_name: "ai_prompt_shield"
    scope: proxy
    enabled: true
    config:
      action: redact       # reject | redact | warn
      builtin_patterns:
        - ssn
        - credit_card
        - api_key
      custom_patterns:
        - name: employee_id
          regex: "EMP-\\d{6}"

fault_injection — chaos testing

yaml

plugin_configs:
  - id: "chaos"
    plugin_name: "fault_injection"
    scope: proxy
    enabled: true
    config:
      abort:
        percentage: 2.0
        http_status: 503
      delay:
        percentage: 10.0
        duration_ms: 250

otel_tracing — distributed tracing

yaml

plugin_configs:
  - id: "tracing"
    plugin_name: "otel_tracing"
    scope: global
    enabled: true
    config:
      otlp_endpoint: "http://otel-collector:4318"
      service_name: "ferrum-edge"
      sample_rate: 0.25

Need a Custom Plugin?

Write custom plugins in Rust — drop them in custom_plugins/ and they're auto-discovered at build time, with full lifecycle hooks and even their own database migrations.

Read the Plugin Development Guide →