Pular para o conteúdo principal

ADR-001: Pacotes de Serviço

Status: Aceito

Data: 2025-09-22

Por quê​

Precisamos de sinais do plano de controle (ex.: reset de sessão) que sejam inequívocos, sem alocações ao analisar e compatíveis com versões anteriores.

Decisão​

Duas codificações coexistem:

  • Legado:

    [type]        // 1 byte

    Mantido para compatibilidade com versões anteriores (atualmente apenas SessionReset).

  • V1 emoldurado:

    0xFF 0x01 [type]   // 3 bytes: prefixo, versão, tipo

    Fornece versionamento para evolução futura.

Detecção (estrita)​

Um pacote é de serviço se e somente se:

  • len==1 e type é conhecido (legado), ou
  • len==3 e os bytes são 0xFF 0x01 <tipo-conhecido> (v1). Todo o resto não é um pacote de serviço.

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 é pré-alocado
    EncodeV1(t PacketType, buffer []byte) ([]byte, error)     // zero-alloc: buffer é pré-alocado
}

Compatibilidade e Implantação​

  • Receber: sempre aceitar tanto legado quanto v1.
  • Enviar: padrão é legado. Após flag de feature no handshake (ServicePacketsV1=true), enviar v1 para aquele cliente; caso contrário manter legado.