Awesome

WebSocket System Handle

Introduction

What is a System Handle?

A System Handle is a plugin that allows a certain middleware or communication protocol to speak the same language used by the eProsima Integration Service, that is, Extensible and Dynamic Topic Types for DDS (xTypes); specifically, Integration Service bases its intercommunication abilities on eProsima's open source implementation for the xTypes protocol, that is, eProsima xTypes.

The WebSocket SystemHandle

This repository contains the source code of Integration Service System Handle for the WebSocket middleware protocol, widely used in the robotics field.

The main purpose of the WebSocket System Handle is that of establishing a connection between a WebSocket application and an application running over a different middleware implementation. This is the classic use-case approach for Integration Service.

Dependencies

This section provides a list of the dependencies needed in order to compile WebSocket System Handle.

OpenSSL: Toolkit for the Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols.
WebSocket++: WebSocket Protocol C++ library implementation.

These libraries can be installed using your Linux distribution package manager with the following command:

sudo apt-get install -y libssl-dev libwebsocketpp-dev

Configuration

Integration Service is configured by means of a YAML configuration file, which specifies the middlewares, topics and/or services involved in the intercommunication process, as well as their topic/service types and the data exchange flow. This configuration file is loaded during runtime, so there is no need to recompile any package before switching to a whole new intercommunication architecture.

To get a more precise idea on how these YAML files have to be filled and which fields they require in order to succesfully configure and launch an Integration Service project, please refer to the dedicated configuration section of the official documentation.

Regarding the WebSocket System Handle, there are several specific parameters which can be configured for the WebSocket middleware. All of these parameters fall as suboptions of the main five sections described in the Configuration chapter of Integration Service repository:

systems: The system type must be websocket_server or websocket_client. In addition to the type and types-from fields, the WebSocket System Handle accepts a wide variety of specific configuration fields, depending on the selected operation mode (Client or Server):

For the websocket_server System Handle, there are two possible configuration scenarios: the former one uses a TLS endpoint, and the latter uses a TCP endpoint.

TLS
```
systems:
  websocket:
    type: websocket_server
    port: 80
    cert: path/to/cert/file.crt
    key: path/to/key/file.key
    authentication:
     policies: [
         { secret: this-is-a-secret, algo: HS256, rules: {example: *regex*} }
     ]
```
TCP
```
systems:
  websocket:
    type: websocket_server
    port: 80
    security: none
    encoding: json
    authentication:
     policies: [
         { secret: this-is-a-secret, algo: HS256, rules: {example: *regex*} }
     ]
```
- port: The specific port where the server will listen for incoming connections. This field is required.
- security: If this field is not present, a secure TLS endpoint will be created. If the special value none is written, a TCP WebSocket server will be set up.
- cert: The X.509 certificate that the server should use. This field is mandatory if security is enabled.
- key: A path to the file containing the public key used to verify credentials with the specified certificate. If security is enabled, this field must exist and must be filled in properly.
- authentication: It is a list of policies. Each policy accepts the following keys:
  - secret: When using MAC (Message Authentication Code) method for verification, this field allows to set the secret used to authenticate the client requesting a connection to the server.
  - pubkey: Path to a file containing a PEM encoded public key.
    
    NOTE: Either a secret or a pubkey is required.
  - rules: List of additional claims that should be checked. It should contain a map with keys corresponding to the claim identifier, and values corresponding to regex patterns that should match the payload's value. In the example above, the rule will check that the payload contains an example claim and that its value contains the regex keyword in any position of the message. This field is optional.
  - algo: The algorithm that should be used for encrypting the connection token. If the incoming token is not encrypted with the same algorithm, it will be discarded. If not specified, the HS256 algorithm will be used.
- encoding: Specifies the protocol, built over JSON, that allows users to exchange useful information between the client and the server, by means of specifying which keys are valid for the JSON sent/received messages and how they should be formatted for the server to accept and process these messages. By default, json encoding is provided in the WebSocket System Handle and used if not specified otherwise. Users can implement their own encoding by implementing the Encoding class.
For the websocket_client System Handle, there are also two possible configuration scenarios: using TLS or TCP.

TLS
```
systems:
  websocket:
    type: websocket_client
    host: localhost
    port: 80
    cert_authorities: [my_cert_authority.ca.crt]
    authentication:
        token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey...
```
TCP
```
systems:
  websocket:
    type: websocket_client
    port: 80
    security: none
    encoding: json
    authentication:
        token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey...
```
- port: The specific port where the client will attempt to establish a connection to a WebSocket server. This field is mandatory.
- host: Address where the WebSocket server is hosted. If not specified, it will use localhost as the default value.
- security: If this field is not present, a secure TLS endpoint will be created. If the special value none is written, a TCP WebSocket client will be set up.
- cert_authorities: List of certificate authorities used to validate the client against the server. This field is optional and only applicable if security is not disabled.
- authentication: allows to specify the public token used to perform the secure authentication process with the server. This field is mandatory.
- encoding: Specifies the protocol, built over JSON, that allows users to exchange useful information between the client and the server, by means of specifying which keys are valid for the JSON sent/received messages and how they should be formatted for the server to accept and process these messages. By default, json encoding is provided in the WebSocket System Handle and used if not specified otherwise. Users can implement their own encoding by implementing the Encoding class.

