parse method

Packet? parse(
  1. Uint8List buffer
)

Validate a raw datagram and decode its header fields.

buffer is the raw UDP datagram to validate.

When the datagram carries no attachment, the returned packet may keep a reference to buffer; callers must treat it as read-only and must not modify it afterwards.

Shared by BridgePacketFactory and DirectPacketFactory: performs the magic-code check, E-width range, header-length formula and per-field bounds. Returns null on any violation. The caller then applies the B-bit filter and the tail (attachment) rule.

Implementation

Packet? parse(Uint8List buffer) {
  if (buffer.length < MIN_HEADER_LENGTH) {
    // UDP datagram must hold at least the fixed 8-byte prefix.
    return null;
  } else if (buffer.length > MSS) {
    // MSS hard cap: header + payload (+ attachment) <= 1232.
    return null;
  }

  // 1. Magic code.
  if (buffer.readUint32(0) != MAGIC_CODE) {
    return null;
  }

  // 2. Type byte.
  final type = buffer.readUint8(4);
  final hLen = buffer.readUint8(5);
  final pLen = buffer.readUint16(6);  // 2 bytes, big-endian

  // flags
  final ack = (type >> 7) & 0x01;
  final bid = (type >> 6) & 0x01;
  final cmd = (type >> 5) & 0x01;
  final dsn = (type >> 4) & 0x01;
  final ext = type & 0x07;

  // E must be 0..4 (5/6/7 are invalid); E>0 requires D=1.
  if (ext > 4) {
    return null;
  } else if (ext > 0 && dsn == 0) {
    return null;
  }

  // Header length must match the formula.
  if (hLen != calcHeaderLength(bid: bid, cmd: cmd, dsn: dsn, ext: ext)) {
    return null;
  }

  // tail < 0: the datagram cannot even hold the declared header + payload.
  // Check before reading the variable-length fields below, otherwise a
  // truncated packet with a long declared header throws RangeError instead
  // of being silently dropped (300:195-201).
  final size = hLen + pLen;
  final tail = buffer.length - size;
  if (tail == ATTACHMENT_LENGTH) {
    // cut the tail here
    buffer = Uint8List.fromList(buffer.sublist(0, size));
  } else if (tail != 0) {
    // tail is neither 0 nor 32: bad packet.
    return null;
  }

  // 3. Read header fields and validate them.
  var target = 0, source = 0;
  var sn = 0, index = 0, count = 1;
  var command = 0;

  var offset = MIN_HEADER_LENGTH;
  if (bid != 0) {
    target = buffer.readUint32(offset);
    offset += 4;
    source = buffer.readUint32(offset);
    offset += 4;
  }
  if (dsn != 0) {
    sn = buffer.readUint32(offset);
    offset += 4;
    if (sn == 0) {
      // D=1 implies sn != 0.
      return null;
    }
  }
  if (ext > 0) {
    index = _readExt(buffer, offset, ext);
    offset += ext;
    count = _readExt(buffer, offset, ext);
    offset += ext;
    if (index >= count || count < 2) {
      // 0 <= index < count; count must be > 1 when E>0.
      return null;
    }
  }
  if (cmd != 0) {
    command = buffer.readUint32(offset);
    offset += 4;
    if (command == 0) {
      // C=1 implies command != 0.
      return null;
    }
  }

  // Tail: attachment decision.
  final payload = pLen > 0
      ? Uint8List.fromList(buffer.sublist(hLen, size))
      : Uint8List(0);

  return MessagePacket(buffer,
    ack: ack,
    bid: bid,
    cmd: cmd,
    dsn: dsn,
    ext: ext,
    headerLength: hLen,
    payloadLength: pLen,
    target: target,
    source: source,
    sn: sn,
    index: index,
    count: count,
    command: command,
    payload: payload,
  );
}