macula_nat_coordinator (macula v0.14.3)

View Source

NAT Hole Punch Coordinator.

Coordinates hole punching between two NATted peers using NATCracker-informed strategies. Determines the optimal connection approach based on both peers' NAT profiles:

Connection Strategy Decision Tree: 1. Direct Connection - Possible when: - Either peer has public IP (no NAT) - Target has EI mapping + EI filtering (Full Cone)

2. Hole Punching - Possible when: - Both peers have EI or HD mapping (predictable external address) - At least one has PP or PC allocation (predictable ports) - Neither has PD mapping + PD filtering + RD allocation

3. Relay Required - When: - Either peer has symmetric NAT (PD+PD+RD) - Hole punching attempts fail

Hole Punch Coordination Protocol: 1. Initiator sends PUNCH_REQUEST to coordinator (any public-IP peer) 2. Coordinator fetches both peers' NAT profiles from DHT 3. Coordinator sends PUNCH_COORDINATE to both peers with timing info 4. Both peers send PUNCH_EXECUTE at coordinated time 5. Coordinator receives PUNCH_RESULT from both peers 6. If failed, falls back to relay

Summary

Types

connection_strategy/0
punch_session/0

Functions

coordinate_punch(InitiatorId, TargetId, Opts)

Coordinate a hole punch between two peers. Called by a public-IP peer acting as coordinator.

get_pending()

Get all pending punch sessions (for debugging).

handle_call(Request, From, State)
handle_cast(Msg, State)
handle_info(Info, State)
init(Opts)
report_result(SessionId, ReporterId, Result)

Report result of a hole punch attempt.

request_connection(InitiatorId, TargetId)

Request a connection to a target peer. Returns the recommended strategy and session ID for tracking.

request_connection(InitiatorId, TargetId, Opts)

Request connection with options.

start_link(Opts)

Start the NAT coordinator server.

terminate(Reason, State)

Types

connection_strategy/0

-type connection_strategy() :: direct | hole_punch | relay.

punch_session/0

-type punch_session() ::
          #{session_id := binary(),
            initiator_id := binary(),
            target_id := binary(),
            initiator_profile := macula_nat_cache:nat_profile() | undefined,
            target_profile := macula_nat_cache:nat_profile() | undefined,
            strategy := connection_strategy(),
            state := pending | coordinating | executing | completed | failed,
            attempts := non_neg_integer(),
            created_at := integer(),
            result => success | timeout | unreachable}.

Functions

coordinate_punch(InitiatorId, TargetId, Opts)

-spec coordinate_punch(binary(), binary(), map()) -> ok | {error, term()}.

Coordinate a hole punch between two peers. Called by a public-IP peer acting as coordinator.

get_pending()

-spec get_pending() -> [punch_session()].

Get all pending punch sessions (for debugging).

handle_call(Request, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

init(Opts)

report_result(SessionId, ReporterId, Result)

-spec report_result(binary(), binary(), success | failure) -> ok.

Report result of a hole punch attempt.

request_connection(InitiatorId, TargetId)

-spec request_connection(binary(), binary()) -> {ok, connection_strategy(), binary()} | {error, term()}.

Request a connection to a target peer. Returns the recommended strategy and session ID for tracking.

request_connection(InitiatorId, TargetId, Opts)

-spec request_connection(binary(), binary(), map()) ->
                            {ok, connection_strategy(), binary()} | {error, term()}.

Request connection with options.

start_link(Opts)

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

Start the NAT coordinator server.

terminate(Reason, State)