Class DnsDiscovery

java.lang.Object
com.loomcache.server.discovery.DnsDiscovery
All Implemented Interfaces:
DiscoveryStrategy
public class DnsDiscovery extends Object implements DiscoveryStrategy
DNS-based discovery strategy for discovering peers via DNS name resolution with resilience.

Features

  • DNS Resolution: Resolves a DNS hostname to multiple A records, useful for Kubernetes headless services where DNS returns all pod IPs.
  • Retry Logic: Automatically retries failed DNS lookups with exponential backoff (up to 3 attempts). DNS failures are transient and should not immediately discard cached results.
  • TTL-Aware Caching: Caches resolved addresses and refreshes them periodically. Modern DNS resolvers respect TTL, but we also support manual refresh via start().
  • Health Checks: Validates cached addresses to detect stale/wrong entries.
  • Metrics: Tracks resolution attempts and success/failure rates.

Usage

  DnsDiscovery discovery = new DnsDiscovery("cache-cluster", 5701, registry);
  discovery.start();
  List peers = discovery.discoverPeers();

Thread Safety

Thread-safe with read-write locking. DNS lookups are performed outside the lock, and results are only published while holding the write lock for the current lifecycle generation.

  • Constructor Summary

    Constructors
    Constructor
    Description
    DnsDiscovery(String hostname, int port)
    Create a DNS discovery strategy for resolving peer addresses via DNS.
    DnsDiscovery(String hostname, int port, @Nullable io.micrometer.core.instrument.MeterRegistry registry)
    Create a DNS discovery strategy with metrics support.

  • Method Summary

    Modifier and Type
    Method
    Description
    List<PeerAddress>
    discoverPeers()
    Discover available peers by DNS resolution of cached peer list.
    String
    getName()
    Get the name of this discovery strategy.
    void
    start()
    Start the DNS discovery strategy by resolving the configured hostname.
    void
    stop()
    Stop the DNS discovery strategy and clear cached peer list.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • DnsDiscovery

      public DnsDiscovery(String hostname, int port)
      Create a DNS discovery strategy for resolving peer addresses via DNS.

      Useful for Kubernetes headless services where DNS returns all pod IPs as separate A records. No metrics are exported when registry is null.

      Parameters:
      hostname - DNS name to resolve (e.g., "cache-cluster" or "cache-cluster.default.svc.cluster.local")
      port - TCP port that all resolved addresses will use
      Throws:
      IllegalArgumentException - if hostname is null/empty or port is out of valid range

    • DnsDiscovery

      public DnsDiscovery(String hostname, int port, @Nullable io.micrometer.core.instrument.MeterRegistry registry)
      Create a DNS discovery strategy with metrics support.
      Parameters:
      hostname - DNS name to resolve
      port - TCP port for all resolved addresses
      registry - optional MeterRegistry for metrics (can be null)
      Throws:
      IllegalArgumentException - if hostname is null/empty or port is out of valid range

  • Method Details

    • discoverPeers

      public List<PeerAddress> discoverPeers()
      Discover available peers by DNS resolution of cached peer list.

      Returns a snapshot of the most recently resolved addresses. To refresh the peer list, call start() again to re-resolve the hostname.

      Performs basic health checks on cached addresses to detect and report stale entries.

      Specified by:
      discoverPeers in interface DiscoveryStrategy
      Returns:
      list of peer addresses resolved from the hostname, empty list if not yet resolved or resolution failed

    • start

      public void start() throws Exception
      Start the DNS discovery strategy by resolving the configured hostname.

      Performs DNS resolution with automatic retry logic and exponential backoff. If DNS resolution fails, previously cached results are retained. If no cached results exist, an empty peer list is used.

      Specified by:
      start in interface DiscoveryStrategy
      Throws:
      Exception - only if an unexpected (non-DNS) error occurs

    • stop

      public void stop()
      Stop the DNS discovery strategy and clear cached peer list.

      This method is idempotent and safe to call multiple times.

      Specified by:
      stop in interface DiscoveryStrategy

    • getName

      public String getName()
      Get the name of this discovery strategy.
      Specified by:
      getName in interface DiscoveryStrategy
      Returns:
      "DnsDiscovery"