-spec advertise_local(registry(), service_id(), handler_fn(), map()) -> registry().

Advertise a service locally (stores handler for incoming calls).

This registers the service handler locally so this node can respond to incoming RPC calls. The actual DHT advertisement must be done separately (see publish_to_dht/4).

-spec cache_service(registry(), service_id(), [provider_info()], pos_integer()) -> registry().

Cache discovered service providers.

Stores providers in local cache with TTL. Subsequent discover_service calls will return cached results until TTL expires.

-spec cache_subscribers(registry(), binary(), [provider_info()], pos_integer()) -> registry().

Cache discovered subscribers for a topic.

Stores subscribers in local cache with TTL. Subsequent discover_subscribers/2 calls will return cached results until TTL expires.

-spec clear_cache(registry()) -> registry().

Clear the entire discovery cache.

-spec clear_subscriber_cache(registry()) -> registry().

Clear the entire subscriber cache.

-spec discover_service(registry(), service_id()) ->
                          {ok, [provider_info()], registry()} | {cache_miss, registry()}.

Discover service providers (checks cache first, returns cached if available).

-spec discover_service(registry(), service_id(), map()) ->
                          {ok, [provider_info()], registry()} | {cache_miss, registry()}.

Discover service providers with options.

Checks local cache first. If found and not expired, returns cached providers. If cache miss or expired, returns {cache_miss, Registry} so caller can query DHT.

Options: - force_refresh - Skip cache, force DHT lookup (default: false)

-spec discover_subscribers(registry(), binary()) ->
                              {ok, [provider_info()], registry()} | {cache_miss, registry()}.

Discover subscribers for a topic (checks cache first).

Similar to discover_service/2 but for pub/sub subscribers. Returns cached subscribers if found and not expired, otherwise cache_miss.

-spec get_local_handler(registry(), service_id()) -> {ok, handler_fn()} | not_found.

Get handler function for a locally advertised service.

-spec list_local_services(registry()) -> [service_id()].

List all locally advertised services.

-spec new() -> registry().

Create new empty service registry with default settings.

-spec new(map()) -> registry().

Create new service registry with custom options.

Options: - default_ttl - Default TTL for DHT advertisements (default: 300s) - cache_ttl - How long to cache discovered services (default: 60s) - service_ttl - TTL for local services before cleanup (default: 300s, 5 minutes)

-spec prune_expired(registry()) -> {registry(), non_neg_integer()}.

Remove expired entries from discovery cache.

Should be called periodically to prevent memory leaks. Returns updated registry and count of removed entries.

-spec prune_expired_local_services(registry()) -> {registry(), non_neg_integer()}.

Remove expired local services.

Should be called periodically to prevent memory leaks from stale service registrations. Returns updated registry and count of removed services.

-spec prune_expired_subscribers(registry()) -> {registry(), non_neg_integer()}.

Remove expired subscriber cache entries.

Should be called periodically to prevent memory leaks. Returns updated registry and count of removed entries.

-spec publish_to_dht(pid() | atom(), service_id(), provider_info(), pos_integer(), pos_integer()) ->
                        ok | {error, term()}.

Publish a service advertisement to the DHT.

This function publishes a service's provider information to the DHT so other nodes can discover it. The service_id is hashed to create a DHT key, and the provider information is stored at that key.

Parameters: - DhtPid: Process ID or registered name of macula_routing_server - ServiceId: The service identifier (procedure URI) - ProviderInfo: Information about this provider (node_id, endpoint, metadata) - TTL: Time-to-live in seconds for this advertisement - K: Number of nodes to store at (typically 20 for Kademlia)

Returns: - ok if successful - {error, Reason} if publication failed

Example:

  ProviderInfo = #{
      node_id => <<"my-node-123">>,
      endpoint => <<"https://localhost:9443">>,
      metadata => #{version => <<"1.0">>}
  },
  ok = publish_to_dht(DhtPid, &lt;&lt;"energy.home.get"&gt;&gt;, ProviderInfo, 300, 20).

-spec query_dht_for_service(pid() | atom(), service_id(), pos_integer()) ->
                               {ok, [provider_info()]} | {error, term()}.

Query the DHT for service providers.

This function queries the DHT to find nodes that provide a given service. It returns a list of provider_info() maps, each containing node_id, endpoint, and metadata for a provider.

Parameters: - DhtPid: Process ID or registered name of macula_routing_server - ServiceId: The service identifier to query for - K: Number of closest nodes to query (typically 20 for Kademlia)

Returns: - {ok, [ProviderInfo]} if providers found - {ok, []} if no providers found - {error, Reason} if query failed

Example:

  {ok, Providers} = query_dht_for_service(DhtPid, <<"energy.home.get">>, 20),
  %% Returns: [{ok, [#{node_id => ..., endpoint => ..., metadata => ...}]}]

-spec remove_from_dht(pid() | atom(), service_id(), node_id()) -> ok | {error, term()}.

Remove a service advertisement from the DHT.

This function removes a service advertisement when unadvertising. Note: In practice, DHT entries expire naturally via TTL, so this is optional and mainly useful for immediate cleanup.

Parameters: - DhtPid: Process ID or registered name of macula_routing_server - ServiceId: The service identifier to remove - NodeId: This node's identifier (to remove only this provider)

Returns: - ok if successful or entry not found - {error, Reason} if removal failed

-spec unadvertise_local(registry(), service_id()) -> registry().

Remove a local service advertisement.