config.md

Config reference

The exhaustive field table. Generated API docs (zig build docs) cover the methods; this covers the comptime configuration. See the config guide for prose.

Config

Field	Type	Default	Meaning
protocol_id	u64	0	wire-compat gate; mismatch = silent drop
app_version	u32	0	negotiated in the handshake (0 = accept any)
capabilities	u64	0	authenticated supported-feature bitset
required_capabilities	u64	0	bits that negotiation must retain
channels	type	-	result of magnet.proto.channels(.{…}) (required)
unconnected_message	?type	null	shared type for typed connectionless send/receive; raw APIs do not require it
congestion	?type	null	controller type; null → NewReno
tracer	type	trace.Null	observability tracer
limits	Limits	.{}	ring/pool sizes
security	Security	.{}	encryption / handshake
delivery	Delivery	.{}	ack / loss / fragmentation knobs
seq	SeqWidths	.{}	wrap widths per domain
degrade	Degrade	.{}	pool-exhaustion policy
mtu	u16	1200	conservative datagram budget
max_datagram	u16	1400	hard cap (PMTUD may raise the working MTU to here)
enable_pmtud	bool	false	live path-MTU discovery
pacing	Pacing	.{}	token-bucket pacing options on the reliable path
memory_budget_bytes	usize	0	compile-time Endpoint(cfg) ceiling; 0 disables

Pacing

Field	Default	Meaning
enabled	true	enable token-bucket pacing
burst_bytes	19200	maximum accumulated send credit

Limits

Field	Default	Sizes
max_connections	64	endpoint connection table
channel_cap	128	per-channel reorder/dedup + reliable send window
bridge_cap	1024	packet→message map (in-flight window)
recvpn_cap	256	received-pn window for ack generation
max_payload	256	max single serialized message
max_msgs_pkt	16	reliable messages packed per datagram
unconnected_cap	0	connectionless queue size (0 = off; power of two when >0)
event_cap	128	lossless connection lifecycle event ring
challenge_cap	64	queued stateless challenge replies
rate_limit_cap	256	per-source handshake token buckets
token_dedup_cap	256	unexpired accepted connect-token MACs

Security

Field	Default	Meaning
mode	.none	.aead to encrypt
aead	.chacha20poly1305	or .aes256gcm
replay_window	1024	sliding replay window (bits)
tokens	false	require backend-signed connect tokens
connection_ids	false	connection IDs + migration (requires .aead)
challenge_rotation_s	240	automatic stateless-cookie secret rotation cadence
key_update_packets	1048576	automatic traffic-key update packet cadence (0 = off)
key_update_ms	3600000	automatic traffic-key update time cadence (0 = off)
forward_secrecy	false	mix an ephemeral X25519 exchange into traffic keys
handshake_rate_per_s	20	per-source hello refill rate (0 = off)
handshake_burst	10	per-source hello burst allowance
handshake_timeout_ms	10000	give up on an incomplete handshake (0 = never)
handshake_response_retries	4	re-hello after this many unanswered responses

handshake_timeout_ms is the only bound on an unfinished handshake: idle_timeout_ms is gated on having received application data, which a handshake that never completes never does. With it disabled, a client that cannot reach the server retransmits indefinitely and holds its connection slot.

Per-channel fields

Each channels(.{ ... }) entry accepts send_cap, recv_cap, and max_payload. Zero inherits the corresponding global limit. Capacities must be powers of two; payload ceilings reduce the actual monomorphized per-channel message storage. Fragmentation uses a uniform fragment size, so fragmented configurations inherit the global payload ceiling.

Two cross-field rules are enforced at compile time:

• send_cap must not exceed recv_cap on reliable_unordered, reliable_sequenced, and reliable_ordered_sequenced. Dedup is a rolling window of recv_cap sequences while the sender may retransmit anything within send_cap; receive credit bounds the newest sequence, not the span, so a wider send window lets a retransmit fall outside the dedup window and be delivered twice. reliable_ordered is exempt, since its cursor is a capacity-independent monotone barrier.
• With fragmentation off, max_payload must fit one datagram after the public header, the AEAD tag, and the frame header, measured against the widest truncated packet number. Otherwise the packer can never place the message, and the channel head stalls silently.

Delivery

Field	Default	Meaning
ack_blocks_max	16	RLE ack-range blocks per frame
loss_packet_threshold	3	RACK packet threshold
loss_time_num / loss_time_den	9 / 8	RACK time threshold = num/den × RTT
nack_delay_ms	3	receiver fast-NAK delay
ping_interval_ms	1000	idle keepalive / RTT cadence
idle_timeout_ms	30000	close a silent peer after 30 seconds (0 = off)
reassembly_slots	4	concurrent fragmented messages
max_fragments	64	fragments per message
fragmentation	false	enable sendBlock / receiveBlock
pn_skip_period	32	keyed AEAD optimistic-ACK defense (0 = off)

SeqWidths

Field	Default	Domain
packet_number	u64	transmit-order packet number; AEAD requires 64 bits to prevent nonce reuse
data_sequence	u16	per-channel message number

Degrade

Field	Default	On exhaustion
on_send_queue_full	.backpressure	.backpressure / .drop_oldest / .drop_new
on_reassembly_full	.drop	.drop / .error_out