macula_port_predictor (macula v0.20.5)

View Source

Port Prediction for NAT Traversal.

Provides intelligent port prediction based on NAT allocation policies and historical port allocation data. Improves hole punch success rates by predicting the external ports a peer will use.

Prediction Strategies by Allocation Policy:

- PP (Port Preservation): External port = internal port Prediction: Use last known port (high confidence)

- PC (Port Contiguity): Sequential port allocation Prediction: Calculate delta from history, predict next ports Delta tracking with exponential moving average

- RD (Random): Random port allocation Prediction: Use historical range + common NAT port ranges Statistical approach with lower confidence

Port History Storage: - Tracks last N port allocations per peer (default: 10) - Calculates port deltas for PC allocation - Maintains statistics for RD allocation (mean, stddev, range)

Summary

Types

allocation_policy/0
port_history/0
port_prediction/0
port_stats/0

Functions

clear(NodeId)

Clear port history for a peer.

get_history(NodeId)

Get port history for a peer.

get_stats(NodeId)

Get port statistics for a peer.

handle_call(Request, From, State)
handle_cast(Msg, State)
handle_info(Info, State)
init(Opts)
predict(NodeId, AllocationPolicy)

Predict external ports for a peer. Uses NAT profile if available, otherwise uses historical data.

predict(NodeId, AllocationPolicy, Opts)

Predict external ports with options. Options: base_port - Known/expected base port for prediction count - Number of ports to predict (default: 5)

record_port(NodeId, Port, AllocationPolicy)

Record an observed external port for a peer. Used to build history for better predictions.

start_link(Opts)

Start the port predictor server.

terminate(Reason, State)

Types

allocation_policy/0

-type allocation_policy() :: pp | pc | rd | unknown.

port_history/0

-type port_history() ::
          #{node_id := binary(),
            ports := [inet:port_number()],
            deltas := [integer()],
            updated_at := integer()}.

port_prediction/0

-type port_prediction() ::
          #{ports := [inet:port_number()],
            confidence := float(),
            strategy := pp | pc | rd | fallback,
            delta => integer(),
            stats => port_stats()}.

port_stats/0

-type port_stats() ::
          #{mean := float(),
            stddev := float(),
            min := inet:port_number(),
            max := inet:port_number(),
            count := non_neg_integer()}.

Functions

clear(NodeId)

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

Clear port history for a peer.

get_history(NodeId)

-spec get_history(binary()) -> {ok, port_history()} | not_found.

Get port history for a peer.

get_stats(NodeId)

-spec get_stats(binary()) -> {ok, port_stats()} | not_found.

Get port statistics for a peer.

handle_call(Request, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

init(Opts)

predict(NodeId, AllocationPolicy)

-spec predict(binary(), allocation_policy()) -> port_prediction().

Predict external ports for a peer. Uses NAT profile if available, otherwise uses historical data.

predict(NodeId, AllocationPolicy, Opts)

-spec predict(binary(), allocation_policy(), map()) -> port_prediction().

Predict external ports with options. Options: base_port - Known/expected base port for prediction count - Number of ports to predict (default: 5)

record_port(NodeId, Port, AllocationPolicy)

-spec record_port(binary(), inet:port_number(), allocation_policy()) -> ok.

Record an observed external port for a peer. Used to build history for better predictions.

start_link(Opts)

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

Start the port predictor server.

terminate(Reason, State)