Packages
macula
0.27.0
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_bridge_system/README.md
# Macula Bridge System
This directory contains all modules related to the hierarchical DHT bridge subsystem (v0.13.0+).
## Overview
The Bridge System enables **hierarchical mesh organization** where Bridge Nodes at each mesh level form their own mesh with a shared DHT. This creates a fractal topology:
```
Cluster < Street < Neighborhood < City < Province < Country < Region < Global
```
When a DHT query fails locally, it **escalates to parent levels**, with results cached at lower levels to avoid repeated escalation.
## Architecture Diagrams
The following SVG diagrams provide visual explanations of the bridge system architecture:
### SuperMesh Hierarchy
Shows the complete 8-level hierarchy from local clusters to global network, demonstrating the fractal mesh organization with bridge nodes connecting each level.
### Hierarchical Mesh Topology
Illustrates how City, Street, and Cluster meshes interconnect through bridge nodes, with peers forming full mesh within each cluster.
### Cluster Mesh Detail
Shows the internal structure of a cluster (smallest mesh unit), where every node has all subsystems (Gateway, Bootstrap, Peer, Bridge) and forms a full P2P mesh via QUIC.
### Bridge Escalation Flow
Demonstrates the DHT query escalation flow: Local DHT → Bridge Cache → Parent Escalation → Parent DHT → Cache Result.
## Modules
| Module | Purpose |
|--------|---------|
| `macula_bridge_system.erl` | Supervisor for bridge subsystem, manages lifecycle |
| `macula_bridge_node.erl` | Manages connection to parent mesh level, handles escalation |
| `macula_bridge_mesh.erl` | Peer-to-peer mesh formation between bridges at same level |
| `macula_bridge_cache.erl` | TTL-based caching for escalated query results with LRU eviction |
## Query Escalation Flow
```
1. Local DHT query → Not found
2. Check bridge cache → Cache miss
3. Escalate to parent via macula_bridge_node
4. Parent DHT query → Found
5. Cache result in bridge_cache (TTL varies by level)
6. Return result to caller
```
## TTL Configuration by Mesh Level
| Level | Default TTL | Rationale |
|-------|-------------|-----------|
| Cluster | 5 minutes | Local, changes frequently |
| Street | 10 minutes | Relatively stable |
| Neighborhood | 15 minutes | More stable |
| City | 30 minutes | Regional stability |
| Province+ | 60 minutes | Wide-area stability |
## Configuration
Environment variables:
```bash
MACULA_BRIDGE_ENABLED=true # Enable bridge functionality
MACULA_MESH_LEVEL=cluster # cluster|street|neighborhood|city|...
MACULA_PARENT_BRIDGES=quic://parent1:9443,quic://parent2:9443
MACULA_BRIDGE_DISCOVERY=static # static|mdns|dns_srv
MACULA_BRIDGE_CACHE_TTL=300 # seconds (optional, uses level default)
MACULA_BRIDGE_CACHE_SIZE=10000 # max entries (optional)
```
Application config:
```erlang
{macula, [
{bridge_enabled, true},
{mesh_level, cluster},
{parent_bridges, [<<"quic://parent1:9443">>, <<"quic://parent2:9443">>]},
{bridge_discovery, static}, % static | mdns | dns_srv
{bridge_cache_ttl, 300}, % seconds
{bridge_cache_size, 10000} % max entries
]}.
```
## API Usage
### Check bridge status
```erlang
%% Check if bridge is enabled and connected
true = macula_bridge_system:is_bridge_enabled().
%% Get bridge statistics
{ok, Stats} = macula_bridge_system:get_stats().
%% => #{mesh_level => cluster, bridge_connected => true, cache_hits => 42, ...}
```
### Get component PIDs
```erlang
%% Get Bridge Node PID (manages parent connection)
{ok, BridgePid} = macula_bridge_system:get_bridge_pid().
%% Get Bridge Mesh PID (manages peer bridges)
{ok, MeshPid} = macula_bridge_system:get_mesh_pid().
```
### Cache operations
```erlang
%% Direct cache access (usually handled automatically)
{ok, Value} = macula_bridge_cache:get(macula_bridge_cache, Key).
ok = macula_bridge_cache:put(macula_bridge_cache, Key, Value).
```
## Message Types
| Type | ID | Purpose |
|------|-----|---------|
| BRIDGE_RPC | 0x60 | Bridge RPC call to parent level |
| BRIDGE_DATA | 0x61 | Bridge data frame for escalated results |
## Integration
The bridge system integrates with:
- **Routing System**: `find_value_with_escalation/5` uses bridge for escalation
- **Gateway System**: Routes BRIDGE_* messages to bridge node
- **Bootstrap System**: Coordinates with DHT for local queries before escalation
## Discovery Methods
### Static (default)
Configured parent bridges via environment or config file.
### mDNS
Local network discovery using `_macula_bridge._udp` service type:
```erlang
%% Bridge advertises itself
mdns:advertise("_macula_bridge._udp", #{level => street, port => 9443}).
%% Bridge discovers peers
mdns:subscribe(advertisement).
```
### DNS SRV
WAN-scale discovery via DNS SRV records:
```
_macula-bridge._udp.street.eu.macula.net. 86400 IN SRV 10 5 9443 bridge1.eu.macula.net.
_macula-bridge._udp.street.eu.macula.net. 86400 IN SRV 10 5 9443 bridge2.eu.macula.net.
```
## Tests
See: `test/macula_bridge_system/`
Run bridge tests:
```bash
rebar3 eunit --module=macula_bridge_system_tests
rebar3 eunit --module=macula_bridge_node_tests
rebar3 eunit --module=macula_bridge_mesh_tests
rebar3 eunit --module=macula_bridge_cache_tests
```
**Test Coverage:**
| Test Module | Tests | Description |
|-------------|-------|-------------|
| `macula_bridge_system_tests` | 9 | Supervisor, child processes, mesh levels |
| `macula_bridge_node_tests` | 10 | Connection state, escalation, parent bridges |
| `macula_bridge_mesh_tests` | 9 | Add/remove peers, discovery, mesh levels |
| `macula_bridge_cache_tests` | 12 | Put/get, TTL, expiration, LRU eviction, stats |
**Total:** 40 tests
## Key Concepts
1. **Each level forms its own mesh** with shared DHT
2. **Bridge nodes connect to parent level** mesh
3. **Queries escalate up** when local DHT misses
4. **Results cached at lower levels** (TTL by level)
5. **Same fractal pattern** at every level
6. **No single point of failure** - redundant bridges