Skip to main content

libkeri/keri/core/routing/
router.rs

1use super::route::{compile_uri_template, Route, RouteResource};
2use crate::cesr::indexing::siger::Siger;
3use crate::cesr::prefixer::Prefixer;
4use crate::cesr::saider::Saider;
5use crate::cesr::seqner::Seqner;
6use crate::cesr::Matter;
7use crate::keri::core::serdering::Serder;
8use crate::keri::core::serdering::SerderKERI;
9use crate::keri::KERIError;
10use std::collections::HashMap;
11use tracing::debug;
12
13/// Reply message router
14///
15/// Reply message router that accepts registration of route handlers and dispatches
16/// reply messages to the appropriate handler.
17pub struct Router {
18    /// List of registered routes
19    routes: Vec<Route>,
20}
21
22impl Router {
23    /// Default resource function name
24    pub const DEFAULT_RESOURCE_FUNC: &'static str = "processReply";
25
26    /// Initialize Router instance with optional list of existing routes
27    pub fn new(routes: Option<Vec<Route>>) -> Self {
28        Self {
29            routes: routes.unwrap_or_default(),
30        }
31    }
32
33    /// Add a route between a route template and a resource
34    ///
35    /// # Parameters
36    /// * `route_template` - A route template to use for the resource
37    /// * `resource` - The resource instance to associate with the route template
38    /// * `suffix` - Optional responder name suffix for this route. If a suffix is provided,
39    ///             Router will map reply routes to processReply{suffix}(). In this way,
40    ///             multiple closely-related routes can be mapped to the same resource.
41    pub fn add_route(
42        &mut self,
43        route_template: &str,
44        resource: Box<dyn RouteResource>,
45        suffix: Option<String>,
46    ) -> Result<(), KERIError> {
47        let (fields, regex) = compile_uri_template(route_template)?;
48        self.routes
49            .push(Route::new(regex, fields, resource, suffix));
50        Ok(())
51    }
52
53    /// Dispatch a reply message to the appropriate route handler
54    ///
55    /// # Parameters
56    /// * `serder` - The reply message serder
57    /// * `saider` - The SAID of the reply message
58    /// * `cigars` - Optional non-transferable signature instances
59    /// * `tsgs` - Optional transferable signature groups
60    pub fn dispatch(
61        &self,
62        serder: &SerderKERI,
63        saider: &Saider,
64        cigars: Option<&[Siger]>,
65        tsgs: Option<&[(Prefixer, Seqner, Saider, Vec<Siger>)]>,
66    ) -> Result<(), KERIError> {
67        let ked = serder.ked();
68
69        // Get route from the message
70        let route = ked
71            .get("r")
72            .and_then(|v| v.as_str())
73            .ok_or_else(|| KERIError::ValueError("Missing route 'r' in message".to_string()))?;
74
75        // Find matching route
76        let (matched_route, captured_params) = self.find_route(route)?;
77
78        // Use the already extracted parameters
79        let params = captured_params.unwrap_or_default();
80
81        // Call the appropriate handler method
82        matched_route
83            .resource
84            .process_reply(serder, saider, route, cigars, tsgs, params)
85    }
86
87    /// Linear search through added routes, returning the first one that matches
88    ///
89    /// Searches through the registered routes until a regex in one of the routes matches
90    /// the provided route and returns the Route object along with the regex Match object.
91    ///
92    /// # Parameters
93    /// * `route` - The route from the 'r' field of the reply message
94    ///
95    /// # Returns
96    /// * The Route object with the resource that is registered to process this reply message
97    /// * The regular expression match that contains the grouping of matched parameters
98    fn find_route(
99        &self,
100        route: &str,
101    ) -> Result<(&Route, Option<HashMap<String, String>>), KERIError> {
102        for registered_route in &self.routes {
103            if let Some(captures) = registered_route.regex.captures(route) {
104                let mut captured_params = HashMap::new();
105                for field_name in &registered_route.fields {
106                    if let Some(matched_value) = captures.name(field_name) {
107                        captured_params
108                            .insert(field_name.clone(), matched_value.as_str().to_string());
109                    }
110                }
111                return Ok((registered_route, Some(captured_params)));
112            }
113        }
114
115        Err(KERIError::ValidationError(format!(
116            "No resource is registered to handle route {}",
117            route
118        )))
119    }
120
121    /// Get the number of registered routes
122    pub fn route_count(&self) -> usize {
123        self.routes.len()
124    }
125
126    /// Check if a route is registered
127    pub fn has_route(&self, route: &str) -> bool {
128        self.find_route(route).is_ok()
129    }
130}
131
132/// Default route resource implementation for testing and fallback
133pub struct DefaultRouteResource;
134
135impl RouteResource for DefaultRouteResource {
136    fn process_reply(
137        &self,
138        serder: &SerderKERI,
139        saider: &Saider,
140        route: &str,
141        _cigars: Option<&[Siger]>,
142        _tsgs: Option<&[(Prefixer, Seqner, Saider, Vec<Siger>)]>,
143        params: HashMap<String, String>,
144    ) -> Result<(), KERIError> {
145        debug!(
146            "DefaultRouteResource processing reply: route={}, said={}, params={:?}",
147            route,
148            saider.qb64(),
149            params
150        );
151
152        // Default implementation just logs the message
153        debug!("Reply message: {}", serder.pretty(None));
154
155        Ok(())
156    }
157}
158
159#[cfg(test)]
160mod tests {
161    use super::*;
162    use crate::cesr::saider::Saider;
163    use crate::keri::core::serdering::SerderKERI;
164    use std::collections::HashMap;
165
166    struct TestResource {
167        pub called: std::sync::Arc<std::sync::Mutex<bool>>,
168    }
169
170    impl RouteResource for TestResource {
171        fn process_reply(
172            &self,
173            _serder: &SerderKERI,
174            _saider: &Saider,
175            _route: &str,
176            _cigars: Option<&[Siger]>,
177            _tsgs: Option<&[(Prefixer, Seqner, Saider, Vec<Siger>)]>,
178            _params: HashMap<String, String>,
179        ) -> Result<(), KERIError> {
180            let mut called = self.called.lock().unwrap();
181            *called = true;
182            Ok(())
183        }
184    }
185
186    #[test]
187    fn test_router_new() {
188        let router = Router::new(None);
189        assert_eq!(router.route_count(), 0);
190    }
191
192    #[test]
193    fn test_router_add_route() {
194        let mut router = Router::new(None);
195        let resource = Box::new(DefaultRouteResource);
196
197        router.add_route("/test", resource, None).unwrap();
198        assert_eq!(router.route_count(), 1);
199        assert!(router.has_route("/test"));
200    }
201
202    #[test]
203    fn test_router_add_route_with_params() {
204        let mut router = Router::new(None);
205        let resource = Box::new(DefaultRouteResource);
206
207        router.add_route("/books/{isbn}", resource, None).unwrap();
208        assert_eq!(router.route_count(), 1);
209        assert!(router.has_route("/books/123"));
210        assert!(!router.has_route("/books"));
211    }
212}