Minor http proxy improvements

src/main/java/io/vertx/core/http/impl/HttpClientImpl.java

@@ -57,6 +57,7 @@ public class HttpClientImpl implements HttpClient, MetricsProvider {
   private final ContextImpl creatingContext;
   private final ConnectionManager connectionManager;
   private final Closeable closeHook;
+  private final boolean useProxy;
   private final SSLHelper sslHelper;
   private volatile boolean closed;
 
@@ -89,6 +90,8 @@ public HttpClientImpl(VertxInternal vertx, HttpClientOptions options) {
     }
     HttpClientMetrics metrics = vertx.metricsSPI().createMetrics(this, options);
     connectionManager = new ConnectionManager(this, metrics);
+    ProxyOptions proxyOptions = options.getProxyOptions();
+    useProxy = !options.isSsl() && proxyOptions != null && proxyOptions.getType() == ProxyType.HTTP;
   }
 
   @Override
@@ -713,29 +716,22 @@ private HttpClientRequest doRequest(HttpMethod method, String host, int port, St
     Objects.requireNonNull(host, "no null host accepted");
     Objects.requireNonNull(relativeURI, "no null relativeURI accepted");
     checkClosed();
-    String connectHost;
-    int connectPort;
-    ProxyOptions proxyOptions = options.getProxyOptions();
-    final boolean useProxy = !options.isSsl() && proxyOptions != null && proxyOptions.getType() == ProxyType.HTTP;
+    HttpClientRequest req;
     if (useProxy) {
       relativeURI = "http://" + host + (port != 80 ? ":" + port : "") + relativeURI;
-      connectHost = proxyOptions.getHost();
-      connectPort = proxyOptions.getPort();
+      ProxyOptions proxyOptions = options.getProxyOptions();
       if (proxyOptions.getUsername() != null && proxyOptions.getPassword() != null) {
         if (headers == null) {
           headers = MultiMap.caseInsensitiveMultiMap();
         }
         headers.add("Proxy-Authorization", "Basic " + Base64.getEncoder()
             .encodeToString((proxyOptions.getUsername() + ":" + proxyOptions.getPassword()).getBytes()));
       }
-    } else {
-      connectHost = host;
-      connectPort = port;
-    }
-    HttpClientRequest req = new HttpClientRequestImpl(this, method, connectHost, connectPort, options.isSsl(),
-        relativeURI, vertx);
-    if (useProxy) {
+      req = new HttpClientRequestImpl(this, method, proxyOptions.getHost(), proxyOptions.getPort(), options.isSsl(),
+          relativeURI, vertx);
       req.setHost(host + (port != 80 ? ":" + port : ""));
+    } else {
+      req = new HttpClientRequestImpl(this, method, host, port, options.isSsl(), relativeURI, vertx);
     }
     if (headers != null) {
       req.headers().setAll(headers);

src/main/java/io/vertx/core/http/package-info.java

@@ -1591,21 +1591,29 @@
  *
  * === Using a proxy for HTTP/HTTPS connections
  *
- * HttpClient supports accessing http/https URLs via a HTTP proxy (e.g. Squid) or _SOCKS4a_ or _SOCKS5_ proxy.
+ * The http client supports accessing http/https URLs via a HTTP proxy (e.g. Squid) or _SOCKS4a_ or _SOCKS5_ proxy.
  * The CONNECT protocol uses HTTP/1.x but can connect to HTTP/1.x and HTTP/2 servers.
+ *
  * Connecting to h2c (unencrypted HTTP/2 servers) is likely not supported by http proxies since they will support
  * HTTP/1.1 only.
  *
  * The proxy can be configured in the {@link io.vertx.core.http.HttpClientOptions} by setting a
  * {@link io.vertx.core.net.ProxyOptions} object containing proxy type, hostname, port and optionally username and password.
  *
- * Here's an example:
+ * Here's an example of using an HTTP proxy:
  *
  * [source,$lang]
  * ----
  * {@link examples.HTTPExamples#example58}
  * ----
- * or using SOCKS5 proxy
+ *
+ * When the client connects to an http URL, it connects to the proxy server and provides the full URL in the
+ * HTTP request ("GET http://www.somehost.com/path/file.html HTTP/1.1").
+ *
+ * When the client connects to an https URL, it asks the proxy to create a tunnel to the remote host with
+ * the CONNECT method.
+ *
+ * For a SOCKS5 proxy:
  *
  * [source,$lang]
  * ----