Merge pull request #4081 from github/mario-campos/version-cache-to-disk

Persist CodeQL version output to file rather than environment

src/cli/output-cache.test.ts

@@ -0,0 +1,128 @@
+import * as fs from "fs";
+import path from "path";
+
+import test from "ava";
+
+import { EnvVar } from "../environment";
+import { getRunnerLogger } from "../logging";
+import { getTestEnv, setupTests } from "../testing-utils";
+import * as util from "../util";
+
+import * as outputCache from "./output-cache";
+
+setupTests(test);
+
+const logger = getRunnerLogger(true);
+
+test.serial(
+  "getCachedCodeQlVersion reuses a version persisted by an earlier step",
+  async (t) => {
+    await util.withTmpDir(async (tmpDir: string) => {
+      const cacheFile = path.join(tmpDir, "codeql-action-command-cache.json");
+      fs.writeFileSync(
+        cacheFile,
+        JSON.stringify({
+          cmd: "/path/to/codeql",
+          entries: { version: { version: "2.20.0" } },
+        }),
+        "utf8",
+      );
+      const env = getTestEnv({ [EnvVar.TEMP]: tmpDir });
+      t.deepEqual(
+        outputCache.getCachedCodeQlVersion(logger, env, "/path/to/codeql"),
+        {
+          version: "2.20.0",
+        },
+      );
+    });
+  },
+);
+
+test.serial(
+  "getCachedCodeQlVersion ignores a persisted version from a different CLI",
+  async (t) => {
+    await util.withTmpDir(async (tmpDir: string) => {
+      const cacheFile = path.join(tmpDir, "version.json");
+      fs.writeFileSync(
+        cacheFile,
+        JSON.stringify({
+          cmd: "/path/to/other-codeql",
+          version: { version: "2.20.0" },
+        }),
+        "utf8",
+      );
+      const env = getTestEnv({ [EnvVar.TEMP]: tmpDir });
+      t.is(
+        outputCache.getCachedCodeQlVersion(logger, env, "/path/to/codeql"),
+        undefined,
+      );
+    });
+  },
+);
+
+test.serial(
+  "getCachedCodeQlVersion ignores a malformed persisted value",
+  async (t) => {
+    await util.withTmpDir(async (tmpDir: string) => {
+      const cacheFile = path.join(tmpDir, "version.json");
+      fs.writeFileSync(cacheFile, "not valid json", "utf8");
+      const env = getTestEnv({ [EnvVar.TEMP]: tmpDir });
+      t.is(
+        outputCache.getCachedCodeQlVersion(logger, env, "/path/to/codeql"),
+        undefined,
+      );
+    });
+  },
+);
+
+test.serial(
+  "getCachedCodeQlVersion ignores a persisted value with the wrong structure",
+  async (t) => {
+    await util.withTmpDir(async (tmpDir: string) => {
+      const cacheFile = path.join(tmpDir, "version.json");
+      const env = getTestEnv({ [EnvVar.TEMP]: tmpDir });
+
+      const testValues = [
+        { cmd: "/path/to/codeql" },
+        { entries: { version: { version: "2.20.0" } } },
+        { cmd: "/path/to/codeql", entries: {} },
+        { cmd: "/path/to/codeql", entries: null },
+        { cmd: "/path/to/codeql", entries: { version: {} } },
+        { cmd: "/path/to/codeql", entries: { version: null } },
+        { cmd: "/path/to/codeql", entries: { version: "2.20.0" } },
+        { cmd: "/path/to/codeql", entries: { version: { version: null } } },
+        { cmd: "/path/to/codeql", entries: { version: { version: 2.2 } } },
+        { cmd: "/path/to/codeql", entries: { version: { version: 2 } } },
+        {
+          cmd: "/path/to/codeql",
+          entries: { version: { version: "2.20.0", overlayVersion: "1" } },
+        },
+        {
+          cmd: "/path/to/codeql",
+          entries: { version: { version: "2.20.0", features: "nope" } },
+        },
+      ].map((v) => JSON.stringify(v));
+
+      for (const value of testValues) {
+        fs.writeFileSync(cacheFile, value, "utf8");
+        t.is(
+          outputCache.getCachedCodeQlVersion(logger, env, "/path/to/codeql"),
+          undefined,
+          value,
+        );
+      }
+    });
+  },
+);
+
+test.serial("getCachedCodeQlVersion ignores non-existent file", async (t) => {
+  await util.withTmpDir(async (tmpDir: string) => {
+    const env = getTestEnv({ [EnvVar.TEMP]: tmpDir });
+    t.notThrows(() => {
+      t.is(
+        outputCache.getCachedCodeQlVersion(logger, env, "/path/to/codeql"),
+        undefined,
+      );
+    });
+  });
+});

