Clavem

Check for updates and download installers from a JUCE plugin

Request GET /v1/releases/:productId/latest on a background thread with the key in an X-License-Key header, compare the version, and fetch the signed download link when the user clicks. A host that has your plugin loaded cannot be updated in place, so download an installer and ask the user to quit.

What the endpoint returns

The releases endpoint gives the most recently published release, which is not always the highest version number. With a valid license key for this product, the answer also carries release notes and a signed download url on each file. Without one, it holds only version and published_at: you can still say an update exists.

I ran the code below against a local mock of the documented answers. The live demo product has no release published, and answers 404 with not_found and the message “This product has no published release yet.”

Call Result in the test
Valid key status 200, version 3.10.0, notes, one file with a URL, entitled true
Wrong key status 200, version only, no notes, entitled false
Nothing published status 404, treated as no update
Rate limited status 429, treated as no update

The request carried platform=macos and the X-License-Key header, and no license_key in the URL. The update endpoint has its own budget of 120 requests per minute per IP address, separate from validation.

Check for an update

Call this from a background thread, at most once a day, and store the time of the last check in the license file. X-License-Key goes in extra headers, which JUCE wants as complete header lines ending in CRLF.

struct UpdateInfo
{
    juce::String version, notes;
    juce::URL download;      // empty without a valid license
    bool entitled = false;
};

inline juce::String platformLabel()   // the label you typed when uploading; Clavem does not fix the list
{
   #if JUCE_MAC
    return "macos";
   #elif JUCE_WINDOWS
    return "windows";
   #else
    return "linux";
   #endif
}

inline std::optional<UpdateInfo> latestRelease (const LicenseClient& client, const juce::String& licenseKey)
{
    const auto url = juce::URL (client.base + "/v1/releases/" + juce::String (client.productId) + "/latest")
                         .withParameter ("platform", platformLabel());
    int status = 0;

    auto stream = url.createInputStream (juce::URL::InputStreamOptions (juce::URL::ParameterHandling::inAddress)
                                             .withExtraHeaders ("X-License-Key: " + licenseKey + "\r\n")
                                             .withConnectionTimeoutMs (4000)
                                             .withStatusCode (&status));

    if (stream == nullptr || status != 200)   // 404: nothing published. 429: wait Retry-After.
        return std::nullopt;

    const auto json = juce::JSON::parse (stream->readEntireStreamAsString());
    UpdateInfo info;
    info.version = json["version"].toString();
    info.notes   = json["notes"].toString();   // plain text, absent without a valid license

    if (auto* files = json["files"].getArray(); files != nullptr && ! files->isEmpty())
    {
        info.download = juce::URL ((*files)[0]["url"].toString());   // signed, valid for one hour
        info.entitled = info.download.isWellFormed();
    }
    return info;
}

Show notes in a read-only TextEditor: release notes are plain text, up to 20,000 characters. When entitled is false, show the version and a renew prompt instead of a dead button.

Compare versions

JUCE gives you String::compareNatural, which orders 3.10.0 after 3.9.2 but puts 4.0.0 before 4.0.0-beta.2, because the shorter string sorts first. This function reads dotted numbers and treats a pre-release tail as older:

inline bool isNewer (const juce::String& a, const juce::String& b)
{
    auto parse = [] (const juce::String& v, bool& preRelease)
    {
        preRelease = v.containsChar ('-');
        juce::StringArray parts;
        parts.addTokens (v.upToFirstOccurrenceOf ("-", false, false).upToFirstOccurrenceOf ("+", false, false), ".", "");
        while (parts.size() < 3) parts.add ("0");
        return parts;
    };

    bool preA = false, preB = false;
    const auto pa = parse (a, preA), pb = parse (b, preB);

    for (int i = 0; i < 3; ++i)
        if (pa[i].getIntValue() != pb[i].getIntValue())
            return pa[i].getIntValue() > pb[i].getIntValue();

    return preB && ! preA;   // 4.0.0 is newer than 4.0.0-beta.2
}

In the run, 3.10.0 was newer than 3.9.2, 4.0.0 newer than 4.0.0-beta.2, equal versions were not newer, and banana against 1.0.0 was not newer. Two different pre-release tags count as equal; use a SemVer library if you ship betas side by side.

Download when the user clicks

Links last one hour, so call latestRelease again on click and use the fresh url. JUCE’s DownloadTask reports back on an arbitrary thread, so hop to the message thread before touching a component.

struct InstallerDownload : juce::URL::DownloadTaskListener
{
    void finished (juce::URL::DownloadTask* task, bool success) override
    {
        const auto code = task->statusCode();    // 403 means the link expired
        juce::MessageManager::callAsync ([success, code] { /* show the result, then start the installer */ });
    }
};

// task = info.download.downloadToFile (target, juce::URL::DownloadTaskOptions().withListener (&listener));

In the run that downloaded the 300,000-byte test file with status 200 and a progress callback. For big installers use a resumable version built on createInputStream:

inline bool resumeDownload (const juce::URL& url, const juce::File& part)
{
    const auto have = part.getSize();
    int status = 0;
    auto in = url.createInputStream (juce::URL::InputStreamOptions (juce::URL::ParameterHandling::inAddress)
                                         .withExtraHeaders ("Range: bytes=" + juce::String (have) + "-\r\n")
                                         .withStatusCode (&status));
    if (in == nullptr || (status != 206 && status != 200))   // 403: the link expired
        return false;

    juce::FileOutputStream out (part);
    if (out.failedToOpen())
        return false;

    if (status == 206) out.setPosition (have);               // the server honoured Range: append
    else { out.setPosition (0); out.truncate(); }            // it sent the whole file: start over

    out.writeFromInputStream (*in, -1);
    out.flush();
    return out.getStatus().wasOk();
}

With a 100,000-byte part file the server answered 206 and the file ended at 300,000 bytes. From an empty file it also completed. An expired link answered 403, and JUCE still handed back a stream with that status.

Applying the update in a plugin

A DAW keeps your plugin binary loaded, so a plugin cannot safely overwrite itself. Download the installer, start it with File::startAsProcess(), and tell the user to close the host so it can finish. Use one platform label per installer: a macOS .pkg or .dmg for all formats, a Windows .exe, a Linux archive. Each file can be up to 5 GiB. Clavem has no auto-updater and no delta updates, and I found no checksum field in the release response, so publish a hash yourself if you want installers verified.

Doing this with Clavem

You upload each installer in the dashboard with a version and a platform label, then publish it. Limits, storage per plan and the one-hour link rule are in the files docs.

Questions

Does URL::downloadToFile resume an interrupted download?

The documented DownloadTask exposes progress, status and errors but no resume. Use createInputStream with a Range header and append to a part file, as below. Clavem's downloads support byte ranges.

Can the plugin replace itself while the DAW is open?

Not reliably. The host has the plugin binary loaded, so download an installer, start it, and ask the user to close the host so the installer can finish.

Sources

  1. JUCE documentation, juce::URL::InputStreamOptions (checked November 2026)
  2. JUCE documentation, juce::URL (checked November 2026)