QMail Tell — Group 6, Code 71

Quick reference

Purpose

After uploading the stripes, the sender calls tell on each recipient’s beacon RAIDA. The tell carries a pass-through blob: a 64-byte file header plus M 32-byte server-location entries that tell the recipient where the stripes live. The beacon writes the blob to the recipient’s inbox directory; when the recipient’s ping or peek arrives, the beacon reads back the blob and returns it.

The sender pays a per-recipient inbox fee by attaching a funded locker key to each address entry. The beacon verifies the locker holds at least the recipient’s configured fee before accepting the delivery.

Request body

Preamble (48)
Routing header (48)                       qmail_v2_tell_req_t
N × Address entry (32 each)             qmail_v2_address_entry_t
File header (64)                          qmail_v2_file_header_t (start of blob)
M × Server location (32 each)           pass-through; format defined by client
Terminator (2)                            3E 3E

Server validates: body_size == 48 + 48 + N×32 + 64 + M×32 + 2.

Routing header (48 bytes, offsets 48–95)

Layout matches qmail_v2_tell_req_t:

Address entries (N × 32 bytes)

Layout per recipient matches qmail_v2_address_entry_t. The server iterates the N entries and writes one .tell2 file to each recipient’s inbox.

Notification blob (64 + M × 32 bytes)

The blob is the pass-through payload — the beacon stores it verbatim and the recipient reads it back through ping/peek. The first 64 bytes are the file header (qmail_v2_file_header_t), followed by M 32-byte server-location entries.

File header (64 bytes)

Server location entries (32 bytes each)

The 32-byte format is partially structured (the recipient’s ping parser reads the first three bytes), partially opaque. The rest_core sender writes:

Response

No body. Status only.

Status codes

Server-side delivery

For each accepted recipient the server writes:

Path: /opt/raidax/QMail_Data/mailboxes/{denom_hex}/{sn}/inbox/00000000{GUID_hex}.tell2

Body: pass-through blob (64-byte file header + M×32 server entries)
      followed by a per-recipient footer:

    byte 0       tag = 0x50
    byte 1       length = 16
    bytes 2-17   receiver_locker = sender's locker_payment_key for this recipient

Writes use atomic publish: open a hidden tempfile (.tmp.PID.TIME.SEQ.GUID.tell2) with O_CREAT|O_EXCL, write, fsync, and rename() into the final .tell2 path. The recipient’s long-poll inotify watch fires on IN_MOVED_TO only after the rename, guaranteeing the watcher never sees a partial file. Any .tmp.* orphan from a crashed sender is ignored by the directory scanner because the dotfile prefix.

After delivery, when the recipient’s ping or peek reads the file into the response, the server remove()s the file. Tells are one-shot; once read they are gone.

Common mistakes

Points of confusion

1. The server doesn’t verify file existence. tell just writes the notification blob to the recipient’s inbox; it does not contact the storage RAIDAs to confirm the stripes are actually there. If you call tell before upload finishes, the recipient will be told about a file they cannot download.
2. Inbox-fee verification is permissive on lookup failure. If the beacon’s call to rest_core for the recipient’s inbox fee fails, fee is treated as 0 and the locker check passes. Recipients who haven’t configured a fee in rest_core are effectively free to mail.
3. stripe_type at byte 1 of each server-location entry is doubly-claimed. The current sender writes 0/1 for data/parity. The recipient’s receive code looks for 10..14 on this byte to identify attachment stripes — logic that was added in anticipation of a sender that emits per-(server, file) entries with the file’s file_type. Until the sender is updated, attachment stripes are uploaded but never announced to the recipient.
4. Atomic-publish is recent. Older raidax builds wrote the .tell2 file in place. The current build uses temp+rename so the inotify watcher never sees a partial file. Senders see no behavior change; recipients see a smaller race window.
5. Multiple reserved regions. Three structures in this command have reserved bytes: reserved_1[4] + reserved_2[1] in the routing header, reserved[8] per recipient, and reserved[13] in the file header. The 13-byte file-header region is the most useful for protocol extension because it’s pass-through — whatever the sender writes there is delivered verbatim to the recipient.