@git.zone/cli 3.2.0 → 4.0.0

package/ts/mod_services/classes.servicedatamarker.ts

@@ -1,4 +1,5 @@
 import * as plugins from './mod.plugins.js';
+import { withInterProcessLock } from './classes.interprocesslock.js';
 
 /**
  * Canonical service identifiers used across mod_services.
@@ -8,9 +9,13 @@ import * as plugins from './mod.plugins.js';
  * `@git.zone/tsdeploy` (`deriveRequiredCapabilities`), so the strings and the
  * array shape must never change here.
  */
-export type TServiceName = 'mongodb' | 'minio' | 'elasticsearch';
+export type TServiceName = 'mongodb' | 'objectstorage' | 'elasticsearch';
+export type TLegacyServiceName = 'minio';
 
-export const serviceNames: TServiceName[] = ['mongodb', 'minio', 'elasticsearch'];
+export const serviceNames: TServiceName[] = ['mongodb', 'objectstorage', 'elasticsearch'];
+
+export const objectStorageImage =
+  'code.foss.global/lossless.zone/objectstorage@sha256:43b60897eed17b54feb4e363808ce540ed1d9d27201871c5c8a869300d41e1b8';
 
 /** Owner recorded in markers and container labels. */
 export const serviceDataOwner = '@git.zone/cli';
@@ -20,6 +25,10 @@ export const serviceToolLabel = 'gitzone-services';
 
 /** Marker file name, stored in `<projectPath>/.nogit/`. */
 export const serviceDataMarkerFile = '.gitzone-services.json';
+export const serviceDataMarkerSchemaVersion = 2;
+export const legacyMinioDataDirectoryName = 'miniodata';
+export const serviceOperationLabel = 'git.zone.operation';
+export const serviceBindOperation = 'service-bind-operation';
 
 /**
  * Directory basename used below `.nogit/` for each service's bind-mounted data.
@@ -28,18 +37,18 @@ export const serviceDataMarkerFile = '.gitzone-services.json';
  */
 export const serviceDataDirectoryNames: { [key in TServiceName]: string } = {
   mongodb: 'mongodata',
-  minio: 'miniodata',
+  objectstorage: 'objectstoragedata',
   elasticsearch: 'esdata',
 };
 
 /**
  * Image used to run each service, and therefore the image available to perform
- * a privileged cleanup of that service's data directory: if the data exists,
+ * a root-helper cleanup of that service's data directory: if the data exists,
  * the service ran, so its image is present locally.
  */
 export const serviceImages: { [key in TServiceName]: string } = {
   mongodb: 'mongo:7.0',
-  minio: 'minio/minio',
+  objectstorage: objectStorageImage,
   elasticsearch: 'elasticsearch:8.11.0',
 };
 
