Clavem

Software update checks and downloads in a Qt app

GET /v1/releases/<product id>/latest with the key in an X-License-Key header, compare versions with QVersionNumber and a pre-release check of your own, and stream the installer to a .part file with a Range header. Request the link when the customer clicks, because it lasts one hour.

Clavem stores your builds and answers GET /v1/releases/:productId/latest. A license that is valid for the product gets release notes and files with signed download links. Any other key gets only version and published_at. The release docs list the fields. This page is the Qt side: the check, the version comparison, a download that resumes, and the install step. It reuses the LicenseClient pattern from license key validation in Qt. The Qt code was not compiled or run, because no Qt installation was available.

Check

#include <QJsonArray>
#include <QJsonDocument>
#include <QNetworkAccessManager>
#include <QNetworkReply>
#include <QVersionNumber>

struct ReleaseFile { qint64 id = 0; QString filename; qint64 size = 0; QUrl url; };
struct UpdateInfo {
  enum class State { UpToDate, Available, Locked, Failed } state = State::Failed;
  QString version, notes, reason;
  ReleaseFile file;
};

/// -1, 0 or 1. QVersionNumber ignores a pre-release suffix, so rank it here: 3.2.1-beta.1 is below 3.2.1.
static int compareVersions(const QString& a, const QString& b) {
  qsizetype ia = 0, ib = 0;
  const QVersionNumber va = QVersionNumber::fromString(a, &ia), vb = QVersionNumber::fromString(b, &ib);
  if (int c = QVersionNumber::compare(va, vb)) return c;
  const bool preA = ia < a.size(), preB = ib < b.size();   // a suffix follows the numbers
  return preA == preB ? 0 : (preA ? -1 : 1);
}

void Updater::check(const QString& licenseKey, const QString& currentVersion) {
  QUrl url(m_base.resolved(QUrl(QString("/v1/releases/%1/latest").arg(m_productId))));
  url.setQuery(QUrlQuery{{"platform", platformLabel()}});
  QNetworkRequest request(url);
  if (!licenseKey.isEmpty()) request.setRawHeader("X-License-Key", licenseKey.toUtf8());   // a header keeps it out of logs
  request.setTransferTimeout(std::chrono::seconds(8));

  QNetworkReply* reply = m_nam.get(request);
  connect(reply, &QNetworkReply::finished, this, [this, reply, currentVersion] {
    reply->deleteLater();
    const int status = reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();
    UpdateInfo info;
    if (status == 0) { info.reason = "offline"; return emit checked(info); }
    if (status == 404) { info.state = UpdateInfo::State::UpToDate; return emit checked(info); }   // nothing published yet
    if (status != 200) { info.reason = status == 429 ? "rate limited, retry in a minute" : QString("HTTP %1").arg(status); return emit checked(info); }

    const QJsonObject release = QJsonDocument::fromJson(reply->readAll()).object();
    info.version = release["version"].toString();
    if (compareVersions(info.version, currentVersion) <= 0) { info.state = UpdateInfo::State::UpToDate; return emit checked(info); }
    for (const QJsonValue& v : release["files"].toArray()) {
      const QJsonObject f = v.toObject();
      if (f["url"].isString()) {
        info.state = UpdateInfo::State::Available;
        info.notes = release["notes"].toString();
        info.file = {f["id"].toInteger(), f["filename"].toString(), f["size"].toInteger(), QUrl(f["url"].toString())};
        return emit checked(info);
      }
    }
    info.state = UpdateInfo::State::Locked;      // newer, but the key is missing or not valid: only the version came back
    emit checked(info);
  });
}

QString platformLabel() {   // the label you chose at upload, for example darwin-arm64, winnt-x86_64 or linux-x86_64
  return QSysInfo::kernelType() + "-" + QSysInfo::currentCpuArchitecture();
}

QVersionNumber::fromString returns the index where the numbers end. The documentation lists the suffixIndex parameter for this. A pre-release suffix such as -beta.1 starts there, so the helper ranks a suffixed version below the same release. Locked is the useful middle case: a lapsed customer learns that a newer version exists and can be sent to renew.

