Skip to content
demuddler

Versions and upgrades

Learn how the npm package and the hosted runtime are versioned, how to pin a runtime version and how to test an upgrade.

The importer has two parts: the npm package in your application and the runtime in its frame. Each package release opens the runtime version that we released it with. So the runtime changes only when you upgrade the package or change runtimeUrl.

The current runtime version is 0.4.0. The runtime changelog lists each version.

Version What it controls
npm package Properties, React props, methods, events, TypeScript types and the default runtime version.
Runtime version, such as 0.4.0 The interface and the engine that read the files.
Runtime URL, such as https://runtime.demuddler.com/version/0.4.0 The runtime version that the importer opens. The package sets it, and runtimeUrl can change it.

If the package and the runtime cannot work together, the loader sends an error event and sends no file to the frame.

Without runtimeUrl, the importer opens https://runtime.demuddler.com/version/<version>. <version> is the runtime version of your package. element.runtimeUrl returns the URL. The content at a runtime URL never changes, and an unknown version returns 404.

The response for the frame document also names the version. Open the Network panel of your browser and look at these headers:

X-Demuddler-Runtime-Version: 0.4.0
X-Demuddler-Release: <SHA-256 build digest>

The second header identifies the exact build. Neither header contains customer data.

To open a different runtime version, set runtimeUrl to https://runtime.demuddler.com/version/<version>. Use the full version, with any pre-release label. The runtime changelog lists each version.

<demuddler-importer runtime-url="https://runtime.demuddler.com/version/0.4.0"></demuddler-importer>

In React, pass the same URL as runtimeUrl. You can use it to take a runtime fix before you upgrade the package, or to keep a runtime version when you upgrade the package. After you set it, a package upgrade does not change your runtime. You must change the URL yourself.

The loader opens only a version of the hosted runtime. Any other address, or a URL with a query or a fragment, throws a TypeError. For development, it also accepts the same path over http on localhost, 127.0.0.1 or [::1].

A runtime version never gets fixes, including security fixes. A fix is a new runtime version. To get it, test the new version as in Upgrade your integration. Then upgrade the package or change runtimeUrl.

Each path of a withdrawn runtime version answers 410 Gone with the reason, in this form: Gone: runtime <version> is withdrawn. <reason>. A new importer with that runtime URL cannot start. After 20 seconds, the loader sends an error event with the loader.notConnected message. An importer that is already open keeps working until it closes. This also applies when the withdrawn version is the default of your package.

To recover, upgrade the package to a release that opens the fixed version, or set runtimeUrl to the fixed version.

Each release publishes a manifest at https://runtime.demuddler.com/version/<version>/manifest.json. It holds the SHA-256 digests of the runtime HTML (htmlDigest), the third-party notices (noticesDigest) and each file (files). The X-Demuddler-Release header is the digest of the manifest without its id field.

Terminal window
version=0.4.0
base=https://runtime.demuddler.com/version/$version
curl -s "$base/manifest.json" > manifest.json
# The HTML digest must equal htmlDigest in manifest.json.
curl -s "$base" | sha256sum
# Each asset digest must equal its entry in files.
curl -s "https://runtime.demuddler.com/<path from files>" | sha256sum
# This must print true: the release ID covers every digest in the manifest.
node -e 'const { id, ...release } = require("./manifest.json");
console.log(require("node:crypto").createHash("sha256")
.update(JSON.stringify(release)).digest("hex") === id)'

Record the release ID when you start to use a version. Compare each later check with it. The manifest comes from the same server as the runtime, so only that comparison shows that the build did not change.

  1. Read the release notes for the package and for the runtime version that it opens.
  2. Install the new package version and commit your lockfile.
  3. If you set runtimeUrl, change it to the runtime version that you test.
  4. Test a valid file, and files with missing, invalid and duplicate values.
  5. Compare the delivered fields, converted values, row numbers and row counts.
  6. Test a failed delivery, a retry, a cancellation and navigation during an import.
  7. Test your appearance settings and each browser that you support.

To go back, restore your lockfile. If you set runtimeUrl, change it back too. An open importer keeps its runtime version until it closes, so a deployment does not change an import in progress.

To report a regression, give the package version, the runtime URL, the X-Demuddler-Release value and an invented sample file. Do not send customer data.