Сериализация: оптимизация proto

Прежде чем что-то оптимизировать, посмотрим, что мы оптимизируем. Документация protobuf.dev по кодированию начинается с определения: «A protocol buffer message is a series of key-value pairs» — сообщение на проводе это серия пар ключ-значение, и дальше — самое важное предложение темы: «The binary version of a message just uses the field's number as the key – the name and declared type for each field can only be determined on the decoding end by referencing the message type's definition». В байтах нет ни имён полей, ни типов: есть номер поля, номер wire type и payload. Имя, тип и всё остальное живёт только в схеме, которую обе стороны обязаны держать согласованной — этим, кстати, занимается кодогенерация из третьего урока, раскладывая дескрипторы в сгенерированные пакеты. Каждая пара кодируется как запись из номера поля, wire type и полезной нагрузки, и «The wire type tells the parser how big the payload after it is. This allows old parsers to skip over new fields they don't understand» — вот фундамент всей совместимости: парсер, не знающий поля, всё равно знает, сколько байт пропустить. Схему называют Tag-Length-Value: «This type of scheme is sometimes called Tag-Length-Value, or TLV». Отсюда два практических вывода, ради которых и существует оптимизация protobuf. Первый: на проводе правит бал номер поля — менять его нельзя, а переименовывать можно почти безнаказанно, что перевернёт ваш взгляд на эволюцию схем ниже. Второй: размер сообщения зависит не от объявления, а от значений и номеров — «разжиревший» int64 в поле номер 30 дороже аккуратного значения в поле номер 3. Подглядывать за байтами удобно тем же grpcurl из восемнадцатого урока: он, правда, показывает вам JSON и дескрипторы, а не сырые байты, но именно сырые байты мы сейчас разберём руками.

Ключ каждой записи — это varint, собранный из номера поля и wire type: «encoded as a varint formed from the field number and the wire type via the formula (field_number << 3) | wire_type». Разбор обратный: «the low 3 bits tell us the wire type, and the rest of the integer tells us the field number» — младшие три бита это wire type, остальное номер. Проверьте на двух знакомых байтах. Первый байт сообщения из схемы message Test1 { int32 a = 1; } — 0x08: двоичное 00001000, младшие три бита 000 — VARINT, сдвиг вправо даёт номер 1. Для message Test2 { string b = 2; } тег — 0x12: двоичное 00010010, младшие биты 010 — это LEN, номер 2. Отсюда следствие, с которого начинается любая оптимизация proto: чем меньше номер, тем короче тег. «You should use the field numbers 1 through 15 for the most-frequently-set fields» — документ прямо советует отдавать диапазон 1–15 самым часто заполняемым полям, потому что «Lower field number values take less space in the wire format»: номера 1–15 кодируются тегом в один байт, 16–2047 — в два. Диапазон номеров ограничен 536 870 911, потому что «The field number is limited to 29 bits rather than 32 bits because three bits are used to specify the field's wire format». И есть запрещённая зона посередине: «Field numbers 19,000 to 19,999 are reserved for the Protocol Buffers implementation» — «The protocol buffer compiler will complain if you use one of these reserved field numbers in your message», protoc отвергнет такую схему на компиляции. Каноничным для нас остаётся Order из второго урока: id = 1, items = 2 — как раз в дешёвом диапазоне.

VARINT — самый частый тип на проводе, и «Variable-width integers, or varints, are at the core of the wire format. They allow encoding unsigned 64-bit integers using anywhere between one and ten bytes, with small values using fewer bytes». Устройство простое: «Each byte in the varint has a continuation bit that indicates if the byte that follows it is part of the varint. This is the most significant bit (MSB)» — старший бит байта это продолжение, остальные семь бит — полезная нагрузка, и «These 7-bit payloads are in little-endian order» — семибитные группы склеиваются младшими вперёд. Классический пример из доки: значение 150 для поля a = 1 едет тремя байтами 08 96 01. Тег 0x08 мы разобрали; varint 96 01 раскладывается так: 10010110 00000001, у первого байта MSB установлен — есть продолжение; сбрасываем биты продолжения, получаем 0010110 и 0000001, разворачиваем в big-endian: 00000010010110 — это 128 + 16 + 4 + 2 = 150. Обратите внимание на цену: 150 стоит одного байта varint, но 1 000 000 — уже трёх, 2^31 и больше — пяти, а почти любое большое 64-битное — всех десяти. Отсюда главное правило варинт-экономии: размер зависит от значений, а не от объявления. Есть и обратная сторона sparseness: «Missing fields are easy to encode: we just leave out the record if it's not present» — незаполненное поле не едет вовсе, поэтому «huge»-прото с горой объявленных полей и парой заполненных на проводе компактнее, чем выглядит в схеме. Bool живёт в VARINT и всегда кодируется ровно одним байтом 00 или 01 — промежуточных значений у него нет.

