Documentation
¶
Overview ¶
Package plugin defines the extension system for Nexus. Extensions are notified of lifecycle events (request received, completed, failed, cached, etc.) and can react to them — audit logging, metrics, tracing, webhooks, etc.
Each lifecycle hook is a separate interface so extensions opt in only to the events they care about.
Index ¶
- type BudgetExceeded
- type BudgetWarning
- type ChunkReceived
- type CircuitOpened
- type Extension
- type FallbackTriggered
- type GuardrailBlocked
- type GuardrailRedacted
- type KeyCreated
- type KeyRevoked
- type ProviderFailed
- type Registry
- func (r *Registry) Count() int
- func (r *Registry) EmitBudgetExceeded(ctx context.Context, tenantID id.TenantID)
- func (r *Registry) EmitBudgetWarning(ctx context.Context, tenantID id.TenantID, usedPct float64)
- func (r *Registry) EmitChunkReceived(ctx context.Context, requestID id.RequestID, kind provider.EventKind, ...)
- func (r *Registry) EmitCircuitOpened(ctx context.Context, providerName string)
- func (r *Registry) EmitFallbackTriggered(ctx context.Context, from, to string)
- func (r *Registry) EmitGuardrailBlocked(ctx context.Context, guardName string, requestID id.RequestID)
- func (r *Registry) EmitGuardrailRedacted(ctx context.Context, guardName, field string)
- func (r *Registry) EmitKeyCreated(ctx context.Context, keyID id.KeyID, tenantID id.TenantID)
- func (r *Registry) EmitKeyRevoked(ctx context.Context, keyID id.KeyID)
- func (r *Registry) EmitProviderFailed(ctx context.Context, providerName, model string, provErr error)
- func (r *Registry) EmitRequestCached(ctx context.Context, requestID id.RequestID, model string)
- func (r *Registry) EmitRequestCompleted(ctx context.Context, requestID id.RequestID, model, providerName string, ...)
- func (r *Registry) EmitRequestFailed(ctx context.Context, requestID id.RequestID, model string, reqErr error)
- func (r *Registry) EmitRequestReceived(ctx context.Context, requestID id.RequestID, model, tenantID string)
- func (r *Registry) EmitStreamCompleted(ctx context.Context, requestID id.RequestID, model, providerName string, ...)
- func (r *Registry) EmitStreamFailed(ctx context.Context, requestID id.RequestID, model string, streamErr error)
- func (r *Registry) EmitStreamStarted(ctx context.Context, requestID id.RequestID, model, providerName string)
- func (r *Registry) EmitTenantCreated(ctx context.Context, tenantID id.TenantID)
- func (r *Registry) EmitTenantDisabled(ctx context.Context, tenantID id.TenantID)
- func (r *Registry) Extensions() []Extension
- func (r *Registry) HasChunkReceived() bool
- func (r *Registry) Register(e Extension)
- type RequestCached
- type RequestCompleted
- type RequestFailed
- type RequestReceived
- type StreamCompleted
- type StreamFailed
- type StreamStarted
- type TenantCreated
- type TenantDisabled
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BudgetExceeded ¶
BudgetExceeded is called when budget is exceeded.
type BudgetWarning ¶
type BudgetWarning interface {
OnBudgetWarning(ctx context.Context, tenantID id.TenantID, usedPct float64) error
}
BudgetWarning is called at 80% budget threshold.
type ChunkReceived ¶
type ChunkReceived interface {
OnChunkReceived(ctx context.Context, requestID id.RequestID, kind provider.EventKind, byteSize int) error
}
ChunkReceived is called per chunk (or per N chunks, configurable). The payload is intentionally tiny (kind + byte size) — full chunk payloads stay off the hot path. Implementations must return promptly.
type CircuitOpened ¶
CircuitOpened is called when a circuit breaker opens for a provider.
type Extension ¶
type Extension interface {
// Name returns a unique human-readable name for the extension.
Name() string
}
Extension is the base interface all extensions must implement.
type FallbackTriggered ¶
type FallbackTriggered interface {
OnFallbackTriggered(ctx context.Context, from string, to string) error
}
FallbackTriggered is called when a fallback provider is used.
type GuardrailBlocked ¶
type GuardrailBlocked interface {
OnGuardrailBlocked(ctx context.Context, guardName string, requestID id.RequestID) error
}
GuardrailBlocked is called when a guardrail blocks a request.
type GuardrailRedacted ¶
type GuardrailRedacted interface {
OnGuardrailRedacted(ctx context.Context, guardName string, field string) error
}
GuardrailRedacted is called when a guardrail redacts content.
type KeyCreated ¶
type KeyCreated interface {
OnKeyCreated(ctx context.Context, keyID id.KeyID, tenantID id.TenantID) error
}
KeyCreated is called when an API key is created.
type KeyRevoked ¶
KeyRevoked is called when an API key is revoked.
type ProviderFailed ¶
type ProviderFailed interface {
OnProviderFailed(ctx context.Context, providerName string, model string, err error) error
}
ProviderFailed is called when a provider call fails (before retry/fallback).
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds registered extensions and dispatches lifecycle events to them. It type-caches extensions at registration time so emit calls iterate only over extensions that implement the relevant hook.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry creates an extension registry with a default logger.
func NewRegistryWithLogger ¶
NewRegistryWithLogger creates an extension registry with the given logger.
func (*Registry) EmitBudgetExceeded ¶
EmitBudgetExceeded notifies all extensions that implement BudgetExceeded.
func (*Registry) EmitBudgetWarning ¶
EmitBudgetWarning notifies all extensions that implement BudgetWarning.
func (*Registry) EmitChunkReceived ¶
func (r *Registry) EmitChunkReceived(ctx context.Context, requestID id.RequestID, kind provider.EventKind, byteSize int)
EmitChunkReceived notifies all extensions that implement ChunkReceived. Hot-path: skip the loop entirely if nobody is listening.
func (*Registry) EmitCircuitOpened ¶
EmitCircuitOpened notifies all extensions that implement CircuitOpened.
func (*Registry) EmitFallbackTriggered ¶
EmitFallbackTriggered notifies all extensions that implement FallbackTriggered.
func (*Registry) EmitGuardrailBlocked ¶
func (r *Registry) EmitGuardrailBlocked(ctx context.Context, guardName string, requestID id.RequestID)
EmitGuardrailBlocked notifies all extensions that implement GuardrailBlocked.
func (*Registry) EmitGuardrailRedacted ¶
EmitGuardrailRedacted notifies all extensions that implement GuardrailRedacted.
func (*Registry) EmitKeyCreated ¶
EmitKeyCreated notifies all extensions that implement KeyCreated.
func (*Registry) EmitKeyRevoked ¶
EmitKeyRevoked notifies all extensions that implement KeyRevoked.
func (*Registry) EmitProviderFailed ¶
func (r *Registry) EmitProviderFailed(ctx context.Context, providerName, model string, provErr error)
EmitProviderFailed notifies all extensions that implement ProviderFailed.
func (*Registry) EmitRequestCached ¶
EmitRequestCached notifies all extensions that implement RequestCached.
func (*Registry) EmitRequestCompleted ¶
func (r *Registry) EmitRequestCompleted(ctx context.Context, requestID id.RequestID, model, providerName string, elapsed time.Duration, inputTokens, outputTokens int)
EmitRequestCompleted notifies all extensions that implement RequestCompleted.
func (*Registry) EmitRequestFailed ¶
func (r *Registry) EmitRequestFailed(ctx context.Context, requestID id.RequestID, model string, reqErr error)
EmitRequestFailed notifies all extensions that implement RequestFailed.
func (*Registry) EmitRequestReceived ¶
func (r *Registry) EmitRequestReceived(ctx context.Context, requestID id.RequestID, model, tenantID string)
EmitRequestReceived notifies all extensions that implement RequestReceived.
func (*Registry) EmitStreamCompleted ¶
func (r *Registry) EmitStreamCompleted(ctx context.Context, requestID id.RequestID, model, providerName string, elapsed time.Duration, final *provider.CompletionResponse)
EmitStreamCompleted notifies all extensions that implement StreamCompleted.
func (*Registry) EmitStreamFailed ¶
func (r *Registry) EmitStreamFailed(ctx context.Context, requestID id.RequestID, model string, streamErr error)
EmitStreamFailed notifies all extensions that implement StreamFailed.
func (*Registry) EmitStreamStarted ¶
func (r *Registry) EmitStreamStarted(ctx context.Context, requestID id.RequestID, model, providerName string)
EmitStreamStarted notifies all extensions that implement StreamStarted.
func (*Registry) EmitTenantCreated ¶
EmitTenantCreated notifies all extensions that implement TenantCreated.
func (*Registry) EmitTenantDisabled ¶
EmitTenantDisabled notifies all extensions that implement TenantDisabled.
func (*Registry) Extensions ¶
Extensions returns all registered extensions.
func (*Registry) HasChunkReceived ¶
HasChunkReceived reports whether at least one extension implements ChunkReceived. Used by the stream lifecycle middleware to skip per-chunk instrumentation when no one is listening.
type RequestCached ¶
type RequestCached interface {
OnRequestCached(ctx context.Context, requestID id.RequestID, model string) error
}
RequestCached is called when a response is served from cache.
type RequestCompleted ¶
type RequestCompleted interface {
OnRequestCompleted(ctx context.Context, requestID id.RequestID, model string, providerName string, elapsed time.Duration, inputTokens int, outputTokens int) error
}
RequestCompleted is called after a successful provider response.
type RequestFailed ¶
type RequestFailed interface {
OnRequestFailed(ctx context.Context, requestID id.RequestID, model string, err error) error
}
RequestFailed is called when a request fails.
type RequestReceived ¶
type RequestReceived interface {
OnRequestReceived(ctx context.Context, requestID id.RequestID, model string, tenantID string) error
}
RequestReceived is called when a request enters the pipeline.
type StreamCompleted ¶
type StreamCompleted interface {
OnStreamCompleted(ctx context.Context, requestID id.RequestID, model, providerName string, elapsed time.Duration, final *provider.CompletionResponse) error
}
StreamCompleted is called after a stream drains successfully. The final argument carries the merged CompletionResponse (Content concat, ToolCalls merged, Usage from the last chunk) — same shape Provider.Complete would have produced. Implementations may treat it as authoritative.
type StreamFailed ¶
type StreamFailed interface {
OnStreamFailed(ctx context.Context, requestID id.RequestID, model string, err error) error
}
StreamFailed is called when a stream errors mid-flight or fails to start.
type StreamStarted ¶
type StreamStarted interface {
OnStreamStarted(ctx context.Context, requestID id.RequestID, model, providerName string) error
}
StreamStarted is called once per streaming request, when the first chunk arrives from the provider. Use this to start spans, open audit records, etc.
type TenantCreated ¶
TenantCreated is called when a new tenant is created.
Source Files