API Reference macula v#0.14.3

Macula - Main API for distributed workloads on Macula platform.

Advertisement manager GenServer - manages DHT service advertisements.

macula public API

Bootstrap Health Monitor - Tracks system health metrics.

Bootstrap Registry - Thin wrapper around macula_routing_server DHT.

Bootstrap Server - Main GenServer for bootstrap node operations.

Macula Bootstrap System - Supervision tree for bootstrap nodes.

Macula Bridge Cache - Caches results from parent DHT queries.

Macula Bridge Mesh - Manages mesh formation with peer bridges.

Macula Bridge Node - Manages connection to parent mesh level.

Macula Bridge System - Supervision tree for Bridge Nodes.

Generic LRU cache implementation. Provides least-recently-used eviction with configurable max size.

Macula Chatter - P2P PubSub Demo for NAT Traversal Testing

Behaviour defining the client API contract for Macula connections

Macula Cluster Strategy for libcluster.

Macula Connection - QUIC Transport Layer (v0.7.0+).

Connection pool manager for endpoint connections.

Connection Upgrade Manager.

Macula Console Formatter - Beautiful colored terminal output.

Core type definitions and encoding/decoding for Macula. Provides fundamental types like node IDs, realm IDs, and addresses.

Conflict-Free Replicated Data Types (CRDTs) for shared state.

Direct Routing Table - Bypass bootstrap for known subscriber endpoints.

Generic DHT-based service discovery. Provides cache-integrated lookup and announcement operations. Used by both pub/sub and RPC discovery layers.

QUIC Distribution Carrier for Erlang.

EPMD Replacement using Macula DHT Discovery.

Macula Distribution mDNS Advertiser.

Macula Distribution System Supervisor.

Macula Gateway - HTTP/3 Message Router & Orchestrator

Clients Worker GenServer - tracks connected clients.

DHT Query Handler Module - handles DHT message forwarding to routing server.

Macula Gateway Diagnostics Service

Macula Gateway Health Check Server

Mesh Connection Manager GenServer - manages peer-to-peer QUIC connections.

Pub/Sub Handler GenServer - manages topic subscriptions and message routing.

Macula Gateway Pub/Sub Router - DHT-Routed Message Distribution

QUIC Transport Layer Gen_Server

RPC Handler GenServer - manages RPC handler registration and call routing.

RPC Router Module - handles routed RPC messages (CALL/REPLY).

Gateway Root Supervisor - top-level supervisor for gateway subsystem.

Gateway Workers Supervisor - supervises gateway worker processes.

QUIC Hole Punch Executor with Cancellation and Adaptive Timing.

ID generation utilities for Macula. Provides functions for generating various types of IDs.

Local client for in-VM workloads to connect to macula_gateway

SWIM failure detector (pure logic, no GenServer). Orchestrates member list, gossip, and protocol timing.

Gossip dissemination for SWIM protocol. Tracks membership updates and provides them for piggybacking. Uses exponential decay: log(N) messages per update.

Membership list for SWIM protocol. Maintains cluster membership view with fast concurrent access. Uses map-based storage (could be ETS in production).

Member record and state transitions for SWIM protocol. Represents a single node in the membership list.

Shared naming utilities for hierarchical dot-separated names. Used by both pub/sub topics and RPC procedure names. Supports DNS-style reverse notation: org.domain.service.method

NAT Profile Cache with TTL and Stale-While-Revalidate.

NAT-aware Peer Connector.

NAT Hole Punch Coordinator.

NAT Type Detector using NATCracker Methodology.

NAT Traversal System Supervisor.

Node identity and metadata management. Represents a single node in the Macula mesh.

Macula Peer - Mesh Participant API (v0.7.0+).

Peer Connection Pool - Manages pooled QUIC connections to remote peers.

Peer Connector - Establishes direct QUIC connections to remote peers (v0.8.0+).

Peer Discovery - DHT-based gateway discovery and P2P mesh formation.

Peer System Supervisor - supervises the peer subsystem.

Macula Peers Supervisor.

Macula Ping/Pong - Direct P2P Async RPC Demo

Macula Platform System Supervisor.

Port Prediction for NAT Traversal.

Protocol message decoder for Macula mesh. Decodes binary wire format to message maps.

