RTC Interceptor - Sans-IO interceptor framework for RTP/RTCP processing.

This crate provides a composable interceptor framework built on top of the [sansio::Protocol] trait. Interceptors can process, modify, or generate RTP/RTCP packets as they flow through the pipeline.

Available Interceptors

RTCP Reports

NACK (Negative Acknowledgement)

TWCC (Transport Wide Congestion Control)

Utility

Design

Each interceptor wraps an inner Interceptor and can:

• Process incoming/outgoing RTP/RTCP packets
• Modify packet contents (headers, payloads)
• Generate new packets (e.g., RTCP Sender/Receiver Reports)
• Handle timeouts for periodic tasks (e.g., report generation)
• Track stream statistics and state

All interceptors work with [TaggedPacket] (RTP or RTCP packets with transport metadata). The innermost interceptor is typically [NoopInterceptor], which serves as the terminal.

No Direction Concept

Important: Unlike PeerConnection's pipeline where read and write have opposite processing direction orders, interceptors have no direction concept.

In PeerConnection's pipeline:

Read:  Network → HandlerA → HandlerB → HandlerC → Application
Write: Application → HandlerC → HandlerB → HandlerA → Network
       (reversed order)

In Interceptor chains, all operations flow in the same direction:

handle_read:    Outer → Inner (A.handle_read calls B.handle_read calls C.handle_read)
handle_write:   Outer → Inner (A.handle_write calls B.handle_write calls C.handle_write)
handle_event:   Outer → Inner (A.handle_event calls B.handle_event calls C.handle_event)
handle_timeout: Outer → Inner (A.handle_timeout calls B.handle_timeout calls C.handle_timeout)

poll_read:    Outer → Inner (A.poll_read calls B.poll_read calls C.poll_read)
poll_write:   Outer → Inner (A.poll_write calls B.poll_write calls C.poll_write)
poll_event:   Outer → Inner (A.poll_event calls B.poll_event calls C.poll_event)
poll_timeout: Outer → Inner (A.poll_timeout calls B.poll_timeout calls C.poll_timeout)

This means interceptors are symmetric - they process read, write, and event in the same structural order. The distinction between "inbound" and "outbound" is semantic (based on message content), not structural (based on call order).

Quick Start

use rtc_interceptor::{
    Registry, SenderReportBuilder, ReceiverReportBuilder,
    NackGeneratorBuilder, NackResponderBuilder,
    TwccSenderBuilder, TwccReceiverBuilder,
};
use std::time::Duration;

// Build a full-featured interceptor chain
let chain = Registry::new()
    // RTCP reports
    .with(SenderReportBuilder::new()
        .with_interval(Duration::from_secs(1))
        .build())
    .with(ReceiverReportBuilder::new()
        .with_interval(Duration::from_secs(1))
        .build())
    // NACK for packet loss recovery
    .with(NackGeneratorBuilder::new()
        .with_size(512)
        .with_interval(Duration::from_millis(100))
        .build())
    .with(NackResponderBuilder::new()
        .with_size(1024)
        .build())
    // TWCC for congestion control
    .with(TwccSenderBuilder::new().build())
    .with(TwccReceiverBuilder::new()
        .with_interval(Duration::from_millis(100))
        .build())
    .build();

Stream Binding

Before interceptors can process packets for a stream, the stream must be bound:

use rtc_interceptor::{StreamInfo, RTCPFeedback, RTPHeaderExtension};

// Create stream info with NACK and TWCC support
let stream_info = StreamInfo {
    ssrc: 0x12345678,
    clock_rate: 90000,
    mime_type: "video/VP8".to_string(),
    payload_type: 96,
    rtcp_feedback: vec![RTCPFeedback {
        typ: "nack".to_string(),
        parameter: String::new(),
    }],
    rtp_header_extensions: vec![RTPHeaderExtension {
        uri: "http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01".to_string(),
        id: 5,
    }],
    ..Default::default()
};

// Bind for outgoing streams (sender side)
chain.bind_local_stream(&stream_info);

// Bind for incoming streams (receiver side)
chain.bind_remote_stream(&stream_info);