4.x: Web Client Discovery integration

all/pom.xml

@@ -1181,6 +1181,10 @@
             <groupId>io.helidon.webclient</groupId>
             <artifactId>helidon-webclient-api</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.helidon.webclient</groupId>
+            <artifactId>helidon-webclient-discovery</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.helidon.webclient</groupId>
             <artifactId>helidon-webclient</artifactId>

bom/pom.xml

@@ -1583,6 +1583,11 @@
                 <artifactId>helidon-webclient-api</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.helidon.webclient</groupId>
+                <artifactId>helidon-webclient-discovery</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
             <dependency>
                 <groupId>io.helidon.webclient</groupId>
                 <artifactId>helidon-webclient</artifactId>

docs/src/main/asciidoc/includes/attributes.adoc

@@ -207,6 +207,7 @@ endif::[]
 :configurable-javadoc-base-url: {javadoc-base-url}/io.helidon.common.configurable
 :context-javadoc-base-url: {javadoc-base-url}/io.helidon.common.context
 :cors-javadoc-base-url: {javadoc-base-url}/io.helidon.cors
+:discovery-providers-eureka-javadoc-base-url: {javadoc-base-url}/io.helidon.discovery.providers.eureka
 :discovery-javadoc-base-url: {javadoc-base-url}/io.helidon.discovery
 :faulttolerance-javadoc-base-url: {javadoc-base-url}/io.helidon.faulttolerance
 :grpc-server-javadoc-base-url: {javadoc-base-url}/io.helidon.webserver.grpc
@@ -247,6 +248,7 @@ endif::[]
 
 :webclient-javadoc-base-url: {javadoc-base-url}/io.helidon.webclient
 :webclient-api-javadoc-base-url: {javadoc-base-url}/io.helidon.webclient.api
+:webclient-discovery-javadoc-base-url: {javadoc-base-url}/io.helidon.webclient.discovery
 :webserver-javadoc-base-url: {javadoc-base-url}/io.helidon.webserver
 :webserver-staticcontent-javadoc-base-url: {webserver-javadoc-base-url}.staticcontent
 :webserver-cors-javadoc-base-url: {javadoc-base-url}/io.helidon.webserver.cors

docs/src/main/asciidoc/se/discovery.adoc

@@ -31,6 +31,9 @@ include::{rootdir}/includes/se.adoc[]
 * <<API Usage, API Usage>>
 * <<Providers, Providers>>
 ** <<Eureka,Eureka>>
+* <<Integrations, Integrations>>
+** <<Web Client Discovery Integration, Web Client>>
+* <<References, References>>
 
 == Overview
 
@@ -308,3 +311,115 @@ discovery: # <1>
 
 Users of the Helidon Eureka Discovery provider may also be interested in the (related)
 xref:{docdir}/integrations/eureka/eureka-registration.adoc[Eureka Server Service Instance Registration] feature.
