@foss.global/gitmanager 2.0.0 → 2.2.0

package/ts/classes.archiveinspection.ts

@@ -0,0 +1,245 @@
+import * as plugins from './plugins.js';
+import { GitManagerError } from './classes.gitmanagererror.js';
+import type {
+  IGitManagerArchiveInspection,
+  IGitManagerArchiveInspectionRequest,
+} from './models.js';
+
+/** The fixed ci-spec path-metadata ceiling of every archive. */
+export const gitManagerArchivePathMetadataCeilingBytes = 134_217_728;
+
+const maxInspectorOutputBytes = 64 * 1024;
+
+type TInspectorSettlement =
+  | { kind: 'closed'; code: number | null; signal: NodeJS.Signals | null }
+  | { kind: 'spawnFailed'; error: Error };
+
+const assertLimit = (
+  nameArg: string,
+  valueArg: number,
+  minimumArg: number,
+  maximumArg: number,
+): void => {
+  if (!Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new TypeError(
+      `${nameArg} must be a safe integer between ${minimumArg} and ${maximumArg}.`,
+    );
+  }
+};
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const isCount = (valueArg: unknown): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 0;
+
+/**
+ * Parses the inspector's single JSON result: the recomputed metadata of an
+ * accepted archive, or a thrown `GitManagerError` for a refused one.
+ */
+const parseInspectorResult = (stdoutArg: string): IGitManagerArchiveInspection => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdoutArg);
+  } catch (error) {
+    throw new Error('Archive inspector returned invalid JSON', { cause: error });
+  }
+  if (isRecord(parsed) && parsed.status === 'rejected' && typeof parsed.message === 'string') {
+    if (parsed.reason === 'limitExceeded') {
+      throw new GitManagerError('archiveLimitExceeded', parsed.message);
+    }
+    if (parsed.reason === 'invalid') {
+      throw new GitManagerError('archiveRejected', parsed.message);
+    }
+  }
+  if (
+    isRecord(parsed)
+    && parsed.status === 'accepted'
+    && isCount(parsed.sizeBytes)
+    && typeof parsed.sha256 === 'string'
+    && /^[0-9a-f]{64}$/.test(parsed.sha256)
+    && isCount(parsed.extractedSizeBytes)
+    && isCount(parsed.entryCount)
+    && isCount(parsed.pathMetadataBytes)
+  ) {
+    return {
+      sizeBytes: parsed.sizeBytes,
+      sha256: parsed.sha256,
+      extractedSizeBytes: parsed.extractedSizeBytes,
+      entryCount: parsed.entryCount,
+      pathMetadataBytes: parsed.pathMetadataBytes,
+    };
+  }
+  throw new Error('Archive inspector returned an invalid result');
+};
+
+/**
+ * Streams one archive into a dedicated engine inspector process and returns
+ * its recomputed metadata. The inspector reads until the archive is accepted
+ * or the first violation; on a refusal the remaining input is not read and
+ * the source is closed. Aborting `signalArg` kills the inspector and rejects
+ * with the abort reason once the process has exited.
+ */
+export const runArchiveInspection = async (
+  binaryPathArg: string,
+  requestArg: IGitManagerArchiveInspectionRequest,
+  signalArg: AbortSignal,
+): Promise<IGitManagerArchiveInspection> => {
+  const maxPathMetadataBytes =
+    requestArg.maxPathMetadataBytes ?? gitManagerArchivePathMetadataCeilingBytes;
+  assertLimit('maxCompressedBytes', requestArg.maxCompressedBytes, 0, Number.MAX_SAFE_INTEGER);
+  assertLimit('maxExtractedBytes', requestArg.maxExtractedBytes, 0, Number.MAX_SAFE_INTEGER);
+  assertLimit('maxEntries', requestArg.maxEntries, 0, Number.MAX_SAFE_INTEGER);
+  assertLimit(
+    'maxPathMetadataBytes',
+    maxPathMetadataBytes,
+    1,
+    gitManagerArchivePathMetadataCeilingBytes,
+  );
+  if (signalArg.aborted) {
+    throw signalArg.reason;
+  }
+
+  const child = plugins.childProcess.spawn(binaryPathArg, [
+    '--inspect-archive-stream',
+    '--max-compressed-bytes',
+    String(requestArg.maxCompressedBytes),
+    '--max-extracted-bytes',
+    String(requestArg.maxExtractedBytes),
+    '--max-entries',
+    String(requestArg.maxEntries),
+    '--max-path-metadata-bytes',
+    String(maxPathMetadataBytes),
+  ], { stdio: ['pipe', 'pipe', 'pipe'] });
+  const killInspector = (): void => {
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill('SIGKILL');
+    }
+  };
+
+  const settled = new Promise<TInspectorSettlement>((resolve) => {
+    child.once('error', (error) => {
+      killInspector();
+      resolve({ kind: 'spawnFailed', error });
+    });
+    child.once('close', (code, signal) => resolve({ kind: 'closed', code, signal }));
+  });
+  let inspectorSettled = false;
+  void settled.then(() => {
+    inspectorSettled = true;
+  });
+
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+  let outputBytes = 0;
+  let outputOverflow = false;
+  const collect = (chunksArg: Buffer[]) => (chunkArg: Buffer): void => {
+    outputBytes += chunkArg.byteLength;
+    if (outputBytes > maxInspectorOutputBytes) {
+      outputOverflow = true;
+      killInspector();
+      return;
+    }
+    chunksArg.push(chunkArg);
+  };
+  child.stdout.on('data', collect(stdoutChunks));
+  child.stderr.on('data', collect(stderrChunks));
+
+  // A write error is the inspector closing its input after a refusal (or
+  // dying); its exit status and result decide the outcome.
+  child.stdin.on('error', () => undefined);
+
+  let aborted = false;
+  const abortInspection = (): void => {
+    aborted = true;
+    killInspector();
+  };
+  signalArg.addEventListener('abort', abortInspection, { once: true });
+
+  let delivered = false;
+  let sourceFailure: { error: unknown } | undefined;
+  const waitForDrain = (): Promise<unknown> => Promise.race([
+    new Promise<void>((resolve) => {
+      const done = (): void => {
+        child.stdin.off('drain', done);
+        child.stdin.off('close', done);
+        resolve();
+      };
+      child.stdin.once('drain', done);
+      child.stdin.once('close', done);
+    }),
+    settled,
+  ]);
+  const feed = async (): Promise<void> => {
+    const archive = requestArg.archive;
+    if (archive instanceof Uint8Array) {
+      child.stdin.end(archive);
+      delivered = true;
+      return;
+    }
+    const iterator = archive[Symbol.asyncIterator]();
+    let exhausted = false;
+    try {
+      while (!inspectorSettled) {
+        const step = await Promise.race([
+          iterator.next().then((result) => ({ kind: 'chunk' as const, result })),
+          settled.then(() => ({ kind: 'settled' as const })),
+        ]);
+        if (step.kind === 'settled' || inspectorSettled) {
+          return;
+        }
+        if (step.result.done) {
+          exhausted = true;
+          child.stdin.end();
+          delivered = true;
+          return;
+        }
+        if (!(step.result.value instanceof Uint8Array)) {
+          throw new TypeError('The archive stream must yield Uint8Array chunks.');
+        }
+        if (!child.stdin.write(step.result.value)) {
+          await waitForDrain();
+        }
+      }
+    } catch (error) {
+      sourceFailure = { error };
+      killInspector();
+    } finally {
+      if (!exhausted && !sourceFailure) {
+        // Close the source like a `for await` loop that stops early; a
+        // stalled source must not hold the inspection open.
+        void Promise.resolve(iterator.return?.()).catch(() => undefined);
+      }
+    }
+  };
+
+  try {
+    const [settlement] = await Promise.all([settled, feed()]);
+    if (aborted) {
+      throw signalArg.reason;
+    }
+    if (sourceFailure) {
+      throw sourceFailure.error;
+    }
+    if (settlement.kind === 'spawnFailed') {
+      throw new Error('Failed to spawn the archive inspector', { cause: settlement.error });
+    }
+    if (outputOverflow) {
+      throw new Error('Archive inspector output exceeded its limit');
+    }
+    if (settlement.code !== 0) {
+      const stderr = Buffer.concat(stderrChunks).toString('utf8').trim();
+      throw new Error(
+        `Archive inspector failed with ${settlement.signal ?? `status ${settlement.code}`}`
+          + (stderr ? `: ${stderr}` : ''),
+      );
+    }
+    const inspection = parseInspectorResult(Buffer.concat(stdoutChunks).toString('utf8'));
+    if (!delivered) {
+      throw new Error('Archive inspector accepted an archive that was not completely delivered');
+    }
+    return inspection;
+  } finally {
+    signalArg.removeEventListener('abort', abortInspection);
+  }
+};