JSON encoding protocol

In order to communicate with the WebSocket System Handle using the JSON encoding, the messages should follow a specific pattern. This pattern will be different depending on the paradigm used for the connection (pub/sub or client/server) and the communication purpose.

Several fields can be used in those messages, but not all of them are mandatory. All of them will be described in this section, as well as in which cases they are optional:

op: The Operation Code is mandatory in every communication as it specifies the purpose of the message. This field can assume nine different values, which are the ones detailed below.
- advertise: It notifies that there is a new publisher that is going to publish messages on a specific topic. The fields that can be set for this operation are: topic, type and optionally the id.
```
  {"op": "advertise", "topic": "helloworld", "type": "HelloWorld", "id": "1"}
```
- unadvertise: It states that a publisher is not going to publish any more messages on a specific topic. The fields that can be set for this operation are: topic and optionally the id.
```
  {"op": "unadvertise", "topic": "helloworld", "id": "1"}
```
- publish: It identifies a message that wants to be published over a specific topic. The fields that can be set for this operation are: topic and msg.
```
  {"op": "publish", "topic": "helloworld", "msg": {"data": "Hello"}}
```
- subscribe: It notifies that a subscriber wants to receive the messages published under a specific topic. The fields that can be set for this operation are: topic and optionally the id and type.
```
  {"op": "subscribe", "topic": "helloworld", "type": "HelloWorld", "id": "1"}
```
- unsubscribe: It states that a subscriber doesn't want to receive messages from a specific topic anymore. The fields that can be set for this operation are: topic and optionally the id.
```
  {"op": "unsubscribe", "topic": "helloworld", "id": "1"}
```
- call_service: It identifies a message request that wants to be published on a specific service. The fields that can be set for this operation are: service, args and optionally the id.
```
  {"op": "call_service", "service": "hello_serv", "args": {"req": "req"}, "id": "1"}
```
- advertise_service: It notifies that a new server is going to attend to the requests done on a specific service. The fields that can be set for this operation are: request_type, reply_type and service.
```
  {"op": "advertise_service", "service": "hello_serv", "request_type":
   "HelloRequest", "reply_type": "HelloReply"}
```
- unadvertise_service: It states that a server is not going to attend any more the requests done on a specific service. The fields that can be set for this operation are: type and service.
```
  {"op": "unadvertise_service", "service": "hello_serv", "type": "HelloReply"}
```
- service_response: It identifies a message reply that wants to be published as response to a specific request.The fields that can be set for this operation are: service, values and optionally the id.
```
 {"op": "service_response", "service": "hello_serv", "values": {"resp": "resp"},
  "id": "1"}
```
id: Code that identifies the message.
topic: Name that identifies a specific topic.
type: Name of the type that wants to be used for publishing messages on a specific topic.
request_type: Name of the type that wants to be used for the service requests.
reply_type: Name of the type that wants to be used for the service responses.
msg: Message that is going to be published under a specific topic.
service: Name that identifies a specific service.
args: Message that is going to be published under a specific service as a request.
values: Message that is going to be published under a specific service as a response.
result: Value that states if the request has been successful.

Examples

There are several Integration Service examples using the WebSocket System Handle available in the project's main source code repository.

One of these examples, where the WebSocket System Handle takes part in the intercommunication process, is introduced here.

WebSocket - ROS 2 bridge (publisher - subscriber)

In this example, Integration Service uses both the WebSocket Server System Handle and the ROS 2 System Handle to transmit data coming from a WebSocket Client into the ROS 2 data space, so that it can be consumed by a ROS 2 subscriber on the same topic, and viceversa.

The configuration file used by Integration Service for this example can be found here.

For a detailed step by step guide on how to build and test this example, please refer to the dedicated section in the official documentation.

WebSocket service server

In this example, the WebSocket System Handle tackles the task of bridging a WebSocket server with one or more client applications, playing the role of a service server capable of processing incoming requests from several middlewares (DDS, ROS1, ROS2) and producing an appropriate answer for them.

The configuration file used by Integration Service for this example can be found here.

For a detailed step by step guide on how to build and test this example, please refer to the dedicated section in the official documentation.

Compilation flags

Besides the global compilation flags available for the whole Integration Service product suite, there are some specific flags which apply only to the WebSocket System Handle; they are listed below:

BUILD_WEBSOCKET_TESTS: Allows to specifically compile the WebSocket System Handle unitary and integration tests; this is useful to avoid compiling each System Handle's test suite present in the colcon workspace, which is what would happen if using the BUILD_TESTS flag; and thus, minimizing the building time; to use it, after making sure that the WebSocket System Handle is present in the colcon workspace, the following command must be executed:
```
~/is_ws$ colcon build --cmake-args -DBUILD_WEBSOCKET_TESTS=ON
```

Documentation

The official documentation for the WebSocket System Handle is included within the official Integration Service documentation, hosted by Read the Docs, and comprises the following sections:

License

This repository is open-sourced under the Apache-2.0 license. See the LICENSE file for more details.

Getting help

If you need support you can reach us by mail at support@eProsima.com or by phone at +34 91 804 34 48.