Transfer file

Transfer file starts a streaming file transfer for the current session. This operation is available only after successful Initialize.

Transport behavior

Request is always a text JSON packet.
Successful transfer flow is a stream where chunk frames are sent as binary frames.

Request

Transfer file uses packet type = 7.

{
  "type": 7,
  "id": 8,
  "filename": "client.dll",
  "resume_at": 0
}

Prop

Type

Response modes

Transfer file does not return one fixed response shape.
Server behavior depends on transfer state:

Server starts streaming and sends frames with the same id.

First stream response frame includes file_size.
Intermediate chunk frames carry file bytes (binary frame).
Successful final frame includes status = Ok, file_checksum, and range_checksum.

If request cannot start transfer (for example file not found, invalid resume_at, not authorized), server sends a regular text JSON response with non-OK status.

If transfer is interrupted after start (for example stop request, quota hit, stream error), server sends metadata with terminal status and ends this stream.

Frame type by situation

Situation	WebSocket frame type	What client receives
Request rejected before streaming starts	Text	One JSON response with non-OK `status` (for example `FileNotFound`, `NotAuthorized`, `FileInvalidResumeOffset`).
Regular streaming chunk	Binary	Metadata JSON + raw chunk bytes in one binary frame.
Stream interrupted after start	Text	Terminal JSON metadata with status like `FileStorageQuotaExceeded`, `FileTransferStopped`, or `InternalServerError`.
Successful stream completion	Binary or Text	Final metadata with `Ok`, `file_checksum`, `range_checksum`; frame is binary if final chunk contains bytes, otherwise text.

Stream metadata (JSON)

Prop

Type

Checksum validation

Client must validate integrity after receiving final Ok frame.

Initialize a streaming SHA-256 hasher before receiving chunks.
For each received chunk payload, append bytes to the hasher in exact receive order.
On final frame, compare hex(sha256(received_stream_bytes)) with range_checksum.
If mismatch occurs, treat transfer as corrupted and reject the file.

file_checksum is the checksum of the full file in storage metadata.

If resume_at = 0, the streamed bytes are the whole file, so your computed SHA-256 should match both range_checksum and file_checksum.
If resume_at > 0, range_checksum validates only the streamed tail (resume_at..EOF).
To validate full file in resume mode, hash local prefix bytes (0..resume_at-1) plus streamed bytes, then compare with file_checksum.

FileChecksumMismatch is client-side

If you use an existing BlazeAuth API client library, just check the final result status and handle FileChecksumMismatch.

If you implement the client library/protocol yourself, you must compute and compare checksums as described above and return/use FileChecksumMismatch when validation fails.

FileChecksumMismatch is not sent by server; it is produced by client-side API implementation.

Binary frame format

When a transfer chunk contains bytes, server sends a binary websocket frame with this exact layout:

4 bytes (uint32, big-endian) with metadata JSON length.

N bytes metadata JSON.

Remaining bytes are raw file chunk payload (chunk_size).

[0..3]        metadata_length (uint32, big-endian)
[4..4+N-1]    metadata JSON
[4+N..end]    file bytes (length == chunk_size)

When a stream step has no binary payload, server sends metadata as a normal text JSON frame.

Behavior notes

The first transfer response frame includes file_size.
Intermediate chunk frames may omit status (equivalent to None).
Successful completion frame contains status = Ok, file_checksum, and range_checksum.
range_checksum is computed for transferred range (resume_at ... end of file), not always for full file.
Error-before-stream responses are regular text JSON packets (no binary payload).
Stream can be stopped by sending Stop file transfer (type = 8) with the same filename.

Transfer-file statuses

Status	Constant	Returned when
`0`	`None`	Intermediate streaming chunk (field may be omitted in metadata).
`1`	`Ok`	Transfer completed successfully.
`3`	`NotAuthorized`	Session is not authorized for file transfer.
`6`	`InternalServerError`	Server failed to process transfer due to an internal error.
`300`	`FileNotFound`	Requested file was not found.
`302`	`FileChecksumMismatch`	Client-side checksum validation failed after transfer. This status is produced by client code and is not sent by server.
`303`	`FileInvalidResumeOffset`	`resume_at` is greater than or equal to file size.
`304`	`FileStorageQuotaExceeded`	Transfer exceeded allowed file transfer/storage quota.
`306`	`FileTransferStopped`	Transfer was explicitly stopped.

Connection-close cases (before/around this usecase)

Transfer file can be interrupted by protocol/session guards:

Close code	Error	When it happens
`4200`	`connection is not initialized`	Request was sent before successful `Initialize`.
`4201`	`rate limit hit`	Global per-session packet rate limit was exceeded.
`4302`	`invalid request body`	Packet body does not match the required schema for this operation.
`4304`	`received unsupported data`	Client sent unsupported frame type (request packets must be text JSON).

Transfer file

On this page