BaseJob: Enable client-side QNetworkRequest adjustments

This may be useful for things like
matrix-org/matrix-spec-proposals#3860.

Quotient/jobs/basejob.cpp

@@ -91,7 +91,9 @@ class Q_DECL_HIDDEN BaseJob::Private {
         }
     }
 
-    void sendRequest();
+    QNetworkRequest prepareRequest();
+    void sendRequest(const QNetworkRequest& req);
+
     /*! \brief Parse the response byte array into JSON
      *
      * This calls QJsonDocument::fromJson() on rawResponse, converts
@@ -284,10 +286,10 @@ QUrl BaseJob::makeRequestUrl(QUrl baseUrl, const QByteArray& encodedPath,
     return baseUrl;
 }
 
-void BaseJob::Private::sendRequest()
+QNetworkRequest BaseJob::Private::prepareRequest()
 {
-    QNetworkRequest req { makeRequestUrl(connection->baseUrl(), apiEndpoint,
-                                         requestQuery) };
+    QNetworkRequest req{ makeRequestUrl(connection->baseUrl(), apiEndpoint,
+                                        requestQuery) };
     if (!requestHeaders.contains("Content-Type"))
         req.setHeader(QNetworkRequest::ContentTypeHeader, "application/json"_ls);
     if (needsToken)
@@ -305,7 +307,11 @@ void BaseJob::Private::sendRequest()
     Q_ASSERT(req.url().isValid());
     for (auto it = requestHeaders.cbegin(); it != requestHeaders.cend(); ++it)
         req.setRawHeader(it.key(), it.value());
+    return req;
+}
 
+void BaseJob::Private::sendRequest(const QNetworkRequest& req)
+{
     switch (verb) {
     case HttpVerb::Get:
         reply = connection->nam()->get(req);
@@ -369,8 +375,9 @@ void BaseJob::sendRequest()
     }
     Q_ASSERT(d->connection && status().code == Pending);
     d->needsToken |= d->connection->needsToken(objectName());
-    emit aboutToSendRequest();
-    d->sendRequest();
+    auto req = d->prepareRequest();
+    emit aboutToSendRequest(&req);
+    d->sendRequest(req);
     Q_ASSERT(d->reply);
     connect(reply(), &QNetworkReply::finished, this, [this] {
         gotReply();

Quotient/jobs/basejob.h

@@ -12,6 +12,7 @@
 #include <QtCore/QObject>
 #include <QtCore/QStringBuilder>
 
+class QNetworkRequest;
 class QNetworkReply;
 class QSslError;
 
@@ -260,8 +261,19 @@ public Q_SLOTS:
     void abandon();
 
 Q_SIGNALS:
-    /** The job is about to send a network request */
-    void aboutToSendRequest();
+    //! \brief The job is about to send a network request
+    //!
+    //! This signal is emitted every time a network request is made (which can
+    //! occur several times due to job retries). You can use it to change
+    //! the request parameters (such as redirect policy) if necessary. If you
+    //! need to set additional request headers or query items, do that using
+    //! setRequestHeaders() and setRequestQuery() instead.
+    //! \note \p req is not guaranteed to exist (i.e. it may point to garbage)
+    //!       unless this signal is handled via a DirectConnection (or
+    //!       BlockingQueuedConnection if in another thread), i.e.,
+    //!       synchronously.
+    //! \sa setRequestHeaders, setRequestQuery
+    void aboutToSendRequest(QNetworkRequest* req);
 
     /** The job has sent a network request */
     void sentRequest();