Module io.helidon.webclient.discovery

Package io.helidon.webclient.discovery

Interface WebClientDiscovery

All Superinterfaces:

NamedService, NamedService, RuntimeType.Api<WebClientDiscoveryConfig>, WebClientService

public interface WebClientDiscovery
extends RuntimeType.Api<WebClientDiscoveryConfig>, WebClientService

A WebClientService that intercepts certain requests and uses Helidon Discovery where appropriate to discover endpoints for those requests, rerouting them as necessary.

WebClientDiscovery instances are normally created by WebClientDiscoveryProvider instances, and are not typically used directly by end users.

The specification for the handle(Chain, WebClientServiceRequest) method fully specifies the required behavior of conforming implementations of this interface, and further describes the implementation-specific behavior of WebClientDiscovery instances returned from invocations of the create(WebClientDiscoveryConfig) method.

Logging

Implementations returned by invocations of the create(WebClientDiscoveryConfig) method, and any of their internal supporting classes, will use Loggers whose names begin with io.helidon.webclient.discovery..

Logging output is particularly important to monitor because as a general rule discovery integrations must strive to be resilient in the presence of failures.

See Also:

• handle(Chain, WebClientServiceRequest)
• builder()
• WebClientDiscoveryConfig.builder()
• Discovery
• WebClientDiscoveryProvider
• WebClientDiscoveryProvider.create(io.helidon.config.Config, String)

Nested Class Summary

Nested classes/interfaces inherited from interface io.helidon.webclient.spi.WebClientService

WebClientService.Chain

Method Summary

Modifier and Type	Method	Description
static WebClientDiscoveryConfig.Builder	builder()	A convenience method that returns the result of invoking the WebClientDiscoveryConfig.builder() method.
static WebClientDiscovery	create(WebClientDiscoveryConfig prototype)	Returns a new WebClientDiscovery implementation configured with the supplied prototype.
static WebClientDiscovery	create(Consumer<WebClientDiscoveryConfig.Builder> consumer)	A convenience method that calls the builder() method, updates it using the supplied Consumer, invokes its build() method, and returns the result.
WebClientServiceResponse	handle(WebClientService.Chain chain, WebClientServiceRequest request)	Handles the supplied WebClientServiceRequest by using this WebClientDiscovery's Helidon Discovery-related configuration to discover a URI appropriate for the request, and altering the ClientUri as necessary with the discovered information before continuing with the request.
default String	name()	Returns the determinate name of this WebClientService implementation (normally discovery).
default String	type()	Returns the determinate type of this WebClientService implementation (discovery by default).

Methods inherited from interface io.helidon.builder.api.RuntimeType.Api

prototype

Method Details

handle

WebClientServiceResponse handle(WebClientService.Chain chain,
 WebClientServiceRequest request)

Handles the supplied WebClientServiceRequest by using this WebClientDiscovery's Helidon Discovery-related configuration to discover a URI appropriate for the request, and altering the ClientUri as necessary with the discovered information before continuing with the request.

The specification of this method is described below, followed by a description of its default implementation.

Specification

Any implementation of this method must:

1. Deterministically decide whether the supplied WebClientServiceRequest is one for which Helidon Discovery is appropriate. If it is not, the implementation must call chain.proceed(request) and return the result.
2. Deterministically produce a discovery name and a default URI appropriate for the supplied WebClientServiceRequest to use during the discovery process. If either cannot be produced for any reason, the implementation must call chain.proceed(request) and return the result.
3. Use the discovery name and default URI in a discovery request. If this cannot happen for any reason, the implementation must call chain.proceed(request) and return the result.
4. Select a URI from the discovered response (the discovered URI). If this cannot happen for any reason, the implementation must call chain.proceed(request) and return the result.
5. Deterministically alter the supplied WebClientServiceRequest's ClientUri with information supplied by the discovered URI. If this cannot happen for any reason, the implementation must call chain.proceed(request) and return the result.
6. Call chain.proceed(request) and return the result.

Implementation Behavior

The (default) behavior of this method, as implemented in instances of WebClientDiscovery returned from the create(WebClientDiscoveryConfig) method, conforms to the specification, and is described below. This implementation-specific behavior may change in subsequent revisions of this interface and its cooperating classes.

Finding and using discovery-related information suitable for the supplied WebClientServiceRequest proceeds as follows, with examples:

