feat(Net): HTTPS proxy support

Net/include/Poco/Net/HTTPClientSession.h

@@ -21,9 +21,11 @@
 #include "Poco/Net/IPAddress.h"
 #include "Poco/Net/Net.h"
 #include "Poco/Net/HTTPSession.h"
+#include "Poco/Net/HTTPSessionFactory.h"
 #include "Poco/Net/HTTPBasicCredentials.h"
 #include "Poco/Net/HTTPDigestCredentials.h"
 #include "Poco/Net/HTTPNTLMCredentials.h"
+#include "Poco/Net/ProxyConfig.h"
 #include "Poco/Net/SocketAddress.h"
 #include "Poco/SharedPtr.h"
 #include <istream>
@@ -32,7 +34,6 @@
 
 namespace Poco::Net {
 
-
 class HTTPRequest;
 class HTTPResponse;
 
@@ -65,40 +66,6 @@ class Net_API HTTPClientSession: public HTTPSession
 	/// set up a session through a proxy.
 {
 public:
-	enum ProxyAuthentication
-	{
-		PROXY_AUTH_NONE,        /// No proxy authentication
-		PROXY_AUTH_HTTP_BASIC,  /// HTTP Basic proxy authentication (default, if username and password are supplied)
-		PROXY_AUTH_HTTP_DIGEST, /// HTTP Digest proxy authentication
-		PROXY_AUTH_NTLM         /// NTLMv2 proxy authentication
-	};
-
-	struct ProxyConfig
-		/// HTTP proxy server configuration.
-	{
-		ProxyConfig():
-			port(HTTP_PORT),
-			authMethod(PROXY_AUTH_HTTP_BASIC)
-		{
-		}
-
-		std::string  host;
-			/// Proxy server host name or IP address.
-		Poco::UInt16 port;
-			/// Proxy server TCP port.
-		std::string  username;
-			/// Proxy server username.
-		std::string  password;
-			/// Proxy server password.
-		std::string  nonProxyHosts;
-			/// A regular expression defining hosts for which the proxy should be bypassed,
-			/// e.g. "localhost|127\.0\.0\.1|192\.168\.0\.\d+". Can also be an empty
-			/// string to disable proxy bypassing.
-
-		ProxyAuthentication authMethod;
-			/// The authentication method to use - HTTP Basic or NTLM.
-	};
-
 	HTTPClientSession();
 		/// Creates an unconnected HTTPClientSession.
 
@@ -167,21 +134,33 @@ class Net_API HTTPClientSession: public HTTPSession
 	const SocketAddress& getSourceAddress6();
 		/// Returns the last IPV6 source address set with setSourceAddress
 
-	void setProxy(const std::string& host, Poco::UInt16 port = HTTPSession::HTTP_PORT);
-		/// Sets the proxy host name and port number.
+	void setProxy(const std::string& host, Poco::UInt16 port = HTTPSession::HTTP_PORT, const std::string& protocol = "http", bool tunnel = true);
+		/// Sets the proxy host name, port number, protocol (http or https) and tunnel behaviour.
 
 	void setProxyHost(const std::string& host);
 		/// Sets the host name of the proxy server.
 
 	void setProxyPort(Poco::UInt16 port);
 		/// Sets the port number of the proxy server.
 
+	void setProxyProtocol(const std::string& protocol);
+		/// Sets the proxy protocol (http or https).
+
+	void setProxyTunnel(bool tunnel);
+		/// If 'true' proxy will be used as tunnel.
+
 	const std::string& getProxyHost() const;
 		/// Returns the proxy host name.
 
 	Poco::UInt16 getProxyPort() const;
 		/// Returns the proxy port number.
 
+	const std::string& getProxyProtocol() const;
+		/// Returns the proxy protocol.
+
+	bool isProxyTunnel() const;
+		/// Returns 'true' if proxy is configured as tunnel.
+
 	void setProxyCredentials(const std::string& username, const std::string& password);
 		/// Sets the username and password for proxy authentication.
 		/// Only Basic authentication is supported.
@@ -203,7 +182,7 @@ class Net_API HTTPClientSession: public HTTPSession
 	void setProxyConfig(const ProxyConfig& config);
 		/// Sets the proxy configuration.
 
-	const ProxyConfig& getProxyConfig() const;
+	[[nodiscard]] const ProxyConfig& getProxyConfig() const;
 		/// Returns the proxy configuration.
 
 	static void setGlobalProxyConfig(const ProxyConfig& config);
@@ -216,7 +195,7 @@ class Net_API HTTPClientSession: public HTTPSession
 		/// The global proxy configuration should be set at start up, before
 		/// the first HTTPClientSession instance is created.
 
-	static const ProxyConfig& getGlobalProxyConfig();
+	[[nodiscard]] static const ProxyConfig& getGlobalProxyConfig();
 		/// Returns the global proxy configuration.
 
 	void setKeepAliveTimeout(const Poco::Timespan& timeout);
@@ -307,11 +286,11 @@ class Net_API HTTPClientSession: public HTTPSession
 		/// the request or response stream changes into
 		/// fail or bad state, but not eof state).
 
-	virtual bool secure() const;
+	[[nodiscard]] virtual bool secure() const;
 		/// Return true iff the session uses SSL or TLS,
 		/// or false otherwise.
 
-	bool bypassProxy() const;
+	[[nodiscard]] bool bypassProxy() const;
 		/// Returns true if the proxy should be bypassed
 		/// for the current host.
 
@@ -365,6 +344,9 @@ class Net_API HTTPClientSession: public HTTPSession
 		/// Calls proxyConnect() and attaches the resulting StreamSocket
 		/// to the HTTPClientSession.
 
+	HTTPSessionFactory _proxySessionFactory;
+		/// Factory to create HTTPClientSession to proxy.
+
 private:
 	using OStreamPtr = Poco::SharedPtr<std::ostream>;
 	using IStreamPtr = Poco::SharedPtr<std::istream>;
@@ -390,8 +372,11 @@ class Net_API HTTPClientSession: public HTTPSession
 
 	static ProxyConfig _globalProxyConfig;
 
-	HTTPClientSession(const HTTPClientSession&);
-	HTTPClientSession& operator = (const HTTPClientSession&);
+	void initProxySessionFactory();
+		/// Registers the "http" protocol with _proxySessionFactory.
+
+	HTTPClientSession(const HTTPClientSession&) = delete;
+	HTTPClientSession& operator = (const HTTPClientSession&) = delete;
 
 	friend class WebSocket;
 };
@@ -424,6 +409,18 @@ inline Poco::UInt16 HTTPClientSession::getProxyPort() const
 }
 
 
