or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-api.mddiscovery-extension.mdindex.mdresolution-types.md
tile.json

tessl/maven-com-typesafe-akka--akka-discovery_2-12

Service discovery API for distributed Akka applications to locate and connect to other services in dynamic environments.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.typesafe.akka/akka-discovery_2.12@2.8.x

To install, run

npx @tessl/cli install tessl/maven-com-typesafe-akka--akka-discovery_2-12@2.8.0

index.mddocs/

Akka Discovery

Akka Discovery provides a service discovery API for distributed Akka applications to locate and connect to other services in dynamic environments. It offers a pluggable architecture with multiple discovery implementations including DNS-based discovery, configuration-based discovery, and aggregate discovery that can combine multiple discovery methods.

Package Information

  • Package Name: akka-discovery
  • Package Type: maven
  • Language: Scala
  • Installation: 
    libraryDependencies += "com.typesafe.akka" %% "akka-discovery" % "2.8.8"
  • Java API: Full Java interoperability with CompletionStage and Optional types

Core Imports

Scala API

import akka.discovery.Discovery
import akka.discovery.{Lookup, ServiceDiscovery}
import akka.discovery.ServiceDiscovery.{Resolved, ResolvedTarget}

Java API

import akka.discovery.Discovery;
import akka.discovery.Lookup;
import akka.discovery.ServiceDiscovery;

Basic Usage

Scala API

import akka.actor.ActorSystem
import akka.discovery.Discovery
import akka.discovery.Lookup
import scala.concurrent.duration._

implicit val system = ActorSystem()
val serviceDiscovery = Discovery(system).discovery

// Simple service lookup
val resolved = serviceDiscovery.lookup("my-service", 3.seconds)

// Advanced lookup with port and protocol
val lookup = Lookup("my-service")
  .withPortName("http")
  .withProtocol("tcp")
val resolvedAdvanced = serviceDiscovery.lookup(lookup, 3.seconds)

Java API

import akka.actor.ActorSystem;
import akka.discovery.Discovery;
import akka.discovery.Lookup;
import java.time.Duration;

ActorSystem system = ActorSystem.create();
ServiceDiscovery serviceDiscovery = Discovery.get(system).discovery();

// Simple service lookup
CompletionStage<ServiceDiscovery.Resolved> resolved = 
    serviceDiscovery.lookup("my-service", Duration.ofSeconds(3));

// Advanced lookup with port and protocol
CompletionStage<ServiceDiscovery.Resolved> resolvedAdvanced = 
    serviceDiscovery.lookup(
        Lookup.create("my-service")
            .withPortName("http")
            .withProtocol("tcp"),
        Duration.ofSeconds(3)
    );

Architecture

Akka Discovery is built around several key components:

  • ServiceDiscovery: Abstract base class defining the discovery contract with pluggable implementations
  • Discovery Extension: Akka extension system integration for loading and managing discovery methods
  • Lookup Query System: Structured queries supporting service names, port names, and protocols including SRV record parsing
  • Multiple Implementations: DNS-based, configuration-based, and aggregate discovery implementations
  • Async Resolution: Non-blocking service resolution with configurable timeouts and Future/CompletionStage APIs

Configuration

Akka Discovery uses several key configuration properties that control its behavior:

Essential Configuration Keys

akka.discovery {
  # Default discovery method - must be set to a valid method name
  method = "akka-dns"  # or "config", "aggregate", or custom implementation
  
  # Built-in implementation classes
  akka-dns {
    class = "akka.discovery.dns.DnsServiceDiscovery"
  }
  
  config {
    class = "akka.discovery.config.ConfigServiceDiscovery"
    services-path = "akka.discovery.config.services"
  }
  
  aggregate {
    class = "akka.discovery.aggregate.AggregateServiceDiscovery" 
    discovery-methods = ["akka-dns", "config"]
  }
}

Configuration Pattern

All discovery implementations follow the pattern akka.discovery.[method].class where [method] is the discovery method name used in loadServiceDiscovery(method).

Capabilities

Core Service Discovery API

Essential service discovery functionality including lookup queries, resolution results, and timeout handling. This forms the foundation for all service discovery operations.

abstract class ServiceDiscovery {
  def lookup(lookup: Lookup, resolveTimeout: FiniteDuration): Future[Resolved]
  def lookup(serviceName: String, resolveTimeout: FiniteDuration): Future[Resolved]
  
  // Java API
  def lookup(query: Lookup, resolveTimeout: java.time.Duration): CompletionStage[Resolved]
  def lookup(serviceName: String, resolveTimeout: java.time.Duration): CompletionStage[Resolved]
}

final class Lookup(val serviceName: String, val portName: Option[String], val protocol: Option[String]) {
  def withPortName(value: String): Lookup
  def withProtocol(value: String): Lookup
  
  // Java API
  def getPortName: Optional[String]
  def getProtocol: Optional[String]
}

Core API

Discovery Extension System

Extension system for loading and managing service discovery implementations with support for multiple discovery methods and configuration-based selection.

final class Discovery extends Extension {
  def discovery: ServiceDiscovery
  def loadServiceDiscovery(method: String): ServiceDiscovery
}

object Discovery extends ExtensionId[Discovery] {
  def apply(system: ActorSystem): Discovery
  def get(system: ActorSystem): Discovery
  def get(system: ClassicActorSystemProvider): Discovery
}

Discovery Extension

Resolution Data Types

Data structures representing service discovery results including resolved endpoints with host, port, and IP address information.

final class Resolved(val serviceName: String, val addresses: immutable.Seq[ResolvedTarget]) {
  // Java API
  def getAddresses: java.util.List[ResolvedTarget]
}

final class ResolvedTarget(val host: String, val port: Option[Int], val address: Option[InetAddress]) {
  // Java API
  def getPort: Optional[Int]
  def getAddress: Optional[InetAddress]
}

Resolution Types

Types

// Exception thrown when lookup times out
final class DiscoveryTimeoutException(reason: String) extends RuntimeException(reason)

// Factory methods for creating Lookup instances
object Lookup {
  def apply(serviceName: String): Lookup
  def apply(serviceName: String, portName: Option[String], protocol: Option[String]): Lookup
  def create(serviceName: String): Lookup  // Java API
  def parseSrv(str: String): Lookup
  def isValidSrv(srv: String): Boolean
}

// Factory methods for creating result types
object ServiceDiscovery {
  object Resolved {
    def apply(serviceName: String, addresses: immutable.Seq[ResolvedTarget]): Resolved
  }
  
  object ResolvedTarget {
    def apply(host: String, port: Option[Int], address: Option[InetAddress]): ResolvedTarget
  }
}