Plugins

Extend Nexus with 15 lifecycle hooks for audit, metrics, webhooks, and custom processing.

The plugin system lets you react to lifecycle events without modifying engine code. Each hook is a separate Go interface — implement only the events you care about.

Base Interface

type Extension interface {
    Name() string
}

Lifecycle Hooks

Request Events

Hook	When
`OnRequestReceived`	Request enters the pipeline
`OnRequestCompleted`	Provider returns a response
`OnRequestFailed`	Request fails
`OnRequestCached`	Response served from cache

Provider Events

Hook	When
`OnProviderFailed`	Provider call fails
`OnCircuitOpened`	Circuit breaker opens
`OnFallbackTriggered`	Fallback provider used

Guardrail Events

Hook	When
`OnGuardrailBlocked`	Request blocked by guardrail
`OnGuardrailRedacted`	Content redacted by guardrail

Tenant & Key Events

Hook	When
`OnTenantCreated`	New tenant created
`OnTenantDisabled`	Tenant disabled
`OnKeyCreated`	API key created
`OnKeyRevoked`	API key revoked

Budget Events

Hook	When
`OnBudgetWarning`	80% budget threshold
`OnBudgetExceeded`	Budget exceeded

Registering Plugins

gw := nexus.New(
    nexus.WithExtension(audithook.New(recorder)),
    nexus.WithExtension(observability.NewMetricsExtension()),
    nexus.WithExtension(relayhook.NewWebhook("https://hooks.example.com/nexus")),
)

Built-in Plugins

audit_hook — Records lifecycle events for audit trails (Chronicle integration)
observability — Increments atomic counters for operational metrics
relay_hook — Forwards events as webhooks to external systems

Plugins

On this page