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

/*!
    \page qthttpserver-index.html
    \since 6.4
    \title Qt HTTP Server
    \brief Provides a lightweight server implementing the HTTP protocol.

    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 \l{Limitations and Security}.

    \section1 Overview

    Qt HTTP Server provides building blocks for embedding a lightweight
    \l{RFC 9110}{HTTP} server supporting \l{RFC 9113}{HTTP/2},
    \l{RFC 9112}{HTTP/1.1}, and \l{RFC 1945}{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 \l{QHttpServer::}{route()} function to bind
    callables to different incoming URLs. These callables can take as arguments
    an \l{QHttpServerRouter::addConverter}{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 \l{QHttpServerRequest::}{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 \l{QHttpServer::}{addAfterRequestHandler()}
    function to process a QHttpServerResponse further, and a
    \l{QHttpServer::}{setMissingHandler()} function to override the default
    behavior of returning \c{404 Not Found} when no routes are matched. From
    the QAbstractHttpServer class it inherits a \l{QAbstractHttpServer::}{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 \l{QAbstractHttpServer::}{handleRequest()} and
    \l{QAbstractHttpServer::}{missingHandler()} functions.

    Runtime logging can be configured as described \l{qthttpserver-logging.html}{here}.

    \section1 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 \l{QSslSocket::SupportedFeature::ServerSideAlpn} feature from the
    active TLS backend is needed for HTTP/2 support. To check if a backend
    supports this, use \l{QSslSocket::isFeatureSupported}.

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

    \section2 Rate Limitations

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

        \li The keep-alive timeout controls how long an idle keep-alive connection is
            kept open before being closed. This can be configured using
            \l{QHttpServerConfiguration::}{setKeepAliveTimeout()}.
            The default value is 15 seconds.
    \endlist

    \section2 Number of Connections Limitations

    \list
        \li The maximum number of simultaneous requests can be configured using
            \l{QHttpServerConfiguration::}{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.

        \li The maximum number of simultaneous requests per client IP can be
            configured using \l{QHttpServerConfiguration::}{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.
    \endlist

    \section2 Blacklisting and Whitelisting

    \list
        \li The list of client subnets that are allowed to access the server can be
            configured using \l{QHttpServerConfiguration::}{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.

        \li Denied client subnets can be configured using
            \l{QHttpServerConfiguration::}{setBlacklist()}.
            The blacklist is only applied when the whitelist is empty.
            By default, the blacklist is empty.
    \endlist

    \section2 Size Limitations on Incoming Requests

    \list
        \li The accepted URL size, specified in bytes, can be limited
            using \l{QHttpServerConfiguration::}{setMaximumUrlSize()}.
            If the limit is exceeded, the server responds with HTTP status
            code 414 (Request-URI Too Long).
            The default value is 64 KiB.

        \li The total accepted size of all HTTP request headers can be limited
            using \l{QHttpServerConfiguration::}{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.

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

        \li The number of HTTP header fields accepted per request can be limited
            using \l{QHttpServerConfiguration::}{setMaximumHeaderFieldCount()}.
            If exceeded, the server responds with HTTP status code 431
            (Request Header Fields Too Large).
            The default value is 128.

        \li The accepted HTTP request body size, specified in bytes, can be limited
            using \l{QHttpServerConfiguration::}{setMaximumBodySize()}.
            If exceeded, the server responds with HTTP status code 413
            (Content Too Large).
            The default value is 32 MiB.
    \endlist

    \section1 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.

    \section2 Building with CMake

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

    \badcode
    find_package(Qt6 REQUIRED COMPONENTS HttpServer)
    target_link_libraries(mytarget PRIVATE Qt6::HttpServer)
    \endcode

    See also the \l{Build with CMake} overview.

    \section2 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:

    \badcode
    QT += httpserver
    \endcode

    \section1 Licenses

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

    \section1 Reference
    \list
    \li \l{Qt HTTP Server Logging}
    \li \l{Qt HTTP Server C++ Classes}{C++ Classes}
    \endlist

    \section1 Examples

    The module provides the following \l{Qt HTTP Server Examples}{Examples} as a guide to using
    the API.
*/
