QMail Ping — Group 6, Code 72

Quick reference

Purpose

ping is QMail’s long-poll receive primitive. It scans the recipient mailbox directory for .tell files. If one or more tells exist, the server returns them using the same tell-list payload format as peek. If none exist, it creates the inbox directory if needed, registers an inotify watcher, and leaves the TCP connection open.

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 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 Ping request packet, bytes on TCP

+-------------------------------+-----------------------------------------+----------------------+
| RAIDA request header           | encrypted request body                  | plaintext terminator |
| 32 bytes                       | 48 bytes minimum, 52 from rest_core     | 2 bytes              |
+-------------------------------+-----------------------------------------+----------------------+
| command group=6, command=72    | challenge/CRC(16)                       | 3E 3E                |
| encryption type=1              | QMail identity/auth block(32)           |                      |
| body_size=50 or 54             | optional ignored timestamp(4)           |                      |
| nonce(8)                       |                                         |                      |
+-------------------------------+-----------------------------------------+----------------------+

The current rest_core ping path reuses the same body builder as peek, so it sends body_size = 54 (0x0036). The raidax ping handler only requires 48 + 2 body bytes and ignores any bytes after the QMail identity/auth block.

Request header (32 bytes, plaintext)

Request body (50 bytes minimum, 54 from current rest_core)

Decrypted request body layout

+-------------------+--------------------------+---------------------+----------------------+
| challenge/CRC     | QMail identity/auth      | optional timestamp  | terminator           |
| 16 bytes          | 32 bytes                 | 4 bytes             | 2 bytes              |
| encrypted         | encrypted                | encrypted if sent   | plaintext            |
+-------------------+--------------------------+---------------------+----------------------+
| body[0..15]       | body[16..47]             | body[48..51]        | body[52..53]         |
| required          | required                 | ignored by ping     | required             |
+-------------------+--------------------------+---------------------+----------------------+

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

There are two normal ping outcomes: a tell-list success response when mail is available, or a status-only timeout response when the parked long-poll expires without mail.

QMail Ping success response, bytes on TCP

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

QMail Ping timeout response, current raidax stale-watcher path

+-------------------------------+
| RAIDA response header          |
| 32 bytes                       |
+-------------------------------+
| status=17, body_size=0         |
| no encrypted payload           |
| no terminator                  |
+-------------------------------+

Current raidax sets timeout status to ERROR_UDP_FRAME_TIMEOUT (17, 0x11) when a parked ping watcher goes stale. Some client-side comments and aliases refer to RAIDA_STATUS_TIMEOUT (245, 0xF5); the current server code path shown above is the authoritative behavior.

Response header (32 bytes, plaintext)

Tell-list payload on success (encrypted)

Decrypted tell-list payload

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

Tell record structure

Each returned record is the full contents of one .tell file. The server does not add a per-record length field. For manifest v1 records, the client reads three fields from the 64-byte file header to compute the record size:

• stripe_count (byte 29, called M): number of server-location entries.
• file_count (byte 52, called N) and file_entry_size (byte 53, always 16): together describe the file manifest. The big-endian manifest_len at bytes 54–55 must equal N × file_entry_size.

manifest v1 record_size = 64 + (M * 32) + manifest_len
legacy v0 record_size   = 64 + (M * 32), then optionally skip an 18-byte footer

+-------------------------+-----------------------------+--------------------------------+
| QMail file header        | server location entries      | file manifest entries          |
| 64 bytes                 | M entries * 32 bytes         | N entries * file_entry_size    |
+-------------------------+-----------------------------+--------------------------------+

Current manifest v1 records do not include a trailing footer; the manifest entries are the last bytes of each record. Pre-manifest legacy records have manifest_version=0, no manifest entries, and may have an 18-byte recipient footer on disk (tag 0x50, length 16, recipient locker). A receiver that sees that footer after a legacy record should skip it before parsing the next record.

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.

File manifest entries (N × 16 bytes)

The manifest is the authoritative list of files that belong to this email. The body is listed first with file_type=0x01; attachments follow using sequential file types 0x0A, 0x0B, and so on. The receiver uses original_size when sizing the reassembly buffer so padding bytes are trimmed correctly.

Local REST test calls

These calls use the two-client local setup: client1 is the sender on port 8081 and client2 is the receiver on port 8082. Stop the receiver background beacon if you want this manual ping call to be the process that consumes the Tell.

# Optional: stop client2 background beacon before the sender sends mail
GET http://127.0.0.1:8082/api/qmail/local/beacon/control?action=stop

# Long-poll client2's beacon RAIDA; notifications include manifest_version, file_count, manifest_flags, and files[]
GET http://127.0.0.1:8082/api/qmail/net/beacon/ping?timeout=10

# Download the received email and all manifest-listed attachments
GET http://127.0.0.1:8082/api/qmail/net/messages/download?file_guid=<FILE_GUID>

# Inspect downloaded attachment rows
GET http://127.0.0.1:8082/api/qmail/db/attachments/list?email_id=<FILE_GUID>

Long-poll mechanics

1. Validate the request body length and 3E 3E terminator.
2. Decrypt the body and validate the 16-byte challenge/CRC.
3. Read the mailbox identity from the decrypted body and verify the AN.
4. Scan QMAIL_MAILBOX_ROOT/{denom_hex}/{sn}/inbox/ for .tell files.
5. If one or more tells are found, read them into the tell-list payload, queue them for deletion, and send a success response.
6. If no tells are found, create the inbox directory if needed, register an inotify monitor, set STATE_PING_ACTIVE, and leave the TCP connection open.
7. When a tell file is atomically renamed into the inbox, the watcher dispatches qmail_resume_ping2(), which rescans and sends the success response.
8. If the watcher expires first, current raidax sends a status-only timeout header with status 17 and body size 0.

Status codes

Compatibility note: some rest_core client code comments refer to RAIDA_STATUS_TIMEOUT (245) for clean long-poll timeout. Current raidax source sends 17 on the stale watcher path.

Common mistakes

Points of confusion

1. ping vs peek. ping blocks until a tell arrives or the watcher times out. peek returns immediately and applies since_timestamp.
2. Tells are deleted on read. A successful ping 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 (byte 29) and manifest_len (bytes 54–55) from the file header to compute 64 + M*32 + manifest_len.
4. Timeout currently uses status 17. If a client is only looking for status 245, it may misclassify the current raidax timeout response.