hook

Documentation

Index

• func NewRequestID() string
• func PointName(p Point) string
• type Context
  • func NewContext(c *gin.Context, protocol string, body []byte) *Context
• type Hook
  • func NewUsageHook(usageStore *store.UsageStore) Hook
• type HookFunc
• type Level
• type Manager
  • func NewManager() *Manager
  • func (m *Manager) Fire(ctx *Context, point Point) error
  • func (m *Manager) Register(h Hook)
• type Point
• type TraceRecorder
  • func NewTraceRecorder(writer io.Writer, indexWriter io.Writer) *TraceRecorder
  • func NoopTraceRecorder() *TraceRecorder
  • func (t *TraceRecorder) RecordRequest(ctx *Context)
  • func (t *TraceRecorder) RecordResponse(ctx *Context)
  • func (t *TraceRecorder) RecordUpstreamRequest(ctx *Context)
  • func (t *TraceRecorder) RecordUpstreamResponse(ctx *Context, status int)

Functions

func NewRequestID

func NewRequestID() string

NewRequestID generates a globally unique request ID with a datetime prefix. Format: YYYYMMDDHHmmss + 6 random hex chars (e.g. "20260430075235a3f1b2c").

func PointName

func PointName(p Point) string

PointName returns a human-readable name for a hook point.

Types

type Context

type Context struct {
	GinCtx    *gin.Context
	RequestID string
	StartTime time.Time

	// Client side
	ClientProtocol  string // "anthropic" | "responses" | "chat"
	ClientReqBody   []byte // original raw request body
	ClientParsedReq any    // parsed struct (AnthropicRequest, ResponsesRequest, ChatRequest)
	ClientModel     string // model name from client request
	SessionID       string // conversation session ID extracted from request metadata

	// Route
	RouteResult *router.RouteResult

	// Upstream side
	UpstreamProtocol  string         // determined by RouteResult.Format
	UpstreamReqBody   []byte         // request body sent to upstream (after conversion)
	UpstreamReqHeader http.Header    // headers sent to upstream
	UpstreamResp      *http.Response // raw response from upstream
	UpstreamRespBody  []byte         // accumulated response body or raw SSE
	UpstreamLatency   time.Duration

	// Client response
	ClientRespBody []byte        // response body sent to client (after conversion)
	ClientTTFB     time.Duration // time from request start to first byte written to client

	// Token usage (populated by stepWriteResp)
	InputTokens       int64
	OutputTokens      int64
	CacheReadTokens   int64
	CacheCreateTokens int64

	// Stream
	IsStream    bool
	StreamState any // protocol-specific stream conversion state

	// Hook mutable store
	Extra map[string]any
	// contains filtered or unexported fields
}

func NewContext

func NewContext(c *gin.Context, protocol string, body []byte) *Context

type Hook

type Hook struct {
	Name  string
	Point Point
	Level Level
	Fn    HookFunc
}

Hook represents a named callback registered at a specific lifecycle point.

func NewUsageHook

func NewUsageHook(usageStore *store.UsageStore) Hook

NewUsageHook creates an AfterResponse hook that records token usage to the store.

type HookFunc

type HookFunc func(ctx *Context) error

HookFunc is the function signature for hook callbacks.

type Level

type Level int

Level determines how hook errors are handled.

const (
	Critical Level = iota // Critical hooks abort the pipeline on error.
	Optional              // Optional hooks log errors and continue.
)

type Manager

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

Manager manages hook registration and dispatching.

func NewManager

func NewManager() *Manager

NewManager creates a new hook Manager.

func (*Manager) Fire

func (m *Manager) Fire(ctx *Context, point Point) error

Fire executes all hooks registered at the given point in order. If a Critical hook returns an error, Fire aborts and returns that error. If an Optional hook returns an error, it is logged and execution continues.

func (*Manager) Register

func (m *Manager) Register(h Hook)

Register adds a hook to be fired at its configured point.

type Point

type Point int

Point represents a specific moment in the request lifecycle where hooks can fire.

const (
	BeforeRoute Point = iota
	AfterRoute
	BeforeUpstream
	AfterUpstream
	AfterResponse
)

type TraceRecorder

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

TraceRecorder records each pipeline stage as a JSONL line.

func NewTraceRecorder

func NewTraceRecorder(writer io.Writer, indexWriter io.Writer) *TraceRecorder

func NoopTraceRecorder

func NoopTraceRecorder() *TraceRecorder

NoopTraceRecorder returns a no-op recorder safe to call when tracing is disabled.

func (*TraceRecorder) RecordRequest

func (t *TraceRecorder) RecordRequest(ctx *Context)

RecordRequest writes a "request" trace record after stepParse.

func (*TraceRecorder) RecordResponse

func (t *TraceRecorder) RecordResponse(ctx *Context)

RecordResponse writes a "response" trace record after stepWriteResp.

func (*TraceRecorder) RecordUpstreamRequest

func (t *TraceRecorder) RecordUpstreamRequest(ctx *Context)

RecordUpstreamRequest writes an "upstream_request" trace record after stepConvertReq.

func (*TraceRecorder) RecordUpstreamResponse

func (t *TraceRecorder) RecordUpstreamResponse(ctx *Context, status int)

RecordUpstreamResponse writes an "upstream_response" trace record after stepForward.