0
# Akka Discovery
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: akka-discovery
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: 
10
  ```scala
11
  libraryDependencies += "com.typesafe.akka" %% "akka-discovery" % "2.8.8"
12
  ```
13
- **Java API**: Full Java interoperability with `CompletionStage` and Optional types
14

15
## Core Imports
16

17
### Scala API
18

19
```scala
20
import akka.discovery.Discovery
21
import akka.discovery.{Lookup, ServiceDiscovery}
22
import akka.discovery.ServiceDiscovery.{Resolved, ResolvedTarget}
23
```
24

25
### Java API
26

27
```java
28
import akka.discovery.Discovery;
29
import akka.discovery.Lookup;
30
import akka.discovery.ServiceDiscovery;
31
```
32

33
## Basic Usage
34

35
### Scala API
36

37
```scala
38
import akka.actor.ActorSystem
39
import akka.discovery.Discovery
40
import akka.discovery.Lookup
41
import scala.concurrent.duration._
42

43
implicit val system = ActorSystem()
44
val serviceDiscovery = Discovery(system).discovery
45

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

49
// Advanced lookup with port and protocol
50
val lookup = Lookup("my-service")
51
  .withPortName("http")
52
  .withProtocol("tcp")
53
val resolvedAdvanced = serviceDiscovery.lookup(lookup, 3.seconds)
54
```
55

56
### Java API
57

58
```java
59
import akka.actor.ActorSystem;
60
import akka.discovery.Discovery;
61
import akka.discovery.Lookup;
62
import java.time.Duration;
63

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

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

71
// Advanced lookup with port and protocol
72
CompletionStage<ServiceDiscovery.Resolved> resolvedAdvanced = 
73
    serviceDiscovery.lookup(
74
        Lookup.create("my-service")
75
            .withPortName("http")
76
            .withProtocol("tcp"),
77
        Duration.ofSeconds(3)
78
    );
79
```
80

81
## Architecture
82

83
Akka Discovery is built around several key components:
84

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

91
## Configuration
92

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

95
### Essential Configuration Keys
96

97
```hocon
98
akka.discovery {
99
  # Default discovery method - must be set to a valid method name
100
  method = "akka-dns"  # or "config", "aggregate", or custom implementation
101
  
102
  # Built-in implementation classes
103
  akka-dns {
104
    class = "akka.discovery.dns.DnsServiceDiscovery"
105
  }
106
  
107
  config {
108
    class = "akka.discovery.config.ConfigServiceDiscovery"
109
    services-path = "akka.discovery.config.services"
110
  }
111
  
112
  aggregate {
113
    class = "akka.discovery.aggregate.AggregateServiceDiscovery" 
114
    discovery-methods = ["akka-dns", "config"]
115
  }
116
}
117
```
118

119
### Configuration Pattern
120

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

123
## Capabilities
124

125
### Core Service Discovery API
126

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

129
```scala { .api }
130
abstract class ServiceDiscovery {
131
  def lookup(lookup: Lookup, resolveTimeout: FiniteDuration): Future[Resolved]
132
  def lookup(serviceName: String, resolveTimeout: FiniteDuration): Future[Resolved]
133
  
134
  // Java API
135
  def lookup(query: Lookup, resolveTimeout: java.time.Duration): CompletionStage[Resolved]
136
  def lookup(serviceName: String, resolveTimeout: java.time.Duration): CompletionStage[Resolved]
137
}
138

139
final class Lookup(val serviceName: String, val portName: Option[String], val protocol: Option[String]) {
140
  def withPortName(value: String): Lookup
141
  def withProtocol(value: String): Lookup
142
  
143
  // Java API
144
  def getPortName: Optional[String]
145
  def getProtocol: Optional[String]
146
}
147
```
148

149
[Core API](./core-api.md)
150

151
### Discovery Extension System
152

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

155
```scala { .api }
156
final class Discovery extends Extension {
157
  def discovery: ServiceDiscovery
158
  def loadServiceDiscovery(method: String): ServiceDiscovery
159
}
160

161
object Discovery extends ExtensionId[Discovery] {
162
  def apply(system: ActorSystem): Discovery
163
  def get(system: ActorSystem): Discovery
164
  def get(system: ClassicActorSystemProvider): Discovery
165
}
166
```
167

168
[Discovery Extension](./discovery-extension.md)
169

170
### Resolution Data Types
171

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

174
```scala { .api }
175
final class Resolved(val serviceName: String, val addresses: immutable.Seq[ResolvedTarget]) {
176
  // Java API
177
  def getAddresses: java.util.List[ResolvedTarget]
178
}
179

180
final class ResolvedTarget(val host: String, val port: Option[Int], val address: Option[InetAddress]) {
181
  // Java API
182
  def getPort: Optional[Int]
183
  def getAddress: Optional[InetAddress]
184
}
185
```
186

187
[Resolution Types](./resolution-types.md)
188

189
## Types
190

191
```scala { .api }
192
// Exception thrown when lookup times out
193
final class DiscoveryTimeoutException(reason: String) extends RuntimeException(reason)
194

195
// Factory methods for creating Lookup instances
196
object Lookup {
197
  def apply(serviceName: String): Lookup
198
  def apply(serviceName: String, portName: Option[String], protocol: Option[String]): Lookup
199
  def create(serviceName: String): Lookup  // Java API
200
  def parseSrv(str: String): Lookup
201
  def isValidSrv(srv: String): Boolean
202
}
203

204
// Factory methods for creating result types
205
object ServiceDiscovery {
206
  object Resolved {
207
    def apply(serviceName: String, addresses: immutable.Seq[ResolvedTarget]): Resolved
208
  }
209
  
210
  object ResolvedTarget {
211
    def apply(host: String, port: Option[Int], address: Option[InetAddress]): ResolvedTarget
212
  }
213
}
214
```