download-verify-install

download-verify-install (DVI) installs IOI components on your machine. It downloads a package from a package registry, verifies it, and installs it in your user space; no administrator rights are needed. If the package is an agent, DVI also registers it with the operating system, so that it is started at logon and kept running.

DVI comes as two programs: dvi-cli, the command line tool described below, and download-verify-install, the resident agent. The agent is started by the operating system and installs components on request of the Store-of-stores; you never run it by hand.

Command Line Interface (CLI)

$ dvi-cli i  <pkg> [--version <x.y.z> | --tag [<channel>]] [--sha2|--sha3 <hex>]
$ dvi-cli ui <pkg> [--version <x.y.z>] [--data]
$ dvi-cli ui --everything [--data]
$ dvi-cli l|ul|ql <pkg>
$ dvi-cli qi <pkg>
$ dvi-cli qo <pkg> [--version <x.y.z> | --tag [<channel>]]

$ dvi-cli --install-self
$ dvi-cli --version | -h|--help

A command is an action, i (install) or l (load), optionally preceded by a prefix, u (un-) or q (query), with no space in between. <pkg> is the package name including its scope e.g., @rootintf/download-verify-install.

Install

$ dvi-cli i @rootintf/some-component --registry <url>

Downloads the package, verifies it and installs it. If the package is an agent, it is loaded right away; if it declares commands, they are placed in the IOI bin directory (see Commands and PATH). The registry can also be given through the IOI_REGISTRY environment variable; a registry that does not allow anonymous access needs a token, given with --auth-token or the IOI_REGISTRY_TOKEN environment variable.

Packages are published per operating system. Without --version or --tag, the version for the operating system you are on is installed; a package that is not published for your OS is refused. Use --version <x.y.z> (no leading v) for an exact version, or --tag <channel> for a named channel; a bare --tag selects latest.

To verify the download, pass the SHA-384 checksum published beside the package with --sha2 <hex> (or --sha3 <hex> for SHA3-384). A download that does not match the checksum is refused. Without a checksum, DVI prints a warning and proceeds.

"C:\Users\dev\AppData\Local\IOI\@rootintf\download-verify-install\os_win32\bin\dvi-cli.exe" i @rootintf/reflector-cpp-mqtt--asio-client --version   3.1.61-win32 --sha2 58f282dc8752e3ec0312024d88b12e080c3f6edc79755ed6cee692d2b09fad804f5ea8fba22d15371be3336f0db1774c --registry   https://gitlab.com/api/v4/projects/85306102/packages/npm/

Uninstall

$ dvi-cli ui @rootintf/some-component [--data]

Removes the package. If the package is an agent, it is unloaded first, i.e., stopped and removed from the operating system, and only then are its files removed. With --version <x.y.z>, the package is only removed if exactly that version is installed. Add --data to also remove the package’s user data.

$ dvi-cli ui --everything [--data]

Removes every installed package, i.e., removes IOI from the system. Add --data to remove all user data as well.

dvi-cli ui @rootintf/reflector-cpp-mqtt--asio-client
dvi-cli ui @rootintf/download-verify-install // dvi can NOT uninstall itself from it's own install; make a copy of the cli outside the install dir.
ui cannot remove the package that dvi-cli itself is running from. The agent is unloaded, but removing the files fails, leaving the package installed but not loaded (see below). Run the uninstall from a dvi-cli outside the IOI directory.

Query

$ dvi-cli qi @rootintf/some-component
$ dvi-cli qo @rootintf/some-component --registry <url>

qi prints the installed version, or (not installed). qo asks the registry whether a newer version is available and prints outdated or current; it follows the same --version and --tag rules as i.

Load / unload

An installed agent is either loaded, i.e., registered with the operating system and running, or not. i loads an agent after installing it and ui unloads it before removing it, so normally you do not need these commands.

$ dvi-cli ql @rootintf/some-agent

Prints loaded or (not loaded). An agent that is installed but not loaded is not running and shows no heartbeat in the store-of-stores. This is the state after an explicit ul, or after an uninstall that failed once the agent was already unloaded. Load it again with:

$ dvi-cli l @rootintf/some-agent

ul does the opposite: it stops the agent and removes the registration, but leaves the files installed.

Install DVI itself

$ dvi-cli --install-self

Installs DVI to its default location, loads its agent and places dvi-cli in the IOI bin directory as a command. The Store-of-stores does this for you; running it again is harmless.

Commands and PATH

A package may declare commands in its package.json: one entry per executable, named as the user will type it, with a path per operating system:

"ioi": { "shim": { "dvi-cli": { "win32": "os_win32/bin/dvi-cli.exe", "darwin": "os_darwin/bin/dvi-cli", "linux": "os_linux/bin/dvi-cli" } }, "agent": { … } }

i places each command as a shim in the bin directory of the IOI root, pointing at the executable inside the package; nothing is copied out. On Windows the shim is a pair, a one-line dvi-cli.cmd for cmd.exe and PowerShell and an extensionless dvi-cli script for Git Bash, which does not resolve .cmd files by bare name; on macOS and Linux it is a symlink. ui removes the shims of the package it removes, and ui --everything removes the bin directory with the rest. A command declared for another operating system only is skipped. A name already taken by another package’s command, or by a file DVI did not write, is refused and the install fails before anything is replaced.

Only declared executables become commands. An agent is not a command and does not appear in bin unless its package lists it.

