С момента последней (и вроде единственной) статьи о brec прошло какое-то время, и мне кажется, что будет полезно лишний раз напомнить о проекте. Даже неожиданно для меня самого он продолжает развиваться. Пусть я пока не могу похвастаться значимым интересом со стороны сообщества, но в паре локальных проектов он уже появился. Да, скорее как эксперимент. Тем даже лучше: можно провести, что называется, полевые испытания.

Кратко напомню, в чем суть. brec - это инструмент для создания бинарного протокола. Две основные сущности - это Block и Payload. Объявляются они максимально просто:

use serde::{Deserialize, Serialize};

#[block]
pub struct MetaBlock {
    pub request_id: u32,
}

#[block]
pub struct PriorityBlock {
    pub level: u8,
}

#[payload(bincode)]
#[derive(Serialize, Deserialize)]
pub struct GreetingPayload {
    pub message: String,
}

#[payload(bincode)]
#[derive(Serialize, Deserialize)]
pub struct BinaryPayload {
    pub tag: String,
    pub compressed: bool,
    pub bytes: Vec<u8>,
    pub status: u16,
}

Все. Теперь можно формировать "сообщение" или, если хотите, "запись", состоящую из 0-255 блоков и опционального Payload. Блоки можно комбинировать свободно: использовать как разные, так и одинаковые, в любом порядке, если это имеет смысл для вашего протокола.

let packet = Packet::new(
    vec![
        Block::MetaBlock(MetaBlock { request_id: 7 }),
        Block::PriorityBlock(PriorityBlock { level: 2 }),
    ],
    Some(Payload::GreetingPayload(GreetingPayload {
        message: "this one carries both blocks and text".to_owned(),
    })),
);

Готовый пакет можно записывать в буфер, отправлять куда нужно и на другом конце декодировать обратно в типизированные структуры.

Описав свои блоки и полезную нагрузку с помощью #[block] и #[payload], brec сделает большую часть рутинной работы:

• создаст глобальное перечисление Block, включающее все варианты блоков;

• создаст глобальное перечисление Payload, включающее все варианты полезной нагрузки;

• добавит к пакету, блокам и payload-данным сигнатуры и CRC-проверки целостности, если вы явно не отключили их атрибутами вроде no_crc;

• создаст тип Packet, который можно использовать для получения бинарного представления пакета и чтения его обратно.

Но одна из особенностей brec в том, что кроме ядра протокола в нем есть набор инструментов для работы с этим протоколом на практике.

Это, в первую очередь, PacketBufReader и Storage. Более подробно об этих "ребятах" можно посмотреть в предыдущей статье, если интересно. Сейчас же я хочу кратко представить новый режим работы, который связан с фичей resilient.

PacketBufReader и так умеет читать "замусоренный" поток: то есть находить пакеты brec внутри массива сторонних данных. Но resilient решает другую задачу - более мягкую эволюцию протокола, когда старый reader встречает новые, еще неизвестные ему блоки или payload-данные.

Представьте, что вы сделали протокол с блоками BlockA, BlockB, BlockC и payload-типами PayloadA, PayloadB. Сообщения в системе могут выглядеть примерно так:

packet: [BlockA, BlockB] + Some(PayloadA)
packet: [BlockA, BlockB] + Some(PayloadB)
packet: [BlockC] + None

Спустя время вы вводите в систему BlockD и PayloadC. В большинстве случаев это приводит к потере совместимости: старый reader уже не может прочитать сообщение с новой сущностью.

packet: [BlockA, BlockB, BlockD] + Some(PayloadA)
packet: [BlockA, BlockB] + Some(PayloadC)

То есть приходится обновлять все компоненты системы почти одновременно. В обычном режиме brec тоже остановится на неизвестной сигнатуре и вернет ошибку.

