# Introducing Swift Service Discovery **URL:** \ **Category:** iOS Official News\ **Tags:** newsbot, swift\ **Created:** [21 October 2020 19:00 UTC](https://forum.devtalk.com/t/introducing-swift-service-discovery/3326 "2020-10-21T19:00:17Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![NewsBot](https://forum.devtalk.com/user_avatar/forum.devtalk.com/newsbot/32/1114_2.png) [@NewsBot](https://forum.devtalk.com/u/NewsBot)\ **Post date:** [21 October 2020 19:00 UTC](https://forum.devtalk.com/t/introducing-swift-service-discovery/3326/1 "2020-10-21T19:00:17Z")
A new [Swift](https://devtalk.com/swift) blog post/announcement has been posted! > [@](#): > > It is my pleasure to announce a new open source project for the Swift Server ecosystem, [Swift Service Discovery](https://github.com/apple/swift-service-discovery). Service Discovery is a Swift package designed to establish a standard API that can be implemented by various [service discovery](https://en.wikipedia.org/wiki/Service_discovery) backends such as DNS-based, key-value store, etc. > > ## How does it work? > > The Swift Service Discovery package defines the API only, similar to [SwiftLog](https://github.com/apple/swift-log) and [SwiftMetrics](https://github.com/apple/swift-metrics); actual functionalities are provided by backend implementations. > > ### Concepts > > - **Service Identity** : Each service must have a unique identity. `Service` denotes the identity type used in a backend implementation. > - **Service Instance** : A service may have zero or more instances, each of which has an associated location (typically host-port). `Instance` denotes the service instance type used in a backend implementation. > > ### Server Applications > > Application owners need to select a service discovery backend to make querying available. This is done by adding a dependency on the desired backend implementation and instantiating it at the beginning of the program. > > For example, suppose the hypothetical `DNSBasedServiceDiscovery` is chosen as the backend: > > ``` > // 1) Import the service discovery backend package > import DNSBasedServiceDiscovery > > ``` > > To fetch the current list of instances (where `result` is `Result<[Instance], Error>`): > > ``` > serviceDiscovery.lookup(service) { result in > ... > } > > ``` > > To fetch the current list of instances (where `result` is `Result<[Instance], Error>`) AND subscribe to future changes: > > ``` > let cancellationToken = serviceDiscovery.subscribe( > to: service, > onNext: { result in > // This closure gets invoked once at the beginning and > // subsequently each time a change occurs > ... > }, > onComplete: { reason in > // This closure gets invoked when the subscription completes > ... > } > ) > … > > ``` > > `subscribe` returns a `CancellationToken` that can be used to cancel the subscription later on. `onComplete` is a closure that gets invoked when the subscription ends (e.g., when the service discovery instance shuts down) or gets cancelled through the `CancellationToken`. `CompletionReason` can be used to distinguish what led to the completion. > > ### Backend Implementations > > To become a compatible service discovery backend, implementations must conform to the `ServiceDiscovery` protocol which includes two methods: `lookup` and `subscribe`. > > ``` > func lookup( > _ service: Service, > deadline: DispatchTime?, > callback: @escaping (Result<[Instance], Error>) -> Void > ) > > ``` > > `lookup` fetches the current list of instances for the given service and sends it to `callback`. If the service is unknown (e.g., registration is required but it has not been done for the service), then the result should be a `LookupError.unknownService` failure. A deadline should be imposed on when the operation will complete either via `deadline` or a default timeout. > > ``` > func subscribe( > to service: Service, > onNext nextResultHandler: @escaping (Result<[Instance], Error>) -> Void, > onComplete completionHandler: @escaping (CompletionReason) -> Void > ) -> CancellationToken > > ``` > > `subscribe` “pushes” service instances to the `nextResultHandler`: > > - When `subscribe` is first invoked, the caller should receive the current list of instances for the given service. This is essentially the `lookup` result. > - Whenever the given service’s list of instances changes. The backend implementation has full control over how and when its service records get updated, but it must notify `nextResultHandler` when the instances list becomes different from the previous result. > > A new `CancellationToken` is created for each `subscribe` request. If the cancellation token’s `isCancelled` is `true`, the subscription has been cancelled and the backend implementation should cease calling the corresponding `nextResultHandler`. > > The backend implementation must also notify via `completionHandler` when the subscription ends for any reason (e.g., the service discovery instance is shutting down or cancellation is requested through `CancellationToken`), so that the subscriber can submit another `subscribe` request if needed. > > ## Project Status > > This is the beginning of a community-driven open-source project actively seeking contributions. Besides contributing to Swift Service Discovery itself, we need compatible backend implementations that manage service registration and location information for querying. > > ## Getting Involved > > If you are interested in Swift Service Discovery, come and get involved! The [source is available](https://github.com/apple/swift-service-discovery), and we encourage contributions from the open source community. If you have feedback, questions or would like to discuss the project, please feel free to chat on the [Swift forums](https://forums.swift.org/c/server). If you would like to report bugs, please use [the GitHub issue tracker](https://github.com/apple/swift-service-discovery/issues). We look forward to working with you, and helping move the industry forward to a better, safer programming future. Get the full details here: [Swift.org - Introducing Swift Service Discovery](https://swift.org/blog/swift-service-discovery/)