Documentation
¶
Overview ¶
Package traffic defines four-leg observation, privileged raw capture, and redactor hooks (design §10–§11). RawCaptureSink is the stable name for privileged “capture sink” bytes; general traffic uses Observer on redacted or structured bodies only.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotConfigured = errors.New("lipsdk/traffic: traffic facade not configured")
ErrNotConfigured means no traffic services are bound for this execution snapshot.
Functions ¶
func ApplyRedactors ¶
func ApplyRedactors(ctx context.Context, leg Leg, meta CaptureMeta, body []byte, redactors []Redactor) []byte
ApplyRedactors runs redactors in registration order. On error the last good payload is kept (fail-open). Nil redactors are skipped.
Types ¶
type CaptureMeta ¶
type CaptureMeta struct {
TraceID string
ALegID string
BLegID string
PrincipalID string
SessionID string
AttemptSeq int
BackendID string
FrontendID string
Scope scope.PrincipalScopeView
}
CaptureMeta is correlation metadata for traffic legs: request trace, attempt lineage, principal and session identifiers, and route-facing backend/frontend labels. It intentionally excludes transport and provider concrete types (hexagonal task 5.2). Scope is optional safe attribution propagated to observers as metadata; it is never injected into payload bytes (req 6.4, 7.4).
type DisabledRawCapture ¶
type DisabledRawCapture struct{}
DisabledRawCapture rejects raw capture until explicitly granted by core policy.
func (DisabledRawCapture) WriteRaw ¶
func (DisabledRawCapture) WriteRaw(context.Context, Leg, CaptureMeta, []byte) error
type Leg ¶
type Leg string
Leg identifies one hop in the four-leg observation model (design section 10).
type NoopObserver ¶
type NoopObserver struct{}
NoopObserver drops observations (safe default for tests and early wiring).
func (NoopObserver) OnObservation ¶
func (NoopObserver) OnObservation(context.Context, Observation) error
type Observation ¶
type Observation struct {
Leg Leg
TraceID string
ALegID string
BLegID string
PrincipalID string
SessionID string
AttemptSeq int
BackendID string
FrontendID string
Protocol string
ContentType string
Body []byte
Scope scope.PrincipalScopeView
RecordedAt time.Time
}
Observation is the stable traffic observer contract (hexagonal task 5.2): only correlation and routing metadata plus a redacted or non-sensitive body snapshot. It must not carry transport types (for example *http.Request), provider SDK handles, executor-private structs, or raw privileged payloads unless policy explicitly places them on the redacted path. Callers of Observer.OnObservation run after PortBundle.Emit applies redactors; [Body] is the post-redaction bytes passed to the observer.
Scope is optional safe principal/scope attribution (requirement 6.4). It is additive metadata only; existing observers may ignore it. Scope must never be injected into [Body]; [Body] remains the wire payload for the leg (requirements 7.1, 7.4).
type Observer ¶
type Observer interface {
OnObservation(ctx context.Context, ev Observation) error
}
Observer receives non-mutating traffic observations (design section 10). Implementations should treat Observation as read-only data for logging, transcript, or metrics adapters; they must not mutate the slice backing Observation.Body in place if they retain it beyond the call.
func ChainObservers ¶
ChainObservers returns an Observer that invokes each non-nil child in order. Handler errors are ignored (fail-open; design §17 traffic observation).
type PortBundle ¶
type PortBundle struct {
Raw RawCaptureSink
Obs Observer
Red []Redactor
}
PortBundle is the raw/redactor/observer triple used at each traffic leg (design sections 10-11). [Emit] maps CaptureMeta and the leg/protocol/content-type arguments into Observation only; it does not attach transport handles or provider-specific values beyond those string fields.
func (PortBundle) Emit ¶
func (p PortBundle) Emit(ctx context.Context, leg Leg, meta CaptureMeta, protocol, contentType string, payload []byte)
Emit runs privileged raw capture, redactors, then the general observer (fail-open on observer errors). A zero or empty bundle is a no-op. The observer sees only metadata copied from meta plus leg, protocol, contentType, redacted body, and a recorded timestamp—see Observation (task 5.2).
func (PortBundle) EmitIsNoop ¶
func (p PortBundle) EmitIsNoop() bool
EmitIsNoop reports whether PortBundle.Emit returns without doing work. Hot-path callers (e.g. per-stream event encoding) can use this to skip expensive payload preparation. Disabled raw ports and NoopObserver match what [Emit] effectively does without touching payloads.
type RawCaptureSink ¶
type RawCaptureSink interface {
WriteRaw(ctx context.Context, leg Leg, meta CaptureMeta, payload []byte) error
}
RawCaptureSink receives verbatim bytes for privileged capture paths (design §10), using the same CaptureMeta correlation fields as structured observers. It is not a general byte sink for arbitrary adapter internals.
func MultiRawCapture ¶
func MultiRawCapture(sinks ...RawCaptureSink) RawCaptureSink
MultiRawCapture fans out verbatim payloads to each non-nil sink. Errors are ignored (fail-open).
type Redactor ¶
type Redactor interface {
ID() string
Redact(ctx context.Context, leg Leg, meta CaptureMeta, body []byte) ([]byte, error)
}
Redactor runs on the observation path after privileged raw capture and before general observers (design §11). Implementations must be deterministic for tests; errors are ignored by ApplyRedactors (fail-open) so request execution is not blocked.
func MaterializeSortedRedactors ¶
MaterializeSortedRedactors returns a defensive copy sorted by the same contract as other extension stages: ascending Priority, then ID, then registration index (design §17).
Source Files