diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 9cef96a..6381139 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -72,8 +72,8 @@ message GetServiceTopicsRequest { // 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 - bool search_central = 2; + // Recursively search up to the root node of the uDiscovery tree + bool recursive = 2; } @@ -104,8 +104,8 @@ message FindServicesRequest { // The Uri to look up uprotocol.v1.UUri uri = 1; - // Recursively search up to the central level when true, otherwise only search up to the domain level - bool search_central = 2; + // Recursively search up to the root node of the uDiscovery tree + bool recursive = 2; } diff --git a/up-l3/udiscovery/v3/client.adoc b/up-l3/udiscovery/v3/client.adoc index dfee1da..bc3a953 100644 --- a/up-l3/udiscovery/v3/client.adoc +++ b/up-l3/udiscovery/v3/client.adoc @@ -51,7 +51,7 @@ Each link:../languages.adoc[uProtocol Language Library] *MUST* implement the cli === FindServices() -The FindServices() API is used to find the authority(ies), instance(s), and version(s) 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 search in the central discovery database, you must set `search_central=true`. +The FindServices() API is used to find service instances matching search criteria like authority, instance ID and (major) version. The only mandatory part of the provided (search) URI is the uEntity ID (`ue_id`), the rest can be discovered. The `recursive` flag can be used to include the uDiscovery service instance's parent nodes in the search. [.specitem,oft-sid="dsn~discovery-findservices-error-notfound~1",oft-needs="impl,test"] -- @@ -61,7 +61,7 @@ The FindServices() API is used to find the authority(ies), instance(s), and vers [.specitem,oft-sid="dsn~discovery-findservices-error-invalid-argument~1",oft-needs="impl,test"] -- * *MUST* return a `UCode.INVALID_ARGUMENT` if: - * `search_central==true` and `authority_name` does not contain the wildcard `*`. + * `recursive==true` and `authority_name` does not contain the wildcard `*`. * `UUri` is empty -- @@ -78,11 +78,11 @@ The FindServices() API is used to find the authority(ies), instance(s), and vers .FindServices() Examples [#findservices-examples, cols="1,1,3", options="header", width="80%"] |=== -| URI | `search_central` | Description +| URI | `recursive` | Description | `up:/FFFF1234/FF/0` | false | Find local instances & versions of service 1234. -| `up://*/FFFF1234/FF/0` | false | Find instances & versions of service 1234 within a domain. -| `up://*/FFFF0004/FF/0` | true | Find instances & versions of service 4 that are globally addressable. +| `up://*/FFFF1234/FF/0` | false | Find instances & versions of service 1234 that are known to the local uDiscovery service instance. +| `up://*/FFFF0004/FF/0` | true | Find instances & versions of service 4 that are known to the local uDiscovery service instance or any of its parent nodes. | `up://*/11234/2/0` | false | Find the authority_name for version 2 & instance 1 of service 1234. |=== diff --git a/up-l3/udiscovery/v3/service.adoc b/up-l3/udiscovery/v3/service.adoc index 0c00db2..1a43ea3 100644 --- a/up-l3/udiscovery/v3/service.adoc +++ b/up-l3/udiscovery/v3/service.adoc @@ -100,10 +100,10 @@ Recursive lookups happen when the client sets the following information in the r * `authority_name` *MUST* contain the wildcard `*`. -- -If `search_central` inside of the `FindServicesRequest` or `GetServiceTopicsRequest` is `true``: +If the `recursive` flag of a `FindServicesRequest` or `GetServiceTopicsRequest` is set to `true`: [.specitem,oft-sid="dsn~discovery-recursive-central~1",oft-needs="impl,test"] -- -* *MUST* search recursively up to and including the central instance. +* *MUST* search recursively along the branch within the uDiscovery service instance hierarchy up to and including the root node of the tree. -- UDiscovery services perform a recursive search when the local or domain instance calls `FindService()` or `GetServiceTopics()` API and then propagates the response back to the client.