+inline const std::string& HTTPClientSession::getProxyProtocol() const
+{
+	return _proxyConfig.protocol;
+}
+
+
+[[nodiscard]] inline bool HTTPClientSession::isProxyTunnel() const
+{
+	return _proxyConfig.tunnel;
+}
+
+
 inline const std::string& HTTPClientSession::getProxyUsername() const
 {
 	return _proxyConfig.username;
@@ -436,13 +433,13 @@ inline const std::string& HTTPClientSession::getProxyPassword() const
 }
 
 
-inline const HTTPClientSession::ProxyConfig& HTTPClientSession::getProxyConfig() const
+inline const ProxyConfig& HTTPClientSession::getProxyConfig() const
 {
 	return _proxyConfig;
 }
 
 
-inline const HTTPClientSession::ProxyConfig& HTTPClientSession::getGlobalProxyConfig()
+inline const ProxyConfig& HTTPClientSession::getGlobalProxyConfig()
 {
 	return _globalProxyConfig;
 }

Net/include/Poco/Net/HTTPSessionFactory.h

@@ -19,7 +19,7 @@
 
 
 #include "Poco/Net/Net.h"
-#include "Poco/Net/HTTPClientSession.h"
+#include "Poco/Net/ProxyConfig.h"
 #include "Poco/Mutex.h"
 #include "Poco/URI.h"
 #include "Poco/SingletonHolder.h"
@@ -29,7 +29,7 @@
 
 namespace Poco::Net {
 
-
+class HTTPClientSession;
 class HTTPSessionInstantiator;
 
 
@@ -51,7 +51,7 @@ class Net_API HTTPSessionFactory
 	HTTPSessionFactory(const std::string& proxyHost, Poco::UInt16 proxyPort);
 		/// Creates the HTTPSessionFactory and sets the proxy host and port.
 
-	HTTPSessionFactory(const HTTPClientSession::ProxyConfig& proxyConfig);
+	HTTPSessionFactory(const ProxyConfig& proxyConfig);
 		/// Creates the HTTPSessionFactory and sets the proxy configuration.
 
 	~HTTPSessionFactory();
@@ -96,10 +96,10 @@ class Net_API HTTPSessionFactory
 	const std::string& proxyPassword() const;
 		/// Returns the password for proxy authorization.
 
-	void setProxyConfig(const HTTPClientSession::ProxyConfig& proxyConfig);
+	void setProxyConfig(const ProxyConfig& proxyConfig);
 		/// Sets the proxy configuration.
 
-	const HTTPClientSession::ProxyConfig& getProxyConfig() const;
+	const ProxyConfig& getProxyConfig() const;
 		/// Returns the proxy configuration.
 
 	static HTTPSessionFactory& defaultFactory();
@@ -121,7 +121,7 @@ class Net_API HTTPSessionFactory
 	typedef std::map<std::string, InstantiatorInfo> Instantiators;
 
 	Instantiators _instantiators;
-	HTTPClientSession::ProxyConfig _proxyConfig;
+	ProxyConfig _proxyConfig;
 
 	mutable Poco::FastMutex _mutex;
 };
