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.
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    #[must_use]
44    pub const fn as_u32(self) -> u32 {
45        self as u32
46    }
47
48    /// Create a UID for this well-known token.
49    #[must_use]
50    pub const fn uid(self) -> UID {
51        UID::well_known(self as u32)
52    }
53}
54
55/// Number of reserved well-known token slots.
56///
57/// The endpoint map reserves an array of this size for O(1) lookup
58/// of well-known endpoints. Tokens 0-63 are reserved for system use.
59///
60/// Matches FDB's `WLTOKEN_RESERVED_COUNT` pattern.
61pub const WELL_KNOWN_RESERVED_COUNT: usize = 64;
62
63#[cfg(test)]
64mod tests {
65    use super::*;
66
67    #[test]
68    fn test_well_known_token_values() {
69        assert_eq!(WellKnownToken::EndpointNotFound.as_u32(), 0);
70        assert_eq!(WellKnownToken::Ping.as_u32(), 1);
71        assert_eq!(WellKnownToken::UnauthorizedEndpoint.as_u32(), 2);
72        assert_eq!(WellKnownToken::FirstAvailable.as_u32(), 3);
73    }
74
75    #[test]
76    fn test_well_known_uid() {
77        let uid = WellKnownToken::Ping.uid();
78        assert!(uid.is_well_known());
79        assert_eq!(uid.first, u64::MAX);
80        assert_eq!(uid.second, 1);
81    }
82
83    #[test]
84    fn test_reserved_count() {
85        // Ensure all defined tokens fit within reserved count
86        assert!((WellKnownToken::FirstAvailable.as_u32() as usize) < WELL_KNOWN_RESERVED_COUNT);
87    }
88}
moonpool_core/well_known.rs

moonpool_core/
well_known.rs
