[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 相关: Event Envelope, Stream Resumption

Event Ordering

一句话定义

Event Ordering 是确保 SSE 事件按发送顺序到达和处理的机制。网络抖动可能导致事件乱序或丢包，需要 sequence number 来检测和处理。

核心原理

Sequence Number

{
  "event": "text_delta",
  "data": {"delta": "你好"},
  "meta": {"sequence": 42}
}

乱序检测

class OrderedEventProcessor {
  private lastSequence = 0;
  private buffer: Map<number, EventEnvelope> = new Map();

  process(event: EventEnvelope) {
    const seq = event.meta.sequence;

    // 检查是否乱序
    if (seq <= this.lastSequence) {
      return; // 重复事件，忽略
    }

    if (seq !== this.lastSequence + 1) {
      // 乱序或丢包，缓存等待
      this.buffer.set(seq, event);
      return;
    }

    // 正常顺序，处理
    this.lastSequence = seq;
    this.handleEvent(event);

    // 处理缓冲区中的后续事件
    while (this.buffer.has(this.lastSequence + 1)) {
      this.lastSequence++;
      this.handleEvent(this.buffer.get(this.lastSequence)!);
      this.buffer.delete(this.lastSequence);
    }
  }
}

常见坑

1. 不做排序: 乱序事件直接处理导致状态错误
2. 不检测丢包: 缺少的 sequence 没有处理
3. 缓冲区无限增长: 等待的事件太多

参考资料

• Event Envelope
• Stream Resumption