Здесь новички платят самую дорогую цену. Для обычных int32 и int64 документ говорит жёстко: «The intN types encode negative numbers as two's complement, which means that, as unsigned, 64-bit integers, they have their highest bit set. As a result, this means that all ten bytes must be used» — отрицательное значение превращается в 64-битное дополнительное с выставленным старшим битом, и varint вынужден тащить все десять байт. Двести пятьдесят байт на сотню отрицательных температур — это не шутка, а реальный профиль трафика. Лечится специальной парой типов: «sintN uses the ZigZag encoding instead of two's complement to encode negative integers» — положительные значения переходят в чётные, отрицательные в нечётные: «Positive integers p are encoded as 2 p (the even numbers), while negative integers n are encoded as 2 |n| - 1 (the odd numbers)». Таблица отражения: 0 → 0, -1 → 1, 1 → 2, -2 → 3, 2147483647 → 4294967294, -2147483648 → 4294967295; формулы — (n << 1) ^ (n >> 31) для sint32 и (n << 1) ^ (n >> 63) для 64-битной версии. В protoscope из доки -500 помечается суффиксом z и равняется varint 999. Итог: -1 в sint32 стоит один байт, в int32 — десять. Когда ширина важнее знака, есть второй путь — fixed: fixed64, sfixed64 и double всегда занимают восемь байт (wire type I64), fixed32, sfixed32 и float — четыре (wire type I32); для координат, хэшей и денежных сумм с плавающей точкой фиксированная ширина честнее varint-roulette.

Всё остальное на проводе — length-delimited. «The LEN wire type has a dynamic length, specified by a varint immediately after the tag, which is followed by the payload as usual» — тег, varint-длина, payload. Пример из доки: строка testing для поля b = 2 — это 12 07 74 65 73 74 69 6e 67: тег 0x12, длина 7, семь байт UTF-8; «The int32 varint means that the max length of a string is 2GB» — отсюда же потолок в 2 ГиБ на сериализованное сообщение. bytes кодируется так же. Вложенные сообщения — тоже LEN: для message Test3 { Test1 c = 3; } со значением c.a = 150 на проводе лежит 1a 03 08 96 01 — тег поля 3, длина 3, внутри ровно те три байта из первого примера. Заметьте цену вложенности: каждый уровень добавляет свой тег и свою длину — глубокая иерархия мелких сообщений раздувает трафик сильнее плоской схемы. repeated-поля чисел в proto3 кодируются packed по умолчанию: вместо записи на элемент — «encoded as a single LEN record that contains each element concatenated» — один LEN-рекорд с конкатенацией значений. При этом порядок записей не важен: записи одного repeated-поля могут перемежаться другими полями, и «only the order of records for the same field with respect to each other is preserved». Парсеры обязаны понимать обе формы — packed и по-элементную — «This permits adding [packed=true] to existing fields in a forward- and backward-compatible way», ещё один пример того, как формат прощает эволюцию.

Теперь правила эволюции — то, ради чего бинарный формат вскрывали. Поле больше не нужно: удаляйте спокойно, но с одним обязательным жестом. Документ proto3 не оставляет выбора: «you must reserve the deleted field number» — номер удалённого поля обязан попасть в reserved. Почему так строго? Потому что формат не даёт второго шанса: «Reusing a field number makes decoding wire-format messages ambiguous» — декодирование сообщений, записанных одной версией схемы и прочитанных другой, становится неоднозначным, и «The protobuf wire format is lean and doesn't provide a way to detect fields encoded using one definition and decoded using another» — на проводе нет контрольной суммы или сигнатуры, которая поймает подмену. Побегут старые данные мимо нового поля — документ перечисляет последствия по возрастанию боли: потерянные часы отладки, «A parse/merge error (best case scenario)», а дальше — «Leaked PII/SPII» и «Data corruption»: например, старое поле хранило email в LEN-записи, новое поле с тем же номером объявили int32 — парсер прочитает длину как значение, а байты письма молча выбросит или уронит разбор. Синтаксис защиты: reserved 2, 15, 9 to 11; — «Reserved field number ranges are inclusive (9 to 11 is the same as 9, 10, 11)». Номер — не единственное, что стоит заблокировать: «You should also reserve the field name to allow JSON and TextFormat encodings of your message to continue to parse» — имя тоже резервируют — reserved "foo", "bar"; — потому что JSON-кодирование ходит по именам. И жёсткое ограничение языка: «you can't mix field names and field numbers in the same reserved statement» — имена и номера резервируются отдельными строками. protoc проверит оба списка и не даст новому полю занять чужой номер или имя.

