From f065ef7f6f6fa1e41ef5115edd8674dd1db1133e Mon Sep 17 00:00:00 2001 From: mayuresh Date: Thu, 18 Apr 2024 11:14:56 -0400 Subject: [PATCH 01/11] Updates to discovery proto and readme --- .../core/udiscovery/v3/udiscovery.proto | 299 +++--------------- up-l3/udiscovery/v3/README.adoc | 88 +----- up-l3/udiscovery/v3/find_node.puml | 8 +- up-l3/udiscovery/v3/lookup_uri.puml | 91 ------ 4 files changed, 66 insertions(+), 420 deletions(-) delete mode 100644 up-l3/udiscovery/v3/lookup_uri.puml diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 8a01182..be230b9 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -41,15 +41,6 @@ service uDiscovery { option (version_minor) = 0; option (id) = 1; - // uDiscovery Node Change Notification that sends the Update message - option (notification_topic) = { - id: 0x8000, - name: "NodeChange", - message: "Notification" - }; - - - // 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. @@ -58,74 +49,27 @@ service uDiscovery { // 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 FinduE(FinduERequest) returns (FinduEResponse) { option (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) { + // Retrieve the list of topics for a given uE + rpc GetuETopics(GetuETopicsRequests) returns (GetuETopicsResponse){ option (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: - // 1. uDomain: `//*.device/` - // 2. uDevice: `//device` - // 3. uService: `//device.domain/body.access/` - // 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; - } - - // Query the database to fetch a list of 1 or more properties for a given node. - rpc FindNodeProperties(FindNodePropertiesRequest) returns (FindNodePropertiesResponse) { + // Retrieve the list of uEs under a device. + // Input argument : Valid device URI + // Output : List of all uEs under that device and appropriate status message + rpc GetuEList(GetuEListRequest) returns (GetuEListResponse){ option (method_id) = 4; } - // 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 GetDeviceList(GetDeviceListRequest) returns (GetDeviceListResponse){ option (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; - } - - - // 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; - } - - - // 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; - } - - - // Unregister for Node change notifications - rpc UnregisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) { - option (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: @@ -139,201 +83,69 @@ service uDiscovery { } -// Typedef for a node properties. A node property can be any one of the uProtocol ("u_") types -// defined below -message PropertyValue { - oneof attr { - bool u_boolean = 1; // Boolean - int32 u_integer = 2; // Integer - string u_string = 3; // String - bytes u_bytes = 4; // Raw Bytes - string u_uri = 5; // A URI - google.protobuf.Timestamp u_timestamp = 6; // Timestamp - double u_double = 7; // Double - int64 u_integer_64 = 8; // 64 bit Integer - } -} - - -// Node can be domain, device, service, resource, method, etc... -message Node { - // uProtocol long form URI pointing to this node - string uri = 1; - - // List of child nodes under this node - repeated Node nodes = 2; - - // List of node properties - map properties = 3; - - // The node type - Type type = 4; - - - // What is the uThing (stored in Node) type. This is used to more easily - // identify the Node rather than parsing from uri and inferring the type - enum Type { - UNSPECIFIED = 0; // Unspecified node type - DOMAIN = 1; // uDomain - DEVICE = 2; // uDevice - ENTITY = 3; // uEntity (uE) - VERSION = 9; // uEntity version - TOPIC = 4; // uE Topic - METHOD = 5; // uE Method - MESSAGE = 6; // uE Message - RESOURCE = 7; // uE Resource - USER = 8; // User Information - } -} - - -// Message passed to the UpdateNode() RPC call -message UpdateNodeRequest { - // Node to be updated in the database - Node node = 1; - - // Time-to-live: How long (ms) the information should be live for in the database. - // -1 means lives forever - optional int32 ttl = 3; -} - - -// Delete one or more nodes request -message DeleteNodesRequest { - repeated string uris = 1; // uProtocol formatted URI -} - - -// FindNodesRequest passed to FindNodes() -message FindNodesRequest { - // uProtocol formatted URI for the node to search, ex. '//vcu.VIN/core.app.hartley' - // shall return the 'core.app.hartley' node +message FinduERequest { string uri = 1; - - // How deep in the node tree should the results return. A value of -1 or - // the field is not present means all child nodes are returned, value of 0 - // returns only the parent node, any other value is the depth of child nodes - optional int32 depth = 2; } - -// 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; +// Return value from FinduE() API that contains the batch of Uris for the +// lookup and status from the API call +message FinduEResponse { + v1.UUriBatch uris = 1; // Batch of Uris + uprotocol.v1.UStatus status = 2; // Return code for the rpc call } -// Find 1 or more properties for a given node passed to FindNodeProperties() -message FindNodePropertiesRequest { - // the uri for the node in the database - string uri = 1; - // List of 1 or more properties names to fetch from the database - // **NOTE:** When this is not populated with any property name, all properties are returned - repeated string properties = 2; +message GetuETopicsRequest { + v1.UUri UE = 1; } -// Returned from FindNodeProperties() -message FindNodePropertiesResponse { - // a list of property name/value pairs - map properties = 1; +// Response data for GetUEtopics. +// Possible return values in status are: +// 1. code.OK: Query lookup was successful +// 2. code.NOT_FOUND: No matching UUris were found +// 3. code.INVALID_ARGUMENT: The passed UUri is invalid +message GetuETopicsResponse { - // Return code for the rpc call - uprotocol.v1.UStatus status = 2; + repeated v1.UUri topicList = 1; + uprotocol.v1.UStatus status = 2; // Return code for the rpc call } +message GetUEListRequest{ -// Passed to AddNodes() API containing the parent node URI and a list of nodes -message AddNodesRequest { - // the URI of the parent node that you would like to add nodes to - string parent_uri = 1; - - // One or more nodes that you would like to add to the parent node. - // **NOTE:** The node uri field MAY be unqualified meaning it does not include the parent_uri - // authority & path). Support for unqualified URIs allows for the same node to be inserted into - // multiple parent nodes (ex. installing a uE node to multiple uDevice parent nodes) - repeated Node nodes = 2; + v1.UUri UDevice = 1; } +// Response data for GetUEtopics. +// Possible return values in status are: +// 1. code.OK: Query lookup was successful +// 2. code.NOT_FOUND: No matching UUris were found +// 3. code.INVALID_ARGUMENT: The passed UUri is invalid +message GetuEListResponse { -// Message passed to UpdateProperty() to update a property in a Node -message UpdatePropertyRequest { - // the uri for the node whos property will be updated - string uri = 1; - - // The name of the property that is to be updated - string property = 2; - - // The value to set in the property - PropertyValue value = 3; + repeated v1.UUri UEList = 1; + uprotocol.v1.UStatus status = 2; // Return code for the rpc call } -// Node Change Notification Message. -// When uEs call RegisterForNotifications(), a Notification message is sent when the node either -// changes, added, or removed. -message Notification { - // The URI to the node that has changed - string uri = 1; - - // the URI of the parent node (if it was affected) - optional string parent_uri = 2; - - // The operation performed on said Node - Operation operation = 3; +message GetDeviceListRequest{ - // Operation - enum Operation { - INVALID = 0; // Invalid - UPDATE = 1; // Updated - ADD = 2; // Added to the parent - REMOVE = 3; // Removed - } - - // Time-to-live: How long (ms) the information should be live for in the database. - // A value of -1 means lives forever. - optional int32 ttl = 4; - - // uDiscovery resource that it serves (per SDV-202 definition): database - enum Resources { nodes = 0; } + v1.UUri UDomain = 1; } +// Response data for GetUEtopics. +// Possible return values in status are: +// 1. code.OK: Query lookup was successful +// 2. code.NOT_FOUND: No matching UUris were found +// 3. code.INVALID_ARGUMENT: The passed UUri is invalid +message GetuEListResponse { -// Observer Identification Information -message ObserverInfo { - // Fully qualified URI for the Observer who is registering to receive the - // notifications from uDiscovery ex. `//vcu.VIN/com.gm.app.hartley` - string uri = 1; + repeated v1.UUri deviceList = 1; + uprotocol.v1.UStatus status = 2; // Return code for the rpc call } -// Passed to the RegisterForNotifications() and UnregisterForNotifications() -// APIs this message includes the list of one or more node addresses we would like -// to receive updates for as well as information about the caller so the notification -// can be routed to the right destination. -message NotificationsRequest { - // A list of one or more Node URIs to receive notifications for - repeated string uris = 1; - - // Observer's identification information - ObserverInfo observer = 2; - - // How deep in the node tree should the notifications be sent for. A value of -1 or if - // the field is not present in the message, signifies that changes to any child nodes will trigger - // a Notification event. A value of 0 returns only the parent node. Any other value specified is - // the depth of child nodes to receive notifications for. - optional int32 depth = 3; -} - // Request message passed to ResolveUri() API to resolve the missing names or numbers. message ResolveUriRequest { // The URI to resolve containing only names or numbers @@ -341,31 +153,10 @@ message ResolveUriRequest { } -// Response message returned from ResolveUri() API containing a UUri and the +// Response returned from ResolveUri() API containing a UUri and the // status of the resolution. message ResolveUriResponse { v1.UUri uri = 1; // Resolved UUri - uprotocol.v1.UStatus status = 3; // Return code for the rpc call -} - - -// Return value from LookupUri() API that contains the batch of Uris for the -// lookup and status from the API call -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) = "*"]; -} \ No newline at end of file diff --git a/up-l3/udiscovery/v3/README.adoc b/up-l3/udiscovery/v3/README.adoc index 6e02a76..9bc0c5d 100644 --- a/up-l3/udiscovery/v3/README.adoc +++ b/up-l3/udiscovery/v3/README.adoc @@ -1,7 +1,6 @@ = uDiscovery :toc: :sectnums: - The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document are to be interpreted as described in https://www.rfc-editor.org/info/bcp14[IETF BCP14 (RFC2119 & RFC8174)] ---- @@ -31,9 +30,9 @@ SPDX-License-Identifier: Apache-2.0 == Purpose -uE's (Software Entities) will be deployed dynamically on devices that are scattered throughout the uProtocol network. In order for these dynamically deployed uE's to be able to know about what is available on their own device or on other devices, we need the ability to discover not only uEs but also what uEs serve (resources, methods, messages, etc...) as well as properties about devices. There exists today a number of Internet protocols such as DNS, Zeroconf, and others, to discover devices and of services running on said devices. the goal is to reuse as much as possible, existing Internet standards for discovering of uThings as well. +uE's (Software Entities) will be deployed dynamically on devices that are scattered throughout the uProtocol network. In order for these dynamically deployed uE's to be able to know about what is available on their own device or on other devices, we need the ability to discover uEs and what they serve (resources, methods, messages, etc...). There are number of Internet protocols such as DNS, Zeroconf, and others, to discover devices and services running on said devices. Intent of uDiscovery is to reuse as much as possible, existing Internet standards for discovering of uThings as well. -The purpose of this proposal is to define the discovery architecture so that uEs can dynamically discovery uThings (other uEs, uDevices, uDomains, uResources, uMethods, etc...), for example what topics a service in another device shall publish, properties of a service, etc... +The purpose of this proposal is to define the discovery architecture so that uEs can dynamically discovery uThings (other uEs, uDevices, uDomains, uResources, uMethods, etc...), for example what topics a service in another device shall publish. == Background @@ -46,14 +45,14 @@ The purpose of this proposal is to define the discovery architecture so that uEs |DNS |Domain Name System covered in various IETF RFCs |CDS |Central Discovery Service implementation of uDiscovery |LDS |Local (to a device) implementation of uDiscovery -|Local Node |Node who is local to the device (local information) -|Remote Node |Node that is fetched from the CDS and cached in the LDS +|Local Entity |Entity who is local to the device (local information) +|Remote Entity |Entity which is hosted on a different device. This is fetched from CDS and cached in the LDS |=== == Overview -uDiscovery provides the ability to discovery stuff that is addressable using UUri notation (devices, services, topics/methods) as well as properties of said stuff. +uDiscovery provides the ability to discover stuff that is addressable using UUri notation (devices, services, topics/methods). NOTE: Data model and interface is described in link:../../../up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto[udiscovery.proto] @@ -70,17 +69,17 @@ NOTE: Components described in <> below all implement link:../../ |Component |Description |Requirements |*Local uDiscovery Service (LDS)* -|Service to provide discovery of uThings per device. Every LDS has-a database that stores all of its local Nodes as well as caches node information for remote devices. +|Service to provide discovery of uThings per device. Every LDS has-a database that stores information of all local entities. In addition, it caches information for uEs on other devices. a|* Every uDevice *MUST* have LDS | *Domain uDiscovery Service (uDDS)* -| Storage for discovery information for all devices within its domain +| Service to provide discovery of all uThings per domain. a| -* uDDS *MUST* store `Nodes` for all the devices under a given domain hierarchy +* uDDS *MUST* store `uEs` for all the devices under a given domain hierarchy * *MUST* be only one uDDS within a domain -* A uLDS *MAY* be also function as uDDS and a uCDS for a uDomain or network +* A uLDS *MAY* also function as uDDS and/or a uCDS for a uDomain or network * uDDS *MUST* support queries from uLDSs that are within its domain -* uDDS *MUST* relay quires from uLDS to the uCDS and then cache the results per the TTL requirements from query API response +* uDDS *MUST* relay queries from uLDS to the uCDS and then cache the results per the TTL requirements from query API response * uDDS *SHOULD* be located in the always-on uDevices |*Central uDiscovery Service (CDS)* @@ -278,13 +277,6 @@ NOTE: uCDS or uDDS MAY allow local notification registration when it is also act NOTE: Dynamic discovery of the CDS is out of scope at the time of writing of this specification and as such the CDS authority is known to the LDS. The CDS does not need to call `RegisterForNotifications()`, the LDS simply sends the notification event to the CDS. -==== Registration - -When a uE wants to be notified of changes to Nodes for either local or remote devices, the uE calls RegisterForNotifications() passing the list of URIs of said nodes. Figure below illustrates the usage of the notification registration API. - -.Registration for Notifications -image:notifications.svg[Notifications] - === Read/Query APIs Query APIs are used to lookup content in the database, either to resolve URIs (to be used by applications) or to fetch content of a database. @@ -294,67 +286,21 @@ Query APIs are used to lookup content in the database, either to resolve URIs (t * Remote Nodes that have `expired` *MUST* be refreshed to the CDS * Locally `expired` Nodes *MUST NOT* be returned in a query -==== URI Resolution: LookupUri() - -Used by any uEs to find service instance location, and its current version. What is returned is a list of Uri strings of fully qualified uris. The lookup searches the node database to find instances that match the search criteria. - -.Lookup URI -image:lookup_uri.svg[LookupURI] - -==== Find Node - -Figure below illustrates the flows for performing a query to the LDS. An _empty node_, shown in the figure below, is a node with only the URI populated and is returned from LDS and CDS when the node is not found. The _empty node_ is used by the LDS to know that a node does not exist in the CDS and we do not need to keep querying the same node. +==== Find UE +Figure below illustrates the flows for performing a query to the LDS. Uri details for requested uE are returned if found in uLDS first, else the query is sent to uDDS and in turn to uCDS if required. * *MUST* update `last_accessed` Node attribute when API is called -.Find Node -image:find_node.svg[FindNode] - -=== Write APIs - -uDiscovery includes a set of APIs that allows uEs to change the content of the database. We will explain each APIs functions in the following section. - -* *MUST* only allow uEs to update their own Node -* When `ttl` is not specified, *MUST* assume -1 (live forever) -* *MUST* verify caller has write permission to update, add, or delete a Node -* *MUST* verify caller has write permission the parent node when adding or deleting a Node -* *MUST* set the Node's `last_updated` to the current time when a write API is called - -Additional CDS Requirements: +image:FindUE.svg[FinduE] -* LDS *SHALL* ONLY be permitted to update Node information for which the uDevice that the LDS runs on is in the list of ancestors of the Node. +==== Get UE Topics -==== Updating a Node +Get uE Topics is used to fetch the list of topics published by a uE. -Below is the sequence when a change happens in the database -.Updating Nodes -image:update_nodes.svg["Update Nodes"] - -==== Adding Node(s) - -Below we shall give an example of a service called `uOTA` that will install a new service called `uService` to `Device1` illustrating how the `AddNodes()` API could be used. We will also show how the Update notification is sent to two observers; local uApp and the CDS (a remote observer). - -.Add Nodes -image:add_nodes.svg[Add Nodes] - - -==== Deleting Node(s) - -DeleteNode() API informs uDiscovery to tag a Node to be inactive. that the Node is no longer active Below shall provide an example of a service called `uOTA` that shall remove a service called `uService` from `Device1` illustrating how the `DeleteNode()` API can be used to remove a uE. We will also show how the Update notification is sent to two observers; a local uApp and the CDS (remote observer). - -.Delete Node -image:delete_node.svg[Delete Node] - - -==== ResolveUri - -`ResolveUri()` is used to lookup names from ids or vice versa meaning to go to/from Long Uri from/to micro Uri. - -For portability between SDKs, Long Form URIs shall be serialized to String and Short form Uris shall be serialized to Bytes per link:../../../basics/uri.adoc[URI Specifications]. +* *MUST* update `last_accessed` Node attribute when API is called - * *MUST* be passed either a Long or Short form URI and return both the Micro and Long form URI if successful == Failure Recovery -In the event that the databases between the CDS and LDS becomes out of sync, the discovery service components (uLDS, uDDS, uCDS) *MAY* fetch the contents using `FindNodes()` API. +In the event that the databases between the CDS and LDS becomes out of sync, the discovery service components (uLDS, uDDS, uCDS) *MAY* fetch the contents using read APIs. diff --git a/up-l3/udiscovery/v3/find_node.puml b/up-l3/udiscovery/v3/find_node.puml index f8d2541..434c2ac 100644 --- a/up-l3/udiscovery/v3/find_node.puml +++ b/up-l3/udiscovery/v3/find_node.puml @@ -34,12 +34,12 @@ end box entity CDS #orange group Local uDevice Query - uEs -> LDS: FindNodes(FindNodesRequest) + uEs -> LDS: FinduE(FinduERequest) note right - **FindNodesRequest:** - ""uri"": "up://Device1/uService" - ""depth"": -1 + **UriRequest:** + ""uri"": ""//topic//"" end note + alt Found LDS --> uEs: FindNodesResponse note right diff --git a/up-l3/udiscovery/v3/lookup_uri.puml b/up-l3/udiscovery/v3/lookup_uri.puml deleted file mode 100644 index f7632e3..0000000 --- a/up-l3/udiscovery/v3/lookup_uri.puml +++ /dev/null @@ -1,91 +0,0 @@ -@startuml -'https://plantuml.com/sequence-diagram - -' Copyright (c) 2023 General Motors GTO LLC -' -' Licensed to the Apache Software Foundation (ASF) under one -' or more contributor license agreements. See the NOTICE file -' distributed with this work for additional information -' regarding copyright ownership. The ASF licenses this file -' to you under the Apache License, Version 2.0 (the -' "License"); you may not use this file except in compliance -' with the License. You may obtain a copy of the License at -' -' http://www.apache.org/licenses/LICENSE-2.0 -' -' Unless required by applicable law or agreed to in writing, -' software distributed under the License is distributed on an -' "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -' KIND, either express or implied. See the License for the -' specific language governing permissions and limitations -' under the License. -' -' SPDX-FileCopyrightText: 2023 General Motors GTO LLC -' SPDX-FileType: SOURCE -' SPDX-License-Identifier: Apache-2.0 - - -autonumber - -box uDevice #white - Collections uEs #red - entity LDS #orange -end box -entity CDS #orange - -uEs -> LDS: LookupUri(UriRequest) -note right -**UriRequest:** -""uri"": ""//topic//"" -end note - -alt Found Locally -LDS --> uEs: UriResponse -note right -**UriRequest:** -""uris"": {""//topic//"", ""//topic//""} -""result"": {""code"": ""OK""} -end note -||| -else Invalid Argument or Permission Denied -LDS --> uEs: UriResponse -note right -**UriResponse:** -""result"" : { ""code"": ""INVALID_ARGUMENT | PERMISSION_DENIED"" } -end note -||| -else Remote Lookup Required -LDS -> CDS: LookupUri(UriRequest) -alt Success -CDS --> LDS: UriResponse -note right -**UriResponse:** -""uris"": {""//topic//"", ""//topic//""} -""result"": {""code"": ""OK""} -end note -LDS -> LDS: Cache (per ttl) -LDS --> uEs: UriResponse -note right -**UriResponse:** -""uris"": {""//topic//"", ""//topic//""} -""result"": {""code"": ""OK""} -end note -else Failure -CDS --> LDS: UriResponse -note right -**UriResponse:** -""result"": {""code"": ""INVALID_ARGUMENT | NOT_FOUND | PERMISSION_DENIED""} -end note -LDS --> uEs: UriResponse -end alt - -else Not Found -LDS --> uEs: UriResponse -note right -**UriResponse:** -""result"": {""code"": ""NOT_FOUND""} -end note -end alt - -LDS --> uEs: UriResponse -@enduml \ No newline at end of file From 2e89ef2ede3715253b57fe338c47117c91b57da2 Mon Sep 17 00:00:00 2001 From: mayuresh Date: Thu, 18 Apr 2024 11:25:03 -0400 Subject: [PATCH 02/11] Add sequence diagram for FindUE --- up-l3/udiscovery/v3/FindUE.puml | 114 ++++++++++++++++++++++++++++++++ up-l3/udiscovery/v3/FindUE.svg | 1 + 2 files changed, 115 insertions(+) create mode 100644 up-l3/udiscovery/v3/FindUE.puml create mode 100644 up-l3/udiscovery/v3/FindUE.svg diff --git a/up-l3/udiscovery/v3/FindUE.puml b/up-l3/udiscovery/v3/FindUE.puml new file mode 100644 index 0000000..53bb25a --- /dev/null +++ b/up-l3/udiscovery/v3/FindUE.puml @@ -0,0 +1,114 @@ +@startuml +'https://plantuml.com/sequence-diagram + +' Copyright (c) 2023 General Motors GTO LLC +' +' Licensed to the Apache Software Foundation (ASF) under one +' or more contributor license agreements. See the NOTICE file +' distributed with this work for additional information +' regarding copyright ownership. The ASF licenses this file +' to you under the Apache License, Version 2.0 (the +' "License"); you may not use this file except in compliance +' with the License. You may obtain a copy of the License at +' +' http://www.apache.org/licenses/LICENSE-2.0 +' +' Unless required by applicable law or agreed to in writing, +' software distributed under the License is distributed on an +' "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +' KIND, either express or implied. See the License for the +' specific language governing permissions and limitations +' under the License. +' +' SPDX-FileCopyrightText: 2023 General Motors GTO LLC +' SPDX-FileType: SOURCE +' SPDX-License-Identifier: Apache-2.0 + + +autonumber + +box uDevice #white + Collections uEs #red + entity uLDS #orange + entity uDDS #orange + entity uCDS #orange +end box +entity CDS #orange + +uEs -> uLDS: FinduE(FinduERequest) +note right +**FinduERequest:** +""uri"": ""//topic//"" +end note + +alt Found Locally +uLDS --> uEs: FinduEResponse +note right +**FinduEResponse:** +""uris"": {""//topic//"", ""//topic//""} +""result"": {""code"": ""OK""} +end note +||| +else Invalid Argument or Permission Denied +uLDS --> uEs: FinduEResponse +note right +**FinduEResponse:** +""result"" : { ""code"": ""INVALID_ARGUMENT | PERMISSION_DENIED"" } +end note +||| +else Remote Lookup Required +uLDS -> uDDS: FinduE(FinduERequest) +alt Success +uDDS --> uLDS: FinduEResponse +note right +**FinduEResponse:** +""uris"": {""//topic//"", ""//topic//""} +""result"": {""code"": ""OK""} +end note +uLDS -> uLDS: Cache (per ttl) +uLDS --> uEs: FinduEResponse +note right +**FinduEResponse:** +""uris"": {""//topic//"", ""//topic//""} +""result"": {""code"": ""OK""} +end note +||| +else Remote Lookup Required +uDDS -> uCDS: FinduE(FinduERequest) +alt Success +uCDS --> uDDS: FinduEResponse +note right +**FinduEResponse:** +""uris"": {""//topic//"", ""//topic//""} +""result"": {""code"": ""OK""} +end note +uDDS -> uDDS: Cache (per ttl) +uDDS --> uLDS: FinduEResponse +uLDS -> uLDS : Cache( per ttl) +uLDS --> uEs : FinduEResponse +note right +**FinduEResponse:** +""uris"": {""//topic//"", ""//topic//""} +""result"": {""code"": ""OK""} +end note +||| +else Failure +uDDS --> uLDS: FinduEResponse +note right +**FinduEResponse:** +""result"": {""code"": ""INVALID_ARGUMENT | NOT_FOUND | PERMISSION_DENIED""} +end note +uLDS --> uEs: FinduEResponse +end alt + +else Not Found +uLDS --> uEs: FinduEResponse +note right +**FinduEResponse:** +""result"": {""code"": ""NOT_FOUND""} +end note +end alt + +uLDS --> uEs: FinduEResponse +end alt +@enduml \ No newline at end of file diff --git a/up-l3/udiscovery/v3/FindUE.svg b/up-l3/udiscovery/v3/FindUE.svg new file mode 100644 index 0000000..f25a0ad --- /dev/null +++ b/up-l3/udiscovery/v3/FindUE.svg @@ -0,0 +1 @@ +uDeviceuEsuEsuLDSuLDSuDDSuDDSuCDSuCDSCDSCDS1FinduE(FinduERequest)FinduERequest:uri:topicalt[Found Locally]2FinduEResponseFinduEResponse:uris: {topic,topic}result: {code:OK}[Invalid Argument or Permission Denied]3FinduEResponseFinduEResponse:result: {code:INVALID_ARGUMENT | PERMISSION_DENIED}[Remote Lookup Required]4FinduE(FinduERequest)alt[Success]5FinduEResponseFinduEResponse:uris: {topic,topic}result: {code:OK}6Cache (per ttl)7FinduEResponseFinduEResponse:uris: {topic,topic}result: {code:OK}[Remote Lookup Required]8FinduE(FinduERequest)alt[Success]9FinduEResponseFinduEResponse:uris: {topic,topic}result: {code:OK}10Cache (per ttl)11FinduEResponse12Cache( per ttl)13FinduEResponseFinduEResponse:uris: {topic,topic}result: {code:OK}[Failure]14FinduEResponseFinduEResponse:result: {code:INVALID_ARGUMENT | NOT_FOUND | PERMISSION_DENIED}15FinduEResponse[Not Found]16FinduEResponseFinduEResponse:result: {code:NOT_FOUND}17FinduEResponse \ No newline at end of file From 04e5bf98196d15c9d83944d600d07a6777458ad9 Mon Sep 17 00:00:00 2001 From: mayuresh Date: Thu, 18 Apr 2024 13:30:34 -0400 Subject: [PATCH 03/11] Updated readme file for discovery --- up-l3/udiscovery/v3/README.adoc | 45 +++-------- up-l3/udiscovery/v3/add_nodes.puml | 100 ------------------------ up-l3/udiscovery/v3/add_nodes.svg | 1 - up-l3/udiscovery/v3/delete_node.puml | 71 ----------------- up-l3/udiscovery/v3/delete_node.svg | 1 - up-l3/udiscovery/v3/find_node.puml | 101 ------------------------- up-l3/udiscovery/v3/find_node.svg | 1 - up-l3/udiscovery/v3/lookup_uri.svg | 1 - up-l3/udiscovery/v3/notifications.puml | 86 --------------------- up-l3/udiscovery/v3/update_nodes.puml | 82 -------------------- 10 files changed, 9 insertions(+), 480 deletions(-) delete mode 100644 up-l3/udiscovery/v3/add_nodes.puml delete mode 100644 up-l3/udiscovery/v3/add_nodes.svg delete mode 100644 up-l3/udiscovery/v3/delete_node.puml delete mode 100644 up-l3/udiscovery/v3/delete_node.svg delete mode 100644 up-l3/udiscovery/v3/find_node.puml delete mode 100644 up-l3/udiscovery/v3/find_node.svg delete mode 100644 up-l3/udiscovery/v3/lookup_uri.svg delete mode 100644 up-l3/udiscovery/v3/notifications.puml delete mode 100644 up-l3/udiscovery/v3/update_nodes.puml diff --git a/up-l3/udiscovery/v3/README.adoc b/up-l3/udiscovery/v3/README.adoc index 9bc0c5d..2e88f29 100644 --- a/up-l3/udiscovery/v3/README.adoc +++ b/up-l3/udiscovery/v3/README.adoc @@ -30,9 +30,9 @@ SPDX-License-Identifier: Apache-2.0 == Purpose -uE's (Software Entities) will be deployed dynamically on devices that are scattered throughout the uProtocol network. In order for these dynamically deployed uE's to be able to know about what is available on their own device or on other devices, we need the ability to discover uEs and what they serve (resources, methods, messages, etc...). There are number of Internet protocols such as DNS, Zeroconf, and others, to discover devices and services running on said devices. Intent of uDiscovery is to reuse as much as possible, existing Internet standards for discovering of uThings as well. +uE's (Software Entities) will be deployed dynamically on devices that are scattered throughout the uProtocol network. In order for these uE's to know about what is available on their own device or on other devices, we need the ability to discover uEs, their locations and what they serve (resources, methods, messages, etc...). There are number of Internet protocols such as DNS, Zeroconf, and others, to discover devices and services running on said devices. Intent of uDiscovery is to reuse as much as possible, existing Internet standards for discovering uThings as well. -The purpose of this proposal is to define the discovery architecture so that uEs can dynamically discovery uThings (other uEs, uDevices, uDomains, uResources, uMethods, etc...), for example what topics a service in another device shall publish. +The purpose of this proposal is to define the discovery architecture so that uEs can dynamically discover uThings (other uEs, uDevices, uDomains, uResources, uMethods, etc...), for example what topics are served(publihed) by a uE in another device. == Background @@ -44,6 +44,7 @@ The purpose of this proposal is to define the discovery architecture so that uEs |Term |Definition |DNS |Domain Name System covered in various IETF RFCs |CDS |Central Discovery Service implementation of uDiscovery +|DDS | Domain Discovery Service(local to a domain) implemenation of uDiscovery |LDS |Local (to a device) implementation of uDiscovery |Local Entity |Entity who is local to the device (local information) |Remote Entity |Entity which is hosted on a different device. This is fetched from CDS and cached in the LDS @@ -52,7 +53,7 @@ The purpose of this proposal is to define the discovery architecture so that uEs == Overview -uDiscovery provides the ability to discover stuff that is addressable using UUri notation (devices, services, topics/methods). +uDiscovery provides the ability to discover things which are addressable using UUri notation (devices, services, topics/methods). NOTE: Data model and interface is described in link:../../../up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto[udiscovery.proto] @@ -69,7 +70,7 @@ NOTE: Components described in <> below all implement link:../../ |Component |Description |Requirements |*Local uDiscovery Service (LDS)* -|Service to provide discovery of uThings per device. Every LDS has-a database that stores information of all local entities. In addition, it caches information for uEs on other devices. +|Service to provide discovery of uThings per device. Every LDS stores information of all local entities. In addition, it caches information for uEs on other devices. a|* Every uDevice *MUST* have LDS | *Domain uDiscovery Service (uDDS)* @@ -82,17 +83,15 @@ a| * uDDS *MUST* relay queries from uLDS to the uCDS and then cache the results per the TTL requirements from query API response * uDDS *SHOULD* be located in the always-on uDevices -|*Central uDiscovery Service (CDS)* +|*Central uDiscovery Service (uCDS)* |Central repository storing all deployed uDevice information in the network of connected devices residing in the Cloud. It is a superset of the local uDiscovery database content a| * *MUST* have one CDS that is globally addressable by the various domain/device LDS |=== -Function specific requirements shall be covered later in this document. - === Hierarchical Specifications -The following section will elaborate on the uProtocol hierarchy elaborating how information is organized, referenced, and structured. This is the system classification specification used to identify and define "things" along with the storage of information (properties) of the uThings in the registry. +The following section will elaborate on the uProtocol hierarchy elaborating how information is organized, referenced, and structured. This is the system classification specification used to identify and define "things" . <> below introduces node and properties that we will define in this section. The diagram illustrates the hierarchy (taxonomy) for things in the network. @@ -205,7 +204,7 @@ NOTE: It is *STRONGLY RECOMMENDED* to scope your property names to avoid namespa === Database Access -The uDiscovery service, through the query and update APIs, allows any uE to discover or change the contents of the local and central databases. Given that we obviously do not want any uE to access anything in the database, we need to build in safety checks that are validated in both the local and central discovery service. +The uDiscovery service, through the query APIs, allows any uE to discover the contents from local and central databases. These APIs shall implement appropriate permission model to prevent unauthorized access. ==== Policy @@ -243,7 +242,6 @@ Node metadata are stored outside the Node structure and describe the Node itself |ttl |int32 |*REQUIRED* |Time-to-Live. How long (in milliseconds) the Node is valid for before it is outdated and needs to be refreshed. When the value is -1 the Node is considered to be valid forever. A Node is expired when the following is true: \begin\{array}\{l}\displaystyle expired = t_\{current} > t_\{last_updated} + ttl\end\{array} |last_updated |Timestamp |*REQUIRED* |Last time the content of the Node has changed (been written) |last_accessed |Timestamp |*OPTIONAL* |The last time the Node was read (accessed) from a FindNodes() API call -|inactive |bool |*REQUIRED* |The Node has been tagged as inactive through the DeleteNode() API call |=== API requirements related to Node metadata shall be covered in the subsequent section. @@ -253,37 +251,12 @@ API requirements related to Node metadata shall be covered in the subsequent sec In the following section we will explain the various APIs and interfaces that are defined in uDiscovery and their requirements. Interface definitions (input and output parameters, etc...) are covered in the link:../../../up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto[udiscovery.proto]. -=== Notifications - -Notifications are used for replicating information between uLDS, uDDS, and uCDS, and to notify local uEs if/when the content of the database has changed for various reasons such as: - -* Installation of a new service version -* Change in property values -* Updates to device configurations -* etc... - -In order for uEs to receive notifications, the uE calls the uDiscovery API `RegisterForNotifications()` passing `NotificationsRequest` message that includes the list of URIs that it would like to be notified of changes, and a value of how deep in the tree should the change notification be sent. When the depth field is set to -1 or not present, the notifications shall be sent for changes to all children nodes. Below are a few high level requirements for uDiscovery notifications: - -* uE *MUST* be permitted to receive the notification (access the node). Permission is granted if the node is public or per [Appendix: Code-Based uE Access Permissions (CAPs)] -* Notifications *MUST* be sent on the topic `/core.udiscovery/3/nodes#Notification` - -* uCDS *MUST* only allow notification registration from uDDS, and uDDS registration from uLDS - -NOTE: uCDS or uDDS MAY allow local notification registration when it is also acting as a uLDS for the local device - -* uLDS *MUST* only accept registration for Node Updates from local uEs or from the CDS and *MUST NOT* accept notification registration from other uDevices uEs - - - -NOTE: Dynamic discovery of the CDS is out of scope at the time of writing of this specification and as such the CDS authority is known to the LDS. The CDS does not need to call `RegisterForNotifications()`, the LDS simply sends the notification event to the CDS. - === Read/Query APIs Query APIs are used to lookup content in the database, either to resolve URIs (to be used by applications) or to fetch content of a database. * Any uE *MAY* call the query APIs defined in the sections below -* *MUST NOT* return Nodes that are flagged as `inactive` -* Remote Nodes that have `expired` *MUST* be refreshed to the CDS +* Remote Nodes that are `expired` *MUST* be refreshed to the CDS * Locally `expired` Nodes *MUST NOT* be returned in a query ==== Find UE diff --git a/up-l3/udiscovery/v3/add_nodes.puml b/up-l3/udiscovery/v3/add_nodes.puml deleted file mode 100644 index 2f6d37e..0000000 --- a/up-l3/udiscovery/v3/add_nodes.puml +++ /dev/null @@ -1,100 +0,0 @@ -@startuml -'https://plantuml.com/sequence-diagram - -' Copyright (c) 2023 General Motors GTO LLC -' -' Licensed to the Apache Software Foundation (ASF) under one -' or more contributor license agreements. See the NOTICE file -' distributed with this work for additional information -' regarding copyright ownership. The ASF licenses this file -' to you under the Apache License, Version 2.0 (the -' "License"); you may not use this file except in compliance -' with the License. You may obtain a copy of the License at -' -' http://www.apache.org/licenses/LICENSE-2.0 -' -' Unless required by applicable law or agreed to in writing, -' software distributed under the License is distributed on an -' "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -' KIND, either express or implied. See the License for the -' specific language governing permissions and limitations -' under the License. -' -' SPDX-FileCopyrightText: 2023 General Motors GTO LLC -' SPDX-FileType: SOURCE -' SPDX-License-Identifier: Apache-2.0 - -autonumber - -box Device2 #white - actor CDS #orange -endbox -box Device1 #white - entity uDiscovery as DS #orange - entity uOTA as US #blue - actor uApp #red -endbox -US -> US: Installation of uService -US -> DS: AddNode(\nAddNodesRequest) -note right - **AddNodesRequest:** - ""parent_uri"" : "up://Device1" - ""nodes"" [ - \t{ - \t\t""uri"": "up://Device1/uService" - \t\t// Additional uService Node info here// - \t\t""properties"": //uService Properties// - \t\t""type"": ""ENTITY"" - \t} - ] - ""ttl"": -1 -end note -DS -> DS: Save Node -note right - **Node Metadata:** - save //""ttl""// - //""last_updated""//=//current time// - //""inactive""//=""false"" -end note -DS --> US: Status -note right - **Status:** - ""code"": ""OK"" -end note -||| -loop Observers - DS -[#0000FF]-\ uApp: Notification - note right - **Notification:** - ""uri"" "up:/uService" - ""parent_uri"": "up://Device1" - ""operation"": ""ADD"" - ""ttl"": -1 - end note - DS -[#0000FF]-\ CDS: Notification - - opt Fetch Newly Added Node - CDS -> DS: FindNodes(FindNodesRequest) - note right - **FindNodesRequest:** - ""uri"": "up://Device1/uService" - ""depth"": -1 - end note - DS --> CDS: FindNodesResponse - note right - **FindNodesResponse:** - ""nodes"": { //added node for uService// } - ""status"": {""code"": ""OK""} - end note - - CDS -> CDS: Save Node - note right - **Node Metadata:** - save //""ttl""// - //""last_updated""//=//current time// - //""inactive""//=""false"" - end note - end opt -end loop - -@enduml \ No newline at end of file diff --git a/up-l3/udiscovery/v3/add_nodes.svg b/up-l3/udiscovery/v3/add_nodes.svg deleted file mode 100644 index b2d46b3..0000000 --- a/up-l3/udiscovery/v3/add_nodes.svg +++ /dev/null @@ -1 +0,0 @@ -Device2Device1CDSCDSuDiscoveryuDiscoveryuOTAuOTAuAppuApp1Installation of uService2AddNode(AddNodesRequest)AddNodesRequest:parent_uri: "up://Device1"nodes[{uri: "up://Device1/uService"Additional uService Node info hereproperties:uService Propertiestype:ENTITY}]ttl: -13Save NodeNode Metadata:savettllast_updated=current timeinactive=false4StatusStatus:code:OKloop[Observers]5NotificationNotification: uri"up:/uService"parent_uri: "up://Device1"operation:ADDttl: -16Notificationopt[Fetch Newly Added Node]7FindNodes(FindNodesRequest)FindNodesRequest:uri: "up://Device1/uService"depth: -18FindNodesResponseFindNodesResponse:nodes: {added node for uService}status: {code:OK}9Save NodeNode Metadata:savettllast_updated=current timeinactive=false \ No newline at end of file diff --git a/up-l3/udiscovery/v3/delete_node.puml b/up-l3/udiscovery/v3/delete_node.puml deleted file mode 100644 index d94645e..0000000 --- a/up-l3/udiscovery/v3/delete_node.puml +++ /dev/null @@ -1,71 +0,0 @@ -@startuml -'https://plantuml.com/sequence-diagram - -' Copyright (c) 2023 General Motors GTO LLC -' -' Licensed to the Apache Software Foundation (ASF) under one -' or more contributor license agreements. See the NOTICE file -' distributed with this work for additional information -' regarding copyright ownership. The ASF licenses this file -' to you under the Apache License, Version 2.0 (the -' "License"); you may not use this file except in compliance -' with the License. You may obtain a copy of the License at -' -' http://www.apache.org/licenses/LICENSE-2.0 -' -' Unless required by applicable law or agreed to in writing, -' software distributed under the License is distributed on an -' "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -' KIND, either express or implied. See the License for the -' specific language governing permissions and limitations -' under the License. -' -' SPDX-FileCopyrightText: 2023 General Motors GTO LLC -' SPDX-FileType: SOURCE -' SPDX-License-Identifier: Apache-2.0 - -autonumber - -box Device2 #white - actor CDS #orange -endbox -box Device1 #white - entity uDiscovery as DS #orange - entity uOTA as US #blue - actor uApp #red -endbox -US -> US: Uninstall of uService -US -> DS: DeleteNodes(\nDeleteNodesRequest) -note right - **DeleteNodesRequest:** - ""uris"": ["up://Device1/uService"] -end note -DS -> DS: Delete Node -note right - **Node Metadata:** - //""last_updated""//=//current time// - //""inactive""//=""true"" -end note -DS --> US: Status -note right - **Status:** - ""code"": ""OK"" -end note -||| -loop Observers - DS -[#0000FF]-\ uApp: Notification - note right - **Notification:** - ""uri"": "up://Device1/uService" - ""operation"": ""DELETE"" - end note - DS -[#0000FF]-\ CDS: Notification - CDS -> CDS: Delete Node - note right - **Node Metadata:** - //""last_updated""//=//current time// - //""inactive""//=""true"" - end note -end loop - -@enduml \ No newline at end of file diff --git a/up-l3/udiscovery/v3/delete_node.svg b/up-l3/udiscovery/v3/delete_node.svg deleted file mode 100644 index 37f3b2f..0000000 --- a/up-l3/udiscovery/v3/delete_node.svg +++ /dev/null @@ -1 +0,0 @@ -Device2Device1CDSCDSuDiscoveryuDiscoveryuOTAuOTAuAppuApp1Uninstall of uService2DeleteNodes(DeleteNodesRequest)DeleteNodesRequest:uris: ["up://Device1/uService"]3Delete NodeNode Metadata:last_updated=current timeinactive=true4StatusStatus:code:OKloop[Observers]5NotificationNotification: uri: "up://Device1/uService"operation:DELETE6Notification7Delete NodeNode Metadata:last_updated=current timeinactive=true \ No newline at end of file diff --git a/up-l3/udiscovery/v3/find_node.puml b/up-l3/udiscovery/v3/find_node.puml deleted file mode 100644 index 434c2ac..0000000 --- a/up-l3/udiscovery/v3/find_node.puml +++ /dev/null @@ -1,101 +0,0 @@ -@startuml -'https://plantuml.com/sequence-diagram - -' Copyright (c) 2023 General Motors GTO LLC -' -' Licensed to the Apache Software Foundation (ASF) under one -' or more contributor license agreements. See the NOTICE file -' distributed with this work for additional information -' regarding copyright ownership. The ASF licenses this file -' to you under the Apache License, Version 2.0 (the -' "License"); you may not use this file except in compliance -' with the License. You may obtain a copy of the License at -' -' http://www.apache.org/licenses/LICENSE-2.0 -' -' Unless required by applicable law or agreed to in writing, -' software distributed under the License is distributed on an -' "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -' KIND, either express or implied. See the License for the -' specific language governing permissions and limitations -' under the License. -' -' SPDX-FileCopyrightText: 2023 General Motors GTO LLC -' SPDX-FileType: SOURCE -' SPDX-License-Identifier: Apache-2.0 - - -autonumber - -box uDevice1 #white - Collections uEs #red - entity LDS #orange -end box -entity CDS #orange - -group Local uDevice Query - uEs -> LDS: FinduE(FinduERequest) - note right - **UriRequest:** - ""uri"": ""//topic//"" - end note - - alt Found - LDS --> uEs: FindNodesResponse - note right - **FindNodesResponse:** - ""nodes"": { //One or more nodes// } - ""status"": {""code"": ""OK""} - end note - else Error - LDS --> uEs: FindNodesResponse - note right - **FindNodesResponse:** - ""nodes"": { //Empty Node// } - ""status"": {""code"": ""INVALID_ARGUMENT | NOT_FOUND | PERMISSION_DENIED""} - end note - end alt -end -||| -group Remote uDevice Query - uEs -> LDS: FindNodes(FindNodesRequest) - note right - **FindNodesRequest:** - ""uri"": "up://Device2/uService" - ""depth"": -1 - end note - LDS -> CDS: FindNodes(FindNodesRequest) - alt Found - CDS --> LDS: FindNodesResponse - note right - **FindNodesResponse:** - ""nodes"": { //One or more nodes// } - ""status"": {""code"": ""OK""} - end note - LDS -> LDS: Cache Node Info (per ttl) - else NOT FOUND - CDS --> LDS: FindNodesResponse - note right - **FindNodesResponse:** - ""nodes"": { //Empty Node// } - ""status"": {""code"": ""NOT_FOUND""} - ""ttl"": 432000000 ///* 5 days */// - end note - LDS -> LDS: Cache Node Info (per ttl) - else TIMEOUT - note right - **FindNodesResponse:** - ""nodes"": { //Empty Node// } - ""status"": {""code"": ""DEADLINE_EXCEEDED""} - end note - else ERROR - CDS --> LDS: FindNodesResponse - note right - **FindNodesResponse:** - ""nodes"": { //One or more nodes// } - ""status"": {""code"": ""INVALID_ARGUMENT | PERMISSION_DENIED""} - end note - end alt - LDS --> uEs: FindNodesResponse -end -@enduml \ No newline at end of file diff --git a/up-l3/udiscovery/v3/find_node.svg b/up-l3/udiscovery/v3/find_node.svg deleted file mode 100644 index 38bd5cc..0000000 --- a/up-l3/udiscovery/v3/find_node.svg +++ /dev/null @@ -1 +0,0 @@ -uDevice1uEsuEsLDSLDSCDSCDSLocal uDevice Query1FindNodes(FindNodesRequest)FindNodesRequest:uri: "up://Device1/uService"depth: -1alt[Found]2FindNodesResponseFindNodesResponse:nodes: {One or more nodes}status: {code:OK}[Error]3FindNodesResponseFindNodesResponse:nodes: {Empty Node}status: {code:INVALID_ARGUMENT | NOT_FOUND | PERMISSION_DENIED}Remote uDevice Query4FindNodes(FindNodesRequest)FindNodesRequest:uri: "up://Device2/uService"depth: -15FindNodes(FindNodesRequest)alt[Found]6FindNodesResponseFindNodesResponse:nodes: {One or more nodes}status: {code:OK}7Cache Node Info (per ttl)[NOT FOUND]8FindNodesResponseFindNodesResponse:nodes: {Empty Node}status: {code:NOT_FOUND}ttl: 432000000/* 5 days */9Cache Node Info (per ttl)FindNodesResponse:nodes: {Empty Node}status: {code:DEADLINE_EXCEEDED}[TIMEOUT][ERROR]10FindNodesResponseFindNodesResponse:nodes: {One or more nodes}status: {code:INVALID_ARGUMENT | PERMISSION_DENIED}11FindNodesResponse \ No newline at end of file diff --git a/up-l3/udiscovery/v3/lookup_uri.svg b/up-l3/udiscovery/v3/lookup_uri.svg deleted file mode 100644 index d4d3887..0000000 --- a/up-l3/udiscovery/v3/lookup_uri.svg +++ /dev/null @@ -1 +0,0 @@ -uDeviceuEsuEsLDSLDSCDSCDS1LookupUri(UriRequest)UriRequest:uri:topicalt[Found Locally]2UriResponseUriRequest:uris: {topic,topic}result: {code:OK}[Invalid Argument or Permission Denied]3UriResponseUriResponse:result: {code:INVALID_ARGUMENT | PERMISSION_DENIED}[Remote Lookup Required]4LookupUri(UriRequest)alt[Success]5UriResponseUriResponse:uris: {topic,topic}result: {code:OK}6Cache (per ttl)7UriResponseUriResponse:uris: {topic,topic}result: {code:OK}[Failure]8UriResponseUriResponse:result: {code:INVALID_ARGUMENT | NOT_FOUND | PERMISSION_DENIED}9UriResponse[Not Found]10UriResponseUriResponse:result: {code:NOT_FOUND}11UriResponse \ No newline at end of file diff --git a/up-l3/udiscovery/v3/notifications.puml b/up-l3/udiscovery/v3/notifications.puml deleted file mode 100644 index 6549259..0000000 --- a/up-l3/udiscovery/v3/notifications.puml +++ /dev/null @@ -1,86 +0,0 @@ -@startuml -'https://plantuml.com/sequence-diagram - -' Copyright (c) 2023 General Motors GTO LLC -' -' Licensed to the Apache Software Foundation (ASF) under one -' or more contributor license agreements. See the NOTICE file -' distributed with this work for additional information -' regarding copyright ownership. The ASF licenses this file -' to you under the Apache License, Version 2.0 (the -' "License"); you may not use this file except in compliance -' with the License. You may obtain a copy of the License at -' -' http://www.apache.org/licenses/LICENSE-2.0 -' -' Unless required by applicable law or agreed to in writing, -' software distributed under the License is distributed on an -' "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -' KIND, either express or implied. See the License for the -' specific language governing permissions and limitations -' under the License. -' -' SPDX-FileCopyrightText: 2023 General Motors GTO LLC -' SPDX-FileType: SOURCE -' SPDX-License-Identifier: Apache-2.0 - - -autonumber - -box uDevice2 #white - actor CDS #orange -end box -box uDevice1 #white - entity LDS as DS #orange - actor uApp #red -endbox -group uApp to LDS Registration - uApp ->DS: RegisterForNotifications(\nNotificationsRequest) - note right - **NotificationsRequest:** - ""uris"": [ "up://Device1/uService/1", "up://Device2/uService/1"] - ""observer"": { ""uri": "up://Device1/uApp/1" } - end note - alt Success - DS -> DS: Save NotificationRequest - DS --> uApp: Status - note right - **Status:** - ""code"": ""OK"" - end note - else Error - DS --> uApp: Status - note right - **Status:** - ""code"": ""INVALID_ARGUMENT |"" - ""NOT_FOUND | PERMISSION_DENIED"" - end note - end alt -end -||| -group LDS to CDS Registration -DS -> CDS: RegisterForNotifications(\nNotificationsRequest) -note right - **NotificationsRequest:** - ""uris"": "up://Device2/uSerivce/1" - ""observer"": { ""uri"": "up://Device1/core.udiscovery/2" } - } -end note -alt Success - CDS -> CDS: Save NotificationRequest - CDS --> DS: Status - note right - **Status:** - ""code"": ""OK"" - end note -else Error - CDS --> DS: Status - note right - **Status:** - ""code"": ""INVALID_ARGUMENT |"" - ""NOT_FOUND | PERMISSION_DENIED"" - end note -end alt -end - -@enduml \ No newline at end of file diff --git a/up-l3/udiscovery/v3/update_nodes.puml b/up-l3/udiscovery/v3/update_nodes.puml deleted file mode 100644 index 3df7846..0000000 --- a/up-l3/udiscovery/v3/update_nodes.puml +++ /dev/null @@ -1,82 +0,0 @@ -@startuml -'https://plantuml.com/sequence-diagram - -' Copyright (c) 2023 General Motors GTO LLC -' -' Licensed to the Apache Software Foundation (ASF) under one -' or more contributor license agreements. See the NOTICE file -' distributed with this work for additional information -' regarding copyright ownership. The ASF licenses this file -' to you under the Apache License, Version 2.0 (the -' "License"); you may not use this file except in compliance -' with the License. You may obtain a copy of the License at -' -' http://www.apache.org/licenses/LICENSE-2.0 -' -' Unless required by applicable law or agreed to in writing, -' software distributed under the License is distributed on an -' "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -' KIND, either express or implied. See the License for the -' specific language governing permissions and limitations -' under the License. -' -' SPDX-FileCopyrightText: 2023 General Motors GTO LLC -' SPDX-FileType: SOURCE -' SPDX-License-Identifier: Apache-2.0 - -autonumber - -box Device2 #white - actor CDS #orange -endbox -box Device1 #white - entity LDS as DS #orange - entity uService as US #blue - actor uApp #red -endbox - -US -> DS: UpdateNode(\nUpdateNodeRequest) -note right - **UpdateNodeRequest:** - ""node"" { //Changed Info// } - ""ttl"": -1 -end note -DS -> DS: Update Node -note right - **Node Metadata:** - save //""ttl""// - //""last_updated""//=//current time// - //""inactive""//=""false"" -end note -DS --> US: Status -note right - **Status:** - ""code"": ""OK"" -end note -||| -loop Notify Observers - DS -[#0000FF]-\ uApp: Notification - note right - **Notification:** - ""uri"" : //uri of changed node// - ""operation"": ""UPDATE"" - ""ttl"": -1 - end note - DS -[#0000FF]-\ CDS: Notification - - opt Fetch Updated Node - CDS -> DS: FindNodes(FindNodesRequest) - note right - **FindNodesRequest:** - ""uri"": //uri of the changed node// - ""depth"": -1 - end note - DS --> CDS: FindNodesResponse - note right - **FindNodesResponse:** - ""nodes"": { //updated node// } - ""status"": {""code"": ""OK""} - end note - end opt -end loop -@enduml \ No newline at end of file From 57d8a5a0d9ae4ddd6a89f36bab19b56d85686592 Mon Sep 17 00:00:00 2001 From: mayuresh Date: Thu, 18 Apr 2024 17:17:26 -0400 Subject: [PATCH 04/11] Resolve initial comments --- up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto | 2 +- up-l3/udiscovery/v3/README.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index be230b9..106399b 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -139,7 +139,7 @@ message GetDeviceListRequest{ // 1. code.OK: Query lookup was successful // 2. code.NOT_FOUND: No matching UUris were found // 3. code.INVALID_ARGUMENT: The passed UUri is invalid -message GetuEListResponse { +message GetDeviceListResponse { repeated v1.UUri deviceList = 1; uprotocol.v1.UStatus status = 2; // Return code for the rpc call diff --git a/up-l3/udiscovery/v3/README.adoc b/up-l3/udiscovery/v3/README.adoc index 2e88f29..96a105e 100644 --- a/up-l3/udiscovery/v3/README.adoc +++ b/up-l3/udiscovery/v3/README.adoc @@ -32,7 +32,7 @@ SPDX-License-Identifier: Apache-2.0 uE's (Software Entities) will be deployed dynamically on devices that are scattered throughout the uProtocol network. In order for these uE's to know about what is available on their own device or on other devices, we need the ability to discover uEs, their locations and what they serve (resources, methods, messages, etc...). There are number of Internet protocols such as DNS, Zeroconf, and others, to discover devices and services running on said devices. Intent of uDiscovery is to reuse as much as possible, existing Internet standards for discovering uThings as well. -The purpose of this proposal is to define the discovery architecture so that uEs can dynamically discover uThings (other uEs, uDevices, uDomains, uResources, uMethods, etc...), for example what topics are served(publihed) by a uE in another device. +The purpose of this proposal is to define the discovery architecture so that uEs can dynamically discover uThings (other uEs, uDevices, uDomains, uResources, uMethods, etc...), for example what topics are served(published) by a uE in another device. == Background From 8e4796f8e3868f805d6d105e4eac80508e41a2a8 Mon Sep 17 00:00:00 2001 From: mayuresh Date: Tue, 23 Apr 2024 10:37:41 -0400 Subject: [PATCH 05/11] Added description for all APIs --- .../core/udiscovery/v3/udiscovery.proto | 104 ++++++++++++------ 1 file changed, 72 insertions(+), 32 deletions(-) diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 106399b..9459ffd 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -41,34 +41,79 @@ service uDiscovery { option (version_minor) = 0; option (id) = 1; - // 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 - // 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 + + option (notification_topic) = { + id: 0x8000, + name: "NodeChange", + message: "Notification" + }; + + /* Consumer calls this API to find all instances for a given uE and their locations. + uDiscovery shall return all local(to the device) URIs for this service and also the ones found + in cache of uEs for remote devices. If requested details are not found (either locally or in cache), it shall + attempt to fetch those details from next uDiscovery instance in the chain. (uLDS to uDDS, uDDS to uCDS) */ + + /* Example: + FindUE(“///core.example”) + Response: [“//ultifi.gm.com/core.example/2.0”, “/core.example/1.0”], Status: code.OK + */ + rpc FinduE(FinduERequest) returns (FinduEResponse) { option (method_id) = 1; } - // Retrieve the list of topics for a given uE + + + /* Consumer calls this API to retrieve a list of topics serviced by a given uE. + List of topics shall consist data topics being published and rpc methods services by that uE. + Scope of the data fetch shall be limited to local device, meaning uLDS shall not attempt to + fetch the details remotely if not found locally or in cache.*/ + + + /* Example: + GetUETopics(“up:/core.example/1”) + Response: [“up:/core.example/1/topic1”, “up:/core.example/1/rpc1”], Status: code.OK + */ + rpc GetuETopics(GetuETopicsRequests) returns (GetuETopicsResponse){ option (method_id) = 2; } - // Retrieve the list of uEs under a device. - // Input argument : Valid device URI - // Output : List of all uEs under that device and appropriate status message + + /* Consumers shall call this API to fetch the list of uEs under a given device. + Idea is to provide an API(at each levle in hierarchy) to get a list of local entities. + For example: uDDS might call on uLDS for each device to build up its local tree in case of failures */ + + /* Example: + GetUETopics(“up:/device1”) + Response: [“up:/device1/uE1”, “up:/device1/uE2”], Status: code.OK + + GetUETopics(“up:/device2”) + Response: [], Status: code.INVALID_ARGUMENT (passed device should match local device) + + */ rpc GetuEList(GetuEListRequest) returns (GetuEListResponse){ option (method_id) = 4; } + + /* Consumers shall call this API to fetch the list of uEs under a given domain. + This is an extension of GetUEList at a higher level. + For example: uCDS might call on uDDS to build up its local tree in case of failures */ + + /* Example: + GetDeviceList(“up:/domain”) + Response: [“up:/domain/device1”, “up:/domain/device2”], Status: code.OK + + GetUETopics(“up:/domain2”) + Response: [], Status: code.INVALID_ARGUMENT (invalid domain) + + */ rpc GetDeviceList(GetDeviceListRequest) returns (GetDeviceListResponse){ option (method_id) = 5; } + /* TODO: Need to catch up on URI discussion before updating this*/ // 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 @@ -83,6 +128,16 @@ service uDiscovery { } +/* All response messages shall include uprotocol status field. This shall indicate whether +the request was processed successfully and provide error reason if applicable. Some of the +common error reasons could be: + code.OK: Query lookup was successful + code.NOT_FOUND: No matching UUris were found + code.INVALID_ARGUMENT: The passed UUri is invalid + code.PERMISSION_DENIED: The caller does not have permission to perform the query + */ + + message FinduERequest { string uri = 1; } @@ -95,57 +150,42 @@ message FinduEResponse { } - +// Request message to get list of topics for a UE message GetuETopicsRequest { v1.UUri UE = 1; } // Response data for GetUEtopics. -// Possible return values in status are: -// 1. code.OK: Query lookup was successful -// 2. code.NOT_FOUND: No matching UUris were found -// 3. code.INVALID_ARGUMENT: The passed UUri is invalid message GetuETopicsResponse { - repeated v1.UUri topicList = 1; uprotocol.v1.UStatus status = 2; // Return code for the rpc call } +// Request message to get list of UEs for a device message GetUEListRequest{ - v1.UUri UDevice = 1; } // Response data for GetUEtopics. -// Possible return values in status are: -// 1. code.OK: Query lookup was successful -// 2. code.NOT_FOUND: No matching UUris were found -// 3. code.INVALID_ARGUMENT: The passed UUri is invalid message GetuEListResponse { - repeated v1.UUri UEList = 1; uprotocol.v1.UStatus status = 2; // Return code for the rpc call } - +// Request message to get list of UEs for a device message GetDeviceListRequest{ - v1.UUri UDomain = 1; } -// Response data for GetUEtopics. -// Possible return values in status are: -// 1. code.OK: Query lookup was successful -// 2. code.NOT_FOUND: No matching UUris were found -// 3. code.INVALID_ARGUMENT: The passed UUri is invalid +// Request message to get list of devices for a domain message GetDeviceListResponse { - repeated v1.UUri deviceList = 1; uprotocol.v1.UStatus status = 2; // Return code for the rpc call } +/* TODO: Update after catching up on URI specs */ // Request message passed to ResolveUri() API to resolve the missing names or numbers. message ResolveUriRequest { // The URI to resolve containing only names or numbers From 8fce52a804c0f583b569e3eec78d59bd19d868c8 Mon Sep 17 00:00:00 2001 From: Mayuresh Date: Tue, 23 Apr 2024 10:50:24 -0400 Subject: [PATCH 06/11] Update up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto Co-authored-by: Steven Hartley --- up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 106399b..de3a3a3 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -106,7 +106,7 @@ message GetuETopicsRequest { // 1. code.OK: Query lookup was successful // 2. code.NOT_FOUND: No matching UUris were found // 3. code.INVALID_ARGUMENT: The passed UUri is invalid -message GetuETopicsResponse { +message GetUETopicsResponse { repeated v1.UUri topicList = 1; uprotocol.v1.UStatus status = 2; // Return code for the rpc call From d44cef8bb03d84eb410990767e50e99a270cb976 Mon Sep 17 00:00:00 2001 From: mayuresh Date: Tue, 23 Apr 2024 11:50:17 -0400 Subject: [PATCH 07/11] Addressed review comments --- .../core/udiscovery/v3/udiscovery.proto | 2 +- up-l3/udiscovery/v3/README.adoc | 85 +++---------------- 2 files changed, 11 insertions(+), 76 deletions(-) diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 9459ffd..ae7bc10 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -175,7 +175,7 @@ message GetuEListResponse { // Request message to get list of UEs for a device message GetDeviceListRequest{ - v1.UUri UDomain = 1; + v1.UAuthority UDomain = 1; } // Request message to get list of devices for a domain diff --git a/up-l3/udiscovery/v3/README.adoc b/up-l3/udiscovery/v3/README.adoc index 96a105e..1a1d849 100644 --- a/up-l3/udiscovery/v3/README.adoc +++ b/up-l3/udiscovery/v3/README.adoc @@ -32,8 +32,6 @@ SPDX-License-Identifier: Apache-2.0 uE's (Software Entities) will be deployed dynamically on devices that are scattered throughout the uProtocol network. In order for these uE's to know about what is available on their own device or on other devices, we need the ability to discover uEs, their locations and what they serve (resources, methods, messages, etc...). There are number of Internet protocols such as DNS, Zeroconf, and others, to discover devices and services running on said devices. Intent of uDiscovery is to reuse as much as possible, existing Internet standards for discovering uThings as well. -The purpose of this proposal is to define the discovery architecture so that uEs can dynamically discover uThings (other uEs, uDevices, uDomains, uResources, uMethods, etc...), for example what topics are served(published) by a uE in another device. - == Background === Definitions of Terms @@ -43,52 +41,12 @@ The purpose of this proposal is to define the discovery architecture so that uEs |=== |Term |Definition |DNS |Domain Name System covered in various IETF RFCs -|CDS |Central Discovery Service implementation of uDiscovery -|DDS | Domain Discovery Service(local to a domain) implemenation of uDiscovery -|LDS |Local (to a device) implementation of uDiscovery -|Local Entity |Entity who is local to the device (local information) -|Remote Entity |Entity which is hosted on a different device. This is fetched from CDS and cached in the LDS +|uCDS |Central Discovery Service implementation of uDiscovery +|uDDS | Domain Discovery Service(local to a domain) implementation of uDiscovery +|uLDS |Local (to a device) implementation of uDiscovery |=== -== Overview - -uDiscovery provides the ability to discover things which are addressable using UUri notation (devices, services, topics/methods). - -NOTE: Data model and interface is described in link:../../../up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto[udiscovery.proto] - -.uProtocol Discovery Architecture -image::overview.drawio.svg[Overview] - -NOTE: Components described in <> below all implement link:../../../up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto[udiscovery.proto] - - -.uDiscovery Software Entities -[#udiscovery-ues] -[width="100%",cols="15%,35%,50%",options="header"]] -|=== -|Component |Description |Requirements - -|*Local uDiscovery Service (LDS)* -|Service to provide discovery of uThings per device. Every LDS stores information of all local entities. In addition, it caches information for uEs on other devices. -a|* Every uDevice *MUST* have LDS - -| *Domain uDiscovery Service (uDDS)* -| Service to provide discovery of all uThings per domain. -a| -* uDDS *MUST* store `uEs` for all the devices under a given domain hierarchy -* *MUST* be only one uDDS within a domain -* A uLDS *MAY* also function as uDDS and/or a uCDS for a uDomain or network -* uDDS *MUST* support queries from uLDSs that are within its domain -* uDDS *MUST* relay queries from uLDS to the uCDS and then cache the results per the TTL requirements from query API response -* uDDS *SHOULD* be located in the always-on uDevices - -|*Central uDiscovery Service (uCDS)* -|Central repository storing all deployed uDevice information in the network of connected devices residing in the Cloud. It is a superset of the local uDiscovery database content -a| -* *MUST* have one CDS that is globally addressable by the various domain/device LDS -|=== - === Hierarchical Specifications The following section will elaborate on the uProtocol hierarchy elaborating how information is organized, referenced, and structured. This is the system classification specification used to identify and define "things" . @@ -202,35 +160,8 @@ Services can declare any non-reserved identifier in their own proto files. NOTE: It is *STRONGLY RECOMMENDED* to scope your property names to avoid namespace collision -=== Database Access - -The uDiscovery service, through the query APIs, allows any uE to discover the contents from local and central databases. These APIs shall implement appropriate permission model to prevent unauthorized access. -==== Policy - -Table below outlines the database access policies written like network firewall rules (top to bottom). The rules will be broken down for specific rules for the LDS vs CDS. - -===== All Components -* *MUST* block access by default - -===== uLDS - -* *MUST* allow local uE to read or write its own Node as well as its children Nodes -* *MUST* allow local uE to read Nodes that it has associated link:../../../up-l2/permissions.adoc[permissions] to do so -* Fetched Nodes *MUST* be cached per ttl requirements - -===== uDDS -* *MUST* allow uLDS to read or write its own Node or its children Nodes -* Fetched Nodes *MUST* be cached per ttl requirements - -===== uCDS -* *MUST* allow uDDS to read or write its own Node or its children Nodes - -|3 | | -|4 | |*MUST* allow LDS to read additional uDevice Nodes that are within its scope Scoping (or grouping) of devices shall be defined in a later version of this specification - - -=== Node Metadata +==== Node Metadata Node metadata are stored outside the Node structure and describe the Node itself (freshness, etc...). @@ -267,10 +198,14 @@ Figure below illustrates the flows for performing a query to the LDS. Uri detail image:FindUE.svg[FinduE] ==== Get UE Topics +Get uE Topics is used to fetch the list of topics published by a uE. Data available locally and in cache for remote uEs shall be returned in response of this API. -Get uE Topics is used to fetch the list of topics published by a uE. -* *MUST* update `last_accessed` Node attribute when API is called +==== Get UE List +Get UE list is used retrieve the list of UEs for a given device. + +==== Get Device List +Get device list is similar to Get UE list, but at a domain level. Consumers would use this API to retrieve all devices under a given domain. From cfe50edd72ac633f70f74f053f454ae2e575d3eb Mon Sep 17 00:00:00 2001 From: mayuresh Date: Wed, 24 Apr 2024 15:19:43 -0400 Subject: [PATCH 08/11] Updated proto and readme files --- .../core/udiscovery/v3/udiscovery.proto | 166 ++++++++++++++---- up-l3/udiscovery/v3/README.adoc | 83 +++++---- 2 files changed, 172 insertions(+), 77 deletions(-) diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index af06ac8..919d2ae 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -48,12 +48,43 @@ service uDiscovery { message: "Notification" }; - /* Consumer calls this API to find all instances for a given uE and their locations. + + + + /******************************* Data population *************************/ + + /* + UEs shall call SetUETopics API to update discovery with the list of topics they service. + This will be used in two scenarios: + 1. when a UE is added on a device + 2. when UE wants to udpate the topic list + uDiscovery shall implement requisite permission model while processing this. + */ + + /* Example: + SetUETopics(parentUE:“///device/UE/1”, TopicList:["UE/1/topic1", "UE/1/topic2", "UE/1/rpc1"]) + Response: Status: code.OK + + SetUETopics(parentUE:“///device/UE2/1”, TopicList:["UE/1/topic1", "UE/1/topic2", "UE/1/rpc1"]) + Response: Status: code.PERMISSION_DENIED (cant change other UEs) + + */ + + rpc SetUETopics(SetUETopicsRequest) returns ( uprotocol.v1.UStatus){ + option (method_id) = 1; + } + + /******************************* Data consumption ************************/ + + /* + Consumer shall call FindUE API to find all instances for a given uE and their locations. uDiscovery shall return all local(to the device) URIs for this service and also the ones found in cache of uEs for remote devices. If requested details are not found (either locally or in cache), it shall - attempt to fetch those details from next uDiscovery instance in the chain. (uLDS to uDDS, uDDS to uCDS) */ + attempt to fetch those details from next uDiscovery instance in the chain. (uLDS to uDDS, uDDS to uCDS) + */ - /* Example: + /* + Example: FindUE(“///core.example”) Response: [“//ultifi.gm.com/core.example/2.0”, “/core.example/1.0”], Status: code.OK */ @@ -62,15 +93,15 @@ service uDiscovery { option (method_id) = 1; } - - - /* Consumer calls this API to retrieve a list of topics serviced by a given uE. + /* + Consumers shall call GetUETopics API to retrieve a list of topics serviced by a given uE. List of topics shall consist data topics being published and rpc methods services by that uE. Scope of the data fetch shall be limited to local device, meaning uLDS shall not attempt to - fetch the details remotely if not found locally or in cache.*/ - - - /* Example: + fetch the details remotely if not found locally or in cache. + */ + + /* + Example: GetUETopics(“up:/core.example/1”) Response: [“up:/core.example/1/topic1”, “up:/core.example/1/rpc1”], Status: code.OK */ @@ -79,27 +110,31 @@ service uDiscovery { option (method_id) = 2; } - - /* Consumers shall call this API to fetch the list of uEs under a given device. + /* + Consumers shall call GetUEList API to fetch the list of uEs under a given device. Idea is to provide an API(at each levle in hierarchy) to get a list of local entities. - For example: uDDS might call on uLDS for each device to build up its local tree in case of failures */ + For example: uDDS might call on uLDS for each device to build up its local tree in case of failures. + */ - /* Example: + /* + Example: GetUETopics(“up:/device1”) Response: [“up:/device1/uE1”, “up:/device1/uE2”], Status: code.OK GetUETopics(“up:/device2”) Response: [], Status: code.INVALID_ARGUMENT (passed device should match local device) - */ + rpc GetuEList(GetuEListRequest) returns (GetuEListResponse){ option (method_id) = 4; } - /* Consumers shall call this API to fetch the list of uEs under a given domain. + /* + Consumers shall call GetDeviceList API to fetch the list of uEs under a given domain. This is an extension of GetUEList at a higher level. - For example: uCDS might call on uDDS to build up its local tree in case of failures */ + For example: uCDS might call on uDDS to build up its local tree in case of failures + */ /* Example: GetDeviceList(“up:/domain”) @@ -113,18 +148,23 @@ service uDiscovery { option (method_id) = 5; } - /* TODO: Need to catch up on URI discussion before updating this*/ - - // 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 - // - 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 - rpc ResolveUri(ResolveUriRequest) returns (ResolveUriResponse) { - option (method_id) = 10; + /******************************* Data replication / synchronization ******/ + + /* + UpdateData is NOT a customer facing API. This shall be used discovery + instances to push an update between to core components (streamer)/ other discovery instances. + */ + + /* + Example: + UpdateData(“up:/domain/device/UE”) + Status: code.OK + */ + + rpc SyncData(UpdateDataRequest) returns (status){ + option (method_id) = 6; } + } @@ -137,7 +177,7 @@ common error reasons could be: code.PERMISSION_DENIED: The caller does not have permission to perform the query */ - +// request message to Find UE message FinduERequest { string uri = 1; } @@ -157,16 +197,7 @@ message GetuETopicsRequest { // Response data for GetUEtopics. -<<<<<<< HEAD -message GetuETopicsResponse { -======= -// Possible return values in status are: -// 1. code.OK: Query lookup was successful -// 2. code.NOT_FOUND: No matching UUris were found -// 3. code.INVALID_ARGUMENT: The passed UUri is invalid message GetUETopicsResponse { - ->>>>>>> 8fce52a804c0f583b569e3eec78d59bd19d868c8 repeated v1.UUri topicList = 1; uprotocol.v1.UStatus status = 2; // Return code for the rpc call } @@ -209,3 +240,62 @@ message ResolveUriResponse { uprotocol.v1.UStatus status = 2; // Return code for the rpc call } +// Request message to set UE topics +message SetUETopicsRequest{ + v1.UUri parentUE = 1; + repeated UServiceTopic UETopicsList = 2; + +} + +/* +Typedef for a node properties. A node property can be any one of the ultifi ("u_") types +defined below +*/ +message PropertyValue { + oneof attr { + bool u_boolean = 1; // Boolean + int32 u_integer = 2; // Integer + string u_string = 3; // String + bytes u_bytes = 4; // Raw Bytes + string u_uri = 5; // A URI + google.protobuf.Timestamp u_timestamp = 6; // Timestamp + double u_double = 7; // Double + int64 u_integer_64 = 8; // 64 bit Integer + } +} + + +/* +uProtocol definition of a Node in the hierarchy per SDV-202. +Node can be domain, device, service, resource, method, etc... +*/ +message Node { + // Ultifi URI pointing to this node + v1.UUri uri = 1; + + // List of child nodes under this node + repeated Node nodes = 2; + + // List of node properties + map properties = 3; + + // The node type + Type type = 4; + + + // What is the uThing (stored in Node) type. This is used to more easily + // identify the Node rather than parsing from uri and inferring the type + enum Type { + UNSPECIFIED = 0; // Unspecified node type + DOMAIN = 1; // uDomain + DEVICE = 2; // uDevice + ENTITY = 3; // uEntity (uE) + VERSION = 9; // uEntity version + TOPIC = 4; // uE Topic + METHOD = 5; // uE Method + MESSAGE = 6; // uE Message + RESOURCE = 7; // uE Resource + USER = 8; // User Information + } +} + diff --git a/up-l3/udiscovery/v3/README.adoc b/up-l3/udiscovery/v3/README.adoc index 1a1d849..c571f18 100644 --- a/up-l3/udiscovery/v3/README.adoc +++ b/up-l3/udiscovery/v3/README.adoc @@ -30,8 +30,9 @@ SPDX-License-Identifier: Apache-2.0 == Purpose -uE's (Software Entities) will be deployed dynamically on devices that are scattered throughout the uProtocol network. In order for these uE's to know about what is available on their own device or on other devices, we need the ability to discover uEs, their locations and what they serve (resources, methods, messages, etc...). There are number of Internet protocols such as DNS, Zeroconf, and others, to discover devices and services running on said devices. Intent of uDiscovery is to reuse as much as possible, existing Internet standards for discovering uThings as well. +Purpose of uDiscovery is to provide a functionality similar to DNS lookup. +uE's (Software Entities) will be deployed dynamically on devices that are scattered throughout the uProtocol network. uDiscovery service provides functionality to discover uEs, their locations and what they serve (resources, methods, messages, etc...). == Background === Definitions of Terms @@ -46,12 +47,11 @@ uE's (Software Entities) will be deployed dynamically on devices that are scatte |uLDS |Local (to a device) implementation of uDiscovery |=== - === Hierarchical Specifications The following section will elaborate on the uProtocol hierarchy elaborating how information is organized, referenced, and structured. This is the system classification specification used to identify and define "things" . -<> below introduces node and properties that we will define in this section. The diagram illustrates the hierarchy (taxonomy) for things in the network. +<> below introduces uEs and properties that we will define in this section. The diagram illustrates the hierarchy (taxonomy) for things in the network. .Hierarchical Classification @@ -61,14 +61,19 @@ image::hierarchical.drawio.svg[Classification] ==== Node -Nodes are addressable uThings like device, service, topics, etc.... Each node has-a list of properties as well as 0-n child nodes. The declarations of nodes and properties can be found in the link:../../../up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto[udiscovery.proto], the snippet is below: +Every ultifi entity that is addressable using URI is represented by a node message defined in link:../../../up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto[udiscovery.proto]. Each node has-a list of properties as well as 0-n child nodes. + +Snippet of the node proto definition is below: .Node & Property Definitions [source] ---- -// Typedef for a node properties. A node property can be any one of the types -// defined below + +/* +Typedef for a node properties. A node property can be any one of the ultifi ("u_") types +defined below +*/ message PropertyValue { oneof attr { bool u_boolean = 1; // Boolean @@ -77,13 +82,19 @@ message PropertyValue { bytes u_bytes = 4; // Raw Bytes string u_uri = 5; // A URI google.protobuf.Timestamp u_timestamp = 6; // Timestamp + double u_double = 7; // Double + int64 u_integer_64 = 8; // 64 bit Integer } } -// Node can be domain, device, service, resource, method, etc... + +/* +uProtocol definition of a Node in the hierarchy per SDV-202. +Node can be domain, device, service, resource, method, etc... +*/ message Node { - // URI pointing to this node - string uri = 1; + // Ultifi URI pointing to this node + v1.UUri uri = 1; // List of child nodes under this node repeated Node nodes = 2; @@ -98,18 +109,19 @@ message Node { // What is the uThing (stored in Node) type. This is used to more easily // identify the Node rather than parsing from uri and inferring the type enum Type { - INVALID = 0; // Invalid node type - DOMAIN = 1; // uDomain - DEVICE = 2; // uDevice - ENTITY = 3; // uEntity (uE) - VERSION = 9; // uE Version - TOPIC = 4; // uE Topic - METHOD = 5; // uE Method - MESSAGE = 6; // uE Message - RESOURCE = 7; // uE Resource - USER = 8; // User Information + UNSPECIFIED = 0; // Unspecified node type + DOMAIN = 1; // uDomain + DEVICE = 2; // uDevice + ENTITY = 3; // uEntity (uE) + VERSION = 9; // uEntity version + TOPIC = 4; // uE Topic + METHOD = 5; // uE Method + MESSAGE = 6; // uE Message + RESOURCE = 7; // uE Resource + USER = 8; // User Information } } + ---- @@ -161,27 +173,16 @@ NOTE: It is *STRONGLY RECOMMENDED* to scope your property names to avoid namespa -==== Node Metadata - -Node metadata are stored outside the Node structure and describe the Node itself (freshness, etc...). - - -.Node Metadata Definition -|=== -|Attribute |Type |RFC2119 |Description - -|ttl |int32 |*REQUIRED* |Time-to-Live. How long (in milliseconds) the Node is valid for before it is outdated and needs to be refreshed. When the value is -1 the Node is considered to be valid forever. A Node is expired when the following is true: \begin\{array}\{l}\displaystyle expired = t_\{current} > t_\{last_updated} + ttl\end\{array} -|last_updated |Timestamp |*REQUIRED* |Last time the content of the Node has changed (been written) -|last_accessed |Timestamp |*OPTIONAL* |The last time the Node was read (accessed) from a FindNodes() API call -|=== - -API requirements related to Node metadata shall be covered in the subsequent section. - - == uDiscovery Interface In the following section we will explain the various APIs and interfaces that are defined in uDiscovery and their requirements. Interface definitions (input and output parameters, etc...) are covered in the link:../../../up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto[udiscovery.proto]. +=== Write APIs +Write APIs are used to populate/ update data in 'local' discovery instance. + +==== Set UE Topics +This API shall be used by ultifi entities to update discovery with the list of topics they serve. This includes the topics they publish on and also the rpcs they serve. + === Read/Query APIs Query APIs are used to lookup content in the database, either to resolve URIs (to be used by applications) or to fetch content of a database. @@ -192,10 +193,9 @@ Query APIs are used to lookup content in the database, either to resolve URIs (t ==== Find UE -Figure below illustrates the flows for performing a query to the LDS. Uri details for requested uE are returned if found in uLDS first, else the query is sent to uDDS and in turn to uCDS if required. -* *MUST* update `last_accessed` Node attribute when API is called +Find UE is used by conusmers to find service instances. uDiscovery shall lookup UE details locally first and try to get it from remote instances if not found locally. -image:FindUE.svg[FinduE] +Figure below illustrates the flows for performing a query to the LDS. Uri details for requested uE are returned if found in uLDS first, else the query is sent to uDDS and in turn to uCDS if required. ==== Get UE Topics Get uE Topics is used to fetch the list of topics published by a uE. Data available locally and in cache for remote uEs shall be returned in response of this API. @@ -207,6 +207,11 @@ Get UE list is used retrieve the list of UEs for a given device. ==== Get Device List Get device list is similar to Get UE list, but at a domain level. Consumers would use this API to retrieve all devices under a given domain. +=== Replication/ Synchronization APIs + +==== Sync Data + +This is used by local discovery instances to push local updates to domain and from domain to central. == Failure Recovery From bc314d9977b906822b49a41c2f18ce73fad1ff3c Mon Sep 17 00:00:00 2001 From: mayuresh Date: Wed, 24 Apr 2024 20:57:45 -0400 Subject: [PATCH 09/11] Added set ue properties API --- .../core/udiscovery/v3/udiscovery.proto | 55 +++++++------- up-l3/udiscovery/v3/README.adoc | 76 +------------------ 2 files changed, 31 insertions(+), 100 deletions(-) diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 919d2ae..2b8de99 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -48,10 +48,7 @@ service uDiscovery { message: "Notification" }; - - - - /******************************* Data population *************************/ + /************************** Write APIs ************************************/ /* UEs shall call SetUETopics API to update discovery with the list of topics they service. @@ -74,7 +71,22 @@ service uDiscovery { option (method_id) = 1; } - /******************************* Data consumption ************************/ + + /* + UEs shall call SetUEProperties API to update discovery with updated property values. + For example, this could be used to update an UE's version. + */ + + /* Example: + SetUEProperties(parentUE:“///device/UE/1”, PropertyValuesList:["version_major" : "1", "version_minor" : "2"]) + Response: Status: code.OK + */ + + rpc SetUEProperties(SetUEPropertiesRequest) returns (uprotocol.v1.UStatus){ + option (method_id) = 1; + } + + /******************************* Read APIs ************************/ /* Consumer shall call FindUE API to find all instances for a given uE and their locations. @@ -182,8 +194,10 @@ message FinduERequest { string uri = 1; } -// Return value from FinduE() API that contains the batch of Uris for the -// lookup and status from the API call +/* +Return value from FinduE() API that contains the batch of Uris for the +lookup and status from the API call */ + message FinduEResponse { v1.UUriBatch uris = 1; // Batch of Uris uprotocol.v1.UStatus status = 2; // Return code for the rpc call @@ -224,29 +238,14 @@ message GetDeviceListResponse { uprotocol.v1.UStatus status = 2; // Return code for the rpc call } - -/* TODO: Update after catching up on URI specs */ -// 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; -} - - -// Response returned from ResolveUri() API containing a UUri and the -// status of the resolution. -message ResolveUriResponse { - v1.UUri uri = 1; // Resolved UUri - uprotocol.v1.UStatus status = 2; // Return code for the rpc call -} - // Request message to set UE topics -message SetUETopicsRequest{ +message SetUEPropertiesRequest{ v1.UUri parentUE = 1; - repeated UServiceTopic UETopicsList = 2; + map propertiesList = 2; } + /* Typedef for a node properties. A node property can be any one of the ultifi ("u_") types defined below @@ -283,8 +282,10 @@ message Node { Type type = 4; - // What is the uThing (stored in Node) type. This is used to more easily - // identify the Node rather than parsing from uri and inferring the type + /* + What is the uThing (stored in Node) type. This is used to more easily + identify the Node rather than parsing from uri and inferring the type + */ enum Type { UNSPECIFIED = 0; // Unspecified node type DOMAIN = 1; // uDomain diff --git a/up-l3/udiscovery/v3/README.adoc b/up-l3/udiscovery/v3/README.adoc index c571f18..cbcc3eb 100644 --- a/up-l3/udiscovery/v3/README.adoc +++ b/up-l3/udiscovery/v3/README.adoc @@ -63,72 +63,6 @@ image::hierarchical.drawio.svg[Classification] Every ultifi entity that is addressable using URI is represented by a node message defined in link:../../../up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto[udiscovery.proto]. Each node has-a list of properties as well as 0-n child nodes. -Snippet of the node proto definition is below: - - -.Node & Property Definitions -[source] ----- - -/* -Typedef for a node properties. A node property can be any one of the ultifi ("u_") types -defined below -*/ -message PropertyValue { - oneof attr { - bool u_boolean = 1; // Boolean - int32 u_integer = 2; // Integer - string u_string = 3; // String - bytes u_bytes = 4; // Raw Bytes - string u_uri = 5; // A URI - google.protobuf.Timestamp u_timestamp = 6; // Timestamp - double u_double = 7; // Double - int64 u_integer_64 = 8; // 64 bit Integer - } -} - - -/* -uProtocol definition of a Node in the hierarchy per SDV-202. -Node can be domain, device, service, resource, method, etc... -*/ -message Node { - // Ultifi URI pointing to this node - v1.UUri uri = 1; - - // List of child nodes under this node - repeated Node nodes = 2; - - // List of node properties - map properties = 3; - - // The node type - Type type = 4; - - - // What is the uThing (stored in Node) type. This is used to more easily - // identify the Node rather than parsing from uri and inferring the type - enum Type { - UNSPECIFIED = 0; // Unspecified node type - DOMAIN = 1; // uDomain - DEVICE = 2; // uDevice - ENTITY = 3; // uEntity (uE) - VERSION = 9; // uEntity version - TOPIC = 4; // uE Topic - METHOD = 5; // uE Method - MESSAGE = 6; // uE Message - RESOURCE = 7; // uE Resource - USER = 8; // User Information - } -} - ----- - - -* The Node `uri` field *MUST* follow the URI specifications defined in uProtocol Specifications -** UE_VERSION *MUST* contain MAJOR -** UE_VERSION *MUST NOT* contain MINOR and PATCH - Table below lists example URIs for the various node types in the database hierarchy. .Example URIs @@ -145,11 +79,6 @@ Table below lists example URIs for the various node types in the database hierar |method |up://UDEVICE.UDOMAIN/UE_NAME/UE_VERSION/rpc.METHOD |=== -==== Markup Language - -* YAML *SHALL* be used as the standard format for human-readable files (defining resources, services, properties, etc...) -* JSON *SHALL* be used as the runtime (machine-readable) markup language - ==== Naming Conventions * Identifiers nodes, and service names *SHALL* use lowercase a-z with underscore between words @@ -171,8 +100,6 @@ Services can declare any non-reserved identifier in their own proto files. NOTE: It is *STRONGLY RECOMMENDED* to scope your property names to avoid namespace collision - - == uDiscovery Interface In the following section we will explain the various APIs and interfaces that are defined in uDiscovery and their requirements. Interface definitions (input and output parameters, etc...) are covered in the link:../../../up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto[udiscovery.proto]. @@ -183,6 +110,9 @@ Write APIs are used to populate/ update data in 'local' discovery instance. ==== Set UE Topics This API shall be used by ultifi entities to update discovery with the list of topics they serve. This includes the topics they publish on and also the rpcs they serve. +==== Set UE Properties +This is used by ultifi entities if there is a need to update any of their properties in discovery. For example, version updates. + === Read/Query APIs Query APIs are used to lookup content in the database, either to resolve URIs (to be used by applications) or to fetch content of a database. From 437f9aed5b6ea358ffba9c35ce432697c389a44a Mon Sep 17 00:00:00 2001 From: mayuresh Date: Wed, 24 Apr 2024 22:17:59 -0400 Subject: [PATCH 10/11] added registration APIs --- .../core/udiscovery/v3/udiscovery.proto | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 2b8de99..c09f454 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -50,6 +50,33 @@ service uDiscovery { /************************** Write APIs ************************************/ + /* + UEs shall call RegisterUE API to add themselves to discovery. + */ + + /* Example: + RegisterUE(“//ultifi.gm.com/core.example/2.0") + Response: Status: code.OK + */ + + rpc RegisterUE(RegisterUERequest) returns ( uprotocol.v1.UStatus){ + option (method_id) = 1; + } + + /* + UEs shall call UnregisterUE API to remove themselves from discovery. + */ + + /* Example: + UnregisterUE(“//ultifi.gm.com/core.example/2.0") + Response: Status: code.OK + */ + + rpc UnregisterUE(UnregisterUERequest) returns ( uprotocol.v1.UStatus){ + option (method_id) = 1; +} + + /* UEs shall call SetUETopics API to update discovery with the list of topics they service. This will be used in two scenarios: @@ -189,6 +216,17 @@ common error reasons could be: code.PERMISSION_DENIED: The caller does not have permission to perform the query */ + +// Request message to register UE +message RegisterUERequest{ + v1.UUri UE = 1; +} + +// Request message to unregister UE +message UnregisterUERequest{ + v1.UUri UE = 1; +} + // request message to Find UE message FinduERequest { string uri = 1; From c44f92360f677e77138a5a318ee282fbda40c305 Mon Sep 17 00:00:00 2001 From: mayuresh Date: Thu, 9 May 2024 11:06:26 -0400 Subject: [PATCH 11/11] corrected few things in proto --- .../core/udiscovery/v3/udiscovery.proto | 26 ++++++++++++++----- 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index c09f454..2fbd4ef 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -145,8 +145,8 @@ service uDiscovery { Response: [“up:/core.example/1/topic1”, “up:/core.example/1/rpc1”], Status: code.OK */ - rpc GetuETopics(GetuETopicsRequests) returns (GetuETopicsResponse){ - option (method_id) = 2; + rpc GetuETopics(GetUETopicsRequest) returns (GetUETopicsResponse){ + option (method_id) = 1; } /* @@ -164,7 +164,7 @@ service uDiscovery { Response: [], Status: code.INVALID_ARGUMENT (passed device should match local device) */ - rpc GetuEList(GetuEListRequest) returns (GetuEListResponse){ + rpc GetuEList(GetUEListRequest) returns (GetUEListResponse){ option (method_id) = 4; } @@ -200,7 +200,7 @@ service uDiscovery { Status: code.OK */ - rpc SyncData(UpdateDataRequest) returns (status){ + rpc SyncData(UpdateDataRequest) returns (uprotocol.v1.UStatus){ option (method_id) = 6; } @@ -243,7 +243,7 @@ message FinduEResponse { // Request message to get list of topics for a UE -message GetuETopicsRequest { +message GetUETopicsRequest { v1.UUri UE = 1; } @@ -260,7 +260,7 @@ message GetUEListRequest{ } // Response data for GetUEtopics. -message GetuEListResponse { +message GetUEListResponse { repeated v1.UUri UEList = 1; uprotocol.v1.UStatus status = 2; // Return code for the rpc call } @@ -283,6 +283,20 @@ message SetUEPropertiesRequest{ } +// Request message to update Data on remote discovery instances +message UpdateDataRequest{ + v1.UUri parentUE = 1; + repeated Node node = 2; + +} + +// Request message to set UE Topics +message SetUETopicsRequest{ + v1.UUri parentUE = 1; + repeated UServiceTopic topicsList = 2; + +} + /* Typedef for a node properties. A node property can be any one of the ultifi ("u_") types