The bin directory is the one path to add to PATH; it serves every installed package, and packages come and go beneath it without further changes. DVI does not edit PATH itself. Once, per user:

Windows (PowerShell)

[Environment]::SetEnvironmentVariable('Path', "$env:LOCALAPPDATA\IOI\bin;" + [Environment]::GetEnvironmentVariable('Path', 'User'), 'User')

macOS (zsh)

echo 'export PATH="$HOME/.ioi/bin:$PATH"' >> ~/.zprofile

Linux (bash)

echo 'export PATH="$HOME/.local/share/ioi/bin:$PATH"' >> ~/.profile

Open a new shell afterwards. With DVI installed, dvi-cli then runs from any directory.

Exit codes

dvi-cli exits with 0 on success, 1 on error, and 2 when there is nothing to report: not installed, not loaded, outdated, or nothing to remove.

IPSME Interface

The resident agent is an IPSME participant: it listens on the local messaging environment and does over messages what dvi-cli does on the command line. This is how the Store-of-stores installs, queries and removes components. On Windows a candidate for the messaging environment is MQTT, while on macOS it is NSDNC.

The agent uses the following interfaces:

  • JSON_Msg, the envelope of every message: id, dt and referer ([participant, instance]); an answer carries the message it answers in _cause. The agent’s participant is its package name, @rootintf/download-verify-install.

  • protocols::Discovery.adoc, version 5: the heartbeat and the boot announce.

  • Installer, version 4: install, uninstall, load and query. The install-spec it carries is specified by InstallSpec, version 6.

Requests

{ "do-install": { "install-spec": { … } }, "Installer": "4", "id": "…", "dt": "…", "referer": [ "<participant>", "<instance>" ] }
{ "un-install": { "installed": { "name": "<pkg>" }, "data": false }, "Installer": "4", … }
{ "do-load": { "installed": { "name": "<pkg>" } }, "Installer": "4", … }
{ "query-install": { "q": "installed", "installed": { "name": "<pkg>" } }, "Installer": "4", … }
{ "query-install": { "q": "outdated", "install-spec": { … } }, "Installer": "4", … }

Each request is the message form of a CLI command and does what the CLI section describes. What the wire adds:

do-install

dvi-cli i, for the operating system the agent runs on; which version and checksum the install-spec resolves to is the InstallSpec’s affair. There is no token on the wire, so the registry must allow anonymous access. An install-spec whose method is neither registry nor vendor is not DVI’s to install and is ignored.

un-install

dvi-cli ui. data: true is --data. There is no --everything on the wire.

do-load

dvi-cli l, for a vendor-installed application only, which it launches. For a package from a registry the message is ignored: its agent was loaded at install.

query-install

q: installed is dvi-cli qi. q: outdated is dvi-cli qo, judged against the channel the install-spec names. q: loaded is not handled yet.

Ignored means no answer at all; the message may be meant for another participant.

The download runs on the agent’s message loop. While a package is downloading the agent answers nothing, so its heartbeat stops until the download completes.

Acks

Every request is answered with the Installer’s one ack, which carries the request it answers in _cause:

"ack": { "ok": true, "installed": { "name": "<pkg>", "version": "3.1.61-win32" } }
"ack": { "ok": false, "error": { "code": 1, "reason": "install: integrity mismatch: …" } }

installed.version is the exact version that is there, which matters when the install-spec only named a channel. code mirrors the CLI’s exit codes: 1 the operation failed, 2 there was nothing to act on (not installed, nothing removed), 3 the installed agent never joined the messaging environment (see below).

A successful q: outdated is the one request answered with an effect instead of an ack:

"query-outdated": { "installed": "3.1.60-win32", "wanted": "3.1.61-win32", "relation": -1 }

wanted is the version the install-spec resolves to right now; installed is absent when nothing is installed; relation compares the two: -1 installed is older, 0 the same, 1 newer. The agent does the comparison so that no consumer has to interpret version numbers. A q: outdated that cannot be judged, e.g., the registry is unreachable or nothing is pinned for this OS, is acked with ok: false.

net-ready

A package declares in its package.json that its agent joins the messaging environment:

"ioi": { "net-ready": "IPSME", "agent": { … } }

For such a package the ack to a do-install is held back until the agent has actually joined. A just-started agent declares itself with an unprompted announce, i.e., one with an empty _cause:

{ "announce": {}, "Discovery": "5", "_cause": null, "id": "…", "dt": "…", "referer": [ "<pkg>", "<instance>" ] }

DVI matches the announce on the install-spec’s referer, or its name when there is none. Heard within 10 seconds of loading the agent, the ack goes out with ok: true; since an agent subscribes before it announces, that ack means the component is installed, running and reachable. Not heard within 10 seconds, the install is treated as failed: DVI unloads the agent, leaves the files for diagnosis, and acks ok: false with code 3, "loaded but never joined the mesh (net-ready: IPSME)". A package without net-ready is acked as soon as it is loaded.

Heartbeat

{ "discover": { "ttl_msec": 5000, "echo-request": [ { "referer": { "participant": "@rootintf/download-verify-install" } } ] }, "Discovery": "5", … }

The agent answers a discover naming its participant with an announce carrying an echo-response; this is the heartbeat the store-of-stores shows. A discover asking for methods or interfaces is answered with what the agent can install (registry, vendor) and the Installer schema it accepts.