Skip to content

Commit

Permalink
Use dedicated messages in service operations (#163)
Browse files Browse the repository at this point in the history 
* [#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
  • Loading branch information
@sophokles73
sophokles73 authored May 28, 2024
1 parent becbf89 commit 2385018
Show file tree
Hide file tree
Showing 3 changed files with 87 additions and 67 deletions.
76 changes: 42 additions & 34 deletions up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/`
Expand All @@ -77,48 +75,47 @@ 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;
}


// 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
Expand Down Expand Up @@ -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 {
Expand All @@ -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;
}


Expand All @@ -235,9 +234,6 @@ message FindNodePropertiesRequest {
message FindNodePropertiesResponse {
// a list of property name/value pairs
map <string, PropertyValue> properties = 1;

// Return code for the rpc call
uprotocol.v1.UStatus status = 2;
}


Expand All @@ -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 {
Expand All @@ -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
Expand Down Expand Up @@ -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;
}
53 changes: 27 additions & 26 deletions up-core-api/uprotocol/core/usubscription/v3/usubscription.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

Expand All @@ -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;
}

Expand All @@ -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;
}
}
Expand Down Expand Up @@ -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;
Expand All @@ -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;
}
Expand All @@ -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;
Expand All @@ -183,34 +182,36 @@ 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
// information for how the subscriber should consume the published events.
EventDeliveryConfig config = 2;

// Subscription topic passed to SubscriptionRequest
v1.UUri topic = 3;
uprotocol.v1.UUri topic = 3;
}


// Passed to the Unsubscribe() API, the message contains the topic to unsubscribe
// 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;
Expand All @@ -220,27 +221,25 @@ 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;
}


// Subscription Message. Contains all the information about a subscription that
// 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
Expand All @@ -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;
Expand All @@ -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;
}


Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -354,3 +352,6 @@ message ResetRequest {
}
}
}

// The (empty) response message representing the successful execution of the Reset operation.
message ResetResponse {}
Loading

0 comments on commit 2385018

Please sign in to comment.