Location Service

The Location Service handles component (i.e. Applications, Sequencers, Assemblies, HCDs, and Services) discovery in the distributed TMT software system.

A component’s location information can be used by other components and services to connect to it and use it.

Type definition for location model can be found here.

Creation of Location Service

Pre-requisite

Access token is not necessary for using Location Service query APIs.

If You are using Location Service to unregister a component, you would need to have the authorization Token with correct access role. Documentation on how to fetch access token could be found here.

Examples to create a client for Location Service

Location Service constructor takes optional tokenFactory and optional location server configuration(host/port pair).

Typescript
sourceconst tokenFactory = () => auth.token

const locationServiceWithToken: LocationService = await LocationService({
  tokenFactory
})

const locationService: LocationService = await LocationService()
Async-Await

Note that the examples are using async/await which makes handling of promises more readable.

Usages of Location Service

Type definitions for all methods can be found here.

Listing & Filtering Locations

Location Service provides multiple ways to get list of locations registered in the TMT cluster.

Type definitions for relevant listings methods can be found by following links:

  1. list.
  2. listByPrefix.
  3. listByHostname.
  4. listByComponentType.
  5. listByConnectionType.

Following example showcases the listByComponentType api usage

Typescript
source// valid Component types : HCD, Assembly, Service, Container, Sequencer, SequenceComponent and Machine

const sequencerLocations: Location[] = await locationService.listByComponentType('Sequencer')

const hcdLocations: Location[] = await locationService.listByComponentType('HCD')

const assemblyLocations: Location[] = await locationService.listByComponentType('Assembly')

Resolving Connection

There are two ways to get/fetch a location information of a connection:

  1. Using resolve API
  2. Using find API

Location Service’s resolve API uses Connection a component to resolve the location within some timeout duration. However, find API does not wait to resolve location. If the location is not present, it returns undefined.

Type definitions for both methods can be found by following links:

  1. find.
  2. resolve.
Typescript
source// ConnectionTypes : HttpConnection, AkkaConnection & TcpConnection
// Time unit : seconds, milliseconds, nanoseconds, microseconds, minutes, hours, days

const connection = HttpConnection(new Prefix('ESW', 'component'), 'HCD')

const maybeLocation1: Option<Location> = await locationService.resolve(connection, 10, 'seconds')
if (maybeLocation1) {
  // use maybeLocation inside here
} else {
  // location did not resolved in 10 seconds
}

Unregister a Connection

This is a secure API and takes a type of Connection as an input argument to be unregistered from the Location Service and returns Done once unregistered.

Type definitions for unregister method can be found here

The following example shows unregister method can be called:

Typescript
source// ConnectionTypes : HttpConnection, AkkaConnection & TcpConnection
const done: Done = await locationServiceWithToken.unregister(HttpConnection(new Prefix('ESW', 'component'), 'HCD'))

Tracking Connection

The lifecycle of a connection of interest can be followed using either the track API. The connection update events will be received by the callback provided to this method. This method returns a subscription which can be used to cancel the tracking subscription.

Type definitions for track method can be found here

The following example shows track method can be called:

Typescript
source// a optional callback function
const onErrorCallback = (error: ServiceError) => {
  // do something when error occurs
  // for ex : close connection / cleanup resources
  console.log(error)
}
//optional
const onCloseCallback = () => {
  // do something when connection is closed
  // for ex : reset client-side state
}

const onTrackingEvent = (event: TrackingEvent) => {
  if (event._type === 'LocationRemoved') {
    // do something when connection's location is removed from the location service
  } else if (event._type === 'LocationUpdated') {
    // do something when connection's location is updated from the location service
  }
}
// connection to be tracked
const httpConnection = HttpConnection(new Prefix('ESW', 'component'), 'HCD')

locationService.track(httpConnection)(onTrackingEvent, onErrorCallback, onCloseCallback)
0.4.1