Search documentation of macula

# macula_gateway (macula v0.44.2)

View Source

Macula Gateway - HTTP/3 Message Router & Orchestrator

Main API module and coordinator for the Macula Gateway. The gateway can be embedded in applications or run standalone as a relay node.

### Quick Start (Embedded Gateway)

       %% Start an embedded gateway
       {ok, Gateway} = macula_gateway:start_link([
           {port, 9443},
           {realm, <<"com.example.realm">>},
           {cert_file, "cert.pem"},
           {key_file, "key.pem"}
       ]).

       %% Register an RPC handler
       ok = macula_gateway:register_handler(Gateway, <<"calculator.add">>, fun(Args) ->
           A = maps:get(a, Args),
           B = maps:get(b, Args),
           #{result => A + B}
       end).

### Quick Start (Standalone Gateway)

Configure `sys.config`:

       [
         {macula, [
           {gateway_port, 9443},
           {gateway_realm, <<"com.example.realm">>},
           {cert_file, "/path/to/cert.pem"},
           {key_file, "/path/to/key.pem"}
         ]}
       ].

Start application:

       application:start(macula).

### Architecture (Modular Design - Refactored Jan 2025)

Gateway (this module): - QUIC Listener Management - Message Decoding & Routing - Supervisor Coordination - API Facade

Child Modules (managed via macula_gateway_sup): - `macula_gateway_client_manager`: Client lifecycle management - `macula_gateway_pubsub`: Pub/Sub message routing with wildcards - `macula_gateway_rpc`: RPC handler registration & invocation - `macula_gateway_mesh`: Mesh connection pooling

Stateless Delegation Modules: - `macula_gateway_dht`: DHT query forwarding to routing server - `macula_gateway_rpc_router`: Multi-hop RPC routing via DHT

Single Responsibility Principle: Each module has one clear purpose and delegates to specialized child modules. Gateway acts as orchestrator, not implementer.

# Summary

## Functions

get_stats(Gateway)

Get gateway statistics.

handle_call(Request, From, State)
handle_cast(Request, State)

Handle rpc_route message forwarded from connection

handle_continue(_, State)

Wire gateway to siblings after init completes. This avoids initialization deadlock from calling supervisor:which_children/1 during init/1 before supervisor has finished starting all children.

handle_info(Info, State)
init(Opts)
register_handler(Procedure, Handler)

Register a handler for a procedure.

start_link()

Start the gateway with default options.

start_link(Opts)

Start the gateway with custom options. Options: {port, Port} - Listen port (default: 9443) {realm, Realm} - Default realm (default: "macula.default")

stop(Gateway)

Stop the gateway.

terminate(Reason, State)
unregister_handler(Procedure)

Unregister a handler for a procedure.

# Functions

# get_stats(Gateway)

    -spec get_stats(pid()) -> map().

Get gateway statistics.

# handle_call(Request, From, State)

# handle_cast(Request, State)

Handle rpc_route message forwarded from connection

# handle_continue(_, State)

Wire gateway to siblings after init completes. This avoids initialization deadlock from calling supervisor:which_children/1 during init/1 before supervisor has finished starting all children.

# handle_info(Info, State)

# init(Opts)

# register_handler(Procedure, Handler)

    -spec register_handler(binary(), fun()) -> ok | {error, term()}.

Register a handler for a procedure.

# start_link()

    -spec start_link() -> {ok, pid()} | {error, term()}.

Start the gateway with default options.

# start_link(Opts)

    -spec start_link(proplists:proplist()) -> {ok, pid()} | {error, term()}.

Start the gateway with custom options. Options: {port, Port} - Listen port (default: 9443) {realm, Realm} - Default realm (default: "macula.default")

# stop(Gateway)

    -spec stop(pid()) -> ok.

Stop the gateway.

# terminate(Reason, State)

# unregister_handler(Procedure)

    -spec unregister_handler(binary()) -> ok.

Unregister a handler for a procedure.