src/cli/output-cache.ts

@@ -0,0 +1,156 @@
+import * as fs from "fs";
+import path from "path";
+
+import { getTemporaryDirectory } from "../actions-util";
+import { Env } from "../environment";
+import { Logger } from "../logging";
+
+import type { VersionInfo } from "./types";
+
+/**
+ * The keys of the command cache. Each key corresponds to a command whose output we cache.
+ */
+export type CommandCacheKey = string;
+
+/**
+ * The type of the command cache that is persisted to disk.
+ */
+export interface OutputCache {
+  cmd: string;
+  entries: Record<CommandCacheKey, unknown>;
+}
+
+/**
+ * The name of the temporary file that backs the on-disk cache of
+ * CLI responses between workflow steps.
+ */
+const COMMAND_CACHE_FILENAME = "codeql-action-command-cache.json";
+
+/**
+ * The module-global variable that caches the CodeQL CLI version in-memory.
+ */
+let cachedCodeQlVersion: undefined | VersionInfo = undefined;
+
+/**
+ * Resets the in-process cache of the CodeQL CLI version. Only for use in tests,
+ * which exercise multiple "steps" within a single process.
+ */
+export function resetCachedCodeQlVersion(): void {
+  cachedCodeQlVersion = undefined;
+}
+
+/**
+ * Returns the path to the temporary file that backs the
+ * on-disk cache of CLI responses between workflow steps.
+ */
+function getCommandCacheFilePath(env: Env): string {
+  return path.join(getTemporaryDirectory(env), COMMAND_CACHE_FILENAME);
+}
+
+/**
+ * Caches the CodeQL CLI version both in-memory and on disk.
+ * @param env The environment variables to use.
+ * @param cmd The path to the CodeQL CLI.
+ * @param version The version information to cache.
+ */
+export function cacheCodeQlVersion(
+  env: Env,
+  cmd: string,
+  version: VersionInfo,
+): void {
+  if (cachedCodeQlVersion !== undefined) {
+    throw new Error("cacheCodeQlVersion() should be called only once");
+  }
+  cachedCodeQlVersion = version;
+  const outputCache = {
+    cmd,
+    entries: { version },
+  } satisfies OutputCache;
+  // Persist the version so that subsequent Actions steps, which run in separate
+  // processes, can reuse it rather than invoking `codeql version` again. We
+  // record the CLI path so that a different step using a different CodeQL bundle
+  // doesn't pick up a stale version.
+  fs.writeFileSync(
+    getCommandCacheFilePath(env),
+    JSON.stringify(outputCache),
+    "utf8",
+  );
+}
+
+/**
+ * Returns the cached CodeQL CLI version, if any.
+ * @param logger The logger to use for logging messages.
+ * @param env The environment variables to use.
+ * @param cmd The path to the CodeQL CLI.
+ */
+export function getCachedCodeQlVersion(
+  logger: Logger,
+  env: Env,
+  cmd?: string,
+): undefined | VersionInfo {
+  if (cachedCodeQlVersion !== undefined) {
+    return cachedCodeQlVersion;
+  }
+  // Fall back to the value persisted by an earlier Actions step, if any. This is
+  // best-effort: any malformed or mismatched value is ignored so that the caller
+  // invokes `codeql version` instead.
+  let serialized: string;
+  try {
+    serialized = fs.readFileSync(getCommandCacheFilePath(env), "utf8");
+  } catch (e) {
+    logger.debug(
+      `Cannot read CLI-cache file ${getCommandCacheFilePath(env)}: ${e}`,
+    );
+    return undefined;
+  }
+  let persisted: unknown;
+  try {
+    persisted = JSON.parse(serialized);
+  } catch (e) {
+    logger.debug(`Cannot parse CLI-cache data as JSON: ${e}`);
+    return undefined;
+  }
+  if (
+    !isOutputCache(persisted) ||
+    (cmd !== undefined && persisted.cmd !== cmd)
+  ) {
+    return undefined;
+  }
+  // Memoize the parsed value so that subsequent calls in this process don't
+  // re-parse the environment variable.
+  cachedCodeQlVersion = persisted.entries.version as VersionInfo;
+  return cachedCodeQlVersion;
+}
+
+/**
+ * Determines whether a value is a `VersionInfo` object.
+ * @param x The value to test
+ */
+function isVersionInfo(x: unknown): x is VersionInfo {
+  const candidate = x as Partial<VersionInfo> | null;
+  return (
+    typeof candidate === "object" &&
+    candidate !== null &&
+    typeof candidate.version === "string" &&
+    (candidate.features === undefined ||
+      (typeof candidate.features === "object" &&
+        candidate.features !== null)) &&
+    (candidate.overlayVersion === undefined ||
+      typeof candidate.overlayVersion === "number")
+  );
+}
+
+/**
+ * Determines whether a value is a `OutputCache` object.
+ * @param x The value to test
+ */
+function isOutputCache(x: unknown): x is OutputCache {
+  const candidate = x as Partial<OutputCache> | null;
+  return (
+    typeof candidate === "object" &&
+    candidate !== null &&
+    typeof candidate.cmd === "string" &&
+    candidate.entries !== undefined &&
+    isVersionInfo(candidate.entries.version)
+  );
+}

