Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

9.1 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
import { dirname, join } from "path";

import { ixHome } from "./ix-home.js";
import type { IxClient } from "../client/api.js";
import type { HealthResponse } from "../client/types.js";

/**
 * Everything that reads or writes `~/.ix/.backend-version`.
 *
 * A leaf on purpose. `upgrade.ts` owns the update notice and imports
 * `backend-status.ts`, so the stamp could not live in either without a cycle the
 * moment `backend-status` needed to write it. Keeping it here lets the ONE
 * function that fetches health also record what it read, which is what stops a
 * future call site from silently forgetting to.
 */

/**
 * The release the backend is believed to be running: `$IX_HOME/.backend-version`.
 *
 * A function, not a const, so the path follows IX_HOME as it is when the stamp
 * is read or written rather than when this module was first imported -- see
 * `ixHome()`.
 */
export function backendVersionFile(): string {
  return join(ixHome(), ".backend-version");
}

/**
 * The one definition of a valid version string, imported by upgrade.ts too.
 *
 * Copied rather than shared once already, and this exact pattern has shipped
 * broken: written as a single `(?:[-+]...)?` group whose class omitted `+`, it
 * rejected the valid tag `0.9.0-rc.1+abc1234` and `ix upgrade` exited 1 with
 * "Could not reach GitHub" against a perfectly reachable GitHub. Two copies mean
 * the next correction lands in one of them.
 */
export const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;

/** Longer than any plausible tag; bounds a value the container controls. */
const MAX_VERSION_LENGTH = 64;

export function getTrackedVersion(versionFile: string): string {
  try {
    if (!existsSync(versionFile)) return "0.0.0";
    return readFileSync(versionFile, "utf-8").trim() || "0.0.0";
  } catch {
    return "0.0.0";
  }
}

/**
 * Record a version stamp. Returns whether it was written.
 *
 * `mkdirSync` because IX_HOME may not exist yet. A falsy version is refused: not
 * knowing which release we are on is not the same as being on none of them.
 *
 * NOT atomic, deliberately. `writeFileSync` opens with O_TRUNC, so a reader
 * landing mid-write sees "" and is told a current backend is out of date — and
 * this is now reachable from `ix status`/`ix map` while `checkForUpdate` reads
 * the file on every command. Two things make that the better trade anyway:
 * `recordBackendRelease` short-circuits when the stamp already agrees, so a
 * write happens only when the backend's version actually CHANGES, not per
 * command; and a temp-file-plus-rename replaces a file the caller may not have
 * permission to write, since rename needs the directory rather than the file.
 * That would silently change when the stamp-failure warning fires and would
 * force the tests that pin it onto read-only directories, which Windows does not
 * honour. Worth revisiting with an injection that works on both platforms.
 */
export function writeVersionStamp(
  versionFile: string,
  version: string | null | undefined,
): boolean {
  if (!version) return false;
  try {
    mkdirSync(dirname(versionFile), { recursive: true });
    writeFileSync(versionFile, version);
    return true;
  } catch {
    return false;
  }
}

/**
 * Record what the backend says it is running.
 *
 * `.backend-version` was a record of what the CLI last INSTALLED, which is the
 * same thing as what is RUNNING only while nothing else moves the image. Pull
 * through docker compose and the file names an older release than the container,
 * so the update notice fires on every command for ever. The container is the one
 * thing that always knows, so it is asked rather than inferred.
 *
 * Three things bound a value the container controls, because this file decides
 * whether the user is ever told about an upgrade again:
 *
 * - it is trimmed before matching. `getTrackedVersion` trims on the way out, and
 *   JavaScript's `$` does not match before a trailing newline, so without this a
 *   value from an --env-file or a ConfigMap silently fails the shape test and
 *   the whole feature no-ops with nothing to see.
 * - it must be version-shaped and bounded in length. It is an env var an
 *   operator can set to anything.
 * - it may NOT claim to be newer than the newest release we know of. Otherwise
 *   one container reporting `99.0.0` — a typo in a compose override, or a
 *   tampered image — permanently silences the notice AND makes `ix upgrade`
 *   report "already on the latest version" without ever pulling, so a security
 *   release can never reach that machine. When no release is known yet, only
 *   corrections that do not move the stamp forward are accepted, which still
 *   repairs a stamp stuck ahead and defers the rest until the cache exists.
 *
 * What the ceiling does NOT stop, stated plainly: a container that reports
 * *exactly* the ceiling is accepted, and a compromised one has outbound network
 * and can simply read the public release feed to learn that number rather than
 * guess it. It then reaches the same silenced state by looking the answer up.
 * This is a capability the feature introduces — before it, the stamp was
 * written only by our own install/pull paths, so a container could not
 * influence it at all. It is accepted deliberately: the alternative is to
 * distrust the only component that actually knows what it is running, and the
 * fail-safe direction (a container under-reporting, causing an unnecessary
 * pull) is the one that stays open. `ix doctor`'s digest comparison remains the
 * check that does not ask the container what it is.
 */
