Create setup-zig

Author: mlugg

LICENSE

@@ -0,0 +1,8 @@
+Copyright Matthew Lugg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

README.md

@@ -0,0 +1,41 @@
+# setup-zig
+
+Install the Zig compiler for use in an Actions workflow, and preserve the Zig cache across workflow runs.
+
+## Usage
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    name: Build and Test
+    steps:
+      - uses: actions/checkout@v3
+      - uses: mlugg/setup-zig@v1
+      - run: zig build test
+```
+
+This will automatically download Zig and install it to `PATH`.
+
+You can use `version` to set a Zig version to download. This may be a release (`0.13.0`), a specific nightly
+build (`0.14.0-dev.2+0884a4341`), the string `master` for the latest nightly build, or the string `latest`
+for the latest full release. The default is `latest`.
+
+```yaml
+  - uses: mlugg/setup-zig@v1
+    with:
+      version: 0.13.0
+```
+
+> [!WARNING]
+> Mirrors, including the official Zig website, may purge old nightly builds at their leisure. This means
+> that if you target an out-of-date nightly build, such as a `0.11.0-dev` build, the download may fail.
+
+## Details
+
+This action attempts to download the requested Zig tarball from a set of mirrors, in a random order. As
+a last resort, the official Zig website is used. The tarball's minisign signature is also downloaded and
+verified to ensure binaries have not been tampered with. The tarball is cached between runs and workflows.
+
+The global Zig cache directory (`~/.cache/zig` on Linux) is automatically cached between runs, and all
+local caches are redirected to the global cache directory to make optimal use of this cross-run caching.

action.yml

@@ -0,0 +1,11 @@
+name: 'Setup Zig Compiler'
+description: 'Download and install the Zig compiler, and cache the global Zig cache'
+inputs:
+  version:
+    description: 'Version of the Zig compiler, e.g. "0.13.0" or "0.13.0-dev.351+64ef45eb0". "master" uses the latest nightly build. "latest" uses the latest tagged release.'
+    required: true
+    default: 'latest'
+runs:
+  using: 'node20'
+  main: 'main.js'
+  post: 'post.js'

common.js

@@ -0,0 +1,114 @@
+const os = require('os');
+const path = require('path');
+const core = require('@actions/core');
+const github = require('@actions/github');
+const exec = require('@actions/exec');
+
+const VERSIONS_JSON = 'https://ziglang.org/download/index.json';
+const CACHE_PREFIX = "setup-zig-global-cache-";
+
+let _cached_version = null;
+async function getVersion() {
+  if (_cached_version != null) {
+    return _cached_version;
+  }
+
+  const raw = core.getInput('version');
+  if (raw === 'master') {
+    const resp = await fetch(VERSIONS_JSON);
+    const versions = await resp.json();
+    _cached_version = versions['master'].version;
+  } else if (raw === 'latest') {
+    const resp = await fetch(VERSIONS_JSON);
+    const versions = await resp.json();
+    let latest = null;
+    let latest_major;
+    let latest_minor;
+    let latest_patch;
+    for (const version in versions) {
+      if (version === 'master') continue;
+      const [major_str, minor_str, patch_str] = version.split('.')
+      const major = Number(major_str);
+      const minor = Number(minor_str);
+      const patch = Number(patch_str);
+      if (latest === null) {
+        latest = version;
+        latest_major = major;
+        latest_minor = minor;
+        latest_patch = patch;
+        continue;
+      }
+      if (major > latest_major ||
+          (major == latest_major && minor > latest_minor) ||
+          (major == latest_major && minor == latest_minor && patch > latest_patch))
+      {
+        latest = version;
+        latest_major = major;
+        latest_minor = minor;
+        latest_patch = patch;
+      }
+    }
+    _cached_version = latest;
+  } else {
+    _cached_version = raw;
+  }
+
+  return _cached_version;
+}
+
+async function getTarballName() {
+  const version = await getVersion();
+
+  const arch = {
+    arm: 'armv7a',
+    arm64: 'aarch64',
+    ppc64: 'powerpc64',
+    riscv64: 'riscv64',
+    x64: 'x86_64',
+  }[os.arch()];
+
+  return {
+    linux:  `zig-linux-${arch}-${version}`,
+    darwin: `zig-macos-${arch}-${version}`,
+    win32:  `zig-windows-${arch}-${version}`,
+  }[os.platform()];
+}
+
+async function getTarballExt() {
+  return {
+    linux:  '.tar.xz',
+    darwin: '.tar.xz',
+    win32:  '.zip',
+  }[os.platform()];
+}
+
+async function getCachePrefix() {
+  const tarball_name = await getTarballName();
+  const job_name = github.context.job.replaceAll(/[^\w]/g, "_");
+  return `setup-zig-cache-${job_name}-${tarball_name}-`;
+}
+
+async function getZigCachePath() {
+  let env_output = '';
+  await exec.exec('zig', ['env'], {
+    listeners: {
+      stdout: (data) => {
+        env_output += data.toString();
+      },
+    },
+  });
+  return JSON.parse(env_output)['global_cache_dir'];
+}
+
+async function getTarballCachePath() {
+  return path.join(process.env['RUNNER_TEMP'], await getTarballName());
+}
+
+module.exports = {
+  getVersion,
+  getTarballName,
+  getTarballExt,
+  getCachePrefix,
+  getZigCachePath,
+  getTarballCachePath,
+};

main.js

@@ -0,0 +1,107 @@
+const os = require('os');
+const path = require('path');
+const fs = require('fs').promises;
+const core = require('@actions/core');
+const tc = require('@actions/tool-cache');
+const cache = require('@actions/cache');
+const common = require('./common');
+const minisign = require('./minisign');
+
+// Upstream's minisign key, from https://ziglang.org/download
+const MINISIGN_KEY = 'RWSGOq2NVecA2UPNdBUZykf1CCb147pkmdtYxgb3Ti+JO/wCYvhbAb/U';
+
+// The base URL of the official builds of Zig. This is only used as a fallback, if all mirrors fail.
+const CANONICAL = 'https://ziglang.org/builds';
+
+// The list of mirrors we attempt to fetch from. These need not be trusted, as
+// we always verify the minisign signature.
+const MIRRORS = [
+  // TODO: are there any more mirrors around?
+  'https://pkg.machengine.org/zig',
+];
+
+async function downloadFromMirror(mirror, tarball_name, tarball_ext) {
+  const tarball_path = await tc.downloadTool(`${mirror}/${tarball_name}${tarball_ext}`);
+
+  const signature_response = await fetch(`${mirror}/${tarball_name}${tarball_ext}.minisig`);
+  const signature_data = Buffer.from(await signature_response.arrayBuffer());
+
+  const tarball_data = await fs.readFile(tarball_path);
+
+  const key = minisign.parseKey(MINISIGN_KEY);
+  const signature = minisign.parseSignature(signature_data);
+  if (!minisign.verifySignature(key, signature, tarball_data)) {
+    throw new Error(`signature verification failed for '${mirror}/${tarball_name}${tarball_ext}'`);
+  }
+
+  return tarball_path;
+}
+
+async function downloadTarball(tarball_name, tarball_ext) {
+  // We will attempt all mirrors before making a last-ditch attempt to the official download.
+  // To avoid hammering a single mirror, we first randomize the array.
+  const shuffled_mirrors = MIRRORS.map((m) => [m, Math.random()]).sort((a, b) => a[1] - b[1]).map((a) => a[0]);
+  for (const mirror of shuffled_mirrors) {
+    core.info(`Attempting mirror: ${mirror}`);
+    try {
+      return await downloadFromMirror(mirror, tarball_name, tarball_ext);
+    } catch (e) {
+      core.info(`Mirror failed with error: ${e}`);
+      // continue loop to next mirror
+    }
+  }
+  core.info(`Attempting official: ${CANONICAL}`);
+  return await downloadFromMirror(CANONICAL, tarball_name, tarball_ext);
+}
+
+async function retrieveTarball(tarball_name, tarball_ext) {
+  const cache_key = `setup-zig-tarball-${tarball_name}`;
+  const tarball_cache_path = await common.getTarballCachePath();
+
+  if (await cache.restoreCache([tarball_cache_path], cache_key)) {
+    return tarball_cache_path;
+  }
+
+  core.info(`Cache miss. Fetching Zig ${await common.getVersion()}`);
+  const downloaded_path = await downloadTarball(tarball_name, tarball_ext);
+  await fs.copyFile(downloaded_path, tarball_cache_path)
+  await cache.saveCache([tarball_cache_path], cache_key);
+  return tarball_cache_path;
+}
+
+async function main() {
+  try {
+    // We will check whether Zig is stored in the cache. We use two separate caches.
+    // * 'tool-cache' caches the final extracted directory if the same Zig build is used multiple
+    //   times by one job. We have this dependency anyway for archive extraction.
+    // * 'cache' only caches the unextracted archive, but it does so across runs. It's a little
+    //   less efficient, but still much preferable to fetching Zig from a mirror. We have this
+    //   dependency anyway for caching the global Zig cache.
+
+    let zig_dir = tc.find('zig', await common.getVersion());
+    if (!zig_dir) {
+      const tarball_name = await common.getTarballName();
+      const tarball_ext = await common.getTarballExt();
+
+      const tarball_path = await retrieveTarball(tarball_name, tarball_ext);
+
+      core.info(`Extracting tarball ${tarball_name}${tarball_ext}`);
+
+      const zig_parent_dir = tarball_ext === 'zip' ?
+        await tc.extractZip(tarball_path) :
+        await tc.extractTar(tarball_path, null, 'xJ'); // J for xz
+
+      const zig_inner_dir = path.join(zig_parent_dir, tarball_name);
+      zig_dir = await tc.cacheDir(zig_inner_dir, 'zig', await common.getVersion());
+    }
+
+    core.addPath(zig_dir);
+    await cache.restoreCache([await common.getZigCachePath()], await common.getCachePrefix());
+    // Direct Zig to use the global cache as every local cache, so that we get maximum benefit from the caching above.
+    core.exportVariable('ZIG_LOCAL_CACHE_DIR', await common.getZigCachePath());
+  } catch (err) {
+    core.setFailed(err.message);
+  }
+}
+
+main();

minisign.js

@@ -0,0 +1,84 @@
+const sodium = require('sodium-native');
+
+// Parse a minisign key represented as a base64 string.
+// Throws exceptions on invalid keys.
+function parseKey(key_str) {
+  const key_info = Buffer.from(key_str, 'base64');
+
+  const id = key_info.subarray(2, 10);
+  const key = key_info.subarray(10);
+
+  if (key.byteLength !== sodium.crypto_sign_PUBLICKEYBYTES) {
+    throw new Error('invalid public key given');
+  }
+
+  return {
+    id: id,
+    key: key
+  };
+}
+
+// Parse a buffer containing the contents of a minisign signature file.
+// Throws exceptions on invalid signature files.
+function parseSignature(sig_buf) {
+  const untrusted_header = Buffer.from('untrusted comment: ');
+
+  // Validate untrusted comment header, and skip
+  if (!sig_buf.subarray(0, untrusted_header.byteLength).equals(untrusted_header)) {
+    throw new Error('file format not recognised');
+  }
+  sig_buf = sig_buf.subarray(untrusted_header.byteLength);
+
+  // Skip untrusted comment
+  sig_buf = sig_buf.subarray(sig_buf.indexOf('\n') + 1);
+
+  // Read and skip signature info
+  const sig_info_end = sig_buf.indexOf('\n');
+  const sig_info = Buffer.from(sig_buf.subarray(0, sig_info_end).toString(), 'base64');
+  sig_buf = sig_buf.subarray(sig_info_end + 1);
+
+  // Extract components of signature info
+  const algorithm = sig_info.subarray(0, 2);
+  const key_id = sig_info.subarray(2, 10);
+  const signature = sig_info.subarray(10);
+
+  // We don't look at the trusted comment or global signature, so we're done.
+
+  return {
+    algorithm: algorithm,
+    key_id: key_id,
+    signature: signature,
+  };
+}
+
+// Given a parsed key, parsed signature file, and raw file content, verifies the
+// signature. Does not throw. Returns 'true' if the signature is valid for this
+// file, 'false' otherwise.
+function verifySignature(pubkey, signature, file_content) {
+  let signed_content;
+  if (signature.algorithm.equals(Buffer.from('ED'))) {
+    signed_content = Buffer.alloc(sodium.crypto_generichash_BYTES_MAX);
+    sodium.crypto_generichash(signed_content, file_content);
+  } else {
+    signed_content = file_content;
+  }
+
+  if (!signature.key_id.equals(pubkey.id)) {
+    return false;
+  }
+
+  if (!sodium.crypto_sign_verify_detached(signature.signature, signed_content, pubkey.key)) {
+    return false;
+  }
+
+  // Since we don't use the trusted comment, we don't bother verifying the global signature.
+  // If we were to start using the trusted comment for any purpose, we must add this.
+
+  return true;
+}
+
+module.exports = {
+  parseKey,
+  parseSignature,
+  verifySignature,
+};