From 8d4f2423025927038088a514cbc0e4a2fffeba46 Mon Sep 17 00:00:00 2001 From: Steven Hartley Date: Mon, 4 Nov 2024 08:48:18 -0500 Subject: [PATCH] More changes from code review --- .../core/udiscovery/v3/udiscovery.proto | 10 +++------- up-l3/udiscovery/v3/service.adoc | 19 +++++-------------- 2 files changed, 8 insertions(+), 21 deletions(-) diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 17d3e31..9cef96a 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -46,9 +46,6 @@ service uDiscovery { // Find Services. // // Discover authorities, instances, and versions of services based on the passed URI. - // The only mandatory portion of the URI that must be passed is the ue_id, the rest can be discovered. - // When you pass the wildcard for authority_name, the search will be done up to the domain, in order to seach - // in the central discovery database, you must set search_central=true. rpc FindServices(FindServicesRequest) returns (FindServicesResponse) { option (uprotocol.method_id) = 1; } @@ -72,8 +69,7 @@ service uDiscovery { // Example might be to get information about a specific topic, all topics for a service (using wildcard resource_id), // or all topics for all services for a given device (using wildcard ue_id and resource_id) message GetServiceTopicsRequest { - // The URI of the topics that we would like to query. for example, - // to fetch a specific topic, we would set + // The URI of the topics that we would like to query. uprotocol.v1.UUri topic = 1; // Recursively search up to the central level when true, otherwise only search up to the domain level @@ -98,8 +94,8 @@ message ServiceTopicInfo { // How long the topic metadata is valid for in seconds. // If the metadata is older than this value, the client SHOULD re-fetch the metadata. - // If the field is missed or the value is 0, the client MAY assume the metadata lives forever. - optional uint32 ttl = 3; + // Metadata lives forever if the value is 0 (default). + uint32 ttl = 3; } diff --git a/up-l3/udiscovery/v3/service.adoc b/up-l3/udiscovery/v3/service.adoc index 4ec4c81..0124ac6 100644 --- a/up-l3/udiscovery/v3/service.adoc +++ b/up-l3/udiscovery/v3/service.adoc @@ -67,12 +67,7 @@ A client uE invokes `FindServices()` to get meta data (authority, version, insta [.specitem,oft-sid="dsn~discovery-findservices-error-permission~1",oft-needs="impl,test"] -- -* *MUST* return `UCode.PERMISSION_DENIED` if the caller is not permitted to query for that service. --- - -[.specitem,oft-sid="dsn~discovery-findservices-error-internal~1",oft-needs="impl,test"] --- -* *MUST* return `UCode.INTERNAL` if an internal error occurs (database is corrupted). +* *MUST* return `UCode.PERMISSION_DENIED` if the caller is not permitted to invoke this API. -- @@ -93,13 +88,9 @@ A client uE invokes `FindServices()` to get meta data (authority, version, insta [.specitem,oft-sid="dsn~discovery-getservicetopics-error-permission~1",oft-needs="impl,test"] -- -* *MUST* return `UCode.PERMISSION_DENIED` if the caller is not permitted to query for that topic(s). +* *MUST* return `UCode.PERMISSION_DENIED` if the caller is not permitted to invoke this API. -- -[.specitem,oft-sid="dsn~discovery-getservicetopics-error-internal~1",oft-needs="impl,test"] --- -* *MUST* return `UCode.INTERNAL` if an internal error occurs (database is corrupted). --- === Recursive Lookups @@ -119,7 +110,7 @@ UDiscovery services perform a recursive search when the local or domain instance [.specitem,oft-sid="dsn~discovery-recursive-async~1",oft-needs="impl,test"] -- -* The original local search *MUST ONLY* return the response message when the recursive search has completed. +* The original local search *MUST ONLY* return the response message when the recursive search has completed. The link:../../../up-core-api/uprotocol/v1/uattributes.proto[`UAttribute.ttl`] is passed to the method invocation to indicate when the lookup should timeout. -- [.specitem,oft-sid="dsn~discovery-recursive-internal~1",oft-needs="impl,test"] @@ -171,7 +162,7 @@ To replicate removal of `UServiceTopic` metadata: [.specitem,oft-sid="dsn~discovery-setservicetopic-error-invalid~1",oft-needs="impl,test"] -- -*MUST* return `UCode.INVALID_ARGUMENT` if the URI passed does not contain a valid ue_id or a FQURI. +*MUST* return `UCode.INVALID_ARGUMENT` if the passed in URI is not a valid xref:../../../basics/uri.adoc[uProtocol URI]. -- [.specitem,oft-sid="dsn~discovery-setservicetopic-error-permission~1",oft-needs="impl,test"] @@ -185,7 +176,7 @@ To replicate removal of `UServiceTopic` metadata: * *MUST* return `UCode.NOT_FOUND` if no topic matching the URI was found when the `UServiceTopic` is being removed (i.e. `ttl=0`). -- - +<> below illustrates how data is replicated using a trusted OTA (_over-the-air_) uE that is responsible for installing or removing applications for said device. .Replication API Design [#udiscovery-replication-design]