The label has to match what you used at upload. If the app asks for darwin-arm64 and your files are labelled macos, you receive only the files with no label. Build the label from kernelType() and not from productType(), which on Linux returns the distribution name and would give you a different label per distro.

Download, resume and progress

Ask for the link when the customer clicks Update, by calling check again, and download from that fresh response. This streams to a .part file, resumes with Range, and renames only when the size matches:

void Updater::download(const ReleaseFile& file, const QString& destination) {
  auto* part = new QFile(destination + ".part", this);
  qint64 have = part->exists() ? part->size() : 0;
  if (have > file.size) { part->remove(); have = 0; }
  if (have == file.size) return finish(part, file, destination);

  QNetworkRequest request(file.url);
  if (have > 0) request.setRawHeader("Range", QByteArray("bytes=") + QByteArray::number(have) + "-");
  QNetworkReply* reply = m_nam.get(request);
  auto opened = std::make_shared<bool>(false);

  connect(reply, &QNetworkReply::readyRead, this, [=] {
    if (!*opened) {   // first bytes: the status is known
      const int status = reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();
      if (status != 200 && status != 206) { reply->abort(); return; }
      const bool append = status == 206;        // 200 means the server ignored Range: start over
      if (!part->open(append ? QIODevice::Append : QIODevice::WriteOnly)) { reply->abort(); return; }
      *opened = true;
    }
    part->write(reply->readAll());
  });
  connect(reply, &QNetworkReply::downloadProgress, this, [=](qint64 received, qint64 total) {
    if (total > 0) emit progress(int((have + received) * 100 / (have + total)));   // total counts only what is left
  });
  connect(reply, &QNetworkReply::finished, this, [=] {
    reply->deleteLater();
    const int status = reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();
    part->close();
    if (status == 403) return emit failed("The download link expired. Check for updates again.");
    if (reply->error() != QNetworkReply::NoError) return emit failed(reply->errorString());
    finish(part, file, destination);
  });
}

void Updater::finish(QFile* part, const ReleaseFile& file, const QString& destination) {
  if (part->size() != file.size) return emit failed("Size does not match. Keep the .part file and resume.");
  QFile::remove(destination);                    // QFile::rename does not overwrite
  if (!part->rename(destination)) return emit failed(part->errorString());
  emit downloaded(destination);
}

The response has no checksum field, so size is the only integrity check the API gives. Sign your installers, and let the operating system check the signature. On a resumed request downloadProgress reports the bytes of the partial response, not of the whole file, so the code adds what was already on disk. Test the percentage on a resumed download before you trust it.

Install

  • macOS. QDesktopServices::openUrl(QUrl::fromLocalFile(path)) opens the DMG, and the customer drags the new app over the old one.
  • Windows. A running executable cannot be overwritten. Start the installer with QProcess::startDetached and call QCoreApplication::quit().
  • Linux. Replace an AppImage and call QFile::setPermissions to add the execute bits. For a package, hand it to the package manager.

Limits and timing

The releases endpoint allows 120 requests a minute per IP address, counted apart from validation. Check once at launch or once a day. “Latest” is the most recently published release, not the highest version number: a backport published after 3.2.1 becomes the answer, so a customer on 3.2.1 sees nothing newer.

Doing this with Clavem

Upload each installer in the dashboard, give it a platform label and publish. The same key that turns the app on fetches the download, and licenses imported from Lemon Squeezy, which have no order page, get their builds through this endpoint. See the release docs for limits.

Questions

How do I compare version strings in Qt?

Use QVersionNumber::fromString and compare the results. It reads 3.10.0 as above 3.9.0. It does not rank pre-release suffixes, so 3.2.1-beta.1 and 3.2.1 compare equal. Read the suffix index it returns and handle that case yourself.

Can I show download progress in Qt?

Connect to QNetworkReply::downloadProgress, which reports bytes received and the total. For a resumed download the numbers describe the partial response, so add the bytes you already had.

Can a Qt program replace itself while it runs?

Not reliably on Windows, where a running executable cannot be overwritten. Download the installer, start it with QProcess::startDetached, and quit. On macOS, open the disk image. On Linux, replace an AppImage and mark it executable.

Sources

  1. Qt 6, QVersionNumber (checked November 2026)