Skip to main content

qualia_core_db/net/qdnf/session/
credit.rs

1//! Stream receive credit backed by RT-01 ledger + lease reservations.
2//!
3//! NET-05.07 (partial, packages remain open): every granted stream receive
4//! window is charged on [`ReservationLedger`] and physically backed by a
5//! direction-aggregate [`BufferLease`] so out-of-order buffers cannot hide
6//! overcommit. 64 streams per direction class; purchased service does not
7//! disable congestion/fairness (NET-05.09 partial). ACK range cap is 8
8//! (NET-05.08 partial).
9//!
10//! One lease slot backs the configured direction window (aggregate), not one
11//! slot per stream. `LeaseTable` has 32 slots; the protocol limit is 64.
12
13use crate::net::peer::runtime::ledger::ChargeRef;
14use crate::net::peer::runtime::{
15    BufferLease, LeaseHandle, LeaseTable, ReservationHandle, ReservationLedger, ResourceBudget,
16};
17use crate::net::qdnf::errors::QdnfError;
18
19pub use super::streams::MAX_STREAMS_PER_DIR;
20
21pub const MAX_ACK_RANGES: usize = 8;
22
23/// Bidirectional client-initiated streams.
24pub const DIR_CLIENT: u8 = 0;
25/// Server-initiated streams.
26pub const DIR_SERVER: u8 = 1;
27
28#[repr(C)]
29#[derive(Clone, Copy, Debug, PartialEq, Eq)]
30pub struct StreamCredit {
31    pub dir: u8,
32    pub open: u8,
33    pub window_bytes: u32,
34}
35
36pub struct CreditTable {
37    client: StreamCredit,
38    server: StreamCredit,
39    client_used: u32,
40    server_used: u32,
41    client_lease: Option<BufferLease>,
42    server_lease: Option<BufferLease>,
43    client_charge: Option<ChargeRef>,
44    server_charge: Option<ChargeRef>,
45}
46
47impl CreditTable {
48    /// Creates a default `CreditTable`.
49    pub fn new(window_bytes: u32) -> Self {
50        Self {
51            client: StreamCredit {
52                dir: DIR_CLIENT,
53                open: 0,
54                window_bytes,
55            },
56            server: StreamCredit {
57                dir: DIR_SERVER,
58                open: 0,
59                window_bytes,
60            },
61            client_used: 0,
62            server_used: 0,
63            client_lease: None,
64            server_lease: None,
65            client_charge: None,
66            server_charge: None,
67        }
68    }
69
70    fn charge_mut(&mut self, dir: u8) -> Result<&mut Option<ChargeRef>, QdnfError> {
71        match dir {
72            DIR_CLIENT => Ok(&mut self.client_charge),
73            DIR_SERVER => Ok(&mut self.server_charge),
74            _ => Err(QdnfError::Range),
75        }
76    }
77
78    /// One ledger handle per direction (aggregate), matching the lease.
79    fn sync_ledger(
80        &mut self,
81        dir: u8,
82        ledger: &mut ReservationLedger,
83        bytes: u32,
84    ) -> Result<(), QdnfError> {
85        if bytes == 0 {
86            if let Some(r) = self.charge_mut(dir)?.take() {
87                ledger.release(ReservationHandle::from_ref(r))?;
88            }
89            return Ok(());
90        }
91        let handle = ledger.reserve(stream_bytes_budget(bytes), true)?;
92        let old = self.charge_mut(dir)?.replace(handle.as_ref());
93        if let Some(r) = old {
94            if let Err(e) = ledger.release(ReservationHandle::from_ref(r)) {
95                let _ = ledger.release(handle);
96                *self.charge_mut(dir)? = None;
97                return Err(e);
98            }
99        }
100        Ok(())
101    }
102
103    /// Grant one stream in `dir`. Ledger + first-open lease are all-or-nothing
104    /// (failed lease acquire releases the ledger charge), matching cell admit.
105    ///
106    /// The returned [`BufferLease`] is the direction-aggregate backing handle.
107    /// `close_stream` releases the physical lease only when that direction's
108    /// last stream closes.
109    pub fn open_stream(
110        &mut self,
111        dir: u8,
112        leases: &mut LeaseTable,
113        ledger: &mut ReservationLedger,
114        bytes: u32,
115    ) -> Result<BufferLease, QdnfError> {
116        {
117            let credit = self.credit(dir)?;
118            if credit.open as usize >= MAX_STREAMS_PER_DIR {
119                return Err(QdnfError::Capacity);
120            }
121            let used = self.used(dir)?;
122            let next_used = used.checked_add(bytes).ok_or(QdnfError::Range)?;
123            if next_used > credit.window_bytes {
124                return Err(QdnfError::Capacity);
125            }
126        }
127
128        let prior_used = self.used(dir)?;
129        let next_used = prior_used.saturating_add(bytes);
130        if bytes > 0 {
131            self.sync_ledger(dir, ledger, next_used)?;
132        }
133
134        let credit = self.credit(dir)?;
135        let first = credit.open == 0;
136        if first && credit.window_bytes > 0 {
137            match leases.acquire(credit.window_bytes, true) {
138                Ok(lease) => {
139                    *self.lease_mut(dir)? = Some(lease);
140                }
141                Err(e) => {
142                    if bytes > 0 {
143                        let _ = self.sync_ledger(dir, ledger, prior_used);
144                    }
145                    return Err(e);
146                }
147            }
148        }
149        let next_open = credit.open.saturating_add(1);
150        *self.used_mut(dir)? = next_used;
151        self.credit_mut(dir)?.open = next_open;
152
153        Ok(match self.lease_copy(dir)? {
154            Some(agg) => BufferLease {
155                handle: agg.handle,
156                capacity: bytes,
157                initialized: 0,
158                exclusive: true,
159            },
160            None => BufferLease {
161                handle: LeaseHandle::INVALID,
162                capacity: bytes,
163                initialized: 0,
164                exclusive: false,
165            },
166        })
167    }
168
169    /// Closes `stream`.
170    pub fn close_stream(
171        &mut self,
172        dir: u8,
173        leases: &mut LeaseTable,
174        ledger: &mut ReservationLedger,
175        lease: BufferLease,
176        bytes: u32,
177    ) -> Result<(), QdnfError> {
178        let credit = self.credit(dir)?;
179        if credit.open == 0 {
180            return Err(QdnfError::DoubleRelease);
181        }
182        let used = self.used(dir)?;
183        if bytes > used {
184            return Err(QdnfError::Range);
185        }
186        if let Some(agg) = self.lease_copy(dir)? {
187            if lease.handle != LeaseHandle::INVALID && lease.handle != agg.handle {
188                return Err(QdnfError::StaleGeneration);
189            }
190        }
191
192        let last = credit.open == 1;
193        if last {
194            if let Some(agg) = self.lease_copy(dir)? {
195                leases.release(agg.handle)?;
196                *self.lease_mut(dir)? = None;
197            } else if lease.handle != LeaseHandle::INVALID {
198                leases.release(lease.handle)?;
199            }
200        }
201
202        let next_used = used.saturating_sub(bytes);
203        if bytes > 0 {
204            self.sync_ledger(dir, ledger, next_used)?;
205        }
206        *self.used_mut(dir)? = next_used;
207        self.credit_mut(dir)?.open = credit.open.saturating_sub(1);
208        Ok(())
209    }
210
211    /// Remaining application window for `dir`. Not a congestion window.
212    pub fn remaining(&self, dir: u8) -> Result<u32, QdnfError> {
213        let window = self.credit(dir)?.window_bytes;
214        let used = self.used(dir)?;
215        Ok(window.saturating_sub(used))
216    }
217
218    /// Application flow-control admit. Exhaustion is Capacity, not BudgetExhausted.
219    pub fn admit_application(&self, dir: u8, bytes: u64) -> Result<(), QdnfError> {
220        if bytes == 0 || bytes > u32::MAX as u64 {
221            return Err(QdnfError::Range);
222        }
223        if bytes > self.remaining(dir)? as u64 {
224            Err(QdnfError::Capacity)
225        } else {
226            Ok(())
227        }
228    }
229
230    /// Credits the session.
231    pub fn credit(&self, dir: u8) -> Result<StreamCredit, QdnfError> {
232        match dir {
233            DIR_CLIENT => Ok(self.client),
234            DIR_SERVER => Ok(self.server),
235            _ => Err(QdnfError::Range),
236        }
237    }
238
239    fn credit_mut(&mut self, dir: u8) -> Result<&mut StreamCredit, QdnfError> {
240        match dir {
241            DIR_CLIENT => Ok(&mut self.client),
242            DIR_SERVER => Ok(&mut self.server),
243            _ => Err(QdnfError::Range),
244        }
245    }
246
247    fn used(&self, dir: u8) -> Result<u32, QdnfError> {
248        match dir {
249            DIR_CLIENT => Ok(self.client_used),
250            DIR_SERVER => Ok(self.server_used),
251            _ => Err(QdnfError::Range),
252        }
253    }
254
255    fn used_mut(&mut self, dir: u8) -> Result<&mut u32, QdnfError> {
256        match dir {
257            DIR_CLIENT => Ok(&mut self.client_used),
258            DIR_SERVER => Ok(&mut self.server_used),
259            _ => Err(QdnfError::Range),
260        }
261    }
262
263    fn lease_mut(&mut self, dir: u8) -> Result<&mut Option<BufferLease>, QdnfError> {
264        match dir {
265            DIR_CLIENT => Ok(&mut self.client_lease),
266            DIR_SERVER => Ok(&mut self.server_lease),
267            _ => Err(QdnfError::Range),
268        }
269    }
270
271    fn lease_copy(&self, dir: u8) -> Result<Option<BufferLease>, QdnfError> {
272        match dir {
273            DIR_CLIENT => Ok(self.client_lease),
274            DIR_SERVER => Ok(self.server_lease),
275            _ => Err(QdnfError::Range),
276        }
277    }
278}
279
280/// Purchased / priority service must not turn off congestion or fairness
281/// (control vs background still share WorkClass queues).
282pub fn purchased_service_disables_congestion() -> bool {
283    false
284}
285
286/// `CreditTable::ack_range_cap`.
287pub fn ack_range_cap() -> usize {
288    MAX_ACK_RANGES
289}
290
291fn stream_bytes_budget(bytes: u32) -> ResourceBudget {
292    ResourceBudget {
293        bytes: bytes as u64,
294        work: 0,
295        io: 0,
296    }
297}
298
299#[cfg(test)]
300mod tests {
301    use super::*;
302
303    const STREAM_BYTES: u32 = 256;
304    const WINDOW: u32 = STREAM_BYTES * MAX_STREAMS_PER_DIR as u32;
305
306    fn fat_ledger() -> ReservationLedger {
307        let cap = ResourceBudget {
308            bytes: WINDOW as u64 * 4,
309            work: 64,
310            io: 64,
311        };
312        ReservationLedger::new(cap, cap, cap, cap, cap)
313    }
314
315    fn fixtures() -> (CreditTable, LeaseTable, ReservationLedger) {
316        (CreditTable::new(WINDOW), LeaseTable::new(), fat_ledger())
317    }
318
319    #[test]
320    fn sixty_four_opens_dir0_ok_sixty_fifth_capacity() {
321        let (mut table, mut leases, mut ledger) = fixtures();
322        let mut last = None;
323        let mut i = 0;
324        while i < MAX_STREAMS_PER_DIR {
325            last = Some(
326                table
327                    .open_stream(DIR_CLIENT, &mut leases, &mut ledger, STREAM_BYTES)
328                    .expect("dir 0 stream within 64"),
329            );
330            i += 1;
331        }
332        assert_eq!(
333            table.credit(DIR_CLIENT).unwrap().open as usize,
334            MAX_STREAMS_PER_DIR
335        );
336        assert_eq!(leases.occupied_count(), 1);
337        assert_eq!(
338            table.open_stream(DIR_CLIENT, &mut leases, &mut ledger, STREAM_BYTES),
339            Err(QdnfError::Capacity)
340        );
341        assert_eq!(
342            table.credit(DIR_CLIENT).unwrap().open as usize,
343            MAX_STREAMS_PER_DIR
344        );
345        assert!(last.is_some());
346    }
347
348    #[test]
349    fn other_dir_independent_sixty_four() {
350        let (mut table, mut leases, mut ledger) = fixtures();
351        let mut i = 0;
352        while i < MAX_STREAMS_PER_DIR {
353            table
354                .open_stream(DIR_CLIENT, &mut leases, &mut ledger, STREAM_BYTES)
355                .expect("dir 0 fill");
356            i += 1;
357        }
358        assert_eq!(
359            table.open_stream(DIR_CLIENT, &mut leases, &mut ledger, STREAM_BYTES),
360            Err(QdnfError::Capacity)
361        );
362        table
363            .open_stream(DIR_SERVER, &mut leases, &mut ledger, STREAM_BYTES)
364            .expect("dir 1 still has its own 64");
365        assert_eq!(table.credit(DIR_SERVER).unwrap().open, 1);
366        assert_eq!(leases.occupied_count(), 2);
367        i = 1;
368        while i < MAX_STREAMS_PER_DIR {
369            table
370                .open_stream(DIR_SERVER, &mut leases, &mut ledger, STREAM_BYTES)
371                .expect("dir 1 within 64");
372            i += 1;
373        }
374        assert_eq!(
375            table.open_stream(DIR_SERVER, &mut leases, &mut ledger, STREAM_BYTES),
376            Err(QdnfError::Capacity)
377        );
378        assert_eq!(
379            table.credit(DIR_SERVER).unwrap().open as usize,
380            MAX_STREAMS_PER_DIR
381        );
382    }
383
384    #[test]
385    fn purchased_service_does_not_disable_congestion() {
386        assert!(!purchased_service_disables_congestion());
387    }
388
389    #[test]
390    fn ack_range_cap_is_eight() {
391        assert_eq!(ack_range_cap(), 8);
392        assert_eq!(ack_range_cap(), MAX_ACK_RANGES);
393    }
394
395    #[test]
396    fn close_releases_lease_and_reopen_succeeds() {
397        let (mut table, mut leases, mut ledger) = fixtures();
398        let lease = table
399            .open_stream(DIR_CLIENT, &mut leases, &mut ledger, STREAM_BYTES)
400            .expect("open");
401        assert_eq!(leases.occupied_count(), 1);
402        assert_eq!(ledger.used().session.bytes, STREAM_BYTES as u64);
403        table
404            .close_stream(DIR_CLIENT, &mut leases, &mut ledger, lease, STREAM_BYTES)
405            .expect("close");
406        assert_eq!(leases.occupied_count(), 0);
407        assert_eq!(table.credit(DIR_CLIENT).unwrap().open, 0);
408        assert_eq!(ledger.used().session.bytes, 0);
409        let again = table
410            .open_stream(DIR_CLIENT, &mut leases, &mut ledger, STREAM_BYTES)
411            .expect("reopen after close");
412        assert_eq!(leases.occupied_count(), 1);
413        table
414            .close_stream(DIR_CLIENT, &mut leases, &mut ledger, again, STREAM_BYTES)
415            .expect("second close");
416        assert_eq!(leases.occupied_count(), 0);
417        assert_eq!(
418            table.close_stream(DIR_CLIENT, &mut leases, &mut ledger, again, STREAM_BYTES),
419            Err(QdnfError::DoubleRelease)
420        );
421    }
422
423    #[test]
424    fn remaining_is_application_credit_not_congestion() {
425        let table = CreditTable::new(0);
426        assert_eq!(table.remaining(DIR_CLIENT).unwrap(), 0);
427        assert_eq!(
428            table.admit_application(DIR_CLIENT, 1),
429            Err(QdnfError::Capacity)
430        );
431        let open = CreditTable::new(STREAM_BYTES);
432        open.admit_application(DIR_CLIENT, STREAM_BYTES as u64)
433            .expect("full remaining window");
434        assert!(!purchased_service_disables_congestion());
435    }
436
437    #[test]
438    fn window_ceiling_rejects_hidden_overcommit() {
439        let mut table = CreditTable::new(STREAM_BYTES);
440        let mut leases = LeaseTable::new();
441        let mut ledger = fat_ledger();
442        table
443            .open_stream(DIR_CLIENT, &mut leases, &mut ledger, STREAM_BYTES)
444            .expect("exact window");
445        assert_eq!(
446            table.open_stream(DIR_CLIENT, &mut leases, &mut ledger, 1),
447            Err(QdnfError::Capacity)
448        );
449        assert_eq!(table.credit(DIR_CLIENT).unwrap().open, 1);
450        assert_eq!(ledger.used().session.bytes, STREAM_BYTES as u64);
451    }
452}