1. Upon initial WebClientDiscovery implementation instantiation, the entries of its prototype's prefixUris Map are normalized and sorted, such that entries containing longer (more specific) URIs precede shorter ones (less specific). This operation happens exactly once.
2. If the prefixUris Map is empty, then discovery will never be used, and chain.proceed(request) is invoked, and the result is returned.
3. In a loop, for each such URI (e.g. http://service1.example.com), proceeding from the longest (most specific) one to the shortest (least specific) one:
   1. a prefix URI is created from it, following the logic that Helidon WebClient uses elsewhere internally to create URIs, for overall fidelity.
      1. Note that this logic may add additional information, or change existing information; e.g. in this example the URI would be http://service1.example.com:80/; note the explicit port (80) and non-empty path that is now / instead of the empty string. See ClientUri.create(URI) and ClientUri.toUri() for an explanation of this logic.
   2. For each such prefix URI, an attempt is made to relativize the original ClientUri against it:
      1. The original ClientUri's URI (e.g. http://service1.example.com:80/foo) in normal form is relativized against the normalized prefix URI (e.g. http://service1.example.com:80/).
         1. Note that for ClientUri-implementation-related reasons, the original ClientUri will always be absolute, its host and port will always be defined, and its path will never be empty, even if the user did not specify any of this explicitly.
      2. If relativization yields anything other than a simple raw path, the prefix URI is skipped and the loop continues.
      3. Otherwise, the loop exits with:
         • the prefix URI (e.g. http://service1.example.com:80/),
         • its corresponding discovery name (e.g. S1), and
         • the result of relativization (the remaining raw path, e.g. foo).
4. If no prefix URI was found for any reason, discovery is not needed, chain.proceed(request) is invoked, and the result is returned.
5. The Discovery instance supplied by the prototype is used to issue a discovery request using the discovery name (e.g. S1) and prefix URI (e.g. http://service1.example.com:80/). The first of the URIs returned is the discovered URI; see Discovery.uris(String, java.net.URI) for more details. For this example, presume the discovered URI is, e.g., http://23.192.228.84:80/v1/.
6. A new raw path is formed by first resolving the remaining raw path (e.g. foo) against the discovered URI (e.g. http://23.192.228.84:80/v1/), yielding, e.g., http://23.192.228.84:80/v1/foo, and then acquiring its raw path (e.g. /v1/foo).
7. If defined, the scheme (e.g. http), host (e.g. 23.192.228.84), and port (e.g. 80) of the discovered URI (e.g. http://23.192.228.84:80/v1) are installed on the original ClientUri using its scheme(String), host(String) and port(int) methods.
8. The new raw path (e.g. /v1/foo) is installed on the original ClientUri using its path(String) method.
9. This results in the final URI (e.g. http://23.192.228.84:80/v1/foo).

Finally, including when any error is encountered, chain.proceed(request) is invoked, and the result is returned.

Configuration Examples

A minimal example of (YAML) configuration follows:

client: # see the Helidon Configuration Reference for WebClient
  services:
    discovery:
      prefix-uris:
        S1: http://service1.example.com

In this example, original ClientUris beginning with http://service1.example.com:80/ (note the added/explicit port and path) will be subject to discovery, using S1 as the discovery name; all others will be passed through with no discovery-related action being taken.

Specified by:

handle in interface WebClientService

Parameters:

chain - a WebClientService.Chain

request - a WebClientServiceRequest

Returns:

the result of invoking the proceed(WebClientServiceRequest) method on the supplied WebClientService.Chain

Throws:

NullPointerException - if any argument is null

See Also:

• WebClientDiscoveryConfig.prefixUris()
• WebClientService.handle(Chain, WebClientServiceRequest)

name

default String name()

Returns the determinate name of this WebClientService implementation (normally discovery).

The default implementation of this method returns the result of invoking the name() method on this WebClientDiscovery's prototype.

Specified by:

name in interface NamedService

Specified by:

name in interface NamedService

Specified by:

name in interface WebClientService

Returns:

this WebClientDiscovery's determinate name

See Also:

• WebClientDiscoveryConfig.name()
• WebClientService.name()
• NamedService.name()

type

default String type()

Returns the determinate type of this WebClientService implementation (discovery by default).

The default implementation of this method returns discovery.

Specified by:

type in interface NamedService

Specified by:

type in interface NamedService

Specified by:

type in interface WebClientService

Returns:

discovery when invoked

See Also:

• WebClientService.type()
• NamedService.type()

builder

static WebClientDiscoveryConfig.Builder builder()

A convenience method that returns the result of invoking the WebClientDiscoveryConfig.builder() method.

Returns:

a non-null WebClientDiscoveryConfig.Builder

See Also:

• WebClientDiscoveryConfig.builder()
• Helidon Builder

create

static WebClientDiscovery create(Consumer<WebClientDiscoveryConfig.Builder> consumer)

A convenience method that calls the builder() method, updates it using the supplied Consumer, invokes its build() method, and returns the result.

Parameters:

consumer - a Consumer of WebClientDiscoveryConfig.Builder instances; must not be null

Returns:

a new WebClientDiscovery implementation; never null

Throws:

NullPointerException - if consumer is null

See Also:

• builder()
• Builder.update(Consumer)
• WebClientDiscoveryConfig.Builder.build()
• Helidon Builder

create

static WebClientDiscovery create(WebClientDiscoveryConfig prototype)

Returns a new WebClientDiscovery implementation configured with the supplied prototype.

This method is most commonly called by the WebClientDiscoveryConfig.Builder.build() method, which supplies it with the return value of an invocation of its WebClientDiscoveryConfig.Builder.buildPrototype() method.

Parameters:

prototype - a WebClientDiscoveryConfig; must not be null

Returns:

a new WebClientDiscovery implementation

Throws:

NullPointerException - if prototype is null

See Also:

• WebClientDiscoveryConfig.Builder.build()
• WebClientDiscoveryConfig.Builder.buildPrototype()
• Helidon Builder