niom-turn/docs/architecture/data_flow.md

Packet Flow & Allocation Handling

This page describes the high-level data flow through niom-turn (control plane and data plane).

Components

• UDP listener: receives STUN/TURN as well as ChannelData on UDP/3478.
• TCP listener: STUN/TURN over TCP/3478.
• TLS listener: STUN/TURN over TLS/5349 ("turns").
• AuthManager: REALM/NONCE challenges, long-term auth (MI), optional TURN REST.
• AllocationManager: manages allocations including relay sockets, permissions, and channel bindings.

Flow (control plane)

1. The request is parsed as STUN/TURN (or recognized as ChannelData).
2. Auth is checked:
   • without valid credentials → 401 (challenge) or 438 (stale nonce)
   • with valid credentials → the request is processed; responses include MESSAGE-INTEGRITY + FINGERPRINT
3. Allocate/Refresh/Permission/ChannelBind update the allocation state.

Flow (relay/data plane)

• On ALLOCATE, a UDP relay socket is bound and a relay loop is started.
• Packets from the peer are received by the relay and sent back to the client as Data Indication or ChannelData.
• For interop, a CHANNEL-BIND may implicitly create the permission for the peer.

Lifecycle / Housekeeping

• Allocations are periodically checked for expiry (housekeeping) so relay tasks can end even while idle.
• The server periodically logs a compact metrics snapshot.

See also: docs/turn_end_to_end_flow.md and docs/tcp_tls_data_plane.md.