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
README.md
# Macula
[](LICENSE)
[](https://www.erlang.org)
[](https://hex.pm/packages/macula)
[](https://buymeacoffee.com/rlefever)
<p align="center">
<img src="assets/logo.svg" width="120" height="120" alt="Macula">
</p>
<p align="center">
<strong>BEAM-native HTTP/3 mesh networking for decentralized applications</strong>
</p>
---
## What is Macula?
Macula is an **Erlang/OTP library** that provides a complete distributed mesh networking stack over HTTP/3 (QUIC). It enables BEAM applications to form self-organizing networks with:
- **Zero configuration clustering** via UDP multicast gossip
- **NAT-friendly transport** using QUIC (single UDP port)
- **Decentralized service discovery** via Kademlia DHT
- **Capability-based security** with DID identities and UCAN tokens
<p align="center">
<img src="assets/mesh-architecture.svg" alt="Macula Mesh Architecture" width="100%">
</p>
---
## Features
### Mesh Networking
<p align="center">
<img src="assets/macula_overview.svg" alt="Macula Overview" width="100%">
</p>
| Feature | Description |
|---------|-------------|
| **HTTP/3 over QUIC** | NAT-friendly, firewall-friendly, built-in TLS 1.3 |
| **Kademlia DHT** | Decentralized routing with O(log N) lookups |
| **Multi-tenant realms** | Isolated namespaces for different applications |
| **Connection pooling** | 94.5% hit rate, LRU eviction |
### Pub/Sub Messaging
<p align="center">
<img src="assets/pubsub_flow.svg" alt="PubSub Flow" width="100%">
</p>
```erlang
%% Subscribe to a topic
{ok, SubRef} = macula:subscribe(Peer, <<"sensors.temperature">>, fun(Msg) ->
io:format("Received: ~p~n", [Msg])
end).
%% Publish to subscribers
ok = macula:publish(Peer, <<"sensors.temperature">>, #{value => 23.5}).
%% Unsubscribe when done
ok = macula:unsubscribe(Peer, SubRef).
```
### RPC (Request/Response)
<p align="center">
<img src="assets/rpc_flow.svg" alt="RPC Flow" width="100%">
</p>
```erlang
%% Advertise a procedure handler
{ok, _Ref} = macula:advertise(Peer, <<"math.add">>, fun(#{a := A, b := B}) ->
{ok, #{result => A + B}}
end).
%% Call the procedure (discovers provider via DHT)
{ok, #{result := 5}} = macula:call(Peer, <<"math.add">>, #{a => 2, b => 3}).
```
### NAT Traversal
<p align="center">
<img src="assets/nat_traversal_flow.svg" alt="NAT Traversal" width="100%">
</p>
| Technique | Status | Description |
|-----------|--------|-------------|
| **Hole Punching** | Adaptive | Direct P2P through NAT |
| **STUN-like Probing** | Built-in | Reflexive address detection |
| **Relay Fallback** | Automatic | When direct fails |
| **Connection Upgrade** | Transparent | Relay → Direct when possible |
### Gossip Clustering
<p align="center">
<img src="assets/gossip_clustering.svg" alt="Gossip Clustering" width="100%">
</p>
Zero-configuration cluster formation using UDP multicast:
```erlang
%% Start gossip-based clustering
ok = macula_cluster:start_cluster(#{
strategy => gossip,
secret => <<"my_cluster_secret">> %% Optional HMAC authentication
}).
%% Nodes auto-discover via multicast 230.1.1.251:45892
```
### Erlang Distribution Over Relay Mesh
<p align="center">
<img src="assets/dist_relay_tunnel.svg" alt="Distribution Relay Tunnel" width="100%">
</p>
Full OTP distribution tunneled through the relay mesh — nodes only need
outbound connectivity. No VPNs, no open ports.
```erlang
%% Enable relay distribution
os:putenv("MACULA_DIST_MODE", "relay"),
macula_dist_relay:register_mesh_client(Client),
macula_dist_relay:advertise_dist_accept(),
%% Now standard OTP distribution works across firewalls
net_adm:ping('other@remote-host'). %% => pong
gen_server:call({Name, 'other@remote-host'}, Request). %% works
```
| Feature | Status |
|---------|--------|
| **Handshake over relay** | 5-message dist_util handshake through pub/sub |
| **AES-256-GCM encryption** | Tunnel bytes encrypted, relay cannot read ETF |
| **Supervised bridges** | gen_server per tunnel under simple_one_for_one |
| **Cross-relay tunnels** | Nodes on different relays connect via peering |
| **Relay reconnection** | Bridge re-acquires client after relay restart |
| **Metrics** | Per-tunnel byte/message counters |
See [Distribution Over Mesh Guide](docs/guides/DIST_OVER_MESH_GUIDE.md) for details.
### Content Transfer (P2P Artifacts)
<p align="center">
<img src="assets/content_transfer_flow.svg" alt="Content Transfer" width="100%">
</p>
Content-addressed storage and transfer for distributing OTP releases across the mesh:
```erlang
%% Publish a file to the mesh
{ok, MCID} = macula_content:publish("/path/to/release.tar.gz").
%% Fetch from any provider
{ok, Binary} = macula_content:fetch(MCID).
```
| Feature | Description |
|---------|-------------|
| **MCID** | Content-addressed identifiers (BLAKE3/SHA256) |
| **Merkle verification** | Chunk-level integrity |
| **Parallel download** | From multiple providers |
| **Want/Have/Block** | Efficient P2P protocol |
### Authorization (DID + UCAN)
<p align="center">
<img src="assets/authorization_flow.svg" alt="Authorization Flow" width="100%">
</p>
Decentralized capability-based authorization:
| Component | Purpose |
|-----------|---------|
| **DID** | Decentralized identifiers for namespace ownership |
| **UCAN** | Capability tokens for delegated permissions |
| **Namespace** | `did:macula:io.example.user` owns `io.example.user.*` |
### Hierarchical DHT (Bridge System)
<p align="center">
<img src="assets/kademlia_dht.svg" alt="Kademlia DHT" width="100%">
</p>
Fractal mesh hierarchy with query escalation:
```
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.
---
## Quick Start
### Installation
Add to your `rebar.config`:
```erlang
{deps, [
{macula, "0.42.7"}
]}.
```
Or in Elixir `mix.exs`:
```elixir
defp deps do
[
{:macula, "~> 0.42.7"}
]
end
```
### Basic Usage
```erlang
%% Start macula application
application:ensure_all_started(macula).
%% Connect to the mesh
{ok, Peer} = macula:connect(<<"quic://seed.example.com:9443">>, #{
realm => <<"io.example.myapp">>,
node_id => <<"node-001">>
}).
%% Subscribe to events
{ok, _SubRef} = macula:subscribe(Peer, <<"events.orders">>, fun(Order) ->
process_order(Order)
end).
%% Advertise an RPC procedure
{ok, _AdvRef} = macula:advertise(Peer, <<"inventory.check">>, fun(#{sku := Sku}) ->
{ok, check_inventory(Sku)}
end).
%% Call an RPC procedure (discovers provider via DHT)
{ok, Result} = macula:call(Peer, <<"inventory.check">>, #{sku => <<"ABC123">>}).
```
---
## Configuration
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `MACULA_QUIC_PORT` | `9443` | QUIC listener port |
| `MACULA_REALM` | `com.example.realm` | Default realm |
| `HEALTH_PORT` | `8080` | Health check HTTP port |
| `MACULA_TLS_MODE` | `development` | TLS mode (`production`/`development`) |
| `CLUSTER_STRATEGY` | `gossip` | Cluster strategy (`gossip`/`static`/`mdns`) |
| `CLUSTER_SECRET` | - | Shared secret for gossip HMAC |
### Application Config
```erlang
{macula, [
{quic_port, 9443},
{realm, <<"io.example.myapp">>},
{tls_mode, production},
{tls_cacertfile, "/etc/ssl/certs/ca-certificates.crt"}
]}.
```
---
## Documentation
| Guide | Description |
|-------|-------------|
| [Cluster API Guide](docs/guides/CLUSTER_API_GUIDE.md) | Clustering and distribution |
| [Gossip Clustering Guide](docs/guides/GOSSIP_CLUSTERING_GUIDE.md) | UDP multicast discovery |
| [Content Transfer Guide](docs/guides/CONTENT_TRANSFER_GUIDE.md) | P2P artifact distribution |
| [NAT Traversal Guide](docs/guides/NAT_TRAVERSAL_DEVELOPER_GUIDE.md) | NAT techniques |
| [DHT Guide](docs/guides/DHT_GUIDE.md) | Kademlia DHT internals |
| [Authorization Guide](docs/guides/AUTHORIZATION_GUIDE.md) | DID/UCAN security |
| [Distribution Over Mesh](docs/guides/DIST_OVER_MESH_GUIDE.md) | Relay-tunneled Erlang distribution |
| [TLS Configuration](docs/operator/TLS_CONFIGURATION.md) | Production TLS setup |
---
## Version History
| Version | Date | Highlights |
|---------|------|------------|
| **v0.42.7** | Apr 2026 | Distribution over relay mesh — cross-relay, encryption, supervision, metrics (48 tests) |
| **v0.40.0** | Apr 2026 | First Erlang dist-over-mesh: net_adm:ping across 3 countries via relay tunnel |
| **v0.19.2** | Jan 2026 | README rework with feature sections and SVGs |
| **v0.19.1** | Jan 2026 | Gossip clustering, static strategy (34 tests) |
| **v0.19.0** | Jan 2026 | Content transfer system, MCID, Want/Have/Block (171 tests) |
| **v0.18.0** | Jan 2026 | Cluster API for bc_gitops integration (19 tests) |
| **v0.16.0** | Dec 2025 | Registry system, Ed25519 signing (60 tests) |
| **v0.15.0** | Dec 2025 | Gossip protocol, CRDT replication (29 tests) |
| **v0.14.0** | Dec 2025 | Masterless CRDT architecture (48 tests) |
| **v0.13.0** | Dec 2025 | Hierarchical DHT, bridge system (40 tests) |
| **v0.12.0** | Nov 2025 | Complete NAT traversal (70 tests) |
See [CHANGELOG.md](CHANGELOG.md) for full history.
---
## Architecture
Macula follows an **always-on architecture** where every node has all capabilities:
```
macula_root (application supervisor)
├── macula_gateway_system (QUIC transport + relay handler)
├── macula_pubsub_system (pub/sub messaging)
├── macula_rpc_system (RPC request/response)
├── macula_routing_system (Kademlia DHT)
├── macula_nat_system (NAT traversal + hole punching)
├── macula_bootstrap_system (mesh discovery)
├── macula_membership_system (gossip clustering)
├── macula_bridge_system (hierarchical mesh escalation)
├── macula_platform_system (CRDT coordination)
├── macula_registry_system (package distribution)
├── macula_content_system (P2P content transfer)
├── macula_cert_system (TLS certificate management)
└── macula_dist_system (Erlang distribution)
├── macula_dist_bridge_sup (relay tunnel bridges)
├── macula_dist_discovery (DHT node discovery)
└── macula_cluster_strategy (optional auto-clustering)
```
---
## Related Projects
| Project | Description |
|---------|-------------|
| [macula-ecosystem](https://github.com/macula-io/macula-ecosystem) | Documentation hub |
| [macula-console](https://github.com/macula-io/macula-console) | Management console |
| [bc-gitops](https://github.com/beam-campus/bc-gitops) | GitOps reconciler |
| [macula-tweann](https://github.com/macula-io/macula-tweann) | Neuroevolution framework |
---
## Community
- **Hex.pm**: [hex.pm/packages/macula](https://hex.pm/packages/macula)
- **GitHub**: [github.com/macula-io/macula](https://github.com/macula-io/macula)
- **Issues**: [github.com/macula-io/macula/issues](https://github.com/macula-io/macula/issues)
---
## License
Apache 2.0 - See [LICENSE](LICENSE) for details.
---
<p align="center">
<sub>Built with the BEAM</sub>
</p>