Skip to main content

vector_calls/
wire.rs

1//! The call's wire format over one Iroh connection: a reliable control stream for
2//! the few messages that must arrive, unreliable QUIC datagrams for audio, where a
3//! late frame is worth less than nothing, and one unidirectional QUIC stream per
4//! video frame, so a keyframe always lands whole and a stale delta can be reset.
5
6use bytes::{BufMut, Bytes, BytesMut};
7use serde::{Deserialize, Serialize};
8use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
9
10pub const CALL_ALPN: &[u8] = b"vector/call/1";
11
12/// Datagram header: sequence, milliseconds since the sender's media start, flags.
13pub const HEADER_LEN: usize = 8;
14
15pub struct Frame<'a> {
16    pub seq: u16,
17    pub flags: u16,
18    pub payload: &'a [u8],
19}
20
21pub fn pack(seq: u16, ts_ms: u32, flags: u16, payload: &[u8]) -> Bytes {
22    let mut b = BytesMut::with_capacity(HEADER_LEN + payload.len());
23    b.put_u16(seq);
24    b.put_u32(ts_ms);
25    b.put_u16(flags);
26    b.put_slice(payload);
27    b.freeze()
28}
29
30pub fn unpack(data: &[u8]) -> Option<Frame<'_>> {
31    if data.len() < HEADER_LEN {
32        return None;
33    }
34    Some(Frame {
35        seq: u16::from_be_bytes([data[0], data[1]]),
36        flags: u16::from_be_bytes([data[6], data[7]]),
37        payload: &data[HEADER_LEN..],
38    })
39}
40
41/// Control messages, length-prefixed JSON on the bidirectional stream.
42#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
43#[serde(tag = "t", rename_all = "snake_case")]
44pub enum Control {
45    /// First message from the caller: which call this connection carries.
46    Hello { call_id: String },
47    Mute { on: bool },
48    Bye,
49    /// What I am sending on the video streams from now on: either, both or neither,
50    /// and whether the screen comes with its sound.
51    Video {
52        camera: bool,
53        screen: bool,
54        #[serde(default)]
55        audio: bool,
56    },
57    /// My decoder lost that chain: its next frame must be a keyframe.
58    KeyframeRequest { kind: VideoKind },
59    /// My view of your video is hidden; stop spending upload on it (or resume).
60    VideoPause { on: bool },
61    /// My decoder cannot take this codec after all; send with another.
62    VideoUnsupported { codec: VideoCodec },
63    /// My app went where the system pauses it (a locked phone, another app in front), or came
64    /// back: my silence meanwhile is a wait, not a hangup.
65    Away { on: bool },
66    /// A message from a newer peer: skipped, never fatal.
67    #[serde(other)]
68    Unknown,
69}
70
71/// The two pictures a side can send at once; a frame's flags say which it is.
72#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
73#[serde(rename_all = "snake_case")]
74pub enum VideoKind {
75    Camera,
76    Screen,
77}
78
79impl VideoKind {
80    pub fn index(self) -> usize {
81        match self {
82            Self::Camera => 0,
83            Self::Screen => 1,
84        }
85    }
86    pub fn from_flags(flags: u8) -> Self {
87        if flags & VIDEO_SCREEN != 0 { Self::Screen } else { Self::Camera }
88    }
89}
90
91/// Which of the two a side is sending.
92#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default)]
93pub struct Tracks {
94    pub camera: bool,
95    pub screen: bool,
96}
97
98impl Tracks {
99    pub fn any(self) -> bool {
100        self.camera || self.screen
101    }
102    pub fn has(self, kind: VideoKind) -> bool {
103        match kind {
104            VideoKind::Camera => self.camera,
105            VideoKind::Screen => self.screen,
106        }
107    }
108    pub fn with(mut self, kind: VideoKind, on: bool) -> Self {
109        match kind {
110            VideoKind::Camera => self.camera = on,
111            VideoKind::Screen => self.screen = on,
112        }
113        self
114    }
115}
116
117/// The codec byte in a video frame header. A fixed table, so nothing from the wire
118/// is ever handed to a decoder as a string.
119#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
120#[serde(rename_all = "snake_case")]
121#[repr(u8)]
122pub enum VideoCodec {
123    H264 = 1,
124    Vp8 = 2,
125}
126
127impl VideoCodec {
128    pub fn from_byte(b: u8) -> Option<Self> {
129        match b {
130            1 => Some(Self::H264),
131            2 => Some(Self::Vp8),
132            _ => None,
133        }
134    }
135    /// The name the signalling tag and the webview use.
136    pub fn name(self) -> &'static str {
137        match self {
138            Self::H264 => "h264",
139            Self::Vp8 => "vp8",
140        }
141    }
142    pub fn from_name(s: &str) -> Option<Self> {
143        match s {
144            "h264" => Some(Self::H264),
145            "vp8" => Some(Self::Vp8),
146            _ => None,
147        }
148    }
149}
150
151/// Video frame flags.
152pub const VIDEO_KEY: u8 = 1;
153pub const VIDEO_SCREEN: u8 = 2;
154/// Header on every video frame, on the QUIC stream and on the link alike.
155pub const VIDEO_HEADER_LEN: usize = 16;
156/// A frame bigger than this is refused: the whole connection window is only 2 MB,
157/// and a bigger frame would sit in front of the control stream. A crisp 1440p
158/// keyframe at the top of the screen ladder is a few hundred kilobytes.
159pub const MAX_VIDEO_FRAME: usize = 1024 * 1024;
160
161#[derive(Debug, Clone, Copy, PartialEq, Eq)]
162pub struct VideoHeader {
163    pub seq: u32,
164    /// Capture time in the sender's microseconds.
165    pub ts_us: u64,
166    pub flags: u8,
167    pub codec: VideoCodec,
168}
169
170impl VideoHeader {
171    pub fn is_key(&self) -> bool {
172        self.flags & VIDEO_KEY != 0
173    }
174
175    pub fn write(&self, out: &mut [u8]) {
176        debug_assert!(out.len() >= VIDEO_HEADER_LEN);
177        out[0..4].copy_from_slice(&self.seq.to_be_bytes());
178        out[4..12].copy_from_slice(&self.ts_us.to_be_bytes());
179        out[12] = self.flags;
180        out[13] = self.codec as u8;
181        out[14] = 0;
182        out[15] = 0;
183    }
184
185    pub fn parse(data: &[u8]) -> Option<Self> {
186        if data.len() < VIDEO_HEADER_LEN {
187            return None;
188        }
189        Some(Self {
190            seq: u32::from_be_bytes([data[0], data[1], data[2], data[3]]),
191            ts_us: u64::from_be_bytes([data[4], data[5], data[6], data[7], data[8], data[9], data[10], data[11]]),
192            flags: data[12],
193            codec: VideoCodec::from_byte(data[13])?,
194        })
195    }
196}
197
198pub const MAX_CONTROL_LEN: usize = 4096;
199
200pub async fn write_control<W: AsyncWrite + Unpin>(send: &mut W, msg: &Control) -> Result<(), String> {
201    let body = serde_json::to_vec(msg).map_err(|e| e.to_string())?;
202    if body.len() > MAX_CONTROL_LEN {
203        return Err("control message too large".into());
204    }
205    let mut buf = Vec::with_capacity(2 + body.len());
206    buf.extend_from_slice(&(body.len() as u16).to_be_bytes());
207    buf.extend_from_slice(&body);
208    send.write_all(&buf).await.map_err(|e| e.to_string())
209}
210
211pub async fn read_control<R: AsyncRead + Unpin>(recv: &mut R) -> Result<Control, String> {
212    let mut len = [0u8; 2];
213    recv.read_exact(&mut len).await.map_err(|e| e.to_string())?;
214    let len = u16::from_be_bytes(len) as usize;
215    if len == 0 || len > MAX_CONTROL_LEN {
216        return Err("control message length out of range".into());
217    }
218    let mut body = vec![0u8; len];
219    recv.read_exact(&mut body).await.map_err(|e| e.to_string())?;
220    serde_json::from_slice(&body).map_err(|e| e.to_string())
221}
222
223#[cfg(test)]
224mod tests {
225    use super::*;
226
227    #[test]
228    fn a_video_header_round_trips_and_refuses_an_unknown_codec() {
229        let h = VideoHeader { seq: 70_000, ts_us: 1 << 40, flags: VIDEO_KEY | VIDEO_SCREEN, codec: VideoCodec::Vp8 };
230        let mut buf = [0u8; VIDEO_HEADER_LEN + 3];
231        h.write(&mut buf);
232        assert_eq!(VideoHeader::parse(&buf), Some(h));
233        assert!(h.is_key());
234        buf[13] = 9;
235        assert!(VideoHeader::parse(&buf).is_none());
236        assert!(VideoHeader::parse(&buf[..10]).is_none());
237    }
238
239    #[test]
240    fn an_unknown_control_message_parses_as_unknown() {
241        let c: Control = serde_json::from_str(r#"{"t":"hologram","on":true}"#).unwrap();
242        assert_eq!(c, Control::Unknown);
243        let v: Control = serde_json::from_str(r#"{"t":"video","camera":false,"screen":true}"#).unwrap();
244        assert_eq!(v, Control::Video { camera: false, screen: true, audio: false });
245        assert_eq!(serde_json::to_string(&Control::KeyframeRequest { kind: VideoKind::Camera }).unwrap(), r#"{"t":"keyframe_request","kind":"camera"}"#);
246        assert_eq!(serde_json::to_string(&Control::Away { on: true }).unwrap(), r#"{"t":"away","on":true}"#);
247        assert_eq!(VideoKind::from_flags(VIDEO_KEY | VIDEO_SCREEN), VideoKind::Screen);
248        assert!(Tracks::default().with(VideoKind::Screen, true).has(VideoKind::Screen));
249    }
250
251    #[test]
252    fn a_frame_round_trips() {
253        let b = pack(7, 1234, 1, &[9, 8, 7]);
254        let f = unpack(&b).unwrap();
255        assert_eq!((f.seq, f.flags, f.payload), (7, 1, &[9u8, 8, 7][..]));
256        assert!(unpack(&b[..5]).is_none());
257    }
258}