src/cli/types.ts

@@ -0,0 +1,13 @@
+export interface VersionInfo {
+  version: string;
+  features?: { [name: string]: boolean };
+  /**
+   * The overlay version helps deal with backward incompatible changes for
+   * overlay analysis. When a precompiled query pack reports the same overlay
+   * version as the CodeQL CLI, we can use the CodeQL CLI to perform overlay
+   * analysis with that pack. Otherwise, if the overlay versions are different,
+   * or if either the pack or the CLI does not report an overlay version,
+   * we need to revert to non-overlay analysis.
+   */
+  overlayVersion?: number;
+}

src/codeql.ts

@@ -12,10 +12,12 @@ import {
   runTool,
 } from "./actions-util";
 import * as api from "./api-client";
+import * as outputCache from "./cli/output-cache";
+import type { VersionInfo } from "./cli/types";
 import { CliError, wrapCliConfigurationError } from "./cli-errors";
 import { appendExtraQueryExclusions, type Config } from "./config-utils";
 import { DocUrl } from "./doc-url";
-import { EnvVar } from "./environment";
+import { EnvVar, getEnv } from "./environment";
 import {
   CodeQLDefaultVersionInfo,
   Feature,
@@ -214,20 +216,6 @@ export interface CodeQL {
   ): Promise<void>;
 }
 
-export interface VersionInfo {
-  version: string;
-  features?: { [name: string]: boolean };
-  /**
-   * The overlay version helps deal with backward incompatible changes for
-   * overlay analysis. When a precompiled query pack reports the same overlay
-   * version as the CodeQL CLI, we can use the CodeQL CLI to perform overlay
-   * analysis with that pack. Otherwise, if the overlay versions are different,
-   * or if either the pack or the CLI does not report an overlay version,
-   * we need to revert to non-overlay analysis.
-   */
-  overlayVersion?: number;
-}
-
 export interface ResolveDatabaseOutput {
   overlayBaseSpecifier?: string;
 }
@@ -503,7 +491,7 @@ async function getCodeQLForCmd(
       return cmd;
     },
     async getVersion() {
-      let result = util.getCachedCodeQlVersion(cmd);
+      let result = outputCache.getCachedCodeQlVersion(logger, getEnv(), cmd);
       if (result === undefined) {
         result = await runCliJson<VersionInfo>(
           cmd,
@@ -512,7 +500,7 @@ async function getCodeQLForCmd(
             noStreamStdout: true,
           },
         );
-        util.cacheCodeQlVersion(cmd, result);
+        outputCache.cacheCodeQlVersion(getEnv(), cmd, result);
       }
       return result;
     },

src/environment.ts

