Added test and refactored some parts of usubscription

Author: lennartbecker-d

include/up-cpp/client/usubscription/v3/RequestBuilder.h

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+// SPDX-FileCopyrightText: 2025 Contributors to the Eclipse Foundation
 //
 // See the NOTICE file(s) distributed with this work for additional
 // information regarding copyright ownership.
@@ -18,12 +18,10 @@
 
 namespace uprotocol::core::usubscription::v3 {
 
-/**
- * @struct USubscriptionOptions
- * @brief Additional details for uSubscription service.
- *
- * Each member represents an optional parameter for the uSubscription service.
- */
+/// @struct USubscriptionOptions
+/// @brief Additional details for uSubscription service.
+///
+/// Each member represents an optional parameter for the uSubscription service.
 struct USubscriptionOptions {
 	/// Permission level of the subscription request
 	std::optional<uint32_t> permission_level;
@@ -39,80 +37,64 @@ struct USubscriptionOptions {
 	std::optional<google::protobuf::Any> subscription_details;
 };
 
-/**
- * @brief Builds different requests using specified options.
- *
- * This struct facilitates the construction of requests based on
- * `USubscriptionOptions`, providing methods to build different requests.
- */
+/// @brief Builds different requests using specified options.
+///
+/// This struct facilitates the construction of requests based on
+/// `USubscriptionOptions`, providing methods to build different requests.
 struct RequestBuilder {
-	/**
-	 * @brief Constructs a RequestBuilder with the given subscription options.
-	 *
-	 * @param options Subscription options to configure the requests. Defaults
-	 * to empty options.
-	 */
-	explicit RequestBuilder(USubscriptionOptions options = {})
-	    : options_(std::move(options)) {}
+	/// @brief Builds a subscription request for a given topic.
+	///
+	/// @param topic The `v1::UUri` representing the topic for the subscription.
+	///
+	/// @return A `SubscriptionRequest` configured for the specified topic.
+	static SubscriptionRequest buildSubscriptionRequest(
+	    const v1::UUri& topic, const USubscriptionOptions& options = {});
 
-	/**
-	 * @brief Builds a subscription request for a given topic.
-	 *
-	 * @param topic The `v1::UUri` representing the topic for the subscription.
-	 *
-	 * @return A `SubscriptionRequest` configured for the specified topic.
-	 */
-	SubscriptionRequest buildSubscriptionRequest(const v1::UUri& topic) const;
-
-	/**
-	 * @brief Builds an unsubscription request for a given topic.
-	 *
-	 * @param topic The `v1::UUri` representing the topic to unsubscribe from.
-	 *
-	 * @return An `UnsubscribeRequest` configured for the specified topic.
-	 */
+	/// @brief Builds an unsubscription request for a given topic.
+	///
+	/// @param topic The `v1::UUri` representing the topic to unsubscribe from.
+	///
+	/// @return An `UnsubscribeRequest` configured for the specified topic.
 	static UnsubscribeRequest buildUnsubscribeRequest(const v1::UUri& topic);
 
-	/**
-	 * @brief Build fetch subscritions request for a given topic.
-	 *
-	 * @param topic The `v1::UUri` representing the topic to fetch.
-	 *
-	 * @return An `FetchSubscriptionsRequest` configured for the specified topic.
-	 */
-	static FetchSubscriptionsRequest buildFetchSubscriptionsRequest(const v1::UUri& topic);
-
-	/**
-	 * @brief Build fetch subscritions request for a given subscriber.
-	 *
-	 * @param subscriber The `SubscriberInfo` representing the subscriber to fetch.
-	 *
-	 * @return An `FetchSubscriptionsRequest` configured for the specified subscriber.
-	 */
-	static FetchSubscriptionsRequest buildFetchSubscriptionsRequest(const SubscriberInfo& subscriber);
+	/// @brief Build fetch subscritions request for a given topic.
+	///
+	/// @param topic The `v1::UUri` representing the topic to fetch.
+	///
+	/// @return A `FetchSubscriptionsRequest` configured for the specified
+	/// topic.
+	static FetchSubscriptionsRequest buildFetchSubscriptionsRequest(
+	    const v1::UUri& topic);
 
-	/**
-	 * @brief Build fetch subscribers request for a given topic.
-	 *
-	 * @param topic The `v1::UUri` representing the topic to fetch.
-	 *
-	 * @return An `FetchSubscribersRequest` configured for the specified topic.
-	 */
-	static FetchSubscribersRequest buildFetchSubscribersRequest(const v1::UUri& topic);
+	/// @brief Build fetch subscritions request for a given subscriber.
+	///
+	/// @param subscriber The `SubscriberInfo` representing the subscriber to
+	/// fetch.
+	///
+	/// @return A `FetchSubscriptionsRequest` configured for the specified
+	/// subscriber.
+	static FetchSubscriptionsRequest buildFetchSubscriptionsRequest(
+	    const SubscriberInfo& subscriber);
 
-	/**
-	 * @brief Build notification request for a given topic. Subscription change notifications 
-	 *		  MUST use topic SubscriptionChange with resource id 0x8000, as per the protobuf definition.
-	 *
-	 * @param topic The `v1::UUri` representing the topic to (un)register for/from.
-	 *
-	 * @return An `NotificationsRequest` configured for the specified topic.
-	 */
-	static NotificationsRequest buildNotificationRequest(const v1::UUri& topic);
-	
+	/// @brief Build fetch subscribers request for a given topic.
+	///
+	/// @param topic The `v1::UUri` representing the topic to fetch.
+	///
+	/// @return A `FetchSubscribersRequest` configured for the specified topic.
+	static FetchSubscribersRequest buildFetchSubscribersRequest(
+	    const v1::UUri& topic);
 
-private:
-	USubscriptionOptions options_;  ///< Options used to configure the requests.
+	/// @brief Build a notifications request for a given topic. Subscription
+	/// change
+	/// notifications MUST use topic SubscriptionsChange with resource id
+	/// 0x8000, as per the protobuf definition.
+	///
+	/// @param topic The `v1::UUri` representing the topic to (un)register
+	/// for/from.
+	///
+	/// @return A `NotificationsRequest` configured for the specified topic.
+	static NotificationsRequest buildNotificationsRequest(
+	    const v1::UUri& topic);
 };
 
 }  // namespace uprotocol::core::usubscription::v3

include/up-cpp/client/usubscription/v3/RpcClientUSubscription.h

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+// SPDX-FileCopyrightText: 2025 Contributors to the Eclipse Foundation
 //
 // See the NOTICE file(s) distributed with this work for additional
 // information regarding copyright ownership.
@@ -23,31 +23,29 @@
 /// The uEntity (type) identifier of the uSubscription service.
 constexpr uint32_t USUBSCRIPTION_TYPE_ID = 0x00000000;
 /// The (latest) major version of the uSubscription service.
-constexpr uint8_t USUBSCRIPTION_VERSION_MAJOR = 0x03;
+constexpr uint8_t UE_VERSION_MAJOR = 0x03;
 /// The resource identifier of uSubscription's _subscribe_ operation.
 constexpr uint16_t RESOURCE_ID_SUBSCRIBE = 0x0001;
 /// The resource identifier of uSubscription's _unsubscribe_ operation.
 constexpr uint16_t RESOURCE_ID_UNSUBSCRIBE = 0x0002;
 /// The resource identifier of uSubscription's _fetch subscriptions_ operation.
 constexpr uint16_t RESOURCE_ID_FETCH_SUBSCRIPTIONS = 0x0003;
-/// The resource identifier of uSubscription's _register for notifications_ operation.
+/// The resource identifier of uSubscription's _register for notifications_
+/// operation.
 constexpr uint16_t RESOURCE_ID_REGISTER_FOR_NOTIFICATIONS = 0x0006;
-/// The resource identifier of uSubscription's _unregister for notifications_ operation.
+/// The resource identifier of uSubscription's _unregister for notifications_
+/// operation.
 constexpr uint16_t RESOURCE_ID_UNREGISTER_FOR_NOTIFICATIONS = 0x0007;
 /// The resource identifier of uSubscription's _fetch subscribers_ operation.
 constexpr uint16_t RESOURCE_ID_FETCH_SUBSCRIBERS = 0x0008;
-// TODO(lennart) see default_call_options() for the request in Rust
-constexpr auto USUBSCRIPTION_REQUEST_TTL =
-    std::chrono::milliseconds(0x0800);  // TODO(lennart) change time
+
+constexpr auto USUBSCRIPTION_REQUEST_TTL = std::chrono::milliseconds(5000);
 
 namespace uprotocol::core::usubscription::v3 {
 using v3::SubscriptionRequest;
 using v3::UnsubscribeRequest;
 
-/// @brief Interface for uEntities to create subscriptions.
-///
-/// Like all L3 client APIs, the RpcClientUSubscription is a wrapper on top of
-/// the L2 Communication APIs and USubscription service.
+/// @brief Client which implements the USubscription interface
 struct RpcClientUSubscription : USubscription {
 	using RpcClientUSubscriptionOrStatus =
 	    utils::Expected<std::unique_ptr<RpcClientUSubscription>, v1::UStatus>;
@@ -57,54 +55,72 @@ struct RpcClientUSubscription : USubscription {
 	template <typename Response>
 	Response invokeResponse(communication::RpcClient rpc_client);
 
-	/// @brief Subscribe to the topic
+	/// @brief Subscribes from a given topic
 	///
+	/// @param subscription_request The request object containing the topic to
+	/// subscribe to
+	/// @return Returns a SubscriptionResponse on success and a UStatus else
 	utils::Expected<SubscriptionResponse, v1::UStatus> subscribe(
 	    const SubscriptionRequest& subscription_request) override;
 
-	/// @brief Unsubscribe from the topic
+	/// @brief Unsubscribes from a given topic
 	///
+	/// @param unsubscribe_request The request object containing the topic to
+	/// unsubscribe from
+	/// @return Returns an UnsubscribeResponse on success and a UStatus else
 	utils::Expected<UnsubscribeResponse, v1::UStatus> unsubscribe(
 	    const UnsubscribeRequest& unsubscribe_request) override;
-	
-	/// @brief Fetch all subscriptions either by topic or subscriber
-	///
-	utils::Expected<FetchSubscriptionsResponse, v1::UStatus> fetch_subscriptions(
-	    const FetchSubscriptionsRequest& fetch_subscribers) override;
 
-	/// @brief Fetch all subscribers
+	/// @brief Fetches the list of topics the client is subscribed to
 	///
+	/// @param fetch_subscriptions_request The request object
+	/// @return Returns a FetchSubscriptionsResponse on success and a UStatus
+	/// else
+	utils::Expected<FetchSubscriptionsResponse, v1::UStatus>
+	fetch_subscriptions(
+	    const FetchSubscriptionsRequest& fetch_subscriptions_request) override;
+
+	/// @brief Fetches the list of subscribers for a given topic
+	///
+	/// @param fetch_subscribers_request The request object containing the topic
+	/// for which the subscribers are to be fetched
+	/// @return Returns a FetchSubscribersResponse on success and a UStatus else
 	utils::Expected<FetchSubscribersResponse, v1::UStatus> fetch_subscribers(
-	    const FetchSubscribersRequest& fetch_subscribers) override;
+	    const FetchSubscribersRequest& fetch_subscribers_request) override;
 
-	/// @brief Register for notifications
+	/// @brief Registers to receive notifications
 	///
-	utils::Expected<NotificationsResponse, v1::UStatus> register_for_notifications(const
-	NotificationsRequest& register_notifications_request) override ;
-
-	/// @brief Unregister for notifications
+	/// @param register_notifications_request The request object containing
+	///	       the details to register for notifications
+	/// @return Returns a NotificationResponse on success and a UStatus else
+	utils::Expected<NotificationsResponse, v1::UStatus>
+	register_for_notifications(
+	    const NotificationsRequest& register_notifications_request) override;
+
+	/// @brief Unregisters from receiving notifications.
 	///
-	utils::Expected<NotificationsResponse, v1::UStatus> unregister_for_notifications(const
-	NotificationsRequest& unregister_notifications_request) override ;
+	/// @param unregister_notifications_request The request object containing
+	///        the details needed to stop receiving notifications.
+	/// @return Returns a NotificationResponse on success and a UStatus else
+	utils::Expected<NotificationsResponse, v1::UStatus>
+	unregister_for_notifications(
+	    const NotificationsRequest& unregister_notifications_request) override;
 
 	/// @brief Constructor
 	///
-	/// @param transport Transport to register with.
+	/// @param transport Transport used to send messages
 	explicit RpcClientUSubscription(
 	    std::shared_ptr<transport::UTransport> transport)
 	    : transport_(std::move(transport)) {}
 
-	/// @brief Destructor
 	~RpcClientUSubscription() override = default;
 
 private:
-	// Transport
 	std::shared_ptr<transport::UTransport> transport_;
 
-	// URI info about the uSubscription service
 	USubscriptionUUriBuilder uuri_builder_;
 };
 
 }  // namespace uprotocol::core::usubscription::v3
 
-#endif  // UP_CPP_CLIENT_USUBSCRIPTION_V3_RPCCLIENTUSUBSCRIPTION_H
+#endif  // UP_CPP_CLIENT_USUBSCRIPTION_V3_RPCCLIENTUSUBSCRIPTION_H

include/up-cpp/client/usubscription/v3/USubscription.h

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+// SPDX-FileCopyrightText: 2025 Contributors to the Eclipse Foundation
 //
 // See the NOTICE file(s) distributed with this work for additional
 // information regarding copyright ownership.
@@ -19,29 +19,61 @@
 
 namespace uprotocol::core::usubscription::v3 {
 
+/// @brief Interface for uEntities to create subscriptions.
+///
+/// Like all L3 client APIs, the RpcClientUSubscription is a wrapper on top of
+/// the L2 Communication APIs and USubscription service.
 struct USubscription {
 	template <typename R>
 	using ResponseOrStatus = utils::Expected<R, v1::UStatus>;
 
 	virtual ~USubscription() = default;
 
+	/// @brief sends a subscription request to a USubscription backend and a
+	/// response on success or else a status code
+	///
+	/// @param subscription_request containing a topic to subscribe to
+	/// @return SubscriptionReponse on success and UStatus else
 	virtual ResponseOrStatus<SubscriptionResponse> subscribe(
 	    const SubscriptionRequest& subscription_request) = 0;
 
+	/// @brief sends an unsubscribe request to a USubscription backend and a
+	/// response on success or else a status code
+	///
+	/// @param unsubscribe_request containing a topic to unsubscribe
+	/// @return UnsubscribeResponse on success and UStatus else
 	virtual ResponseOrStatus<UnsubscribeResponse> unsubscribe(
 	    const UnsubscribeRequest& unsubscribe_request) = 0;
 
-	virtual ResponseOrStatus<FetchSubscriptionsResponse> fetch_subscriptions(const
-	FetchSubscriptionsRequest& fetch_subscribers_request) = 0;
+	/// @brief fetches all topics the client is subscribed to from the backend
+	///
+	/// @param fetch_subscriptions_request
+	/// @return FetchSubscriptionsResponse on success and UStatus else
+	virtual ResponseOrStatus<FetchSubscriptionsResponse> fetch_subscriptions(
+	    const FetchSubscriptionsRequest& fetch_subscriptions_request) = 0;
 
-	virtual ResponseOrStatus<NotificationsResponse> register_for_notifications(const
-	NotificationsRequest& register_notifications_request) =0 ;
+	/// @brief registers for notifications to a USubscription backend
+	///
+	/// @param register_notifications_request
+	/// @return NotificationResponse on success and UStatus else
+	virtual ResponseOrStatus<NotificationsResponse> register_for_notifications(
+	    const NotificationsRequest& register_notifications_request) = 0;
 
-	virtual ResponseOrStatus<NotificationsResponse> unregister_for_notifications(const
-	NotificationsRequest& unregister_notifications_request) = 0;
+	/// @brief unregisters for notifications to a USubscription backend
+	///
+	/// @param unregister_notifications_request
+	/// @return NotificationResponse on success and UStatus else
+	virtual ResponseOrStatus<NotificationsResponse>
+	unregister_for_notifications(
+	    const NotificationsRequest& unregister_notifications_request) = 0;
 
-	virtual ResponseOrStatus<FetchSubscribersResponse> fetch_subscribers(const
-	FetchSubscribersRequest& fetch_subscribers_request) = 0;
+	/// @brief fetches all subscribers for a given topic from the backend
+	///
+	/// @param fetch_subscriptions_request containing the topic for which the
+	/// subscribers are fetched
+	/// @return FetchSubscriptionsResponse on success and UStatus else
+	virtual ResponseOrStatus<FetchSubscribersResponse> fetch_subscribers(
+	    const FetchSubscribersRequest& fetch_subscribers_request) = 0;
 };
 
 }  // namespace uprotocol::core::usubscription::v3

include/up-cpp/client/usubscription/v3/USubscriptionUUriBuilder.h

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+// SPDX-FileCopyrightText: 2025 Contributors to the Eclipse Foundation
 //
 // See the NOTICE file(s) distributed with this work for additional
 // information regarding copyright ownership.