Macula SDK

Erlang/OTP client SDK for the Macula HTTP/3 relay mesh

What is Macula?

Macula is an Erlang/OTP client SDK for building applications that connect to a Macula relay mesh. 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:

{deps, [
    {macula, "1.1.0"}
]}.

Or in Elixir mix.exs:

defp deps do
  [{:macula, "~> 1.0"}]
end

Connect and Communicate

%% 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

Full OTP distribution tunneled through the relay mesh. No VPNs, no open ports.

%% 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(&#39;other@remote-host&#39;).  %% => pong
gen_server:call({Name, &#39;other@remote-host&#39;}, Request).  %% works

LAN Clustering

Zero-configuration cluster formation using UDP multicast:

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)

Built-in Rust NIFs with pure Erlang fallbacks for all operations:

%% 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)

Typed, hierarchical resource addressing: mri:{type}:{realm}/{path}

{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

For relay server documentation, see macula-relay.

SDK Modules (45)

Server modules (gateway, DHT routing, RPC routing, PubSub routing, SWIM, peering, bootstrap, bridge, content, registry) live in macula-relay.

Related Projects

License

Apache 2.0 - See LICENSE for details.

_{Built with the BEAM}