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
18pub use crate::up_core_api::udiscovery::{
19    FindServicesRequest, FindServicesResponse, GetServiceTopicsRequest, GetServiceTopicsResponse,
20    ServiceTopicInfo,
21};
22use crate::{UStatus, UUri};
23
24/// The uEntity (type) identifier of the uDiscovery service.
25pub const UDISCOVERY_TYPE_ID: u32 = 0x0000_0001;
26/// The (latest) major version of the uDiscovery service.
27pub const UDISCOVERY_VERSION_MAJOR: u8 = 0x03;
28/// The resource identifier of uDiscovery's _find services_ operation.
29pub const RESOURCE_ID_FIND_SERVICES: u16 = 0x0001;
30/// The resource identifier of uDiscovery's _get service topics_ operation.
31pub const RESOURCE_ID_GET_SERVICE_TOPICS: u16 = 0x0002;
32
33/// Gets a UUri referring to one of the local uDiscovery service's resources.
34///
35/// # Examples
36///
37/// ```rust
38/// use up_rust::core::udiscovery;
39///
40/// let uuri = udiscovery::udiscovery_uri(udiscovery::RESOURCE_ID_FIND_SERVICES);
41/// assert_eq!(uuri.resource_id, 0x0001);
42/// ```
43pub fn udiscovery_uri(resource_id: u16) -> UUri {
44    UUri::try_from_parts(
45        "",
46        UDISCOVERY_TYPE_ID,
47        UDISCOVERY_VERSION_MAJOR,
48        resource_id,
49    )
50    .unwrap()
51}
52
53/// The uProtocol Application Layer client interface to the uDiscovery service.
54///
55/// Please refer to the [uDiscovery service specification](https://github.com/eclipse-uprotocol/up-spec/blob/v1.6.0-alpha.4/up-l3/udiscovery/v3/client.adoc)
56/// for details.
57#[cfg_attr(test, automock)]
58#[async_trait]
59pub trait UDiscovery: Send + Sync {
60    /// Finds service instances based on search criteria.
61    ///
62    /// # Parameters
63    ///
64    /// * `uri_pattern` - The URI pattern to use for looking up service instances.
65    /// * `recursive` - Flag indicating whether the service should extend the search to its parent uDiscovery node.
66    ///
67    /// # Returns
68    ///
69    /// The service instances matching the given search criteria.
70    async fn find_services(&self, uri_pattern: UUri, recursive: bool)
71        -> Result<Vec<UUri>, UStatus>;
72
73    /// Gets information about topic(s) that a service (instance) publishes messages to.
74    ///
75    /// # Parameters
76    ///
77    /// * `topic_pattern` - The URI pattern to use for looking up topic information.
78    /// * `recursive` - Flag indicating whether the service should extend the search to its parent uDiscovery node.
79    ///
80    /// # Returns
81    ///
82    /// The topics.
83    async fn get_service_topics(
84        &self,
85        topic_pattern: UUri,
86        recursive: bool,
87    ) -> Result<Vec<ServiceTopicInfo>, UStatus>;
88}
up_rust/core/udiscovery.rs

up_rust/core/
udiscovery.rs
