Documentation
¶
Overview ¶
Package hooks executes submit, part, and tool-reactor chains with deterministic ordering and validation of canonical mutations.
Index ¶
- func StableParticipantLess(orderA, orderB int, idA, idB string, regIdxA, regIdxB int) int
- func ValidateCallAfterRequestHooks(hookID string, call *lipapi.Call) error
- func ValidateEventAfterResponseHook(hookID string, ev *lipapi.Event) error
- func ValidateToolEventAfterPolicy(policyID string, te *lipapi.ToolEvent) error
- func WithDiagnosticsLogger(ctx context.Context, log *slog.Logger) context.Context
- func WithSubmitEvidence(ctx context.Context, fn SubmitEvidenceFunc) context.Context
- func WithToolReactorEvidence(ctx context.Context, fn ToolReactorEvidenceFunc) context.Context
- type Bus
- func (b *Bus) ApplyToolReactors(ctx context.Context, te lipapi.ToolEvent, meta sdk.ToolMeta) ToolApplyResult
- func (b *Bus) HookChainLengths() (submit, requestParts, responseParts, tools int)
- func (b *Bus) RunRequestPartHooks(ctx context.Context, call *lipapi.Call, meta sdk.PartMeta) error
- func (b *Bus) RunResponsePartHooks(ctx context.Context, ev *lipapi.Event, meta sdk.PartMeta) error
- func (b *Bus) RunSubmit(ctx context.Context, call *lipapi.Call, meta *sdk.SubmitMeta) error
- type Config
- type HookScenarioSpec
- type SubmitEvidenceFunc
- type ToolApplyResult
- type ToolReactorEvidenceFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func StableParticipantLess ¶
StableParticipantLess is the design §17 intra-stage ordering: ascending order (priority), then ascending stable id, then ascending registration index tie-break.
func ValidateCallAfterRequestHooks ¶
ValidateCallAfterRequestHooks re-validates the canonical call after request-part hooks.
func ValidateEventAfterResponseHook ¶
ValidateEventAfterResponseHook checks a single event remains structurally legal after a response hook.
func ValidateToolEventAfterPolicy ¶
ValidateToolEventAfterPolicy checks a tool-policy decision has not produced an illegal tool event.
func WithDiagnosticsLogger ¶
WithDiagnosticsLogger attaches log for isolated fail-open hook panic diagnostics. Nil log is a no-op. Composition roots that run hooks (for example the executor) should attach the server logger when available so [logFailOpenHookPanic] can emit structured lines; otherwise fail-open panic logs are skipped.
func WithSubmitEvidence ¶
func WithSubmitEvidence(ctx context.Context, fn SubmitEvidenceFunc) context.Context
WithSubmitEvidence attaches fn to ctx so Bus.RunSubmit can emit per-hook policy decision evidence. A nil fn means no evidence is emitted.
func WithToolReactorEvidence ¶
func WithToolReactorEvidence(ctx context.Context, fn ToolReactorEvidenceFunc) context.Context
WithToolReactorEvidence attaches fn to ctx so Bus.ApplyToolReactors can emit per-reactor policy decision evidence. A nil fn means no evidence is emitted.
Types ¶
type Bus ¶
type Bus struct {
// contains filtered or unexported fields
}
Bus runs hook chains in stable order (Order ascending, then ID ascending, then registration index ascending so equal Order+ID hooks remain deterministic).
After New, the bus does not replace its internal hook slices; concurrent Bus method calls are safe only if hook implementations are safe for concurrent use. Callers must not mutate those slices or the bus fields after construction (including when the same bus is embedded in github.com/matdev83/go-llm-interactive-proxy/internal/core/extensions.RequestRuntimeSnapshot).
func (*Bus) ApplyToolReactors ¶
func (b *Bus) ApplyToolReactors(ctx context.Context, te lipapi.ToolEvent, meta sdk.ToolMeta) ToolApplyResult
ApplyToolReactors runs tool reactors in order. Reactor errors follow Config.ToolReactorErrorPolicy (default fail-open). Swallow stops the chain and returns Emit=false.
func (*Bus) HookChainLengths ¶
HookChainLengths returns hook counts for diagnostics and tests.
func (*Bus) RunRequestPartHooks ¶
RunRequestPartHooks runs request-part hooks in order and re-validates the call.
func (*Bus) RunResponsePartHooks ¶
RunResponsePartHooks runs response-part hooks in order and validates each mutation.
func (*Bus) RunSubmit ¶
RunSubmit executes submit hooks in order. meta may be nil; a working meta map is allocated.
When a SubmitEvidenceFunc is attached to ctx via WithSubmitEvidence, the runner invokes it once per hook after the hook returns, with the hook's provider id, reject flag, the annotations the hook added to meta.Annotations, and the hook's returned error. Evidence emission is a side effect isolated from request execution: return values and sdk.SubmitRejectError semantics are unchanged. A nil seam emits nothing.
type Config ¶
type Config = lipfeature.HookConfig
Config wires hook implementations into a Bus. Any slice may be nil or empty. It aliases the SDK-owned lipfeature.HookConfig projected from declared feature planes.
func MaterializeSorted ¶
MaterializeSorted returns a copy of cfg with each hook chain sorted per design §17 (order, id, registration index). Diagnostics and tests use it without constructing a Bus.
type HookScenarioSpec ¶
type HookScenarioSpec struct {
ID string
InvariantSummary string
TestName string // exists in internal/core/hooks/*_test.go
}
HookScenarioSpec links a stable scenario identifier to hook-bus invariants and the primary regression test (specification bundle).
func SpecBundleHookScenarios ¶
func SpecBundleHookScenarios() []HookScenarioSpec
SpecBundleHookScenarios lists submit, request/response part, and tool-reactor invariants. Keep aligned with the referenced tests.
type SubmitEvidenceFunc ¶
type SubmitEvidenceFunc func(ctx context.Context, providerID string, rejected bool, annotations map[string]string, err error)
SubmitEvidenceFunc projects a submit-hook outcome into shared policy decision evidence when attached to the request context. It is invoked by Bus.RunSubmit after each submit hook returns, with the hook's provider id, whether it rejected the call, the annotations it added to sdk.SubmitMeta.Annotations, and the hook's returned error (provider failure). Implementations must not change runtime behavior; evidence emission is a side effect isolated from request execution and preserves sdk.SubmitRejectError semantics.
The func is defined here (in hooks) so the submit runner can call it without importing the extensions package (which would create an import cycle, since extensions imports hooks). The extensions package provides a constructor that wires the func to the configured evidence emitter and projector, mirroring ToolReactorEvidenceFunc.
A nil fn means no evidence is emitted.
func SubmitEvidenceFromContext ¶
func SubmitEvidenceFromContext(ctx context.Context) SubmitEvidenceFunc
SubmitEvidenceFromContext returns the evidence func attached by WithSubmitEvidence, or nil when none is attached.
type ToolApplyResult ¶
type ToolApplyResult struct {
// Emit is false when a reactor swallowed the event.
Emit bool
// Event is the canonical tool event to surface when Emit is true.
Event lipapi.ToolEvent
// Err is set when ToolReactorErrorsFailClosed is configured and a reactor returned an error.
Err error
}
ToolApplyResult is the outcome of running the tool-reactor chain on one tool event.
type ToolReactorEvidenceFunc ¶
type ToolReactorEvidenceFunc func(ctx context.Context, providerID string, decision sdk.ToolDecision, err error, validationErr error)
ToolReactorEvidenceFunc projects a tool-reactor decision into shared policy decision evidence when attached to the request context. It is invoked by Bus.ApplyToolReactors after each reactor returns and the runner has validated any rewrite/replace output, with the reactor's provider id, its decision, the reactor's returned error (provider failure), and the validation error for an invalid rewrite/replace (malformed output). Implementations must not change runtime behavior; evidence emission is a side effect isolated from request execution.
The func is defined here (in hooks) so the reactor runner can call it without importing the extensions package (which would create an import cycle, since extensions imports hooks). The extensions package provides a constructor that wires the func to the configured evidence emitter and projector.
func ToolReactorEvidenceFromContext ¶
func ToolReactorEvidenceFromContext(ctx context.Context) ToolReactorEvidenceFunc
ToolReactorEvidenceFromContext returns the evidence func attached by WithToolReactorEvidence, or nil when none is attached.
Source Files