Packages
macula
1.4.21
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 SDK
[](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>Erlang/OTP client SDK for the Macula HTTP/3 relay mesh</strong>
</p>
---
## What is Macula?
<p align="center">
<img src="assets/sdk_architecture.svg" alt="Macula SDK Architecture" width="100%">
</p>
Macula is an **Erlang/OTP client SDK** for building applications that connect to a [Macula relay mesh](https://github.com/macula-io/macula-relay). It provides:
- **Pub/Sub messaging** -- topic-based event distribution across the mesh
- **RPC (request/response)** -- service discovery and invocation via DHT
- **Erlang distribution over relay** -- `net_adm:ping` across firewalls, no VPN
- **Identity** -- Ed25519 keypairs, UCAN tokens, DID documents (NIF-accelerated)
- **MRI** -- Macula Resource Identifiers for typed, hierarchical resource addressing
- **Zero-config clustering** -- UDP multicast gossip for LAN nodes
Nodes connect **outbound** to relays over QUIC. No open ports, NAT-friendly.
---
## Quick Start
Add to `rebar.config`:
```erlang
{deps, [
{macula, "1.1.0"}
]}.
```
Or in Elixir `mix.exs`:
```elixir
defp deps do
[{:macula, "~> 1.0"}]
end
```
<p align="center">
<img src="assets/connect_flow.svg" alt="SDK Connect Flow" width="100%">
</p>
### Connect and Communicate
```erlang
%% Start macula
application:ensure_all_started(macula).
%% Connect to the mesh via a relay
{ok, Client} = macula:connect(<<"quic://boot.macula.io:443">>, #{
realm => <<"io.example.myapp">>
}).
%% Subscribe to events
{ok, _SubRef} = macula:subscribe(Client, <<"sensors.temperature">>, fun(Msg) ->
io:format("Received: ~p~n", [Msg])
end).
%% Publish to subscribers
ok = macula:publish(Client, <<"sensors.temperature">>, #{value => 23.5}).
%% Advertise an RPC procedure
{ok, _Ref} = macula:advertise(Client, <<"math.add">>, fun(#{a := A, b := B}) ->
{ok, #{result => A + B}}
end).
%% Call a procedure (relay discovers the provider)
{ok, #{result := 5}} = macula:call(Client, <<"math.add">>, #{a => 2, b => 3}).
```
### Erlang Distribution Over Mesh
<p align="center">
<img src="assets/dist_over_mesh.svg" alt="Erlang Distribution Over Relay Mesh" width="100%">
</p>
Full OTP distribution tunneled through the relay mesh. No VPNs, no open ports.
```erlang
%% Single call to join the mesh with distribution
macula:join_mesh(#{
realm => <<"io.macula">>,
relays => [<<"quic://boot.macula.io:443">>],
site => #{name => <<"my-site">>, lat => 51.5, lng => -0.1}
}).
%% Standard OTP distribution now works across firewalls
net_adm:ping('other@remote-host'). %% => pong
gen_server:call({Name, 'other@remote-host'}, Request). %% works
```
### LAN Clustering
Zero-configuration cluster formation using UDP multicast:
```erlang
ok = macula_cluster:start_cluster(#{
strategy => gossip,
secret => <<"my_cluster_secret">>
}).
%% Nodes auto-discover via multicast 230.1.1.251:45892
```
---
## Identity and Crypto (NIF-accelerated)
<p align="center">
<img src="assets/identity_crypto.svg" alt="Identity and Crypto Stack" width="100%">
</p>
Built-in Rust NIFs with pure Erlang fallbacks for all operations:
```erlang
%% Ed25519 keypair
{ok, {PubKey, PrivKey}} = macula_crypto_nif:generate_keypair().
{ok, Sig} = macula_crypto_nif:sign(<<"hello">>, PrivKey).
true = macula_crypto_nif:verify(<<"hello">>, Sig, PubKey).
%% BLAKE3 hashing
Hash = macula_crypto_nif:blake3(Data).
%% UCAN capability tokens
{ok, Token} = macula_ucan_nif:create(Issuer, Audience, Caps, PrivKey).
{ok, Payload} = macula_ucan_nif:verify(Token, PubKey).
%% DID documents
{ok, Doc} = macula_did_nif:create_document(<<"did:macula:io.example">>, PubKey).
```
## MRI (Resource Identifiers)
<p align="center">
<img src="assets/mri_trie_index.svg" alt="MRI Trie Index" width="100%">
</p>
Typed, hierarchical resource addressing: `mri:{type}:{realm}/{path}`
```erlang
{ok, Parsed} = macula_mri:parse(<<"mri:app:io.macula/acme/counter">>).
%% #{type => app, realm => <<"io.macula">>, path => [<<"acme">>, <<"counter">>]}
MRI = macula_mri:new_app(<<"io.macula">>, <<"acme">>, <<"counter">>).
%% <<"mri:app:io.macula/acme/counter">>
%% Trie index for million-scale hierarchy queries
{ok, Idx} = macula_mri:build_index(MRIs).
{ok, Children} = macula_mri:index_children(Idx, <<"io.macula">>, [<<"acme">>]).
```
23 built-in types: realm, org, user, app, service, artifact, instance, license, cert, key, topic, proc, content, device, cluster, location, zone, network, model, dataset, config, class, taxonomy. Custom types via `macula_mri_registry`.
---
## Documentation
| Guide | Description |
|-------|-------------|
| [PubSub Guide](docs/guides/PUBSUB_GUIDE.md) | Topic-based messaging |
| [RPC Guide](docs/guides/RPC_GUIDE.md) | Request/response patterns |
| [Distribution Over Mesh](docs/guides/DIST_OVER_MESH_GUIDE.md) | Erlang dist through relays |
| [Clustering Guide](docs/guides/CLUSTERING_GUIDE.md) | LAN gossip clustering |
| [Authorization Guide](docs/guides/AUTHORIZATION_GUIDE.md) | DID/UCAN security |
| [MRI Guide](docs/guides/MRI_GUIDE.md) | Resource identifiers |
| [Development Guide](docs/guides/DEVELOPMENT.md) | Building and testing |
| [Glossary](docs/GLOSSARY.md) | Terminology |
For relay server documentation, see [macula-relay](https://github.com/macula-io/macula-relay).
---
## SDK Modules (45)
| Group | Modules |
|-------|---------|
| **Facade** | `macula`, `macula_app`, `macula_root` |
| **Client Transport** | `macula_mesh_client`, `macula_multi_relay`, `macula_quic`, `macula_relay_discovery`, `macula_tls` |
| **Wire Protocol** | `macula_protocol_encoder`, `macula_protocol_decoder`, `macula_protocol_types`, `macula_core_types` |
| **Crypto / Identity** | `macula_crypto_nif`, `macula_blake3_nif`, `macula_ucan_nif`, `macula_did_nif` |
| **Cert System** | `macula_cert`, `macula_cert_system`, `macula_trust_store` |
| **MRI** | `macula_mri`, `macula_mri_nif`, `macula_mri_registry`, `macula_mri_store`, `macula_mri_graph`, `macula_mri_ets` |
| **Dist Over Mesh** | `macula_dist`, `macula_dist_bridge`, `macula_dist_bridge_sup`, `macula_dist_discovery`, `macula_dist_relay`, `macula_dist_mdns_advertiser`, `macula_dist_system`, `macula_cluster`, `macula_cluster_gossip`, `macula_cluster_static`, `macula_cluster_strategy` |
| **Utilities** | `macula_id`, `macula_names`, `macula_node`, `macula_realm`, `macula_time`, `macula_uri`, `macula_utils`, `macula_cache`, `macula_console` |
Server modules (gateway, DHT routing, RPC routing, PubSub routing, SWIM, peering, bootstrap, bridge, content, registry) live in [macula-relay](https://github.com/macula-io/macula-relay).
---
## Related Projects
| Project | Description |
|---------|-------------|
| [macula-relay](https://github.com/macula-io/macula-relay) | Relay server (hub-spoke routing, DHT, peering) |
| [macula-mri-khepri](https://github.com/macula-io/macula-mri-khepri) | Distributed MRI persistence (Khepri/Raft) |
| [macula-ecosystem](https://github.com/macula-io/macula-ecosystem) | Documentation hub |
| [hecate-daemon](https://github.com/hecate-social/hecate-daemon) | AI agent sidecar for mesh |
---
## License
Apache 2.0 - See [LICENSE](LICENSE) for details.
---
<p align="center">
<sub>Built with the BEAM</sub>
</p>