Module ws 

WebSocket transport protocol shared by the server and the browser client.

Both upload and download use the exact same block-transfer engine over a single WebSocket connection per file:

• The sender pipelines fixed-size blocks without waiting for a per-block acknowledgment, so blocks may be sent out of order and throughput is bounded by bandwidth instead of block_size / RTT.
• The receiver verifies every block in real time (CRC32 + bounds) and marks bad blocks with a FRAME_NAK; the sender re-adds those indices to its transfer queue.
• A wave boundary (FRAME_WAVE_DONE) triggers a reconciliation round: the receiver replies with a FRAME_REQ listing every block still not verified, which the sender re-queues and re-sends. This repeats until the receiver has verified all blocks, at which point it sends FRAME_COMPLETE (for downloads the client is the receiver and sends it; for uploads the server is the receiver, commits the file and sends it).

All control commands (handshake, directory listing, metadata) travel over the same WebSocket; nothing uses separate HTTP requests anymore on the client transfer path.

Frame layout

Every frame is [type: u8][payload: ...]. Control frames carry a JSON payload; data frames carry a compact binary payload (see the individual builders/parsers below).

Structs

Block

A decoded FRAME_BLOCK payload.

BlockSet

A compact bitset tracking which blocks the receiver has verified good.

CompleteMessage

The FRAME_COMPLETE payload (receiver → sender).

ErrorMessage

The FRAME_ERROR payload.

Hello

The FRAME_HELLO payload.

ReadyReply

The FRAME_READY payload (server → client).

StartRequest

The FRAME_START payload (client → server).

Enums

TransferKind

Direction of a transfer.

Constants

FRAME_BLOCK

Block payload (binary): [index:u32][crc:u32][raw_len:u32][data].

FRAME_COMPLETE

Receiver completed the transfer (CompleteMessage, JSON).

FRAME_ERROR

Protocol error ({"code","message"}, JSON).

FRAME_HELLO

Client → server handshake ({"protocol","token"}).

FRAME_HELLO_OK

Server → client handshake acknowledgment ({"ok":true}).

FRAME_LIST_REPLY

Server → client directory listing reply ({"path","entries":[...]}).

FRAME_LIST_REQ

Client → server directory listing request ({"path"}).

FRAME_META_REPLY

Server → client file metadata reply ({"path","size","mtime","etag"}).

FRAME_META_REQ

Client → server file metadata request ({"path"}).

FRAME_NAK

Receiver marks a block bad → sender re-queues it (binary [index:u32]).

FRAME_READY

Server → client transfer ready (ReadyReply).

FRAME_REQ

Receiver asks the sender to re-send a set of blocks (binary [count:u32][index:u32 ...]).

FRAME_START

Client → server transfer start (StartRequest).

FRAME_WAVE_DONE

Sender finished a wave of blocks (empty payload).

Functions

block_bounds

The absolute [start, end) byte range of block index.

block_count

The number of blocks covering size bytes at block_size.

block_frame

Build a FRAME_BLOCK frame.

block_offset

The absolute byte offset where block index of a transfer that begins at file offset lands.

control_frame

Build a control frame from a serializable JSON payload.

crc32

CRC32 of a byte slice, used to verify every block in real time.

frame_payload

Strip the type byte and return the payload slice.

frame_type

Read the frame type from the first byte.

missing_blocks

The block indices of size-byte file at block_size that are NOT covered by received ranges — the “transfer queue” a sender seeds on resume so it only retransmits the broken/lost parts.

nak_frame

Build a FRAME_NAK frame for index.

parse_block

Parse a FRAME_BLOCK frame.

parse_control

Parse a control frame’s JSON payload into T.

parse_nak

Parse the block index out of a FRAME_NAK frame.

parse_req

Parse a FRAME_REQ frame into the requested indices.

req_frame

Build a FRAME_REQ frame for a set of indices.

wave_done_frame

A FRAME_WAVE_DONE frame (empty payload).