Qt HTTP Server

Qt HTTP Server supports building HTTP server functionality into an application. Common use cases are exposing the application's functionality through REST APIs, or making devices in a trusted environment configurable also via HTTP. The limitations are described in Limitations and Security.

Overview

Qt HTTP Server provides building blocks for embedding a lightweight HTTP server supporting HTTP/2, HTTP/1.1, and HTTP/1.0 in an application. There are classes for the messages sent and received, and for the various parts of an HTTP server.

The QHttpServer class has a route() function to bind callables to different incoming URLs. These callables can take as arguments an extensible collection of different copyable types that are parsed from the URL. Types supported are most numeric types, QString, QByteArray, and QUrl. Optionally the callables can also take QHttpServerRequest and QHttpServerResponder objects as arguments. The QHttpServerRequest class contains all the information of an incoming request, and is needed to get the body() from a POST HTTP request. The callables either return a QHttpServerResponse object or respond using the QHttpServerResponder argument. The QHttpServerResponse class contains a complete response and has numerous constructors for different types, while the QHttpServerResponder has various methods for writing back to the client.

The QHttpServer class also has an addAfterRequestHandler() function to process a QHttpServerResponse further, and a setMissingHandler() function to override the default behavior of returning 404 Not Found when no routes are matched. From the QAbstractHttpServer class it inherits a bind() function to bind to a listening QTcpServer, QSslServer, or QLocalServer.

An HTTP server can also be created by subclassing the QAbstractHttpServer class and overriding the handleRequest() and missingHandler() functions.

Runtime logging can be configured as described here.

Limitations and Security

Qt HTTP Server does not have many of the more advanced features and optimizations that general-purpose HTTP servers have. It also has not seen the same scrutiny regarding various attack vectors over the network. Use Qt HTTP Server, therefore, only for local connections or in a trusted network, and do not expose the ports to the internet.

You can add HTTPS support as a basic security measure, though. If Qt is compiled with support for TLS, you can bind the HTTP server to a QSslServer object, providing Transport Layer Security handling.

The QSslSocket::SupportedFeature::ServerSideAlpn feature from the active TLS backend is needed for HTTP/2 support. To check if a backend supports this, use QSslSocket::isFeatureSupported.

The primary way of configuring QHttpServer happens through the QHttpServerConfiguration class. Key configuration options are listed below.

Rate Limitations

• The maximum number of requests per second per client IP can be configured using setRateLimitPerSecond(). By default, no rate limit is applied. When the limit is exceeded, the server responds with status code 429 (Too Many Requests).
• The keep-alive timeout controls how long an idle keep-alive connection is kept open before being closed. This can be configured using setKeepAliveTimeout(). The default value is 15 seconds.

Number of Connections Limitations

• The maximum number of simultaneous requests can be configured using setMaximumConnections(). By default, no limit is applied. When the limit is exceeded, the server responds with status code 429 (Too Many Requests), and the connection is closed.
• The maximum number of simultaneous requests per client IP can be configured using setMaximumConnectionsPerHost(). By default, no limit is applied. When the limit is exceeded, the server responds with status code 429 (Too Many Requests), and the connection is closed.

Blacklisting and Whitelisting

• The list of client subnets that are allowed to access the server can be configured using setWhitelist(). By default, the whitelist is empty, and all clients are allowed. If the whitelist is not empty, only addresses in this list are accepted. The whitelist is checked before the blacklist.
• Denied client subnets can be configured using setBlacklist(). The blacklist is only applied when the whitelist is empty. By default, the blacklist is empty.

Size Limitations on Incoming Requests

• The accepted URL size, specified in bytes, can be limited using setMaximumUrlSize(). If the limit is exceeded, the server responds with HTTP status code 414 (Request-URI Too Long). The default value is 64 KiB.
• The total accepted size of all HTTP request headers can be limited using setMaximumTotalHeaderSize(). If the limit is exceeded, the server responds with HTTP status code 431 (Request Header Fields Too Large). The default value is 64 KiB.
• The accepted size of a single HTTP header field can be limited using setMaximumHeaderFieldSize(). If exceeded, the server responds with HTTP status code 431 (Request Header Fields Too Large). The default value is 48 KiB.
• The number of HTTP header fields accepted per request can be limited using setMaximumHeaderFieldCount(). If exceeded, the server responds with HTTP status code 431 (Request Header Fields Too Large). The default value is 128.
• The accepted HTTP request body size, specified in bytes, can be limited using setMaximumBodySize(). If exceeded, the server responds with HTTP status code 413 (Content Too Large). The default value is 32 MiB.

Using the Module

Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including CMake and qmake.

Building with CMake

Use the find_package() command to locate the needed module components in the Qt6 package:

find_package(Qt6 REQUIRED COMPONENTS HttpServer)
target_link_libraries(mytarget PRIVATE Qt6::HttpServer)

See also the Build with CMake overview.

Building with qmake

To configure the module for building with qmake, add the module as a value of the QT variable in the project's .pro file:

QT += httpserver

Licenses

Qt HTTP Server is available under commercial licenses from The Qt Company. In addition, it is available under the GNU General Public License, version 3. See Qt Licensing for further details.

Reference

• Qt HTTP Server Logging
• C++ Classes

Examples

The module provides the following Examples as a guide to using the API.