velo 0.12.0

Velo distributed-systems runtime: active messaging, peer discovery, streaming, rendezvous, and queue backends
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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

// SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

//! Handler registration manager for the messenger active message system.

use std::sync::Arc;

use anyhow::Result;
use dashmap::DashMap;

use super::{ActiveMessageDispatcher, Handler};

/// Manager for registering handlers with the dispatcher.
///
/// Inserts directly into the shared DashMap so registration is immediately
/// visible to the dispatcher — no async task needs to run first.
#[derive(Clone)]
pub(crate) struct HandlerManager {
    handlers: Arc<DashMap<String, Arc<dyn ActiveMessageDispatcher>>>,
}

impl HandlerManager {
    /// Create a new handler manager backed by the given DashMap.
    pub(crate) fn new(handlers: Arc<DashMap<String, Arc<dyn ActiveMessageDispatcher>>>) -> Self {
        Self { handlers }
    }

    /// Register a public handler (handler names cannot start with `_`).
    pub fn register_handler(&self, handler: Handler) -> Result<()> {
        let name = handler.name();

        if name.starts_with('_') {
            anyhow::bail!(
                "Handler name '{}' cannot start with '_'. System handlers must be registered via internal APIs.",
                name
            );
        }

        self.register_dispatcher(handler.dispatcher)
    }

    /// Register a system/internal handler (allows names starting with `_`).
    pub(crate) fn register_internal_handler(&self, handler: Handler) -> Result<()> {
        self.register_dispatcher(handler.dispatcher)
    }

    /// Insert a dispatcher directly into the shared DashMap.
    fn register_dispatcher(&self, dispatcher: Arc<dyn ActiveMessageDispatcher>) -> Result<()> {
        let name = dispatcher.name().to_string();
        self.handlers.insert(name, dispatcher);
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::messenger::server::dispatcher::HandlerContext;

    struct MockDispatcher {
        name: String,
    }

    impl ActiveMessageDispatcher for MockDispatcher {
        fn name(&self) -> &str {
            &self.name
        }

        fn dispatch(&self, _ctx: HandlerContext) {
            // No-op for testing
        }
    }

    fn make_manager() -> HandlerManager {
        HandlerManager::new(Arc::new(DashMap::new()))
    }

    #[test]
    fn test_register_handler_blocks_underscore() {
        let manager = make_manager();

        let dispatcher = Arc::new(MockDispatcher {
            name: "_system".to_string(),
        });

        let handler = Handler { dispatcher };

        let result = manager.register_handler(handler);
        assert!(result.is_err());
        assert!(
            result
                .unwrap_err()
                .to_string()
                .contains("cannot start with '_'")
        );
    }

    #[test]
    fn test_register_handler_allows_normal_names() {
        let manager = make_manager();

        let dispatcher = Arc::new(MockDispatcher {
            name: "my_handler".to_string(),
        });

        let handler = Handler { dispatcher };

        let result = manager.register_handler(handler);
        assert!(result.is_ok());
        assert!(manager.handlers.contains_key("my_handler"));
    }

    #[test]
    fn test_register_internal_handler_allows_underscore() {
        let manager = make_manager();

        let dispatcher = Arc::new(MockDispatcher {
            name: "_hello".to_string(),
        });

        let handler = Handler { dispatcher };

        let result = manager.register_internal_handler(handler);
        assert!(result.is_ok());
        assert!(manager.handlers.contains_key("_hello"));
    }

    #[test]
    fn test_register_internal_handler_allows_normal_names() {
        let manager = make_manager();

        let dispatcher = Arc::new(MockDispatcher {
            name: "internal_util".to_string(),
        });

        let handler = Handler { dispatcher };

        let result = manager.register_internal_handler(handler);
        assert!(result.is_ok());
        assert!(manager.handlers.contains_key("internal_util"));
    }
}