《移动游戏产品的架构·网络、资源与热更新》2.1 消息信封、版本与兼容规则

// file: src/net/message-envelope.ts
// tier: L1
// verify: node --test test/net/message-envelope.test.ts

export const ENVELOPE_MAGIC = 0x4d47;
export const PROTOCOL_MAJOR = 2;
export const HEADER_BYTES = 14;

export type MessageKind = "request" | "response" | "push" | "snapshot";

const KIND_TO_CODE: Record<MessageKind, number> = {
  request: 1,
  response: 2,
  push: 3,
  snapshot: 4,
};

const CODE_TO_KIND: Record<number, MessageKind> = {
  1: "request",
  2: "response",
  3: "push",
  4: "snapshot",
};

export type EnvelopeErrorCode =
  | "short"
  | "magic"
  | "version"
  | "kind"
  | "schema"
  | "length";

export class EnvelopeError extends Error {
  readonly code: EnvelopeErrorCode;

  constructor(code: EnvelopeErrorCode, message: string) {
    super(message);
    this.name = "EnvelopeError";
    this.code = code;
  }
}

export interface Envelope {
  readonly major: number;
  readonly kind: MessageKind;
  readonly flags: number;
  readonly sequence: number;
  readonly schema: string;
  readonly payload: Uint8Array;
}

export interface SchemaField {
  readonly name: string;
  readonly required: boolean;
  readonly sinceMinor: number;
}

export interface SchemaContract {
  readonly name: string;
  readonly major: number;
  readonly minor: number;
  readonly fields: readonly SchemaField[];
}

export type CompatibilityLevel =
  | "identical"
  | "backward"
  | "forward"
  | "breaking";

export interface Compatibility {
  readonly ok: boolean;
  readonly level: CompatibilityLevel;
  readonly reasons: readonly string[];
  readonly unknownFields: readonly string[];
}

const encoder = new TextEncoder();
const decoder = new TextDecoder();

function kindCode(kind: MessageKind): number {
  const code = KIND_TO_CODE[kind];
  if (code === undefined) {
    throw new EnvelopeError("kind", `unknown message kind: ${String(kind)}`);
  }
  return code;
}

function isMessageKind(value: number): value is MessageKind {
  return CODE_TO_KIND[value] !== undefined;
}

export function encodeEnvelope(envelope: Envelope): Uint8Array {
  if (!Number.isInteger(envelope.major) || envelope.major < 0 || envelope.major > 255) {
    throw new EnvelopeError("version", `major out of range: ${envelope.major}`);
  }
  const schemaBytes = encoder.encode(envelope.schema);
  if (schemaBytes.length === 0 || schemaBytes.length > 255) {
    throw new EnvelopeError("schema", `schema length out of range: ${schemaBytes.length}`);
  }
  if (!Number.isInteger(envelope.sequence) || envelope.sequence < 0) {
    throw new EnvelopeError("length", `sequence out of range: ${envelope.sequence}`);
  }
  const bodyBytes = HEADER_BYTES + schemaBytes.length + envelope.payload.length;
  const buffer = new Uint8Array(bodyBytes);
  const view = new DataView(buffer.buffer);

  view.setUint16(0, ENVELOPE_MAGIC, false);
  view.setUint8(2, envelope.major);
  view.setUint8(3, kindCode(envelope.kind));
  view.setUint8(4, envelope.flags & 0xff);
  view.setUint8(5, schemaBytes.length);
  view.setUint32(6, envelope.sequence, false);
  view.setUint32(10, envelope.payload.length, false);

  buffer.set(schemaBytes, HEADER_BYTES);
  buffer.set(envelope.payload, HEADER_BYTES + schemaBytes.length);
  return buffer;
}

export function decodeEnvelope(bytes: Uint8Array): Envelope {
  if (bytes.length < HEADER_BYTES) {
    throw new EnvelopeError("short", `buffer ${bytes.length} < ${HEADER_BYTES}`);
  }
  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
  const magic = view.getUint16(0, false);
  if (magic !== ENVELOPE_MAGIC) {
    throw new EnvelopeError("magic", `bad magic: 0x${magic.toString(16)}`);
  }
  const major = view.getUint8(2);
  if (major !== PROTOCOL_MAJOR) {
    throw new EnvelopeError("version", `unsupported major: ${major}`);
  }
  const kindCodeValue = view.getUint8(3);
  if (!isMessageKind(kindCodeValue)) {
    throw new EnvelopeError("kind", `unknown kind code: ${kindCodeValue}`);
  }
  const flags = view.getUint8(4);
  const schemaLength = view.getUint8(5);
  if (schemaLength === 0) {
    throw new EnvelopeError("schema", "empty schema name");
  }
  const sequence = view.getUint32(6, false);
  const payloadLength = view.getUint32(10, false);
  const expected = HEADER_BYTES + schemaLength + payloadLength;
  if (bytes.length < expected) {
    throw new EnvelopeError("length", `buffer ${bytes.length} < ${expected}`);
  }
  const schema = decoder.decode(bytes.subarray(HEADER_BYTES, HEADER_BYTES + schemaLength));
  const payloadStart = HEADER_BYTES + schemaLength;
  const payload = bytes.slice(payloadStart, payloadStart + payloadLength);
  return {
    major,
    kind: CODE_TO_KIND[kindCodeValue] as MessageKind,
    flags,
    sequence,
    schema,
    payload,
  };
}

export function checkCompatibility(
  local: SchemaContract,
  remote: SchemaContract,
): Compatibility {
  const reasons: string[] = [];
  if (local.name !== remote.name) {
    reasons.push(`schema ${remote.name} != ${local.name}`);
  }
  if (local.major !== remote.major) {
    reasons.push(`major ${remote.major} != ${local.major}`);
  }
  if (reasons.length > 0) {
    return { ok: false, level: "breaking", reasons, unknownFields: [] };
  }

  const localFields = new Map(local.fields.map((field) => [field.name, field]));
  const remoteFields = new Map(remote.fields.map((field) => [field.name, field]));

  for (const field of local.fields) {
    if (field.required && !remoteFields.has(field.name)) {
      reasons.push(`remote drops required field ${field.name}`);
    }
  }

  const unknownFields: string[] = [];
  for (const field of remote.fields) {
    if (!localFields.has(field.name)) {
      unknownFields.push(field.name);
      if (field.required && field.sinceMinor > local.minor) {
        reasons.push(`remote requires unknown field ${field.name}`);
      }
    }
  }

  if (reasons.length > 0) {
    return { ok: false, level: "breaking", reasons, unknownFields };
  }
  if (local.minor === remote.minor && unknownFields.length === 0) {
    return { ok: true, level: "identical", reasons: [], unknownFields: [] };
  }
  if (remote.minor > local.minor) {
    return { ok: true, level: "forward", reasons: [], unknownFields };
  }
  return { ok: true, level: "backward", reasons: [], unknownFields };
}

export function describeEnvelope(envelope: Envelope): string {
  const flags = `0x${(envelope.flags & 0xff).toString(16).padStart(2, "0")}`;
  return `MG/${envelope.major} ${envelope.kind} seq=${envelope.sequence} schema=${envelope.schema} payload=${envelope.payload.length}B flags=${flags}`;
}

export function describeCompatibility(result: Compatibility): string {
  if (result.ok) {
    const unknown = result.unknownFields.length > 0
      ? ` unknown=${result.unknownFields.join(",")}`
      : "";
    return `compatible:${result.level}${unknown}`;
  }
  return `breaking: ${result.reasons.join("; ")}`;
}

MG/2 snapshot seq=1042 schema=ark.battle.snapshot payload=4B flags=0x00