Skip to content

Commit

Permalink
uProtocol Options Cleanup (#141)
Browse files Browse the repository at this point in the history 
* uProtocol Options Cleanup

The following change addresses a number of concerns with the uprotocol_options.proto that is used to declare protocol specific metadata.

* missing the java package name

* Incorporate feedback from Yuval

* Adding the someip compiler options

* Update basics/permissions.adoc

Co-authored-by: Kai Hudalla <kai.hudalla@bosch.com>

* Update up-l3/udiscovery/v3/README.adoc

Co-authored-by: Kai Hudalla <kai.hudalla@bosch.com>

* add missing EOL

* Incorporate more feedback from Halim and Yuval

* make UServiceTopic::permission_level optional

---------

Co-authored-by: Kai Hudalla <kai.hudalla@bosch.com>
  • Loading branch information
@sophokles73
Steven Hartley and sophokles73 authored May 22, 2024
1 parent d60a593 commit a19bdc2
Show file tree
Hide file tree
Showing 13 changed files with 338 additions and 156 deletions.
2 changes: 1 addition & 1 deletion basics/permissions.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ While inspired by Android’s permission, CAPs under the current proposal are di

=== Service Declaration of uPLs

Services declare their uPLs as google.protobuf CustomOptions within their protos. The options are declared in link:../../up-core-api/uprotocol/uprotocol_options.proto[uprotocol_options.proto] and their purpose is defined in <<cap-options>> below.
Services declare their uPLs as google.protobuf CustomOptions within their protos. The options are declared in link:../up-core-api/uprotocol/uoptions.proto[uoptions.proto] and their purpose is defined in <<cap-options>> below.

* uPL value *MUST* be an integer, 0 to N, where N is the most permissive level. The default value is 0.

Expand Down
50 changes: 18 additions & 32 deletions up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,23 +15,23 @@ syntax = "proto3";

package uprotocol.core.udiscovery.v3;
import "google/protobuf/timestamp.proto";
import "uprotocol_options.proto";
import "uri.proto";
import "ustatus.proto";
import "uoptions.proto";
import "v1/uri.proto";
import "v1/ustatus.proto";

option java_package = "org.eclipse.uprotocol.core.udiscovery.v3";
option java_outer_classname = "UDiscoveryProto";
option java_multiple_files = true;

// Platform USE Discovery Service Interface
service uDiscovery {
option (name) = "core.udiscovery"; // Service name
option (version_major) = 3;
option (version_minor) = 0;
option (id) = 1;
option (uprotocol.service_name) = "core.udiscovery"; // Service name
option (uprotocol.service_version_major) = 3;
option (uprotocol.service_version_minor) = 0;
option (uprotocol.service_id) = 1;

// uDiscovery Node Change Notification that sends the Update message
option (notification_topic) = {
option (uprotocol.notification_topic) = {
id: 0x8000,
name: "NodeChange",
message: "Notification"
Expand All @@ -48,14 +48,14 @@ service uDiscovery {
// 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) {
option (method_id) = 1;
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) {
option (method_id) = 2;
option (uprotocol.method_id) = 2;
}

// Query the database to find Node(s). What is passed is the search criterial in
Expand All @@ -68,12 +68,12 @@ service uDiscovery {
// 4. uResource: `//device.domain/body.access//door.door_front_left`
// **NOTE:** You MUST have read permission to the node in the database
rpc FindNodes(FindNodesRequest) returns (FindNodesResponse) {
option (method_id) = 3;
option (uprotocol.method_id) = 3;
}

// Query the database to fetch a list of 1 or more properties for a given node.
rpc FindNodeProperties(FindNodePropertiesRequest) returns (FindNodePropertiesResponse) {
option (method_id) = 4;
option (uprotocol.method_id) = 4;
}

// Remove one or more nodes (and all its children nodes) in the database.
Expand All @@ -82,36 +82,36 @@ service uDiscovery {
// 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) {
option (method_id) = 5;
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.
// **NOTE:** You MUST have write permission to the parent node
rpc AddNodes(AddNodesRequest) returns (uprotocol.v1.UStatus) {
option (method_id) = 6;
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) {
option (method_id) = 7;
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) {
option (method_id) = 8;
option (uprotocol.method_id) = 8;
}


// Unregister for Node change notifications
rpc UnregisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) {
option (method_id) = 9;
option (uprotocol.method_id) = 9;
}


Expand All @@ -123,7 +123,7 @@ service uDiscovery {
// - 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
rpc ResolveUri(ResolveUriRequest) returns (ResolveUriResponse) {
option (method_id) = 10;
option (uprotocol.method_id) = 10;
}
}

Expand Down Expand Up @@ -344,17 +344,3 @@ message LookupUriResponse {
v1.UUriBatch uris = 1; // Batch of Uris
uprotocol.v1.UStatus status = 2; // Return code for the rpc call
}


// Node Notification Topic
// Service Meta-data structure used to build the notification topic when there are
// changes to a Node in the database. This message build the topic:
// '/core.udiscovery/3/nodes#Notification'.
// **NODE:** This message definition is ONLY used to autogenerate the Node Change Notification topic.
message NodeNotificationTopic {
// Service meta-data option definition - Topic identity
option (base_topic_id) = 1000;

// Meta flags for generating the YAML
Notification.Resources resource_name = 1 [(resource_name_mask) = "*"];
}
30 changes: 15 additions & 15 deletions up-core-api/uprotocol/core/usubscription/v3/usubscription.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,23 +17,23 @@ package uprotocol.core.usubscription.v3;

import "google/protobuf/any.proto";
import "google/protobuf/timestamp.proto";
import "ustatus.proto";
import "uri.proto";
import "uprotocol_options.proto";
import "v1/ustatus.proto";
import "v1/uri.proto";
import "uoptions.proto";

option java_package = "org.eclipse.uprotocol.core.usubscription.v3";
option java_outer_classname = "USubscriptionProto";
option java_multiple_files = true;

// Subscription Service Interface definition
service uSubscription {
option (name) = "core.usubscription"; // Service name
option (version_major) = 3;
option (version_minor) = 0;
option (id) = 0;
option (uprotocol.service_name) = "core.usubscription"; // Service name
option (uprotocol.service_version_major) = 3;
option (uprotocol.service_version_minor) = 0;
option (uprotocol.service_id) = 0;

// uSubscription change Notification topic that sends the Update message
option (notification_topic) = {
option (uprotocol.notification_topic) = {
id: 0x8000,
name: "SubscriptionChange",
message: "Update"
Expand All @@ -49,35 +49,35 @@ service uSubscription {
// to received subscription change notifications if ever the subscription state
// changes.
rpc Subscribe(SubscriptionRequest) returns (SubscriptionResponse) {
option (method_id) = 1;
option (uprotocol.method_id) = 1;
}

// The consumer no longer wishes to subscribe to a topic so it issues an
// explicit unsubscribe request.
rpc Unsubscribe(UnsubscribeRequest) returns (uprotocol.v1.UStatus) {
option (method_id) = 2;
option (uprotocol.method_id) = 2;
}

// Fetch a list of subscriptions
rpc FetchSubscriptions(FetchSubscriptionsRequest) returns (FetchSubscriptionsResponse) {
option (method_id) = 3;
option (uprotocol.method_id) = 3;
}


// Register to receive subscription change notifications that are published on the
// 'up:/core.usubscription/3/subscriptions#Update'
rpc RegisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) {
option (method_id) = 6;
option (uprotocol.method_id) = 6;
}

// Unregister for subscription change events
rpc UnregisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) {
option (method_id) = 7;
option (uprotocol.method_id) = 7;
}

// Fetch a list of subscribers that are currently subscribed to a given topic.
rpc FetchSubscribers(FetchSubscribersRequest) returns (FetchSubscribersResponse) {
option (method_id) = 8;
option (uprotocol.method_id) = 8;
}

// Reset subscriptions to and from the uSubscription Service.
Expand All @@ -88,7 +88,7 @@ service uSubscription {
// **__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) {
option (method_id) = 9;
option (uprotocol.method_id) = 9;
}
}

Expand Down
20 changes: 10 additions & 10 deletions up-core-api/uprotocol/core/utwin/v2/utwin.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,29 +15,29 @@ syntax = "proto3";

package uprotocol.core.utwin.v2;

import "uprotocol_options.proto";
import "ustatus.proto";
import "uri.proto";
import "umessage.proto";
import "uoptions.proto";
import "v1/ustatus.proto";
import "v1/uri.proto";
import "v1/umessage.proto";

option java_package = "org.eclipse.uprotocol.core.utwin.v2";
option java_outer_classname = "UTwinProto";
option java_multiple_files = true;

// uTwin Service interface definition
service uTwin {
option (name) = "core.utwin"; // Service name
option (version_major) = 2;
option (version_minor) = 0;
option (id) = 26;
option (uprotocol.service_name) = "core.utwin"; // Service name
option (uprotocol.service_version_major) = 2;
option (uprotocol.service_version_minor) = 0;
option (uprotocol.service_id) = 26;

// A uE calls this API to retrieve the last uMessages for a given set of topics.<br>
// What is returned is a list of MessageResponse with the status for message retreival
// 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.<br>
rpc GetLastMessages(uprotocol.v1.UUriBatch) returns (GetLastMessagesResponse) {
option (method_id) = 1;
option (uprotocol.method_id) = 1;
}

// A call to SetLasMessage (typically from uBus) to update the uTwin internal cache
Expand All @@ -48,7 +48,7 @@ service uTwin {
// - 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) {
option (method_id) = 2;
option (uprotocol.method_id) = 2;
}

}
Expand Down
Loading

0 comments on commit a19bdc2

Please sign in to comment.