Skip to main content

ADR-001: Service Packets

Status: Accepted

Date: 2025-09-22

Why​

We need control-plane signals (e.g., session reset) that are unambiguous, zero-alloc to parse, and backward-compatible.

Decision​

Two encodings coexist:

  • Legacy:

    [type]        // 1 byte

    Kept for backward compatibility (currently only SessionReset).

  • V1 framed:

    0xFF 0x01 [type]   // 3 bytes: prefix, version, type

    Provides versioning for future evolution.

Detection (strict)​

A packet is service if and only if:

  • len==1 and type is known (legacy), or
  • len==3 and bytes are 0xFF 0x01 <known-type> (v1). Everything else is not a service packet.

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

Compatibility & Rollout​

  • Receive: always accept both legacy and v1.
  • Send: default to legacy. After handshake feature flag (ServicePacketsV1=true), send v1 to that client; otherwise keep legacy.