Настало время развернуть два термина, которые постоянно путают. Forward compatibility — старый код читает данные новой схемы; backward compatibility — новый код читает данные старой схемы. Протокол даёт оба направления сразу, и механизм уже знаком: «The wire type tells the parser how big the payload after it is. This allows old parsers to skip over new fields they don't understand». Старый клиент встречает незнакомый тег, смотрит на три младших бита и ровно столько байт пропускает, сколько требует тип: VARINT — до байта без MSB, LEN — читает varint длины и отматывает её, I32/I64 — отматывает 4/8 байта. Документ proto3 подтверждает: «Adding new fields is safe ... old binaries simply ignore the new field when parsing» — добавление полей безопасно в обе стороны, значения незнакомых полей примут дефолты. Зеркально про номера: «Changing the field number is equivalent to deleting the field and adding a new field with the same type» — смена номера это не перенос, а удаление плюс новое поле, поэтому смена номеров живых полей — «Changing field numbers for any existing field is not safe». Причём unknown fields не выбрасываются: парсер сохраняет их в сообщении и возвращает на провод при ре-сериализации — цепочка прокси из старых версий не теряет новые данные. Есть и обратная сторона честности: дефолты неотличимы от пустых значений, поэтому старый код, читающий новое сообщение, видит нули там, где новый код видит данные. Наконец, правило Last One Wins: «if the same field appears multiple times, the parser accepts the last value it sees» — дубликат скаляра перезаписывается последним значением, дубликаты вложенных сообщений мержатся, а разбор конкатенации двух сообщений эквивалентен разбору по очереди с merge — удобное свойство для стриминга и логов.

Во втором уроке в схеме Order уже мелькнуло optional string promo_code = 4; — теперь разберём, что это значит на проводе. У обычного (implicit) скалярного поля proto3 присутствия нет: нулевое значение не кодируется вовсе, и set-ли вы его или нет, на проводе не отличишь. Поле optional включает явное присутствие: «An optional field is in one of two possible states: the field is set, and contains a value that was explicitly set or parsed from the wire. It will be serialized to the wire» — либо unset, тогда возвращается дефолт и на провод ничего не едет; главное — «You can check to see if the value was explicitly set». В Go это делает поле указателем — PromoCode *string — и хаззеры GetPromoCode/HasPromoCode в сгенерированном коде. История версии: «Presence tracking for proto3 messages is enabled by default since v3.15.0 release», а до 3.12.0 требовался флаг --experimental_allow_proto3_optional; свежий protoc просто принимает optional. Зачем платить указателем? Разница проявляется в круглых поездках: «The serialized value following implicit presence discipline does not contain the default value, even though it was explicitly set» — клиент с implicit-полем, получив explicit-значение 0, потеряет факт «было ноль», и документ показывает, как assert на has после такого round trip падает. Поэтому рекомендация синтаксиса прямая: «optional is recommended over implicit fields for maximum compatibility with protobuf editions and proto2» — тот же механизм presence даёт и oneof из второго урока, поэтому различать «не задано» и «задано пусто» можно без своих флагов-костылей.

