hsp.go/DOCS.md

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:

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

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.

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:

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.