tunnel

type DecodedFrame struct {
	MsgID   uint32
	Flags   Flags
	Payload []byte // alias into the input buffer; copy if you need to outlive it
}

type Dispatcher struct {
	KCPConn   *TunnelPacketConn
	Handshake chan<- ReceivedFrame
	Legacy    chan<- ReceivedFrame // ping/pong/test frames

	DroppedKCP   uint64
	DroppedOther uint64
}

type Flags uint8

type RateController struct {

	// Tunables (exported for tests / call-site override).
	MinBps      float64
	MaxBps      float64
	LowLoss     float64 // below this smoothed loss we ramp up
	HighLoss    float64 // above this we back off
	IncreaseMul float64 // multiplicative increase per feedback when clean
	EMAWeight   float64 // weight of the newest sample in the loss EMA
	// contains filtered or unexported fields
}

type Reassembler struct {
	// MaxWait is how long a frame waits after its LAST received packet before
	// it is released incomplete. It must be measured from the last packet, not
	// from the first: a 64 KB sample spread over a ~1.5 Mbit/s mobile leg takes
	// ~350 ms to arrive in full, so an age-based deadline would cut healthy,
	// loss-free frames in half.
	MaxWait time.Duration

	// MaxAge bounds how long a frame may be held in total, so a source that
	// keeps dribbling packets into one timestamp cannot pin memory forever.
	MaxAge time.Duration
	// MaxPending caps the frames held at once; the oldest is released early.
	MaxPending int

	Complete uint64 // frames released with every packet
	Partial  uint64 // frames released with holes (timeout or eviction)
	Late     uint64 // packets for frames already released
	Dups     uint64 // duplicate packets within a pending frame
	// contains filtered or unexported fields
}

type ReceivedFrame struct {
	MsgID   uint32
	Flags   Flags
	Payload []byte
}

type Receiver struct {

	// DropFlag, when non-zero, causes [Receiver.walkFrames] to silently
	// discard any frame whose Flags has DropFlag set. Used by the SFU pool
	// architecture: server-side pool members set DropFlag=FlagFromServer
	// so they drop frames produced by other server-side pool members
	// (which the SFU broadcasts to everyone in the room). 0 = no filtering
	// (legacy single-instance behaviour).
	DropFlag Flags

	RTPPackets     atomic.Uint64
	StripErrs      atomic.Uint64
	BadMagic       atomic.Uint64
	DecodeErrs     atomic.Uint64
	FramesPushed   atomic.Uint64
	HeaderTooShort atomic.Uint64
	HeaderBadStart atomic.Uint64
	SideFiltered   atomic.Uint64 // count of frames dropped via DropFlag
	PartialFrames  atomic.Uint64 // samples released with holes after the reassembly wait
	ResyncFrames   atomic.Uint64 // tunnel frames salvaged from mid-sample fragments
	LatePackets    atomic.Uint64 // packets for samples already released
	// contains filtered or unexported fields
}

type ReleasedFrame struct {
	// Segments holds the contiguous runs of the frame in sequence order. A
	// complete frame has exactly one segment.
	Segments [][]byte
	Complete bool
	// AtBegin reports that Segments[0] starts at the frame's first packet,
	// i.e. on the codec prefix rather than somewhere mid-frame.
	AtBegin bool
}