@@ -39,12 +39,6 @@ export enum EnvVar {
    */
   CODE_SCANNING_REF = "CODE_SCANNING_REF",
 
-  /**
-   * `PersistedVersionInfo` for the CodeQL CLI, so later Actions steps can reuse it instead of
-   * invoking `codeql version` again.
-   */
-  CODEQL_VERSION_INFO = "CODEQL_ACTION_CLI_VERSION_INFO",
-
   /** Whether the CodeQL Action has invoked the Go autobuilder. */
   DID_AUTOBUILD_GOLANG = "CODEQL_ACTION_DID_AUTOBUILD_GOLANG",
 

src/status-report.ts

@@ -14,6 +14,7 @@ import {
   isSelfHostedRunner,
 } from "./actions-util";
 import { getAnalysisKey, getApiClient } from "./api-client";
+import { getCachedCodeQlVersion } from "./cli/output-cache";
 import type { Config } from "./config/action-config";
 import type { ComputedInput, InputName } from "./config/inputs";
 import { parseRegistriesWithoutCredentials } from "./config/pack-registries";
@@ -30,7 +31,6 @@ import { registryBaseSchema } from "./start-proxy/types";
 import {
   ConfigurationError,
   getRequiredEnvParam,
-  getCachedCodeQlVersion,
   isInTestMode,
   GITHUB_DOTCOM_URL,
   DiskUsage,
@@ -376,7 +376,7 @@ export async function createStatusReportBase(
       core.exportVariable(EnvVar.WORKFLOW_STARTED_AT, workflowStartedAt);
     }
     const runnerOs = getRequiredEnvParam("RUNNER_OS");
-    const codeQlCliVersion = getCachedCodeQlVersion();
+    const codeQlCliVersion = getCachedCodeQlVersion(logger, getEnv());
     const actionRef = process.env["GITHUB_ACTION_REF"] || "";
     const testingEnvironment = getTestingEnvironment();
     // re-export the testing environment variable so that it is available to subsequent steps,

src/testing-utils.ts

@@ -18,6 +18,8 @@ import { AnalysisKind } from "./analyses";
 import * as apiClient from "./api-client";
 import { GitHubApiDetails } from "./api-client";
 import { CachingKind } from "./caching-utils";
+import { resetCachedCodeQlVersion } from "./cli/output-cache";
+import type { VersionInfo } from "./cli/types";
 import * as codeql from "./codeql";
 import { Config } from "./config-utils";
 import * as defaults from "./defaults.json";
@@ -39,7 +41,6 @@ import {
   GitHubVariant,
   GitHubVersion,
   HTTPError,
-  resetCachedCodeQlVersion,
   Result,
   Success,
 } from "./util";
@@ -872,7 +873,7 @@ export const makeVersionInfo = (
   version: string,
   features?: { [name: string]: boolean },
   overlayVersion?: number,
-): codeql.VersionInfo => ({
+): VersionInfo => ({
   version,
   features,
   overlayVersion,

src/tools-features.ts

@@ -1,6 +1,6 @@
 import * as semver from "semver";
 
-import type { VersionInfo } from "./codeql";
+import type { VersionInfo } from "./cli/types";
 
 export enum ToolsFeature {
   BuiltinExtractorsSpecifyDefaultQueries = "builtinExtractorsSpecifyDefaultQueries",

src/util.test.ts

@@ -532,58 +532,3 @@ test("Failure.orElse returns the default value for a failure result", (t) => {
   const result = new util.Failure(new Error("test error"));
   t.is(result.orElse("default value"), "default value");
 });
-
-test.serial(
-  "getCachedCodeQlVersion reuses a version persisted by an earlier step",
-  (t) => {
-    process.env[EnvVar.CODEQL_VERSION_INFO] = JSON.stringify({
-      cmd: "/path/to/codeql",
-      version: { version: "2.20.0" },
-    });
-    t.deepEqual(util.getCachedCodeQlVersion("/path/to/codeql"), {
-      version: "2.20.0",
-    });
-  },
-);
-
-test.serial(
-  "getCachedCodeQlVersion ignores a persisted version from a different CLI",
-  (t) => {
-    process.env[EnvVar.CODEQL_VERSION_INFO] = JSON.stringify({
-      cmd: "/path/to/other-codeql",
-      version: { version: "2.20.0" },
-    });
-    t.is(util.getCachedCodeQlVersion("/path/to/codeql"), undefined);
-  },
-);
-
-test.serial(
-  "getCachedCodeQlVersion ignores a malformed persisted value",
-  (t) => {
-    process.env[EnvVar.CODEQL_VERSION_INFO] = "not valid json";
-    t.is(util.getCachedCodeQlVersion("/path/to/codeql"), undefined);
-  },
-);
-
-test.serial(
-  "getCachedCodeQlVersion ignores a persisted value with the wrong structure",
-  (t) => {
-    for (const value of [
-      JSON.stringify({ cmd: "/path/to/codeql" }),
-      JSON.stringify({ cmd: "/path/to/codeql", version: {} }),
-      JSON.stringify({ cmd: "/path/to/codeql", version: { version: 2 } }),
-      JSON.stringify({ version: { version: "2.20.0" } }),
-      JSON.stringify({
-        cmd: "/path/to/codeql",
-        version: { version: "2.20.0", overlayVersion: "1" },
-      }),
-      JSON.stringify({
-        cmd: "/path/to/codeql",
-        version: { version: "2.20.0", features: "nope" },
-      }),
-    ]) {
-      process.env[EnvVar.CODEQL_VERSION_INFO] = value;
-      t.is(util.getCachedCodeQlVersion("/path/to/codeql"), undefined, value);
-    }
-  },
-);

src/util.ts

@@ -10,7 +10,7 @@ import * as yaml from "js-yaml";
 import * as semver from "semver";
 
 import * as apiCompatibility from "./api-compatibility.json";
-import type { CodeQL, VersionInfo } from "./codeql";
+import type { CodeQL } from "./codeql";
 import type { Pack } from "./config/db-config";
 import type { Config } from "./config-utils";
 import { EnvVar, getRequiredEnvParam } from "./environment";
@@ -598,90 +598,6 @@ export function asHTTPError(arg: any): HTTPError | undefined {
   return undefined;
 }
 
-let cachedCodeQlVersion: undefined | VersionInfo = undefined;
-
-/**
- * Resets the in-process cache of the CodeQL CLI version. Only for use in tests,
- * which exercise multiple "steps" within a single process.
- */
-export function resetCachedCodeQlVersion(): void {
-  cachedCodeQlVersion = undefined;
-}
-
-/** The persisted version together with the CLI path it was obtained from. */
-interface PersistedVersionInfo {
-  cmd: string;
-  version: VersionInfo;
-}
-
-function isVersionInfo(x: unknown): x is VersionInfo {
-  const candidate = x as Partial<VersionInfo> | null;
-  return (
-    typeof candidate === "object" &&
-    candidate !== null &&
-    typeof candidate.version === "string" &&
-    (candidate.features === undefined ||
-      (typeof candidate.features === "object" &&
-        candidate.features !== null)) &&
-    (candidate.overlayVersion === undefined ||
-      typeof candidate.overlayVersion === "number")
-  );
-}
-
-function isPersistedVersionInfo(x: unknown): x is PersistedVersionInfo {
-  const candidate = x as Partial<PersistedVersionInfo> | null;
-  return (
-    typeof candidate === "object" &&
-    candidate !== null &&
-    typeof candidate.cmd === "string" &&
-    isVersionInfo(candidate.version)
-  );
-}
-
-export function cacheCodeQlVersion(cmd: string, version: VersionInfo): void {
-  if (cachedCodeQlVersion !== undefined) {
-    throw new Error("cacheCodeQlVersion() should be called only once");
-  }
-  cachedCodeQlVersion = version;
-  // Persist the version so that subsequent Actions steps, which run in separate
-  // processes, can reuse it rather than invoking `codeql version` again. We
-  // record the CLI path so that a different step using a different CodeQL bundle
-  // doesn't pick up a stale version.
-  core.exportVariable(
-    EnvVar.CODEQL_VERSION_INFO,
-    JSON.stringify({ cmd, version }),
-  );
-}
-
-export function getCachedCodeQlVersion(cmd?: string): undefined | VersionInfo {
-  if (cachedCodeQlVersion !== undefined) {
-    return cachedCodeQlVersion;
-  }
-  // Fall back to the value persisted by an earlier Actions step, if any. This is
-  // best-effort: any malformed or mismatched value is ignored so that the caller
-  // invokes `codeql version` instead.
-  const serialized = process.env[EnvVar.CODEQL_VERSION_INFO];
-  if (!serialized) {
-    return undefined;
-  }
-  let persisted: unknown;
-  try {
-    persisted = JSON.parse(serialized);
-  } catch {
-    return undefined;
-  }
-  if (
-    !isPersistedVersionInfo(persisted) ||
-    (cmd !== undefined && persisted.cmd !== cmd)
-  ) {
-    return undefined;
-  }
-  // Memoize the parsed value so that subsequent calls in this process don't
-  // re-parse the environment variable.
-  cachedCodeQlVersion = persisted.version;
-  return cachedCodeQlVersion;
-}
-
 export async function codeQlVersionAtLeast(
   codeql: CodeQL,
   requiredVersion: string,