macula_gateway_dht (macula v0.25.1)
View SourceDHT 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 a PUBLISH message to the bootstrap gateway for distribution.
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 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 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 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.
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 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).
Functions
Forward a PUBLISH message to the bootstrap gateway for distribution.
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 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 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 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.
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 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).