В режиме resilient поведение меняется: brec пытается прочитать пакет хотя бы в той части, которая известна текущей версии протокола. Неизвестные блоки и неизвестный payload не превращаются в фиктивный UNKNOWN внутри Block или Payload: они пропускаются, а информация о них возвращается отдельно как список Unrecognized в PacketReadStatus.

Упрощенно это выглядит так:

packet: [BlockA, BlockB, BlockD] + Some(PayloadA)
    -> [BlockA, BlockB] + Some(PayloadA), skipped: [BlockD]

packet: [BlockA, BlockB] + Some(PayloadC)
    -> [BlockA, BlockB] + None, skipped: [PayloadC]

И это важная деталь. Если старый компонент не знает новый payload, он не сможет магически обработать его содержимое. Но он может не упасть на чтении всего пакета, сохранить известные блоки, увидеть факт пропуска и принять нормальное решение: проигнорировать запись, отправить ее в отдельный поток, переложить в storage, залогировать несовместимость или обработать только известную индексную часть.

Под капотом для блоков это работает за счет дополнительного поля длины тела блока в resilient-режиме. Когда reader видит неизвестную сигнатуру блока, он все еще может понять, сколько байт нужно пропустить, не зная структуры этого блока. Для payload-данных похожая идея опирается на заголовок: если сигнатура неизвестна, но длина payload корректна и помещается в границы пакета, тело можно пропустить.

При этом resilient не означает "проглотить любую битую запись". Если CRC-проверку не проходит известный блок или известный payload, это остается жесткой ошибкой. Если длина неизвестного блока или payload некорректна, выходит за границы пакета или данных не хватает, это тоже ошибка или NotEnoughData. Фича нужна не для маскировки повреждений, а для forward compatibility: старый код может пережить появление новых типов, если протокол к этому готов.

Где это реально может быть полезно:

• Rolling update сервисов. Новый producer уже пишет дополнительный блок с диагностикой, версией алгоритма или tenant-метаданными, а часть consumer'ов еще работает на старом протоколе. Старые consumer'ы могут продолжить читать известные блоки и известный payload, вместо того чтобы падать на первой новой записи.

• Логи и event storage. В storage годами лежат записи разных версий, а утилиты анализа обновляются не всегда синхронно с producer'ами. Старый CLI или offline-задача может продолжить сканировать поток по известным индексным блокам, даже если новые записи уже содержат расширенные блоки.

• Edge-клиенты и встраиваемые агенты. Не все клиенты можно обновить одновременно. Если сервер начал добавлять новый optional-блок, старый агент не обязан сразу становиться несовместимым со всем потоком.

• Плагины и расширения. Базовый обработчик может понимать основной протокол, а отдельные команды или плагины могут добавлять свои блоки. Без resilient такие расширения легко ломают старые инструменты, которые вообще не обязаны знать о plugin-specific данных.

Есть и обратная сторона: фичу стоит включать осознанно. У нее есть небольшой overhead в wire format для блоков, а проектировать протокол все равно нужно аккуратно. Например, если новая версия переносит критически важный смысл только в новый payload, старый reader честно вернет None для payload, и дальше уже ваша логика должна решить, что делать с такой записью.

Подробнее про resilient лучше читать в документации. Здесь я не хочу утомлять деталями wire format, но главная идея именно такая: неизвестное можно пропустить, известное можно прочитать, поврежденное нельзя выдавать за корректное.

Напоследок скажу, что первые версии brec по производительности я сравнивал с JSON, но позже решился сравнить и с Protobuf/FlatBuffers. Я не претендую на первенство ни в коем случае, но результаты выглядят достойно в ряде сценариев. Например, использование brec как протокола для логирования с последующим быстрым поиском и фильтрацией по блокам - вполне оправданная идея.

Как всегда, призываю поделиться "звездочкой" на GitHub. Для вас это просто клик, а для меня - обратная связь и мотивация не забрасывать проект, а развивать его дальше. Лучи добра и света каждому, кто не пройдет мимо.

Спасибо.