ByteBox/1 frame: 20 bytes по offsets

Что показывает схема

ByteBox/1 header всегда занимает ровно 20 bytes. Его layout frozen как struct.Struct("!4sBBHIII"): четыре raw magic bytes, два one-byte fields, один big-endian uint16 и три big-endian uint32. Символ ! одновременно задаёт network byte order и отсутствие native padding в нормативном Python notation.

Payload начинается только с offset 20 и имеет длину из header. Он binary-safe: NUL внутри content допустим, поэтому strlen, %s и поиск terminator неприменимы. Максимальная payload length — 65536.

Таблица offsets

Почему нельзя cast к C struct

Native compiler может вставить padding, потребовать alignment и хранить integers в host byte order. Даже pragma pack решает только padding, но не byte order и не безопасный unaligned access. Надёжный decoder читает raw[20], проверяет наличие всех bytes, затем извлекает fields по offsets. Fixed-width values копируются через memcpy в выровненные uint16_t/uint32_t и переводятся ntohs/ntohl. Encoder делает обратное с htons/htonl.

Порядок validation

1. Получить ровно 20 header bytes или классифицировать EOF.
2. Проверить magic BTBX.
3. Декодировать fixed-width fields.
4. Проверить version 1.
5. Проверить payload_len <= 65536.
6. Прочитать ровно bounded payload.
7. Проверить CRC-32/ISO-HDLC payload.
8. Проверить request_id, status, opcode и payload schema.
9. Только затем dispatch LIST/GET.

Порядок нужен для safety и синхронизации stream parser. Oversized declaration получает ERROR/FRAME_TOO_LARGE и close без body read. CRC mismatch получает ERROR/BAD_CHECKSUM и close после bounded read.

Сценарии и prediction

Перед запуском посчитайте frame size для empty LIST: 20 bytes. Для GET hello.txt payload содержит big-endian name_len 9 и девять ASCII bytes, поэтому request frame содержит 20-byte header плюс 11-byte payload. Это размер ByteBox frame; TCP может доставить его любым числом recv chunks.

Предскажите также outcome для корректного имени missing.bin: server отвечает ровно одним 20-byte ERROR frame, opcode 0xff, status NOT_FOUND=2, echoed request_id, length/CRC zero, без body.

Практика на C и Winsock

Создайте функции decode_header(raw[20], fields), encode_header(fields, raw[20]), recv_exact и send_all. Unit tests должны использовать literal byte vectors, а не encode и decode одной и той же реализацией: иначе симметричная ошибка byte order останется зелёной.

После payload_len check выделяйте не больше 65536 bytes. Для zero length не требуйте non-null body. Сравнивайте вычисленный CRC как uint32_t и кодируйте его на wire через htonl. CRC check value для ASCII 123456789 равен 0xcbf43926, empty — 0.

Частые ошибки

• Считать HEADER_SIZE равным sizeof(native_struct).
• Применить ntohl к one-byte version/opcode или забыть ntohs для status.
• Проверить CRC до получения всего payload.
• Dispatch operation до CRC/schema validation.
• Добавить имя или terminator в GET response body, хотя response содержит только raw object bytes.
• Принять payload_len больше bound и надеяться, что malloc откажет безопасно.

Контрольные вопросы

1. Какие fields меняют byte order между little-endian host и wire?
2. Почему pragma pack недостаточно?
3. В какой момент parser имеет право выделить payload storage?
4. Что должен сделать server после bad magic, oversized length и bad checksum?

Нормативный источник

Сверяйте каждую цифру с docs/curriculum/computer-networks/capstone-bytebox.md и docs/curriculum/computer-networks/harness/bytebox_protocol.py. Любое wire изменение требует ByteBox/2, а не тихой правки harness.