Zum Hauptinhalt springen

ADR-001: Service-Pakete

Status: Akzeptiert

Datum: 2025-09-22

Warum​

Wir benötigen Control-Plane-Signale (z.B. Session-Reset), die eindeutig, beim Parsen allokationsfrei und abwärtskompatibel sind.

Entscheidung​

Zwei Kodierungen koexistieren:

  • Legacy:

    [type]        // 1 Byte

    Beibehalten für Abwärtskompatibilität (derzeit nur SessionReset).

  • V1 gerahmt:

    0xFF 0x01 [type]   // 3 Bytes: Präfix, Version, Typ

    Bietet Versionierung für zukünftige Evolution.

Erkennung (strikt)​

Ein Paket ist ein Service-Paket genau dann, wenn:

  • len==1 und type bekannt ist (legacy), oder
  • len==3 und die Bytes 0xFF 0x01 <bekannter-typ> sind (v1). Alles andere ist kein Service-Paket.

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

Kompatibilität & Rollout​

  • Empfangen: immer sowohl legacy als auch v1 akzeptieren.
  • Senden: Standard ist legacy. Nach Handshake-Feature-Flag (ServicePacketsV1=true) v1 an diesen Client senden; ansonsten legacy beibehalten.