macula_routing_dht (macula v0.20.5)

View Source

Core DHT algorithms for Kademlia routing. Implements iterative lookup, store, and find operations. Pure functions - no GenServer, designed to be called by macula_routing_server.

Summary

Types

query_fn/0
store_fn/0

Functions

delete(Key)

Delete a key from the DHT. Delegates to macula_routing_server if running.

find(Key)

Find a value in the DHT. Delegates to macula_routing_server if running.

find_value(RoutingTable, Key, K, QueryFn)

Find value in DHT. Returns {ok, Value} if found, {nodes, [NodeInfo]} if not found.

iterative_find_node(RoutingTable, Target, K, QueryFn)

Iterative lookup to find k closest nodes to target. Uses alpha concurrent queries (default: 3).

notify_delete(Key)

Notify subscribers about a DHT delete event. Called by macula_routing_server when a key is deleted.

notify_store(Key, Value)

Notify subscribers about a DHT store event. Called by macula_routing_server when a key is stored.

select_alpha(Closest, Queried, Alpha)

Select up to alpha unqueried nodes from closest set.

store(Key, Value)

Store a key-value pair in the DHT. Delegates to macula_routing_server if running.

store_value(RoutingTable, Key, Value, K, QueryFn, StoreFn)

Store value at k closest nodes to key.

subscribe(Prefix, Pid)

Subscribe to DHT events matching a key prefix. Subscribes the given Pid to receive events when keys with the given prefix are stored or deleted. Uses gproc property-based subscriptions.

update_closest(CurrentClosest, NewNodes, Target, K)

Update closest set with new nodes, maintaining k closest and removing duplicates.

Types

query_fn/0

-type query_fn() ::
          fun((macula_routing_bucket:node_info(), binary()) ->
                  {ok, [macula_routing_bucket:node_info()]} |
                  {value, term()} |
                  {nodes, [macula_routing_bucket:node_info()]} |
                  {error, term()}).

store_fn/0

-type store_fn() :: fun((macula_routing_bucket:node_info(), binary(), term()) -> ok | {error, term()}).

Functions

delete(Key)

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

Delete a key from the DHT. Delegates to macula_routing_server if running.

find(Key)

-spec find(binary()) -> {ok, binary()} | {error, not_found | term()}.

Find a value in the DHT. Delegates to macula_routing_server if running.

find_value(RoutingTable, Key, K, QueryFn)

-spec find_value(macula_routing_table:routing_table(), binary(), pos_integer(), query_fn()) ->
                    {ok, term()} | {nodes, [macula_routing_bucket:node_info()]}.

Find value in DHT. Returns {ok, Value} if found, {nodes, [NodeInfo]} if not found.

iterative_find_node(RoutingTable, Target, K, QueryFn)

-spec iterative_find_node(macula_routing_table:routing_table(), binary(), pos_integer(), query_fn()) ->
                             {ok, [macula_routing_bucket:node_info()]}.

Iterative lookup to find k closest nodes to target. Uses alpha concurrent queries (default: 3).

notify_delete(Key)

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

Notify subscribers about a DHT delete event. Called by macula_routing_server when a key is deleted.

notify_store(Key, Value)

-spec notify_store(binary(), term()) -> ok.

Notify subscribers about a DHT store event. Called by macula_routing_server when a key is stored.

select_alpha(Closest, Queried, Alpha)

-spec select_alpha([macula_routing_bucket:node_info()], [binary()], pos_integer()) ->
                      [macula_routing_bucket:node_info()].

Select up to alpha unqueried nodes from closest set.

store(Key, Value)

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

Store a key-value pair in the DHT. Delegates to macula_routing_server if running.

store_value(RoutingTable, Key, Value, K, QueryFn, StoreFn)

-spec store_value(macula_routing_table:routing_table(),
                  binary(),
                  term(),
                  pos_integer(),
                  query_fn(),
                  store_fn()) ->
                     ok.

Store value at k closest nodes to key.

subscribe(Prefix, Pid)

-spec subscribe(binary(), pid()) -> ok.

Subscribe to DHT events matching a key prefix. Subscribes the given Pid to receive events when keys with the given prefix are stored or deleted. Uses gproc property-based subscriptions.

Events sent to the subscriber: {dht_stored, Key, Value} - When a key is stored {dht_deleted, Key} - When a key is deleted

To unsubscribe, the subscriber process should call: gproc:unreg({p, l, {dht_prefix_subscription, Prefix}})

update_closest(CurrentClosest, NewNodes, Target, K)

-spec update_closest([macula_routing_bucket:node_info()],
                     [macula_routing_bucket:node_info()],
                     binary(),
                     pos_integer()) ->
                        [macula_routing_bucket:node_info()].

Update closest set with new nodes, maintaining k closest and removing duplicates.