From 238501808e051ba1d81a0cbbc4d58025d0931a0c Mon Sep 17 00:00:00 2001 From: Kai Hudalla Date: Tue, 28 May 2024 13:15:51 +0200 Subject: [PATCH] Use dedicated messages in service operations (#163) * [#112] Use dedicated messages in service operations Changed operation definitions of uProtocol core services to always use dedicated request and response messages as recommended by Protobuf Best Practices. Removed UStatus from response messages, following recommendations from uProtocol Error Model specification. * Add documentation --- .../core/udiscovery/v3/udiscovery.proto | 76 ++++++++++--------- .../core/usubscription/v3/usubscription.proto | 53 ++++++------- .../uprotocol/core/utwin/v2/utwin.proto | 25 ++++-- 3 files changed, 87 insertions(+), 67 deletions(-) diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 6673e93..f1aebda 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -42,26 +42,24 @@ service uDiscovery { // Used by any uProtocol application or service to find service instances // locations. The passed UUri contains valid UEntity, UResource, and UAuthority information // for a query. - // What is returned is a list of UUris that match the query. Possible return values in status are: - // 1. code.OK: Query lookup was successful + // What is returned is a list of UUris that match the query. + // If lookup fails, the response will be a UStatus with // 2. code.NOT_FOUND: No matching UUris were found // 3. code.INVALID_ARGUMENT: The passed UUri is invalid // 4. code.PERMISSION_DENIED: The caller does not have permission to perform the query - rpc LookupUri(v1.UUri) returns (LookupUriResponse) { + rpc LookupUri(LookupUriRequest) returns (LookupUriResponse) { option (uprotocol.method_id) = 1; } // Update a node in the database. - // What is returned is the status of the API request as uprotocol.v1.UStatus. // **NOTE:** You MUST have write permission to the node in the database - rpc UpdateNode(UpdateNodeRequest) returns (uprotocol.v1.UStatus) { + rpc UpdateNode(UpdateNodeRequest) returns (UpdateNodeResponse) { option (uprotocol.method_id) = 2; } // Query the database to find Node(s). What is passed is the search criterial in // the FindNodeRequest message. the returned FindNodeResponse contains the - // resulting query node(s) and their child nodes, as well as the - // uprotocol.v1.UStatus for the query. Below are some example queries: + // resulting query node(s) and their child nodes. Below are some example queries: // 1. uDomain: `//*.device/` // 2. uDevice: `//device` // 3. uService: `//device.domain/body.access/` @@ -77,19 +75,18 @@ service uDiscovery { } // Remove one or more nodes (and all its children nodes) in the database. - // What is returned is the status of the API request as uprotocol.v1.UStatus. // **NOTE:** You MUST have write permission to the deleted all the nodes passed, // all the children nodes, as well as write permission to the parent otherwise // you will get PERMISSION_DENIED and no nodes will be deleted. - rpc DeleteNodes(DeleteNodesRequest) returns (uprotocol.v1.UStatus) { + rpc DeleteNodes(DeleteNodesRequest) returns (DeleteNodesResponse) { option (uprotocol.method_id) = 5; } - // Add one of more nodes to a parent node. If one of the nodes already exists, this API will return - // ALREADY_EXISTS and none of the nodes shall be added to the parent. + // Add one of more nodes to a parent node. If one of the nodes already exists, this RPC will fail + // with a UStatus containing an ALREADY_EXISTS UCode and none of the nodes shall be added to the parent. // **NOTE:** You MUST have write permission to the parent node - rpc AddNodes(AddNodesRequest) returns (uprotocol.v1.UStatus) { + rpc AddNodes(AddNodesRequest) returns (AddNodesResponse) { option (uprotocol.method_id) = 6; } @@ -97,28 +94,28 @@ service uDiscovery { // Update a property in a node // **NOTE:** You MUST have write permission to the node who's property you // are updating - rpc UpdateProperty(UpdatePropertyRequest) returns (uprotocol.v1.UStatus) { + rpc UpdateProperty(UpdatePropertyRequest) returns (UpdatePropertyResponse) { option (uprotocol.method_id) = 7; } // Register to receive Notifications to changes to one of more Nodes. The changes // are published on the notification topic: '/core.udiscovery/3/nodes#Notification' - rpc RegisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) { + rpc RegisterForNotifications(NotificationsRequest) returns (NotificationsResponse) { option (uprotocol.method_id) = 8; } // Unregister for Node change notifications - rpc UnregisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) { + rpc UnregisterForNotifications(NotificationsRequest) returns (NotificationsResponse) { option (uprotocol.method_id) = 9; } // Resolve a UUri filling in the missing names/numbers from the Discovery database. // If the resolution was successful, the resolved UUri containing names and numbers - // is returned along with the following status.code values: - // - code.OK: Resolution was successfull + // is returned. + // If resolving fails, the response will be a UStatus with // - code.NOT_FOUND: Unable to find the missing names or numbers for the passed UUri // - code.INVALID_ARGUMENT: The passed UUri is invalid (missing names or numbers) // - code.PERMISSION_DENIED: The caller does not have permission to perform the resolution @@ -183,15 +180,19 @@ message UpdateNodeRequest { // Time-to-live: How long (ms) the information should be live for in the database. // -1 means lives forever - optional int32 ttl = 3; + optional int32 ttl = 2; } +// The (empty) response message representing the successful execution of the UpdateNode operation. +message UpdateNodeResponse {} // Delete one or more nodes request message DeleteNodesRequest { repeated string uris = 1; // uProtocol formatted URI } +// The (empty) response message representing the successful execution of the DeleteNodes operation. +message DeleteNodesResponse {} // FindNodesRequest passed to FindNodes() message FindNodesRequest { @@ -208,15 +209,13 @@ message FindNodesRequest { // FindNodesResponse that is returned from the FindNodes() API message FindNodesResponse { + // List of node information repeated Node nodes = 1; - // Return code for the rpc call - uprotocol.v1.UStatus status = 2; - // Time-to-live: How long (ms) the information should be live for in the database. // -1 means lives forever - optional int32 ttl = 3; + optional int32 ttl = 2; } @@ -235,9 +234,6 @@ message FindNodePropertiesRequest { message FindNodePropertiesResponse { // a list of property name/value pairs map properties = 1; - - // Return code for the rpc call - uprotocol.v1.UStatus status = 2; } @@ -253,6 +249,8 @@ message AddNodesRequest { repeated Node nodes = 2; } +// The (empty) response message representing the successful execution of the AddNodes operation. +message AddNodesResponse {} // Message passed to UpdateProperty() to update a property in a Node message UpdatePropertyRequest { @@ -266,6 +264,8 @@ message UpdatePropertyRequest { PropertyValue value = 3; } +// The (empty) response message representing the successful execution of the UpdateProperty operation. +message UpdatePropertyResponse {} // Node Change Notification Message. // When uEs call RegisterForNotifications(), a Notification message is sent when the node either @@ -323,24 +323,32 @@ message NotificationsRequest { optional int32 depth = 3; } +// The (empty) response message representing the successful execution of the +// RegisterForNotifications and UnregisterForNotifications operations. +message NotificationsResponse {} + // Request message passed to ResolveUri() API to resolve the missing names or numbers. message ResolveUriRequest { - // The URI to resolve containing only names or numbers - v1.UUri uri = 1; + // The URI to resolve + uprotocol.v1.UUri uri = 1; } -// Response message returned from ResolveUri() API containing a UUri and the -// status of the resolution. +// Response message returned from ResolveUri() API containing the resolved UUri message ResolveUriResponse { - v1.UUri uri = 1; // Resolved UUri - uprotocol.v1.UStatus status = 3; // Return code for the rpc call + // Resolved URI + uprotocol.v1.UUri uri = 1; } +// Request message passed to LookupUri() API. +message LookupUriRequest { + // The Uri to look up + uprotocol.v1.UUri uri = 1; +} // Return value from LookupUri() API that contains the batch of Uris for the -// lookup and status from the API call +// lookup message LookupUriResponse { - v1.UUriBatch uris = 1; // Batch of Uris - uprotocol.v1.UStatus status = 2; // Return code for the rpc call + // Batch of URIs + uprotocol.v1.UUriBatch uris = 1; } diff --git a/up-core-api/uprotocol/core/usubscription/v3/usubscription.proto b/up-core-api/uprotocol/core/usubscription/v3/usubscription.proto index 18c27ed..1484e43 100644 --- a/up-core-api/uprotocol/core/usubscription/v3/usubscription.proto +++ b/up-core-api/uprotocol/core/usubscription/v3/usubscription.proto @@ -54,7 +54,7 @@ service uSubscription { // The consumer no longer wishes to subscribe to a topic so it issues an // explicit unsubscribe request. - rpc Unsubscribe(UnsubscribeRequest) returns (uprotocol.v1.UStatus) { + rpc Unsubscribe(UnsubscribeRequest) returns (UnsubscribeResponse) { option (uprotocol.method_id) = 2; } @@ -66,12 +66,12 @@ service uSubscription { // Register to receive subscription change notifications that are published on the // 'up:/core.usubscription/3/subscriptions#Update' - rpc RegisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) { + rpc RegisterForNotifications(NotificationsRequest) returns (NotificationsResponse) { option (uprotocol.method_id) = 6; } // Unregister for subscription change events - rpc UnregisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) { + rpc UnregisterForNotifications(NotificationsRequest) returns (NotificationsResponse) { option (uprotocol.method_id) = 7; } @@ -87,7 +87,7 @@ service uSubscription { // reset). // **__NOTE:__** This is a private API only for uSubscription services, // uEs can call Unsubscribe() to flush their own subscriptions. - rpc Reset(ResetRequest) returns (uprotocol.v1.UStatus) { + rpc Reset(ResetRequest) returns (ResetResponse) { option (uprotocol.method_id) = 9; } } @@ -119,7 +119,7 @@ message SubscribeAttributes { message SubscriberInfo { // subscriber URI containig the names and numbers of the // uE subscribing. Example represented in long form: `//device.domain/com.gm.app.hartley` - v1.UUri uri = 1; + uprotocol.v1.UUri uri = 1; // Any additional device specific subscriber information repeated google.protobuf.Any details = 2; @@ -141,12 +141,11 @@ message SubscriptionStatus { // remote uSubscription Service } + reserved 2; + // Subscription state State state = 1; - // The Subscription status code - uprotocol.v1.UCode code = 2; - // The Subscription status message string message = 3; } @@ -171,7 +170,7 @@ message EventDeliveryConfig { // Passed to Subscribe() contains the subscription request information message SubscriptionRequest { // uProtocol uri topic to subscribe too - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Subscribers's information (who is calling Subscribe) SubscriberInfo subscriber = 2; @@ -183,7 +182,7 @@ message SubscriptionRequest { // Response message from the Subscribe() API message SubscriptionResponse { - // Current status of the subscription (state, code, etc...) + // Current status of the subscription SubscriptionStatus status = 1; // Any platform (uDevice) specific additional event delivered configuration @@ -191,7 +190,7 @@ message SubscriptionResponse { EventDeliveryConfig config = 2; // Subscription topic passed to SubscriptionRequest - v1.UUri topic = 3; + uprotocol.v1.UUri topic = 3; } @@ -199,18 +198,20 @@ message SubscriptionResponse { // to as well as the subscriber identification message UnsubscribeRequest { // Topic to be unsubscribed to - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Subscriber identification SubscriberInfo subscriber = 2; } +// The (empty) response message representing the successful execution of the Unsubscribe operation. +message UnsubscribeResponse {} // Passed to FetchSubscribers such that we can obtain a list of subscribers to // a particular topic message FetchSubscribersRequest { // Topic we wish to find the subscribers for - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Offset in the fetch requests optional uint32 offset = 2; @@ -220,14 +221,12 @@ message FetchSubscribersRequest { // Returned from FetchSubscribers(), this message contains a repeated list of // SubscriberInfo message FetchSubscribersResponse { + reserved 3; // List of subscribers repeated SubscriberInfo subscribers = 1; // Set to true if the batch did not return all records optional bool has_more_records = 2; - - // Status of the query - uprotocol.v1.UStatus status = 3; } @@ -235,12 +234,12 @@ message FetchSubscribersResponse { // is returned from FetchSubscriptions() API. message Subscription { // Subscription topic - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Information about the subscriber who changed their subscription SubscriberInfo subscriber = 2; - // Current status of the subscription (state, code, etc...) + // Current status of the subscription SubscriptionStatus status = 3; // Subscribers subscription attributes @@ -255,7 +254,7 @@ message Subscription { message FetchSubscriptionsRequest { oneof request { // Topic to register/unregister to receive subscription change notifications - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Subscribers's information SubscriberInfo subscriber = 2; @@ -273,9 +272,6 @@ message FetchSubscriptionsResponse { // Set to true if the batch did not return all records optional bool has_more_records = 2; - - // Status of the query - uprotocol.v1.UStatus status = 3; } @@ -284,13 +280,15 @@ message FetchSubscriptionsResponse { // as information about the subscriber who wishes to receive said notifications message NotificationsRequest { // Topic to register/unregister to receive subscription change notifications - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Subscribers's information SubscriberInfo subscriber = 2; } - +// The (empty) response message representing the successful execution of the +// RegisterForSubscriptionChanges and UnregisterForSubscriptionChanges operations. +message NotificationsResponse {} // Subscription Update Message. // This Update message is sent from uSusbcription on the topic: @@ -299,12 +297,12 @@ message NotificationsRequest { // any uE that called RegisterForNotifications(). message Update { // Subscribed topic whos state has changed - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Information about the subscriber who changed their subscription SubscriberInfo subscriber = 2; - // Current status of the subscription (state, code, etc...) + // Current status of the subscription SubscriptionStatus status = 3; // Subscribers subscription attributes @@ -354,3 +352,6 @@ message ResetRequest { } } } + +// The (empty) response message representing the successful execution of the Reset operation. +message ResetResponse {} diff --git a/up-core-api/uprotocol/core/utwin/v2/utwin.proto b/up-core-api/uprotocol/core/utwin/v2/utwin.proto index c2871cc..69885dd 100644 --- a/up-core-api/uprotocol/core/utwin/v2/utwin.proto +++ b/up-core-api/uprotocol/core/utwin/v2/utwin.proto @@ -32,25 +32,23 @@ service uTwin { option (uprotocol.service_id) = 26; // A uE calls this API to retrieve the last uMessages for a given set of topics.
- // What is returned is a list of MessageResponse with the status for message retreival + // What is returned is a list of MessageResponse with the status for message retrieval // and the event itself if uTwin was able to fetch it. uTwin will also return // status for those messages that it was unable to fetch (i.e. due to NOT_FOUND // or PERMISSION_DENIED.
- rpc GetLastMessages(uprotocol.v1.UUriBatch) returns (GetLastMessagesResponse) { + rpc GetLastMessages(GetLastMessagesRequest) returns (GetLastMessagesResponse) { option (uprotocol.method_id) = 1; } // A call to SetLasMessage (typically from uBus) to update the uTwin internal cache // with a message for a given topic (UMessage.source). - // Return value status.Code is one of: - // - OK if UMessage was successfully stored in uTwin - // - INVALID argument if uTwin encountered an issue with UMessage content (source field in particular) + // If setting the value fails, the response is a UStatus with code + // - INVALID_ARGUMENT if uTwin encountered an issue with UMessage content (source field in particular) // - PERMISSION_DENIED if requesting uE does not have permission to access the Topic // - RESOURCE_EXHAUSTED if uTwin has no more memory available to store new UMessages - rpc SetLastMessage(uprotocol.v1.UMessage) returns (uprotocol.v1.UStatus) { + rpc SetLastMessage(SetLastMessageRequest) returns (SetLastMessageResponse) { option (uprotocol.method_id) = 2; } - } @@ -66,9 +64,22 @@ message MessageResponse { uprotocol.v1.UMessage message = 3; } +// The request message for the GetLastMessage operation. +message GetLastMessagesRequest { + // The topics to get the last message for + uprotocol.v1.UUriBatch topics = 1; +} // Message returned by the rpc GetLastMessages. message GetLastMessagesResponse { // List of one or more messages and the results for fetching the message per topic repeated MessageResponse responses = 2; } + +// The request message for the SetLastMessage operation. +message SetLastMessageRequest { + uprotocol.v1.UMessage message = 1; +} + +// The (empty) response message representing the successful execution of the SetLastMessage operation. +message SetLastMessageResponse {}