up_rust/core/
udiscovery.rs

1/********************************************************************************
2 * Copyright (c) 2024 Contributors to the Eclipse Foundation
3 *
4 * See the NOTICE file(s) distributed with this work for additional
5 * information regarding copyright ownership.
6 *
7 * This program and the accompanying materials are made available under the
8 * terms of the Apache License Version 2.0 which is available at
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * SPDX-License-Identifier: Apache-2.0
12 ********************************************************************************/
13
14use async_trait::async_trait;
15#[cfg(test)]
16use mockall::automock;
17
18use crate::{UStatus, UUri};
19
20#[cfg(feature = "communication-api")]
21mod udiscovery_client;
22#[cfg(feature = "communication-api")]
23pub use udiscovery_client::RpcClientUDiscovery;
24
25/// The uEntity (type) identifier of the uDiscovery service.
26pub const UDISCOVERY_TYPE_ID: u32 = 0x0000_0001;
27/// The (latest) major version of the uDiscovery service.
28pub const UDISCOVERY_VERSION_MAJOR: u8 = 0x03;
29/// The resource identifier of uDiscovery's _find services_ operation.
30pub const RESOURCE_ID_FIND_SERVICES: u16 = 0x0001;
31/// The resource identifier of uDiscovery's _get service topics_ operation.
32pub const RESOURCE_ID_GET_SERVICE_TOPICS: u16 = 0x0002;
33
34type MessageTypeString = String;
35
36#[derive(Clone, Debug)]
37#[repr(C)]
38/// One discoverable topic as reported by the uDiscovery service.
39pub struct TopicInfo {
40    pub(crate) topic: UUri,
41    pub(crate) message_type: MessageTypeString,
42    pub(crate) permission_level: Option<u32>,
43    pub(crate) ttl: u32,
44}
45
46impl TopicInfo {
47    /// Gets the topic URI.
48    pub fn topic(&self) -> &UUri {
49        &self.topic
50    }
51
52    /// Gets the message type string.
53    pub fn message_type(&self) -> &str {
54        self.message_type.as_str()
55    }
56
57    /// Gets the permission level, if any.
58    pub fn permission_level(&self) -> Option<u32> {
59        self.permission_level
60    }
61
62    /// Gets the time-to-live (TTL) value in seconds.
63    pub fn ttl(&self) -> u32 {
64        self.ttl
65    }
66}
67
68/// The uProtocol Application Layer client interface to the uDiscovery service.
69///
70/// Please refer to the [uDiscovery service specification](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.7/up-l3/udiscovery/v3/client.adoc)
71/// for details.
72#[cfg_attr(test, automock)]
73#[async_trait]
74pub trait UDiscovery: Send + Sync {
75    /// Finds service instances based on search criteria.
76    ///
77    /// # Parameters
78    ///
79    /// * `uri_pattern` - The URI pattern to use for looking up service instances.
80    /// * `recursive` - Flag indicating whether the service should extend the search to its parent uDiscovery node.
81    ///
82    /// # Returns
83    ///
84    /// The service instances matching the given search criteria.
85    async fn find_services(&self, uri_pattern: UUri, recursive: bool)
86        -> Result<Vec<UUri>, UStatus>;
87
88    /// Gets information about topic(s) that a service (instance) publishes messages to.
89    ///
90    /// # Parameters
91    ///
92    /// * `topic_pattern` - The URI pattern to use for looking up topic information.
93    /// * `recursive` - Flag indicating whether the service should extend the search to its parent uDiscovery node.
94    ///
95    /// # Returns
96    ///
97    /// The topics.
98    async fn get_service_topics(
99        &self,
100        topic_pattern: UUri,
101        recursive: bool,
102    ) -> Result<Vec<TopicInfo>, UStatus>;
103}
up_rust/core/udiscovery.rs

up_rust/core/
udiscovery.rs
