Skip to main content

qualia_core_db/net/qdnf/session/
recovery.rs

1//! Reconnect recovery for application operations (NET-05.16 partial).
2//!
3//! Durable application (`DurableApplied`) and economic (`EconomicReceipt`)
4//! stages occupy a slot in [`RecoveryTable`]. Transport ACK and consumption
5//! are recorded separately and never count as accepted work or payment.
6//! Cancellation is owned by [`OperationTable`]; this module does not copy
7//! that kernel's slot table. Packages remain open.
8
9use crate::net::qdnf::errors::QdnfError;
10use crate::net::qdnf::session::datagrams::DeliveryStage;
11use crate::net::qdnf::types::OperationId;
12
13/// Re-export the peer-runtime cancel kernel. Session recovery does not copy its slot table.
14pub use crate::net::peer::runtime::cancel::{CancelEpoch, OperationHandle, OperationTable};
15
16/// Occupied durable-receipt slots. A 17th distinct durable id is Capacity.
17pub const MAX_DURABLE: usize = 16;
18
19/// Reconnect decision. Transport-only delivery does not skip durable work.
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21pub enum ReconnectOutcome {
22    /// Never durably applied; the caller may proceed.
23    NeedsWork,
24    /// DurableApplied or EconomicReceipt already recorded; must not duplicate.
25    AlreadyDurable,
26    /// Transport ACK or consumption exists; still not durable.
27    TransportOnly,
28}
29
30#[repr(C)]
31#[derive(Clone, Copy, Debug, PartialEq, Eq)]
32struct StageRecord {
33    id: OperationId,
34    stage: DeliveryStage,
35}
36
37/// Sixteen durable slots plus sixteen transport-observation slots. Copy-friendly.
38#[derive(Clone, Copy, Debug)]
39pub struct RecoveryTable {
40    durable: [Option<StageRecord>; MAX_DURABLE],
41    transport: [Option<StageRecord>; MAX_DURABLE],
42}
43
44impl RecoveryTable {
45    /// Creates a default `RecoveryTable`.
46    pub const fn new() -> Self {
47        Self {
48            durable: [None; MAX_DURABLE],
49            transport: [None; MAX_DURABLE],
50        }
51    }
52
53    /// Occupied durable slots. Transport observations are excluded.
54    pub fn durable_len(&self) -> usize {
55        let mut n = 0usize;
56        let mut i = 0usize;
57        while i < MAX_DURABLE {
58            if self.durable[i].is_some() {
59                n += 1;
60            }
61            i += 1;
62        }
63        n
64    }
65
66    fn find_durable(&self, id: OperationId) -> Option<usize> {
67        let mut i = 0usize;
68        while i < MAX_DURABLE {
69            if let Some(rec) = self.durable[i] {
70                if rec.id == id {
71                    return Some(i);
72                }
73            }
74            i += 1;
75        }
76        None
77    }
78
79    fn find_transport(&self, id: OperationId) -> Option<usize> {
80        let mut i = 0usize;
81        while i < MAX_DURABLE {
82            if let Some(rec) = self.transport[i] {
83                if rec.id == id {
84                    return Some(i);
85                }
86            }
87            i += 1;
88        }
89        None
90    }
91
92    fn first_free_durable(&self) -> Option<usize> {
93        let mut i = 0usize;
94        while i < MAX_DURABLE {
95            if self.durable[i].is_none() {
96                return Some(i);
97            }
98            i += 1;
99        }
100        None
101    }
102
103    fn first_free_transport(&self) -> Option<usize> {
104        let mut i = 0usize;
105        while i < MAX_DURABLE {
106            if self.transport[i].is_none() {
107                return Some(i);
108            }
109            i += 1;
110        }
111        None
112    }
113}
114
115impl Default for RecoveryTable {
116    fn default() -> Self {
117        Self::new()
118    }
119}
120
121/// Durable application and economic receipts only.
122#[inline]
123pub fn stage_is_durable(stage: DeliveryStage) -> bool {
124    matches!(
125        stage,
126        DeliveryStage::DurableApplied | DeliveryStage::EconomicReceipt
127    )
128}
129
130/// Transport ACK / consumption never imply accepted work or payment.
131#[inline]
132pub fn transport_delivery_is_accepted_work() -> bool {
133    false
134}
135
136/// Reconnect must not emit a second durable effect for a recorded id.
137#[inline]
138pub fn reconnect_may_duplicate_durable() -> bool {
139    false
140}
141
142/// Record that `id` reached `stage`.
143///
144/// `TransportAck` / `Consumed` never occupy a durable slot.
145/// `DurableApplied` / `EconomicReceipt` occupy one durable slot; repeating the
146/// same durable stage for the same id is idempotent (not Conflict).
147pub fn record_stage(
148    table: &mut RecoveryTable,
149    id: OperationId,
150    stage: DeliveryStage,
151) -> Result<(), QdnfError> {
152    if id == OperationId::ZERO {
153        return Err(QdnfError::Malformed);
154    }
155    if stage_is_durable(stage) {
156        record_durable(table, id, stage)
157    } else {
158        record_transport(table, id, stage)
159    }
160}
161
162fn record_durable(
163    table: &mut RecoveryTable,
164    id: OperationId,
165    stage: DeliveryStage,
166) -> Result<(), QdnfError> {
167    if let Some(idx) = table.find_durable(id) {
168        if let Some(rec) = &mut table.durable[idx] {
169            if stage_rank(stage) > stage_rank(rec.stage) {
170                rec.stage = stage;
171            }
172        }
173        return Ok(());
174    }
175    let idx = table.first_free_durable().ok_or(QdnfError::Capacity)?;
176    table.durable[idx] = Some(StageRecord { id, stage });
177    Ok(())
178}
179
180fn record_transport(
181    table: &mut RecoveryTable,
182    id: OperationId,
183    stage: DeliveryStage,
184) -> Result<(), QdnfError> {
185    if let Some(idx) = table.find_transport(id) {
186        if let Some(rec) = &mut table.transport[idx] {
187            if stage_rank(stage) > stage_rank(rec.stage) {
188                rec.stage = stage;
189            }
190        }
191        return Ok(());
192    }
193    let idx = table.first_free_transport().ok_or(QdnfError::Capacity)?;
194    table.transport[idx] = Some(StageRecord { id, stage });
195    Ok(())
196}
197
198#[inline]
199fn stage_rank(stage: DeliveryStage) -> u8 {
200    stage as u8
201}
202
203/// Reconnect attempt for `id`.
204///
205/// Already-durable ids return [`ReconnectOutcome::AlreadyDurable`] without a
206/// second durable effect. Cancellation from [`OperationTable`] returns
207/// [`QdnfError::Cancelled`]. Transport ACK / consumption alone is not enough
208/// to skip work.
209pub fn reconnect(
210    table: &RecoveryTable,
211    ops: &OperationTable,
212    id: OperationId,
213) -> Result<ReconnectOutcome, QdnfError> {
214    if id == OperationId::ZERO {
215        return Err(QdnfError::Malformed);
216    }
217    if table.find_durable(id).is_some() {
218        return Ok(ReconnectOutcome::AlreadyDurable);
219    }
220    if ops.is_cancelled(id) {
221        return Err(QdnfError::Cancelled);
222    }
223    if table.find_transport(id).is_some() {
224        return Ok(ReconnectOutcome::TransportOnly);
225    }
226    Ok(ReconnectOutcome::NeedsWork)
227}
228
229#[cfg(test)]
230mod tests {
231    use super::*;
232    use crate::net::peer::runtime::cancel::OperationTable;
233    use crate::net::peer::runtime::leases::LeaseTable;
234
235    fn op(n: u8) -> OperationId {
236        let mut id = [0u8; 16];
237        id[0] = n;
238        OperationId(id)
239    }
240
241    #[test]
242    fn reconnect_after_durable_applied_is_already_durable() {
243        let mut table = RecoveryTable::new();
244        let ops = OperationTable::new();
245        let id = op(1);
246        assert!(record_stage(&mut table, id, DeliveryStage::DurableApplied).is_ok());
247        assert_eq!(table.durable_len(), 1);
248        assert_eq!(
249            reconnect(&table, &ops, id),
250            Ok(ReconnectOutcome::AlreadyDurable)
251        );
252        assert_eq!(table.durable_len(), 1);
253        assert!(!reconnect_may_duplicate_durable());
254    }
255
256    #[test]
257    fn transport_ack_reconnect_is_not_already_durable() {
258        let mut table = RecoveryTable::new();
259        let ops = OperationTable::new();
260        let id = op(2);
261        assert!(record_stage(&mut table, id, DeliveryStage::TransportAck).is_ok());
262        assert_eq!(table.durable_len(), 0);
263        let outcome = reconnect(&table, &ops, id).unwrap();
264        assert_ne!(outcome, ReconnectOutcome::AlreadyDurable);
265        assert_eq!(outcome, ReconnectOutcome::TransportOnly);
266        assert!(record_stage(&mut table, id, DeliveryStage::Consumed).is_ok());
267        assert_eq!(
268            reconnect(&table, &ops, id),
269            Ok(ReconnectOutcome::TransportOnly)
270        );
271        assert_eq!(table.durable_len(), 0);
272    }
273
274    #[test]
275    fn cancel_then_reconnect_is_cancelled() {
276        let table = RecoveryTable::new();
277        let mut leases = LeaseTable::new();
278        let mut ops = OperationTable::new();
279        let lease = leases.acquire(8, true).unwrap();
280        let id = op(3);
281        let _handle: OperationHandle = ops.admit(id, lease.handle).unwrap();
282        let _epoch: CancelEpoch = ops.cancel(id).unwrap();
283        assert_eq!(reconnect(&table, &ops, id), Err(QdnfError::Cancelled));
284        assert_eq!(table.durable_len(), 0);
285    }
286
287    #[test]
288    fn economic_receipt_is_durable() {
289        let mut table = RecoveryTable::new();
290        let ops = OperationTable::new();
291        let id = op(4);
292        assert!(record_stage(&mut table, id, DeliveryStage::EconomicReceipt).is_ok());
293        assert_eq!(table.durable_len(), 1);
294        assert_eq!(
295            reconnect(&table, &ops, id),
296            Ok(ReconnectOutcome::AlreadyDurable)
297        );
298        assert!(stage_is_durable(DeliveryStage::EconomicReceipt));
299        assert!(!stage_is_durable(DeliveryStage::TransportAck));
300        assert!(!stage_is_durable(DeliveryStage::Consumed));
301    }
302
303    #[test]
304    fn transport_delivery_is_not_accepted_work() {
305        assert!(!transport_delivery_is_accepted_work());
306        assert!(!reconnect_may_duplicate_durable());
307    }
308
309    #[test]
310    fn seventeenth_distinct_durable_is_capacity() {
311        let mut table = RecoveryTable::new();
312        let mut n = 1u8;
313        while n <= MAX_DURABLE as u8 {
314            assert!(record_stage(&mut table, op(n), DeliveryStage::DurableApplied).is_ok());
315            n += 1;
316        }
317        assert_eq!(table.durable_len(), MAX_DURABLE);
318        assert_eq!(
319            record_stage(&mut table, op(17), DeliveryStage::DurableApplied),
320            Err(QdnfError::Capacity)
321        );
322        assert_eq!(table.durable_len(), MAX_DURABLE);
323        assert!(record_stage(&mut table, op(1), DeliveryStage::DurableApplied).is_ok());
324        assert_eq!(table.durable_len(), MAX_DURABLE);
325    }
326
327    #[test]
328    fn zero_operation_id_is_malformed() {
329        let mut table = RecoveryTable::new();
330        let ops = OperationTable::new();
331        assert_eq!(
332            record_stage(&mut table, OperationId::ZERO, DeliveryStage::DurableApplied),
333            Err(QdnfError::Malformed)
334        );
335        assert_eq!(
336            record_stage(&mut table, OperationId::ZERO, DeliveryStage::TransportAck),
337            Err(QdnfError::Malformed)
338        );
339        assert_eq!(
340            reconnect(&table, &ops, OperationId::ZERO),
341            Err(QdnfError::Malformed)
342        );
343        assert_eq!(table.durable_len(), 0);
344    }
345
346    #[test]
347    fn duplicate_durable_applied_is_idempotent() {
348        let mut table = RecoveryTable::new();
349        let ops = OperationTable::new();
350        let id = op(8);
351        assert!(record_stage(&mut table, id, DeliveryStage::DurableApplied).is_ok());
352        assert_eq!(
353            record_stage(&mut table, id, DeliveryStage::DurableApplied),
354            Ok(())
355        );
356        assert_ne!(
357            record_stage(&mut table, id, DeliveryStage::DurableApplied),
358            Err(QdnfError::Conflict)
359        );
360        assert_eq!(table.durable_len(), 1);
361        assert_eq!(
362            reconnect(&table, &ops, id),
363            Ok(ReconnectOutcome::AlreadyDurable)
364        );
365        assert!(record_stage(&mut table, id, DeliveryStage::EconomicReceipt).is_ok());
366        assert_eq!(table.durable_len(), 1);
367    }
368}