httpcapture

package
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package httpcapture owns the bounded, in-memory HTTP capture handoff. It does no I/O and starts no goroutines. Only framework packages can submit captures.

Index

Constants

View Source
const (
	ResponseBytes = 4 << 10
	// MetadataBytes includes bounded strings, header entries, slice backing
	// arrays and snapshot bookkeeping, as well as the response head and the
	// bounded initial preread buffer during its one growth allocation.
	MetadataBytes = 96 << 10
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Body

type Body struct {
	Prefix        []byte // raw, at most cap+1; a later owner applies disclosure policy
	End           BodyEnd
	ObservedBytes int64                 // counts source reads, never replay reads
	MeasuredBytes value.Nullable[int64] // known only after observed EOF
	ReadFailure   ReadFailure
}

type BodyEnd

type BodyEnd uint8
const (
	NotRead BodyEnd = iota
	EOF
	OverCaptureLimit
	SourceFailure
)

type Completion

type Completion struct {
	Route                                 string
	Result                                observability.Result
	Status                                value.Nullable[uint16] // actual committed status; absent on precommit abort/hijack
	ResponseHead                          []byte
	ResponseHeaders                       []Field // the handler's header map at commit, before net/http adds transport headers
	ResponseContentType, ResponseEncoding string
	ResponseMetadataTruncated             bool
	ResponseTruncated                     bool
	ResponseBytes                         int64 // accepted by the HTTP writer, not proof of delivery
	Hijacked                              bool
	Aborted                               bool
	WriteFailed                           bool
	Duration                              time.Duration
}

type Config

type Config struct {
	BodyBytes     int
	RetainedBytes int64
	QueueSize     int
	Rate          int
	Burst         int
}

Config contains operational limits only; it cannot select paths or body mode.

func DefaultConfig

func DefaultConfig() Config

func (Config) Validate

func (c Config) Validate() error

Validate checks every limit against its hard cap. The retained budget must admit at least one whole reservation.

type DropReason

type DropReason uint8
const (
	DropSealed DropReason = iota
	DropRate
	DropCapacity
	DropBytes
	// DropWrite and DropShutdown are reported by the persistence owner after
	// it relinquishes records it could not store.
	DropWrite
	DropShutdown
	DropReasons
)

type Field

type Field struct {
	Name   string
	Values []string
}

type Metadata

type Metadata struct {
	RequestID                                                       attribution.RequestID
	ReceivedAt                                                      time.Time
	Prefix                                                          string
	Full                                                            bool
	Method                                                          string
	EscapedPath                                                     string
	RawQuery                                                        string
	ClientIP                                                        netip.Addr
	Headers                                                         []Field
	ContentType                                                     string
	ContentEncoding                                                 string
	DeclaredBytes                                                   value.Nullable[int64]
	PathTruncated, QueryTruncated, HeadersTruncated                 bool
	MethodTruncated, ContentTypeTruncated, ContentEncodingTruncated bool
}

type ReadFailure

type ReadFailure string
const (
	ReadFailed       ReadFailure = "read_failed"
	ReadTimeout      ReadFailure = "read_timeout"
	ClientDisconnect ReadFailure = "client_disconnect"
	BodyLimit        ReadFailure = "body_limit"
)

type Record

type Record struct {
	Snapshot Snapshot
	// contains filtered or unexported fields
}

Record is exclusively owned by the draining consumer, including its buffers.

func (*Record) Format

func (r *Record) Format(s fmt.State, verb rune)

func (*Record) Release

func (r *Record) Release()

type Recorder

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

Recorder reserves both a slot and bytes before HTTP allocates capture data. Dequeued snapshots remain charged until their consumer releases them.

func New

func New(config Config) (*Recorder, error)

func (*Recorder) BodyBytes

func (r *Recorder) BodyBytes() int

func (*Recorder) Done

func (r *Recorder) Done() <-chan struct{}

func (*Recorder) Drain

func (r *Recorder) Drain() *Record

Drain transfers one queued record without waiting. Release it only after all persistence/retry work has relinquished its snapshot.

func (*Recorder) Drops

func (r *Recorder) Drops() [DropReasons]uint64

Drops returns owned cumulative counters indexed by DropReason.

func (*Recorder) Lost

func (r *Recorder) Lost(reason DropReason, records, carried uint64)

Lost counts captures the consumer could not store, including the loss counts those records carried, so the next completed record reports them.

func (*Recorder) Ready

func (r *Recorder) Ready() <-chan struct{}

func (*Recorder) Reserve

func (r *Recorder) Reserve() *Reservation

Reserve never waits for capacity, a consumer, or I/O.

func (*Recorder) Seal

func (r *Recorder) Seal()

Seal refuses new reservations. Existing reservations may still complete.

func (*Recorder) Usage

func (r *Recorder) Usage() (int, int64)

Usage includes prereads, queued records and records held by the consumer.

type Reservation

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

func (*Reservation) Complete

func (l *Reservation) Complete(snapshot Snapshot)

Complete takes exclusive ownership of every snapshot buffer. The HTTP owner must never mutate or retain those buffers after this call.

type Snapshot

type Snapshot struct {
	Metadata      Metadata
	Body          Body
	Completion    Completion
	DroppedBefore uint64
}

func (Snapshot) Format

func (Snapshot) Format(s fmt.State, _ rune)

Capture data must never be disclosed through ordinary diagnostic formatting.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL