Search documentation of macula

# macula_gateway_dht (macula v0.44.2)

View Source

DHT Query Handler Module - handles DHT message forwarding to routing server.

Responsibilities: - Forward DHT STORE messages to routing server - Forward DHT FIND_VALUE messages to routing server, send encoded replies - Forward DHT FIND_NODE messages to routing server, send encoded replies - Handle DHT queries from process messages - Encode replies using protocol encoder - Handle errors gracefully

Pattern: Stateless delegation module - No GenServer (no state to manage) - Pure functions forwarding to routing server - Consistent error handling ({ok, Result} | {error, Reason})

Extracted from macula_gateway.erl (Phase 10)

# Summary

## Functions

forward_publish_to_bootstrap(PubMsg) deprecated

Forward a PUBLISH message to the bootstrap gateway for distribution.

handle_find_node(Stream, FindNodeMsg)

Handle DHT FIND_NODE message. The message is already decoded by the gateway — it's the payload without the type field. We extract the target and query the routing table directly instead of going through handle_message (which re-classifies and fails because the type field is stripped).

handle_find_value(Stream, FindValueMsg)

Handle DHT FIND_VALUE message. Extracts the key and performs local storage lookup, returning result over stream. The message format from protocol decoder contains a binary key field.

handle_query(FromPid, QueryType, QueryData)

Handle DHT query from process message. Decodes query, forwards to routing server, encodes reply, sends to requesting process. Crashes on decode or routing failures - exposes protocol/DHT bugs.

handle_store(Stream, StoreMsg)

Handle DHT STORE message. Forwards to routing server asynchronously (fire-and-forget, no reply needed). Uses async handler to prevent blocking the gateway on DHT operations.

lookup_value(Key)

Look up ALL providers for a key — merges local + network results. Used by pubsub discovery where we need ALL subscribers, not just the first.

query_peer(NodeInfo, MessageType, Message)

Query remote peer and wait for response. Used for FIND_NODE and FIND_VALUE operations. Currently uses fire-and-forget delivery. For request/response patterns, use macula_rpc_handler:request/4 which provides NATS-style async RPC with callbacks (available since v0.12.1).

send_and_wait(NodeInfo, MessageType, Message, Timeout)

Send a DHT message to a peer and wait for response. Used by macula_routing_server for iterative FIND_VALUE lookups.

send_to_peer(NodeInfo, MessageType, Message)

# Functions

# forward_publish_to_bootstrap(PubMsg)

This function is deprecated. v0.14.0+ uses direct P2P routing via local DHT lookup. Bootstrap is NOT a broker - use route_via_local_dht in pubsub_router instead. This function remains for backwards compatibility but should not be used..

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

Forward a PUBLISH message to the bootstrap gateway for distribution.

# handle_find_node(Stream, FindNodeMsg)

    -spec handle_find_node(reference(), map()) -> ok.

Handle DHT FIND_NODE message. The message is already decoded by the gateway — it's the payload without the type field. We extract the target and query the routing table directly instead of going through handle_message (which re-classifies and fails because the type field is stripped).

# handle_find_value(Stream, FindValueMsg)

    -spec handle_find_value(reference(), map()) -> ok.

Handle DHT FIND_VALUE message. Extracts the key and performs local storage lookup, returning result over stream. The message format from protocol decoder contains a binary key field.

# handle_query(FromPid, QueryType, QueryData)

    -spec handle_query(pid(), atom(), binary()) -> ok.

Handle DHT query from process message. Decodes query, forwards to routing server, encodes reply, sends to requesting process. Crashes on decode or routing failures - exposes protocol/DHT bugs.

# handle_store(Stream, StoreMsg)

    -spec handle_store(reference(), map()) -> ok.

Handle DHT STORE message. Forwards to routing server asynchronously (fire-and-forget, no reply needed). Uses async handler to prevent blocking the gateway on DHT operations.

# lookup_value(Key)

    -spec lookup_value(binary()) -> {ok, list()} | {error, not_found}.

Look up ALL providers for a key — merges local + network results. Used by pubsub discovery where we need ALL subscribers, not just the first.

# query_peer(NodeInfo, MessageType, Message)

    -spec query_peer(map(), atom(), map()) -> {ok, term()} | {error, term()}.

Query remote peer and wait for response. Used for FIND_NODE and FIND_VALUE operations. Currently uses fire-and-forget delivery. For request/response patterns, use macula_rpc_handler:request/4 which provides NATS-style async RPC with callbacks (available since v0.12.1).

# send_and_wait(NodeInfo, MessageType, Message, Timeout)

    -spec send_and_wait(map(), atom(), map(), timeout()) -> {ok, term()} | {error, term()}.

Send a DHT message to a peer and wait for response. Used by macula_routing_server for iterative FIND_VALUE lookups.

# send_to_peer(NodeInfo, MessageType, Message)

    -spec send_to_peer(map(), atom(), map()) -> ok | {error, term()}.