moonpool_core/
well_known.rs

1//! Well-known endpoint tokens for system services.
2//!
3//! These are compile-time constants matching FDB's WLTOKEN_* enum.
4//! Well-known tokens enable O(1) lookup in the endpoint map via array indexing
5//! (first part is u64::MAX, second part is the index).
6
7use crate::types::UID;
8
9/// Well-known endpoint tokens (FDB-compatible pattern).
10///
11/// These tokens are used for system services that need deterministic addressing
12/// without service discovery. Clients can construct endpoints directly using
13/// these well-known tokens.
14///
15/// # FDB Reference
16/// From FlowTransport.h:
17/// ```cpp
18/// enum { WLTOKEN_ENDPOINT_NOT_FOUND = 0, WLTOKEN_PING_PACKET,
19///        WLTOKEN_UNAUTHORIZED_ENDPOINT, WLTOKEN_FIRST_AVAILABLE };
20/// ```
21#[repr(u32)]
22#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
23pub enum WellKnownToken {
24    /// Response sent when an endpoint is not found.
25    /// Used to notify senders that their target doesn't exist.
26    EndpointNotFound = 0,
27
28    /// Ping for connection health checks.
29    /// Used by the connection monitor to detect failures.
30    Ping = 1,
31
32    /// Unauthorized endpoint access response.
33    /// Sent when a client tries to access a protected endpoint.
34    UnauthorizedEndpoint = 2,
35
36    /// First available token for user services.
37    /// User-defined well-known services should use this value or higher.
38    FirstAvailable = 3,
39}
40
41impl WellKnownToken {
42    /// Convert to u32 for UID creation.
43    pub const fn as_u32(self) -> u32 {
44        self as u32
45    }
46
47    /// Create a UID for this well-known token.
48    pub const fn uid(self) -> UID {
49        UID::well_known(self as u32)
50    }
51}
52
53/// Number of reserved well-known token slots.
54///
55/// The endpoint map reserves an array of this size for O(1) lookup
56/// of well-known endpoints. Tokens 0-63 are reserved for system use.
57///
58/// Matches FDB's WLTOKEN_RESERVED_COUNT pattern.
59pub const WELL_KNOWN_RESERVED_COUNT: usize = 64;
60
61#[cfg(test)]
62mod tests {
63    use super::*;
64
65    #[test]
66    fn test_well_known_token_values() {
67        assert_eq!(WellKnownToken::EndpointNotFound.as_u32(), 0);
68        assert_eq!(WellKnownToken::Ping.as_u32(), 1);
69        assert_eq!(WellKnownToken::UnauthorizedEndpoint.as_u32(), 2);
70        assert_eq!(WellKnownToken::FirstAvailable.as_u32(), 3);
71    }
72
73    #[test]
74    fn test_well_known_uid() {
75        let uid = WellKnownToken::Ping.uid();
76        assert!(uid.is_well_known());
77        assert_eq!(uid.first, u64::MAX);
78        assert_eq!(uid.second, 1);
79    }
80
81    #[test]
82    fn test_reserved_count() {
83        // Ensure all defined tokens fit within reserved count
84        assert!((WellKnownToken::FirstAvailable.as_u32() as usize) < WELL_KNOWN_RESERVED_COUNT);
85    }
86}
moonpool_core/well_known.rs

moonpool_core/
well_known.rs
