Architecture - OpenSlides/OpenSlides GitHub Wiki

The figure above gives a quick glance on the service existing and how they communicate with each other.

0. Notation Special words with a definied meaning are surrounded by underscores. E.g. the word request would be the unique term for the http-message send form the client to the server.

1. What? This document provides the specification for the unidirectional server to client streaming. This is realized with HTTP1.1 streaming responses. The general pattern starts with an initial request form the client to a streaming endpoint. The server can send packets of data to the client whenever the server wants to. The connection stays open, until one side closes it manually.

2. Production usage To keep the amount of tcp connections, connection establishments and the associated overhead low, it is advised to ensure HTTP2 in production to make use out of tcp multiplexing. All streaming (and other non-streaming) content is multiplexed through a single tcp connection.

3. Request meta information The method, headers and payload of the initiating request are arbitrary and not bounded to an restriction. The response content type header must be set to application/octet-stream to avoid unwanted buffering in some browsers. Otherwise all other headers are free to choose. If errors happen before the response was send, the response status code can be a non-200 one.

4. Message format: Packets The server sends JSON objects (with an object as the outer most JSON-object) as the content of a package. So one package contains one JSON object. The content is terminated with a line feed (0x0A). The terminated content is the payload, which is send over the connection. It must be taken care of not sending prettified JSON, to not include any unwanted line feeds and to not send unnecessary bytes. To clearify, the terminating line feed must be the only line feed in the payload. Note that linefeeds must be escaped in JSON-strings (see RFC 7159).

5. Errors If an error happen in an established connection, the status code can not be altered. To indicate errors, the following convention is used: To send an error to the client, send a JSON-object with the single key error with an object as value (e.g. {"error": {"detail": "Failed successfully"}}`). The server must close the connection afterwards, because the client cannot react to the error. For normal packets, it is forbidden to send content with an error key in the outer most JSON-object.

6. Outlook There might be an additional reserved keys. The protocol may be extended to:

• a watchdog: the server sends a ping in regular time intervals. The client take note of them and notices, if there was a missing ping. E.g. the timeout for the client is twice the send interval time. If a missing ping was detected, the connection is reestablished.