@foss.global/gitmanager 2.2.0 → 2.4.0

package/ts/classes.gitmanager.ts

@@ -1,6 +1,8 @@
 import * as plugins from './plugins.js';
 import type {
   IGitManagerAncestryRequest,
+  IGitManagerAtomicPushRequest,
+  IGitManagerAtomicPushResult,
   IGitManagerArchiveInspection,
   IGitManagerArchiveInspectionOptions,
   IGitManagerArchiveInspectionRequest,
@@ -18,6 +20,8 @@ import type {
   IGitManagerMergeResult,
   IGitManagerReadFileRequest,
   IGitManagerRefRequest,
+  IGitManagerRefreshMirrorRequest,
+  IGitManagerRemoteTransferOptions,
   IGitManagerProtectedRefsApplyResult,
   IGitManagerSmartHttpRepositoryProtectedRefs,
   IGitManagerRepositoryBundle,
@@ -28,7 +32,9 @@ import type {
   IGitManagerRepositoryServiceRequest,
   IGitManagerRepositoryInfo,
   IGitManagerRepositorySelector,
+  IGitManagerRepositorySize,
   IGitManagerRestoreBundleRequest,
+  IGitManagerSetDefaultBranchRequest,
   IGitManagerSmartHttpRepositoryAccess,
   IGitManagerSmartHttpRepositoryVisibility,
   IGitManagerStatus,
@@ -36,6 +42,7 @@ import type {
   IGitManagerTagRequest,
   IGitManagerTreeEntry,
   IGitManagerTreeRequest,
+  IGitManagerTransferControlOptions,
   IGitManagerOptions,
   IGitManagerReadinessOptions,
   IRustGitManagerConfig,
@@ -49,6 +56,66 @@ import { runArchiveInspection } from './classes.archiveinspection.js';
 
 const readinessDefaultTimeoutMs = 2_000;
 const readinessMaximumTimeoutMs = 30_000;
+const remoteTransferMaximumTimeoutMs = 21_600_000;
+
+/**
+ * Checks transfer options before they reach the engine, which answers a
+ * malformed credential-bearing request with fixed text only. Messages never
+ * quote a credential value.
+ */
+const assertRemoteTransferOptions = (optionsArg: IGitManagerRemoteTransferOptions): void => {
+  const { credential, caCertificates, timeoutMs } = optionsArg;
+  if (credential !== undefined) {
+    if (
+      credential === null
+      || typeof credential !== 'object'
+      || credential.kind !== 'basic'
+      || typeof credential.username !== 'string'
+      || typeof credential.password !== 'string'
+      || Object.keys(credential).some((key) => !['kind', 'username', 'password'].includes(key))
+    ) {
+      throw new TypeError('credential must be { kind: "basic", username: string, password: string }');
+    }
+  }
+  if (
+    caCertificates !== undefined
+    && (!Array.isArray(caCertificates) || caCertificates.some((certificate) => typeof certificate !== 'string'))
+  ) {
+    throw new TypeError('caCertificates must be an array of PEM strings');
+  }
+  if (
+    timeoutMs !== undefined
+    && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > remoteTransferMaximumTimeoutMs)
+  ) {
+    throw new RangeError(`timeoutMs must be an integer between 1 and ${remoteTransferMaximumTimeoutMs}`);
+  }
+};
+
+/**
+ * Checks the shape of push updates before they reach the engine, which
+ * answers a malformed request with fixed text only. Ref names and object IDs
+ * are validated by the engine.
+ */
+const assertAtomicPushUpdates = (updatesArg: unknown): void => {
+  const isObjectIdOrNull = (valueArg: unknown): boolean => valueArg === null || typeof valueArg === 'string';
+  if (
+    !Array.isArray(updatesArg)
+    || updatesArg.some((update: unknown) => {
+      if (update === null || typeof update !== 'object') {
+        return true;
+      }
+      const record = update as Record<string, unknown>;
+      return typeof record.ref !== 'string'
+        || !isObjectIdOrNull(record.expectedOldObjectId)
+        || !isObjectIdOrNull(record.newObjectId)
+        || Object.keys(record).some((key) => !['ref', 'expectedOldObjectId', 'newObjectId'].includes(key));
+    })
+  ) {
+    throw new TypeError(
+      'updates must be an array of { ref: string, expectedOldObjectId: string | null, newObjectId: string | null }',
+    );
+  }
+};
 
 type TGitManagerReadinessAbortSource = 'caller' | 'deadline';
 type TGitManagerReadinessProbeOutcome = 'ready' | 'aborted' | 'unavailable';
@@ -339,14 +406,95 @@ export class GitManager extends plugins.EventEmitter {
     return this.bridge.initBareRepository(requestArg);
   }
 
-  public async importMirror(requestArg: IGitManagerImportMirrorRequest): Promise<IGitManagerRepositoryInfo> {
+  /**
+   * Clones every ref of `remoteUrl` into a new mirror repository whose HEAD
+   * points at the source's default branch. Pass a credential as
+   * `credential`, never inside the URL: the engine hands it to Git only
+   * through the process environment and removes it from errors.
+   *
+   * The import runs alongside other commands and holds `org/repo` until it
+   * ends: another mirror transfer of it or a write to it (such as
+   * `initBareRepository` or `restoreRepositoryBundle`) fails with
+   * `repositoryBusy`. Aborting `optionsArg.signal`, or `stop()`, terminates
+   * the clone and removes the partial repository; the call then rejects with
+   * `transferAborted`, and no repository is left behind. An import whose
+   * clone already completed when the abort arrived returns its result.
+   */
+  public async importMirror(
+    requestArg: IGitManagerImportMirrorRequest,
+    optionsArg: IGitManagerTransferControlOptions = {},
+  ): Promise<IGitManagerRepositoryInfo> {
+    this.assertRunning();
+    assertRemoteTransferOptions(requestArg);
+    return this.bridge.importMirror(requestArg, optionsArg);
+  }
+
+  /**
+   * Fetches every ref of an imported mirror's remote again, with the same
+   * transfer options as `importMirror`, and points HEAD at the source's
+   * current default branch when the source advertises one.
+   *
+   * The refresh holds `org/repo` like `importMirror`: writes to it, including
+   * Smart HTTP pushes, are refused with `repositoryBusy` while it runs, and it
+   * is refused while such a write is in progress; reads proceed. Aborting
+   * `optionsArg.signal`, or `stop()`, terminates the fetch and rejects with
+   * `transferAborted`. The mirror's refs then stay as they were or, when the
+   * abort came after `git fetch --atomic` committed its ref transaction, are
+   * fully refreshed; HEAD moves only when the refresh completes.
+   */
+  public async refreshMirror(
+    requestArg: IGitManagerRefreshMirrorRequest,
+    optionsArg: IGitManagerTransferControlOptions = {},
+  ): Promise<IGitManagerRepositoryInfo> {
+    this.assertRunning();
+    assertRemoteTransferOptions(requestArg);
+    return this.bridge.refreshMirror(requestArg, optionsArg);
+  }
+
+  /**
+   * Pushes leased ref updates to `remoteUrl` as one atomic transaction: the
+   * remote applies all of them or none. The remote must advertise the
+   * `atomic` receive-pack capability; otherwise a `GitManagerError` with code
+   * `atomicPushUnsupported` is thrown and nothing is pushed. `remoteUrl` must
+   * be `https`, or `http` to a loopback IP address (`127.0.0.0/8`, `[::1]`;
+   * never a host name such as `localhost`), without user information; the
+   * credential travels as for `importMirror`. A ref that already holds its
+   * `newObjectId` is reported `ok` without its lease being checked; it is not
+   * changed, so `ok` never means the lease matched. Any refusal the remote
+   * reports per ref returns status `rejected`, with the refused refs `stale`
+   * or `rejected` and the up-to-date ones `ok`; the call throws only when the
+   * remote's answer does not say what it did.
+   *
+   * The push only reads the managed repository, so it runs alongside other
+   * commands and other transfers. Aborting `optionsArg.signal`, or `stop()`,
+   * rejects with `transferAborted`. An abort before `git push` starts (a
+   * signal already aborted, or an abort during the local object check)
+   * changes nothing on the remote. An abort while it runs terminates it, and
+   * the remote then holds all of the updates or none of them, unknown which:
+   * read the remote refs again before retrying.
+   */
+  public async pushRefs(
+    requestArg: IGitManagerAtomicPushRequest,
+    optionsArg: IGitManagerTransferControlOptions = {},
+  ): Promise<IGitManagerAtomicPushResult> {
     this.assertRunning();
-    return this.bridge.importMirror(requestArg);
+    assertRemoteTransferOptions(requestArg);
+    assertAtomicPushUpdates(requestArg.updates);
+    return this.bridge.pushRefs(requestArg, optionsArg);
   }
 
-  public async refreshMirror(requestArg: IGitManagerRepositorySelector): Promise<IGitManagerRepositoryInfo> {
+  /** Points the repository's HEAD at an existing branch; a missing branch is refused and HEAD stays unchanged. */
+  public async setDefaultBranch(
+    requestArg: IGitManagerSetDefaultBranchRequest,
+  ): Promise<IGitManagerRepositoryInfo> {
     this.assertRunning();
-    return this.bridge.refreshMirror(requestArg);
+    return this.bridge.setDefaultBranch(requestArg);
+  }
+
+  /** Counts the repository's objects and their exact Git bytes. */
+  public async getRepositorySize(requestArg: IGitManagerRepositorySelector): Promise<IGitManagerRepositorySize> {
+    this.assertRunning();
+    return this.bridge.getRepositorySize(requestArg);
   }
 
   public async verifyRepository(requestArg: IGitManagerRepositorySelector): Promise<IGitManagerRepositoryInfo> {
@@ -369,29 +517,64 @@ export class GitManager extends plugins.EventEmitter {
     return this.bridge.createRepositoryArchive(requestArg, optionsArg);
   }
 
+  /**
+   * Starts a bounded `git upload-pack` or protected `git receive-pack` for an
+   * authenticated ingress such as SSH.
+   *
+   * A receive-pack holds its repository against mirror transfers: while its
+   * `guardTicketId` is held, `importMirror` and `refreshMirror` of the
+   * repository fail with `repositoryBusy`, and a receive-pack is refused with
+   * `repositoryBusy` while a mirror transfer runs. Release the ticket with
+   * `releaseRepositoryService()` in a `finally` once the process has exited
+   * and the push is reconciled; `stop()` releases every ticket. Upload-pack
+   * takes no ticket.
+   *
+   * The ticket ID is chosen here, before the engine is asked. When opening a
+   * receive-pack fails, including a bridge timeout after the engine already
+   * issued the ticket, the ticket is released before the error is thrown. If
+   * that release fails as well, the original error is still thrown: the
+   * release error becomes its `cause` when it has none, and otherwise both
+   * are thrown together as an `AggregateError` (`errors`: the original error,
+   * then the release error; `cause`: the original error).
+   */
   public async openRepositoryService(
     requestArg: IGitManagerRepositoryServiceRequest,
   ): Promise<GitManagerRepositoryService> {
     this.assertRunning();
     const serviceEpoch = this.lifecycleEpoch;
-    const descriptor = await this.bridge.prepareRepositoryService({
-      org: requestArg.org,
-      repo: requestArg.repo,
-      service: requestArg.service,
-      ...(requestArg.protocol ? { protocol: requestArg.protocol } : {}),
-    });
-    if (
-      this.lifecycleEpoch !== serviceEpoch
-      || this.stopRequested
-      || !this.running
-    ) {
-      throw new Error('GitManager stopped while preparing repository service');
+    const guardTicketId = requestArg.service === 'receive-pack'
+      ? plugins.crypto.randomUUID()
+      : undefined;
+    let service: GitManagerRepositoryService;
+    try {
+      const descriptor = await this.bridge.prepareRepositoryService({
+        org: requestArg.org,
+        repo: requestArg.repo,
+        service: requestArg.service,
+        ...(requestArg.protocol ? { protocol: requestArg.protocol } : {}),
+        ...(guardTicketId === undefined ? {} : { guardTicketId }),
+      });
+      if (
+        this.lifecycleEpoch !== serviceEpoch
+        || this.stopRequested
+        || !this.running
+      ) {
+        throw new Error('GitManager stopped while preparing repository service');
+      }
+      if (descriptor.guardTicketId !== guardTicketId) {
+        throw new Error('GitManager returned an invalid repository service descriptor');
+      }
+      service = new GitManagerRepositoryService(
+        descriptor,
+        requestArg,
+        this.config.dataDir,
+      );
+    } catch (error) {
+      if (guardTicketId === undefined) {
+        throw error;
+      }
+      throw await this.releaseUnusedTicket(guardTicketId, error);
     }
-    const service = new GitManagerRepositoryService(
-      descriptor,
-      requestArg,
-      this.config.dataDir,
-    );
     this.repositoryServices.add(service);
     service.completed.finally(() => {
       this.repositoryServices.delete(service);
@@ -399,6 +582,46 @@ export class GitManager extends plugins.EventEmitter {
     return service;
   }
 
+  /**
+   * Releases the guard ticket of a receive-pack that failed to open and
+   * returns the error to throw: `errorArg`, carrying a failed release as its
+   * `cause` when it has none, or else an `AggregateError` of both.
+   */
+  private async releaseUnusedTicket(ticketIdArg: string, errorArg: unknown): Promise<unknown> {
+    try {
+      await this.releaseRepositoryService(ticketIdArg);
+      return errorArg;
+    } catch (releaseError) {
+      if (errorArg instanceof Error && errorArg.cause === undefined) {
+        errorArg.cause = releaseError;
+        return errorArg;
+      }
+      return new AggregateError(
+        [errorArg, releaseError],
+        'Opening the repository service failed, and releasing its guard ticket failed',
+        { cause: errorArg },
+      );
+    }
+  }
+
+  /**
+   * Releases the guard ticket of a receive-pack opened with
+   * `openRepositoryService()` (`service.guardTicketId`), so mirror transfers
+   * of its repository are admitted again. Call it in a `finally` after the
+   * Git process has exited. Releasing is idempotent: an unknown or already
+   * released ticket, or a stopped engine, whose tickets ended with it, is a
+   * no-op.
+   */
+  public async releaseRepositoryService(ticketIdArg: string): Promise<void> {
+    if (typeof ticketIdArg !== 'string') {
+      throw new TypeError('ticketId must be a string');
+    }
+    if (!this.bridge.running) {
+      return;
+    }
+    await this.bridge.releaseRepositoryService(ticketIdArg);
+  }
+
   public async restoreRepositoryBundle(
     requestArg: IGitManagerRestoreBundleRequest,
   ): Promise<IGitManagerRepositoryInfo> {

package/ts/classes.gitmanagererror.ts

@@ -7,6 +7,9 @@ const gitManagerErrorCodes: ReadonlySet<string> = new Set<TGitManagerErrorCode>(
   'ancestryBudgetExceeded',
   'archiveLimitExceeded',
   'archiveRejected',
+  'atomicPushUnsupported',
+  'transferAborted',
+  'repositoryBusy',
 ]);
 
 export const isGitManagerErrorCode = (valueArg: unknown): valueArg is TGitManagerErrorCode =>

package/ts/classes.repositoryservice.ts

@@ -64,12 +64,15 @@ const validateDescriptor = (
       || !plugins.path.isAbsolute(descriptorArg.hookPath)
       || !descriptorArg.protectedRefsPolicy
       || !/^[A-Za-z0-9_-]{1,65536}$/.test(descriptorArg.protectedRefsPolicy)
+      || typeof descriptorArg.guardTicketId !== 'string'
+      || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(descriptorArg.guardTicketId)
     ) {
       throw new Error('GitManager returned an invalid receive-pack descriptor');
     }
   } else if (
     descriptorArg.hookPath !== undefined
     || descriptorArg.protectedRefsPolicy !== undefined
+    || descriptorArg.guardTicketId !== undefined
   ) {
     throw new Error('GitManager returned unexpected upload-pack hook state');
   }
@@ -80,6 +83,15 @@ export class GitManagerRepositoryService {
   public readonly stdout: plugins.stream.Readable;
   public readonly stderr: plugins.stream.Readable;
   public readonly completed: Promise<IGitManagerRepositoryServiceResult>;
+  /**
+   * Receive-pack only: the guard ticket that holds the repository against
+   * mirror transfers (`importMirror`, `refreshMirror`, which fail with
+   * `repositoryBusy`) until `GitManager.releaseRepositoryService()` releases
+   * it or the engine stops. Release it in a `finally` once the process has
+   * exited and the push is reconciled. A UUID that `openRepositoryService()`
+   * chose. Null for upload-pack.
+   */
+  public readonly guardTicketId: string | null;
   private readonly child: plugins.childProcess.ChildProcessWithoutNullStreams;
   private completionSettled = false;
   private failure: TGitManagerRepositoryServiceFailure | null = null;
@@ -91,6 +103,7 @@ export class GitManagerRepositoryService {
     homeDirectoryArg: string,
   ) {
     validateDescriptor(descriptorArg, requestArg);
+    this.guardTicketId = descriptorArg.guardTicketId ?? null;
     const args = descriptorArg.service === 'upload-pack'
       ? [
           'upload-pack',

package/ts/models.ts

@@ -79,6 +79,15 @@ export interface IGitManagerRepositoryArchiveOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Call options of the remote transfers `importMirror`, `refreshMirror` and
+ * `pushRefs`. Aborting `signal` stops the transfer; the call then rejects
+ * with a `GitManagerError` whose code is `transferAborted`.
+ */
+export interface IGitManagerTransferControlOptions {
+  signal?: AbortSignal;
+}
+
 export interface IGitManagerRepositoryArchive
   extends IGitManagerRepositorySelector {
   objectId: string;
@@ -145,6 +154,13 @@ export interface IGitManagerArchiveInspection {
  *   answer is unknown, never `false`.
  * - `archiveLimitExceeded`: the archive exceeds a requested limit.
  * - `archiveRejected`: the archive breaks a format, path, or link rule.
+ * - `atomicPushUnsupported`: the push remote does not advertise the `atomic`
+ *   receive-pack capability; nothing was pushed.
+ * - `transferAborted`: a remote transfer was aborted through its `signal` or
+ *   by `stop()`. An aborted push may or may not have been applied by the
+ *   remote; read its refs again.
+ * - `repositoryBusy`: a mirror transfer holds the repository, or a write to
+ *   it is in progress when a mirror transfer starts; nothing was changed.
  */
 export type TGitManagerErrorCode =
   | 'invalidObjectId'
@@ -152,7 +168,10 @@ export type TGitManagerErrorCode =
   | 'objectNotCommit'
   | 'ancestryBudgetExceeded'
   | 'archiveLimitExceeded'
-  | 'archiveRejected';
+  | 'archiveRejected'
+  | 'atomicPushUnsupported'
+  | 'transferAborted'
+  | 'repositoryBusy';
 
 export interface IGitManagerRepositoryLfsPointer {
   oid: string;
@@ -169,6 +188,17 @@ export interface IGitManagerRepositoryServiceRequest
   protocol?: 'version=0' | 'version=1' | 'version=2';
 }
 
+/**
+ * The engine request that prepares a repository service. A receive-pack
+ * carries the guard ticket ID the facade chose, so the facade can release the
+ * ticket even when it never receives the engine's answer.
+ */
+export interface IRustGitManagerRepositoryServicePrepareRequest
+  extends IGitManagerRepositoryServiceRequest {
+  /** Receive-pack only, and required there: a lowercase hyphenated UUID. */
+  guardTicketId?: string;
+}
+
 export interface IRustGitManagerRepositoryServiceDescriptor
   extends IGitManagerRepositoryServiceRequest {
   repositoryPath: string;
@@ -178,6 +208,8 @@ export interface IRustGitManagerRepositoryServiceDescriptor
   maxResponseBytes: number;
   processTimeoutMs: number;
   idleTimeoutSeconds: number;
+  /** Receive-pack only: the requested guard ticket ID, which `releaseRepositoryService` releases. */
+  guardTicketId?: string;
 }
 
 /**
@@ -295,6 +327,10 @@ export type TGitManagerReadinessResult =
     };
 
 export type {
+  IGitManagerAtomicPushRefResult,
+  IGitManagerAtomicPushRefUpdate,
+  IGitManagerAtomicPushRequest,
+  IGitManagerAtomicPushResult,
   IGitManagerCommitDetail,
   IGitManagerCommitRequest,
   IGitManagerCommitSummary,
@@ -317,12 +353,18 @@ export type {
   IGitManagerRefInventoryPage,
   IGitManagerRefInventoryStale,
   IGitManagerRefRequest,
+  IGitManagerRefreshMirrorRequest,
+  IGitManagerRemoteBasicCredential,
+  IGitManagerRemoteTransferOptions,
   IGitManagerRepositoryInfo,
   IGitManagerRepositorySelector,
+  IGitManagerRepositorySize,
+  IGitManagerSetDefaultBranchRequest,
   IGitManagerTag,
   IGitManagerTagRequest,
   IGitManagerTreeEntry,
   IGitManagerTreeRequest,
+  TGitManagerAtomicPushRefStatus,
   TGitManagerDiffFileStatus,
   TGitManagerDiffLineKind,
   TGitManagerMergeMethod,
@@ -330,5 +372,6 @@ export type {
   TGitManagerObjectType,
   TGitManagerRefInventoryPagination,
   TGitManagerRefInventoryResult,
+  TGitManagerRemoteCredential,
   TGitManagerTreeEntryType,
 } from '@foss.global/interfaces';