ant-quic 0.22.2

QUIC transport protocol with advanced NAT traversal for P2P networks
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

// Copyright 2024 Saorsa Labs Ltd.
//
// This Saorsa Network Software is licensed under the General Public License (GPL), version 3.
// Please see the file LICENSE-GPL, or visit <http://www.gnu.org/licenses/> for the full text.
//
// Full details available at https://saorsalabs.com/licenses

//! MASQUE CONNECT-UDP Bind Protocol Implementation
//!
//! This module implements the MASQUE relay mechanism per
//! draft-ietf-masque-connect-udp-listen-10 for enabling
//! fully connectable P2P nodes.
//!
//! # Overview
//!
//! MASQUE (Multiplexed Application Substrate over QUIC Encryption) provides
//! a standardized mechanism for proxying UDP traffic over QUIC connections.
//! The CONNECT-UDP Bind extension allows nodes behind NATs to receive
//! inbound connections through a relay server.
//!
//! # Protocol Components
//!
//! ## Capsules
//!
//! HTTP Capsules are used for control plane operations:
//!
//! - **COMPRESSION_ASSIGN** (0x11): Register a Context ID for header compression
//! - **COMPRESSION_ACK** (0x12): Acknowledge context registration
//! - **COMPRESSION_CLOSE** (0x13): Close or reject a context
//!
//! ## Context IDs
//!
//! Context IDs enable header compression:
//!
//! - Clients allocate even Context IDs (starting at 2)
//! - Servers allocate odd Context IDs (starting at 1)
//! - Context ID 0 is reserved
//! - Only one uncompressed context is allowed per direction
//!
//! ## Datagrams
//!
//! Two datagram formats are supported:
//!
//! 1. **Uncompressed**: Includes full target address in each datagram
//! 2. **Compressed**: Target address is implicit from context registration
//!
//! # Example
//!
//! ```rust
//! use ant_quic::masque::{ContextManager, CompressionAssign, CompressedDatagram};
//! use ant_quic::VarInt;
//! use bytes::Bytes;
//! use std::net::{SocketAddr, IpAddr, Ipv4Addr};
//!
//! // Create a context manager for a client
//! let mut mgr = ContextManager::new(true);
//!
//! // Allocate a context ID for a specific target
//! let context_id = mgr.allocate_local().unwrap();
//! let target = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 1, 100)), 8080);
//!
//! // Register the compressed context
//! mgr.register_compressed(context_id, target).unwrap();
//!
//! // Create a COMPRESSION_ASSIGN capsule to send to the relay
//! let assign = CompressionAssign::compressed_v4(
//!     context_id,
//!     Ipv4Addr::new(192, 168, 1, 100),
//!     8080
//! );
//!
//! // After receiving COMPRESSION_ACK, the context is active
//! mgr.handle_ack(context_id).unwrap();
//!
//! // Now we can send compressed datagrams
//! let datagram = CompressedDatagram::new(context_id, Bytes::from("Hello!"));
//! let encoded = datagram.encode();
//! ```
//!
//! # Security Considerations
//!
//! - All relay operations use ML-KEM-768 and ML-DSA-65 for authentication
//! - Rate limiting prevents abuse of relay resources
//! - Context IDs are validated to prevent spoofing
//! - Anti-replay protection is enforced on control messages
//!
//! # References
//!
//! - [draft-ietf-masque-connect-udp-listen-10](https://datatracker.ietf.org/doc/draft-ietf-masque-connect-udp-listen/)
//! - [RFC 9298 - CONNECT-UDP](https://datatracker.ietf.org/doc/rfc9298/)
//! - [RFC 9297 - HTTP Datagrams](https://datatracker.ietf.org/doc/rfc9297/)

pub mod capsule;
pub mod connect;
pub mod context;
pub mod datagram;
pub mod integration;
pub mod migration;
pub mod relay_client;
pub mod relay_server;
pub mod relay_session;

// Re-export primary types for convenience
pub use capsule::{
    CAPSULE_COMPRESSION_ACK, CAPSULE_COMPRESSION_ASSIGN, CAPSULE_COMPRESSION_CLOSE, Capsule,
    CompressionAck, CompressionAssign, CompressionClose,
};
pub use connect::{
    BIND_ANY_HOST, BIND_ANY_PORT, CONNECT_UDP_BIND_PROTOCOL, CONNECT_UDP_PROTOCOL, ConnectError,
    ConnectUdpRequest, ConnectUdpResponse,
};
pub use context::{ContextError, ContextInfo, ContextManager, ContextState};
pub use datagram::{CompressedDatagram, Datagram, UncompressedDatagram};
pub use integration::{
    RelayHealthStatus, RelayManager, RelayManagerConfig, RelayManagerStats, RelayOperationResult,
};
pub use migration::{MigrationConfig, MigrationCoordinator, MigrationState, MigrationStats};
pub use relay_client::{
    MasqueRelayClient, RelayClientConfig, RelayClientStats, RelayConnectionState,
};
pub use relay_server::{
    DatagramResult, MasqueRelayConfig, MasqueRelayServer, MasqueRelayStats, OutboundDatagram,
    SessionInfo,
};
pub use relay_session::{RelaySession, RelaySessionConfig, RelaySessionState, RelaySessionStats};