narupa.essd.servicehub module¶

Module defining a Service.

class narupa.essd.servicehub.ServiceHub(**properties)¶

Bases: object

A definition of a ServiceHub that can be discovered or broadcast.

A service hub consists of properties that must at least consist of a name and ip address. The payload can optionally include additional information on the services provided.

Param:	name: The name of the service hub.
Param:	address: The address of the service hub.
Param:	id: The unique ID of the service hub. If not specified, it will be generated.
Param:	essd_version: The version of ESSD this service hub uses. If not specified it will be determined automatically.
Param:	services: Dictionary of service names and their ports. Standard Narupa services include imd, trajectory, multiplayer and builder.

>>> # the ID field is usually autogenerated, provided here for completeness.
>>> hub = ServiceHub(name="Example Narupa Service Hub", address="localhost", id="12345")
>>> hub.add_service("imd", 54322)
>>> hub.add_service("trajectory", 54323)
>>> hub.services
{'imd': 54322, 'trajectory': 54323}
>>> hub.message
'{"name": "Example Narupa Service Hub", "address": "localhost", "id": "12345", "essd_version": "1.0.0", "services": {"imd": 54322, "trajectory": 54323}}'

The IP address of a service can either be a specific IP address of the interface to be broadcast, or it can be one of two special values: localhost or [::].

If localhost is specified, it will be broadcasted as running at 127.0.0.1, which is the usual translation of such a definition.

If [::] is specified, then the appropriate IP address will be broadcast for each interface on the system.

Consider a system with two interfaces, with IP addresses 192.168.1.2 (e.g. ethernet), and 72.34.5.5 (e.g. wireless), and broadcast addresses 192.168.1.255 and 72.34.255.255 respectively. The address [::] is provided. Then the service will be broadcast at as being at 192.168.1.2 on the ethernet network, and as being at 72.34.5.5 on the second network. Thus, a client at on the ethernet network will receive the address 192.168.1.2, which it can route to.

add_service(name, port)¶

Adds a service with the given name and port to the service hub definition.

Parameters:	name – Name of the service port – Port at which the service is running

address¶

The IP address of the service hub.

Returns:	The IP address of the service hub.
Raises:	KeyError – if name has not been set.

classmethod from_json(json_properties)¶

Constructs an instance of ServiceHub from the given json string.

Parameters:	json_properties – The JSON string containing the properties of the ServiceHub
Returns:	An instance of `ServiceHub`

:raises:`KeyError` if the properties do not contain required fields, name and address.

get_service_address(service_name: str) → Optional[Tuple[str, int]]¶: Gets the address and port of a service, if it exists. :param service_name: Service name :return: Tuple consisting of address and port of a service, or None if not found.

id¶

Gets the unique ID string of this service hub.

Returns:	The unique ID string of this service hub.

message¶

Returns the message that represents this service hub as a JSON string.

Returns:	The message representing this service hub, as a JSON string.

name¶

The name of the service hub.

Returns:	The name of the service hub.
Raises:	KeyError – if name has not been set.

services¶

Gets the services registered at this service hub.

Returns:	Dictionary of service definitions.

to_message(override_address: Optional[str] = None) → str¶

Returns the JSON message representing this service hub, with the option to override this address.

Parameters:	override_address – The address to override in the resulting message.
Returns:	JSON message representing this service hub.

When broadcasting services, it is useful to be able to provide human-readable shortcuts for underlying addresses, but clients receiving broadcasting need to know the actual address the service hub is running at.

A typical use case is when using the ‘[::]’ notation for defining a gRPC service, which means it will listen on all interfaces. When it comes to broadcasting, the discovery server will broadcast on all interfaces with the correct address for that interface.

>>> hub = ServiceHub(name='Example', address='[::]', id='12345')
>>> # The resulting message is not particularly useful.
>>> hub.message
'{"name": "Example", "address": "[::]", "id": "12345"}'
>>> # Instead, at transmission, override with an actual address for the target interface.
>>> hub.to_message(override_address="192.168.1.15")
'{"name": "Example", "address": "192.168.1.15", "id": "12345"}'

version¶

Gets the version of ESSD this service hub is compatible with.

Returns:	Version string of this service hub.