Macula Logo

Macula HTTP/3 Mesh

Self-organizing distributed mesh for decentralized applications

LicenseErlang/OTPHex.pm

Macula Architecture Overview

BEAM-Native • HTTP/3 (QUIC) • Kademlia DHT • Direct P2P • Multi-Tenant • 50% Faster (v0.8.0)

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.2"}

]}.

Latest Release: v0.8.2 (2025-11-17) - Compelling visual landing page (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