pi-microsandbox 0.1.0

package/extensions/pi-msb/labels.ts

@@ -0,0 +1,321 @@
+/** Managed microsandbox labels and persisted session state. */
+import {
+  LABEL_KEYS,
+  STATE_SCHEMA_VERSION,
+  type ManagedSandboxRecord,
+  type PersistedSandboxState,
+  type SandboxLabelInput,
+  type StorageMode,
+  type ValidatedManagedSandbox,
+  type VolumeLabelInput,
+  type VolumeRecord,
+} from "./types.ts";
+
+const STORAGE_MODES: readonly StorageMode[] = ["git", "direct", "none"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isStorageMode(value: unknown): value is StorageMode {
+  return typeof value === "string" && STORAGE_MODES.includes(value as StorageMode);
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function finiteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/**
+ * SDK versions have returned labels both as maps and as entry/tuple arrays.
+ * Keep that tolerance in this module so callers never need to know the SDK shape.
+ */
+function normalizeLabels(value: unknown): Record<string, string> | null {
+  const labels: Record<string, string> = {};
+
+  if (isRecord(value)) {
+    for (const [key, labelValue] of Object.entries(value)) {
+      if (!key || labelValue === null || labelValue === undefined) continue;
+      if (
+        typeof labelValue === "string" ||
+        typeof labelValue === "number" ||
+        typeof labelValue === "boolean"
+      ) {
+        labels[key] = String(labelValue);
+      }
+    }
+    return labels;
+  }
+
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      let key: unknown;
+      let labelValue: unknown;
+
+      if (Array.isArray(entry)) {
+        [key, labelValue] = entry;
+      } else if (isRecord(entry)) {
+        key = entry.key ?? entry.name;
+        labelValue = entry.value;
+      }
+
+      if (
+        typeof key !== "string" ||
+        key.length === 0 ||
+        (typeof labelValue !== "string" &&
+          typeof labelValue !== "number" &&
+          typeof labelValue !== "boolean")
+      ) {
+        // A bad label entry must not make otherwise useful SDK output unusable.
+        continue;
+      }
+      labels[key] = String(labelValue);
+    }
+    return labels;
+  }
+
+  return null;
+}
+
+function rawRecord(value: unknown): Record<string, unknown> | null {
+  if (isRecord(value)) return value;
+
+  // Some CLI/SDK adapters expose a record as [name, labels]. Accept this only
+  // at the normalization boundary; all public functions return object records.
+  if (
+    Array.isArray(value) &&
+    value.length >= 2 &&
+    typeof value[0] === "string"
+  ) {
+    return { name: value[0], labels: value[1] };
+  }
+
+  return null;
+}
+
+function labelsFromRaw(raw: Record<string, unknown>): Record<string, string> | null {
+  const direct = raw.labels;
+  if (direct !== undefined) return normalizeLabels(direct);
+
+  const metadata = raw.metadata;
+  if (isRecord(metadata) && metadata.labels !== undefined) {
+    return normalizeLabels(metadata.labels);
+  }
+
+  return null;
+}
+
+function optionalString(
+  target: Record<string, unknown>,
+  key: string,
+  value: unknown,
+): void {
+  if (typeof value === "string") target[key] = value;
+  else delete target[key];
+}
+
+function optionalNumber(
+  target: Record<string, unknown>,
+  key: string,
+  value: unknown,
+): void {
+  if (finiteNumber(value)) target[key] = value;
+  else delete target[key];
+}
+
+export function buildSandboxLabels(input: SandboxLabelInput): Record<string, string> {
+  const labels: Record<string, string> = {
+    [LABEL_KEYS.managed]: "true",
+    [LABEL_KEYS.schema]: String(STATE_SCHEMA_VERSION),
+    [LABEL_KEYS.session]: input.sessionId,
+    [LABEL_KEYS.mode]: input.mode,
+    [LABEL_KEYS.cwd]: input.cwd,
+    [LABEL_KEYS.pid]: String(input.pid),
+    [LABEL_KEYS.image]: input.image,
+    [LABEL_KEYS.keep]: "true",
+  };
+
+  if (input.mode === "git") {
+    if (!nonEmptyString(input.volumeName)) {
+      throw new Error("git sandbox labels require a volume name");
+    }
+    labels[LABEL_KEYS.volume] = input.volumeName;
+    if (input.seedBranch !== undefined && input.seedBranch !== null) {
+      labels[LABEL_KEYS.seedBranch] = input.seedBranch;
+    }
+    if (input.seedSha !== undefined && input.seedSha !== null) {
+      labels[LABEL_KEYS.seedSha] = input.seedSha;
+    }
+  }
+
+  return labels;
+}
+
+export function buildVolumeLabels(input: VolumeLabelInput): Record<string, string> {
+  const labels: Record<string, string> = {
+    [LABEL_KEYS.managed]: "true",
+    [LABEL_KEYS.schema]: String(STATE_SCHEMA_VERSION),
+    [LABEL_KEYS.session]: input.sessionId,
+    [LABEL_KEYS.cwd]: input.cwd,
+    [LABEL_KEYS.keep]: "true",
+  };
+
+  if (input.seedBranch !== undefined && input.seedBranch !== null) {
+    labels[LABEL_KEYS.seedBranch] = input.seedBranch;
+  }
+  if (input.seedSha !== undefined && input.seedSha !== null) {
+    labels[LABEL_KEYS.seedSha] = input.seedSha;
+  }
+
+  return labels;
+}
+
+export function normalizeSandboxRecord(value: unknown): ManagedSandboxRecord | null {
+  const raw = rawRecord(value);
+  if (!raw) return null;
+
+  const labels = labelsFromRaw(raw);
+  const name = raw.name ?? raw.id ?? raw.sandboxName;
+  if (!labels || !nonEmptyString(name)) return null;
+
+  const normalized: Record<string, unknown> = { ...raw, name, labels };
+  optionalString(normalized, "status", raw.status ?? raw.state);
+  optionalNumber(normalized, "createdAt", raw.createdAt ?? raw.created_at);
+  return normalized as unknown as ManagedSandboxRecord;
+}
+
+export function normalizeVolumeRecord(value: unknown): VolumeRecord | null {
+  const raw = rawRecord(value);
+  if (!raw) return null;
+
+  const labels = labelsFromRaw(raw);
+  const name = raw.name ?? raw.id ?? raw.volumeName;
+  const hostPath = raw.hostPath ?? raw.path ?? raw.host_path;
+  if (!labels || !nonEmptyString(name) || !nonEmptyString(hostPath)) return null;
+
+  const normalized: Record<string, unknown> = { ...raw, name, hostPath, labels };
+  optionalString(normalized, "kind", raw.kind ?? raw.type);
+  optionalNumber(normalized, "usedBytes", raw.usedBytes ?? raw.used_bytes);
+  optionalNumber(normalized, "createdAt", raw.createdAt ?? raw.created_at);
+  return normalized as unknown as VolumeRecord;
+}
+
+export function parseCliSandboxList(json: string): ManagedSandboxRecord[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch (error) {
+    throw new Error("invalid sandbox list JSON", { cause: error });
+  }
+
+  let rows: unknown[];
+  if (Array.isArray(parsed)) {
+    rows = parsed;
+  } else if (isRecord(parsed) && Array.isArray(parsed.sandboxes)) {
+    rows = parsed.sandboxes;
+  } else {
+    throw new Error("invalid sandbox list shape: expected an array or {sandboxes: []}");
+  }
+
+  return rows
+    .map((row) => normalizeSandboxRecord(row))
+    .filter((row): row is ManagedSandboxRecord => row !== null);
+}
+
+export function validateManagedSandbox(
+  record: ManagedSandboxRecord,
+): ValidatedManagedSandbox | null {
+  if (!isRecord(record) || !nonEmptyString(record.name)) return null;
+
+  const labels = normalizeLabels(record.labels);
+  if (!labels) return null;
+
+  const sessionId = labels[LABEL_KEYS.session];
+  const mode = labels[LABEL_KEYS.mode];
+  const cwd = labels[LABEL_KEYS.cwd];
+  const image = labels[LABEL_KEYS.image];
+  const pidText = labels[LABEL_KEYS.pid];
+  const volumeName = labels[LABEL_KEYS.volume];
+
+  if (
+    labels[LABEL_KEYS.managed] !== "true" ||
+    labels[LABEL_KEYS.schema] !== String(STATE_SCHEMA_VERSION) ||
+    labels[LABEL_KEYS.keep] !== "true" ||
+    !nonEmptyString(sessionId) ||
+    !isStorageMode(mode) ||
+    !nonEmptyString(cwd) ||
+    !nonEmptyString(image) ||
+    !pidText ||
+    !/^\d+$/.test(pidText) ||
+    !Number.isSafeInteger(Number(pidText))
+  ) {
+    return null;
+  }
+
+  if (mode === "git" && !nonEmptyString(volumeName)) return null;
+  if (mode !== "git" && volumeName !== undefined) return null;
+
+  const normalized: Record<string, unknown> = {
+    ...record,
+    labels,
+    name: record.name,
+    sessionId,
+    mode,
+    cwd,
+  };
+  if (volumeName !== undefined && volumeName.length > 0) {
+    normalized.volumeName = volumeName;
+  } else {
+    delete normalized.volumeName;
+  }
+  return normalized as unknown as ValidatedManagedSandbox;
+}
+
+function validOptionalString(value: unknown): boolean {
+  return value === undefined || typeof value === "string";
+}
+
+function validOptionalNullableString(value: unknown): boolean {
+  return value === undefined || value === null || typeof value === "string";
+}
+
+function validPersistedState(value: Record<string, unknown>): boolean {
+  return (
+    value.version === STATE_SCHEMA_VERSION &&
+    nonEmptyString(value.sessionId) &&
+    nonEmptyString(value.sandboxName) &&
+    isStorageMode(value.mode) &&
+    nonEmptyString(value.cwd) &&
+    nonEmptyString(value.image) &&
+    typeof value.enabled === "boolean" &&
+    finiteNumber(value.createdAt) &&
+    validOptionalString(value.volumeName) &&
+    validOptionalString(value.volumeHostPath) &&
+    validOptionalNullableString(value.seedBranch) &&
+    validOptionalNullableString(value.seedSha)
+  );
+}
+
+export function encodeSessionState(
+  state: PersistedSandboxState,
+): PersistedSandboxState {
+  // Do not mutate a caller-owned object. Encoding always stamps the current
+  // schema so a state written by this module can never be mistaken for an old
+  // version after a future schema change.
+  return { ...state, version: STATE_SCHEMA_VERSION };
+}
+
+export function decodeSessionState(
+  value: unknown,
+  currentSessionId: string,
+): PersistedSandboxState | null {
+  if (!isRecord(value) || value.sessionId !== currentSessionId) return null;
+  if (!validPersistedState(value)) return null;
+
+  // Preserve forward-compatible, unknown JSON fields while replacing the
+  // validated known fields with their exact runtime values.
+  return { ...value, version: STATE_SCHEMA_VERSION } as PersistedSandboxState;
+}

