fetch-executable

fetch-executable

Fetch an executable, but only if needed

Intended for use downloading exact versions of executables and storing them on a per-project basis, rather than relying on a globally stored version being good enough for everything.

Quickstart

npm i --save fetch-executable

Then:

import { fetchExecutable } from 'fetch-executable';

await fetchExecutable({
    target: './my-exec',
    url: 'https://example.com/download/my-exec/{version}',
    version: '1.2.3',
    versionExecArgs: ['--version'],
});

This will:

• run ./my-exec --version and check if the output is 1.2.3
• if so, then done
• if not (because the output was the wrong version, or it errored, or the file just wasn't there)
  • download the file from https://example.com/download/my-exec/1.2.3
  • save it to ./my-exec
  • make it executable
  • check it now passes the version check

Shortcuts

There is a selection of executables for which the steps to download and check the version are bundled. These can be installed with eg:

import { kubectl } from 'fetch-executable/executables';

await kubectl('./kubectl', '1.23.0');

The full set is as follows, where the name of the function to download matches the name of the tool. Note also that these functions take an optional third argument that allow overriding of any options in the full set of options (see below).

• kubectl
• sops
• helmfile
• helm
• eksctl
• minikube
• gomplate
• mysqlsh
• usql
• terraform
• jq
• vagrant
• yq
• kubent
• flux

Options

This is the full set of options that can be passed to fetchExecutable (or as the optional third argument to any of the shortcuts, but with no required options).

target

Required?: yes

Type: string

The target local path on disk, either absolute, or relative to working directory.

url

Required?: yes

Type: string (is formatted)

URL from which to download if required.

execIsOk

Required?: must set one of: execIsOk; version; hashValueUrl

Type: (filepath: string) => Promise<boolean>

Given a filepath to an executable that might be the right one, return true if it is, false if it is not. If this is set in addition to either of version or hashValueUrl, then all tests must pass for the local executable to be considered "ok".

version

Required?: must set one of: execIsOk; version; hashValueUrl

Type: string

The desired version. Used with versionExecArgs to determine if the version of a local executable is as desired. Passed to formatted.

versionExecArgs

Required?: no, defaults to []. Only relevant if version is set.

Type: Array<string>

Command line arguments to pass to the local executable to make it print its version.

versionExecCaptureStderr

Required?: no, defaults capturing stdout

Type: boolean

If set to true, capture stderr from the executed command. Otherwise, captures stdout.

versionExecPostProcess

Required?: no, defaults to no post processing. Only relevant if version is set.

Type: (execOutput: string) => string

Given the string output from running the local executable (with versionExecArgs), process it to return the version number for comparison with the value set for version.

pathInTar

Required?: no, defaults to saving the downloaded file as-is

Type: string (is formatted)

If set, treat the downloaded file as a tar archive, and extract the file at the given path. Can be used in conjunction with gzExtract: true to handle .tar.gz files.

pathInZip

Required?: no, defaults to saving the downloaded file as-is

Type: string (is formatted)

If set, treat the downloaded file as a zip archive, and extract the file at the given path.

executableSubPathInDir

Required?: no, defaults to assuming the desired executable is a file at pathInTar. Only relevant if pathInTar is set (not yet supported with pathInZip).

Type: string (is formatted)

If set, treats pathInTar as a directory, and extracts the contents to a directory created at target. The executable itself is then at ${target}/${executableSubPathInDir}.

executableSubPathSymlink

Required?: no, defaults to no symlink created.

Type: string

If set, creates a symlink from the given path to the executable at ${target}/${executableSubPathInDir}.

gzExtract

Required?: no, defaults to saving the downloaded file as-is

Type: boolean

If set to true, gzip-extract the downloaded file. Can be used in conjunction with pathInTar to handle .tar.gz files.

bz2Extract

Required?: no, defaults to saving the downloaded file as-is

Type: boolean

If set to true, bz2-extract the downloaded file. Can be used in conjunction with pathInTar to handle .tar.bz2 files.

Note: if bz2Extract and gzExtract are both set to true, will gzip-extract then bz2-extract, but this is not expected to be a real use case.

hashValueUrl

Required?: must set one of: execIsOk; version; hashValueUrl

Type: string (is formatted)

URL that returns checksum data about the executable file. Possibly with hashMethod and hashChecksumFileMatchFilepath, use this to check if the local file is the correct version by comparing its hash with a published, expected hash. Note that need for the hash of the executable itself to be published at this URL, not of the archive used to distribute it.

hashMethod

Required?: no, by default uses sha256. Only relevant if hashValueUrl is set.

Type: string

A hash algorithm that node's crypto.createHash understands.

hashChecksumFileMatchFilepath

Required?: no, by default the value fetched from hashValueUrl as-is. Only relevant if hashValueUrl is set.

Type: string (is formatted)

If the data returned from hashValueUrl is not a single hash, but rather a list of hashes as returned by a utility like sha256sum, that lists hashes and filenames, use this to identify the filename whose hash to use.

messageHandler

Required?: no

Type: (message: FetchExecutableMessage) => void

A function that is called when fetchExecutable does things. Intended to allow for communication with the user about what is going on, for example, when downloading a potentially large file over a potentially slow network connection.

Note that this takes precedence over messageHandlerBuiltin.

Note that FetchExecutableMessage is exported and has the form:

interface FetchExecutableMessage {
    message: string;
    kind: string;
    target: string;
    isVerbose: boolean;
}

The kind string attribute will be one of:

• 'executable_is_ok', when the pre-existing executable has been checked and is OK
• 'fetching', when starting to fetch
• 'fetch_progress', progress during fetch
• 'saving', when starting to save
• 'done', when saved and made executable

messager

Deprecated alias for messageHandler.

messageHandlerBuiltin

Required?: no

Type: string (one of: 'string', 'json')

Shortcuts for some simple builtin messageHandlers.

• 'string': just prints the message attribute
• 'json': just prints the whole message as a JSON object

If a string other than the above options is passed, is ignored.

messagerBuiltin

Deprecated alias for messageHandlerBuiltin.

messageHandlerBuiltinVerbose

Required?: no, by default verbose messages not included. Only relevant if messageHandlerBuiltin is set.

Type: boolean

Whether the builtin messageHandlers should include the messages that have isVerbose: true.

messagerBuiltinVerbose

Deprecated alias for messageHandlerBuiltinVerbose.

messageHandlerBuiltinStream

Required?: no, by default messages are printed to process.stderr. Only relevant if messageHandlerBuiltin is set.

Type: stream.Writable

The stream to which messages from the builtin messageHandler are written.

messagerBuiltinStream

Deprecated alias for messageHandlerBuiltinStream.

String formatting

As a convenience, for the string options noted above, can perform formatting with the following variables:

• version, value of the version option, if set
• platform, value of process.platform
• arch, value of process.arch

Also, the following transformers are available:

• capitalize, upper-case the first character
• x64ToAmd64, if the passed value is 'x64', return 'amd64' (intended for use with arch)

Eg:

url: 'https://example.com/download/my-exec/{version}/{platform!capitalize}.tar.gz',
version: '1.2.3',
gzExtract: true,
pathInTar: '{arch!x64ToAmd64}/my-exec',

On a Linux, 64-bit OS, would retrieve the file from https://example.com/download/my-exec/1.2.3/Linux.tar.gz, and gzip extract, and retrieve the file from amd64/my-exec.