span

type Collector ¶

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

Collector accumulates spans out of order, deduplicating and merging them eagerly, and releases them in Start order once the caller guarantees no further span can touch them.

The zero value is a ready-to-use, empty Collector.

Merge/precedence rules (deterministic — see docs/DESIGN.md):

1. Identical spans (same Start/End) dedupe: keep the highest Confidence, then the lowest Rule index.
2. Overlapping or exactly adjacent (a.End == b.Start) spans merge into their union. Attribution (Rule/Confidence of the merged result) goes to the higher-Confidence contributor; ties break to the contributor with the earlier original Start, then to the lower Rule index.
3. Merging is transitive: a chain of overlapping/adjacent spans collapses into a single span.

entries is always kept sorted by start and, because merged spans are non-overlapping by construction, is therefore also sorted by end.

func (c *Collector) Add(s Span)

func (c *Collector) Earliest() (Span, bool)

func (c *Collector) Pending() bool

func (c *Collector) Release(dst []Span, limit int64) []Span

func (c *Collector) Reset()

type MaskStrategy ¶

type MaskStrategy uint8

MaskStrategy selects how a redacted span's bytes are replaced in the Writer's output.

const (
	// MaskFixedMarker writes exactly one copy of the fixed marker per
	// span, regardless of the span's length. This is the default.
	MaskFixedMarker MaskStrategy = iota

	// MaskLengthPreserving writes one '*' per redacted input byte, so
	// output length always equals input length.
	MaskLengthPreserving

	// MaskFormatPreserving writes one byte per redacted input byte,
	// preserving its coarse character class: uppercase letters become
	// 'X', lowercase letters 'x', digits '9'; the separator bytes
	// - _ . : / + = @ pass through verbatim; every other byte becomes
	// '*'. Output length equals input length and token shapes (JWT
	// dots, UUID dashes, base64 padding) survive. Note the preserved
	// separators and class shape ARE information about the original
	// secret; this strategy trades that disclosure for format fidelity
	// and must be an explicit caller choice.
	MaskFormatPreserving
)

type Span ¶

type Span struct {
	Start, End int64 // absolute input offsets, half-open, Start < End
	Rule       int   // index into the active rule set
	Confidence uint8
}

Span is a confirmed redaction candidate expressed as an absolute, half-open byte range [Start, End) within the input stream.

Rule is the index of the detection rule that produced the span, into whatever rule set the caller is using. Confidence is an opaque ordering value: higher means "more confident this is a true positive".

type Writer ¶

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

Writer emits input bytes to an underlying io.Writer, replacing each redacted span's bytes according to a MaskStrategy: with exactly one copy of a fixed marker (MaskFixedMarker), or byte for byte with masked replacements (MaskLengthPreserving, MaskFormatPreserving).

Writer tracks absolute input offsets across a sequence of Emit calls. The caller (the engine) must feed it consecutive, non-overlapping, gap-free input regions in ascending order — that is, the region passed to one Emit call must start exactly where the previous one ended (the very first call may start at any offset, e.g. 0). Each Emit call also carries the spans (already merged, sorted by Start, non-overlapping — as produced by Collector.Release) whose Start falls within that call's region.

Straddling spans ¶

A merged span may be longer than a single Emit call's region: it can start in one call and end in a later one. The contract for this case is:

• A span is reported to Emit exactly once, in the call whose region contains the span's Start. Its End may be beyond that region.
• The caller must NOT pass that span (or any remainder of it) again in later calls; Writer tracks the in-progress redaction internally and automatically consumes input bytes belonging to it across as many subsequent Emit calls as needed, without emitting any further marker for it.
• Under MaskFixedMarker the marker is written exactly once, at the point the span starts, and the span's remaining bytes are skipped. Under the preserving strategies each Emit call instead writes the masked replacement of the span bytes its region covers, so the replacement accumulates to exactly the span's length across calls.

Discarded span interiors ¶

The engine may discard the interior bytes of a very long merged span under buffer pressure and replay them as zero-filled scratch. Under MaskFixedMarker those bytes are never read. Under the preserving strategies the zero bytes mask to '*' (0x00 is in no preserved class), so length preservation still holds exactly and format preservation degrades to '*' fill for the discarded stretch only.

A span's Start must never be less than the offset of the region currently being processed (i.e. it must not start before or inside a still-pending straddling redaction, and it must not start before the current Emit call's off). Violating this, or feeding non-contiguous regions, is a programmer error and Writer panics.

func NewMaskingWriter(w io.Writer, marker []byte, strategy MaskStrategy) *Writer

func NewWriter(w io.Writer, marker []byte) *Writer

func (w *Writer) BytesWritten() int64

func (w *Writer) Emit(off int64, data []byte, spans []Span) error

func (w *Writer) RedactedBytes() int64