Implementation:ClickHouse ClickHouse Poco HTTPClientSession

Knowledge Sources	ClickHouse Poco Documentation
Domains	Networking, HTTP
Last Updated	2026-02-08 00:00 GMT

Overview

Client-side HTTP session management with support for persistent connections, proxy configuration, and keep-alive.

Description

The Poco `HTTPClientSession` class implements client-side HTTP/1.1 functionality for establishing connections to HTTP servers and exchanging requests and responses. It extends `HTTPSession` to provide client-specific features including host/port configuration, proxy support (with CONNECT tunneling and authentication), and persistent connection management with keep-alive timeouts.

The class manages connection lifecycle, automatically reconnecting when necessary, and provides methods to send HTTP requests and receive responses. It supports both HTTP and HTTPS (via subclasses), proxy authentication, and configurable keep-alive behavior to optimize connection reuse.

Usage

ClickHouse uses this vendored Poco component for HTTP client operations, including communicating with remote HTTP services, fetching data from HTTP endpoints, and interacting with HTTP-based APIs. The proxy support enables ClickHouse to work in network environments requiring proxy servers.

Code Reference

Source Location

• Repository: ClickHouse
• File: base/poco/Net/include/Poco/Net/HTTPClientSession.h
• Lines: 1-495

Signature

class HTTPClientSession : public HTTPSession {
public:
    struct ProxyConfig {
        std::string host;
        Poco::UInt16 port;
        std::string protocol;
        bool tunnel;
        std::string username;
        std::string password;
        std::string nonProxyHosts;
        std::string originalRequestProtocol;
    };

    HTTPClientSession();
    explicit HTTPClientSession(const StreamSocket& socket);
    explicit HTTPClientSession(const SocketAddress& address);
    HTTPClientSession(const std::string& host, Poco::UInt16 port = HTTP_PORT);
    HTTPClientSession(const std::string& host, Poco::UInt16 port, const ProxyConfig& proxyConfig);

    void setHost(const std::string& host);
    const std::string& getHost() const;
    void setPort(Poco::UInt16 port);
    Poco::UInt16 getPort() const;

    void setProxy(const std::string& host, Poco::UInt16 port, const std::string& protocol, bool tunnel);
    void setProxyCredentials(const std::string& username, const std::string& password);
    void setProxyConfig(const ProxyConfig& config);
    static void setGlobalProxyConfig(const ProxyConfig& config);

    void setKeepAliveTimeout(const Poco::Timespan& timeout);
    Poco::Timespan getKeepAliveTimeout() const;
    bool isKeepAliveExpired(double reliability = 1.0) const;

    virtual std::ostream& sendRequest(HTTPRequest& request, uint64_t* connect_time, uint64_t* first_byte_time);
    virtual std::istream& receiveResponse(HTTPResponse& response);
    virtual bool peekResponse(HTTPResponse& response);
    virtual void reset();
    virtual bool secure() const;
};

Import

#include <Poco/Net/HTTPClientSession.h>

I/O Contract

Input	Output
Host name/IP and port number	Established TCP connection to server
`HTTPRequest` object with headers and method	Output stream for writing request body
Request body written to stream	`HTTPResponse` object with status and headers
Response headers processed	Input stream for reading response body

Proxy Configuration

Field	Description
`host`	Proxy server hostname or IP address
`port`	Proxy server TCP port
`protocol`	Proxy protocol (`http` or `https`)
`tunnel`	Use CONNECT method to establish tunnel
`username`	Proxy authentication username
`password`	Proxy authentication password
`nonProxyHosts`	Regex pattern for hosts to bypass proxy

Usage Examples

// Simple HTTP GET request
HTTPClientSession session("www.example.com", 80);
HTTPRequest request(HTTPRequest::HTTP_GET, "/index.html");
session.sendRequest(request);

HTTPResponse response;
std::istream& rs = session.receiveResponse(response);
std::cout << "Status: " << response.getStatus() << std::endl;
std::string body;
Poco::StreamCopier::copyToString(rs, body);

// HTTP POST with body
HTTPRequest postReq(HTTPRequest::HTTP_POST, "/api/data");
postReq.setContentType("application/json");
std::ostream& os = session.sendRequest(postReq);
os << "{\"key\":\"value\"}";
session.receiveResponse(response);

// Using proxy
HTTPClientSession::ProxyConfig proxyConfig;
proxyConfig.host = "proxy.example.com";
proxyConfig.port = 8080;
proxyConfig.username = "user";
proxyConfig.password = "pass";

HTTPClientSession proxiedSession("target.com", 80, proxyConfig);
// ... make requests through proxy ...

// Keep-alive connection reuse
session.setKeepAliveTimeout(Poco::Timespan(8, 0));
// Make multiple requests on same session
for (int i = 0; i < 10; i++) {
    HTTPRequest req(HTTPRequest::HTTP_GET, "/page" + std::to_string(i));
    session.sendRequest(req);
    session.receiveResponse(response);
    // Connection is automatically reused
}

Related Pages

• Principle:ClickHouse_ClickHouse_HTTP_Client_Communication