package/extensions/pi-msb/locks.ts

@@ -0,0 +1,292 @@
+import { chmod, mkdir, open, readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+
+import { LOCKFILE_VERSION, resourceId } from "./types.ts";
+import type { LockHandle, LockInfo, LocksPort } from "./types.ts";
+
+/**
+ * The hooks are deliberately part of the options shape so unit tests can exercise
+ * the lifecycle without loading the native addon. Production callers leave them
+ * unset and use fs-ext below.
+ */
+export type FlockFn = (fd: number, operation: "exnb" | "un") => Promise<void>;
+
+export interface LocksOptions {
+  lockDir: string;
+  warn?: (message: string) => void;
+  flock?: FlockFn;
+  unlock?: (fd: number) => Promise<void>;
+}
+
+type FsExtCallback = (
+  fd: number,
+  operation: string,
+  callback: (error?: unknown) => void,
+) => void;
+type FsExtUnlockCallback = (fd: number, callback: (error?: unknown) => void) => void;
+type FsExtModule = {
+  flock?: FsExtCallback;
+  unlock?: FsExtUnlockCallback;
+};
+
+let fsExtPromise: Promise<FsExtModule> | undefined;
+
+// Keep the native dependency genuinely lazy and let extension-load/type-only
+// environments operate without resolving the optional native module.
+function importNativeModule(specifier: string): Promise<unknown> {
+  return import(specifier);
+}
+
+function errorCode(error: unknown): string | undefined {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    const code = (error as { code?: unknown }).code;
+    return typeof code === "string" ? code : undefined;
+  }
+  return undefined;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function unsupportedPlatformError(): Error {
+  return new Error(
+    "pi-microsandbox owner locks require POSIX flock(2) via fs-ext; this platform is unsupported (Windows LockFileEx is not implemented)",
+  );
+}
+
+async function loadFsExt(): Promise<FsExtModule> {
+  if (process.platform === "win32") throw unsupportedPlatformError();
+  fsExtPromise ??= importNativeModule("fs-ext").then((module) => {
+    const defaultExport = (module as unknown as { default?: unknown }).default;
+    const candidate = (defaultExport ?? module) as FsExtModule;
+    if (typeof candidate.flock !== "function") {
+      throw new Error("fs-ext loaded without flock(); refusing to use a racy PID fallback");
+    }
+    return candidate;
+  });
+  return fsExtPromise;
+}
+
+function callbackFlock(flock: FsExtCallback, fd: number, operation: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    try {
+      flock(fd, operation, (error) => (error ? reject(error) : resolve()));
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+function callbackUnlock(unlock: FsExtUnlockCallback, fd: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    try {
+      unlock(fd, (error) => (error ? reject(error) : resolve()));
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+interface LockOperations {
+  flock(fd: number): Promise<void>;
+  unlock(fd: number): Promise<void>;
+}
+
+async function lockOperations(opts: LocksOptions): Promise<LockOperations> {
+  if (opts.flock) {
+    return {
+      flock: (fd) => opts.flock!(fd, "exnb"),
+      unlock: (fd) => opts.unlock ? opts.unlock(fd) : opts.flock!(fd, "un"),
+    };
+  }
+
+  let module: FsExtModule;
+  try {
+    module = await loadFsExt();
+  } catch (error) {
+    throw new Error(
+      `Unable to load fs-ext for owner locks; refusing to use a racy PID fallback: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+  const flock = module.flock;
+  if (!flock) {
+    throw new Error("fs-ext does not provide flock(); refusing to use a racy PID fallback");
+  }
+  const unlock = module.unlock;
+  return {
+    flock: (fd) => callbackFlock(flock, fd, "exnb"),
+    unlock: (fd) => unlock
+      ? callbackUnlock(unlock, fd)
+      : callbackFlock(flock, fd, "un"),
+  };
+}
+
+function normalizeLockInfo(value: unknown): LockInfo | null {
+  if (typeof value !== "object" || value === null) return null;
+  const candidate = value as Partial<LockInfo>;
+  const { version, sessionId, sandboxName, volumeName, mode, cwd, pid, createdAt } = candidate;
+  if (version !== LOCKFILE_VERSION
+    || typeof sessionId !== "string" || sessionId.length === 0
+    || typeof sandboxName !== "string" || sandboxName.length === 0
+    || (volumeName !== undefined && (typeof volumeName !== "string" || volumeName.length === 0))
+    || (mode !== "git" && mode !== "direct" && mode !== "none")
+    || typeof cwd !== "string" || !isAbsolute(cwd)
+    || typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0
+    || typeof createdAt !== "number" || !Number.isFinite(createdAt)) {
+    return null;
+  }
+  return { version, sessionId, sandboxName, volumeName, mode, cwd, pid, createdAt };
+}
+
+function validLockInfo(value: unknown): value is LockInfo {
+  return normalizeLockInfo(value) !== null;
+}
+
+function lockInfoJson(info: LockInfo): string {
+  // Serialize only the contract fields. This keeps the lockfile a small, validated
+  // ownership record even if a caller passes an object with accidental extra fields.
+  const value: Record<string, unknown> = {
+    version: LOCKFILE_VERSION,
+    sessionId: info.sessionId,
+    sandboxName: info.sandboxName,
+    mode: info.mode,
+    cwd: info.cwd,
+    pid: info.pid,
+    createdAt: info.createdAt,
+  };
+  if (info.volumeName !== undefined) value.volumeName = info.volumeName;
+  return `${JSON.stringify(value)}\n`;
+}
+
+async function ensureLockDir(lockDir: string): Promise<void> {
+  try {
+    await mkdir(lockDir, { recursive: true, mode: 0o700 });
+    // mkdir's mode is ignored when the directory already exists.
+    await chmod(lockDir, 0o700);
+  } catch (error) {
+    throw new Error(`Unable to prepare owner lock directory ${lockDir}: ${errorMessage(error)}`, { cause: error });
+  }
+}
+
+export function lockPathFor(lockDir: string, sessionId: string): string {
+  return join(lockDir, `pi-msb-${resourceId(sessionId)}.lock`);
+}
+
+async function acquireLock(
+  opts: LocksOptions,
+  path: string,
+  info?: LockInfo,
+): Promise<LockHandle | null> {
+  await ensureLockDir(opts.lockDir);
+  const operations = await lockOperations(opts);
+  const file = await open(path, "a+", 0o600);
+
+  try {
+    try {
+      await operations.flock(file.fd);
+    } catch (error) {
+      if (errorCode(error) === "EAGAIN" || errorCode(error) === "EWOULDBLOCK") {
+        await file.close();
+        return null;
+      }
+      throw new Error(
+        `Unable to acquire non-blocking owner flock for ${path}: ${errorMessage(error)}`,
+        { cause: error },
+      );
+    }
+
+    try {
+      await file.chmod(0o600);
+      if (info) {
+        if (!validLockInfo(info)) throw new TypeError("Invalid owner lock information");
+        await file.truncate(0);
+        await file.writeFile(lockInfoJson(info), "utf8");
+        await file.sync();
+      }
+    } catch (error) {
+      try {
+        await operations.unlock(file.fd);
+      } finally {
+        await file.close();
+      }
+      throw new Error(`Unable to write owner lock ${path}: ${errorMessage(error)}`, { cause: error });
+    }
+
+    let releasePromise: Promise<void> | undefined;
+    return {
+      path,
+      release: () => {
+        releasePromise ??= (async () => {
+          let firstError: unknown;
+          try {
+            await operations.unlock(file.fd);
+          } catch (error) {
+            firstError = error;
+          }
+          try {
+            await file.close();
+          } catch (error) {
+            firstError ??= error;
+          }
+          if (firstError) {
+            throw new Error(`Unable to release owner flock for ${path}: ${errorMessage(firstError)}`, {
+              cause: firstError,
+            });
+          }
+        })();
+        return releasePromise;
+      },
+    };
+  } catch (error) {
+    // The contention path closes the descriptor itself. All other failures must
+    // close it too; the persistent inode is intentionally never unlinked.
+    if (errorCode(error) !== "EAGAIN" && errorCode(error) !== "EWOULDBLOCK") {
+      try {
+        await file.close();
+      } catch {
+        // Preserve the actionable acquisition/write error.
+      }
+    }
+    throw error;
+  }
+}
+
+export async function acquireOwnerLock(opts: LocksOptions, info: LockInfo): Promise<LockHandle | null> {
+  if (!validLockInfo(info)) throw new TypeError("Invalid owner lock information");
+  return acquireLock(opts, lockPathFor(opts.lockDir, info.sessionId), info);
+}
+
+export async function tryAcquireOrphanLock(
+  opts: LocksOptions,
+  sessionId: string,
+): Promise<LockHandle | null> {
+  if (typeof sessionId !== "string" || sessionId.length === 0) {
+    throw new TypeError("sessionId must be a non-empty string");
+  }
+  return acquireLock(opts, lockPathFor(opts.lockDir, sessionId));
+}
+
+export async function readLockInfo(path: string): Promise<LockInfo | null> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return null;
+    throw error;
+  }
+
+  try {
+    const value: unknown = JSON.parse(text);
+    return validLockInfo(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function createLocksPort(opts: LocksOptions): LocksPort {
+  return {
+    tryAcquire: (sessionId) => tryAcquireOrphanLock(opts, sessionId),
+  };
+}