@@ -154,7 +154,7 @@ inline const std::string& HTTPSessionFactory::proxyPassword() const
 }
 
 
-inline const HTTPClientSession::ProxyConfig& HTTPSessionFactory::getProxyConfig() const
+inline const ProxyConfig& HTTPSessionFactory::getProxyConfig() const
 {
 	return _proxyConfig;
 }

Net/include/Poco/Net/HTTPSessionInstantiator.h

@@ -51,14 +51,14 @@ class Net_API HTTPSessionInstantiator
 		/// Unregisters the factory with the global HTTPSessionFactory.
 
 protected:
-	void setProxyConfig(const HTTPClientSession::ProxyConfig& proxyConfig);
+	void setProxyConfig(const ProxyConfig& proxyConfig);
 		/// Sets the proxy configuration.
 
-	const HTTPClientSession::ProxyConfig& getProxyConfig() const;
+	const ProxyConfig& getProxyConfig() const;
 		/// Returns the proxy configuration.
 
 private:
-	HTTPClientSession::ProxyConfig _proxyConfig;
+	ProxyConfig _proxyConfig;
 
 	friend class HTTPSessionFactory;
 };
@@ -67,7 +67,7 @@ class Net_API HTTPSessionInstantiator
 //
 // inlines
 //
-inline const HTTPClientSession::ProxyConfig& HTTPSessionInstantiator::getProxyConfig() const
+inline const ProxyConfig& HTTPSessionInstantiator::getProxyConfig() const
 {
 	return _proxyConfig;
 }

Net/include/Poco/Net/ProxyConfig.h

@@ -0,0 +1,69 @@
+//
+// ProxyConfig.h
+//
+// Library: Net
+// Package: HTTP
+// Module:  ProxyConfig
+//
+// Definition of the ProxyConfig class.
+//
+// Copyright (c) 2026-2026, Applied Informatics Software Engineering GmbH.
+// and Contributors.
+//
+// SPDX-License-Identifier:	BSL-1.0
+//
+
+#ifndef Net_ProxyConfig_INCLUDED
+#define Net_ProxyConfig_INCLUDED
+
+#include "Poco/Net/Net.h"
+#include "Poco/Net/HTTPSession.h"
+
+namespace Poco {
+namespace Net {
+
+
+enum class ProxyAuthentication
+{
+	None,        /// No proxy authentication
+	Basic,       /// HTTP Basic proxy authentication (default, if username and password are supplied)
+	Digest,      /// HTTP Digest proxy authentication
+	NTLM         /// NTLMv2 proxy authentication
+};
+
+
+struct ProxyConfig
+	/// HTTP proxy server configuration.
+{
+	ProxyConfig() = default;
+
+	std::string host;
+		/// Proxy server host name or IP address.
+	Poco::UInt16 port = HTTPSession::HTTP_PORT;
+		/// Proxy server TCP port.
+	std::string protocol = "http";
+		/// Protocol to use (http or https).
+	bool tunnel = true;
+		/// Use proxy as tunnel (establish 2-way communication through CONNECT request).
+		/// If tunnel option is 'false' request will be sent directly to proxy without CONNECT request.
+		///
+		/// Warning: Setting tunnel to false for HTTPS sessions means the TLS connection
+		/// terminates at the proxy, not at the destination server. The proxy will see
+		/// the request in plaintext.
+	std::string username;
+		/// Proxy server username.
+	std::string password;
+		/// Proxy server password.
+	std::string nonProxyHosts;
+		/// A regular expression defining hosts for which the proxy should be bypassed,
+		/// e.g. "localhost|127\.0\.0\.1|192\.168\.0\.\d+". Can also be an empty
+		/// string to disable proxy bypassing.
+
+	ProxyAuthentication authMethod = ProxyAuthentication::Basic;
+		/// The authentication method to use - HTTP Basic or NTLM.
+};
+
+
+} } // namespace Poco::Net
+
+#endif // Net_ProxyConfig_INCLUDED