ag-admin/OpenSlides
0
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Client server communication

Browse Source
This commit is contained in:
FinnStutzenstein 2020-03-17 10:45:26 +01:00
parent 4f029d336c
commit e43e46fca7
1 changed files with 53 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
docs/client-server-streaming-communication.txt Normal file
View File

@ -0,0 +1,53 @@
# Documentation for the streaming Client-Server-Protocol
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.
5) 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.