@foss.global/gitmanager 2.3.0 → 2.5.0

package/ts/classes.gitmanager.ts

@@ -1,6 +1,8 @@
 import * as plugins from './plugins.js';
 import type {
   IGitManagerAncestryRequest,
+  IGitManagerAtomicPushRequest,
+  IGitManagerAtomicPushResult,
   IGitManagerArchiveInspection,
   IGitManagerArchiveInspectionOptions,
   IGitManagerArchiveInspectionRequest,
@@ -32,6 +34,7 @@ import type {
   IGitManagerRepositorySelector,
   IGitManagerRepositorySize,
   IGitManagerRestoreBundleRequest,
+  IGitManagerSetDefaultBranchRequest,
   IGitManagerSmartHttpRepositoryAccess,
   IGitManagerSmartHttpRepositoryVisibility,
   IGitManagerStatus,
@@ -39,6 +42,7 @@ import type {
   IGitManagerTagRequest,
   IGitManagerTreeEntry,
   IGitManagerTreeRequest,
+  IGitManagerTransferControlOptions,
   IGitManagerOptions,
   IGitManagerReadinessOptions,
   IRustGitManagerConfig,
@@ -87,6 +91,32 @@ const assertRemoteTransferOptions = (optionsArg: IGitManagerRemoteTransferOption
   }
 };
 
+/**
+ * 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';
 
@@ -377,21 +407,90 @@ export class GitManager extends plugins.EventEmitter {
   }
 
   /**
-   * Clones every ref of `remoteUrl` into a new mirror repository. 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.
+   * 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 importMirror(requestArg: IGitManagerImportMirrorRequest): Promise<IGitManagerRepositoryInfo> {
+  public async refreshMirror(
+    requestArg: IGitManagerRefreshMirrorRequest,
+    optionsArg: IGitManagerTransferControlOptions = {},
+  ): Promise<IGitManagerRepositoryInfo> {
     this.assertRunning();
     assertRemoteTransferOptions(requestArg);
-    return this.bridge.importMirror(requestArg);
+    return this.bridge.refreshMirror(requestArg, optionsArg);
   }
 
-  /** Fetches every ref of an imported mirror's remote again, with the same transfer options as `importMirror`. */
-  public async refreshMirror(requestArg: IGitManagerRefreshMirrorRequest): Promise<IGitManagerRepositoryInfo> {
+  /**
+   * Pushes leased ref updates to `remoteUrl` as one atomic transaction: the
+   * remote applies all of them or none, however many there are. The remote
+   * must advertise the `atomic` receive-pack capability; otherwise a
+   * `GitManagerError` with code `atomicPushUnsupported` is thrown and nothing
+   * is pushed. A remote that refuses the push request as too large (HTTP 413)
+   * throws `remoteLimitExceeded`, 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 the updates are sent (a
+   * signal already aborted, or an abort during the local object check or the
+   * remote ref listing) changes nothing on the remote. An abort after that
+   * terminates the push, 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();
     assertRemoteTransferOptions(requestArg);
-    return this.bridge.refreshMirror(requestArg);
+    assertAtomicPushUpdates(requestArg.updates);
+    return this.bridge.pushRefs(requestArg, optionsArg);
+  }
+
+  /** 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.setDefaultBranch(requestArg);
   }
 
   /** Counts the repository's objects and their exact Git bytes. */
@@ -420,29 +519,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);
@@ -450,6 +584,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,10 @@ const gitManagerErrorCodes: ReadonlySet<string> = new Set<TGitManagerErrorCode>(
   'ancestryBudgetExceeded',
   'archiveLimitExceeded',
   'archiveRejected',
+  'atomicPushUnsupported',
+  'remoteLimitExceeded',
+  '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,15 @@ 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.
+ * - `remoteLimitExceeded`: the push remote refused the push request as too
+ *   large (HTTP 413); 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 +170,11 @@ export type TGitManagerErrorCode =
   | 'objectNotCommit'
   | 'ancestryBudgetExceeded'
   | 'archiveLimitExceeded'
-  | 'archiveRejected';
+  | 'archiveRejected'
+  | 'atomicPushUnsupported'
+  | 'remoteLimitExceeded'
+  | 'transferAborted'
+  | 'repositoryBusy';
 
 export interface IGitManagerRepositoryLfsPointer {
   oid: string;
@@ -169,6 +191,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 +211,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 +330,10 @@ export type TGitManagerReadinessResult =
     };
 
 export type {
+  IGitManagerAtomicPushRefResult,
+  IGitManagerAtomicPushRefUpdate,
+  IGitManagerAtomicPushRequest,
+  IGitManagerAtomicPushResult,
   IGitManagerCommitDetail,
   IGitManagerCommitRequest,
   IGitManagerCommitSummary,
@@ -323,10 +362,12 @@ export type {
   IGitManagerRepositoryInfo,
   IGitManagerRepositorySelector,
   IGitManagerRepositorySize,
+  IGitManagerSetDefaultBranchRequest,
   IGitManagerTag,
   IGitManagerTagRequest,
   IGitManagerTreeEntry,
   IGitManagerTreeRequest,
+  TGitManagerAtomicPushRefStatus,
   TGitManagerDiffFileStatus,
   TGitManagerDiffLineKind,
   TGitManagerMergeMethod,

package/ts/rust-gitmanager-bridge.ts

@@ -2,6 +2,8 @@ import * as plugins from './plugins.js';
 import { GitManagerError, isGitManagerErrorCode } from './classes.gitmanagererror.js';
 import type {
   IGitManagerAncestryRequest,
+  IGitManagerAtomicPushRequest,
+  IGitManagerAtomicPushResult,
   IGitManagerCommitDetail,
   IGitManagerCommitRequest,
   IGitManagerCommitSummary,
@@ -24,11 +26,11 @@ import type {
   IGitManagerRepositoryArchiveOptions,
   IGitManagerRepositoryArchiveRequest,
   IGitManagerRepositoryLfsPointer,
-  IGitManagerRepositoryServiceRequest,
   IGitManagerRepositoryInfo,
   IGitManagerRepositorySelector,
   IGitManagerRepositorySize,
   IGitManagerRestoreBundleRequest,
+  IGitManagerSetDefaultBranchRequest,
   IGitManagerSmartHttpRepositoryAccess,
   IGitManagerSmartHttpRepositoryVisibility,
   IGitManagerStatus,
@@ -36,9 +38,11 @@ import type {
   IGitManagerTagRequest,
   IGitManagerTreeEntry,
   IGitManagerTreeRequest,
+  IGitManagerTransferControlOptions,
   IRustGitManagerConfig,
   TGitManagerRefInventoryResult,
   IRustGitManagerRepositoryServiceDescriptor,
+  IRustGitManagerRepositoryServicePrepareRequest,
 } from './models.js';
 
 type TRepositoryArchiveCancelStatus =
@@ -56,6 +60,14 @@ interface IRepositoryArchiveCancelRequest {
   operationId: string;
 }
 
+/** A remote transfer under the operation ID that `cancelTransfer` names. */
+interface ITransferOperationRequest<TRequest> {
+  operationId: string;
+  request: TRequest;
+}
+
+type TTransferCancelStatus = 'cancelling' | 'not_found';
+
 type TGitManagerCommands = {
   start: { params: { config: IRustGitManagerConfig }; result: Record<string, never> };
   stop: { params: Record<string, never>; result: Record<string, never> };
@@ -64,14 +76,27 @@ type TGitManagerCommands = {
   setSmartHttpRepositoryVisibility: { params: IGitManagerSmartHttpRepositoryVisibility; result: Record<string, never> };
   setSmartHttpRepositoryProtectedRefs: { params: IGitManagerSmartHttpRepositoryProtectedRefs; result: IGitManagerProtectedRefsApplyResult };
   initBareRepository: { params: IGitManagerInitBareRepositoryRequest; result: IGitManagerRepositoryInfo };
-  importMirror: { params: IGitManagerImportMirrorRequest; result: IGitManagerRepositoryInfo };
-  refreshMirror: { params: IGitManagerRefreshMirrorRequest; result: IGitManagerRepositoryInfo };
+  importMirror: {
+    params: ITransferOperationRequest<IGitManagerImportMirrorRequest>;
+    result: IGitManagerRepositoryInfo;
+  };
+  refreshMirror: {
+    params: ITransferOperationRequest<IGitManagerRefreshMirrorRequest>;
+    result: IGitManagerRepositoryInfo;
+  };
+  pushRefs: {
+    params: ITransferOperationRequest<IGitManagerAtomicPushRequest>;
+    result: IGitManagerAtomicPushResult;
+  };
+  cancelTransfer: { params: { operationId: string }; result: { status: TTransferCancelStatus } };
+  setDefaultBranch: { params: IGitManagerSetDefaultBranchRequest; result: IGitManagerRepositoryInfo };
   verifyRepository: { params: IGitManagerRepositorySelector; result: IGitManagerRepositoryInfo };
   getRepositorySize: { params: IGitManagerRepositorySelector; result: IGitManagerRepositorySize };
   createRepositoryBundle: { params: IGitManagerRepositorySelector; result: IGitManagerRepositoryBundle };
   createRepositoryArchive: { params: IRepositoryArchiveOperationRequest; result: IGitManagerRepositoryArchive };
   cancelRepositoryArchive: { params: IRepositoryArchiveCancelRequest; result: { status: TRepositoryArchiveCancelStatus } };
-  prepareRepositoryService: { params: IGitManagerRepositoryServiceRequest; result: IRustGitManagerRepositoryServiceDescriptor };
+  prepareRepositoryService: { params: IRustGitManagerRepositoryServicePrepareRequest; result: IRustGitManagerRepositoryServiceDescriptor };
+  releaseRepositoryService: { params: { ticketId: string }; result: { released: boolean } };
   restoreRepositoryBundle: { params: IGitManagerRestoreBundleRequest; result: IGitManagerRepositoryInfo };
   listRepositories: { params: Record<string, never>; result: IGitManagerRepositoryInfo[] };
   listRefs: { params: IGitManagerRefRequest; result: TGitManagerRefInventoryResult };
@@ -97,6 +122,9 @@ const defaultRemoteTransferTimeoutMs = 120_000;
 const remoteTransferResponseTimeoutMs = (timeoutMsArg: number | undefined): number =>
   (timeoutMsArg ?? defaultRemoteTransferTimeoutMs) + 30_000;
 
+/** The cancel command is answered at once; the transfer reports its own end. */
+const transferCancelTimeoutMs = 30_000;
+
 function getPackageRoot(): string {
   const thisDir = plugins.path.dirname(plugins.url.fileURLToPath(import.meta.url));
   return plugins.path.resolve(thisDir, '..');
@@ -227,19 +255,72 @@ export class RustGitManagerBridge extends plugins.EventEmitter {
   }
 
   public async initBareRepository(requestArg: IGitManagerInitBareRepositoryRequest): Promise<IGitManagerRepositoryInfo> {
-    return this.bridge.sendCommand('initBareRepository', requestArg);
+    return this.bridge.sendCommand('initBareRepository', requestArg).catch(rethrowCodedError);
   }
 
-  public async importMirror(requestArg: IGitManagerImportMirrorRequest): Promise<IGitManagerRepositoryInfo> {
-    return this.bridge.sendCommand('importMirror', requestArg, {
-      timeoutMs: remoteTransferResponseTimeoutMs(requestArg.timeoutMs),
-    });
+  public async importMirror(
+    requestArg: IGitManagerImportMirrorRequest,
+    optionsArg: IGitManagerTransferControlOptions = {},
+  ): Promise<IGitManagerRepositoryInfo> {
+    return this.runTransfer('importMirror', requestArg, optionsArg);
   }
 
-  public async refreshMirror(requestArg: IGitManagerRefreshMirrorRequest): Promise<IGitManagerRepositoryInfo> {
-    return this.bridge.sendCommand('refreshMirror', requestArg, {
+  public async refreshMirror(
+    requestArg: IGitManagerRefreshMirrorRequest,
+    optionsArg: IGitManagerTransferControlOptions = {},
+  ): Promise<IGitManagerRepositoryInfo> {
+    return this.runTransfer('refreshMirror', requestArg, optionsArg);
+  }
+
+  public async pushRefs(
+    requestArg: IGitManagerAtomicPushRequest,
+    optionsArg: IGitManagerTransferControlOptions = {},
+  ): Promise<IGitManagerAtomicPushResult> {
+    return this.runTransfer('pushRefs', requestArg, optionsArg);
+  }
+
+  /**
+   * Runs a remote transfer under a fresh operation ID. Aborting the signal
+   * sends `cancelTransfer`; the engine then terminates the transfer's Git
+   * process and answers the transfer itself with `transferAborted`. A signal
+   * that is already aborted rejects before anything is sent.
+   */
+  private async runTransfer<TMethod extends 'importMirror' | 'refreshMirror' | 'pushRefs'>(
+    methodArg: TMethod,
+    requestArg: TGitManagerCommands[TMethod]['params']['request'],
+    optionsArg: IGitManagerTransferControlOptions,
+  ): Promise<TGitManagerCommands[TMethod]['result']> {
+    const signal = optionsArg.signal;
+    if (signal?.aborted) {
+      throw new GitManagerError('transferAborted', 'The transfer was aborted before it started', {
+        cause: signal.reason,
+      });
+    }
+    const operationId = plugins.crypto.randomUUID();
+    const params = { operationId, request: requestArg } as TGitManagerCommands[TMethod]['params'];
+    const transfer = this.bridge.sendCommand(methodArg, params, {
       timeoutMs: remoteTransferResponseTimeoutMs(requestArg.timeoutMs),
     });
+    const cancelTransfer = (): void => {
+      // Only the transfer's own response settles the call.
+      void this.bridge.sendCommand('cancelTransfer', { operationId }, {
+        timeoutMs: transferCancelTimeoutMs,
+      }).catch(() => undefined);
+    };
+    signal?.addEventListener('abort', cancelTransfer, { once: true });
+    try {
+      return await transfer;
+    } catch (error) {
+      return rethrowCodedError(error);
+    } finally {
+      signal?.removeEventListener('abort', cancelTransfer);
+    }
+  }
+
+  public async setDefaultBranch(
+    requestArg: IGitManagerSetDefaultBranchRequest,
+  ): Promise<IGitManagerRepositoryInfo> {
+    return this.bridge.sendCommand('setDefaultBranch', requestArg).catch(rethrowCodedError);
   }
 
   public async getRepositorySize(requestArg: IGitManagerRepositorySelector): Promise<IGitManagerRepositorySize> {
@@ -320,15 +401,20 @@ export class RustGitManagerBridge extends plugins.EventEmitter {
   }
 
   public async prepareRepositoryService(
-    requestArg: IGitManagerRepositoryServiceRequest,
+    requestArg: IRustGitManagerRepositoryServicePrepareRequest,
   ): Promise<IRustGitManagerRepositoryServiceDescriptor> {
-    return this.bridge.sendCommand('prepareRepositoryService', requestArg);
+    return this.bridge.sendCommand('prepareRepositoryService', requestArg).catch(rethrowCodedError);
+  }
+
+  /** Releases a receive-pack guard ticket; unknown or released tickets are a no-op. */
+  public async releaseRepositoryService(ticketIdArg: string): Promise<void> {
+    await this.bridge.sendCommand('releaseRepositoryService', { ticketId: ticketIdArg });
   }
 
   public async restoreRepositoryBundle(
     requestArg: IGitManagerRestoreBundleRequest,
   ): Promise<IGitManagerRepositoryInfo> {
-    return this.bridge.sendCommand('restoreRepositoryBundle', requestArg);
+    return this.bridge.sendCommand('restoreRepositoryBundle', requestArg).catch(rethrowCodedError);
   }
 
   public async listRepositories(): Promise<IGitManagerRepositoryInfo[]> {
@@ -350,7 +436,7 @@ export class RustGitManagerBridge extends plugins.EventEmitter {
   public async mergeRepository(
     requestArg: IGitManagerMergeRequest,
   ): Promise<IGitManagerMergeResult> {
-    return this.bridge.sendCommand('mergeRepository', requestArg);
+    return this.bridge.sendCommand('mergeRepository', requestArg).catch(rethrowCodedError);
   }
 
   public async listTree(requestArg: IGitManagerTreeRequest): Promise<IGitManagerTreeEntry[]> {