// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page qthttpserver-security.html
    \title Qt HTTP Server Security Considerations
    \ingroup security
    \brief Provides the recommended security settings for Qt HTTP Server.

    \section1 Overview

    Qt HTTP Server provides several configuration settings to help protect
    an application against misuse scenarios such as malformed requests or
    unauthorized access. Qt 6.10 added several security configuration
    settings. This page summarizes recommended configurations and explains
    when and how to use them.

    \warning Do not expose Qt HTTP Server directly to the internet. Qt HTTP
    Server is not hardened against network-based attacks.

    \section1 Network setups and configurations

    Here are different ways to set up a network with a Qt HTTP Server.

    \section2 No internet access

    Ideally there should be no access to the internet at all. This is the
    safest setup, but you often need internet access. If Qt HTTP Server
    is bound to localhost or to a \l{QLocalServer}, it does not accept
    connections from the internet. If multiple clients are connected to
    127.0.0.1, the connections are added to connections per host,
    and \l{QHttpServerConfiguration::}{setMaximumConnectionsPerHost()}
    is affected. By default, no per-host connection limit is set.

    \section2 Binding to QSslServer on the internet

    It is possible, but not supported to bind the Qt HTTP Server to a
    \l{QSslServer} that is bound to a network interface that is reachable from
    the internet. Despite all the options in \l{QHttpServerConfiguration}, this
    setup is not supported because Qt HTTP Server is not sufficiently
    hardened.

    \section1 Application setup

    If using a thread pool, make sure it is not so large that the server
    cannot handle simultaneous, resource-intensive incoming requests.
    Though the \l{QHttpServer::}{route()} call makes parsing from the URL
    in the HTTP requests easy, it is the developer's responsibility to
    handle input validation.

    \section1 Qt HTTP Server security configuration

    Configure Qt HTTP Server through the \l{QHttpServerConfiguration} class.
    Adjust the limits based on your platform's capabilities and network setup.

    \section2 Rate limits

    \list
        \li Configure the maximum number of requests per second
            per client IP using
            \l{QHttpServerConfiguration::}{setRateLimitPerSecond()}.
            By default, there is no rate limit. When the limit is exceeded,
            the server responds with status code 429 (Too Many Requests).

        \li Configure the maximum number of simultaneous connections
            using \l{QHttpServerConfiguration::}{setMaximumConnections()}.
            By default, there is no connection limit. When the limit is
            exceeded, the server responds with status code 429 (Too Many
            Requests), and the connection is closed.

        \li Configure the maximum number of simultaneous
            connections per client IP using
            \l{QHttpServerConfiguration::}{setMaximumConnectionsPerHost()}.
            By default, there is no limit. When the limit is exceeded,
            the server responds with status code 429 (Too Many Requests), and
            the connection is closed.
    \endlist

    \section2 Connection limits

    \list
        \li Configure the maximum idle time for keep-alive connections
            using \l{QHttpServerConfiguration::}{setKeepAliveTimeout()}.
            By default, the timeout is 15 seconds.
    \endlist

    \section2 Allowlisting and denylisting

    \list
        \li Configure the list of client subnets that are allowed to access the
            server using \l{QHttpServerConfiguration::}{setWhitelist()}.
            By default, the allowlist is empty, and all clients are allowed.
            If the allowlist is not empty, only addresses in this list
            are accepted.
            The allowlist is checked before the denylist.

        \li Configure the denied client subnets using
            \l{QHttpServerConfiguration::}{setBlacklist()}.
            The denylist is only applied when the allowlist is empty.
            By default, the denylist is empty.
    \endlist

    \section2 Request size limits

    \list
        \li Configure the maximum URL size using
            \l{QHttpServerConfiguration::}{setMaximumUrlSize()}.
            If the limit is exceeded, the server responds with HTTP status
            code 414 (Request-URI Too Long).
            The default maximum URL size is 64 KiB.

        \li Configure the maximum total size of all HTTP request headers
            using \l{QHttpServerConfiguration::}{setMaximumTotalHeaderSize()}.
            If the limit is exceeded, the server responds with HTTP status code
            431 (Request Header Fields Too Large).
            The default total header size is 64 KiB.

        \li Configure the maximum size of a single HTTP header field
            using \l{QHttpServerConfiguration::}{setMaximumHeaderFieldSize()}.
            If the limit is exceeded, the server responds with HTTP status code
            431 (Request Header Fields Too Large).
            The default maximum header field size is 48 KiB.

        \li Configure the maximum number of HTTP header fields per request
            using \l{QHttpServerConfiguration::}{setMaximumHeaderFieldCount()}.
            If the limit is exceeded, the server responds with HTTP status code
            431 (Request Header Fields Too Large).
            The default maximum header field count is 128.

        \li Configure the maximum request body size using
            \l{QHttpServerConfiguration::}{setMaximumBodySize()}.
            If the limit is exceeded, the server responds with HTTP status code
            413 (Content Too Large).
            The default maximum body size is 32 MiB.
    \endlist

    \note Always use the latest security updates for Qt and all dependent libraries.
*/
