@git.zone/cli 3.2.0 → 4.0.0

package/ts/mod_services/classes.globalregistrystore.ts

@@ -0,0 +1,279 @@
+import * as plugins from '../plugins.js';
+import { InterProcessLock } from './classes.interprocesslock.js';
+
+export interface IRegisteredProject {
+  projectPath: string;
+  projectName: string;
+  containers: {
+    mongo?: string;
+    objectstorage?: string;
+    elasticsearch?: string;
+  };
+  ports: {
+    mongo?: number;
+    s3?: number;
+    s3Ui?: number;
+    elasticsearch?: number;
+  };
+  legacy?: {
+    /** Preserved migration evidence. Never passed to an active lifecycle operation. */
+    minioContainer?: string;
+  };
+  enabledServices: string[];
+  lastActive: number;
+}
+
+export interface IGlobalRegistryData {
+  schemaVersion: 2;
+  projects: { [projectPath: string]: IRegisteredProject };
+}
+
+const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> => {
+  return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+};
+
+const assertAllowedKeys = (
+  valueArg: Record<string, unknown>,
+  allowedKeysArg: readonly string[],
+  contextArg: string,
+): void => {
+  if (Object.keys(valueArg).some((keyArg) => !allowedKeysArg.includes(keyArg))) {
+    throw new Error(`Global services registry ${contextArg} contains unsupported fields.`);
+  }
+};
+
+const assertOptionalStrings = (
+  valueArg: Record<string, unknown>,
+  keysArg: readonly string[],
+  contextArg: string,
+): void => {
+  for (const key of keysArg) {
+    if (valueArg[key] !== undefined && (typeof valueArg[key] !== 'string' || !valueArg[key])) {
+      throw new Error(
+        `Global services registry ${contextArg}.${key} must be a non-empty string.`,
+      );
+    }
+  }
+};
+
+const assertOptionalNumbers = (
+  valueArg: Record<string, unknown>,
+  keysArg: readonly string[],
+  contextArg: string,
+): void => {
+  for (const key of keysArg) {
+    const value = valueArg[key];
+    if (value !== undefined && (typeof value !== 'number' || !Number.isFinite(value))) {
+      throw new Error(
+        `Global services registry ${contextArg}.${key} must be a finite number.`,
+      );
+    }
+  }
+};
+
+/** Validate the canonical runtime schema after startup migrations have completed. */
+export const assertCanonicalGlobalRegistryData = (
+  dataArg: unknown,
+): IGlobalRegistryData => {
+  if (!isPlainObject(dataArg)) {
+    throw new Error('Global services registry root must be a JSON object.');
+  }
+  assertAllowedKeys(dataArg, ['schemaVersion', 'projects'], 'root');
+  if (dataArg.schemaVersion !== 2 || !isPlainObject(dataArg.projects)) {
+    throw new Error('Global services registry requires canonical schema version 2.');
+  }
+  for (const [projectPath, rawProject] of Object.entries(dataArg.projects)) {
+    if (!isPlainObject(rawProject)) {
+      throw new Error(
+        `Global services registry project ${projectPath} must be a JSON object.`,
+      );
+    }
+    assertAllowedKeys(
+      rawProject,
+      [
+        'projectPath',
+        'projectName',
+        'containers',
+        'ports',
+        'legacy',
+        'enabledServices',
+        'lastActive',
+      ],
+      `project ${projectPath}`,
+    );
+    if (
+      typeof rawProject.projectPath !== 'string' ||
+      !rawProject.projectPath ||
+      plugins.path.resolve(rawProject.projectPath) !== plugins.path.resolve(projectPath)
+    ) {
+      throw new Error(
+        `Global services registry project ${projectPath} has an invalid or inconsistent path.`,
+      );
+    }
+    if (typeof rawProject.projectName !== 'string' || !rawProject.projectName) {
+      throw new Error(
+        `Global services registry project ${projectPath} has an invalid name.`,
+      );
+    }
+    if (!isPlainObject(rawProject.containers) || !isPlainObject(rawProject.ports)) {
+      throw new Error(
+        `Global services registry project ${projectPath} requires container and port objects.`,
+      );
+    }
+    if (!Array.isArray(rawProject.enabledServices)) {
+      throw new Error(
+        `Global services registry project ${projectPath} has invalid enabled services.`,
+      );
+    }
+    const canonicalServices = ['mongodb', 'objectstorage', 'elasticsearch'];
+    if (
+      !rawProject.enabledServices.every(
+        (serviceArg) =>
+          typeof serviceArg === 'string' && canonicalServices.includes(serviceArg),
+      ) ||
+      new Set(rawProject.enabledServices).size !== rawProject.enabledServices.length
+    ) {
+      throw new Error(
+        `Global services registry project ${projectPath} has noncanonical enabled services.`,
+      );
+    }
+    if (typeof rawProject.lastActive !== 'number' || !Number.isFinite(rawProject.lastActive)) {
+      throw new Error(
+        `Global services registry project ${projectPath} has an invalid lastActive value.`,
+      );
+    }
+    const rawContainers = rawProject.containers;
+    const rawPorts = rawProject.ports;
+    assertAllowedKeys(
+      rawContainers,
+      ['mongo', 'objectstorage', 'elasticsearch'],
+      `project ${projectPath} containers`,
+    );
+    assertOptionalStrings(
+      rawContainers,
+      ['mongo', 'objectstorage', 'elasticsearch'],
+      `project ${projectPath}.containers`,
+    );
+    assertAllowedKeys(
+      rawPorts,
+      ['mongo', 's3', 's3Ui', 'elasticsearch'],
+      `project ${projectPath} ports`,
+    );
+    assertOptionalNumbers(
+      rawPorts,
+      ['mongo', 's3', 's3Ui', 'elasticsearch'],
+      `project ${projectPath}.ports`,
+    );
+    if (rawProject.legacy !== undefined) {
+      if (!isPlainObject(rawProject.legacy)) {
+        throw new Error(
+          `Global services registry project ${projectPath} has invalid legacy evidence.`,
+        );
+      }
+      assertAllowedKeys(rawProject.legacy, ['minioContainer'], `project ${projectPath} legacy`);
+      assertOptionalStrings(
+        rawProject.legacy,
+        ['minioContainer'],
+        `project ${projectPath}.legacy`,
+      );
+      if (!rawProject.legacy.minioContainer) {
+        throw new Error(
+          `Global services registry project ${projectPath} has empty legacy evidence.`,
+        );
+      }
+    }
+  }
+  return dataArg as unknown as IGlobalRegistryData;
+};
+
+export interface IGlobalRegistryTransactionResult<T> {
+  result: T;
+  writeData?: IGlobalRegistryData;
+}
+
+export interface IGlobalRegistryStoreOptions {
+  filePath?: string;
+  lockTimeoutMs?: number;
+  lockPollMs?: number;
+}
+
+/** Raw, atomically replaced registry storage shared by runtime and migrations. */
+export class GlobalRegistryStore {
+  public readonly filePath: string;
+  private readonly lock: InterProcessLock;
+
+  constructor(optionsArg: IGlobalRegistryStoreOptions = {}) {
+    this.filePath = plugins.path.resolve(
+      optionsArg.filePath ||
+        plugins.path.join(
+          plugins.smartpath.get.home(),
+          '.smartconfig',
+          'kv',
+          'gitzone-services.json',
+        ),
+    );
+    this.lock = new InterProcessLock({
+      lockPath: `${this.filePath}.lock`,
+      description: 'Global services registry',
+      timeoutMs: optionsArg.lockTimeoutMs,
+      pollMs: optionsArg.lockPollMs,
+    });
+  }
+
+  public async readRaw(): Promise<unknown> {
+    let content: string;
+    try {
+      content = await plugins.fs.readFile(this.filePath, 'utf8');
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return {};
+      }
+      throw new Error('Global services registry could not be read.', { cause: error });
+    }
+    try {
+      return JSON.parse(content);
+    } catch (error) {
+      throw new Error('Global services registry contains invalid JSON.', { cause: error });
+    }
+  }
+
+  public async readCanonical(): Promise<IGlobalRegistryData> {
+    return assertCanonicalGlobalRegistryData(await this.readRaw());
+  }
+
+  public async transact<T>(
+    operationArg: (
+      rawDataArg: unknown,
+    ) => Promise<IGlobalRegistryTransactionResult<T>> | IGlobalRegistryTransactionResult<T>,
+  ): Promise<T> {
+    return this.lock.runExclusive(async () => {
+      const transaction = await operationArg(await this.readRaw());
+      if (transaction.writeData) {
+        await this.writeAtomic(assertCanonicalGlobalRegistryData(transaction.writeData));
+      }
+      return transaction.result;
+    });
+  }
+
+  private async writeAtomic(dataArg: IGlobalRegistryData): Promise<void> {
+    await plugins.fs.mkdir(plugins.path.dirname(this.filePath), { recursive: true });
+    const tempPath = `${this.filePath}.tmp-${process.pid}-${plugins.crypto
+      .randomBytes(12)
+      .toString('hex')}`;
+    let handle: Awaited<ReturnType<typeof plugins.fs.open>> | undefined;
+    try {
+      handle = await plugins.fs.open(tempPath, 'wx', 0o600);
+      await handle.writeFile(`${JSON.stringify(dataArg, null, 2)}\n`, 'utf8');
+      await handle.sync();
+      await handle.close();
+      handle = undefined;
+      await plugins.fs.rename(tempPath, this.filePath);
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      await plugins.fs.rm(tempPath, { force: true }).catch(() => {});
+      throw new Error('Global services registry could not be written atomically.', {
+        cause: error,
+      });
+    }
+  }
+}

