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.
What each version means
Section titled “What each version means”| 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.
Which runtime version runs
Section titled “Which runtime version runs”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.0X-Demuddler-Release: <SHA-256 build digest>The second header identifies the exact build. Neither header contains customer data.
Pin a runtime version
Section titled “Pin a runtime version”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.
Withdrawn versions
Section titled “Withdrawn versions”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.
Verify a pinned build
Section titled “Verify a pinned build”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.
version=0.4.0base=https://runtime.demuddler.com/version/$versioncurl -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.
Upgrade your integration
Section titled “Upgrade your integration”- Read the release notes for the package and for the runtime version that it opens.
- Install the new package version and commit your lockfile.
- If you set
runtimeUrl, change it to the runtime version that you test. - Test a valid file, and files with missing, invalid and duplicate values.
- Compare the delivered fields, converted values, row numbers and row counts.
- Test a failed delivery, a retry, a cancellation and navigation during an import.
- 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.