graph LR
    A[Publisher Client] -->|SFrame Encrypt| B(SFU Router)
    B -->|Forward Only| C[Subscriber Client]
    C -->|SFrame Decrypt| D[Renderer]
    KMS[(Key Management Service)] -.->|Epoch/Key Distribution| A
    KMS -.->|Epoch/Key Distribution| C

// sframe-encoder.ts
import { SFrameEncoder, KeyManager } from '@webrtc/sframe'; // 假设已发布 npm 包

export class SFramePublisher {
  private encoder: SFrameEncoder;
  private keyMgr: KeyManager;

  constructor(private senderId: number, private kms: KMSClient) {
    this.keyMgr = new KeyManager({ kms });
    this.encoder = new SFrameEncoder({
      cipherSuite: 'AES_GCM_128_SHA256', // 推荐基线套件
      keyLength: 16,
      saltLength: 12,
    });
  }

  /** 入会时拉取 Epoch & Sender Key */
  async join(roomId: string) {
    const { epoch, senderKey } = await this.kms.fetchKeyBundle(roomId, this.senderId);
    await this.keyMgr.init({ epoch, senderKey });
    this.encoder.setKey(this.keyMgr.currentMediaKey());
  }

  /** 每帧编码入口：由 VideoEncoder / AudioEncoder 回调驱动 */
  async encodeFrame(frame: EncodedVideoChunk | EncodedAudioChunk): Promise<RTCEncodedVideoFrame | RTCEncodedAudioFrame> {
    // 1. 取出原始 payload 与 metadata
    const payload = new Uint8Array(frame.data);
    const metadata = this.buildMetadata(frame); // 包含 frameId, spatialLayer 等

    // 2. SFrame 加密
    const encrypted = await this.encoder.encrypt(payload, metadata);

    // 3. 重组 RTP 包（保留原 header，替换 payload）
    return new RTCEncodedVideoFrame({
      type: frame.type,
      timestamp: frame.timestamp,
      data: encrypted,
      // 关键：保留原 RTP Header Extensions，供 SFU 路由使用
      ...this.extractRtpHeaders(frame),
    });
  }

  /** 密钥轮转：KMS 推送新 Epoch 时调用 */
  async rotateKey(newEpoch: number, newSenderKey: Uint8Array) {
    await this.keyMgr.rotate({ epoch: newEpoch, senderKey: newSenderKey });
    this.encoder.setKey(this.keyMgr.currentMediaKey());
  }

  private buildMetadata(frame: EncodedVideoChunk | EncodedAudioChunk): SFrameMetadata {
    return {
      frameCounter: frame.timestamp, // 简化：用 timestamp 作为单调递增计数器
      // 可扩展：spatialLayer, temporalLayer, dependencyId 等
    };
  }
}

// sframe_router.rs
use bytes::BytesMut;
use sframe::parser::SFrameHeader; // 仅解析头部，不解密

pub struct SFrameRouter {
    // 仅缓存合法 SSRC -> SenderId 映射，用于防伪造
    valid_senders: DashMap<u32, u64>,
}

impl SFrameRouter {
    pub fn forward(&self, mut pkt: RtpPacket) -> Result<RtpPacket, RouterError> {
        // 1. 校验 SSRC 是否在白名单
        let sender_id = *self.valid_senders.get(&pkt.ssrc).ok_or(RouterError::InvalidSender)?;

        // 2. 轻量解析 SFrame Header（前 2~4 字节），确认帧边界完整
        let _header = SFrameHeader::parse(&pkt.payload[..4])?;

        // 3. 直接转发，零拷贝
        Ok(pkt)
    }

    /// 由信令服务器在用户加入/离开时调用
    pub fn update_sender_map(&self, ssrc: u32, sender_id: u64) {
        self.valid_senders.insert(ssrc, sender_id);
    }
}

// sframe-decoder.ts
export class SFrameSubscriber {
  private decoder: SFrameDecoder;
  private pendingFrames = new Map<number, EncryptedFrame[]>(); // 用于乱序重组

  constructor(private receiverId: number, private kms: KMSClient) {
    this.decoder = new SFrameDecoder({ cipherSuite: 'AES_GCM_128_SHA256' });
  }

  async onTrack(track: MediaStreamTrack) {
    const { epoch, senderKey } = await this.kms.fetchKeyBundle(track.roomId, this.receiverId);
    await this.decoder.init({ epoch, senderKey });
  }

  /** 处理乱序/丢包：缓存 N 帧等待关键帧 */
  async handleFrame(rtpPkt: RTCEncodedVideoFrame) {
    const frameId = this.extractFrameId(rtpPkt);
    this.pendingFrames.set(frameId, rtpPkt);

    // 简单策略：收到关键帧尝试 flush
    if (rtpPkt.type === 'key') this.tryFlush(frameId);
  }

