Search documentation of macula

# macula_routing_dht (macula v0.44.2)

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.