Перейти к основному содержимому

ADR-001: Сервисные пакеты

Статус: Принято

Дата: 2025-09-22

Зачем​

Нам нужны сигналы управляющего уровня (например, сброс сессии), которые однозначны, парсятся без аллокаций и обратно совместимы.

Решение​

Сосуществуют две кодировки:

  • Legacy:

    [type]        // 1 байт

    Сохранена для обратной совместимости (в настоящее время только SessionReset).

  • V1 с фреймом:

    0xFF 0x01 [type]   // 3 байта: префикс, версия, тип

    Обеспечивает версионирование для будущего развития.

Обнаружение (строгое)​

Пакет является сервисным тогда и только тогда, когда:

  • len==1 и type известен (legacy), или
  • len==3 и байты равны 0xFF 0x01 <известный-тип> (v1). Всё остальное не является сервисным пакетом.

API​

package service

type PacketType uint8
const (
	Unknown PacketType = iota
	SessionReset
)

type PacketHandler interface {
    TryParseType(pkt []byte) (PacketType, bool)               // zero-alloc
    EncodeLegacy(t PacketType, buffer []byte) ([]byte, error) // zero-alloc: buffer предварительно выделен
    EncodeV1(t PacketType, buffer []byte) ([]byte, error)     // zero-alloc: buffer предварительно выделен
}

Совместимость и развёртывание​

  • Приём: всегда принимать как legacy, так и v1.
  • Отправка: по умолчанию legacy. После флага функции в рукопожатии (ServicePacketsV1=true) отправлять v1 этому клиенту; иначе сохранять legacy.