  private async tryFlush(keyFrameId: number) {
    const sorted = [...this.pendingFrames.entries()].sort((a, b) => a[0] - b[0]);
    for (const [id, pkt] of sorted) {
      if (id > keyFrameId) break; // 只 flush 关键帧及之前的帧
      try {
        const plain = await this.decoder.decrypt(pkt.data);
        this.renderer.push(plain, pkt.timestamp);
        this.pendingFrames.delete(id);
      } catch (e) {
        if (e.code === 'MAC_VERIFY_FAILED') {
          // 丢包导致 MAC 校验失败，丢弃该帧并请求关键帧
          this.requestKeyFrame();
          break;
        }
        throw e;
      }
    }
  }
}

// sframe_signal.proto
message KeyBundleRequest {
  string room_id = 1;
  uint64 sender_id = 2;
  uint32 client_epoch = 3;  // 客户端当前已知 Epoch，用于增量同步
}

message KeyBundleResponse {
  uint32 epoch = 1;
  bytes sender_key = 2;           // Base Key (32 bytes for AES-256)
  bytes key_derivation_salt = 3;  // 可选：自定义派生盐值
  uint32 key_ttl_sec = 4;         // 密钥生存期，客户端定时器触发轮转
  repeated uint32 deprecated_epochs = 5; // 已废弃 Epoch 列表，防重放
}

message KeyUpdatePush {           // 服务端主动推送（成员变更/定时轮转）
  uint32 new_epoch = 1;
  bytes new_sender_key = 2;
  uint32 grace_period_sec = 3;    // 新旧并存宽限期
  KeyUpdateReason reason = 4;     // ROTATION / MEMBER_JOIN / MEMBER_LEAVE / COMPROMISE
}

// SFrameVTEncoder.swift
final class SFrameVTEncoder {
    private let vtSession: VTCompressionSession
    private let sframeCtx: OpaquePointer // libsframe C API context
    private var frameCounter: UInt64 = 0

    init(width: Int, height: Int, senderId: UInt64, key: Data) throws {
        // 1. 创建 VT 压缩会话，输出回调中直接拿到 CMSampleBuffer
        var session: VTCompressionSession?
        VTCompressionSessionCreate(
            allocator: kCFAllocatorDefault,
            width: width, height: height,
            codecType: kCMVideoCodecType_H264,
            encoderSpecification: nil,
            imageBufferAttributes: nil,
            compressedDataAllocator: kCFAllocatorDefault,
            outputCallback: { _, _, sampleBuffer, _, _ in
                Self.handleOutput(sampleBuffer: sampleBuffer!, senderId: senderId, ctx: $0)
            },
            refcon: Unmanaged.passUnretained(self).toOpaque(),
            compressionSessionOut: &session
        )
        self.vtSession = session!

        // 2. 初始化 libsframe 加密上下文
        self.sframeCtx = sframe_create_context(senderId, key.bytes, key.count, CIPHER_AES_GCM_128)
    }

    private static func handleOutput(sampleBuffer: CMSampleBuffer, senderId: UInt64, ctx: UnsafeMutableRawPointer) {
        let encoder = Unmanaged<SFrameVTEncoder>.fromOpaque(ctx).takeUnretainedValue()
        guard let dataBuffer = CMSampleBufferGetDataBuffer(sampleBuffer) else { return }
        
        var length: Int = 0
        var pointer: UnsafeMutablePointer<UInt8>?
        CMBlockBufferGetDataPointer(dataBuffer, atOffset: 0, lengthAtOffsetOut: nil, totalLengthOut: &length, dataPointerOut: &pointer)
        
        // 3. 原地加密：直接在 CMBlockBuffer 内存上做 SFrame 封装（需预留 16+ 字节头部/尾部空间）
        var encryptedLen = length + SFRAME_OVERHEAD_MAX
        let encryptedPtr = UnsafeMutablePointer<UInt8>.allocate(capacity: encryptedLen)
        defer { encryptedPtr.deallocate() }
        
        let ret = sframe_encrypt(encoder.sframeCtx, encoder.frameCounter, pointer!, length, encryptedPtr, &encryptedLen)
        guard ret == 0 else { return }
        
        encoder.frameCounter += 1
        
        // 4. 替换 SampleBuffer 数据指针，零拷贝送网络层
        var newBuffer: CMBlockBuffer?
        CMBlockBufferCreateWithMemoryBlock(
            allocator: kCFAllocatorDefault,
            memoryBlock: encryptedPtr, blockLength: encryptedLen,
            blockAllocator: kCFAllocatorNull, // 由网络层释放
            customBlockSource: nil,
            offsetToData: 0, dataLength: encryptedLen,
            flags: 0, blockBufferOut: &newBuffer
        )
        // 交付给 RTP 发送队列...
    }
}

