File transfer

Blazeauth can stream protected files over the existing WebSocket session. The server sends multiple messages for a single transfer_file request.

Operations involved

• get_file_metadata (optional): check size/checksum/transfer stats before downloading.
• transfer_file: start streaming the file.
• stop_file_transfer: stop an active stream (optionally get a resume token).
• resume_file_transfer: resume from a resume token.

Authorization requirement

transfer_file, stop_file_transfer and resume_file_transfer require the session to be authorized.

Streaming model

When you send transfer_file, the server starts a stream and sends a sequence of chunks that share the same payload.id (your request id).

For each chunk, the server sends two WebSocket messages:

1. A JSON message with the TransferFileResponse payload.
2. A binary WebSocket frame containing the file bytes for this chunk.

The TransferFileResponse.chunk_size value tells you how many bytes to read from the binary frame.

If chunk_size is 0, the server sends only the JSON message.

Fields in TransferFileResponse

Chunk size

Chunk size is determined by the server and depends on the transport frame limit. Do not assume a fixed chunk size.

Terminal statuses

• ok (1): end of stream. The final chunk is included and the JSON header also includes file_checksum and range_checksum.
• file_transfer_stopped (308): stream was stopped by stop_file_transfer.
• file_storage_quota_exceeded (304): transfer exceeded plan quota; stream is aborted.
• internal_server_error (6): unexpected server error; stream is aborted.

Non-terminal chunks

For full-size chunks (all chunks except the last one), the server uses status = none (0) and omits it from JSON.

Stopping and resuming

Stop without resume

Send stop_file_transfer with issue_token = false.

• The active stream emits a terminal streamed message with status = file_transfer_stopped.
• The stop_file_transfer response itself returns status = ok.

Stop with resume token

Send stop_file_transfer with issue_token = true.

• The response includes a resume_token.
• Later, send resume_file_transfer with that token. The server continues streaming from the stored offset.

Notes:

• Ordering is not guaranteed between the stop_file_transfer response and the terminal streamed file_transfer_stopped message. Treat them as independent and correlate by id.
• Resume tokens are server-side objects. If a resumed transfer completes successfully, the token is deleted.

Client-side recommendations

• Treat the stream as: JSON header → binary bytes repeated until a terminal status is received.
• If you support resume, persist the received byte count and validate range_checksum at the end.
• Always handle chunk_size = 0 (terminal errors and stop notifications can be JSON-only).