# 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`.