Packages
macula
0.42.7
7.0.0
6.0.0
5.2.2
5.2.1
5.2.0
5.1.0
5.0.0
4.8.0
4.7.1
4.7.0
4.6.0
4.5.0
4.4.10
4.4.9
4.4.8
4.4.7
4.4.6
4.4.5
4.4.4
4.4.3
4.4.2
4.4.1
4.4.0
4.3.1
4.3.0
4.2.9
4.2.8
4.2.7
4.2.6
4.2.5
4.2.4
4.2.3
4.2.2
4.2.1
4.2.0
4.1.1
4.1.0
4.0.0
3.16.0
3.15.3
3.15.2
3.15.1
3.14.0
3.13.0
3.12.1
3.12.0
3.11.1
3.11.0
3.10.3
3.10.2
3.10.1
3.9.0
3.8.0
3.7.0
3.5.0
3.4.0
3.3.0
3.2.0
3.1.0
3.0.0
2.1.1
2.1.0
2.0.0
1.5.2
1.5.1
1.4.30
1.4.29
1.4.28
1.4.27
1.4.26
1.4.25
1.4.24
1.4.23
1.4.22
1.4.21
1.4.20
1.4.19
1.4.18
1.4.17
1.4.16
1.4.15
1.4.14
1.4.13
1.4.11
1.4.10
1.4.9
1.4.8
1.4.7
1.4.6
1.4.5
1.4.4
1.4.3
1.4.2
1.4.1
1.4.0
1.3.1
1.3.0
1.2.0
1.1.0
1.0.10
1.0.9
1.0.8
1.0.7
1.0.6
1.0.5
1.0.4
1.0.3
1.0.2
1.0.1
1.0.0
0.48.6
0.48.5
0.48.4
0.48.3
0.48.2
0.48.1
0.48.0
0.47.1
0.47.0
0.46.3
0.46.1
0.46.0
0.45.3
0.45.2
0.45.1
0.45.0
0.44.2
0.44.1
0.44.0
0.43.3
0.43.2
0.43.1
0.43.0
0.42.9
0.42.8
0.42.7
0.42.6
0.42.5
0.42.4
0.42.3
0.42.2
0.42.1
0.42.0
0.41.1
0.41.0
0.40.1
0.40.0
0.39.9
0.39.8
0.39.7
0.39.6
0.39.5
0.39.4
0.39.3
0.39.2
0.39.1
0.39.0
0.38.8
0.38.7
0.38.6
0.38.5
0.38.4
0.38.3
0.38.2
0.38.1
0.38.0
0.37.7
0.37.6
0.37.5
0.37.4
0.37.3
0.37.2
0.37.1
0.37.0
0.36.6
0.36.5
0.36.4
0.36.3
0.36.2
0.36.1
0.36.0
0.35.4
0.35.3
0.35.2
0.35.1
0.35.0
0.34.1
0.34.0
0.33.1
0.33.0
0.32.5
0.32.4
0.32.3
0.32.2
0.32.1
0.32.0
0.31.9
0.31.8
0.31.7
0.31.6
0.31.5
0.31.4
0.31.3
0.31.2
0.31.1
0.31.0
0.30.10
0.30.9
0.30.8
0.30.7
0.30.6
0.30.5
0.30.4
0.30.3
0.30.2
0.30.1
0.30.0
0.29.0
0.28.3
0.28.2
0.28.1
0.28.0
0.27.1
0.27.0
0.26.1
0.26.0
0.25.6
0.25.5
0.25.4
0.25.3
0.25.2
0.25.1
0.25.0
0.24.6
0.24.5
0.24.4
0.24.3
0.24.2
0.24.1
0.24.0
0.23.3
0.23.2
0.23.1
0.23.0
0.22.12
0.22.11
0.22.10
0.22.9
0.22.8
0.22.7
0.22.6
0.22.5
0.22.4
0.22.3
0.22.2
0.22.1
0.22.0
0.21.7
0.21.6
0.21.5
0.21.4
0.21.2
0.21.1
0.21.0
0.20.25
0.20.24
0.20.23
0.20.22
0.20.21
0.20.20
0.20.19
0.20.18
0.20.17
0.20.16
0.20.15
0.20.14
0.20.13
0.20.12
0.20.11
0.20.10
0.20.9
0.20.8
0.20.7
0.20.6
0.20.5
0.20.3
0.20.2
0.20.1
0.20.0
0.19.2
0.19.1
0.19.0
0.18.1
0.18.0
0.17.4
0.17.3
0.17.2
0.17.1
0.17.0
0.16.6
0.16.5
0.16.4
0.16.3
0.16.2
0.16.1
0.16.0
0.15.1
0.15.0
0.14.3
0.14.2
0.14.1
0.14.0
0.12.6
0.12.5
0.12.3
0.11.3
0.10.2
0.10.1
0.10.0
0.9.2
0.9.1
0.9.0
0.8.25
0.8.24
0.8.23
0.8.22
0.8.21
0.8.20
0.8.19
0.8.18
0.8.17
0.8.16
0.8.15
0.8.14
0.8.13
0.8.12
0.8.11
0.8.10
0.8.9
0.8.8
0.8.7
0.8.6
0.8.5
0.8.4
0.8.3
0.8.2
0.8.1
0.8.0
0.7.30
0.7.29
0.7.28
0.7.27
0.7.26
0.7.25
0.7.24
0.7.23
0.7.22
0.7.21
0.7.20
0.7.19
0.7.18
0.7.17
0.7.16
0.7.15
0.7.14
0.7.13
0.7.12
0.7.11
0.7.10
0.7.9
0.7.8
0.7.7
0.7.6
0.7.5
0.7.4
0.7.3
0.7.2
0.7.1
0.7.0
0.6.7
0.6.6
0.6.5
0.6.4
0.6.3
0.6.2
0.6.1
0.6.0
0.5.0
0.4.4
0.4.3
0.4.2
0.4.1
0.4.0
0.3.4
0.3.3
0.3.2
0.3.1
Macula HTTP/3 Mesh SDK — connect, subscribe, publish, call, advertise
Current section
Files
Jump to
Current section
Files
src/macula_nat_system/README.md
# NAT System
The NAT System handles Network Address Translation detection and traversal, enabling direct peer-to-peer connections across NAT boundaries.
## Module Table
| Module | Purpose | LOC |
|--------|---------|-----|
| `macula_nat_system` | Supervisor for NAT subsystem | 4.4k |
| `macula_nat_detector` | Detects local NAT type (Full Cone, Restricted, Symmetric) | 32k |
| `macula_nat_coordinator` | Coordinates hole-punch timing between peers | 28k |
| `macula_nat_cache` | Caches NAT detection results with TTL | 18k |
| `macula_nat_connector` | NAT-aware connection establishment | 17k |
| `macula_hole_punch` | Performs UDP/QUIC hole punching | 16k |
| `macula_port_predictor` | Predicts symmetric NAT port allocations | 23k |
| `macula_connection_upgrade` | Upgrades relay connections to direct | 9.5k |
| `macula_relay_node` | Peer relay functionality for unreachable peers | 19k |
| `macula_relay_registry` | Tracks available relay nodes with load balancing | 13k |
## NAT Type Detection Flow
```
1. Client starts macula_nat_detector
2. Detector sends NAT_PROBE to multiple observers (bootstrap nodes)
3. Each observer replies with reflexive address (public IP:port seen)
4. Detector compares:
- Same IP:port from all observers → Full Cone NAT
- Same IP, different ports → Address Restricted or Symmetric
- Different IP:port pairs → Symmetric NAT
5. Result cached in macula_nat_cache (TTL: 5 minutes)
```
## Hole Punching Sequence
```
Peer A (behind NAT) Coordinator Peer B (behind NAT)
| | |
|--- PUNCH_REQUEST(B) -------->| |
| |<---- PUNCH_REQUEST(A) --|
| | |
|<-- PUNCH_COORDINATE ---------|---- PUNCH_COORDINATE -->|
| (B's reflexive addr, | (A's reflexive addr, |
| punch_at: T+100ms) | punch_at: T+100ms) |
| | |
|============ At time T+100ms, both peers punch ==========|
| |
|<========== Direct QUIC connection established =========>|
```
### Adaptive Timing by NAT Type
| NAT Type | Initial Delay | Retry Interval | Max Retries |
|----------|---------------|----------------|-------------|
| Full Cone | 50ms | 100ms | 3 |
| Restricted | 100ms | 200ms | 5 |
| Symmetric | 150ms | 300ms | 7 |
## Configuration Options
Environment variables for runtime configuration:
| Variable | Default | Description |
|----------|---------|-------------|
| `MACULA_NAT_CACHE_TTL` | 300 | Cache TTL in seconds |
| `MACULA_NAT_CACHE_MAX` | 10000 | Maximum cache entries |
| `MACULA_NAT_PROBE_TIMEOUT` | 5000 | Probe timeout in ms |
| `MACULA_RELAY_AUTO_ENABLE` | false | Auto-enable relay on capable nodes |
| `RELAY_ENABLED` | false | Enable relay functionality |
### Programmatic Configuration
```erlang
%% Start NAT system with custom options
macula_nat_system:start_link(#{
cache_max_entries => 5000,
cache_ttl_seconds => 600,
detection_timeout_ms => 3000
}).
%% Detect local NAT type
{ok, NATType} = macula_nat_detector:detect().
%% Returns: full_cone | address_restricted | port_restricted | symmetric
%% Request hole punch to peer
{ok, SessionId} = macula_hole_punch:start_punch(TargetNodeId).
%% Enable relay capability
macula_relay_node:enable(#{
node_id => NodeId,
endpoint => {<<"192.168.1.100">>, 4433},
capacity => 100
}).
```
## Message Types (0x50-0x5F)
| Type | ID | Purpose |
|------|-----|---------|
| NAT_PROBE | 0x50 | Request reflexive address from observer |
| NAT_PROBE_REPLY | 0x51 | Return reflexive address to requester |
| PUNCH_REQUEST | 0x52 | Request hole punch coordination |
| PUNCH_COORDINATE | 0x53 | Synchronized punch timing info |
| PUNCH_RESULT | 0x55 | Report punch success/failure |
| RELAY_REQUEST | 0x56 | Request relay tunnel setup |
| RELAY_DATA | 0x57 | Relayed data frame |
## Supervision Tree
```
macula_nat_system (supervisor)
├── nat_cache (macula_nat_cache)
├── nat_detector (macula_nat_detector)
├── nat_coordinator (macula_nat_coordinator)
├── hole_punch (macula_hole_punch)
├── connection_upgrade (macula_connection_upgrade)
├── port_predictor (macula_port_predictor)
├── relay_registry (macula_relay_registry)
└── relay_node (macula_relay_node)
```
## Performance Metrics
| Metric | Target | Description |
|--------|--------|-------------|
| NAT detection time | < 2s | Time to detect local NAT type |
| Hole punch success rate | > 80% | Direct connection establishment |
| Connection upgrade time | < 5s | Relay to direct upgrade |
| Cache hit rate | > 95% | NAT cache effectiveness |
## Related Documentation
- [NAT Types Explained](../../docs/guides/NAT_TYPES_EXPLAINED.md)
- [NAT Traversal Developer Guide](../../docs/guides/NAT_TRAVERSAL_DEVELOPER_GUIDE.md)
- [v0.12.0 NAT Complete Plan](../../architecture/V0.12.0_NAT_COMPLETE_PLAN.md)