Каждое protobuf-сообщение внутри gRPC едет не голым, а в пятибайтовой рамке: один байт — флаг сжатия, четыре байта — длина big-endian. В исходниках rpc_util.go это буквально: «The format of the payload: compressed or not?», тип payloadFormat, где compressionNone = 0 и compressionMade = 1 — единица в первом байте значит, что содержимое сжато кодеком, названным в заголовке grpc-encoding. Сжатие gzip в gRPC собирается из трёх деталей. Первая — регистрация кодека: предпочтительный способ — encoding.RegisterCompressor, и для gzip он уже написан за вас: пакет gzip «implements and registers the gzip compressor» — достаточно импортировать google.golang.org/grpc/encoding/gzip, init() зарегистрирует кодек сам; имя фиксировано константой Name со значением «gzip», и пакет честно помечен: «This package is EXPERIMENTAL and may be changed or removed in a later release». Вторая — выбор кодека клиентом: CallOption grpc.UseCompressor(gzip.Name) — док говорит, что он «sets the compressor used when sending the request», а через WithDefaultCallOptions становится дефолтом всех вызовов канала. Если кодек не установлен, клиент не пойдёт в сеть: «If UseCompressor is used and the corresponding compressor has not been installed, an Internal error will be returned to the application before the RPC is sent»; имя, которого нет в реестре, даёт InvalidArgument с текстом «grpc: compressor %q is not registered». Третья — сервер: «registered compressors will be used automatically to decode request messages and encode the responses», и правило симметрии: «Servers currently always respond using the same compression method specified by the client» — сжатый запрос получает сжатый ответ; кодека нет у сервера — «an Unimplemented status will be returned to the client». Форсировать кодек ответа можно grpc.SetSendCompressor(ctx, gzip.Name) внутри хендлера — «SetSendCompressor sets a compressor for outbound messages from the server», — но только если клиент заявлял кодек в grpc-accept-encoding — «compressor name must exist in the client advertised compressor names sent in grpc-accept-encoding header»; базовое правило остаётся прежним: «By default, server messages will be sent using the same compressor with which request messages were sent». Уровень сжатия настраивает gzip.SetLevel — но он «must only be called during initialization time (i.e. in an init() function), and is not thread-safe», и «gzip.HuffmanOnly is not supported».

Сжатие экономит байты, но у gRPC есть жёсткий потолок на каждое входящее сообщение. В server.go константа defaultServerMaxReceiveMessageSize = 1024 1024 4 — четыре мегабайта; столько же стоит и у клиента, defaultClientMaxReceiveMessageSize. Превышение ловится в парсере рамки: «grpc: received message larger than max (%d vs. %d)» со статусом ResourceExhausted — цифры в тексте это фактическая длина рамки и текущий потолок. Сжатие не спасает от лимита: длина в рамке — это размер сжатого payload, но grpc-go ограничивает и результат декомпрессии — декомпрессор режет распакованный поток на границе maxMessageSize+1, чтобы поймать превышение (doWithMaxSize в rpc_util.go). Свой потолок и у protobuf: «Protos must be smaller than 2 GiB when serialized» — varint-префикс длины LEN-записей шире не даёт. Теперь про порядок: «Field numbers may be declared in any order in a .proto file. The order chosen has no effect on how the messages are serialized» — перестановка полей в объявлении не меняет размер, писать «горячие поля первыми» для скорости сериализации бессмысленно; выгоден только номер — 1–15 дешевле тегом. И важное предостережение: «Serialization order is an implementation detail», «Do not assume the byte output of a serialized message is stable», по умолчанию «the default serialization is not deterministic» — хэшировать байты сериализации, сравнивать их или класть в БД как канонические нельзя; детерминированная сериализация гарантируется только внутри конкретной сборки. Всё это — ручки, которые крутим дальше: «двадцать второй урок — производительность и тюнинг: keepalive, message size, компрессия» — разберёт MaxReceiveMessageSize и буферные пулы по-настоящему.

Честная оговорка про формат, одна на урок: в самоучителе есть песочница с интерпретатором Go, но сеть в браузере недоступна — protoc, gRPC-сервер и grpcurl в браузере не запустить, поэтому runner-ов в этом уроке, как и во всём gRPC-курсе, нет; каждое упражнение делается локально за несколько минут. Три эксперимента. Первый: соберите сервер и клиент из четвёртого и пятого уроков, сериализуйте Order с id = 150 и hexdump-ните тело ответа — найдите те самые 08 96 01, затем поменяйте значение на 200000 и пересчитайте varint руками. Второй: добавьте gzip-кодек в клиент из этого урока и не импортируйте его на сервере — GetOrder вернёт Unimplemented; добавьте blank-импорт на сервер и убедитесь, что ответ снова приходит, а сниффер показывает grpc-encoding: gzip в обоих направлениях. Третий: удалите поле из схемы, поставьте reserved, перегенерируйте код и убедитесь, что старый бинарник клиента читает ответы нового сервера без ошибок, а protoc отвергает попытку занять зарезервированный номер. Дальше по маршруту: двадцатый урок — версионирование API: там «эволюция схем» поднимается с уровня формата на уровень организации кода — пакеты и версии proto-схем в одном сервисе, несколько версий одного API без вилок в коде; сегодняшняя матрица изменений станет его словарём. Перед этим освежите синтаксис proto3 из второго урока — номера полей, enum и oneof — и рефлексию из восемнадцатого — describe покажет живую схему после каждой эволюции. Полный маршрут курса — на странице gRPC-Go.