plugin

Documentation

Overview

Package plugin defines the Plugin interface and the lifecycle stages used to hook into the gateway request pipeline.

Plugins are registered by name via RegisterFactory and loaded by the gateway at startup. The plugin.Context carries the request and response through each stage, and plugins may modify, reject, or skip requests.

Built-in plugins live in the internal/plugins/* packages and are registered by importing them with a blank import (e.g. _ "github.com/ferro-labs/ai-gateway/internal/plugins/wordfilter").

Index

• func PutContext(c *Context)
• func RegisterFactory(name string, factory PluginFactory)
• func RegisteredPlugins() []string
• type Context
  • func NewContext(req *providers.Request) *Context
• type Manager
  • func NewManager() *Manager
  • func (m *Manager) HasPlugins() bool
  • func (m *Manager) Register(stage Stage, p Plugin) error
  • func (m *Manager) RunAfter(ctx context.Context, pctx *Context) error
  • func (m *Manager) RunBefore(ctx context.Context, pctx *Context) error
  • func (m *Manager) RunOnError(ctx context.Context, pctx *Context)
• type Plugin
• type PluginFactory
  • func GetFactory(name string) (PluginFactory, bool)
• type PluginType
• type RejectionError
  • func (e *RejectionError) Error() string
• type Stage

Functions

func PutContext

func PutContext(c *Context)

PutContext returns a plugin context to the pool after resetting all fields.

func RegisterFactory

func RegisterFactory(name string, factory PluginFactory)

RegisterFactory registers a plugin factory by name.

func RegisteredPlugins

func RegisteredPlugins() []string

RegisteredPlugins returns the names of all registered plugin factories.

Types

type Context

type Context struct {
	Request  *providers.Request
	Response *providers.Response
	Metadata map[string]interface{}
	Error    error
	Skip     bool
	Reject   bool
	Reason   string
}

Context provides access to request/response data for plugins.

func NewContext

func NewContext(req *providers.Request) *Context

NewContext retrieves a plugin context from the pool and sets the request. Caller MUST call PutContext when the request is complete.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager manages plugin lifecycle and execution.

func NewManager

func NewManager() *Manager

NewManager creates a new plugin manager.

func (*Manager) HasPlugins

func (m *Manager) HasPlugins() bool

HasPlugins returns true if any plugins are registered.

func (*Manager) Register

func (m *Manager) Register(stage Stage, p Plugin) error

Register registers a plugin at the given stage.

func (*Manager) RunAfter

func (m *Manager) RunAfter(ctx context.Context, pctx *Context) error

RunAfter executes all after-request plugins.

func (*Manager) RunBefore

func (m *Manager) RunBefore(ctx context.Context, pctx *Context) error

RunBefore executes all before-request plugins. Returns an error if a plugin rejects the request.

func (*Manager) RunOnError

func (m *Manager) RunOnError(ctx context.Context, pctx *Context)

RunOnError executes all on-error plugins.

type Plugin

type Plugin interface {
	Name() string
	Type() PluginType
	Init(config map[string]interface{}) error
	Execute(ctx context.Context, pctx *Context) error
}

Plugin is the interface all plugins must implement.

type PluginFactory

type PluginFactory func() Plugin

PluginFactory creates a new instance of a plugin.

func GetFactory

func GetFactory(name string) (PluginFactory, bool)

GetFactory returns a plugin factory by name.

type PluginType

type PluginType string

PluginType categorizes plugins.

const (
	TypeGuardrail PluginType = "guardrail"
	TypeLogging   PluginType = "logging"
	TypeMetrics   PluginType = "metrics"
	TypeAuth      PluginType = "auth"
	TypeTransform PluginType = "transform"
	TypeRateLimit PluginType = "ratelimit"
)

PluginType constants define the supported lifecycle attachment points.

type RejectionError

type RejectionError struct {
	Plugin     string
	PluginType PluginType
	Stage      Stage
	Reason     string
}

RejectionError indicates a plugin intentionally rejected a request/response.

func (*RejectionError) Error

func (e *RejectionError) Error() string

Error implements the error interface.

type Stage

type Stage string

Stage defines when a plugin runs in the request lifecycle.

const (
	StageBeforeRequest Stage = "before_request"
	StageAfterRequest  Stage = "after_request"
	StageOnError       Stage = "on_error"
)

Stage constants define the execution phases within the proxy pipeline.