Audience: Developers, platform engineers
OpenLimit supports a plugin system that lets you extend the gateway with custom guardrails, HTTP middleware, and provider adapters — without modifying core source code.
Plugins are Go code that implements one of three extension interfaces:
| Type | Interface | Purpose |
|---|---|---|
| Guardrail | GuardrailPlugin |
Custom input/output guardrail stages |
| Middleware | MiddlewarePlugin |
HTTP request/response middleware |
| Provider | ProviderPlugin |
Custom provider adapters |
Plugins are registered at init time via plugins.Register() and activated through the plugins section of gateway.yaml.
gateway.yaml Go Code
─────────── ────────
plugins: func init() {
- name: my-plugin plugins.Register(&MyPlugin{})
type: guardrail }
config:
option: value ↓
Gateway loads plugin config
from yaml, calls Init()
↓
guardrails: Guardrail pipeline calls
input: ProcessInput() / ProcessOutput()
- type: plugin
config:
name: my-plugin
Registration happens at init time via plugins.Register() in a Go init() function.
Activation happens via config — the plugins array in gateway.yaml tells the gateway which plugins to initialize and with what configuration.
Integration happens at the point of use — guardrail plugins are wired into the guardrail pipeline, middleware plugins wrap HTTP handlers, provider plugins create adapters.
All plugins implement the base Plugin interface:
type Plugin interface {
Name() string // Unique identifier
Type() string // "guardrail", "middleware", or "provider"
Init(config map[string]any) error // Initialize with config
}Custom guardrail stages that process input before it's sent to the provider, and output after it's received.
type GuardrailPlugin interface {
Plugin
ProcessInput(ctx GuardrailContext) (GuardrailContext, error)
ProcessOutput(ctx GuardrailContext) (GuardrailContext, error)
}HTTP middleware that wraps request handlers.
type MiddlewarePlugin interface {
Plugin
Middleware() func(http.Handler) http.Handler
}Custom provider adapters for non-standard AI providers.
type ProviderPlugin interface {
Plugin
CreateAdapter(config map[string]any) (ProviderAdapter, error)
}The GuardrailContext carries data through the guardrail pipeline:
type GuardrailContext struct {
Message string // Text content being processed
Metadata map[string]any // Arbitrary key-value data
Blocked bool // Set to true to block the request
BlockReason string // Why the request was blocked
Modified bool // Set to true if content was changed
}Blocking: Set Blocked = true and provide a BlockReason. The pipeline will reject the request with a 400 error.
Modifying: Change Message and set Modified = true. The modified content replaces the original.
Passing: Return the context unchanged.
Here's a complete example — a length guardrail that blocks messages outside configurable bounds:
package plugins
import "fmt"
type LengthGuardrailPlugin struct {
minLength int
maxLength int
}
func (p *LengthGuardrailPlugin) Name() string { return "example-length-guardrail" }
func (p *LengthGuardrailPlugin) Type() string { return "guardrail" }
func (p *LengthGuardrailPlugin) Init(config map[string]any) error {
p.minLength = 0
p.maxLength = 10000
if config == nil {
return nil
}
if v, ok := config["min_length"]; ok {
if f, ok := v.(float64); ok { // JSON numbers decode as float64
p.minLength = int(f)
}
}
if v, ok := config["max_length"]; ok {
if f, ok := v.(float64); ok {
p.maxLength = int(f)
}
}
return nil
}
func (p *LengthGuardrailPlugin) ProcessInput(ctx GuardrailContext) (GuardrailContext, error) {
return p.checkLength(ctx, "input"), nil
}
func (p *LengthGuardrailPlugin) ProcessOutput(ctx GuardrailContext) (GuardrailContext, error) {
return p.checkLength(ctx, "output"), nil
}
func (p *LengthGuardrailPlugin) checkLength(ctx GuardrailContext, dir string) GuardrailContext {
n := len(ctx.Message)
if n < p.minLength {
ctx.Blocked = true
ctx.BlockReason = fmt.Sprintf("%s message too short: %d < %d", dir, n, p.minLength)
} else if p.maxLength > 0 && n > p.maxLength {
ctx.Blocked = true
ctx.BlockReason = fmt.Sprintf("%s message too long: %d > %d", dir, n, p.maxLength)
}
return ctx
}See the full source at internal/plugins/example_length_guardrail.go.
The built-in HeaderInjectorPlugin demonstrates the middleware pattern:
type HeaderInjectorPlugin struct {
headers map[string]string
}
func (h *HeaderInjectorPlugin) Name() string { return "header-injector" }
func (h *HeaderInjectorPlugin) Type() string { return "middleware" }
func (h *HeaderInjectorPlugin) Init(config map[string]any) error {
h.headers = map[string]string{}
if raw, ok := config["headers"]; ok {
if m, ok := raw.(map[string]any); ok {
for k, v := range m {
h.headers[k] = fmt.Sprintf("%v", v)
}
}
}
return nil
}
func (h *HeaderInjectorPlugin) Middleware() func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
for k, v := range h.headers {
if !strings.HasPrefix(k, "X-") && !strings.HasPrefix(k, "x-") {
continue // Only inject X- headers for safety
}
r.Header.Set(k, v)
}
next.ServeHTTP(w, r)
})
}
}See the full source at internal/plugins/header_injector.go.
Add a plugins section to your gateway.yaml:
plugins:
- name: example-length-guardrail
type: guardrail
config:
min_length: 10
max_length: 5000Each plugin entry has three fields:
| Field | Required | Description |
|---|---|---|
name |
Yes | Must match the plugin's Name() return value |
type |
Yes | "guardrail", "middleware", or "provider" |
config |
No | Plugin-specific configuration (passed to Init()) |
For guardrail plugins, reference them in the guardrails section using stage type plugin:
guardrails:
input:
- type: plugin
config:
name: example-length-guardrail
output:
- type: plugin
config:
name: example-length-guardrailThe name in the guardrail stage config must match the plugin's registered name.
plugins:
- name: example-length-guardrail
type: guardrail
config:
min_length: 10
max_length: 5000
- name: header-injector
type: middleware
config:
headers:
X-Custom-Header: "my-value"
guardrails:
input:
- type: keyword
config:
keywords: ["forbidden", "blocked"]
- type: plugin
config:
name: example-length-guardrail
output:
- type: plugin
config:
name: example-length-guardrailPlugin stages execute in order alongside built-in guardrail stages (PII, regex, keyword, length, webhook, json_schema).
- Always handle nil config.
Init(nil)should work and use sensible defaults. - Type-assert config values carefully. JSON/YAML numbers decode as
float64, notint. Use thev.(float64)pattern. - Be thread-safe. Plugins may be called concurrently. Use
sync.Mutexif your plugin has mutable state. - Name uniquely. Plugin names must be unique across the registry. Use a prefix like
mycompany-to avoid collisions. - Return errors from Init. If configuration is invalid, return an error — the gateway will fail to start, which is better than running with bad config.
- Keep ProcessInput/ProcessOutput fast. These run on every request. Avoid network calls or heavy computation.
- Set BlockReason when blocking. Users need to know why their request was blocked. Include the actual values in the reason string.
| Plugin | File | Type | Description |
|---|---|---|---|
| HeaderInjector | internal/plugins/header_injector.go |
Middleware | Injects custom X-* headers into requests |
| LengthGuardrail | internal/plugins/example_length_guardrail.go |
Guardrail | Blocks messages outside configurable length bounds |
- Configuration — Full config reference including plugins section
- Governance — Guardrail pipeline and built-in guardrail types
- API Reference — Error responses when guardrails block requests