Client server communication

docs/client-server-streaming-communication.txt

@@ -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.
+