QHttpServer Class

Member Function Documentation

[explicit] QHttpServer::QHttpServer(QObject *parent = nullptr)

Creates an instance of QHttpServer with parent parent.

[override virtual noexcept] QHttpServer::~QHttpServer()

Destroys a QHttpServer.

template <typename Functor> void QHttpServer::addAfterRequestHandler(const QObject *context, Functor &&slot)

Register a context and slot to be called after each request is handled.

The slot has to implement the signature void (*)(const QHttpServerRequest &, QHttpServerResponse &).

The slot can also be a function pointer, non-mutable lambda, or any other copyable callable with const call operator. In that case the context will be a context object and the handler will be valid until the context object is destroyed.

Example:

server.addAfterRequestHandler(&server, [] (const QHttpServerRequest &req, QHttpServerResponse &resp) {
    auto h = resp.headers();
    h.append(QHttpHeaders::WellKnownHeader::Cookie, "PollyWants=Cracker");
    resp.setHeaders(std::move(h));
}

void QHttpServer::clearMissingHandler()

Resets the handler to the default one that produces replies with status 404 Not Found.

See also setMissingHandler.

template <typename Rule = QHttpServerRouterRule, typename Functor> Rule *QHttpServer::route(const QString &pathPattern, QHttpServerRequest::Methods method, const QObject *context, Functor &&slot)

This method adds a new routing Rule to the server's QHttpServerRouter member. The Rule template parameter can be any class derived from QHttpServerRouterRule. The parameters are passed to Rule. The server matches incoming HTTP requests against registered rules based on the URL path and HTTP method, and the first match of both is executed.

The pathPattern parameter is compared with the path() of the URL of the incoming request. The method parameter is compared with the HTTP method of the incoming request. The slot parameter is the request handler. It can be a member function pointer of context, a function pointer, non-mutable lambda, or any copyable callable with a const call operator. If context is provided, the rule remains valid as long as context exists. The context must share the same thread affinity as QHttpServer.

The slot takes as arguments any number of parsed arguments, that are extracted from the pathPattern by matching the "<arg>" placeholders, followed by an optional QHttpServerRequest and optional QHttpServerResponder. These two classes are called specials.

The slot can return a QHttpServerResponse or a convertible type:

QHttpServer server;
server.route("/test/", this, [] () { return ""; });

Alternatively, if an optional QHttpServerResponder argument is provided, the response has to be written using it and the function must return void or QFuture<void>. QFuture<void> support was added in Qt 6.11. The QHttpServerResponder is not copyable, and can be passed as reference or rvalue reference, except when returning a QFuture<void>, in which case it must be passed as a rvalue reference to prevent it from going out of scope.

server.route("/test2", this,
             [] (QHttpServerResponder &&responder) {
                responder.write(QHttpServerResponder::StatusCode::Forbidden);
             });

Furthermore QHttpServerRequest can be used as a last argument or, if there is a QHttpServerResponder argument, as a second to last argument to get detailed information of the request. It can be passed as a const reference (only for non-concurrent callbacks) or by value, and can be used to access the body of the request:

server.route("/test3", QHttpServerRequest::Method::Post, this,
             [] (QHttpServerRequest request, QHttpServerResponder &&responder) {
                responder.write(request.body(), "text/plain"_ba);
             });

Any placeholder ( "<arg>" ) in pathPattern is automatically converted to match the handler's argument types. Supported types include integers, floating point numbers, QString, QByteArray, and QUrl. The QUrl class can be used as the last parameter to handle the end of the pathPattern, and by splitting it an arbitrary number of arguments can be supported. Custom converters can be added using QHttpServerRouter::addConverter().

Each registered type has an associated regex that is used to match and convert placeholders in the pathPattern. These regex patterns are combined to construct a parser for the entire path. The resulting parser is then used to verify if the path matches the pattern. If parsing succeeds, the corresponding function is called with the converted parameters. If parsing fails, the next registered callback is attempted. If parsing fails for all callbacks, the missingHandler is called.

In the example below, the value in the request path replacing "<arg>" is converted to an int because the lambda expects an int parameter. When an HTTP request matches the route, the converted value is passed to the lambda's page argument:

QHttpServer server;
server.route("/showpage/<arg>", this, [] (int page) { return getPage(page); });

This function returns, if successful, a pointer to the newly created Rule, otherwise a nullptr. The pointer can be used to set parameters on any custom QHttpServerRouter class:

auto rule = server.route<MyRule>("/test4", this, [] () {return "";});
rule->setParameter("test");

Requests are processed sequentially inside the QHttpServer's thread by default. The request handler may return QFuture<QHttpServerResponse> if concurrent processing is desired:

server.route("/feature/<arg>", [] (int ms) {
    return QtConcurrent::run(pool, [ms] () {
        QThread::msleep(ms);
        return QHttpServerResponse("the future is coming");
    });
});

The lambda of the QtConcurrent::run() is executed concurrently, but all the network communication is executed in the thread the QHttpServer belongs.

Routes returning futures are only executed fully concurrently on an HTTP/2 connection. Earlier versions of HTTP do not support interleaving parts of different responses: The responses must come back in full in the same order as the requests come in. So even if a route handler returns a QFuture<void> the next incoming request on that HTTP/1 connection will not be processed until processing of the current one is done. Route handlers on different connections can be executed concurrently though.

Making a route handler perform its work in a concurrent run can have benefits for all versions of HTTP because the thread that QHttpServer belongs to will be relieved of the work that the concurrent run performs.

QHttpServerRequest is copyable, and must be captured by value when returning a future, because the variables passed to slot may go out of scope before the future is finished.

server.route("/test4", QHttpServerRequest::Method::Post, this,
             [] (QHttpServerRequest request) {
                return QtConcurrent::run(pool, [request]() {
                    return QHttpServerResponse("text/plain"_ba, request.body());
                }
             });

A slot that captures QHttpServerRequest or QHttpServerResponder by reference when returning a future causes an assertion with an explanation of why it forbidden.

Not all platforms support moving QHttpServerResponder into a mutable lambda that is passed to QConcurrent::run, so the workaround is to move QHttpServerResponder into a std::shared_ptr and copying that.

server.route("/concurrent-multipart-back/<arg>",
             [](QString message, QHttpServerResponder &&responder) {
                return QtConcurrent::run(pool,
                    [=, r = std::make_shared<QHttpServerResponder>(std::move(responder))] {
                        QByteArray ba = message.toUtf8();
                        r->writeBeginChunked("text/plain"_ba);
                        for (ushort i = 1; i < 8; ++i) {
                            r->writeChunk(ba);
                        }
                        r->writeEndChunked(ba);
                    });
            });

See also QHttpServerRouter::addRule and addAfterRequestHandler.

template <typename Rule = QHttpServerRouterRule, typename Functor> Rule *QHttpServer::route(const QString &pathPattern, Functor &&handler)

Overload of QHttpServer::route to create a Rule for pathPattern and QHttpServerRequest::Method::AnyKnown. All requests are forwarded to handler, which can be a function pointer, a non-mutable lambda, or any other copyable callable with const call operator. The rule will be valid until the QHttpServer is destroyed.

template <typename Rule = QHttpServerRouterRule, typename Functor> Rule *QHttpServer::route(const QString &pathPattern, QHttpServerRequest::Methods method, Functor &&handler)

Overload of QHttpServer::route to create a Rule for pathPattern and method. All requests are forwarded to handler, which can be a function pointer, a non-mutable lambda, or any other copyable callable with const call operator. The rule will be valid until the QHttpServer is destroyed.

template <typename Rule = QHttpServerRouterRule, typename Functor> Rule *QHttpServer::route(const QString &pathPattern, const QObject *context, Functor &&slot)

Overload of QHttpServer::route to create a Rule for pathPattern and the method QHttpServerRequest::Method::AnyKnown. All requests are forwarded to context and slot.

QHttpServerRouter *QHttpServer::router()

Returns a pointer to the router object.

const QHttpServerRouter *QHttpServer::router() const

Returns a pointer to the constant router object.

template <typename Functor> void QHttpServer::setMissingHandler(const QObject *context, Functor &&slot)

Set a handler for unhandled requests.

All unhandled requests will be forwarded to the context's slot.

The slot has to implement the signature void (*)(const QHttpServerRequest &, QHttpServerResponder &). The slot can also be a function pointer, non-mutable lambda, or any other copyable callable with const call operator. In that case the context will be a context object. The handler will be valid until the context object is destroyed.

The default handler replies with status 404 Not Found.

See also clearMissingHandler.