QMail Object Begin — Group 6, Code 76

Quick reference

Purpose

Before uploading any bytes, the client declares what it wants to store: total size, hash algorithm, storage class, retention, and whether this is a new object (operation=0, create) or a replacement of an existing one (operation=1, replace). The server reserves exactly total_size physical content bytes in the selected class, attempts payment, and returns an accepted upload chunk size the client should use for subsequent object_put_range calls.

storage_class=0 selects the server default. preferred_chunk=0 selects the server preference; otherwise the server returns an accepted size no larger than the requested size or its configured maximum. requested_retention_seconds is unsigned 64-bit; zero requests the server default. For a nonzero request the server either accepts the exact duration or returns ERROR_RETENTION_UNAVAILABLE — it does not silently shorten paid retention. locker_code carries the existing 16-byte storage-payment marker, the same field used by cmd 70 upload.

Create fails if a live object already exists, requires expected_generation=0, and accepts any nonzero target_generation. Replace requires owner authentication, an exact expected_generation, and target_generation > expected_generation. The server commits exactly the requested target rather than incrementing a local counter, letting a client publish one logical revision across servers whose prior local generations differ after partial failures. A stale expected generation or non-monotonic target returns ERROR_GENERATION_CONFLICT.

Request body

Preamble (48 bytes, offsets 0–47)

Standard QMail preamble. See QMail Overview — Universal preamble.

Common prefix (16 bytes, offsets 48–63)

Every Object Transfer v1 command payload begins with this prefix. See the Object Transfer overview for the shared framing rules.

Begin payload (128 bytes, offsets 64–191)

Total request body length: 16 (challenge) + 32 (identity preamble) + 16 (common prefix) + 128 (begin payload) + 2 (terminator) = 194 bytes.

Response body

Successful response header length: 80 bytes (16-byte common prefix + 64-byte begin response).

Object expiry, when accepted_retention_seconds is nonzero, is committed_at + accepted_retention_seconds using checked arithmetic.

Byte-offset note for parsers: credit_state is at response offset 74, remaining_kb at 75–77, trailing reserved at 78–79. Parsers that require all six trailing bytes (74–79) to be zero must relax that check to the final two bytes (78–79) before enforcement is turned on — see Zero-locker funding & welfare.

Zero-locker funding & welfare

An upload is normally paid for by attaching a funded locker_code (the 16-byte storage-payment marker). To let users store data without first buying and attaching a locker, object_begin also supports an all-zero locker_code (“zero-locker” upload). When the locker is all zeros the server decides how the stripe is funded from server-side balances, and reports the outcome in the response's credit_state and remaining_kb fields. A nonzero locker skips all of this and uses the legacy locker-payment path.

Per-stripe, per-mailbox accounting

Each RAIDA sees only its own stripe of a striped message — never the total message size or the stripe count. All sizes and allowances below are therefore per server, per mailbox (identified by the authenticated denomination + serial number). A message split across N servers is funded independently on each.

Funding precedence

For a zero-locker upload the server tries these in order and stops at the first that succeeds:

credit_state values

remaining_kb is a 3-byte big-endian unsigned integer (KB), saturating at 0xFFFFFF (≈16 GB reported ceiling). The commit response (cmd 79) repurposes its own 3 formerly-reserved trailing bytes to report the mailbox's remaining subscription credit after commit, in the same KB encoding.

Status codes

Idempotency

object_begin is idempotent by owner and Transfer ID. The server durably records the begin attempt before initiating payment. An exact retry — ignoring only the common request_id, which is allowed to change — never reserves capacity or initiates payment twice. While payment is pending it returns ERROR_PAYMENT_PROCESSING; after acceptance it returns the original negotiated values while echoing the retry's request ID. Reusing the same Transfer ID with any different command-specific field returns ERROR_TRANSFER_CONFLICT. An aborted or expired attempt requires a new Transfer ID.

Common mistakes