+
+== Integrations
+
+Helidon integrates a <<Providers,Discovery provider>> with other Helidon modules as described below.
+
+=== Web Client Discovery Integration
+
+Helidon integrates a <<Providers,Discovery provider>> with xref:webclient.adoc[Web Client].
+
+==== Maven Coordinates
+
+To include the Helidon Web Client Discovery integration in your project, you add the Web Client Discovery integration
+dependency as well as a <<Providers,Discovery provider>> dependency (see
+xref:{rootdir}/about/managing-dependencies.adoc[Managing Dependencies]):
+
+[source,xml]
+.`pom.xml`
+----
+<dependencies>
+    <dependency>
+        <groupId>io.helidon.webclient</groupId>
+        <artifactId>helidon-webclient-discovery</artifactId> <!--1-->
+        <scope>runtime</scope> <!--2-->
+    </dependency>
+    <dependency>
+        <groupId>io.helidon.discovery.providers</groupId>
+        <artifactId>helidon-discovery-providers-eureka</artifactId> <!--3-->
+        <scope>runtime</scope> <!--4-->
+    </dependency>
+</dependencies>
+----
+<1> Helidon Web Client Discovery integration dependency.
+<2> The scope for the integration. `runtime` since the integration is never required at compile time.
+<3> Helidon <<Eureka, Eureka Discovery provider>> dependency (for example).
+<4> The scope for the provider. Use `runtime` if you have no interest in provider-specific classes and methods (the most
+    common case). Use `compile` if you plan to call provider-specific methods.
+
+The behavior of the Web Client Discovery integration is
+link:{webclient-discovery-javadoc-base-url}/io/helidon/webclient/discovery/WebClientDiscovery.html#handle(io.helidon.webclient.spi.WebClientService.Chain,io.helidon.webclient.api.WebClientServiceRequest)[fully
+specified and documented].
+
+==== Configuration
+
+The Helidon Web Client Discovery integration can be configured using xref:config/introduction.adoc[Helidon
+Config]. Examples shown below are in YAML, but are expressible in any format and any location that Helidon Config
+supports.
+
+Because the Helidon Web Client Discovery integration is fundamentally a
+xref:webclient.adoc#_adding_service_to_webclient[Web Client Service], you configure it under a Web Client's `services`
+configuration node:
+
+[source,yaml]
+.`application.yaml`
+----
+webclient:
+  services:
+    discovery: # <1>
+----
+<1> Indicates that the Web Client Discovery integration should apply to this Web Client configuration. More configuration
+    is required; see below.
+
+You also configure the Discovery provider in use following its documentation. See, for example,
+<<_configuration,Eureka configuration>>.
+
+==== Configuring URIs
+
+To mark URIs requested by a Web Client as subject to discovery, and to use discovery names appropriate for them, you
+need to configure _prefix URIs_. URIs that match no prefix will not be subject to discovery:
+
+[source,yaml]
+.`application.yaml`
+----
+webclient:
+  services:
+    discovery:
+      properties:
+        helidon-discovery-EXAMPLE-prefix-uri: "https://example.com:443/" # <1>
+        helidon-discovery-TEST-prefix-uri: "https://test.example.com:443/" # <2> <3>
+----
+<1> Indicates that URIs starting with `https://example.com:443/` will be subject to discovery, using the discovery name
+    of `EXAMPLE`
+<2> Indicates that URIs starting with `https://test.example.com:443/` will be subject to discovery, using the discovery
+    name of `TEST`
+<3> URIs that begin with text other than `https://example.com:443/` or `https://test.example.com:443/` will not be
+    subject to discovery
+
+===== Complicated Discovery Names
+
+To use complicated discovery names for certain prefix URIs, you can link them to specific prefix URIs as follows. This
+configuration strategy is primarily for cases where, for whatever reason, the discovery name is too long or complicated
+to appear in a property name:
+
+[source,yaml]
+.`application.yaml`
+----
+webclient:
+  services:
+    discovery:
+      properties:
+        helidon-discovery-EXAMPLE-prefix-uri: "https://example.com:443/" # <1>
+        helidon-discovery-EXAMPLE-name: "My Long Complicated Discovery Name" # <2>
+----
+<1> Indicates that URIs starting with `https://example.com:443/` will be subject to discovery
+<2> Indicates that the discovery name to use for prefix URIs identified by the
+    `helidon-discovery-EXAMPLE-prefix-uri` property name will be `My Long Complicated Discovery Name`
+
+== References
+
+* link:{discovery-javadoc-base-url}/module-summary.html[Discovery Javadoc]
+* link:{discovery-providers-eureka-javadoc-base-url}/module-summary.html[Eureka Discovery Provider Javadoc]
+* link:{webclient-discovery-javadoc-base-url}/module-summary.html[Web Client Discovery Integration Javadoc]
+* xref:webclient.adoc[Helidon Web Client]

docs/src/main/asciidoc/se/webclient.adoc

@@ -407,29 +407,56 @@ include::{sourcedir}/se/WebClientSnippets.java[tag=snippet_8,indent=0]
 
 === Adding Service to WebClient
 
-WebClient currently supports 3 built-in services namely `metrics`, `tracing` and `security`.
+WebClient currently supports four built-in services, namely
+xref:discovery.adoc#_web_client_discovery_integration[`discovery`], `metrics`, `tracing` and `security`.
 
 ==== Enabling the service
 
