Search documentation of macula

# macula_routing_bucket (macula v0.44.2)

View Source

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

# Summary

## Types

bucket/0
node_info/0

## Functions

add_node(Bucket, NodeInfo)

Add a node to the bucket. If node exists (same node_id), move to tail (most recent). If endpoint exists with different node_id, replace the stale entry. If bucket full, replace oldest stale entry or return {error, bucket_full}.

capacity(_)

Get bucket capacity.

evict_stale(Bucket, StaleThreshold)

Remove nodes not seen since StaleThreshold (millisecond timestamp).

find_closest(_, Target, N)

Find n closest nodes to target (sorted by XOR distance).

find_node(_, NodeId)

Find a node by ID.

get_endpoint(_)

Extract endpoint from node info (handles multiple key formats).

get_nodes(_)

Get all nodes in the bucket (ordered: oldest first).

has_node(_, NodeId)

Check if bucket contains node.

new(Capacity)

Create a new bucket with capacity k.

remove_by_endpoint(Bucket, Endpoint)

Remove all nodes matching an endpoint (regardless of node_id).

remove_ghost_by_endpoint(Bucket, Endpoint, NodeId)

Remove entries with matching endpoint but different node_id (ghost cleanup).

remove_node(Bucket, NodeId)

Remove a node from the bucket.

size(_)

Get number of nodes in bucket.

update_timestamp(Bucket, NodeId)

Update node's last_seen timestamp (moves to tail).

# Types

# bucket/0

    -type bucket() :: #{capacity := pos_integer(), nodes := [node_info()]}.

# node_info/0

    -type node_info() ::
              #{node_id := binary(),
                address := {inet:ip_address(), inet:port_number()},
                last_seen => integer()}.

# Functions

# add_node(Bucket, NodeInfo)

    -spec add_node(bucket(), node_info()) -> bucket() | {error, bucket_full}.

Add a node to the bucket. If node exists (same node_id), move to tail (most recent). If endpoint exists with different node_id, replace the stale entry. If bucket full, replace oldest stale entry or return {error, bucket_full}.

# capacity(_)

    -spec capacity(bucket()) -> pos_integer().

Get bucket capacity.

# evict_stale(Bucket, StaleThreshold)

    -spec evict_stale(bucket(), integer()) -> bucket().

Remove nodes not seen since StaleThreshold (millisecond timestamp).

# find_closest(_, Target, N)

    -spec find_closest(bucket(), binary(), pos_integer()) -> [node_info()].

Find n closest nodes to target (sorted by XOR distance).

# find_node(_, NodeId)

    -spec find_node(bucket(), binary()) -> {ok, node_info()} | not_found.

Find a node by ID.

# get_endpoint(_)

    -spec get_endpoint(node_info()) -> binary() | undefined.

Extract endpoint from node info (handles multiple key formats).

# get_nodes(_)

    -spec get_nodes(bucket()) -> [node_info()].

Get all nodes in the bucket (ordered: oldest first).

# has_node(_, NodeId)

    -spec has_node(bucket(), binary()) -> boolean().

Check if bucket contains node.

# new(Capacity)

    -spec new(pos_integer()) -> bucket().

Create a new bucket with capacity k.

# remove_by_endpoint(Bucket, Endpoint)

    -spec remove_by_endpoint(bucket(), binary() | undefined) -> bucket().

Remove all nodes matching an endpoint (regardless of node_id).

# remove_ghost_by_endpoint(Bucket, Endpoint, NodeId)

    -spec remove_ghost_by_endpoint(bucket(), binary() | undefined, binary()) -> bucket().

Remove entries with matching endpoint but different node_id (ghost cleanup).

# remove_node(Bucket, NodeId)

    -spec remove_node(bucket(), binary()) -> bucket().

Remove a node from the bucket.

# size(_)

    -spec size(bucket()) -> non_neg_integer().

Get number of nodes in bucket.

# update_timestamp(Bucket, NodeId)

    -spec update_timestamp(bucket(), binary()) -> bucket().

Update node's last_seen timestamp (moves to tail).