Macula SDK

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

---

Latest — 10.5.0: every supervised primitive pair is now complete and symmetric, each wrapping its raw SDK primitive as an OTP behaviour with a simple_one_for_one factory supervisor, mesh-visible protocol facts (sharing.*_v1, streaming.*_v1, rpc.*_v1) around its own side of the operation, and both a pooled and a direct-dial (resolve + one-hop dial) mode:

• RPC — macula_request/macula_response, unary call/reply.
• Pub/Sub — macula_publisher/macula_subscriber, publish and per-publisher-ordered subscribe.
• Content sharing — macula_feeder/macula_download, built on the addressable macula_content_transfer primitive: a genuinely peer-visible cancel (a real QUIC RESET_STREAM, not a local kill), pause/resume between chunks, and parallel multi-stream chunk transfer.
• Streaming RPC — macula_streamer/macula_stream_sink, server / client / bidi modes, with an optional client_stream receive loop and terminal-reply callback, and abort-wired cancel.
• Push-initiated content transfer — macula_pusher/macula_upload push a file at a specific, already-known recipient (rather than into content-addressed storage for someone to discover and pull later), with the same chunk/hash/verify integrity guarantees, over client_stream.
• NEW: overlay (HyParView + Plumtree) — realm-scoped bounded partial views and epidemic broadcast trees, absorbed from the standalone macula-hyparview/macula-plumtree packages. No supervised wrapper yet — see the HyParView and Plumtree guides.

All additive since 9.2.0, no breaking changes. See CHANGELOG.md for the full version-by-version history.

What is Macula?

Macula is an Erlang/OTP client SDK for building applications on a mesh of stations — realm-agnostic relays that route over QUIC (HTTP/3) and form a Kademlia DHT. Your service or daemon connects outbound to one or more stations: no open ports, NAT-friendly, no VPN. It provides:

• RPC (request/response) — discover a provider in the DHT, then dial its serving station directly (one hop), with optional realm-CA trust verification.
• Pub/Sub — topic-based event fan-out across stations, with per-publisher ordered delivery.
• Content — content-addressed sharing and live streaming (MCID).
• DHT records — signed, TTL'd records (advertisements, endpoints, more).
• Erlang distribution over mesh — net_adm:ping across firewalls, no VPN.
• Identity — Ed25519 keypairs, UCAN tokens, DID documents (NIF-accelerated).
• MRI — typed, hierarchical resource identifiers.
• Zero-config LAN clustering — UDP-multicast gossip.

The station (routing, DHT, SWIM, peering) is a separate repo, macula-station; this package is the client you build against.

---

Quick Start

Add to rebar.config:

{deps, [{macula, "~> 10.5"}]}.

Or in Elixir mix.exs:

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

application:ensure_all_started(macula),

%% Connect a pool to one or more stations (seed URLs). The pool owns one
%% QUIC link per seed, reconnecting and replaying subscriptions as needed.
{ok, Pool} = macula:connect([<<"quic://boot.macula.io:443">>], #{}),

%% A realm is a 32-byte tag derived from a name; it scopes every call.
Realm = macula_realm:id(<<"io.example.myapp">>),

%% Subscribe (delivers {macula_event, Ref, Topic, Payload, Meta} to a pid),
{ok, Ref} = macula:subscribe(Pool, Realm, <<"sensors.temperature">>, self()),

%% or subscribe with a callback fun(Topic, Payload, Meta):
{ok, Ref2} = macula:subscribe_callback(
    Pool, Realm, <<"sensors.temperature">>,
    fun(_Topic, Payload, _Meta) -> io:format("~p~n", [Payload]) end),

%% Publish. Entity IDs go in the PAYLOAD, never in the topic.
ok = macula:publish(Pool, Realm, <<"sensors.temperature">>,
                    #{sensor => <<"kitchen">>, value => 23.5}),

%% Advertise an RPC procedure (open to any identified caller here),
ok = macula:advertise(Pool, Realm, <<"math.add">>,
                      fun(#{<<"a">> := A, <<"b">> := B}) -> {ok, A + B} end,
                      #{}),

%% Call it — the SDK resolves the provider and dials its station directly.
{ok, 5} = macula:call(Pool, Realm, <<"math.add">>,
                      #{<<"a">> => 2, <<"b">> => 3}, 5_000).

---

Identity and Crypto (NIF-accelerated)

Rust NIFs with pure-Erlang fallbacks:

%% Ed25519 keypair (a #{public := _, private := _} map)
KP  = macula_identity:generate(),
Sig = macula_identity:sign(<<"hello">>, KP),
true = macula_identity:verify(<<"hello">>, Sig, macula_identity:public(KP)),

%% BLAKE3 hashing
Hash = macula_blake3_nif:hash(Data),

%% UCAN capability tokens + DID documents
{ok, Token}   = macula_ucan_nif:create(Issuer, Audience, Caps, PrivKey),
{ok, Payload} = macula_ucan_nif:verify(Token, PubKey).

---

Documentation

Guide	Description
Connecting	Pools, seeds, TLS policy, reconnection
PubSub Guide	Fan-out + per-publisher delivery ordering
PubSub Protocol	Raw subscribe/publish primitives
Topic Naming	Event-type topics, IDs in payloads
RPC Guide	Direct-dial request/response
RPC Protocol	Raw advertise/call primitives, error codes
Content Guide	Content-addressed blobs (MCID), push/upload
Content Protocol	Raw put_content/get_content, MCID format, discovery
Records Guide	Signed, TTL'd facts in the DHT — your own record types
Streaming Guide	Streaming RPC (server / client / bidi)
Streaming Protocol	Raw call_stream/advertise_stream primitives
HyParView Guide	Bounded partial-view realm membership
Plumtree Guide	Epidemic broadcast trees, realm PubSub, OR-Set CRDT
Distribution Over Mesh	Erlang dist through the mesh
Clustering	LAN gossip clustering
Authorization	DID / UCAN / cert-chain trust
MRI Guide	Resource identifiers
Development	Building and testing
Glossary	Terminology

The station server lives in macula-station.

---

Related Projects

Project	Description
macula-station	The station: DHT, SWIM, routing, peering
macula-realm	Managed-realm identity + certificate authority
macula-mri-khepri	Distributed MRI persistence (Khepri/Raft)
macula-ecosystem	Documentation hub

---

License

Apache 2.0 — see LICENSE.

---

_{Built with the BEAM}