hibana 0.9.6

Choreography-derived runtime enforcement kernel for no_std Rust multiparty protocols
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! TapEvent encoders owned by runtime operations.
//!
//! Production callers use the event owner that matches the runtime operation.

use super::core::TapEvent;
use super::ids;
use crate::global::const_dsl::{ScopeId, ScopeKind};

// ────────────── Endpoint boundary (0x0200-0x020F) ──────────────

// ────────────── Lane lifecycle (0x0210-0x021F) ──────────────

/// Session/lane association count moved 0->1.
#[inline(always)]
pub(crate) const fn lane_acquire(rv_id: u32, sid: u32, lane: u16) -> TapEvent {
    let rv_lane = (rv_id << 16) | (lane as u32);
    TapEvent::new(0, ids::LANE_ACQUIRE, 0, sid, rv_lane)
}

/// Session/lane association count moved 1->0.
#[inline(always)]
pub(crate) const fn lane_release(rv_id: u32, sid: u32, lane: u16) -> TapEvent {
    let rv_lane = (rv_id << 16) | (lane as u32);
    TapEvent::new(0, ids::LANE_RELEASE, 0, sid, rv_lane)
}

// ────────────── Route decision (0x0220-0x022F) ──────────────

/// Route arm selection resolved.
#[inline(always)]
pub(crate) const fn route_arm_selection_with_causal(
    causal: u16,
    sid: u32,
    scope_id: ScopeId,
    arm: u8,
) -> TapEvent {
    let arg1 = ((route_site(scope_id) as u32) << 16) | (arm as u32);
    TapEvent::new(0, ids::ROUTE_ARM_SELECTION, causal, sid, arg1)
}

// ────────────── Misuse detection (0x02FF) ──────────────

// ────────────── Resolver audit (0x0400-0x041F) ──────────────

#[inline(always)]
pub(crate) const fn resolver_audit(
    lane: u8,
    sid: u32,
    scope_id: ScopeId,
    resolver_id: u16,
    result: u8,
) -> TapEvent {
    let causal = TapEvent::make_causal_key(lane, result);
    let arg1 = ((route_site(scope_id) as u32) << 16) | (resolver_id as u32);
    TapEvent::new(0, ids::RESOLVER_AUDIT, causal, sid, arg1)
}

#[inline(always)]
const fn route_site(scope_id: ScopeId) -> u16 {
    if !matches!(scope_id.kind(), Some(ScopeKind::Route)) {
        crate::invariant();
    }
    scope_id.local_ordinal()
}

// ────────────── Raw builder for fixed event encoders ──────────────

/// Raw TapEvent builder for callers that already own the event identifier.
#[inline(always)]
pub(crate) const fn raw_event(id: u16) -> TapEvent {
    TapEvent::new(0, id, 0, 0, 0)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn route_site_evidence_uses_scope_local_ordinal() {
        let first = route_arm_selection_with_causal(2, 3, ScopeId::route(0), 1);
        let second = route_arm_selection_with_causal(2, 3, ScopeId::route(1), 1);
        assert_eq!(first.arg1() >> 16, 0);
        assert_eq!(second.arg1() >> 16, 1);
        assert_eq!(first.arg1() & 0xffff, 1);
        assert_eq!(second.arg1() & 0xffff, 1);

        let first_audit = resolver_audit(7, 3, ScopeId::route(0), 77, 0);
        let second_audit = resolver_audit(7, 3, ScopeId::route(1), 77, 0);
        assert_eq!(first_audit.arg1() >> 16, 0);
        assert_eq!(second_audit.arg1() >> 16, 1);
        assert_eq!(first_audit.arg1() & 0xffff, 77);
        assert_eq!(second_audit.arg1() & 0xffff, 77);
        assert_eq!(first_audit.causal_key(), second_audit.causal_key());
    }

    #[test]
    #[should_panic]
    fn route_site_rejects_non_route_scope() {
        let _ = route_arm_selection_with_causal(2, 3, ScopeId::roll_scope(0), 1);
    }

    #[test]
    #[should_panic]
    fn route_site_rejects_out_of_domain_scope() {
        let _ = route_arm_selection_with_causal(2, 3, ScopeId::route(ScopeId::LOCAL_CAPACITY), 1);
    }
}