Implementation:ClickHouse ClickHouse Poco HTTPSession

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

Overview

Base class for HTTP session management providing buffering, timeouts, throttling, and connection lifecycle management.

Description

The Poco `HTTPSession` class serves as the foundation for both client and server HTTP sessions. It implements buffered I/O over stream sockets, manages connection timeouts (separate for connection, send, and receive operations), and provides throttling capabilities to limit data transfer rates.

The class maintains an internal buffer for efficient socket I/O, supports keep-alive connections, and provides hooks for monitoring and controlling data flow through the `IHTTPSessionDataHooks` interface. It also manages exception state for tracking network errors and allows attaching application-specific session data.

Usage

ClickHouse uses this as the base for HTTP communication, providing core socket management and buffering capabilities that `HTTPClientSession` and `HTTPServerSession` extend. The throttling support is particularly useful for rate-limiting HTTP traffic.

Code Reference

Source Location

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

Signature

class IHTTPSessionDataHooks {
public:
    virtual void atStart(int bytes) = 0;
    virtual void atFinish(int bytes) = 0;
    virtual void atFail() = 0;
};

class HTTPSession {
public:
    void setKeepAlive(bool keepAlive);
    bool getKeepAlive() const;

    void setTimeout(const Poco::Timespan& timeout);
    void setTimeout(const Poco::Timespan& connectionTimeout,
                    const Poco::Timespan& sendTimeout,
                    const Poco::Timespan& receiveTimeout);

    void setReceiveThrottler(const ThrottlerPtr& throttler);
    void setSendThrottler(const ThrottlerPtr& throttler);

    Poco::Timespan getTimeout() const;
    Poco::Timespan getConnectionTimeout() const;
    Poco::Timespan getSendTimeout() const;
    Poco::Timespan getReceiveTimeout() const;

    void setSendDataHooks(const HTTPSessionDataHooksPtr& sendDataHooks);
    void setReceiveDataHooks(const HTTPSessionDataHooksPtr& receiveDataHooks);

    bool connected() const;
    virtual void abort();

    const Poco::Exception* networkException() const;

    void attachSessionData(const Poco::Any& data);
    const Poco::Any& sessionData() const;

    StreamSocket detachSocket();
    StreamSocket& socket();
    void drainBuffer(Poco::Buffer<char>& buffer);

protected:
    HTTPSession();
    HTTPSession(const StreamSocket& socket);
    HTTPSession(const StreamSocket& socket, bool keepAlive);

    int get();
    int peek();
    virtual int read(char* buffer, std::streamsize length);
    virtual int write(const char* buffer, std::streamsize length);
    int receive(char* buffer, int length);
    int buffered() const;
    void refill();
    virtual void connect(const SocketAddress& address);
    void attachSocket(const StreamSocket& socket);
    void close();
};

Import

#include <Poco/Net/HTTPSession.h>

I/O Contract

Input	Output
`StreamSocket` connection	Buffered session for HTTP communication
Timeout configuration (connection, send, receive)	Socket with configured timeouts
Data read/write requests	Buffered I/O with automatic refill/flush
Throttler objects (send/receive)	Rate-limited data transfer

Session Configuration

Property	Description
Keep-Alive	Enable persistent connections (HTTP/1.1)
Connection Timeout	Maximum time to establish connection
Send Timeout	Maximum time for send operations
Receive Timeout	Maximum time for receive operations
Send Throttler	Limits outgoing data rate
Receive Throttler	Limits incoming data rate

Usage Examples

// Configure session timeouts
HTTPClientSession session("example.com");
session.setTimeout(
    Poco::Timespan(10, 0),  // 10 second connection timeout
    Poco::Timespan(30, 0),  // 30 second send timeout
    Poco::Timespan(30, 0)   // 30 second receive timeout
);

// Enable keep-alive
session.setKeepAlive(true);

// Set up throttling (limit to 1 MB/sec)
auto throttler = std::make_shared<Throttler>(1024 * 1024);
session.setSendThrottler(throttler);
session.setReceiveThrottler(throttler);

// Attach custom data hooks for monitoring
class MyDataHooks : public IHTTPSessionDataHooks {
    void atStart(int bytes) override {
        std::cout << "Starting transfer of " << bytes << " bytes\n";
    }
    void atFinish(int bytes) override {
        std::cout << "Finished transfer of " << bytes << " bytes\n";
    }
    void atFail() override {
        std::cerr << "Transfer failed\n";
    }
};

auto hooks = std::make_shared<MyDataHooks>();
session.setSendDataHooks(hooks);
session.setReceiveDataHooks(hooks);

// Attach session-specific data
struct SessionContext {
    int requestCount = 0;
    std::string userId;
};
SessionContext ctx;
ctx.userId = "user123";
session.attachSessionData(Poco::Any(ctx));

// Later retrieve session data
if (session.sessionData().type() == typeid(SessionContext)) {
    auto& ctx = Poco::AnyCast<SessionContext&>(session.sessionData());
    ctx.requestCount++;
}

// Check connection status
if (session.connected()) {
    // Session is active
}

// Handle network errors
const Poco::Exception* ex = session.networkException();
if (ex) {
    std::cerr << "Network error: " << ex->displayText() << std::endl;
}

Related Pages

• Principle:ClickHouse_ClickHouse_HTTP_Client_Communication