flakenet

README

flakenet

Wrap a net.Conn or net.PacketConn to simulate bandwidth limits, latency, jitter, and packet loss in Go tests. No root, no tc, no external processes.

OS-level tools like tc-netem shape traffic for the whole machine. netem works at the connection level, so tests stay hermetic and run anywhere.

Usage

lat := &policy.LatencyVar{}
lat.Set(100 * time.Millisecond)

conn := flakenet.NewPacketConn(udpConn, flakenet.PacketProfile{
    Latency: lat,
    Jitter:  policy.RandomJitter(20 * time.Millisecond),
    Loss:    policy.RandomLoss(0.01),
})

// Conditions can change while the connection is live.
lat.Set(500 * time.Millisecond)

Policies

Conditions are values, not constants. The Var types are safe for concurrent use and can be reset on an active connection, so a test can degrade a link mid-transfer without reconnecting.

• Bandwidth: throughput ceiling in bits/sec (StaticBandwidth, BandwidthVar)
• Latency: base propagation delay
• Jitter: delivery-time variance (RandomJitter is amplitude-based)
• Loss: packet drops (RandomLoss)
• Fault: trigger failures or closure on demand

Conn vs PacketConn

Conn is stream-oriented. Delayed bytes queue in FIFO order, so jitter shows up as head-of-line blocking rather than reordered or interleaved bytes.

PacketConn is datagram-oriented. Packets reorder naturally, and a later datagram can overtake an earlier one under sufficient jitter.

Relation to lossy

Builds on cevatbarisyilmaz/lossy with two changes: queued delivery instead of a goroutine per packet, which bounds memory at high throughput, and FIFO ordering on streams, which fixes byte interleaving under high jitter.

Documentation

Overview

Package flakenet provides network emulation wrappers for the net.PacketConn and net.Conn interfaces; it allows for dynamic thread-safe configuration of connection bandwidth, latency, jitter, and packet loss via indirection.

Index

• Constants
• func NewConn(c net.Conn, p StreamProfile) net.Conn
• func NewPacketConn(c net.PacketConn, p PacketProfile) net.PacketConn
• type Bandwidth
• type Conn
  • func (c *Conn) Close() error
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Write(b []byte) (n int, err error)
• type Fault
• type Jitter
• type Latency
• type LinkProfile
• type Loss
• type PacketConn
  • func (c *PacketConn) Close() error
  • func (c *PacketConn) SetDeadline(t time.Time) error
  • func (c *PacketConn) SetWriteDeadline(t time.Time) error
  • func (c *PacketConn) WriteTo(p []byte, addr net.Addr) (n int, err error)
• type PacketProfile
• type StreamProfile

Constants

const (
	// IPv4HeaderSize is the min size of an IPv4 header in bytes.
	IPv4HeaderSize = 20
	// IPv6HeaderSize is the fixed size of an IPv6 header in bytes.
	IPv6HeaderSize = 40
	// TCPHeaderSize is the min size of a TCP header in bytes, excluding options.
	TCPHeaderSize = 20
	// UDPHeaderSize is the fixed size of a UDP header in bytes.
	UDPHeaderSize = 8
)

const (
	// EthernetDefaultMTU is the standard MTU for most WANs and Internet traffic (1500 bytes).
	EthernetDefaultMTU = 1_500
	// EthernetJumboFrameMTU is used in data center environments to reduce CPU overhead (9000 bytes).
	EthernetJumboFrameMTU = 9_000
	// IPMaximumMTU represents the maximum possible size of an IP packet.
	IPMaximumMTU = 65_535
)

Functions

func NewConn

func NewConn(c net.Conn, p StreamProfile) net.Conn

NewConn wraps an existing net.Conn to emulate network conditions for stream-oriented protocols like TCP. It ensures that data order is strictly preserved even when jitter or latency is applied.

func NewPacketConn

func NewPacketConn(c net.PacketConn, p PacketProfile) net.PacketConn

NewPacketConn wraps an existing net.PacketConn to emulate network conditions for packet-oriented protocols like UDP.

Types

type Bandwidth

type Bandwidth interface {
	// Limit returns the allowed throughput in bits per second.
	Limit() uint64
}

Bandwidth models the capacity of the link.

type Conn

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

Conn wraps an existing net.Conn to emulate network conditions for stream-oriented protocols.

To prevent stream corruption, Conn uses an internal FIFO queue (writeCh) to ensure that data is written to the underlying socket in the exact order it was received from the application, even in the presence of latency and jitter.

func (*Conn) Close

func (c *Conn) Close() error

Close implements net.Conn.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline implements net.Conn.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements net.Conn.

func (*Conn) Write

func (c *Conn) Write(b []byte) (n int, err error)

Write implements net.Conn.

type Fault

type Fault interface {
	// ShouldClose returns true if the connection should be severed abruptly.
	ShouldClose() bool
}

Fault models the stability of a connection.

type Jitter

type Jitter interface {
	// Duration returns the random variance to add to the latency.
	Duration() time.Duration
}

Jitter models the variance in transmission delay.

type Latency

type Latency interface {
	// Duration returns the delay for the current operation.
	Duration() time.Duration
}

Latency models the delay of a network transmission.

type LinkProfile

type LinkProfile struct {
	Latency   Latency
	Jitter    Jitter
	Bandwidth Bandwidth
}

LinkProfile defines the shared physical properties of a network link.

type Loss

type Loss interface {
	// Drop returns true if the current datagram should be discarded.
	Drop() bool
}

Loss models the unreliability of a datagram link.

type PacketConn

type PacketConn struct {
	net.PacketConn
	// contains filtered or unexported fields
}

PacketConn wraps an existing net.PacketConn to emulate network conditions for packet-oriented protocols.

Unlike Conn, PacketConn allows for natural packet reordering if jitter configurations cause a later packet to be scheduled for delivery earlier than a previous one.

func (*PacketConn) Close

func (c *PacketConn) Close() error

Close implements net.PacketConn.

func (*PacketConn) SetDeadline

func (c *PacketConn) SetDeadline(t time.Time) error

SetDeadline implements net.PacketConn.

func (*PacketConn) SetWriteDeadline

func (c *PacketConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements net.PacketConn.

func (*PacketConn) WriteTo

func (c *PacketConn) WriteTo(p []byte, addr net.Addr) (n int, err error)

WriteTo implements net.PacketConn.

type PacketProfile

type PacketProfile struct {
	// MTU (Maximum Transmission Unit) is the largest packet size allowed.
	// This value includes L3/L4 headers.
	//
	// Defaults to [EthernetDefaultMTU] if 0.
	MTU uint

	Latency   Latency
	Jitter    Jitter
	Bandwidth Bandwidth
	Loss      Loss
}

PacketProfile extends the link with datagram-specific behaviors.

type StreamProfile

type StreamProfile struct {
	// MTU (Maximum Transmission Unit) is the largest packet size allowed.
	// This value includes L3/L4 headers.
	//
	// Defaults to [EthernetDefaultMTU] if 0.
	MTU uint

	Latency   Latency
	Jitter    Jitter
	Bandwidth Bandwidth
	Fault     Fault
}

StreamProfile extends the link with stream-specific behaviors.