QNetworkRequestFactory convenience class

The class provides a way to represent server-side service endpoints.
With RESTful applications these endpoints typically have a need for
repeating requests fields such as headers, query parameters,
bearer token, base URL, SSL configuration. This class allows setting
of the repeating parts, while allowing the setting of changing parts
on a per-request basis.

[ChangeLog][QtNetwork][QNetworkRequestFactory] Added a new convenience
class to help with the needs of repeating network request details
imposed by the server-side service endpoints, which is common
with RESTful applications.

Task-number: QTBUG-113814
Change-Id: Iabcfaed786949ffbb0ad0c75297d0db6ecc1a3cc
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
Reviewed-by: Mate Barany <mate.barany@qt.io>
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>

3 files changed, 622 insertions, 0 deletions

diff --git a/src/network/access/qnetworkrequestfactory.cpp b/src/network/access/qnetworkrequestfactory.cpp
new file mode 100644
index 0000000000..3f039515cb
--- /dev/null
+++ b/src/network/access/qnetworkrequestfactory.cpp
@@ -0,0 +1,497 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
+
+#include "qnetworkrequestfactory.h"
+#include "qnetworkrequestfactory_p.h"
+
+#if QT_CONFIG(ssl)
+#include <QtNetwork/qsslconfiguration.h>
+#endif
+
+#include <QtCore/qloggingcategory.h>
+
+QT_BEGIN_NAMESPACE
+
+QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QNetworkRequestFactoryPrivate)
+
+using namespace Qt::StringLiterals;
+
+Q_LOGGING_CATEGORY(lcQrequestfactory, "qt.network.access.request.factory")
+
+/*!
+    \class QNetworkRequestFactory
+    \since 6.7
+    \ingroup shared
+    \inmodule QtNetwork
+
+    \brief Convenience class for grouping remote server endpoints that share
+    common network request properties.
+
+    REST servers often have endpoints that require the same headers and other data.
+    Grouping such endpoints with a QNetworkRequestFactory makes it more
+    convenient to issue requests to these endpoints; only the typically
+    varying parts such as \e path and \e query parameters are provided
+    when creating a new request.
+
+    Basic usage steps of QNetworkRequestFactory are as follows:
+    \list
+        \li Instantiation
+        \li Setting the data common to all requests
+        \li Issuing requests
+    \endlist
+
+    An example of usage:
+
+    \snippet code/src_network_access_qnetworkrequestfactory.cpp 0
+*/
+
+/*!
+    Creates a new QNetworkRequestFactory object.
+    Use setBaseUrl() to set a valid base URL for the requests.
+
+    \sa QNetworkRequestFactory(const QUrl &baseUrl), setBaseUrl()
+*/
+
+QNetworkRequestFactory::QNetworkRequestFactory()
+    : d(new QNetworkRequestFactoryPrivate)
+{
+}
+
+/*!
+    Creates a new QNetworkRequestFactory object, initializing the base URL to
+    \a baseUrl. The base URL is used to populate subsequent network
+    requests.
+
+    If the URL contains a \e path component, it will be extracted and used
+    as a base path in subsequent network requests. This means that any
+    paths provided when requesting individual requests will be appended
+    to this base path, as illustrated below:
+
+    \snippet code/src_network_access_qnetworkrequestfactory.cpp 1
+ */
+QNetworkRequestFactory::QNetworkRequestFactory(const QUrl &baseUrl)
+    : d(new QNetworkRequestFactoryPrivate(baseUrl))
+{
+}
+
+/*!
+    Destroys this QNetworkRequestFactory object.
+ */
+QNetworkRequestFactory::~QNetworkRequestFactory()
+    = default;
+
+/*!
+    Creates a copy of \a other.
+ */
+QNetworkRequestFactory::QNetworkRequestFactory(const QNetworkRequestFactory &other)
+    = default;
+
+/*!
+    Creates a copy of \a other and returns a reference to this factory.
+ */
+QNetworkRequestFactory &QNetworkRequestFactory::operator=(const QNetworkRequestFactory &other)
+    = default;
+
+/*!
+    \fn QNetworkRequestFactory::QNetworkRequestFactory(QNetworkRequestFactory &&other) noexcept
+
+    Move-constructs the factory from \a other.
+
+    \note The moved-from object \a other is placed in a
+    partially-formed state, in which the only valid operations are
+    destruction and assignment of a new value.
+*/
+
+/*!
+    \fn QNetworkRequestFactory &QNetworkRequestFactory::operator=(QNetworkRequestFactory &&other) noexcept
+
+    Move-assigns \a other and returns a reference to this factory.
+
+    \note The moved-from object \a other is placed in a
+    partially-formed state, in which the only valid operations are
+    destruction and assignment of a new value.
+ */
+
+/*!
+    \fn void QNetworkRequestFactory::swap(QNetworkRequestFactory &other)
+
+    Swaps this factory with \a other. This operation is
+    very fast and never fails.
+ */
+
+/*!
+    \fn bool QNetworkRequestFactory::operator==(const QNetworkRequestFactory &lhs,
+                                              const QNetworkRequestFactory &rhs)
+
+    Returns \c true if \a lhs is considered equal with \a rhs, meaning
+    that all data in the factories match, otherwise returns \c false.
+
+    \note The headers comparison is order-insensitive.
+
+    \sa QNetworkRequestFactory::operator!=()
+ */
+
+/*!
+    \fn bool QNetworkRequestFactory::operator!=(const QNetworkRequestFactory &lhs,
+                                              const QNetworkRequestFactory &rhs)
+
+    Returns \c true if \a lhs is not considered equal with \a rhs.
+
+    \sa QNetworkRequestFactory::operator==()
+ */
+
+/*!
+    \internal
+ */
+bool comparesEqual(const QNetworkRequestFactory &lhs, const QNetworkRequestFactory &rhs) noexcept
+{
+    return lhs.d == rhs.d || lhs.d->equals(*rhs.d);
+}
+
+/*!
+    Returns the base URL used for the individual requests.
+
+    The base URL may contain a path component. This path is used
+    as path "prefix" for the paths that are provided when generating
+    individual requests.
+
+    \sa setBaseUrl()
+ */
+QUrl QNetworkRequestFactory::baseUrl() const
+{
+    return d->baseUrl;
+}
+
+/*!
+    Sets the base URL used in individual requests to \a url.
+
+    \sa baseUrl()
+ */
+void QNetworkRequestFactory::setBaseUrl(const QUrl &url)
+{
+    if (d->baseUrl == url)
+        return;
+
+    d.detach();
+    d->baseUrl = url;
+}
+
+#if QT_CONFIG(ssl)
+/*!
+    Returns the SSL configuration set to this factory. The SSL configuration
+    is set to each individual request.
+
+    \sa setSslConfiguration()
+ */
+QSslConfiguration QNetworkRequestFactory::sslConfiguration() const
+{
+    return d->sslConfig;
+}
+
+/*!
+    Sets the SSL configuration to \a configuration.
+
+    \sa sslConfiguration()
+ */
+void QNetworkRequestFactory::setSslConfiguration(const QSslConfiguration &configuration)
+{
+    if (d->sslConfig == configuration)
+        return;
+
+    d.detach();
+    d->sslConfig = configuration;
+}
+#endif
+
+/*!
+    Returns a QNetworkRequest.
+
+    The returned request is filled with the data that this factory
+    has been configured with.
+
+    \sa request(const QUrlQuery&), request(const QString&, const QUrlQuery&)
+*/
+
+QNetworkRequest QNetworkRequestFactory::request() const
+{
+    return d->newRequest(d->requestUrl());
+}
+
+/*!
+    Returns a QNetworkRequest.
+
+    The returned request's URL is formed by appending the provided \a path
+    to the baseUrl (which may itself have a path component).
+
+    \sa request(const QString &, const QUrlQuery &), request(), baseUrl()
+*/
+QNetworkRequest QNetworkRequestFactory::request(const QString &path) const
+{
+    return d->newRequest(d->requestUrl(&path));
+}
+
+/*!
+    Returns a QNetworkRequest.
+
+    The returned request's URL is formed by appending the provided \a query
+    to the baseUrl.
+
+    \sa request(const QString &, const QUrlQuery &), request(), baseUrl()
+*/
+QNetworkRequest QNetworkRequestFactory::request(const QUrlQuery &query) const
+{
+    return d->newRequest(d->requestUrl(nullptr, &query));
+}
+
+/*!
+    Returns a QNetworkRequest.
+
+    The returned request's URL is formed by appending the provided \a path
+    and \a query to the baseUrl (which may itself have a path component).
+
+    If the provided \a path contains query items, they will be combined
+    with the items in \a query.
+
+    \sa request(const QUrlQuery&), request(), baseUrl()
+ */
+QNetworkRequest QNetworkRequestFactory::request(const QString &path, const QUrlQuery &query) const
+{
+    return d->newRequest(d->requestUrl(&path, &query));
+}
+
+/*!
+    Sets the headers to \a headers.
+
+    These headers are added to individual requests' headers.
+    This is a convenience mechanism for setting headers that
+    repeat across requests.
+
+    \sa headers(), clearHeaders()
+ */
+void QNetworkRequestFactory::setHeaders(const QHttpHeaders &headers)
+{
+    d.detach();
+    d->headers = headers;
+}
+
+/*!
+    Returns the currently set headers.
+
+    \sa setHeaders(), clearHeaders()
+ */
+QHttpHeaders QNetworkRequestFactory::headers() const
+{
+    return d->headers;
+}
+
+/*!
+    Clears current headers.
+
+    \sa headers(), setHeaders()
+*/
+void QNetworkRequestFactory::clearHeaders()
+{
+    if (d->headers.isEmpty())
+        return;
+    d.detach();
+    d->headers.clear();
+}
+
+/*!
+    Returns the bearer token that has been set.
+
+    The bearer token, if present, is used to set the
+    \c {Authorization: Bearer my_token} header for requests. This is a common
+    authorization convention and provided as an additional convenience.
+
+    Means to acquire the bearer token varies. Common methods include \c OAuth2
+    and the service provider's website/dashboard. It's common that the bearer
+    token changes over time, for example when updated with a refresh token.
+    By always re-setting the new token ensures that subsequent requests will
+    always have the latest, valid, token.
+
+    The presence of the bearer token does not impact the \l headers()
+    listing. If the \l headers() also lists \c Authorization header, it
+    will be overwritten.
+
+    \sa setBearerToken(), headers()
+ */
+QByteArray QNetworkRequestFactory::bearerToken() const
+{
+    return d->bearerToken;
+}
+
+/*!
+    Sets the bearer token to \a token.
+
+    \sa bearerToken(), clearBearerToken()
+*/
+void QNetworkRequestFactory::setBearerToken(const QByteArray &token)
+{
+    if (d->bearerToken == token)
+        return;
+
+    d.detach();
+    d->bearerToken = token;
+}
+
+/*!
+    Clears the bearer token.
+
+    \sa bearerToken()
+*/
+void QNetworkRequestFactory::clearBearerToken()
+{
+    if (d->bearerToken.isEmpty())
+        return;
+
+    d.detach();
+    d->bearerToken.clear();
+}
+
+/*!
+    Returns query parameters that are added to individual requests' query
+    parameters. The query parameters are added to any potential query
+    parameters provided with the individual \l request() calls.
+
+    Use cases for using repeating query parameters are server dependent,
+    but typical examples include language setting \c {?lang=en}, format
+    specification \c {?format=json}, API version specification
+    \c {?version=1.0} and API key authentication.
+
+    \sa setQueryParameters(), clearQueryParameters(), request()
+*/
+QUrlQuery QNetworkRequestFactory::queryParameters() const
+{
+    return d->queryParameters;
+}
+
+/*!
+    Sets \a query parameters that are added to individual requests' query
+    parameters.
+
+    \sa queryParameters(), clearQueryParameters()
+ */
+void QNetworkRequestFactory::setQueryParameters(const QUrlQuery &query)
+{
+    if (d->queryParameters == query)
+        return;
+
+    d.detach();
+    d->queryParameters = query;
+}
+
+/*!
+    Clears the query parameters.
+
+    \sa queryParameters()
+*/
+void QNetworkRequestFactory::clearQueryParameters()
+{
+    if (d->queryParameters.isEmpty())
+        return;
+
+    d.detach();
+    d->queryParameters.clear();
+}
+
+QNetworkRequestFactoryPrivate::QNetworkRequestFactoryPrivate()
+    = default;
+
+QNetworkRequestFactoryPrivate::QNetworkRequestFactoryPrivate(const QUrl &baseUrl)
+    : baseUrl(baseUrl)
+{
+}
+
+QNetworkRequestFactoryPrivate::~QNetworkRequestFactoryPrivate()
+    = default;
+
+QNetworkRequest QNetworkRequestFactoryPrivate::newRequest(const QUrl &url) const
+{
+    QNetworkRequest request;
+    request.setUrl(url);
+#if QT_CONFIG(ssl)
+    if (!sslConfig.isNull())
+        request.setSslConfiguration(sslConfig);
+#endif
+    // Set the header entries to the request. Combine values as there
+    // may be multiple values per name. Note: this would not necessarily
+    // produce right result for 'Set-Cookie' header if it has multiple values,
+    // but since it is a purely server-side (response) header, not relevant here.
+    const auto headerNames = headers.names();
+    for (const auto &name : headerNames)
+        request.setRawHeader(name, headers.combinedValue(name));
+
+    constexpr char Bearer[] = "Bearer ";
+    if (!bearerToken.isEmpty())
+        request.setRawHeader("Authorization"_ba, Bearer + bearerToken);
+
+    return request;
+}
+
+QUrl QNetworkRequestFactoryPrivate::requestUrl(const QString *path,
+                                             const QUrlQuery *query) const
+{
+    const QUrl providedPath = path ? QUrl(*path) : QUrl{};
+    const QUrlQuery providedQuery = query ? *query : QUrlQuery();
+
+    if (!providedPath.scheme().isEmpty() || !providedPath.host().isEmpty()) {
+        qCWarning(lcQrequestfactory, "The provided path %ls may only contain path and query item "
+                  "components, and other parts will be ignored. Set the baseUrl instead",
+                  qUtf16Printable(providedPath.toDisplayString()));
+    }
+
+    QUrl resultUrl = baseUrl;
+    QUrlQuery resultQuery(providedQuery);
+    QString basePath = baseUrl.path();
+    // Separate the path and query parameters components on the application-provided path
+    const QString requestPath{providedPath.path()};
+    const QUrlQuery pathQueryItems{providedPath};
+
+    if (!pathQueryItems.isEmpty()) {
+        // Add any query items provided as part of the path
+        const auto items = pathQueryItems.queryItems(QUrl::ComponentFormattingOption::FullyEncoded);
+        for (const auto &[key, value]: items)
+            resultQuery.addQueryItem(key, value);
+    }
+
+    if (!queryParameters.isEmpty()) {
+        // Add any query items set to this factory
+        const QList<std::pair<QString,QString>> items =
+                queryParameters.queryItems(QUrl::ComponentFormattingOption::FullyEncoded);
+        for (const auto &item: items)
+            resultQuery.addQueryItem(item.first, item.second);
+    }
+
+    if (!resultQuery.isEmpty())
+        resultUrl.setQuery(resultQuery);
+
+    if (requestPath.isEmpty())
+        return resultUrl;
+
+    // Ensure that the "base path" (the path that may be present
+    // in the baseUrl), and the request path are joined with one '/'
+    // If both have it, remove one, if neither has it, add one
+    if (basePath.endsWith(u'/') && requestPath.startsWith(u'/'))
+        basePath.chop(1);
+    else if (!requestPath.startsWith(u'/') && !basePath.endsWith(u'/'))
+        basePath.append(u'/');
+
+    resultUrl.setPath(basePath.append(requestPath));
+    return resultUrl;
+}
+
+bool QNetworkRequestFactoryPrivate::equals(
+        const QNetworkRequestFactoryPrivate &other) const noexcept
+{
+    return
+#if QT_CONFIG(ssl)
+            sslConfig == other.sslConfig &&
+#endif
+            baseUrl == other.baseUrl &&
+            bearerToken == other.bearerToken &&
+            headers.equals(other.headers) &&
+            queryParameters == other.queryParameters;
+}
+
+QT_END_NAMESPACE
diff --git a/src/network/access/qnetworkrequestfactory.h b/src/network/access/qnetworkrequestfactory.h
new file mode 100644
index 0000000000..901a61decc
--- /dev/null
+++ b/src/network/access/qnetworkrequestfactory.h
@@ -0,0 +1,75 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
+
+#ifndef QNETWORKREQUESTFACTORY_H
+#define QNETWORKREQUESTFACTORY_H
+
+#include <QtNetwork/qnetworkrequest.h>
+#include <QtNetwork/qhttpheaders.h>
+
+#include <QtCore/qcompare.h>
+#include <QtCore/qshareddata.h>
+#include <QtCore/qurlquery.h>
+#include <QtCore/qurl.h>
+
+QT_BEGIN_NAMESPACE
+
+#if QT_CONFIG(ssl)
+class QSslConfiguration;
+#endif
+
+class QNetworkRequestFactoryPrivate;
+QT_DECLARE_QESDP_SPECIALIZATION_DTOR_WITH_EXPORT(QNetworkRequestFactoryPrivate, Q_NETWORK_EXPORT)
+
+class QNetworkRequestFactory
+{
+public:
+    Q_NETWORK_EXPORT QNetworkRequestFactory();
+    Q_NETWORK_EXPORT explicit QNetworkRequestFactory(const QUrl &baseUrl);
+    Q_NETWORK_EXPORT ~QNetworkRequestFactory();
+
+    Q_NETWORK_EXPORT QNetworkRequestFactory(const QNetworkRequestFactory &other);
+    QNetworkRequestFactory(QNetworkRequestFactory &&other) noexcept = default;
+    Q_NETWORK_EXPORT QNetworkRequestFactory &operator=(const QNetworkRequestFactory &other);
+
+    QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_PURE_SWAP(QNetworkRequestFactory)
+    void swap(QNetworkRequestFactory &other) noexcept { d.swap(other.d); }
+
+    Q_NETWORK_EXPORT QUrl baseUrl() const;
+    Q_NETWORK_EXPORT void setBaseUrl(const QUrl &url);
+
+#if QT_CONFIG(ssl)
+    Q_NETWORK_EXPORT QSslConfiguration sslConfiguration() const;
+    Q_NETWORK_EXPORT void setSslConfiguration(const QSslConfiguration &configuration);
+#endif
+
+    Q_NETWORK_EXPORT QNetworkRequest request() const;
+    Q_NETWORK_EXPORT QNetworkRequest request(const QUrlQuery &query) const;
+    Q_NETWORK_EXPORT QNetworkRequest request(const QString &path) const;
+    Q_NETWORK_EXPORT QNetworkRequest request(const QString &path, const QUrlQuery &query) const;
+
+    Q_NETWORK_EXPORT void setHeaders(const QHttpHeaders &headers);
+    Q_NETWORK_EXPORT QHttpHeaders headers() const;
+    Q_NETWORK_EXPORT void clearHeaders();
+
+    Q_NETWORK_EXPORT QByteArray bearerToken() const;
+    Q_NETWORK_EXPORT void setBearerToken(const QByteArray &token);
+    Q_NETWORK_EXPORT void clearBearerToken();
+
+    Q_NETWORK_EXPORT QUrlQuery queryParameters() const;
+    Q_NETWORK_EXPORT void setQueryParameters(const QUrlQuery &query);
+    Q_NETWORK_EXPORT void clearQueryParameters();
+
+private:
+    friend Q_NETWORK_EXPORT bool comparesEqual(const QNetworkRequestFactory &lhs,
+                                               const QNetworkRequestFactory &rhs) noexcept;
+    Q_DECLARE_EQUALITY_COMPARABLE(QNetworkRequestFactory)
+
+    QExplicitlySharedDataPointer<QNetworkRequestFactoryPrivate> d;
+};
+
+Q_DECLARE_SHARED(QNetworkRequestFactory)
+
+QT_END_NAMESPACE
+
+#endif // QNETWORKREQUESTFACTORY_H
diff --git a/src/network/access/qnetworkrequestfactory_p.h b/src/network/access/qnetworkrequestfactory_p.h
new file mode 100644
index 0000000000..d90d83361b
--- /dev/null
+++ b/src/network/access/qnetworkrequestfactory_p.h
@@ -0,0 +1,50 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
+
+#ifndef QNETWORKREQUESTFACTORY_P_H
+#define QNETWORKREQUESTFACTORY_P_H
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is not part of the Qt API.  It exists for the convenience
+// of the Network Access framework.  This header file may change from
+// version to version without notice, or even be removed.
+//
+// We mean it.
+//
+
+#include <QtNetwork/qhttpheaders.h>
+#include <QtNetwork/qnetworkrequest.h>
+#if QT_CONFIG(ssl)
+#include <QtNetwork/qsslconfiguration.h>
+#endif
+#include <QtCore/qshareddata.h>
+#include <QtCore/qurl.h>
+#include <QtCore/qurlquery.h>
+
+QT_BEGIN_NAMESPACE
+
+class QNetworkRequestFactoryPrivate : public QSharedData
+{
+public:
+    QNetworkRequestFactoryPrivate();
+    explicit QNetworkRequestFactoryPrivate(const QUrl &baseUrl);
+    ~QNetworkRequestFactoryPrivate();
+    QNetworkRequest newRequest(const QUrl &url) const;
+    QUrl requestUrl(const QString *path = nullptr, const QUrlQuery *query = nullptr) const;
+    bool equals(const QNetworkRequestFactoryPrivate &other) const noexcept;
+
+#if QT_CONFIG(ssl)
+    QSslConfiguration sslConfig;
+#endif
+    QUrl baseUrl;
+    QHttpHeaders headers;
+    QByteArray bearerToken;
+    QUrlQuery queryParameters;
+};
+
+QT_END_NAMESPACE
+
+#endif // QNETWORKREQUESTFACTORY_P_H