Documentation
¶
Overview ¶
Package capturefilter implements the v0.1.2 "capture-filter" path gate: BEFORE the recording pipeline allocates a trace ID or wires the per-trace capture sinks, the proxy handler asks this filter whether the request path is in the operator-configured drop list. If yes, the request is forwarded upstream WITHOUT capture — no JSONL line, no SQLite row, no media extraction, no media tee reading bytes off the wire.
Why a separate package from pathfilter (which already exists as an observer-class drop plugin):
- pathfilter runs at finalize (after capture sinks have already run, after the body is in memory) and marks the trace as "do not record". The bytes are still captured + thrown away.
- capturefilter runs in the proxy handler BEFORE startTrace(). The request flows through the proxy unaltered but the CaptureTransport's tee never fires (no trace ID in context → SinksFor returns nil → bytes pass through unwrapped).
Why both exist (sub2gpt + sub2api already ship a pathfilter `patterns` block):
- Existing operator deployments configured `plugins.path_filter` get the same observer semantics they had pre-v0.1.2. Their YAML is not silently re-interpreted as "drop before capture", which would be a breaking behavioral change.
- New `plugins.capture_filter` is opt-in — operators flip it on to skip writes for high-volume polling endpoints (e.g. an admin UI's /api/v1/auth/me + /api/v1/subscriptions/active polls that pollute the data dir without LLM relevance).
Pattern syntax is intentionally identical to pathfilter (exact + trailing-`*` prefix). Operators copy the same pattern string between the two blocks if they want both display-hide AND pre-write drop on the same paths.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config = pathfilter.Config
Config is the YAML subtree under `plugins.capture_filter`. Mirrors pathfilter.Config so the YAML shape stays consistent across the two filter surfaces.
type Filter ¶
type Filter struct {
// contains filtered or unexported fields
}
Filter is the standalone gate the proxy handler calls per request. Constructed once at startup via New; nil-safe — `(*Filter).ShouldDrop` on a nil receiver returns false, so callers can treat "no filter configured" identically to "filter configured but empty".
func New ¶
New compiles cfg.Patterns into a Filter. Returns (nil, nil) when no patterns are configured — callers wire the same nil-safe Filter regardless of whether the operator opted in. Validation matches pathfilter (refuses empty strings + the lone `*`).
func (*Filter) Patterns ¶
Patterns returns a flat slice of the operator-facing pattern strings. Used for /healthz + startup log emission so operators can confirm the configured drop list without reading the YAML back. Nil-safe.
func (*Filter) ShouldDrop ¶
ShouldDrop returns true when path matches any configured pattern. Nil-safe: a nil Filter always returns false (no gate configured).
Source Files