89 lines
2.9 KiB
Markdown
89 lines
2.9 KiB
Markdown
|
|
|
|
# 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.
|
|
|