extproc

type L4Record struct {
	Timestamp time.Time
	EndAt     time.Time

	// Agent identity, populated from the clrk.apoxy.dev dynamic
	// metadata namespace forwarded by Envoy on the first
	// ProcessingRequest (same shape the HTTP path reads).
	AgentKind      string
	AgentNamespace string
	AgentName      string
	AgentUID       string
	AgentRevision  string
	InvocationID   string

	// DstName is the DNS-bound destination hostname the sandbox's
	// resolver answered for the connection's destination IP. Carried
	// from the worker via PROXY v2 TLVDstName and forwarded by Envoy
	// as MetaDstName under the clrk.apoxy.dev namespace. Empty when
	// no binding existed at dial time (direct-IP, DNS bypass,
	// expired entry, or DoT/DoH bypass).
	DstName string

	// BytesUpstream is the count of agent → server bytes observed on
	// this connection. Server → agent bytes are unobserved by design.
	BytesUpstream int64
}

type NetworkServer struct {
	netextprocsvcv3.UnimplementedNetworkExternalProcessorServer
	// contains filtered or unexported fields
}

type Record struct {
	Timestamp time.Time
	EndAt     time.Time

	AgentKind      string
	AgentNamespace string
	AgentName      string
	AgentUID       string
	AgentRevision  string
	InvocationID   string

	RequestHeadersAt time.Time
	RequestHeaders   map[string]string
	RequestBodyAt    time.Time
	RequestBody      []byte
	RequestTruncated bool

	ResponseHeadersAt time.Time
	ResponseHeaders   map[string]string
	ResponseBodyAt    time.Time
	ResponseBody      []byte
	ResponseTruncated bool

	// RequestBodyDecoded / ResponseBodyDecoded carry the content-encoding-
	// decoded copy of the body when enrichRecord inflated it (agents send
	// `accept-encoding: gzip, ...` and the MITM forwards it, so providers
	// gzip/br/zstd even SSE bodies). The OTLP body span event ships these
	// so the inspector renders readable JSON instead of a compressed blob.
	// Nil when the body was identity-encoded, truncated (a header-less
	// keep-last-N tail no codec can inflate), or failed to inflate -- the
	// sink then falls back to the raw RequestBody/ResponseBody. The raw
	// bytes are never overwritten, so clrk.req.bytes / clrk.resp.bytes stay
	// true on-wire counts.
	//
	// RequestContentEncoding / ResponseContentEncoding name the non-identity
	// wire encoding that was present (e.g. "gzip"), set whenever the body
	// carried one regardless of whether it inflated, so the sink can label a
	// decoded body as "was gzipped" and a truncated/undecodable compressed
	// body as not decodable.
	RequestBodyDecoded      []byte
	RequestContentEncoding  string
	ResponseBodyDecoded     []byte
	ResponseContentEncoding string
	// ResponseBodyChunks counts ResponseBody ProcessingRequest messages
	// received from Envoy. Under ResponseBodyMode=BUFFERED this is 1
	// (or 0 if the upstream produced no body); under STREAMED it
	// reflects per-chunk delivery. Surfaced on OTLP so operators (and
	// integration tests) can confirm the conditional STREAMED override
	// promoted the mode for streaming traffic.
	ResponseBodyChunks int

	// RequestBodyRewritten is true when ext_proc replaced the request
	// body before forwarding (e.g. forcing OpenAI
	// stream_options.include_usage=true so streamed responses always
	// emit terminal usage). Surfaced on the OTLP record as
	// clrk.body.request_rewritten so operators can correlate
	// upstream-observed bodies with what the agent actually sent.
	RequestBodyRewritten bool

	// Provider holds parsed AI-provider facts (gen_ai.* shape) when the
	// request's :authority host matched a known provider. Nil for any
	// other host.
	Provider *parsers.ProviderInfo

	// MatchedRouteNamespace / MatchedRouteName identify the
	// AIProviderRoute that accepted this transaction; empty when no
	// route attached to the calling EG matched.
	MatchedRouteNamespace string
	MatchedRouteName      string

	// BudgetDenied is set when the matched route's TokenBudget caused
	// us to short-circuit the request with an HTTP 429. The captured
	// record will only have RequestHeaders populated in that case
	// (response phases never ran).
	BudgetDenied bool
	// BudgetDailyUsed / BudgetDailyMax are the counter snapshot at the
	// moment of the deny decision, attached for operator visibility.
	BudgetDailyUsed int64
	BudgetDailyMax  int64

	// MCP carries parsed MCP JSON-RPC envelope facts when the
	// :authority host fell under an attached MCPRoute and the request
	// body was a single (non-batch) JSON-RPC request. Nil for any
	// other traffic.
	MCP *parsers.MCPInfo

	// MatchedMCPRouteNamespace / MatchedMCPRouteName identify the
	// MCPRoute whose rule accepted this transaction; empty when no
	// rule matched.
	MatchedMCPRouteNamespace string
	MatchedMCPRouteName      string

	// MCPToolPolicyDecision is "allow" or "deny" when the matched
	// rule's ToolPolicy fired on a tools/call request; empty for
	// non-tools/call methods, no-policy rules, or unmatched traffic.
	MCPToolPolicyDecision string

	// SelectedBackendNamespace / SelectedBackendName identify the clrk
	// Backend this transaction was re-pointed to at RequestBody EOS.
	// SelectedBackendSchema is that backend's canonical gen_ai.system
	// (the wire schema the response was parsed against).
	// SelectedBackendReselected is true only when re-selection actually
	// fired. All four stay zero for single-backend / non-reselectable
	// routes, so OTLP attributes are unchanged for existing traffic.
	SelectedBackendNamespace  string
	SelectedBackendName       string
	SelectedBackendSchema     string
	SelectedBackendReselected bool

	// Cross-schema translation facts (APO-742). TranslationApplied is
	// true when the request committed upstream in a different wire
	// schema than the agent spoke; From/To are the canonical
	// gen_ai.system names of those schemas. SkippedBackends counts
	// cross-schema candidates dropped by per-request filtering
	// (streaming, capability misses, no applicable modelRewrite).
	// DroppedExtras counts source-schema members not representable in
	// the target schema (request + response sides). Error carries the
	// reason translation degraded: a fallback's decode/encode failure,
	// or the response-side failure behind a fail-closed 502.
	TranslationApplied         bool
	TranslationFrom            string
	TranslationTo              string
	TranslationSkippedBackends int
	TranslationDroppedExtras   int
	TranslationError           string

	// Attempts is the number of upstream router attempts that recorded
	// facts for this request; AttemptBackends is the ordered
	// "<ns>/<name>" walk of the backends they targeted (the last entry
	// is the serving attempt, mirrored in SelectedBackend*). Both stay
	// zero for unpinned traffic.
	Attempts        int
	AttemptBackends []string

	// RetryIneligibleReason is set when a pinned request cannot be
	// retried — today only "body_too_large": the request body exceeded
	// the synthesized route's retry buffer, so Envoy silently disables
	// retries and an attached FallbackRoutingPolicy cannot fire.
	RetryIneligibleReason string
}

type Server struct {
	extprocv3.UnimplementedExternalProcessorServer
	// contains filtered or unexported fields
}

type ServerOption func(*Server)

type Sink interface {
	Emit(record Record)
	EmitL4(record L4Record)
}