package/ts/mod_services/classes.interprocesslock.ts

@@ -0,0 +1,189 @@
+import * as plugins from '../plugins.js';
+import type { TServiceName } from './classes.servicedatamarker.js';
+
+interface ILockOwner {
+  token: string;
+  pid: number;
+  createdAt: string;
+}
+
+export interface IInterProcessLockOptions {
+  lockPath: string;
+  description: string;
+  timeoutMs?: number;
+  pollMs?: number;
+}
+
+const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> => {
+  return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+};
+
+/** Atomic-mkdir lock with bounded waiting and manual-only stale-lock recovery. */
+export class InterProcessLock {
+  public readonly lockPath: string;
+  private readonly description: string;
+  private readonly timeoutMs: number;
+  private readonly pollMs: number;
+
+  constructor(optionsArg: IInterProcessLockOptions) {
+    this.lockPath = plugins.path.resolve(optionsArg.lockPath);
+    this.description = optionsArg.description;
+    this.timeoutMs = optionsArg.timeoutMs ?? 5_000;
+    this.pollMs = optionsArg.pollMs ?? 25;
+    if (!this.description) {
+      throw new Error('Interprocess lock description must not be empty.');
+    }
+    if (!Number.isSafeInteger(this.timeoutMs) || this.timeoutMs <= 0) {
+      throw new Error('Interprocess lock timeout must be a positive safe integer.');
+    }
+    if (!Number.isSafeInteger(this.pollMs) || this.pollMs <= 0) {
+      throw new Error('Interprocess lock poll interval must be a positive safe integer.');
+    }
+  }
+
+  public async runExclusive<T>(operationArg: () => Promise<T>): Promise<T> {
+    const release = await this.acquire();
+    let result: T | undefined;
+    let primaryError: unknown;
+    try {
+      result = await operationArg();
+    } catch (error) {
+      primaryError = error;
+    }
+
+    let releaseError: unknown;
+    try {
+      await release();
+    } catch (error) {
+      releaseError = error;
+    }
+    if (primaryError && releaseError) {
+      throw new AggregateError(
+        [primaryError, releaseError],
+        `${this.description} failed and its lock could not be released.`,
+      );
+    }
+    if (primaryError) {
+      throw primaryError;
+    }
+    if (releaseError) {
+      throw releaseError;
+    }
+    return result as T;
+  }
+
+  private async acquire(): Promise<() => Promise<void>> {
+    await plugins.fs.mkdir(plugins.path.dirname(this.lockPath), { recursive: true });
+    const owner: ILockOwner = {
+      token: plugins.crypto.randomBytes(16).toString('hex'),
+      pid: process.pid,
+      createdAt: new Date().toISOString(),
+    };
+    const ownerPath = plugins.path.join(this.lockPath, 'owner.json');
+    const deadlineAt = Date.now() + this.timeoutMs;
+
+    while (true) {
+      try {
+        await plugins.fs.mkdir(this.lockPath);
+        try {
+          await plugins.fs.writeFile(ownerPath, `${JSON.stringify(owner)}\n`, {
+            encoding: 'utf8',
+            flag: 'wx',
+            mode: 0o600,
+          });
+        } catch (error) {
+          await this.release(owner.token, false).catch(() => {});
+          throw error;
+        }
+        return async () => this.release(owner.token, true);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+          throw new Error(`${this.description} lock could not be acquired.`, { cause: error });
+        }
+        const remaining = deadlineAt - Date.now();
+        if (remaining <= 0) {
+          let ownerDescription = 'owner metadata unavailable';
+          try {
+            const existingOwner = JSON.parse(await plugins.fs.readFile(ownerPath, 'utf8')) as {
+              pid?: unknown;
+              createdAt?: unknown;
+            };
+            if (
+              typeof existingOwner.pid === 'number' &&
+              typeof existingOwner.createdAt === 'string'
+            ) {
+              ownerDescription = `pid ${existingOwner.pid}, created ${existingOwner.createdAt}`;
+            }
+          } catch {
+            // Incomplete stale locks remain fail-closed and require operator review.
+          }
+          throw new Error(
+            `${this.description} is locked (${ownerDescription}). ` +
+              `If that process no longer exists, inspect and remove ${this.lockPath}.`,
+          );
+        }
+        await plugins.smartdelay.delayFor(Math.min(this.pollMs, remaining));
+      }
+    }
+  }
+
+  private async release(tokenArg: string, requireOwnerArg: boolean): Promise<void> {
+    const ownerPath = plugins.path.join(this.lockPath, 'owner.json');
+    if (requireOwnerArg) {
+      let owner: unknown;
+      try {
+        owner = JSON.parse(await plugins.fs.readFile(ownerPath, 'utf8'));
+      } catch (error) {
+        throw new Error(`${this.description} lock ownership could not be verified.`, {
+          cause: error,
+        });
+      }
+      if (!isPlainObject(owner) || owner.token !== tokenArg) {
+        throw new Error(`${this.description} lock ownership changed before release.`);
+      }
+    }
+
+    const tombstonePath = `${this.lockPath}.release-${tokenArg}`;
+    await plugins.fs.rename(this.lockPath, tombstonePath);
+    await plugins.fs.rm(tombstonePath, { recursive: true, force: false });
+  }
+}
+
+export const withInterProcessLock = async <T>(
+  optionsArg: IInterProcessLockOptions,
+  operationArg: () => Promise<T>,
+): Promise<T> => {
+  return new InterProcessLock(optionsArg).runExclusive(operationArg);
+};
+
+export const getServiceDataOperationLockPath = (
+  projectPathArg: string,
+  serviceArg: TServiceName,
+): string => {
+  const projectHash = plugins.crypto
+    .createHash('sha256')
+    .update(plugins.path.resolve(projectPathArg))
+    .digest('hex')
+    .slice(0, 32);
+  return plugins.path.join(
+    plugins.smartpath.get.home(),
+    '.smartconfig',
+    'kv',
+    'gitzone-services-locks',
+    `${projectHash}-${serviceArg}.lock`,
+  );
+};
+
+export const withServiceDataOperationLock = async <T>(
+  projectPathArg: string,
+  serviceArg: TServiceName,
+  operationArg: () => Promise<T>,
+): Promise<T> => {
+  return withInterProcessLock(
+    {
+      lockPath: getServiceDataOperationLockPath(projectPathArg, serviceArg),
+      description: `${serviceArg} service data operation`,
+    },
+    operationArg,
+  );
+};