diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 8a01182..2fbd4ef 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -41,331 +41,314 @@ 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" }; - + /************************** Write APIs ************************************/ - // 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 - rpc LookupUri(v1.UUri) returns (LookupUriResponse) { + /* + 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; } - // Update a node in the database. - // What is returned is the status of the API request as uprotocol.v1.UStatus. - // **NOTE:** You MUST have write permission to the node in the database - rpc UpdateNode(UpdateNodeRequest) returns (uprotocol.v1.UStatus) { - option (method_id) = 2; - } + /* + UEs shall call UnregisterUE API to remove themselves from discovery. + */ - // 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; - } + /* Example: + UnregisterUE(“//ultifi.gm.com/core.example/2.0") + Response: Status: code.OK + */ - // Query the database to fetch a list of 1 or more properties for a given node. - rpc FindNodeProperties(FindNodePropertiesRequest) returns (FindNodePropertiesResponse) { - option (method_id) = 4; - } + rpc UnregisterUE(UnregisterUERequest) returns ( uprotocol.v1.UStatus){ + option (method_id) = 1; +} - // 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) { - option (method_id) = 5; - } + /* + 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. + */ - // 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; - } + /* 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) - // 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; + */ + + rpc SetUETopics(SetUETopicsRequest) returns ( uprotocol.v1.UStatus){ + option (method_id) = 1; } - // 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; - } - + /* + UEs shall call SetUEProperties API to update discovery with updated property values. + For example, this could be used to update an UE's version. + */ - // Unregister for Node change notifications - rpc UnregisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) { - option (method_id) = 9; - } + /* Example: + SetUEProperties(parentUE:“///device/UE/1”, PropertyValuesList:["version_major" : "1", "version_minor" : "2"]) + Response: Status: code.OK + */ - - // 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; + rpc SetUEProperties(SetUEPropertiesRequest) returns (uprotocol.v1.UStatus){ + option (method_id) = 1; } -} + /******************************* Read APIs ************************/ -// 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 - } -} + /* + 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) + */ + /* + Example: + FindUE(“///core.example”) + Response: [“//ultifi.gm.com/core.example/2.0”, “/core.example/1.0”], Status: code.OK + */ -// Node can be domain, device, service, resource, method, etc... -message Node { - // uProtocol long form URI pointing to this node - string uri = 1; + rpc FinduE(FinduERequest) returns (FinduEResponse) { + option (method_id) = 1; + } - // List of child nodes under this node - repeated Node nodes = 2; + /* + 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: + GetUETopics(“up:/core.example/1”) + Response: [“up:/core.example/1/topic1”, “up:/core.example/1/rpc1”], Status: code.OK + */ - // List of node properties - map properties = 3; + rpc GetuETopics(GetUETopicsRequest) returns (GetUETopicsResponse){ + option (method_id) = 1; + } - // The node type - Type type = 4; + /* + 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. + */ + /* + Example: + GetUETopics(“up:/device1”) + Response: [“up:/device1/uE1”, “up:/device1/uE2”], Status: code.OK - // 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 + GetUETopics(“up:/device2”) + Response: [], Status: code.INVALID_ARGUMENT (passed device should match local device) + */ + + rpc GetuEList(GetUEListRequest) returns (GetUEListResponse){ + option (method_id) = 4; } -} -// Message passed to the UpdateNode() RPC call -message UpdateNodeRequest { - // Node to be updated in the database - Node node = 1; + /* + 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 + */ - // Time-to-live: How long (ms) the information should be live for in the database. - // -1 means lives forever - optional int32 ttl = 3; -} + /* Example: + GetDeviceList(“up:/domain”) + Response: [“up:/domain/device1”, “up:/domain/device2”], Status: code.OK + GetUETopics(“up:/domain2”) + Response: [], Status: code.INVALID_ARGUMENT (invalid domain) -// Delete one or more nodes request -message DeleteNodesRequest { - repeated string uris = 1; // uProtocol formatted URI -} + */ + rpc GetDeviceList(GetDeviceListRequest) returns (GetDeviceListResponse){ + option (method_id) = 5; + } + /******************************* Data replication / synchronization ******/ -// 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 - string uri = 1; + /* + 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 (uprotocol.v1.UStatus){ + option (method_id) = 6; + } - // 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; +/* 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 + */ - // 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; +// Request message to register UE +message RegisterUERequest{ + v1.UUri UE = 1; } +// Request message to unregister UE +message UnregisterUERequest{ + v1.UUri UE = 1; +} -// Find 1 or more properties for a given node passed to FindNodeProperties() -message FindNodePropertiesRequest { - // the uri for the node in the database +// request message to Find UE +message FinduERequest { 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; } +/* +Return value from FinduE() API that contains the batch of Uris for the +lookup and status from the API call */ -// Returned from FindNodeProperties() -message FindNodePropertiesResponse { - // a list of property name/value pairs - map properties = 1; - - // Return code for the rpc call - uprotocol.v1.UStatus status = 2; +message FinduEResponse { + v1.UUriBatch uris = 1; // Batch of Uris + uprotocol.v1.UStatus status = 2; // Return code for the rpc call } -// 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; +// Request message to get list of topics for a UE +message GetUETopicsRequest { + v1.UUri UE = 1; } -// 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; +// Response data for GetUEtopics. +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; +} -// 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; +// Response data for GetUEtopics. +message GetUEListResponse { + repeated v1.UUri UEList = 1; + uprotocol.v1.UStatus status = 2; // Return code for the rpc call +} - // The operation performed on said Node - Operation operation = 3; +// Request message to get list of UEs for a device +message GetDeviceListRequest{ + v1.UAuthority UDomain = 1; +} - // Operation - enum Operation { - INVALID = 0; // Invalid - UPDATE = 1; // Updated - ADD = 2; // Added to the parent - REMOVE = 3; // Removed - } +// 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 +} - // 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; +// Request message to set UE topics +message SetUEPropertiesRequest{ + v1.UUri parentUE = 1; + map propertiesList = 2; - // uDiscovery resource that it serves (per SDV-202 definition): database - enum Resources { nodes = 0; } } +// Request message to update Data on remote discovery instances +message UpdateDataRequest{ + v1.UUri parentUE = 1; + repeated Node node = 2; -// 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; } +// Request message to set UE Topics +message SetUETopicsRequest{ + v1.UUri parentUE = 1; + repeated UServiceTopic topicsList = 2; -// 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; +/* +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 + } } -// 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; -} +/* +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; -// Response message 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 -} + // List of child nodes under this node + repeated Node nodes = 2; + // List of node properties + map properties = 3; -// 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 -} + // The node type + Type type = 4; -// 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; + /* + 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 + } +} - // 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/lookup_uri.puml b/up-l3/udiscovery/v3/FindUE.puml similarity index 61% rename from up-l3/udiscovery/v3/lookup_uri.puml rename to up-l3/udiscovery/v3/FindUE.puml index f7632e3..53bb25a 100644 --- a/up-l3/udiscovery/v3/lookup_uri.puml +++ b/up-l3/udiscovery/v3/FindUE.puml @@ -29,63 +29,86 @@ autonumber box uDevice #white Collections uEs #red - entity LDS #orange + entity uLDS #orange + entity uDDS #orange + entity uCDS #orange end box entity CDS #orange -uEs -> LDS: LookupUri(UriRequest) +uEs -> uLDS: FinduE(FinduERequest) note right -**UriRequest:** +**FinduERequest:** ""uri"": ""//topic//"" end note alt Found Locally -LDS --> uEs: UriResponse +uLDS --> uEs: FinduEResponse note right -**UriRequest:** +**FinduEResponse:** ""uris"": {""//topic//"", ""//topic//""} ""result"": {""code"": ""OK""} end note ||| else Invalid Argument or Permission Denied -LDS --> uEs: UriResponse +uLDS --> uEs: FinduEResponse note right -**UriResponse:** +**FinduEResponse:** ""result"" : { ""code"": ""INVALID_ARGUMENT | PERMISSION_DENIED"" } end note ||| else Remote Lookup Required -LDS -> CDS: LookupUri(UriRequest) +uLDS -> uDDS: FinduE(FinduERequest) alt Success -CDS --> LDS: UriResponse +uDDS --> uLDS: FinduEResponse note right -**UriResponse:** +**FinduEResponse:** ""uris"": {""//topic//"", ""//topic//""} ""result"": {""code"": ""OK""} end note -LDS -> LDS: Cache (per ttl) -LDS --> uEs: UriResponse +uLDS -> uLDS: Cache (per ttl) +uLDS --> uEs: FinduEResponse note right -**UriResponse:** +**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 -CDS --> LDS: UriResponse +uDDS --> uLDS: FinduEResponse note right -**UriResponse:** +**FinduEResponse:** ""result"": {""code"": ""INVALID_ARGUMENT | NOT_FOUND | PERMISSION_DENIED""} end note -LDS --> uEs: UriResponse +uLDS --> uEs: FinduEResponse end alt else Not Found -LDS --> uEs: UriResponse +uLDS --> uEs: FinduEResponse note right -**UriResponse:** +**FinduEResponse:** ""result"": {""code"": ""NOT_FOUND""} end note end alt -LDS --> uEs: UriResponse +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 diff --git a/up-l3/udiscovery/v3/README.adoc b/up-l3/udiscovery/v3/README.adoc index 6e02a76..cbcc3eb 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,10 +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. - -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... +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 @@ -44,58 +42,16 @@ 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 -|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 -|=== - - -== 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. - -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 has-a database that stores all of its local Nodes as well as caches node information for remote devices. -a|* Every uDevice *MUST* have LDS - -| *Domain uDiscovery Service (uDDS)* -| Storage for discovery information for all devices within its domain -a| -* uDDS *MUST* store `Nodes` 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 -* 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 *SHOULD* be located in the always-on uDevices - -|*Central uDiscovery Service (CDS)* -|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 +|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 |=== -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. +<> 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 @@ -105,61 +61,7 @@ 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: - - -.Node & Property Definitions -[source] ----- -// Typedef for a node properties. A node property can be any one of the 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 - } -} - -// Node can be domain, device, service, resource, method, etc... -message Node { - // 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 { - 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 - } -} ----- - - -* 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 +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. Table below lists example URIs for the various node types in the database hierarchy. @@ -177,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 @@ -203,158 +100,50 @@ 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 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. - -==== 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 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 -|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. - - == 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]. -=== 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. +=== Write APIs +Write APIs are used to populate/ update data in 'local' discovery instance. -==== Registration +==== 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. -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] +==== 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. * 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 -==== 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. - -* *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: - -* 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. - -==== Updating a Node - -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] +==== Find UE +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. -==== Deleting Node(s) +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. -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). +==== 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. -.Delete Node -image:delete_node.svg[Delete Node] +==== Get UE List +Get UE list is used retrieve the list of UEs for a given device. -==== ResolveUri +==== 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. -`ResolveUri()` is used to lookup names from ids or vice versa meaning to go to/from Long Uri from/to micro Uri. +=== Replication/ Synchronization APIs -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]. +==== Sync Data - * *MUST* be passed either a Long or Short form URI and return both the Micro and Long form URI if successful +This is used by local discovery instances to push local updates to domain and from domain to central. == 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/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 f8d2541..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: FindNodes(FindNodesRequest) - note right - **FindNodesRequest:** - ""uri"": "up://Device1/uService" - ""depth"": -1 - 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