4.x: Web Client Discovery integration

[ljnelson]

Web Client Discovery

Summary

This PR integrates Discovery with Helidon Web Client by introducing a suitable WebClientService implementation (as required for such integrations).

Pull Request

The heart of the pull request is the WebClientDiscovery interface (an extension of the WebClientService interface) and the DefaultWebClientDiscovery class that implements it. All other .java files are boilerplate or scaffolding related to the required usage of Helidon Builder.

The full specification of this integration can be found in the documentation of the WebClientDiscovery#handle(io.helidon.webclient.spi.WebClientService.Chain, io.helidon.webclient.api.WebClientServiceRequest) method.

Documentation

Documentation included in this pull request consists of:

• Full javadoc (class and method specifications)
• Style- and length-compatible additions to webclient.adoc
• A new section in discovery.adoc

Thanks in particular to @tjquinno, @romain-grecourt and @barchetta for their collective design and documentation help.

Requirements

• Discovery is opt-in, not out-out, so Web Client Discovery must be opt-in as well.

• Discovery itself can be disabled, and WebClientServiceProvider implementations can be disabled. When either is disabled, the implementation must continue by using any supplied URIs "as is".

• Discovery must not prevent requests from completing, even in the face of errors, so Web Client Discovery must not either.

• It must be easy to see (in configuration, etc.) which Web Client requests are subject to discovery, and which are not.

• Given a WebClientServiceRequest, the implementation must be able to retrieve or infer a discovery name and a default URI from its contents.

• Given a UriInfo, the implementation must have a deterministic algorithm for combining path information that is part of the discovered URI returned by discovery, path information that is part of the default URI submitted as part of discovery, and remaining path information that is part of the UriInfo that is not part of either.

Invariants and Constraints

• Invariant: The implementation fundamentally must be a WebClientService created by a WebClientServiceProvider implementation and therefore must adhere to its requirements as described in its javadocs.

• Invariant: Helidon Builder API must be used.

• Invariant: Textual representations of URIs must not be used as configuration keys.

• Invariant: Properties must not be used as the primary means of configuration.

• Constraint: ClientRequestBase supports only URIs whose schemes are http or https. (See also issue 10752.)

• Constraint: ClientUri does not support opaque URIs.

• Constraint: ClientUri paths are never empty, even when explicitly set to be empty.

• Constraint: ClientUri#create() returns a ClientUri with a scheme component of http, a host component of localhost, a port component of 80 and a path of /.

Sample Javadoc

io.helidon.webclient.discovery.WebClientDiscovery

Javadoc HTML pages are not capturable by full-screen screenshot tools. Screenshots are accordingly paged below.

Page 1

Page 2

Page 3

Page 4

[tjquinno]

A couple possible small changes.

[tomas-langer]

The way the webclient discovery is configured seems very complicated to me. I think this deserves more attention. I think we should dedicate some time for it on our weekly meeting