nanover.essd.servicehub module

Module defining a Service.

class nanover.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 NanoVer services include imd, trajectory, multiplayer and builder.

Example

>>> # the ID field is usually autogenerated, provided here for completeness.
>>> hub = ServiceHub(name="Example NanoVer 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 NanoVer 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.

Example

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

property 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) → Tuple[str, int] | None

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.

property id

Gets the unique ID string of this service hub.

Returns:

The unique ID string of this service hub.

property message

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

Returns:

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

property name

The name of the service hub.

Returns:

The name of the service hub.

Raises:

KeyError – if name has not been set.

property services

Gets the services registered at this service hub.

Returns:

Dictionary of service definitions.

to_message(override_address: str | None = 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"}'

property version

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

Returns:

Version string of this service hub.