-In order for a service to function, their dependency needs to be added in the application's pom.xml. Below are examples on how to enable the built-in services:
+In order for a service to function, its dependencies need to be added in the application's `pom.xml`. Below are examples on how to enable the built-in services:
+
+* `discovery` (see xref:discovery.adoc#_web_client_discovery_integration[its documentation])
++
+.`pom.xml`
+[source,xml]
+----
+<dependency>
+    <groupId>io.helidon.webclient</groupId>
+    <artifactId>helidon-webclient-discovery</artifactId>
+    <scope>runtime</scope>
+</dependency>
+<dependency>
+    <groupId>io.helidon.discovery.providers</groupId>
+    <artifactId>helidon-discovery-providers-eureka</artifactId> <!--1-->
+    <scope>runtime</scope>
+</dependency>
+----
+<1> Backs the `discovery` service with a xref:discovery.adoc#_eureka[Discovery provider based on Netflix's Eureka]
 
 * `metrics`
++
+.`pom.xml`
 [source,xml]
 ----
 <dependency>
     <groupId>io.helidon.webclient</groupId>
     <artifactId>helidon-webclient-metrics</artifactId>
 </dependency>
 ----
+
 * `tracing`
++
+.`pom.xml`
 [source,xml]
 ----
 <dependency>
     <groupId>io.helidon.webclient</groupId>
     <artifactId>helidon-webclient-tracing</artifactId>
 </dependency>
 ----
+
 * `security`
++
+.`pom.xml`
 [source,xml]
 ----
 <dependency>
@@ -562,6 +589,7 @@ include::{rootdir}/config/io_helidon_webclient_context_WebClientContextService.a
 * link:{webclient-javadoc-base-url}.http2/module-summary.html[Helidon WebClient HTTP/2 Support]
 * link:{webclient-javadoc-base-url}.dns.resolver.first/module-summary.html[Helidon WebClient DNS Resolver First Support]
 * link:{webclient-javadoc-base-url}.dns.resolver.roundrobin/module-summary.html[Helidon WebClient DNS Resolver Round Robin Support]
+* link:{webclient-javadoc-base-url}.discovery/module-summary.html[Helidon WebClient Discovery Support]
 * link:{webclient-javadoc-base-url}.metrics/module-summary.html[Helidon WebClient Metrics Support]
 * link:{webclient-javadoc-base-url}.security/module-summary.html[Helidon WebClient Security Support]
 * link:{webclient-javadoc-base-url}.tracing/module-summary.html[Helidon WebClient Tracing Support]

webclient/discovery/README.md

@@ -0,0 +1,6 @@
+# Web Client Discovery
+
+This module integrates [Helidon Discovery](https://helidon.io/docs/latest/se/discovery) with [Helidon Web
+Client](https://helidon.io/docs/latest/se/webclient) by providing a a suitable
+[`WebClientService`](https://helidon.io/docs/latest/apidocs/io.helidon.webclient.api/io/helidon/webclient/spi/WebClientService.html)
+[implementation](src/main/java/io/helidon/webclient/discovery/WebClientDiscovery.java).

webclient/discovery/etc/spotbugs/exclude.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2025 Oracle and/or its affiliates.
+
+    Licensed 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.
+
+-->
+<FindBugsFilter
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://github.com/spotbugs/filter/3.0.0"
+        xsi:schemaLocation="https://github.com/spotbugs/filter/3.0.0 https://raw.githubusercontent.com/spotbugs/spotbugs/3.1.0/spotbugs/etc/findbugsfilter.xsd">
+    <Match>
+        <!--
+            The generated builder contains a local variable in its preBuildPrototype() method that is never used that
+            shadows an instance field. Harmless.
+        -->
+        <Class name="io.helidon.webclient.discovery.WebClientDiscoveryConfig$BuilderBase"/>
+        <Bug pattern="DLS_DEAD_LOCAL_STORE_SHADOWS_FIELD"/>
+    </Match>
+</FindBugsFilter>