Packages
macula
0.20.20
7.1.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
README.md
# Macula
[](LICENSE)
[](https://www.erlang.org)
[](https://hex.pm/packages/macula)
[](https://buymeacoffee.com/beamologist)
<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 = 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}).
```
### RPC (Request/Response)
<p align="center">
<img src="assets/rpc_flow.svg" alt="RPC Flow" width="100%">
</p>
```erlang
%% Register a procedure handler
ok = macula:register(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
```
### 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.19.2"}
]}.
```
Or in Elixir `mix.exs`:
```elixir
defp deps do
[
{:macula, "~> 0.19.2"}
]
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
macula:subscribe(Peer, <<"events.orders">>, fun(Order) ->
process_order(Order)
end).
%% Make RPC calls
{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 |
| [TLS Configuration](docs/operator/TLS_CONFIGURATION.md) | Production TLS setup |
---
## Version History
| Version | Date | Highlights |
|---------|------|------------|
| **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_routing_server (Kademlia DHT)
├── macula_nat_system (NAT traversal)
├── macula_bootstrap_system (mesh discovery)
├── macula_gateway_system (QUIC transport)
├── macula_bridge_system (hierarchical mesh)
├── macula_platform_system (CRDT coordination)
├── macula_registry_system (package distribution)
├── macula_content_system (P2P content transfer)
└── macula_dist_system (Erlang distribution)
```
---
## 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>