Protocol message encoder for Macula mesh. Encodes message maps to binary wire format.

Protocol message type definitions and constants for Macula mesh. Defines all message types that can be sent over QUIC streams.

Provider selection strategies for multi-provider RPC load balancing.

LRU cache for remote subscriber lists. Caches DHT query results to avoid repeated lookups. Wraps macula_cache with subscriber-specific logic.

Message routing and delivery to local and remote subscribers. Combines local registry and remote discovery for full fan-out.

DHT operations for pub/sub - handles subscription advertisement and discovery.

DHT integration for finding remote subscribers. Uses Kademlia DHT to publish and discover subscriptions. Wraps macula_discovery with pub/sub-specific types.

PubSub handler GenServer - facade that orchestrates pub/sub operations.

QoS (Quality of Service) manager for pub/sub.

Local subscription registry for pub/sub. Maps topic patterns to local subscribers (callback PIDs).

Pub/Sub routing for multi-hop DHT-routed pub/sub. Handles wrapping, unwrapping, and routing of PUBLISH messages through the Kademlia DHT mesh.

Pub/Sub GenServer - manages subscriptions and message delivery. Ties together registry, cache, discovery, and delivery layers.

Subscription management for pub/sub.

Topic utilities for pub/sub system. Handles topic validation, pattern matching, and normalization. Supports MQTT-style wildcards: * (single-level) and # (multi-level).

Main API module for Macula QUIC transport. Provides a simplified wrapper around the quicer library.

Macula QUIC certificate utilities. Provides functions for generating and validating self-signed certificates for QUIC connections via OpenSSL command-line tool.

QUIC connection callback module for Macula. Implements quicer_connection behavior to handle connection lifecycle.

QUIC stream acceptor process. Dedicated process that waits for incoming streams on a connection and forwards them to the gateway for processing.

Realm management and validation. Realms provide logical isolation boundaries in the mesh. Realm names follow reverse DNS notation (e.g., "org.example.mesh").

Realm Trust Management for Hybrid Trust Model

Peer Relay Node.

Distributed Relay Registry.

Macula Application Root Supervisor.

K-bucket for Kademlia routing table. Stores up to k nodes with LRU eviction policy.

Core DHT algorithms for Kademlia routing. Implements iterative lookup, store, and find operations. Pure functions - no GenServer, designed to be called by macula_routing_server.

Node ID utilities for Kademlia DHT. 256-bit node identifiers with XOR distance metric.

DHT protocol message encoding/decoding. Maps DHT operations to/from message format.

GenServer managing Kademlia DHT routing table and operations. Integrates all routing components: table, DHT algorithms, protocol.

Routing table for Kademlia DHT. Manages 256 k-buckets organized by XOR distance.

Async RPC Module (NATS-style Request/Reply)

LRU cache for RPC procedure results. Caches results of idempotent procedures to avoid repeated execution. Wraps macula_cache with RPC-specific logic and TTL handling.

DHT integration for finding RPC service providers. Uses Kademlia DHT to publish and discover RPC registrations. Wraps macula_discovery with RPC-specific types.

RPC call execution with timeout handling. Executes local handlers and remote calls via QUIC.

RPC Failover Strategy Module

RPC handler GenServer - manages RPC calls, replies, and failover.

Name validation and utilities for RPC procedures. Uses reverse DNS notation: org.domain.service.procedure

Local RPC procedure registration registry. Maps URIs to handler functions. Supports multiple handlers per URI (for load balancing).

RPC call routing strategies. Selects which provider to use for a call (local or remote).

RPC routing for multi-hop DHT-routed RPC. Handles wrapping, unwrapping, and routing of RPC messages through the Kademlia DHT mesh.

RPC server managing registrations and calls. GenServer that integrates registry, cache, discovery, router, and executor.

RPC Service Interests Module (Pull-based Discovery)

Decentralized service advertisement registry using DHT.

Dedicated process for accepting QUIC streams on a connection.

DHT Subscriber Cache - Caches topic→subscribers mappings for fast pub/sub.

Time utilities for Macula. Provides functions for timestamps, durations, and timeouts.

TLS Certificate Management and Verification Module (v0.11.0+)

Macula URI parsing and construction. Format: macula://realm/node_id Example: macula://org.example.mesh/0123456789abcdef...

Common utility functions for Macula.