ByteBox/1: capstone от socket до conformance

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

ByteBox/1 — frozen учебный wire contract поверх TCP. Он связывает почти весь курс в одном наблюдаемом результате: Winsock lifecycle, TCP stream, application framing, network byte order, bounded allocation, checksum, request correlation, concurrent connections и partial I/O.

Server read-only и предоставляет только LIST и GET для фиксированного каталога. На wire нет upload, path traversal, authentication, TLS, compression или custom crypto. Добавить «удобное поле» без смены версии нельзя: instructor harness сравнивает observable bytes и outcomes.

Нормативный frame contract

Каждый request и response начинается ровно с 20 bytes, layout struct.Struct("!4sBBHIII"). Поля: magic BTBX, version 1, one-byte opcode, big-endian status, request_id, payload_len и payload_crc32. MAX_PAYLOAD равен 65536. CRC-32/ISO-HDLC считается только от payload; для empty payload он равен zero.

Request ID выбирает client в диапазоне 1..0xffffffff, а server echo возвращает его в response. LIST=0x01, GET=0x02, LIST_RESPONSE=0x81, GET_RESPONSE=0x82, ERROR=0xff. Success использует status 0; error statuses 1..7 определены нормативной спецификацией.

Компоненты

• Client frame codec создаёт/проверяет header и payload schema; binary payload не измеряется strlen.
• send_all / recv_exact повторяют short I/O до полного значения или terminal outcome.
• Per-connection state хранит independent input/output progress; один slow peer не должен блокировать других.
• Header validator проверяет fixed header до allocation по payload_len.
• Bounded payload/output ограничивают память и queued response bytes.
• Fixed catalog содержит ровно empty.bin, hello.txt, numbers.txt и pattern.bin с нормативными bytes/CRC.

Четыре сценария

1. Valid LIST возвращает четыре entries в ascending raw ASCII order; нормативный LIST payload занимает 82 bytes.
2. Fragmented GET доказывает, что один frame корректно собирается из произвольных TCP chunks.
3. Oversize declaration даёт ERROR/FRAME_TOO_LARGE (status 5), body не читается, allocation по недоверенной длине не выполняется, connection закрывается.
4. Bad checksum даёт ERROR/BAD_CHECKSUM (status 6); operation не выполняется, connection закрывается.

Validation order как safety property

Server сначала читает ровно 20 header bytes, проверяет magic, декодирует fixed-width fields, проверяет version и payload_len <= 65536. Только после этого он читает bounded payload, проверяет CRC, request fields/opcode/schema и выполняет LIST или GET. Такой порядок не является style preference: он исключает allocation по атакующей длине и сохраняет детерминированные harness outcomes.

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

Не приводите raw 20-byte buffer к native C struct. Padding, alignment и host byte order не являются wire contract. Декодируйте offsets явно либо делайте memcpy fixed-width fields в выровненные переменные, затем ntohs/ntohl. Для encode используйте htons/htonl.

recv_exact различает clean EOF до нового frame и truncated EOF после начала header/body. recv()==0 — orderly shutdown, не «пустой packet». send_all повторяет send до полного progress или SOCKET_ERROR. Сохраняйте WSAGetLastError() до logging/cleanup calls.

Семестровый baseline server использует один event-loop thread с select() или WSAPoll(), отдельным state каждой connection, конечным MAX_CLIENTS и bounded pending output. Он обслуживает не менее 16 concurrent connections на classroom reference image. Slow-reader test не разрешает одному client остановить progress остальных.

Evidence и conformance

• unit vectors для encode/decode, network order и CRC, включая empty и 123456789;
• instructor server harness со всеми нормативными scenarios;
• отдельный client interoperability run против независимого server;
• fragmented/coalesced frames, mid-frame disconnect и recovery probes;
• concurrent/slow-reader evidence и resource observation;
• exact commit, compiler/SDK, harness version, command и exit code.

Зелёный server harness необходим, но не доказывает корректность student client или внутренний memory bound. Эти boundaries закрываются отдельными tests, review и resource evidence.

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

• Считать один recv полным frame или один send полностью записанным buffer.
• Выделять payload до проверки MAX_PAYLOAD.
• Использовать packed struct без byte-order conversion.
• Возвращать platform error text или исходный payload в ERROR response.
• Читать произвольный filesystem path вместо frozen catalog.
• Копить неограниченные responses для slow reader.

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

1. Почему server может безопасно ответить на oversized header, но не должен читать объявленный body?
2. Какие outcomes различает recv_exact при EOF?
3. Какой test доказывает, что два complete frames в одном TCP chunk не теряются?
4. Почему CRC не является authentication или encryption?

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

Единственный источник правды: docs/curriculum/computer-networks/capstone-bytebox.md. Исполняемая cross-check поверхность: docs/curriculum/computer-networks/harness/bytebox_protocol.py и harness scenarios.