netem

type BatchedReader struct{ *Endpoint }

type Config struct {
	// Delay is the one-way propagation delay.
	Delay time.Duration

	// Jitter perturbs Delay by a uniform amount in [-Jitter, +Jitter].
	// Delivery order is preserved unless Jitter exceeds packet spacing.
	Jitter time.Duration

	// LossRate is the independent probability of dropping a packet, in [0,1].
	// This is loss on the medium; it is counted separately from queue
	// overflow, which is loss caused by congestion.
	LossRate float64

	// DuplicateRate is the probability that a packet is delivered twice, in
	// [0,1]. The copy is made past the bottleneck, as a link-layer
	// retransmission or a misbehaving switch would make it: it takes no
	// queue space and arrives just after the original.
	DuplicateRate float64

	// ReorderRate is the probability that a packet is displaced backwards in
	// the delivery order by ReorderDelay, in [0,1].
	ReorderRate float64

	// ReorderDelay is how much extra delay a reordered packet receives.
	// Defaults to DefaultReorderDelay.
	ReorderDelay time.Duration

	// BandwidthBps is the bottleneck rate in bits per second. Zero means
	// unlimited: packets are not serialized and never queue.
	//
	// Packets are serialized at this rate, so a packet's transmission
	// occupies len*8/BandwidthBps seconds during which no other packet on
	// this link can be sent. Flows sharing a link contend for it.
	BandwidthBps uint64

	// QueueBytes is the bottleneck queue capacity. A packet arriving when the
	// queue is full is tail-dropped. Defaults to DefaultQueueBytes.
	//
	// This is what bounds standing queueing delay, and therefore what a
	// delay-based controller is supposed to keep clear of.
	QueueBytes int

	// NoQueueSamples stops the link recording a QueueSample for every
	// packet. The samples are what QueueSamples reports, for the benchmarks'
	// standing-queue figures, and they are kept for the link's life: 40 bytes
	// a packet, which a soak of hours turns into gigabytes of the process's
	// heap -- 2.5 GB in two hours, all of it the emulator's, which is what
	// the soak then measured.
	NoQueueSamples bool

	// MTU is the largest datagram the path will carry, in bytes. Zero means
	// unlimited, which is what every link modelled here did before: any
	// datagram, however large, arrived.
	//
	// A datagram larger than this is dropped outright, which is what an IPv6
	// path does, and what an IPv4 path does for a packet marked don't-fragment.
	// It is counted separately from loss and from queue overflow, because it is
	// neither: it says something about size, and nothing about congestion.
	//
	// This exists because path-MTU discovery had never been tested against a
	// path that limits size. The search converged on whatever ceiling it was
	// given, every time, because nothing in the harness could refuse a large
	// packet -- so the half of the search that lowers the ceiling was never
	// exercised end to end.
	MTU int

	// OnMTUDrop, when set, is called for every datagram this link refuses for
	// being larger than MTU. It is the router that would have forwarded the
	// datagram sending an ICMP "fragmentation needed" message back to the
	// sender, and it carries what such a message carries: the front of the
	// offending datagram and the next-hop MTU.
	//
	// payload is the whole refused datagram; a real router quotes only its
	// front, so a test that wants to model that should truncate. src and dst
	// are the endpoint names this link runs between, so a caller can route
	// the report back to the socket that sent it. linkMTU is this link's MTU
	// expressed the way ICMP expresses it -- the largest IP datagram the hop
	// will carry -- which is the emulated link's MTU plus the IP and UDP
	// headers a real path would also have had to carry.
	//
	// It runs on the link's goroutine with no lock held, and must not block.
	//
	// Without this, an emulated path that refuses a large datagram is
	// indistinguishable from one that lost it, so the half of path-MTU
	// discovery that takes a router's word for the limit could not be tested
	// end to end at all.
	OnMTUDrop func(payload []byte, src, dst string, linkMTU int)

	// OnOffered, if set, sees every datagram offered to this link, before
	// anything decides whether it is carried, dropped or delayed, with the
	// instant it was offered. The payload is a copy.
	//
	// It runs on the sender's goroutine with no lock held, and must not
	// block. It exists so a test can see what a sender puts on the wire and
	// when -- a retransmission burst is invisible in delivered-packet counts,
	// because the burst is exactly what a blackout drops.
	OnOffered func(payload []byte, at time.Time)

	// FragmentOversized makes this link fragment a datagram larger than MTU
	// and forward it, instead of dropping it -- unless the sender set the
	// don't-fragment bit, in which case it is dropped as before.
	//
	// This is the difference between an IPv4 path and an IPv6 one, and it is
	// the only condition under which the don't-fragment bit changes anything.
	// With it false (the default) this link models IPv6: oversized is always
	// dropped, so a path-MTU search learns the truth whether or not it sets
	// the bit.
	//
	// With it true the link models IPv4, where an MTU probe sent without the
	// bit is fragmented, arrives, and is acknowledged -- telling the search
	// that a size the path cannot actually carry in one piece is fine. That
	// is the failure utp.DontFragmentWriter exists to prevent, and this is
	// where it can be observed.
	FragmentOversized bool

	// Seed seeds this link's PRNG. Links in one Network derive distinct seeds
	// from Network's seed, so a single Seed makes a whole topology
	// reproducible.
	Seed int64
}

type DeliverySample struct {
	At    time.Time
	Bytes uint64
}

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

type DriftingClock struct {
	utp.Conn
	// contains filtered or unexported fields
}

type DropCause int

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

