QMail Upload Large Page — Group 6, Code 75

Quick reference

Purpose

Command 70 carries an entire stripe in one request and is limited by the legacy request body-size field. Command 75 allows the sender to split each server-side QMail object into fixed-size pages. Each page is uploaded independently and stored under the same email GUID, file type, and page number.

The client still does the striping, retry tracking, page accounting, and final message metadata. The server stores pages idempotently and does not maintain an upload session.

Request header use

For command 75, the RAIDA request header is interpreted by command group and command code. This command uses a contiguous 32-bit request body length in bytes 10–13 and a 16-bit page number in bytes 14–15.

Request body

The on-wire request body is framed exactly like every other encrypted QMail command:

challenge(16) + [ preamble(32) + command payload(40) + page data(N) ] + terminator(2)

The protocol layer prepends a 16-byte challenge and appends a 2-byte terminator. The challenge and the command region (preamble + command payload + page data) are encrypted with AES-128-CTR; the terminator is sent in the clear. The 32-bit header body length in bytes 10–13 counts the entire body: challenge + command region + terminator (see total below). The offsets in the tables below are relative to the start of the command region (i.e. immediately after the 16-byte challenge), matching command 70's layout.

Preamble (32 bytes, offsets 0–31)

Standard QMail identity preamble (QMAIL_PREAMBLE_SIZE = 32), identical to command 70. See QMail Overview — Universal preamble.

Command payload (40 bytes, offsets 32–71)

Command region length: 32 (preamble) + 40 (payload) + N (page data).

Total body length (bytes 10–13): 16 (challenge) + 32 (preamble) + 40 (payload) + N (page data) + 2 (terminator) = 90 + N. The 32-bit header body length in bytes 10–13 must equal this value exactly. The accounting mirrors command 70's 16-bit field (challenge + command region + terminator); command 75's command region is 2 bytes larger because of the in-body page-number echo.

Validation rules (server)

The Page Data Length field (command payload offsets 68–71) and the header body length (bytes 10–13) are two independent counts that the server MUST cross-check. They are redundant by design: bytes 10–13 bound the read off the socket before decryption; offsets 68–71 are read after decryption and confirm the page size inside the authenticated body.

• Bound before allocate (anti-DoS): parse bytes 10–13 as UNSIGNED. Reject (status 16, ERROR_INVALID_PACKET_LENGTH) if it is 0 or exceeds the per-command maximum (90 + 262144 = 262234 for Phase 1). Never allocate or read more than this cap, regardless of the claimed value.
• Self-consistency: after decrypt, require header_body_length (10-13) == 90 + PageDataLength (68-71) and 1 ≤ PageDataLength ≤ 262144. Reject with status 16 on mismatch.
• Page-number echo: require the in-body page-number echo (offsets 66–67) to equal the cleartext header page number (bytes 14–15). Reject with status 198 (ERROR_INVALID_PARAMETER) on mismatch. This prevents header-only tampering from misfiling a page.
• Terminator: the last two body bytes must be 3E 3E. Reject with status 16 otherwise.
• Sentinel: bytes 22–23 are expected to be 0xFFFF for command 75; the server uses bytes 10–13 as the authoritative length and ignores 22–23 for framing.
• Payment before durable write: validate the locker (read-only, local) before writing the page to disk (see Payment).

Paging rules

• Page number is per server-side stored object. Two different RAIDAs may store objects with the same GUID, file type, and page number.
• Page size is fixed at 256 KiB maximum for Phase 1.
• The final page may be shorter than 256 KiB.
• Uploads are sessionless. The client decides which pages are missing and retries them.
• Storage must be idempotent by GUID + file type + page number + server. Re-uploading the same stored page (identical bytes) must not double-charge and returns success. Re-uploading the same GUID + file type + page number with different bytes is rejected (status 198) — stored page content is never silently overwritten.
• Total page count, original file size, page size, and checksum/hash belong in the Tell manifest and private CBDF meta object, not in clear request header bytes.

On-disk naming contract: command 75 stores each page as the normal command-70 object name plus .p{PAGE}, where {PAGE} is the 5-digit zero-padded decimal page number. Examples: private meta page 0 is 00000000{GUID}.meta.p00000; body page 0 is 00000000{GUID}.qmail.p00000; attachment 1 page 3 is 00000000{GUID}.0.bin.p00003. Current clients normally page large attachments; the command itself is file-type neutral and may be used for larger meta/body objects in a future phase once the receiver advertises support.

Payment

Billing rounds stored data up to 1 MiB units. A sender may provide a locker with more funds than the upload requires; the extra value should remain unconsumed in the sender-controlled locker and can be reused by the sender later. This is escrow, not a server-held account balance.

The server should consume value only for unique pages that are durably stored. If an upload fails before all pages are uploaded, unconsumed locker value remains available to the sender and no refund command is required.

Response

No response body is required. The status byte in the response header indicates whether the page was stored or rejected.

Status codes

Implementation notes