type Sender struct {
	FrameDuration time.Duration

	VP8Prefix []byte
	VP8Wrap   bool

	BatchSize         int
	BatchInterval     time.Duration
	PacingInterval    time.Duration
	KeepaliveInterval time.Duration

	// IdleKeepaliveInterval is the keepalive cadence used when no real
	// tunnel data has been sent for IdleAfter. Defaults to ~1fps —
	// enough to keep the SFU's track-active heuristics happy while
	// dropping our battery footprint by ~25× compared to the active
	// 25fps cadence. Set to 0 to disable idle-mode entirely.
	IdleKeepaliveInterval time.Duration
	IdleAfter             time.Duration

	// BatchSizeJitter randomizes per-batch flush threshold to
	// BatchSize × (1 ± BatchSizeJitter). 0.0 means constant BatchSize
	// (legacy behaviour); 0.4 means each batch flushes at a size drawn
	// uniformly from [0.6·BatchSize, 1.4·BatchSize]. Mimics the size
	// distribution of real VP8 interframes which varies with motion —
	// uniform 6KB samples every flush is a giveaway to classifiers.
	// See [Sender.pickBatchTarget].
	BatchSizeJitter float64

	// PacingJitter is the maximum ±delay applied on top of PacingInterval
	// per ship. 0 = constant pacing (legacy). Non-zero breaks the
	// periodic-write fingerprint that REMB/TWCC heuristics latch onto.
	PacingJitter time.Duration

	// KeyframeEvery, when >0 and combined with KeyframeBatchSize, makes
	// ~1-in-N batches use KeyframeBatchSize as the flush threshold instead
	// of BatchSize±jitter. Imitates the size spike of a real VP8 keyframe
	// (5-10× larger than interframes). 0 disables the peak entirely.
	KeyframeEvery     int
	KeyframeBatchSize int

	// SideFlag is OR'd into every outgoing frame's Flags byte. Used by the
	// SFU pool architecture to stamp each side's frames so the receiver
	// can drop same-side cross-talk (e.g. server bot J seeing server bot
	// K's frames via SFU broadcast). 0 = legacy single-instance behaviour.
	// See [tunnel.FlagFromServer].
	SideFlag Flags

	// InterframePrefix is the bytes prepended to outbound samples that
	// are NOT periodic keyframes — i.e. ~98% of frames in a realistic
	// VP9 stream. When non-empty and VP8Wrap is true, the sendLoop
	// alternates between [Sender.VP8Prefix] (keyframe header) for every
	// KeyframePeriod-th frame and InterframePrefix for all the others.
	//
	// pion's VP9 packetizer reads the uncompressed header inside the
	// prefix to decide keyframe vs interframe — keyframes emit an 11-byte
	// RTP descriptor (with Scalability Structure), interframes emit a
	// 3-byte descriptor. Real video sources alternate the same way, so
	// matching this ratio is critical for any DPI classifier looking at
	// keyframe-rate fingerprints.
	//
	// Empty (default) preserves the legacy single-prefix behaviour
	// (every frame uses VP8Prefix and is therefore tagged as keyframe).
	// 2026-05-28 — added to fix the "100% keyframes" DPI fingerprint.
	InterframePrefix []byte

	// KeyframePeriod controls how often the data path emits a real
	// keyframe (using VP8Prefix). Every KeyframePeriod-th frame counter
	// uses keyframe prefix; all others use InterframePrefix. 0 disables
	// alternation — every frame is a keyframe (legacy behaviour). Realistic
	// values: 60-90 (matches real WebRTC video sources at ~25-30 fps).
	KeyframePeriod int

	TxSamples atomic.Uint64
	TxBytes   atomic.Uint64
	TxBatches atomic.Uint64
	TxDrops   atomic.Uint64 // batches dropped on full queue (backpressure) — diagnostic

	// WriteMu, when non-nil, serializes track.WriteSample across ALL goroutines
	// that write the same video track (this Sender's data path plus the keyframe
	// refresh / PLI-keyframe helpers). pion's TrackLocalStaticSample assigns
	// seq/ts/pictureID under its own lock but RELEASES it before the per-packet
	// WriteRTP loop, so concurrent writers interleave packets ON THE WIRE — a
	// big data frame's packets get split by an injected keyframe packet, the SFU
	// sheds the out-of-order tail (gappy forward while TWCC stays 0% loss), and
	// with no RTX the gaps are never repaired → slot unbind. Holding one shared
	// mutex around the whole WriteSample makes each frame flush completely before
	// the next starts. Mutates zero wire bytes — only ordering. 2026-07-22.
	WriteMu *sync.Mutex

	// Logger, when non-nil, receives throttled backpressure-drop diagnostics.
	// Optional / nil-safe. Set by the server telemost path (2026-06-25) to
	// tell local queue-overflow stalls apart from network loss.
	Logger *log.Logger
	// contains filtered or unexported fields
}

type StreamManager struct {
	PacketConn *TunnelPacketConn
	KCPConn    net.Conn // the single KCP session (as net.Conn)
	KCPSession *kcp.UDPSession
	Mux        *yamux.Session
	Logger     *log.Logger
	IsServer   bool
}

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