type EndpointStats struct {
	PacketsReceived uint64
	BytesReceived   uint64
	// PacketsDroppedFullInbox is packets that arrived while the application
	// was not reading fast enough.
	PacketsDroppedFullInbox uint64
}

type FlowOptions struct {
	// InitiatorCid is the lower of the two connection ids. Give each
	// concurrent flow a distinct value at least 2 apart.
	InitiatorCid uint16
	// Config, if non-nil, is used as the base connection configuration.
	// Its Metrics observer is replaced.
	Config *utp.ConnectionConfig
	// MetricsInterval controls sampling density.
	MetricsInterval time.Duration
	// Verify compares received bytes against what was sent. Costs a full
	// comparison; leave off for long soaks.
	Verify bool
}

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

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

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

type QueueSample struct {
	At           time.Time
	Delay        time.Duration
	BacklogBytes int
}

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

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

type RenoResult struct {
	BytesTransferred int
	Elapsed          time.Duration
	Goodput          Throughput
	PacketsSent      uint64
	Retransmits      uint64
	Timeouts         uint64
	FastRetransmits  uint64
	// CwndMaxBytes and CwndMeanBytes describe the congestion window over the
	// transfer, sampled once per acknowledgement.
	CwndMaxBytes  uint32
	CwndMeanBytes uint64
	// Delivered is the receiver's in-order byte count over time, sampled at
	// most every deliverySampleInterval, so a split against another flow can
	// be taken over only the time both were running. See SplitWhileBothRan.
	Delivered []DeliverySample
}

type Stats struct {
	// Offered is what the sender handed to the link.
	PacketsOffered uint64
	BytesOffered   uint64

	// Delivered is what reached the destination's inbox.
	PacketsDelivered uint64
	BytesDelivered   uint64

	// Dropped is the total, broken down by cause below.
	PacketsDropped    uint64
	DroppedByLoss     uint64
	DroppedByQueue    uint64
	DroppedByReceiver uint64
	// DroppedByMTU counts datagrams larger than the link's MTU. This is a
	// statement about size, not about congestion, and is kept apart from the
	// other two for that reason.
	DroppedByMTU uint64

	// PacketsFragmented counts datagrams larger than the link's MTU that were
	// forwarded anyway, because Config.FragmentOversized is set and the
	// sender did not forbid fragmentation. They are delivered, so they are
	// not dropped and not counted as such -- the number exists because "the
	// probe arrived" and "the probe arrived in one piece" are different
	// facts, and a path-MTU search can only tell them apart if something
	// records the difference.
	PacketsFragmented uint64

	PacketsReordered uint64
	// PacketsDuplicated counts the extra copies Config.DuplicateRate made.
	PacketsDuplicated uint64

	QueueDelaySum   time.Duration
	QueueDelayCount uint64
	QueueDelayMax   time.Duration
}

type Summary struct {
	Samples int
	Span    time.Duration

	CwndMeanBytes uint64
	CwndMaxBytes  uint32
	CwndMinBytes  uint32
	// CwndPinnedAtMin is the fraction of samples where the window sat at its
	// floor. A controller stuck here has collapsed rather than backed off.
	CwndPinnedAtMin float64

	RTTMean time.Duration
	RTTP50  time.Duration
	RTTP95  time.Duration
	RTTMax  time.Duration
	// RTTMin is the lowest round trip seen over the whole flow. On a path
	// this flow started on while it was empty, this is the path's real
	// unloaded round trip.
	RTTMin time.Duration

	// StandingQueueP50 and StandingQueueP95 are the round trip above
	// RTTMin -- the queue this flow actually left standing on the path.
	//
	// This exists because QueueingDelay below cannot be trusted for that
	// question. QueueingDelay is `PeerTimestampDiff - BaseDelay`, and BaseDelay is
	// the *controller's own estimate* of the empty path. A delay-based
	// controller whose base-delay estimate has drifted upwards -- which is
	// precisely the failure LEDBAT++ exists to fix -- reports a small
	// queueing delay while sitting on a large queue, because it is
	// subtracting the queue from itself.
	//
	// Measured on a 40ms path: classic LEDBAT reported 156µs of queueing
	// delay while its round trip sat at 80ms. It was causing 40ms of queue
	// and could not see it. StandingQueueP50 reports the 40ms.
	StandingQueueP50 time.Duration
	StandingQueueP95 time.Duration

	// Queueing delay is the excess of measured one-way delay over the lowest
	// seen: the standing queue LEDBAT exists to bound.
	QueueingDelayMean time.Duration
	QueueingDelayP50  time.Duration
	QueueingDelayP95  time.Duration
	QueueingDelayMax  time.Duration

	BytesSent            uint64
	PacketsSent          uint64
	PacketsRetransmitted uint64
	RetransmitRate       float64
	Timeouts             uint64
	FastRetransmits      uint64
}

type Throughput struct {
	Bytes    uint64
	Duration time.Duration
}

type TransferResult struct {
	// BytesTransferred is what the receiver actually read.
	BytesTransferred int
	// Elapsed is wall-clock time from connect to end of stream.
	Elapsed time.Duration
	// Goodput is application-level throughput: payload delivered per second,
	// excluding headers and retransmissions. This is the number that matters
	// -- a flow can be busy and still deliver nothing.
	Goodput Throughput
	// Sender and Receiver hold the recorded metric series for each side.
	Sender   *Recorder
	Receiver *Recorder
	// Verified reports whether the received bytes matched what was sent.
	Verified bool
}

type UtpPair struct {
	Net          *Network
	A, B         *Endpoint
	SockA, SockB *utp.Socket
}