Fixes #7647 - Document org.eclipse.jetty.client.Socks4Proxy "secure" …

…parameter. (#11533) Added javadocs and documentation. Signed-off-by: Simone Bordet <[email protected]>
jetty · Mar 22, 2024 · ae6f98e · ae6f98e
1 parent 0ab9f68
commit ae6f98e
Show file tree

Hide file tree

Showing 4 changed files with 96 additions and 0 deletions.
diff --git a/...entation/src/main/asciidoc/programming-guide/client/http/client-http-proxy.adoc b/...entation/src/main/asciidoc/programming-guide/client/http/client-http-proxy.adoc
@@ -37,6 +37,8 @@ Configured in this way, `HttpClient` makes requests to the HTTP proxy (for plain
 
 Proxying is supported for any version of the HTTP protocol.
 
+The communication between the client and the proxy may be encrypted, so that it would not be possible for another party on the same network as the client to know what servers the client connects to.
+
 [[pg-client-http-proxy-socks5]]
 ===== SOCKS5 Proxy Support
 

diff --git a/jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/HttpProxy.java b/jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/HttpProxy.java
@@ -38,35 +38,92 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * <p>Client-side proxy configuration for HTTP proxying, as specified by
+ * <a href="https://www.rfc-editor.org/rfc/rfc9110.html">RFC 9110</a>.</p>
+ * <p>By default the communication between client and proxy happens using
+ * the HTTP/1.1 protocol, but it may be configured to use
+ * also other HTTP protocol versions, such as HTTP/2.</p>
+ */
 public class HttpProxy extends ProxyConfiguration.Proxy
 {
     private static final Logger LOG = LoggerFactory.getLogger(HttpProxy.class);
 
+    /**
+     * <p>Creates a new instance with the given HTTP proxy host and port.</p>
+     *
+     * @param host the HTTP proxy host name
+     * @param port the HTTP proxy port
+     */
     public HttpProxy(String host, int port)
     {
         this(new Origin.Address(host, port), false);
     }
 
+    /**
+     * <p>Creates a new instance with the given HTTP proxy address.</p>
+     * <p>When {@code secure=true} the communication between the client and the
+     * proxy will be encrypted (using this proxy {@link #getSslContextFactory()}
+     * which typically defaults to that of {@link HttpClient}.</p>
+     *
+     * @param address the HTTP proxy address (host and port)
+     * @param secure whether the communication between the client and the HTTP proxy should be secure
+     */
     public HttpProxy(Origin.Address address, boolean secure)
     {
         this(address, secure, new Origin.Protocol(List.of("http/1.1"), false));
     }
 
+    /**
+     * <p>Creates a new instance with the given HTTP proxy address and protocol.</p>
+     *
+     * @param address the HTTP proxy address (host and port)
+     * @param secure whether the communication between the client and the HTTP proxy should be secure
+     * @param protocol the protocol to use to communicate with the HTTP proxy
+     */
     public HttpProxy(Origin.Address address, boolean secure, Origin.Protocol protocol)
     {
         this(new Origin(secure ? "https" : "http", address, null, protocol, Transport.TCP_IP), null);
     }
 
+    /**
+     * <p>Creates a new instance with the given HTTP proxy address and TLS configuration.</p>
+     * <p>The {@link SslContextFactory} could have a different configuration from the
+     * one configured in {@link HttpClient}, and it is used to communicate with the HTTP
+     * proxy only (not to communicate with the servers).</p>
+     *
+     * @param address the HTTP proxy address (host and port)
+     * @param sslContextFactory the {@link SslContextFactory.Client} to use to communicate with the HTTP proxy
+     */
     public HttpProxy(Origin.Address address, SslContextFactory.Client sslContextFactory)
     {
         this(address, sslContextFactory, new Origin.Protocol(List.of("http/1.1"), false));
     }
 
+    /**
+     * <p>Creates a new instance with the given HTTP proxy address, TLS configuration and protocol.</p>
+     * <p>The {@link SslContextFactory} could have a different configuration from the
+     * one configured in {@link HttpClient} and it is used to communicate with the HTTP
+     * proxy only (not to communicate with the servers).</p>
+     *
+     * @param address the HTTP proxy address (host and port)
+     * @param sslContextFactory the {@link SslContextFactory.Client} to use to communicate with the HTTP proxy
+     * @param protocol the protocol to use to communicate with the HTTP proxy
+     */
     public HttpProxy(Origin.Address address, SslContextFactory.Client sslContextFactory, Origin.Protocol protocol)
     {
         this(new Origin(sslContextFactory == null ? "http" : "https", address, null, protocol, Transport.TCP_IP), sslContextFactory);
     }
 
+    /**
+     * <p>Creates a new instance with the given HTTP proxy {@link Origin} and TLS configuration.</p>
+     * <p>The {@link SslContextFactory} could have a different configuration from the
+     * one configured in {@link HttpClient} and it is used to communicate with the HTTP
+     * proxy only (not to communicate with the servers).</p>
+     *
+     * @param origin the HTTP proxy {@link Origin} information
+     * @param sslContextFactory the {@link SslContextFactory.Client} to use to communicate with the HTTP proxy
+     */
     public HttpProxy(Origin origin, SslContextFactory.Client sslContextFactory)
     {
         super(origin, sslContextFactory);

diff --git a/jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/Socks4Proxy.java b/jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/Socks4Proxy.java
@@ -33,13 +33,35 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * <p>Client-side proxy configuration for SOCKS4, a de-facto standard.</p>
+ * <p>Consider using SOCK5 instead, a protocol that has been standardized
+ * by IETF.</p>
+ *
+ * @see Socks5Proxy
+ */
 public class Socks4Proxy extends ProxyConfiguration.Proxy
 {
+    /**
+     * <p>Creates a new instance with the given SOCKS4 proxy host and port.</p>
+     *
+     * @param host the SOCKS4 proxy host name
+     * @param port the SOCKS4 proxy port
+     */
     public Socks4Proxy(String host, int port)
     {
         this(new Origin.Address(host, port), false);
     }
 
+    /**
+     * <p>Creates a new instance with the given SOCKS4 proxy address.</p>
+     * <p>When {@code secure=true} the communication between the client and the
+     * proxy will be encrypted (using this proxy {@link #getSslContextFactory()}
+     * which typically defaults to that of {@link HttpClient}.</p>
+     *
+     * @param address the SOCKS4 proxy address (host and port)
+     * @param secure whether the communication between the client and the SOCKS4 proxy should be secure
+     */
     public Socks4Proxy(Origin.Address address, boolean secure)
     {
         super(address, secure, null, null);

diff --git a/jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/Socks5Proxy.java b/jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/Socks5Proxy.java
@@ -56,11 +56,26 @@ public class Socks5Proxy extends Proxy
 
     private final Map<Byte, Socks5.Authentication.Factory> authentications = new LinkedHashMap<>();
 
+    /**
+     * <p>Creates a new instance with the given SOCKS5 proxy host and port.</p>
+     *
+     * @param host the SOCKS5 proxy host name
+     * @param port the SOCKS5 proxy port
+     */
     public Socks5Proxy(String host, int port)
     {
         this(new Origin.Address(host, port), false);
     }
 
+    /**
+     * <p>Creates a new instance with the given SOCKS5 proxy address.</p>
+     * <p>When {@code secure=true} the communication between the client and the
+     * proxy will be encrypted (using this proxy {@link #getSslContextFactory()}
+     * which typically defaults to that of {@link HttpClient}.</p>
+     *
+     * @param address the SOCKS5 proxy address (host and port)
+     * @param secure whether the communication between the client and the SOCKS5 proxy should be secure
+     */
     public Socks5Proxy(Origin.Address address, boolean secure)
     {
         super(address, secure, null, null);