Macula Logo

Macula HTTP/3 Mesh

A distributed platform for decentralized applications

LicenseErlang/OTP

Table of Contents

What is Macula?

Macula is infrastructure for building decentralized applications and services that operate autonomously at the edge, without dependency on centralized cloud infrastructure.

Key Features:

✅ BEAM-native (Erlang/Elixir OTP supervision and fault tolerance) ✅ HTTP/3 (QUIC) transport (modern, encrypted, NAT-friendly) ✅ Edge-first design (works through firewalls and NAT) ✅ Built-in pub/sub & RPC (no external message broker needed) ✅ Multi-tenancy (realm isolation for SaaS and shared infrastructure) ✅ Self-organizing mesh (DHT-based service discovery, O(log N) routing) ✅ Production-ready patterns (OTP behaviors, comprehensive testing, memory management)

Architecture at a Glance

System Context - How your application uses Macula:

┌──────────────┐

│     Your     │

│ Application  │

└──────┬───────┘

       │ macula_peer API

       ▼

┌──────────────┐     QUIC/HTTP3      ┌──────────────┐

│ Macula Peer  │◄───────────────────►│   Gateway    │

│ (Local Node) │    Or Direct P2P    │ (Relay Node) │

└──────┬───────┘                     └──────┬───────┘

       │                                    │

       └────────────► DHT ◄─────────────────┘

                 (Service Discovery)

Message Flow (v0.8.0 Direct P2P):

Client ──1. Query DHT──► DHT (Find Service)

Client ◄─2. Endpoint──── DHT Returns "192.168.1.50:9443"

Client ──3. Direct────► Provider (1-hop, 50ms)

Client ◄─4. Response─── Provider (50% faster than relay!)

📊 See Full Architecture Guide with:

Installation

Elixir (mix.exs):

def deps do

  [

    {:macula, "~> 0.8"}

  ]

end

Erlang (rebar.config):

{deps, [

    {macula, "0.8.1"}

]}.

Latest Release: v0.8.1 (2025-11-17) - Documentation improvements (v0.8.0: Direct P2P with DHT propagation)

What's New in v0.8.0

Major Features:

Performance:

Breaking Changes: None - fully backward compatible with v0.7.x

Quick Start

1. Connect to a Gateway

%% Start a peer connection

{ok, Peer} = macula_peer:start_link(<<"https://gateway.example.com:9443">>, #{

    realm => <<"com.example.app">>

}).

2. Publish/Subscribe

%% Subscribe to events

ok = macula_peer:subscribe(Peer, <<"sensor.temperature">>, self()).



%% Publish an event

ok = macula_peer:publish(Peer, <<"sensor.temperature">>, #{

    device_id => <<"sensor-001">>,

    celsius => 21.5,

    timestamp => erlang:system_time(millisecond)

}).



%% Receive events

receive

    {macula_event, <<"sensor.temperature">>, Payload} ->

        io:format("Temperature: ~p°C~n", [maps:get(celsius, Payload)])

end.

3. RPC (Remote Procedure Calls)

%% Call a remote service

{ok, Result} = macula_peer:call(Peer, <<"calculator.add">>, #{

    a => 5,

    b => 3

}).

%% Result: #{result => 8}

4. Advertise Services (Providers)

%% Advertise a service handler

ok = macula_peer:advertise(Peer, <<"calculator.add">>, fun(Args) ->

    A = maps:get(a, Args),

    B = maps:get(b, Args),

    #{result => A + B}

end, #{ttl => 300}).

Core Concepts

Mesh Architecture

Macula creates a self-organizing mesh network where nodes communicate over HTTP/3 (QUIC). Each node can act as:

Multi-Tenancy via Realms

Realms provide logical isolation for different applications sharing the same physical mesh:

%% App 1

{ok, Peer1} = macula_peer:start_link(GatewayUrl, #{realm => <<"com.app1">>}).



%% App 2 (completely isolated from App 1)

{ok, Peer2} = macula_peer:start_link(GatewayUrl, #{realm => <<"com.app2">>}).

DHT-Based Service Discovery

Services are discovered via a Kademlia DHT with k=20 replication:

  1. Provider advertises: advertise(<<"my.service">>, Handler)
  2. DHT propagates to k=20 closest nodes
  3. Consumer discovers: call(<<"my.service">>, Args)
  4. Direct P2P connection established (v0.8.0+)

Direct P2P Connections (v0.8.0)

Instead of relaying through gateways, v0.8.0 establishes direct QUIC connections:

API Overview

Main Modules

macula_peer - High-level mesh participant API

macula_gateway - Gateway/relay node

macula_peer_connector - Direct P2P connections (v0.8.0)

Configuration Options

Opts = #{

    realm => <<"com.example.app">>,        %% Required: Realm for isolation

    node_id => <<"my-node-001">>,         %% Optional: Custom node ID

    cert_file => "cert.pem",               %% Optional: TLS certificate

    key_file => "key.pem"                  %% Optional: TLS private key

}

Development Setup

# Clone the repository

git clone https://github.com/macula-io/macula.git

cd macula



# Fetch dependencies

rebar3 get-deps



# Compile

rebar3 compile



# Run tests

rebar3 eunit



# Start a shell with Macula loaded

rebar3 shell

Testing

# Run unit tests

rebar3 eunit



# Run integration tests (requires Docker)

rebar3 ct --suite=test/integration/multi_hop_rpc_SUITE

rebar3 ct --suite=test/integration/multi_hop_pubsub_SUITE

License

Macula is licensed under the Apache License 2.0. See LICENSE for details.

Community & Support

Built with ❤️ for the BEAM community