QMail Peek — Group 6, Code 73

Quick reference

Purpose

peek is the non-blocking version of ping. It scans the recipient mailbox directory immediately, returns every .tell2 file whose filesystem modification time is greater than since_timestamp, and then closes the request. Pass 0 to return every tell currently in the inbox.

The server path is selected from the mailbox identity in the request body: QMAIL_MAILBOX_ROOT/{denom_hex}/{serial_number}/inbox/. The request must be sent to the recipient’s beacon RAIDA; other RAIDAs may not have that mailbox coin loaded.

Wire packet

The word header is used carefully on this page. The RAIDA packet header is the 32 plaintext bytes at the front of the TCP packet. The 16-byte challenge/CRC is encrypted with the rest of the request body. raidax groups that challenge with the QMail identity block and calls those first 48 decrypted body bytes qmail_preamble_t.

QMail Peek request packet, bytes on TCP

+-------------------------------+-----------------------------------------+----------------------+
| RAIDA request header           | encrypted request body                  | plaintext terminator |
| 32 bytes                       | 52 bytes                                | 2 bytes              |
+-------------------------------+-----------------------------------------+----------------------+
| command group=6, command=73    | challenge/CRC(16)                       | 3E 3E                |
| encryption type=1              | QMail identity/auth block(32)           |                      |
| body_size=54                   | since_timestamp(4)                      |                      |
| nonce(8)                       |                                         |                      |
+-------------------------------+-----------------------------------------+----------------------+

The header’s body_size field includes the encrypted body bytes and the terminator, so for peek it is always 54 (0x0036) in current rest_core.

Request header (32 bytes, plaintext)

Request body (54 bytes after the RAIDA header)

Decrypted request body layout

+-------------------+--------------------------+---------------------+----------------------+
| challenge/CRC     | QMail identity/auth      | since_timestamp     | terminator           |
| 16 bytes          | 32 bytes                 | 4 bytes             | 2 bytes              |
| encrypted         | encrypted                | encrypted           | plaintext            |
+-------------------+--------------------------+---------------------+----------------------+
| body[0..15]       | body[16..47]             | body[48..51]        | body[52..53]         |
+-------------------+--------------------------+---------------------+----------------------+

raidax names body offsets 0–47 qmail_preamble_t. In the terminology above, the challenge is still body data because it is encrypted with the rest of the body fields.

Response packet

For encryption type 1, the response has the same legacy 32-byte RAIDA header size. If the command returns a tell-list payload, the server encrypts the payload bytes and appends an unencrypted 3E 3E terminator.

QMail Peek response packet, bytes on TCP

+-------------------------------+-----------------------------------------+----------------------+
| RAIDA response header          | encrypted tell-list payload             | plaintext terminator |
| 32 bytes                       | payload_len bytes                       | 2 bytes              |
+-------------------------------+-----------------------------------------+----------------------+
| status, group, body_size       | array header(8)                         | 3E 3E                |
| execution time                 | record 1                                |                      |
| challenge signature            | record 2                                |                      |
|                                | ...                                     |                      |
+-------------------------------+-----------------------------------------+----------------------+

The response header’s 3-byte body size is payload_len + 2. For an empty successful peek, payload_len is 8 and the response body size is 10.

Response header (32 bytes, plaintext)

Tell-list payload (encrypted)

Decrypted tell-list payload

+----------------------+--------------------------------------+--------------------------------+
| Array header          | Tell record 1                        | Tell record 2 ...              |
| 8 bytes               | 64 + (M * 32) + 18 bytes             | variable                       |
+----------------------+--------------------------------------+--------------------------------+

If the inbox directory does not exist or contains no matching files, the server returns STATUS_SUCCESS with an 8-byte all-zero payload (tell_count = 0). That is a successful empty peek.

Tell record structure

Each returned record is the full contents of one .tell2 file. The server does not add a per-record length field. The client must read byte 29 of the 64-byte file header (stripe_count, called M below) and compute the record size:

record_size = 64 + (M * 32) + 18

+-------------------------+-----------------------------+-----------------------------+
| QMail file header        | server location entries      | recipient footer            |
| 64 bytes                 | M entries * 32 bytes         | 18 bytes                    |
+-------------------------+-----------------------------+-----------------------------+

QMail file header (64 bytes)

Server location entry (32 bytes each)

There are M entries immediately after the file header. This structure tells the recipient which RAIDA servers hold the stripes and how to connect to them for download.

Recipient footer (18 bytes)

The beacon appends this footer when writing each recipient’s .tell2 file. A receiver must skip these 18 bytes before parsing the next tell record.

Status codes

The per-coin rate limiter can silently drop excessive requests by closing the connection without a status response.

Common mistakes

Points of confusion

1. Filter is mtime-based. The server compares each .tell2 file’s st_mtime to since_timestamp. It does not compare the timestamp embedded in the tell file header.
2. Tells are deleted on read. A successful peek queues returned files for deletion after directory scanning. Multiple devices sharing one mailbox can race; only the first device receives a given tell.
3. Records are variable length. There is no length prefix per record. Use stripe_count from the file header to compute 64 + M*32 + 18.
4. The response can be capped. The server stops growing the response at its maximum tell response size; remaining tell files stay in the inbox for a later call.
5. peek2 is the active command. The suffix is historical. Group 6 code 73 dispatches to cmd_qmail_peek2.