Distributed ROAD Cluster

Introduction

A "ROAD cluster" is a group of ROAD hosts, which share one database. Each host might have different resources and work might be distributed over them for load balancing.

See General Architecture for an overview.

ROAD clients usually connect to one of the cluster's hosts and refer to jobs and resources on that machine. It's also possible for a client to connect to several hosts as required, but usually the client relies on the connected host to forward requests directly to other ROAD hosts as required.

Some clients might connect to only one host, but handle with data or resources which are located on or referring to different hosts.

Here we provide some information which a client developer should know about this topic.

Available Hosts

All hosts sharing one database are connected and build a ROAD cluster. To get to know which hosts there are and about their current state, a client can query for them. See api/hosts.

Each ROAD Service instance updates this information in the database periodically, so clients can assume if they are currently running.

This list is also considered when relaying REST or socket requests. Relaying by the ROAD Service is only targeted to hosts which are registered in the list of available hosts.

Relaying REST Requests

All REST request which only refer to the (common) database will be processed in the same way by any ROAD host in this cluster, so a client can send the request to the host of its choice.

Some requests deal either not (only) with the database or have some other impact, which must be processed on a specific machine.

To make this possible, http relaying is implemented in the ROAD Service. In some cases this is done by an explicit REST parameter "host", in others this is managed by the Service depending on the context.

In general relaying can only be directed to one of the host, which are registered in the available hosts list, which is described above.

See below documentation for relaying on different API interfaces:

api/versions

This API allows to query the current versions of a host's Service and Worker version. See api/programs.

It can be relayed to another host by providing a REST parameter host. Example: <uri>/api/programs/versions?hosts=another.host

api/devices

This API allows to query the currently available audio devices on a machine. See api/devices.

It can be relayed to another host by providing a REST parameter host. Example: <uri>/api/devices?hosts=another.host

api/jobs

This API allows to create and access jobs on a specific machine. See api/jobs.

Receiving jobs data by a query is done with a GET request, which is not relayed.

When an active job is referred to by its alias ("Easy REST interface"), requests to it will be relayed to the responsible host automatically.

Relaying is supported for POST requests by providing a REST parameter “host”. By this a job can be created on another host, where a Worker will be created and started. When a job has been created, the Service sets the data field "ProcessingHost" to its own host name.

Relaying is supported for PUT requests by the content of the “ProcessingHost” field of the job. So an update on a job is always been processed by the host where the job is running. (Updates on finished jobs are not allowed.)

Relaying is supported for DELETE requests by providing a REST parameter “host”. By providing an additional parameter "force" active jobs can be terminated before deleting them. Without this parameter or for inactive jobs deleting is a pure database operation, so relaying makes no difference.

api/schedules

This API allows to create and access schedules, which later control jobs on a specific machine.See api/schedules.

Receiving schedules data by a query is done with a GET request, which is not relayed.

Relaying is supported for POST, PUT and DELETE requests by the content of the "WorkerHost" field of the schedule - but only if the REST parameter "resetOccurrences" is set, because otherwise there's only an update to the database to be done. With this parameter a currently running job may be affected as well as new pending jobs.

If an existing schedule’s WorkerHost is being changed in a PUT request, the update is processed by the old and the new host by relaying accordingly.

Relaying Subscriptions and Notifications

All JobState and live data subscriptions can be relayed by passing a RelayHost parameter. This leads the addressed host to relaying to the other host and routing the notifications in the opposite direction back to the requesting client.

This can be useful if a client has no direct network connection to the target host or might decrease network load because the host-to-host relay connection bundles identical subscriptions and notifications for several clients.