ADR-001: حزم الخدمة

الحالة: مقبول

التاريخ: 2025-09-22

لماذا

نحتاج إلى إشارات مستوى التحكم (مثل إعادة تعيين الجلسة) التي تكون واضحة، بدون تخصيص ذاكرة عند التحليل، ومتوافقة مع الإصدارات السابقة.

القرار

يتعايش ترميزان:

• القديم:

  [type]        // 1 بايت

  محفوظ للتوافق مع الإصدارات السابقة (حاليًا فقط SessionReset).

• V1 المؤطر:

  0xFF 0x01 [type]   // 3 بايت: بادئة، إصدار، نوع

  يوفر إصدارات للتطور المستقبلي.

الكشف (صارم)

الحزمة هي حزمة خدمة إذا وفقط إذا:

• len==1 و type معروف (قديم)، أو
• len==3 و البايتات هي 0xFF 0x01 <نوع-معروف> (v1). كل شيء آخر ليس حزمة خدمة.

API

package service

type PacketType uint8
const (
	Unknown PacketType = iota
	SessionReset
)

type PacketHandler interface {
    TryParseType(pkt []byte) (PacketType, bool)               // بدون تخصيص
    EncodeLegacy(t PacketType, buffer []byte) ([]byte, error) // بدون تخصيص: buffer مخصص مسبقًا
    EncodeV1(t PacketType, buffer []byte) ([]byte, error)     // بدون تخصيص: buffer مخصص مسبقًا
}

التوافق والنشر

• الاستقبال: قبول كل من القديم و v1 دائمًا.
• الإرسال: افتراضيًا القديم. بعد علامة ميزة المصافحة (ServicePacketsV1=true)، إرسال v1 لذلك العميل؛ وإلا الاحتفاظ بالقديم.