macula_nat_cache (macula v0.20.5)
View SourceNAT Profile Cache with TTL and Stale-While-Revalidate.
Caches NAT profiles for peers to avoid repeated detection overhead. Implements stale-while-revalidate pattern: - Fresh (0-TTL): Use immediately - Stale (TTL to TTL+60s): Use but trigger background refresh - Expired (>TTL+60s): Must re-detect
Based on NATCracker methodology, NAT profiles include: - Mapping policy: EI (Endpoint-Independent), HD (Host-Dependent), PD (Port-Dependent) - Filtering policy: EI, HD, PD - Allocation policy: PP (Port-Preservation), PC (Port-Contiguity), RD (Random)
Uses ETS for O(1) lookups with bounded memory via LRU eviction.
Summary
Functions
Clear all cached NAT profiles.
Get NAT profile for a node ID from local cache. Returns {ok, Profile, Status} where Status is fresh | stale Returns not_found if not in cache or expired.
Get NAT profile from DHT (remote lookup). First checks local cache, then falls back to DHT query. Caches result locally if found in DHT. Returns {ok, Profile} | not_found | {error, Reason}.
Get NAT profile for the local node. Uses macula_names:local_node_id/0 to get the local node ID. Returns {ok, Profile} or not_found.
Invalidate NAT profile for a node ID.
Store NAT profile with default TTL.
Store NAT profile with custom TTL.
Start the NAT cache server.
Get cache statistics.
Types
-type allocation_policy() :: pp | pc | rd.
-type filtering_policy() :: ei | hd | pd.
-type mapping_policy() :: ei | hd | pd.
-type nat_profile() :: #{node_id := binary(), mapping_policy := mapping_policy(), filtering_policy := filtering_policy(), allocation_policy := allocation_policy(), reflexive_address => {inet:ip_address(), inet:port_number()}, port_delta => integer(), can_receive_unsolicited := boolean(), requires_relay := boolean(), relay_capable := boolean(), detected_at := integer(), ttl_seconds := pos_integer(), latitude => float(), longitude => float(), location_label => binary()}.
Functions
-spec clear() -> ok.
Clear all cached NAT profiles.
-spec get(binary()) -> {ok, nat_profile(), fresh | stale} | not_found.
Get NAT profile for a node ID from local cache. Returns {ok, Profile, Status} where Status is fresh | stale Returns not_found if not in cache or expired.
-spec get_from_dht(binary()) -> {ok, nat_profile()} | not_found | {error, term()}.
Get NAT profile from DHT (remote lookup). First checks local cache, then falls back to DHT query. Caches result locally if found in DHT. Returns {ok, Profile} | not_found | {error, Reason}.
-spec get_local() -> {ok, nat_profile()} | not_found.
Get NAT profile for the local node. Uses macula_names:local_node_id/0 to get the local node ID. Returns {ok, Profile} or not_found.
-spec invalidate(binary()) -> ok.
Invalidate NAT profile for a node ID.
-spec put(binary(), nat_profile()) -> ok.
Store NAT profile with default TTL.
-spec put(binary(), nat_profile(), pos_integer()) -> ok.
Store NAT profile with custom TTL.
Start the NAT cache server.
-spec stats() -> #{size := non_neg_integer(), max_entries := pos_integer(), hits := non_neg_integer(), misses := non_neg_integer(), evictions := non_neg_integer(), hit_rate := float()}.
Get cache statistics.