feat: docs on stream requests

DOCS.md

@@ -0,0 +1,88 @@
+
+
+# Stream Requests
+
+Usage:
+
+if you want to send really large payload and doesn't matter if it's json, text
+or raw bytes. You can acknowledge server about that.
+
+## 1. Client sends a packet with additional headers:
+
+```yaml
+headers:
+    data-format: bytes
+    route: /upload-file
+    x-stream: 20000:4096
+payload: -
+```
+
+"x-stream" header defines how much data client wants to send in total and which buffer
+size it will use for each portion of data. These two values are separated with colon.
+Client should also acknowledge server about target type of the data through "data-format" 
+header.
+
+## 2. Server sees the "x-stream" header and sends back a packet
+
+Server informs client and reminds in which format he should send the data through
+"data-format" header
+
+Server informs client how much data it can receive and hold through use of "x-stream"
+header. If server can handle whole amount, then it sends "x-stream: 0" back.
+Otherwise it sends "x-stream: n" where 'n' is amount of bytes that server is able
+to receive. If server doesn't support stream requests on that route or for some 
+reason can't handle that stream it sends "x-stream: -1" indicating an error
+
+```yaml
+headers:
+    x-stream: 0:4096
+    x-stream-key: some_unique_id
+    data-format: bytes
+payload: -
+```
+
+Apart from that, server sends additional header "x-stream-key" that can later be used 
+to try identifying the stream after possible error or break of the connection. 
+This header helps both sides identify the stream and recover from a loss of connection 
+or any other issue. For example server might use that key for identifying the filename 
+in internal database and continue receiving file data.
+
+## 3. Client starts sending raw bytes, without packet serialization
+
+Client should also save the stream key in order to be able to recover.
+
+At this point the server is ready to accept raw data from the "stream". The client 
+should try to send data in portion of buffer size that the server has specified.
+
+## 4. Server waits
+
+After all data has been transferred, the server sends final packet to acknowledge the 
+client about successful transmission.
+
+```yaml
+headers:
+    status: 0       <- Success
+    x-stream-key: same_unique_id
+    x-stream: 0:0
+payload: -
+```
+
+Server sends back a packet containing a "status" header identifying the status of 
+transferring. Additionally it sends the same stream key and "x-stream" header again 
+containing information about how much data didn't arrive. In successful scenario it 
+should equal to "0:0" identifying 0 bytes left.
+
+In case of an error the server might send packet in following schema:
+
+```yaml
+headers:
+    status: non-zero
+    x-stream-key: same_unique_id
+    x-stream: 377:0
+payload: -
+```
+
+To identify if request wasn't successful, the server will send a "status" header 
+that will contain "non-zero" error number and "x-stream" header containing the amount 
+of bytes that didn't arrive due to specific issues, e.g. running out of the storage.
+