proxy

Documentation

Overview

Package proxy provides OpticTrace's interception layer in two flavors that share one code path:

1. Standalone reverse-proxy sidecar (NewReverseProxy): OpticTrace listens on service.listen and forwards to service.upstream.
2. Embedded middleware (Interceptor.Wrap): drop OpticTrace in front of any http.Handler inside an existing Go application.

Per exchange, one canonical store.Record is built after governance (restriction, redaction, sampling) and fanned out to the configured sinks: structured console log, Prometheus collector, async payload store.

Performance posture: the policy is resolved once per request *before* any capture machinery is attached, so routes that restrict capture pay almost nothing — no body buffering, no header copying. Captured bodies are bounded by capture_limit_bytes; the full stream always reaches the client untouched.

Index

• type Interceptor
  • func NewInterceptor(cfg *config.Config, eng *engine.Engine, logger *slog.Logger, opts ...Option) *Interceptor
  • func NewReverseProxy(cfg *config.Config, eng *engine.Engine, logger *slog.Logger, opts ...Option) (http.Handler, *Interceptor, error)
  • func (ic *Interceptor) SwapEngine(eng *engine.Engine)
  • func (ic *Interceptor) Wrap(next http.Handler) http.Handler
• type Option
  • func WithExporters(d *export.Dispatcher) Option
  • func WithMetrics(c *metrics.Collector) Option
  • func WithStore(w *store.AsyncWriter) Option

Types

type Interceptor

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

Interceptor evaluates governance rules around an inner handler and emits telemetry to its sinks. The engine is swappable at runtime (hot reload).

func NewInterceptor

func NewInterceptor(cfg *config.Config, eng *engine.Engine, logger *slog.Logger, opts ...Option) *Interceptor

func NewReverseProxy

func NewReverseProxy(cfg *config.Config, eng *engine.Engine, logger *slog.Logger, opts ...Option) (http.Handler, *Interceptor, error)

NewReverseProxy builds the standalone sidecar handler: interception wrapped around a single-host reverse proxy pointed at service.upstream.

func (*Interceptor) SwapEngine

func (ic *Interceptor) SwapEngine(eng *engine.Engine)

SwapEngine atomically replaces the rule engine — the heart of config hot reload. In-flight requests finish under the policy they started with.

func (*Interceptor) Wrap

func (ic *Interceptor) Wrap(next http.Handler) http.Handler

Wrap is the embedded-middleware entry point.

type Option

type Option func(*Interceptor)

Option configures optional telemetry sinks.

func WithExporters

func WithExporters(d *export.Dispatcher) Option

WithExporters attaches the output-plugin dispatcher.

func WithMetrics

func WithMetrics(c *metrics.Collector) Option

WithMetrics attaches a Prometheus collector.

func WithStore

func WithStore(w *store.AsyncWriter) Option

WithStore attaches the async payload store.