export function recordBackendRelease(
  reported: string | null | undefined,
  knownLatest: string | null | undefined,
  isNewer: (a: string, b: string) => boolean,
): boolean {
  const value = typeof reported === "string" ? reported.trim() : "";
  if (!value || value.length > MAX_VERSION_LENGTH || !VERSION_RE.test(value)) return false;

  const tracked = getTrackedVersion(backendVersionFile());
  if (value === tracked) return false; // already agrees; do not touch the file

  const ceiling =
    typeof knownLatest === "string" && VERSION_RE.test(knownLatest.trim())
      ? knownLatest.trim()
      : null;
  // No published release can be older than what a container legitimately runs.
  if (ceiling ? isNewer(value, ceiling) : isNewer(value, tracked)) return false;

  return writeVersionStamp(backendVersionFile(), value);
}

/**
 * True when this endpoint is the local backend the update notice is about.
 *
 * The stamp is global (`~/.ix/.backend-version`) but the endpoint is per
 * invocation, so `IX_ENDPOINT=http://staging:8090 ix status` would otherwise
 * record a different deployment's release into the file that governs the LOCAL
 * docker image notice — a newer remote silencing a genuinely stale local
 * backend, or an older one nagging about a current one.
 */
export function isLocalEndpoint(endpoint: string): boolean {
  try {
    // A trailing dot is the fully-qualified form and resolvers accept it.
    const host = new URL(endpoint).hostname.toLowerCase().replace(/\.$/, "");
    return (
      host === "localhost" ||
      /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host) || // 127.0.0.0/8, as an ADDRESS
      // ...not a prefix: `127.0.0.1.evil.com` is a remote name that starts "127."
      host === "0.0.0.0" || // what client/api.ts and errors.ts already accept
      host === "[::1]" // new URL() always brackets IPv6, so bare "::1" is unreachable
    );
  } catch {
    return false;
  }
}

/**
 * Fetch `/v1/health` AND record the release it reports.
 *
 * The single place either happens. Every command that READS a health body goes
 * through here, so "a new call site forgot to record" is not a mistake that can
 * be made — which is worth more than the grep-based drift guard it replaces.
 *
 * Precisely: reads of the body. docker.ts and upgrade.ts also hit /v1/health via
 * `curl -sf` with stdio ignored, purely as a readiness poll; they discard the
 * response, so there is nothing there to record.
 */
export async function fetchBackendHealth(
  client: IxClient,
  knownLatest: string | null | undefined,
  isNewer: (a: string, b: string) => boolean,
  /** Bounds a probe that must answer in seconds; the client's default otherwise. */
  timeoutMs?: number,
): Promise<HealthResponse> {
  const health = await client.health(timeoutMs);
  // From the client the request actually went to. Taking it as a second
  // argument reintroduced exactly the "a call site can get it wrong" mistake
  // this module exists to make impossible.
  // `health?.` because a 200 whose body is literally `null` parses to null.
  // The contract of this function is "return whatever the backend sent"; adding
  // a throw of its own would be this bookkeeping changing the outcome of a
  // request that succeeded. Nothing more is claimed: status.ts dereferences
  // health.status unguarded moments later, so on a null body it fails either
  // way — the `?.` keeps the failure the caller's, not ours.
  if (isLocalEndpoint(client.endpoint)) {
    recordBackendRelease(health?.release_version, knownLatest, isNewer);
  }
  return health;
}