Add module-level docs and first milestone plan.

README.md

@@ -57,6 +57,28 @@ Auth caveat
   this with a secure credential workflow (ephemeral/REST credentials, PBKDF/KDF storage, or mTLS)
   before any production deployment. See `src/auth.rs` for the current simple store and helpers.
 
+Milestone 1 — Protocol Backlog
+------------------------------
+This milestone focuses on turning the current MVP into a feature-complete TURN core that can be used
+reliably by `niom-webrtc`.
+
+- **Authentication Hardening**: nonce lifecycle, realm configuration, Argon2-backed credential
+  storage, and detailed error handling for 401/438 responses.
+- **TURN Method Coverage**: implement `Allocate` attributes, `CreatePermission`, `ChannelBind`,
+  `Refresh`, and full relay path (peer data forwarding, Send/Data indications).
+- **Allocation Lifecycle**: timers, refresh logic, cleanup of expired allocations, and resource
+  limits per user/IP.
+- **Protocol Compliance**: FINGERPRINT support, XOR-MAPPED-ADDRESS, IPv6 evaluation, checksum
+  validation, and robustness against malformed packets.
+- **Observability & Limits**: structured tracing, metrics, rate limiting, and integration tests
+  (including the bundled `smoke_client`).
+
+Artifacts that track this milestone live in two places:
+
+1. This README section is kept up to date while the milestone is in progress.
+2. Inline module docs (`//!`) inside `src/` record the current responsibilities and open backlog
+   items for each subsystem as we iterate.
+
 License: MIT
 
 Smoke-Test (End-to-End)

src/alloc.rs

@@ -1,3 +1,5 @@
+//! Allocation manager: provisions relay sockets and forwards packets for TURN allocations.
+//! Backlog: permission tables, channel bindings, allocation refresh timers, and rate limits.
 use std::collections::HashMap;
 use std::net::SocketAddr;
 use std::sync::{Arc, Mutex};

src/auth.rs

@@ -1,3 +1,5 @@
+//! Authentication helpers and the in-memory credential store used for the MVP server.
+//! Backlog: Argon2-backed storage, nonce lifecycle, and integration with persistent secrets.
 use async_trait::async_trait;
 use std::sync::Arc;
 use crate::traits::CredentialStore;

src/config.rs

@@ -1,3 +1,5 @@
+//! Configuration loader for server bind addresses, TLS artifacts, and seed credentials.
+//! Backlog: hot-reload support, secret injection, and environment overrides per deployment.
 use serde::Deserialize;
 use std::path::Path;
 

src/main.rs

@@ -1,3 +1,5 @@
+//! Binary entry point that wires configuration, UDP listener, optional TLS listener, and allocation handling.
+//! Backlog: graceful shutdown signals, structured metrics, and coordinated lifecycle management across listeners.
 use std::net::SocketAddr;
 use std::sync::Arc;
 use tokio::net::UdpSocket;

src/stun.rs

@@ -1,3 +1,5 @@
+//! STUN/TURN message parsing and builders for the server.
+//! Backlog: full attribute coverage, fingerprint helpers, IPv6 handling, and fuzz testing.
 use std::convert::TryInto;
 use crate::models::stun::{StunHeader, StunAttribute, StunMessage};
 use crate::constants::*;

src/tls.rs

@@ -1,3 +1,5 @@
+//! TLS listener that wraps the STUN/TURN logic for `turns:` clients.
+//! Backlog: ALPN negotiation, TCP relay support, and shared flow-control with the UDP path.
 use std::sync::Arc;
 use anyhow::Context;
 use tokio::net::TcpListener;