Search documentation of macula

# macula_content_dht (macula v0.44.2)

View Source

DHT integration for Macula content-addressed storage.

Handles content announcement and discovery through the DHT: - Announce manifest availability to mesh peers - Discover providers of content by MCID - TTL-based re-announcement for liveness

### DHT Key Structure

DHT keys are SHA-256 hashes of the MCID. This ensures: - Uniform distribution in the DHT keyspace - Same content always maps to same key - 32-byte keys match DHT node ID size

### Provider Discovery

When content is published, the provider announces to the DHT:

       Key: hash(MCID)
       Value: #{node_id, endpoint, metadata, advertised_at, ttl}

Multiple providers can announce the same content.

### Example Usage

       %% Announce content availability
       {Key, Value} = macula_content_dht:create_announcement(MCID, NodeId, Endpoint, Info),
       macula_routing_server:store(RoutingPid, Key, Value).

       %% Discover providers
       case macula_routing_server:find_value(RoutingPid, Key, 20) of
           {ok, Providers} -> handle_providers(Providers);
           {nodes, _} -> {error, not_found}
       end.

# Summary

## Types

mcid/0

34 bytes: version + codec + hash

provider_info/0

## Functions

announce_manifest(MCID, NodeId, Endpoint, ManifestInfo)

Announce manifest availability to DHT. Stores provider info at DHT key derived from MCID.

announce_manifest(MCID, NodeId, Endpoint, ManifestInfo, Opts)

Announce manifest with options. Options: - ttl: Custom TTL (default: 300 seconds)

create_announcement(MCID, NodeId, Endpoint, ManifestInfo)

Create DHT announcement for content availability. Returns {DHTKey, ProviderValue} tuple ready for storage.

create_provider_info(NodeId, Endpoint, Metadata)

Create provider info map with all required fields.

create_removal(NodeId)

Create removal marker for DHT. When a provider stops hosting content, they announce removal.

default_ttl()

Get default TTL for content announcements.

dht_key(MCID)

Generate DHT key from MCID. Uses SHA-256 to hash the MCID, ensuring uniform distribution in the DHT keyspace.

format_providers(Providers)

Format raw provider values into standardized list. Handles both single provider and list of providers.

get_ttl(Opts)

Get TTL from options or use default.

locate_providers(MCID)

Locate providers of content by MCID. Queries DHT and returns list of provider endpoints.

locate_providers(MCID, Opts)

Locate providers with options. Options: - k: Number of closest nodes to query (default: 20) - timeout: Query timeout in milliseconds

reannounce_interval(TTL)

Calculate interval for re-announcement. Re-announces slightly before TTL expires to maintain presence. Returns interval in seconds.

unannounce_manifest(MCID, NodeId, Opts)

Remove manifest announcement from DHT.

# Types

# mcid/0

    -type mcid() :: <<_:272>>.

34 bytes: version + codec + hash

# provider_info/0

    -type provider_info() ::
              #{node_id := binary(),
                endpoint := binary(),
                metadata := map(),
                advertised_at := integer(),
                ttl => pos_integer()}.

# Functions

# announce_manifest(MCID, NodeId, Endpoint, ManifestInfo)

    -spec announce_manifest(mcid(), binary(), binary(), map()) -> ok | {error, term()}.

Announce manifest availability to DHT. Stores provider info at DHT key derived from MCID.

# announce_manifest(MCID, NodeId, Endpoint, ManifestInfo, Opts)

    -spec announce_manifest(mcid(), binary(), binary(), map(), map()) -> ok | {error, term()}.

Announce manifest with options. Options: - ttl: Custom TTL (default: 300 seconds)

# create_announcement(MCID, NodeId, Endpoint, ManifestInfo)

    -spec create_announcement(mcid(), binary(), binary(), map()) -> {binary(), provider_info()}.

Create DHT announcement for content availability. Returns {DHTKey, ProviderValue} tuple ready for storage.

# create_provider_info(NodeId, Endpoint, Metadata)

    -spec create_provider_info(binary(), binary(), map()) -> provider_info().

Create provider info map with all required fields.

# create_removal(NodeId)

    -spec create_removal(binary()) -> map().

Create removal marker for DHT. When a provider stops hosting content, they announce removal.

# default_ttl()

    -spec default_ttl() -> pos_integer().

Get default TTL for content announcements.

# dht_key(MCID)

    -spec dht_key(mcid()) -> binary().

Generate DHT key from MCID. Uses SHA-256 to hash the MCID, ensuring uniform distribution in the DHT keyspace.

# format_providers(Providers)

    -spec format_providers([provider_info()] | provider_info()) -> [provider_info()].

Format raw provider values into standardized list. Handles both single provider and list of providers.

# get_ttl(Opts)

    -spec get_ttl(map()) -> pos_integer().

Get TTL from options or use default.

# locate_providers(MCID)

    -spec locate_providers(mcid()) -> {ok, [provider_info()]} | {error, term()}.

Locate providers of content by MCID. Queries DHT and returns list of provider endpoints.

# locate_providers(MCID, Opts)

    -spec locate_providers(mcid(), map()) -> {ok, [provider_info()]} | {error, term()}.

Locate providers with options. Options: - k: Number of closest nodes to query (default: 20) - timeout: Query timeout in milliseconds

# reannounce_interval(TTL)

    -spec reannounce_interval(pos_integer()) -> pos_integer().

Calculate interval for re-announcement. Re-announces slightly before TTL expires to maintain presence. Returns interval in seconds.

# unannounce_manifest(MCID, NodeId, Opts)

    -spec unannounce_manifest(mcid(), binary(), map()) -> ok | {error, term()}.

Remove manifest announcement from DHT.