// SFrameMediaCodecEncoder.kt
class SFrameMediaCodecEncoder(
    private val senderId: Long,
    private val key: ByteArray,
    private val callback: (ByteArray, Long, Boolean) -> Unit // data, pts, isKeyFrame
) {
    private val codec = MediaCodec.createEncoderByType("video/avc")
    private val sframeCtx = SFrameNative.init(senderId, key) // JNI 绑定 libsframe
    private var frameCounter = 0L

    @OptIn(ExperimentalMediaApi::class)
    fun start(format: MediaFormat) {
        codec.setCallback(object : MediaCodec.Callback() {
            override fun onOutputBufferAvailable(codec: MediaCodec, index: Int, info: MediaCodec.BufferInfo) {
                val outputBuffer = codec.getOutputBuffer(index)!!
                outputBuffer.position(info.offset)
                outputBuffer.limit(info.offset + info.size)

                // 1. 取出裸流
                val plain = ByteArray(info.size)
                outputBuffer.get(plain)

                // 2. SFrame 加密（JNI 直传 Direct Buffer，避免堆拷贝）
                val encrypted = SFrameNative.encrypt(sframeCtx, frameCounter, plain)
                frameCounter++

                // 3. 回调网络层
                callback(encrypted, info.presentationTimeUs, (info.flags and MediaCodec.BUFFER_FLAG_KEY_FRAME) != 0)
                codec.releaseOutputBuffer(index, false)
            }
        })
        codec.configure(format, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE)
        codec.start()
    }
}

// sframe_kdf_sm4.rs
use gmssl::sm3::Sm3Hash;
use hkdf::Hkdf;

pub fn derive_media_key_sm4(base_key: &[u8], salt: &[u8], label: &[u8], context: &[u8]) -> [u8; 16] {
    // HKDF-SM3 (参考 RFC 5869 结构，哈希替换为 SM3)
    let hk = Hkdf::<Sm3Hash>::new(Some(salt), base_key);
    let mut okm = [0u8; 16];
    hk.expand(&[label, context].concat(), &mut okm).expect("HKDF expand failed");
    okm
}

单机最大路数 ≈ (CPU 核心数 × 0.75 × 单核处理能力) / (单路码率 × 加密开销系数)
# 经验系数：AES-GCM 1.15, SM4-GCM 1.35 (软实现) / 1.10 (硬件加速)

groups:
- name: sframe-reliability
  rules:
  - alert: SFrameDecryptFailureRateHigh
    expr: |
      sum(rate(sframe_decrypt_fail_total[5m])) by (room_id)
      /
      sum(rate(sframe_decrypt_total[5m])) by (room_id)
      > 0.02
    for: 2m
    labels:
      severity: critical
    annotations:
      summary: "Room {{ $labels.room_id }} 解密失败率 > 2%"
      runbook_url: "https://wiki.example.com/sframe-troubleshooting"

  - alert: SFrameKeyRotationStuck
    expr: |
      time() - sframe_last_key_rotation_timestamp_seconds > 3600
    for: 10m
    labels:
      severity: warning
    annotations:
      summary: "密钥轮转卡顿超过 1 小时，疑似 KMS 异常"

graph TD
    A[Client SDK] -->|OpenTelemetry| B(Collector)
    C[SFU Router] -->|Prometheus Metrics + pprof| B
    D[KMS] -->|Audit Log (JSON)| B
    B --> E[Tempo: Trace]
    B --> F[Loki: Log]
    B --> G[Mimir: Metric]
    E --> H[Grafana Dashboard]
    F --> H
    G --> H

// Trace Span 示例 (W3C TraceContext)
{
  "trace_id": "a1b2c3d4e5f6...",
  "span_id": "1234567890ab...",
  "name": "sframe.encrypt",
  "kind": "INTERNAL",
  "attributes": {
    "sframe.sender_id": 1001,
    "sframe.epoch": 42,
    "sframe.frame_counter": 10245,
    "sframe.cipher_suite": "AES_GCM_128_SHA256",
    "sframe.payload_bytes": 1456,
    "sframe.overhead_bytes": 24,
    "codec": "H264",
    "layer": "spatial_2",
    "hw_accel": "VideoToolbox"
  },
  "events": [
    {"name": "key_derived", "time": "..."},
    {"name": "encrypt_done", "time": "..."}
  ]
}