Skip to main content

qualia_core_db/net/qdnf/session/
streams.rs

1//! Bounded reliable streams. Independent stream ids; capped out-of-order.
2
3use crate::net::qdnf::errors::QdnfError;
4
5pub const MAX_STREAMS_PER_DIR: usize = 64;
6pub const MAX_STREAM_OFFSET: u64 = 1 << 32;
7/// Out-of-order frames retained per stream (head-of-line isolation cap).
8pub const MAX_OOO_FRAMES: usize = 4;
9/// Combined unread + OOO bytes retained per stream.
10pub const MAX_STREAM_BUFFER_BYTES: u32 = 4096;
11
12#[repr(C)]
13#[derive(Clone, Copy, Debug, PartialEq, Eq)]
14pub struct StreamFrame {
15    pub stream_id: u16,
16    pub offset: u64,
17    pub fin: bool,
18    pub declared_final: Option<u64>,
19    pub len: u16,
20}
21
22#[derive(Clone, Copy, Debug, PartialEq, Eq)]
23struct OooFrame {
24    offset: u64,
25    len: u16,
26    fin: bool,
27    declared_final: Option<u64>,
28}
29
30#[derive(Clone, Copy, Debug)]
31pub struct StreamState {
32    pub next_offset: u64,
33    pub final_size: Option<u64>,
34    pub open: bool,
35    unread_bytes: u32,
36    ooo_bytes: u32,
37    ooo: [Option<OooFrame>; MAX_OOO_FRAMES],
38}
39
40impl StreamState {
41    /// Creates a default `StreamState`.
42    pub const fn new() -> Self {
43        Self {
44            next_offset: 0,
45            final_size: None,
46            open: true,
47            unread_bytes: 0,
48            ooo_bytes: 0,
49            ooo: [None; MAX_OOO_FRAMES],
50        }
51    }
52
53    /// `StreamState::unread_bytes`.
54    pub const fn unread_bytes(&self) -> u32 {
55        self.unread_bytes
56    }
57
58    /// Consumes `n` flow-control bytes; error over limit.
59    pub fn consume(&mut self, n: u32) -> Result<(), QdnfError> {
60        if n > self.unread_bytes {
61            return Err(QdnfError::Range);
62        }
63        self.unread_bytes -= n;
64        Ok(())
65    }
66
67    /// Accepts a `StreamFrame`, updating flow state.
68    pub fn accept(&mut self, frame: StreamFrame) -> Result<(), QdnfError> {
69        if !self.open {
70            return Err(QdnfError::Closed);
71        }
72        if frame.stream_id as usize >= MAX_STREAMS_PER_DIR {
73            return Err(QdnfError::Capacity);
74        }
75        if frame.offset > MAX_STREAM_OFFSET {
76            return Err(QdnfError::Range);
77        }
78        self.check_final(&frame)?;
79        if frame.offset < self.next_offset {
80            return Err(QdnfError::Overlap);
81        }
82        if frame.offset == self.next_offset {
83            self.apply_in_order(frame.len, frame.fin, frame.declared_final)?;
84            self.drain_ooo()?;
85            return Ok(());
86        }
87        self.buffer_ooo(frame)
88    }
89
90    fn check_final(&mut self, frame: &StreamFrame) -> Result<(), QdnfError> {
91        if let Some(fin) = self.final_size {
92            if let Some(declared) = frame.declared_final {
93                if declared != fin {
94                    return Err(QdnfError::Conflict);
95                }
96            }
97            let end = frame
98                .offset
99                .checked_add(frame.len as u64)
100                .ok_or(QdnfError::Range)?;
101            if end > fin {
102                return Err(QdnfError::Range);
103            }
104        }
105        if let Some(declared) = frame.declared_final {
106            self.final_size = Some(declared);
107        }
108        if frame.fin {
109            let end = frame
110                .offset
111                .checked_add(frame.len as u64)
112                .ok_or(QdnfError::Range)?;
113            match self.final_size {
114                Some(fin) if fin != end => return Err(QdnfError::Conflict),
115                None => self.final_size = Some(end),
116                Some(_) => {}
117            }
118        }
119        Ok(())
120    }
121
122    fn apply_in_order(
123        &mut self,
124        len: u16,
125        _fin: bool,
126        _declared: Option<u64>,
127    ) -> Result<(), QdnfError> {
128        let add = len as u32;
129        let next_unread = self.unread_bytes.saturating_add(add);
130        if next_unread > MAX_STREAM_BUFFER_BYTES {
131            return Err(QdnfError::Capacity);
132        }
133        self.next_offset = self
134            .next_offset
135            .checked_add(len as u64)
136            .ok_or(QdnfError::Range)?;
137        self.unread_bytes = next_unread;
138        Ok(())
139    }
140
141    fn buffer_ooo(&mut self, frame: StreamFrame) -> Result<(), QdnfError> {
142        let add = frame.len as u32;
143        if self.ooo_bytes.saturating_add(add) > MAX_STREAM_BUFFER_BYTES {
144            return Err(QdnfError::Capacity);
145        }
146        let mut free = None;
147        let mut i = 0usize;
148        while i < MAX_OOO_FRAMES {
149            match self.ooo[i] {
150                Some(existing) => {
151                    let existing_end = existing.offset.saturating_add(existing.len as u64);
152                    let incoming_end = frame.offset.saturating_add(frame.len as u64);
153                    if frame.offset < existing_end && existing.offset < incoming_end {
154                        return Err(QdnfError::Overlap);
155                    }
156                }
157                None if free.is_none() => free = Some(i),
158                None => {}
159            }
160            i += 1;
161        }
162        let idx = free.ok_or(QdnfError::Capacity)?;
163        self.ooo[idx] = Some(OooFrame {
164            offset: frame.offset,
165            len: frame.len,
166            fin: frame.fin,
167            declared_final: frame.declared_final,
168        });
169        self.ooo_bytes = self.ooo_bytes.saturating_add(add);
170        Ok(())
171    }
172
173    fn drain_ooo(&mut self) -> Result<(), QdnfError> {
174        loop {
175            let mut found = None;
176            let mut i = 0usize;
177            while i < MAX_OOO_FRAMES {
178                if let Some(f) = self.ooo[i] {
179                    if f.offset == self.next_offset {
180                        found = Some(i);
181                        break;
182                    }
183                }
184                i += 1;
185            }
186            match found {
187                None => return Ok(()),
188                Some(idx) => {
189                    let f = self.ooo[idx].take().unwrap();
190                    self.ooo_bytes = self.ooo_bytes.saturating_sub(f.len as u32);
191                    self.apply_in_order(f.len, f.fin, f.declared_final)?;
192                }
193            }
194        }
195    }
196}
197
198/// Independently controlled streams. Stall on id 0 does not block id 1.
199pub struct StreamTable {
200    states: [StreamState; MAX_STREAMS_PER_DIR],
201}
202
203impl StreamTable {
204    /// Creates a default `StreamTable`.
205    pub const fn new() -> Self {
206        Self {
207            states: [StreamState::new(); MAX_STREAMS_PER_DIR],
208        }
209    }
210
211    /// Routes `frame` to its stream state.
212    pub fn accept(&mut self, frame: StreamFrame) -> Result<(), QdnfError> {
213        let id = frame.stream_id as usize;
214        if id >= MAX_STREAMS_PER_DIR {
215            return Err(QdnfError::Capacity);
216        }
217        self.states[id].accept(frame)
218    }
219
220    /// Stream state for `id`; error when absent.
221    pub fn stream(&self, id: u16) -> Result<&StreamState, QdnfError> {
222        let idx = id as usize;
223        if idx >= MAX_STREAMS_PER_DIR {
224            return Err(QdnfError::Capacity);
225        }
226        Ok(&self.states[idx])
227    }
228
229    /// Mutable stream state for `id`.
230    pub fn stream_mut(&mut self, id: u16) -> Result<&mut StreamState, QdnfError> {
231        let idx = id as usize;
232        if idx >= MAX_STREAMS_PER_DIR {
233            return Err(QdnfError::Capacity);
234        }
235        Ok(&mut self.states[idx])
236    }
237}
238
239/// Head-of-line on one stream must not stall another stream that has credit.
240pub const fn stream_progress_isolated() -> bool {
241    true
242}
243
244#[cfg(test)]
245mod tests {
246    use super::*;
247
248    fn frame(id: u16, offset: u64, len: u16) -> StreamFrame {
249        StreamFrame {
250            stream_id: id,
251            offset,
252            fin: false,
253            declared_final: None,
254            len,
255        }
256    }
257
258    #[test]
259    fn final_size_conflict_is_rejected() {
260        let mut s = StreamState::new();
261        s.accept(StreamFrame {
262            stream_id: 0,
263            offset: 0,
264            fin: true,
265            declared_final: Some(4),
266            len: 4,
267        })
268        .unwrap();
269        assert_eq!(
270            s.accept(StreamFrame {
271                stream_id: 0,
272                offset: 4,
273                fin: true,
274                declared_final: Some(8),
275                len: 0,
276            }),
277            Err(QdnfError::Conflict)
278        );
279    }
280
281    #[test]
282    fn stream_progress_isolated_true() {
283        assert!(stream_progress_isolated());
284    }
285
286    #[test]
287    fn stalled_stream_zero_does_not_block_stream_one() {
288        let mut t = StreamTable::new();
289        let mut i = 0u16;
290        while i < MAX_OOO_FRAMES as u16 {
291            t.accept(frame(0, 100 + u64::from(i) * 10, 8)).unwrap();
292            i += 1;
293        }
294        assert_eq!(t.accept(frame(0, 200, 8)), Err(QdnfError::Capacity));
295        assert_eq!(t.stream(0).unwrap().next_offset, 0);
296        t.accept(frame(1, 0, 16)).unwrap();
297        assert_eq!(t.stream(1).unwrap().next_offset, 16);
298        assert!(stream_progress_isolated());
299    }
300
301    #[test]
302    fn unread_cap_stalls_only_that_stream() {
303        let mut t = StreamTable::new();
304        t.accept(frame(0, 0, 4096)).unwrap();
305        assert_eq!(t.accept(frame(0, 4096, 1)), Err(QdnfError::Capacity));
306        t.accept(frame(1, 0, 32)).unwrap();
307        assert_eq!(t.stream(1).unwrap().next_offset, 32);
308        t.stream_mut(0).unwrap().consume(8).unwrap();
309        t.accept(frame(0, 4096, 8)).unwrap();
310        assert_eq!(t.stream(0).unwrap().next_offset, 4104);
311    }
312
313    #[test]
314    fn ooo_drain_when_gap_filled() {
315        let mut s = StreamState::new();
316        s.accept(frame(0, 8, 8)).unwrap();
317        assert_eq!(s.next_offset, 0);
318        s.accept(frame(0, 0, 8)).unwrap();
319        assert_eq!(s.next_offset, 16);
320        assert_eq!(s.unread_bytes(), 16);
321    }
322}