package/ts/classes.gitmanager.ts

@@ -1,5 +1,9 @@
 import * as plugins from './plugins.js';
 import type {
+  IGitManagerAncestryRequest,
+  IGitManagerArchiveInspection,
+  IGitManagerArchiveInspectionOptions,
+  IGitManagerArchiveInspectionRequest,
   IGitManagerCommitDetail,
   IGitManagerCommitRequest,
   IGitManagerCommitSummary,
@@ -41,6 +45,7 @@ import type {
 } from './models.js';
 import { RustGitManagerBridge } from './rust-gitmanager-bridge.js';
 import { GitManagerRepositoryService } from './classes.repositoryservice.js';
+import { runArchiveInspection } from './classes.archiveinspection.js';
 
 const readinessDefaultTimeoutMs = 2_000;
 const readinessMaximumTimeoutMs = 30_000;
@@ -56,6 +61,7 @@ export class GitManager extends plugins.EventEmitter {
   private stopPromise: Promise<void> | null = null;
   private config: IRustGitManagerConfig;
   private readonly repositoryServices = new Set<GitManagerRepositoryService>();
+  private readonly archiveInspections = new Map<AbortController, Promise<unknown>>();
   private lifecycleEpoch = 0;
   private smartHttpProbeUrl: string | null = null;
   private readonly activeReadinessControllers = new Set<AbortController>();
@@ -168,12 +174,14 @@ export class GitManager extends plugins.EventEmitter {
     }
     if (!this.bridge.running) {
       await this.closeRepositoryServices();
+      await this.abortArchiveInspections();
       await this.bridge.terminate();
       this.started = false;
       return;
     }
     try {
       await this.closeRepositoryServices();
+      await this.abortArchiveInspections();
       await this.bridge.stopGitManager();
     } finally {
       await this.bridge.terminate();
@@ -440,6 +448,51 @@ export class GitManager extends plugins.EventEmitter {
     return this.bridge.readFile(requestArg);
   }
 
+  /**
+   * Answers `git merge-base --is-ancestor` exactly within a work budget.
+   * Anything short of an exact answer throws a `GitManagerError`
+   * (`invalidObjectId`, `objectNotFound`, `objectNotCommit`,
+   * `ancestryBudgetExceeded`); it never degrades to `false`.
+   */
+  public async isAncestor(requestArg: IGitManagerAncestryRequest): Promise<boolean> {
+    this.assertRunning();
+    return this.bridge.isAncestor(requestArg);
+  }
+
+  /**
+   * Inspects a receiver-side `tar.gz` archive in a dedicated engine process:
+   * recomputes its compressed size, SHA-256, extracted bytes, entry count,
+   * and path metadata bytes while enforcing the limits and the ci-spec path
+   * and link rules. A refused archive throws a `GitManagerError` with code
+   * `archiveLimitExceeded` or `archiveRejected`; an invalid limit throws a
+   * `TypeError`. `stop()` aborts inspections in flight.
+   */
+  public async inspectArchive(
+    requestArg: IGitManagerArchiveInspectionRequest,
+    optionsArg: IGitManagerArchiveInspectionOptions = {},
+  ): Promise<IGitManagerArchiveInspection> {
+    this.assertRunning();
+    const controller = new AbortController();
+    const callerSignal = optionsArg.signal;
+    const abortForCaller = (): void => {
+      controller.abort(callerSignal?.reason);
+    };
+    if (callerSignal?.aborted) {
+      throw callerSignal.reason;
+    }
+    callerSignal?.addEventListener('abort', abortForCaller, { once: true });
+    const inspection = this.bridge.findBinary().then((binaryPath) => {
+      return runArchiveInspection(binaryPath, requestArg, controller.signal);
+    });
+    this.archiveInspections.set(controller, inspection);
+    try {
+      return await inspection;
+    } finally {
+      callerSignal?.removeEventListener('abort', abortForCaller);
+      this.archiveInspections.delete(controller);
+    }
+  }
+
   public async listCommits(requestArg: IGitManagerListCommitsRequest): Promise<IGitManagerCommitSummary[]> {
     this.assertRunning();
     return this.bridge.listCommits(requestArg);
@@ -675,6 +728,15 @@ export class GitManager extends plugins.EventEmitter {
     }
   }
 
+  private async abortArchiveInspections(): Promise<void> {
+    const inspections = [...this.archiveInspections];
+    this.archiveInspections.clear();
+    for (const [controller] of inspections) {
+      controller.abort(new Error('GitManager stopped during archive inspection'));
+    }
+    await Promise.all(inspections.map(([, inspection]) => inspection.catch(() => undefined)));
+  }
+
   private async closeRepositoryServices(): Promise<void> {
     const services = [...this.repositoryServices];
     this.repositoryServices.clear();

package/ts/classes.gitmanagererror.ts

@@ -0,0 +1,28 @@
+import type { TGitManagerErrorCode } from './models.js';
+
+const gitManagerErrorCodes: ReadonlySet<string> = new Set<TGitManagerErrorCode>([
+  'invalidObjectId',
+  'objectNotFound',
+  'objectNotCommit',
+  'ancestryBudgetExceeded',
+  'archiveLimitExceeded',
+  'archiveRejected',
+]);
+
+export const isGitManagerErrorCode = (valueArg: unknown): valueArg is TGitManagerErrorCode =>
+  typeof valueArg === 'string' && gitManagerErrorCodes.has(valueArg);
+
+/**
+ * A failure callers can branch on through its stable `code`. Other failures,
+ * such as an unknown repository or an engine that is not running, remain
+ * plain errors.
+ */
+export class GitManagerError extends Error {
+  public readonly code: TGitManagerErrorCode;
+
+  constructor(codeArg: TGitManagerErrorCode, messageArg: string, optionsArg?: ErrorOptions) {
+    super(messageArg, optionsArg);
+    this.name = 'GitManagerError';
+    this.code = codeArg;
+  }
+}

package/ts/index.ts

@@ -2,3 +2,5 @@ export * from './models.js';
 export * from './rust-gitmanager-bridge.js';
 export * from './classes.gitmanager.js';
 export * from './classes.repositoryservice.js';
+export * from './classes.gitmanagererror.js';
+export { gitManagerArchivePathMetadataCeilingBytes } from './classes.archiveinspection.js';

package/ts/models.ts

@@ -89,6 +89,71 @@ export interface IGitManagerRepositoryArchive
   entryCount: number;
 }
 
+/**
+ * Asks whether `ancestorObjectId` is reachable from `descendantObjectId`
+ * (`git merge-base --is-ancestor`; a commit is its own ancestor). Both must be
+ * full lowercase object IDs of commits in the repository; revision
+ * expressions, abbreviations, and tag objects are refused.
+ */
+export interface IGitManagerAncestryRequest extends IGitManagerRepositorySelector {
+  ancestorObjectId: string;
+  descendantObjectId: string;
+  /**
+   * Wall-clock work budget for the object lookup and the history walk,
+   * 1 to 60000 ms, default 10000. Exceeding it throws a `GitManagerError`
+   * with code `ancestryBudgetExceeded`.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * Limits for inspecting one `tar.gz` archive. Every limit is inclusive.
+ */
+export interface IGitManagerArchiveInspectionRequest {
+  /** The archive bytes, or a stream of them; it is consumed and closed. */
+  archive: Uint8Array | AsyncIterable<Uint8Array>;
+  maxCompressedBytes: number;
+  maxExtractedBytes: number;
+  maxEntries: number;
+  /**
+   * Ceiling for the UTF-8 bytes of every effective entry path and symlink
+   * target, 1 to 134217728 (the fixed ci-spec ceiling, and the default).
+   */
+  maxPathMetadataBytes?: number;
+}
+
+export interface IGitManagerArchiveInspectionOptions {
+  signal?: AbortSignal;
+}
+
+/** Metadata recomputed from an accepted archive; nothing is taken on trust. */
+export interface IGitManagerArchiveInspection {
+  sizeBytes: number;
+  sha256: string;
+  extractedSizeBytes: number;
+  entryCount: number;
+  pathMetadataBytes: number;
+}
+
+/**
+ * Stable codes of `GitManagerError`.
+ *
+ * - `invalidObjectId`: an object ID is not a full lowercase SHA-1 or SHA-256.
+ * - `objectNotFound`: the object does not exist in the repository.
+ * - `objectNotCommit`: the object exists but is not a commit.
+ * - `ancestryBudgetExceeded`: the ancestry check exceeded `timeoutMs`; the
+ *   answer is unknown, never `false`.
+ * - `archiveLimitExceeded`: the archive exceeds a requested limit.
+ * - `archiveRejected`: the archive breaks a format, path, or link rule.
+ */
+export type TGitManagerErrorCode =
+  | 'invalidObjectId'
+  | 'objectNotFound'
+  | 'objectNotCommit'
+  | 'ancestryBudgetExceeded'
+  | 'archiveLimitExceeded'
+  | 'archiveRejected';
+
 export interface IGitManagerRepositoryLfsPointer {
   oid: string;
   sizeBytes: number;

package/ts/rust-gitmanager-bridge.ts

@@ -1,5 +1,7 @@
 import * as plugins from './plugins.js';
+import { GitManagerError, isGitManagerErrorCode } from './classes.gitmanagererror.js';
 import type {
+  IGitManagerAncestryRequest,
   IGitManagerCommitDetail,
   IGitManagerCommitRequest,
   IGitManagerCommitSummary,
@@ -74,6 +76,7 @@ type TGitManagerCommands = {
   mergeRepository: { params: IGitManagerMergeRequest; result: IGitManagerMergeResult };
   listTree: { params: IGitManagerTreeRequest; result: IGitManagerTreeEntry[] };
   readFile: { params: IGitManagerReadFileRequest; result: IGitManagerFileContent };
+  isAncestor: { params: IGitManagerAncestryRequest; result: boolean };
   listCommits: { params: IGitManagerListCommitsRequest; result: IGitManagerCommitSummary[] };
   getCommit: { params: IGitManagerCommitRequest; result: IGitManagerCommitDetail };
   getDiff: { params: IGitManagerDiffRequest; result: IGitManagerDiff };
@@ -109,16 +112,37 @@ function buildLocalPaths(): string[] {
   return paths;
 }
 
+/**
+ * Rethrows a Rust response that carries a stable GitManager error code as a
+ * `GitManagerError`; every other failure is rethrown unchanged.
+ */
+const rethrowCodedError = (errorArg: unknown): never => {
+  if (
+    errorArg instanceof plugins.smartrust.RustBridgeRequestError
+    && isGitManagerErrorCode(errorArg.responseErrorCode)
+  ) {
+    throw new GitManagerError(errorArg.responseErrorCode, errorArg.message, {
+      cause: errorArg,
+    });
+  }
+  throw errorArg;
+};
+
 export class RustGitManagerBridge extends plugins.EventEmitter {
   private bridge: plugins.smartrust.RustBridge<TGitManagerCommands>;
+  private binaryLocator: plugins.smartrust.RustBinaryLocator;
 
   constructor() {
     super();
-    this.bridge = new plugins.smartrust.RustBridge<TGitManagerCommands>({
+    const binaryLocatorOptions: plugins.smartrust.IBinaryLocatorOptions = {
       binaryName: 'rustgitmanager',
       envVarName: 'GITMANAGER_RUST_BINARY',
       platformPackagePrefix: '@foss.global/gitmanager',
       localPaths: buildLocalPaths(),
+    };
+    this.binaryLocator = new plugins.smartrust.RustBinaryLocator(binaryLocatorOptions);
+    this.bridge = new plugins.smartrust.RustBridge<TGitManagerCommands>({
+      ...binaryLocatorOptions,
       requestTimeoutMs: 130000,
       readyTimeoutMs: 10000,
     });
@@ -135,6 +159,15 @@ export class RustGitManagerBridge extends plugins.EventEmitter {
     return this.bridge.spawn();
   }
 
+  /** Resolves the engine binary the bridge spawns, for its one-shot modes. */
+  public async findBinary(): Promise<string> {
+    const binaryPath = await this.binaryLocator.findBinary();
+    if (!binaryPath) {
+      throw new Error('Unable to locate the rustgitmanager binary');
+    }
+    return binaryPath;
+  }
+
   public kill(): void {
     this.bridge.kill();
   }
@@ -304,6 +337,20 @@ export class RustGitManagerBridge extends plugins.EventEmitter {
     return this.bridge.sendCommand('readFile', requestArg);
   }
 
+  public async isAncestor(requestArg: IGitManagerAncestryRequest): Promise<boolean> {
+    const result = await this.bridge.sendCommand('isAncestor', {
+      org: requestArg.org,
+      repo: requestArg.repo,
+      ancestorObjectId: requestArg.ancestorObjectId,
+      descendantObjectId: requestArg.descendantObjectId,
+      ...(requestArg.timeoutMs === undefined ? {} : { timeoutMs: requestArg.timeoutMs }),
+    }).catch(rethrowCodedError);
+    if (typeof result !== 'boolean') {
+      throw new Error('Rust GitManager returned an invalid ancestry result');
+    }
+    return result;
+  }
+
   public async listCommits(requestArg: IGitManagerListCommitsRequest): Promise<IGitManagerCommitSummary[]> {
     return this.bridge.sendCommand('listCommits', requestArg);
   }