@@ -51,22 +60,36 @@ export interface IServiceDataMarkerEntry {
 export interface IServiceDataMarker {
   owner: string;
   kind: 'service-data';
-  schemaVersion: 1;
+  schemaVersion: 2;
   projectPath: string;
   safeToPrune: true;
   createdAt: string;
   dataDirectories: IServiceDataMarkerEntry[];
+  legacyDataDirectories?: ILegacyServiceDataMarkerEntry[];
+}
+
+export interface ILegacyServiceDataMarkerEntry {
+  service: TLegacyServiceName;
+  path: string;
+  safeToPrune: false;
 }
 
 const isPlainObject = (value: unknown): value is Record<string, any> => {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 };
 
+const hasOnlyKeys = (valueArg: Record<string, any>, allowedKeysArg: readonly string[]): boolean =>
+  Object.keys(valueArg).every((keyArg) => allowedKeysArg.includes(keyArg));
+
 /** Absolute path of the marker file for a project. */
 export const getServiceDataMarkerPath = (projectPathArg: string): string => {
   return plugins.path.join(plugins.path.resolve(projectPathArg), '.nogit', serviceDataMarkerFile);
 };
 
+export const getServiceDataMarkerLockPath = (projectPathArg: string): string => {
+  return `${getServiceDataMarkerPath(projectPathArg)}.lock`;
+};
+
 /**
  * Expected absolute data directory path for a service in a project.
  * `mod_services` must always derive data paths through this helper so that
@@ -83,8 +106,17 @@ export const getServiceDataDirectory = (
   );
 };
 
+/** Exact legacy path retained only for migration detection. */
+export const getLegacyMinioDataDirectory = (projectPathArg: string): string => {
+  return plugins.path.join(
+    plugins.path.resolve(projectPathArg),
+    '.nogit',
+    legacyMinioDataDirectoryName,
+  );
+};
+
 /**
- * True only when `candidatePathArg` is exactly one of the three data
+ * True only when `candidatePathArg` is exactly one of the canonical data
  * directories `gitzone services` creates for `projectPathArg`.
  *
  * This is an allowlist, not a denylist: any path that is not byte-for-byte one
@@ -104,31 +136,44 @@ export const isSafeServiceDataPath = (
   return false;
 };
 
-/** Validate an unknown value as a usable marker. */
+const hasValidMarkerEnvelope = (markerArg: Record<string, any>): boolean => {
+  return (
+    markerArg.owner === serviceDataOwner &&
+    markerArg.kind === 'service-data' &&
+    markerArg.safeToPrune === true &&
+    typeof markerArg.projectPath === 'string' &&
+    markerArg.projectPath.length > 0 &&
+    typeof markerArg.createdAt === 'string' &&
+    markerArg.createdAt.length > 0 &&
+    Array.isArray(markerArg.dataDirectories)
+  );
+};
+
+/** Validate an unknown value as a canonical v2 marker. */
 export const isValidServiceDataMarker = (markerArg: unknown): markerArg is IServiceDataMarker => {
   if (!isPlainObject(markerArg)) {
     return false;
   }
-  if (markerArg.owner !== serviceDataOwner) {
-    return false;
-  }
-  if (markerArg.kind !== 'service-data') {
-    return false;
-  }
-  if (markerArg.schemaVersion !== 1) {
-    return false;
-  }
-  if (markerArg.safeToPrune !== true) {
-    return false;
-  }
-  if (typeof markerArg.projectPath !== 'string' || !markerArg.projectPath) {
-    return false;
-  }
-  if (!Array.isArray(markerArg.dataDirectories)) {
+  if (
+    !hasOnlyKeys(markerArg, [
+      'owner',
+      'kind',
+      'schemaVersion',
+      'projectPath',
+      'safeToPrune',
+      'createdAt',
+      'dataDirectories',
+      'legacyDataDirectories',
+    ]) ||
+    !hasValidMarkerEnvelope(markerArg) ||
+    markerArg.schemaVersion !== serviceDataMarkerSchemaVersion
+  ) {
     return false;
   }
+  const projectPath = plugins.path.resolve(markerArg.projectPath);
+  const seenServices = new Set<TServiceName>();
   for (const entry of markerArg.dataDirectories) {
-    if (!isPlainObject(entry)) {
+    if (!isPlainObject(entry) || !hasOnlyKeys(entry, ['service', 'path'])) {
       return false;
     }
     if (!serviceNames.includes(entry.service)) {
@@ -137,10 +182,60 @@ export const isValidServiceDataMarker = (markerArg: unknown): markerArg is IServ
     if (typeof entry.path !== 'string' || !entry.path) {
       return false;
     }
+    if (
+      seenServices.has(entry.service) ||
+      plugins.path.resolve(entry.path) !== getServiceDataDirectory(projectPath, entry.service)
+    ) {
+      return false;
+    }
+    seenServices.add(entry.service);
+  }
+  if (markerArg.legacyDataDirectories !== undefined) {
+    if (!Array.isArray(markerArg.legacyDataDirectories)) {
+      return false;
+    }
+    for (const entry of markerArg.legacyDataDirectories) {
+      if (
+        !isPlainObject(entry) ||
+        !hasOnlyKeys(entry, ['service', 'path', 'safeToPrune']) ||
+        entry.service !== 'minio' ||
+        entry.safeToPrune !== false ||
+        typeof entry.path !== 'string' ||
+        plugins.path.resolve(entry.path) !== getLegacyMinioDataDirectory(projectPath)
+      ) {
+        return false;
+      }
+    }
+    if (markerArg.legacyDataDirectories.length > 1) {
+      return false;
+    }
   }
   return true;
 };
 
+const writeServiceDataMarker = async (
+  projectPathArg: string,
+  markerArg: IServiceDataMarker,
+): Promise<void> => {
+  const markerPath = getServiceDataMarkerPath(projectPathArg);
+  await plugins.smartfs.directory(plugins.path.dirname(markerPath)).recursive().create();
+  const tempPath = `${markerPath}.tmp-${process.pid}-${plugins.crypto
+    .randomBytes(12)
+    .toString('hex')}`;
+  try {
+    await plugins.fs.writeFile(tempPath, `${JSON.stringify(markerArg, null, 2)}\n`, {
+      encoding: 'utf8',
+      flag: 'wx',
+    });
+    await plugins.fs.rename(tempPath, markerPath);
+  } catch (error) {
+    await plugins.fs.rm(tempPath, { force: true }).catch(() => {});
+    throw new Error(`Could not persist service data marker atomically: ${markerPath}`, {
+      cause: error,
+    });
+  }
+};
+
 /** Read and validate the marker for a project, or undefined when absent/invalid. */
 export const readServiceDataMarker = async (
   projectPathArg: string,
@@ -152,18 +247,32 @@ export const readServiceDataMarker = async (
     }
     const content = (await plugins.smartfs.file(markerPath).encoding('utf8').read()) as string;
     const parsed = JSON.parse(content);
-    return isValidServiceDataMarker(parsed) ? parsed : undefined;
+    return isValidServiceDataMarker(parsed) &&
+      plugins.path.resolve(parsed.projectPath) === plugins.path.resolve(projectPathArg)
+      ? parsed
+      : undefined;
   } catch {
     return undefined;
   }
 };
 
+export const markerProvesServiceDataDirectory = (
+  markerArg: IServiceDataMarker | undefined,
+  projectPathArg: string,
+  serviceArg: TServiceName,
+): boolean => {
+  const expectedPath = getServiceDataDirectory(projectPathArg, serviceArg);
+  return !!markerArg?.dataDirectories.some(
+    (entry) => entry.service === serviceArg && plugins.path.resolve(entry.path) === expectedPath,
+  );
+};
+
 /**
  * Record that `gitzone services` owns a data directory for this project.
  *
  * The marker lives in `.nogit/` rather than inside the bind-mounted data
- * directory itself, so it can never confuse mongod, MinIO or Elasticsearch at
- * runtime. Entries are merged so enabling a service later does not drop the
+ * directory itself, so it can never confuse a service runtime. Entries are
+ * merged so enabling a service later does not drop the
  * claim on previously created directories.
  */
 export const recordServiceDataDirectory = async (
@@ -171,31 +280,44 @@ export const recordServiceDataDirectory = async (
   serviceArg: TServiceName,
 ): Promise<void> => {
   const projectPath = plugins.path.resolve(projectPathArg);
-  const dataPath = getServiceDataDirectory(projectPath, serviceArg);
-  const existingMarker = await readServiceDataMarker(projectPath);
-
-  const entries: IServiceDataMarkerEntry[] = existingMarker
-    ? existingMarker.dataDirectories.filter((entry) => entry.service !== serviceArg)
-    : [];
-  entries.push({ service: serviceArg, path: dataPath });
-  entries.sort((entryA, entryB) => entryA.service.localeCompare(entryB.service));
-
-  const marker: IServiceDataMarker = {
-    owner: serviceDataOwner,
-    kind: 'service-data',
-    schemaVersion: 1,
-    projectPath,
-    safeToPrune: true,
-    createdAt: existingMarker?.createdAt || new Date().toISOString(),
-    dataDirectories: entries,
-  };
+  await withInterProcessLock(
+    {
+      lockPath: getServiceDataMarkerLockPath(projectPath),
+      description: 'Service data marker',
+    },
+    async () => {
+      const dataPath = getServiceDataDirectory(projectPath, serviceArg);
+      const markerPath = getServiceDataMarkerPath(projectPath);
+      const markerExists = await plugins.smartfs.file(markerPath).exists();
+      const existingMarker = await readServiceDataMarker(projectPath);
+      if (markerExists && !existingMarker) {
+        throw new Error(
+          `Refusing to overwrite invalid or foreign service data marker: ${markerPath}`,
+        );
+      }
 
-  const markerPath = getServiceDataMarkerPath(projectPath);
-  await plugins.smartfs.directory(plugins.path.dirname(markerPath)).recursive().create();
-  await plugins.smartfs
-    .file(markerPath)
-    .encoding('utf8')
-    .write(`${JSON.stringify(marker, null, 2)}\n`);
+      const entries: IServiceDataMarkerEntry[] = existingMarker
+        ? existingMarker.dataDirectories.filter((entry) => entry.service !== serviceArg)
+        : [];
+      entries.push({ service: serviceArg, path: dataPath });
+      entries.sort((entryA, entryB) => entryA.service.localeCompare(entryB.service));
+
+      const marker: IServiceDataMarker = {
+        owner: serviceDataOwner,
+        kind: 'service-data',
+        schemaVersion: serviceDataMarkerSchemaVersion,
+        projectPath,
+        safeToPrune: true,
+        createdAt: existingMarker?.createdAt || new Date().toISOString(),
+        dataDirectories: entries,
+        ...(existingMarker?.legacyDataDirectories
+          ? { legacyDataDirectories: existingMarker.legacyDataDirectories }
+          : {}),
+      };
+
+      await writeServiceDataMarker(projectPath, marker);
+    },
+  );
 };
 
 /**
@@ -219,6 +341,22 @@ export const getServiceContainerLabels = (optionsArg: {
   };
 };
 
+export const hasExactServiceContainerLabels = (
+  labelsArg: Record<string, string>,
+  expectedArg: Record<string, string>,
+): boolean => {
+  const actualGitZoneLabels = Object.entries(labelsArg).filter(([key]) =>
+    key.startsWith('git.zone.'),
+  );
+  const expectedGitZoneLabels = Object.entries(expectedArg).filter(([key]) =>
+    key.startsWith('git.zone.'),
+  );
+  return (
+    actualGitZoneLabels.length === expectedGitZoneLabels.length &&
+    expectedGitZoneLabels.every(([key, value]) => labelsArg[key] === value)
+  );
+};
+
 /** True when a container's labels prove `gitzone services` created it. */
 export const isServiceOwnedByLabels = (labelsArg: { [key: string]: string }): boolean => {
   return (
@@ -226,3 +364,23 @@ export const isServiceOwnedByLabels = (labelsArg: { [key: string]: string }): bo
     labelsArg['git.zone.safe-to-prune'] === 'true'
   );
 };
+
+/** Legacy provider evidence is retained for migration, never active lifecycle ownership. */
+export const isLegacyMinioContainerLabels = (labelsArg: {
+  [key: string]: string;
+}): boolean => {
+  return (
+    labelsArg['git.zone.tool'] === serviceToolLabel &&
+    labelsArg['git.zone.service'] === 'minio'
+  );
+};
+
+/** Transient bind-operation containers are owned by their invocation, not by prune. */
+export const isServiceOperationHelperLabels = (labelsArg: {
+  [key: string]: string;
+}): boolean => {
+  return (
+    labelsArg['git.zone.tool'] === serviceToolLabel &&
+    labelsArg[serviceOperationLabel] === serviceBindOperation
+  );
+};