54 lines
2.7 KiB
Plaintext
54 lines
2.7 KiB
Plaintext
|
# 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.
|
||
|
|
|