Implement wire protocol message types and frame encoding layer
Define the complete set of protocol messages shared between client and
server in pwr-core. The MessageType enum assigns stable 1-byte
discriminants to each message variant for routing in the frame header.
Handshake messages carry 32-byte client and server nonces with
HMAC-SHA256 proofs for mutual PSK authentication, plus a server
version string and optional error reason for debugging failed handshakes.
Archive flow messages coordinate project uploads: ArchiveRequest
announces the project UUID, name, total size, file count, and compression
flag; ArchiveAccept returns a session UUID for correlating subsequent
chunks; ArchiveComplete reports the final SHA-256 hash and transfer size.
Restore flow mirrors this with RestoreRequest, RestoreAccept (carrying
size and hash so the client can pre-allocate), and RestoreComplete.
File streaming uses FileHeader (relative path, size, Unix mode bits) sent
before raw chunk data and FileEnd (SHA-256 checksum) sent after. Query
messages provide StatusRequest with optional project UUID filter and
StatusResponse with a ProjectInfo vector carrying UUID, name, size, file
count, and timestamps.
The frame module implements a 10-byte header format: 4 magic bytes
(0x50575246, ASCII “PWRF”), 4-byte big-endian payload length, 1-byte
protocol version, and 1-byte message type. Payloads are JSON-encoded for
debuggability. encode_frame serializes and wraps a message; decode_frame
validates magic, version, and length bounds, returning None when more
data is needed. FrameDecoder maintains an internal buffer for incremental
socket reads. File chunks use a separate 4-byte length-prefixed streaming
format with a zero-length EOF marker, keeping large file data out of the
JSON framing layer.
Thirteen tests cover message type discriminants, serialization round-trips
for ArchiveRequest and ProjectInfo, handshake nonce sizes, frame
encode-decode with magic verification, partial-read buffering in
FrameDecoder, oversized frame rejection, bad magic rejection, file chunk
encode-decode, and EOF marker detection.
Comments 0
No comments yet. Be the first!
Sign in to join the conversation.