Skip to content
Python
4.7 KB
Raw Blame
/** Stable, allowlisted failure codes for cross-layer diagnosis.
 *
 * A Desktop action used to log `desktop_action_failed` for every failure, and a
 * host uninstall logged one message for every way it can refuse. Neither says
 * whether the fix is to re-authorize a source, repair a plugin, or recover a
 * half-applied install, which is what issue #29 needed to know.
 *
 * The codes are an allowlist on purpose. The alternative — parsing a domain
 * code back out of a thrown `Error.message` — is a protocol smuggled through
 * free text: any message that happens to match changes the classification, and
 * any message that does not match loses it entirely. Throwing a typed error at
 * the point of failure is the only place the truth is known.
 *
 * This lives in host-bridge rather than runtime-control because both layers
 * throw these and runtime-control already depends on host-bridge.
 */

export const DOMAIN_CODES = [
  "grant_required",
  "source_identity_changed",
  "host_uninstall_modified_managed_value",
  "host_uninstall_unknown_owned_file",
  "host_uninstall_needs_review",
  "host_install_journal_invalid",
  "host_install_recovery_required",
  "host_permission_storage_unsafe",
] as const;

export type DomainCode = (typeof DOMAIN_CODES)[number];

const CODES: ReadonlySet<string> = new Set(DOMAIN_CODES);

export function isDomainCode(value: unknown): value is DomainCode {
  return typeof value === "string" && CODES.has(value);
}

/** A failure the caller classified at the point it happened. */
export class DomainError extends Error {
  readonly code: DomainCode;

  constructor(code: DomainCode, message?: string) {
    super(message ?? code);
    this.name = "DomainError";
    this.code = code;
  }
}

export function isDomainError(value: unknown): value is DomainError {
  return value instanceof DomainError && isDomainCode(value.code);
}

/** The code to log, or null when the failure was never classified.
 *
 * Returning null rather than inventing a code is deliberate: an unclassified
 * error is information, and collapsing it into a guess is how a support bundle
 * starts agreeing with itself instead of with the machine.
 */
export function domainCodeOf(error: unknown): DomainCode | null {
  if (isDomainError(error)) return error.code;
  if (
    error &&
    typeof error === "object" &&
    isDomainCode((error as { code?: unknown }).code)
  )
    return (error as { code: DomainCode }).code;
  return null;
}

const SAFE_STACK_PREFIXES = ["apps/", "packages/", "scripts/"] as const;

function isSafeStackCharacter(character: string): boolean {
  const code = character.charCodeAt(0);
  return (
    (code >= 48 && code <= 57) ||
    (code >= 65 && code <= 90) ||
    (code >= 97 && code <= 122) ||
    "_./-:".includes(character)
  );
}

function isAsciiDigits(value: string): boolean {
  if (!value.length) return false;
  for (const character of value) {
    const code = character.charCodeAt(0);
    if (code < 48 || code > 57) return false;
  }
  return true;
}

/** Extract one repo-relative `path:line:column` in linear time. */
function safeStackLocation(line: string): string | null {
  for (const prefix of SAFE_STACK_PREFIXES) {
    const start = line.indexOf(prefix);
    if (start < 0) continue;
    let end = start;
    while (end < line.length && isSafeStackCharacter(line[end] ?? "")) end += 1;
    const candidate = line.slice(start, end);
    const columnSeparator = candidate.lastIndexOf(":");
    const lineSeparator = candidate.lastIndexOf(":", columnSeparator - 1);
    if (
      lineSeparator > prefix.length &&
      columnSeparator > lineSeparator + 1 &&
      isAsciiDigits(candidate.slice(lineSeparator + 1, columnSeparator)) &&
      isAsciiDigits(candidate.slice(columnSeparator + 1))
    )
      return candidate;
  }
  return null;
}

/** The diagnostic fields for a failure, keeping the code when there is one.
 *
 * Only `error_type` and a repo-relative stack survive. `Error.message` is
 * dropped: host paths, transcript names and user content all end up in
 * messages that were written for a person reading them on screen.
 */
export function diagnosticDomainError(error: unknown): {
  error_type: string;
  error_code?: string;
  safe_stack?: string[];
} {
  const code = domainCodeOf(error);
  if (!(error instanceof Error))
    return code
      ? { error_type: "DomainError", error_code: code }
      : { error_type: "UnknownError" };
  const stack = (error.stack ?? "")
    .split("\n")
    .flatMap((line) => {
      const location = safeStackLocation(line);
      return location ? [location] : [];
    })
    .slice(0, 16);
  return {
    error_type: /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(error.name)
      ? error.name
      : "Error",
    ...(code ? { error_code: code } : {}),
    ...(stack.length ? { safe_stack: stack } : {}),
  };
}