@ohos-ports/nx 23.2.1-beta.1 → 23.3.0-beta.0

package/dist/src/command-line/migrate/run/broker.d.ts

@@ -0,0 +1,150 @@
+import { type DeferredOutputRecord } from '../deferred-output';
+import { type CommitResult } from '../migrate-commits';
+import { type GiveUpOutcome } from './give-up';
+import { type MigrateRunPolicy, type MigrateRunState, type MigrateStep, type MigrateTreeOperation } from './run-state';
+export declare const BROKER_ENV_VAR = "NX_MIGRATE_BROKER";
+export type BrokerRequestKind = 'commit' | 'install' | 'fold-install' | 'action-install' | 'reset' | 'give-up';
+export type InstallSeam = 'install' | 'fold-install' | 'action-install';
+export interface BrokerRequest {
+    kind: BrokerRequestKind;
+    stepId: string;
+    attempt: number;
+    invocation?: string;
+    commitAs?: 'adopt';
+}
+export type BrokerResult = {
+    kind: 'commit';
+    result: CommitResult;
+    absorbedStepIds: string[];
+    output: DeferredOutputRecord[];
+} | {
+    kind: 'installed';
+    output: DeferredOutputRecord[];
+} | {
+    kind: 'install-failed';
+    message: string;
+    peerDeps: boolean;
+    output: DeferredOutputRecord[];
+} | {
+    kind: 'reset';
+    error?: string;
+} | {
+    kind: 'give-up';
+    outcome: GiveUpOutcome;
+    output: DeferredOutputRecord[];
+} | {
+    kind: 'stale';
+};
+export interface BrokeredCommit {
+    result: CommitResult;
+    absorbedStepIds: string[];
+    /**
+     * True when the session's parent ran the commit and recorded whatever it
+     * produced before answering, so the caller appends nothing. False for an
+     * in-process commit, which the caller records.
+     */
+    recorded: boolean;
+}
+/** The request no longer matches the step: another attempt owns it. */
+export declare class BrokerStaleRequestError extends Error {
+}
+/**
+ * The advertised parent could not accept the request, or went away before
+ * answering it. It may have landed the install or the commit; the tree and
+ * the run state say.
+ */
+export declare class BrokerUnavailableError extends Error {
+}
+/** Another live process holds the working tree for an operation of its own. */
+export declare class TreeBusyError extends Error {
+}
+export interface TreeOperationRequest {
+    kind: BrokerRequestKind | 'checkpoint';
+    stepId?: string;
+    attempt?: number;
+}
+export interface TreeLease {
+    readonly owner: string;
+    markedStepId?: string;
+    release(): void;
+}
+/**
+ * Owned by the scope that runs an operation and its state write: a seam that
+ * acquires in process writes the lease here before its fallible callback
+ * runs, and the scope releases it in a `finally` once the write landed or
+ * failed. A brokered call leaves it empty; the parent holds its own.
+ */
+export interface TreeScope {
+    lease?: TreeLease;
+}
+/**
+ * Reserves the working tree for one operation in a single fresh-state write:
+ * the request must still be at its seam (else the attempt moved on and the
+ * request is stale), and no other live process may hold a reservation.
+ * A reservation whose owner process is gone holds nothing.
+ */
+export declare function acquireTreeOperation(dir: string, request: TreeOperationRequest, owner?: string): TreeLease;
+/**
+ * Owner-checked: a lease released late never drops a newer reservation, nor
+ * the mark it set.
+ */
+export declare function releaseTreeOperation(dir: string, owner: string, markedStepId?: string): void;
+/** The reservation a live process other than `owner` holds, if any. */
+export declare function liveTreeOperation(state: MigrateRunState, owner?: string): MigrateTreeOperation | undefined;
+export declare function treeBusyMessage(held: MigrateTreeOperation): string;
+export declare function treeOperationLabel(held: Pick<MigrateTreeOperation, 'kind' | 'stepId'>): string;
+export declare function brokerDir(runDirPath: string): string;
+/**
+ * Runs the step's install and commit where they can land: in this process
+ * unless a parent session advertised its broker, in which case the request
+ * goes to the parent and the answer comes back with the output the parent
+ * collected, printed here. The absorbed step ids come from whichever side
+ * ran the commit, so the ledger entry names what its `git add -A` took.
+ */
+export declare function commitStepTree(dir: string, step: MigrateStep, absorbedStepIds: string[], commitInProcess: () => Promise<CommitResult>, scope: TreeScope, commitAs?: 'adopt'): Promise<BrokeredCommit>;
+/**
+ * The same for a step that owes only its install: no commit is due, or the
+ * commit waits for a fold.
+ */
+export declare function installStepTree(dir: string, step: MigrateStep, seam: InstallSeam, installInProcess: () => Promise<void>, scope: TreeScope): Promise<void>;
+/**
+ * The same for the reset a clean retry of a failed or died step needs. Runs
+ * `resetInProcess` under the reservation, or asks the parent, which resets
+ * against the state it reads then; a reset that could not run throws.
+ */
+export declare function resetStepTree(dir: string, step: MigrateStep, resetInProcess: () => void, scope: TreeScope): Promise<void>;
+/**
+ * The same for giving a failed or died step up while the run commits. Unlike
+ * the seams above, the operation settles the step itself, under the
+ * reservation it runs with, so the caller writes no transition of its own.
+ */
+export declare function giveUpStepTree(root: string, dir: string, step: MigrateStep, skipInstall: boolean, reconcileCommand: string, scope: TreeScope): Promise<GiveUpOutcome>;
+/**
+ * The parent side. Holds one exclusive lock for the session's lifetime so a
+ * waiting step can tell a slow parent from a dead one, answers each request
+ * once, and removes its own requests on close; its answers stay for the steps
+ * still reading them. Requests carrying another session's nonce belong to
+ * that session and are never touched. Whether to install or commit comes from
+ * the policy the session started with, never from run state, which the
+ * agent's sandbox can write.
+ */
+export declare class MigrateCommitBroker {
+    private readonly root;
+    private readonly dir;
+    private readonly reconcileCommand;
+    private readonly policy;
+    readonly nonce: string;
+    private readonly handled;
+    private inFlight;
+    private readonly lock;
+    constructor(root: string, dir: string, reconcileCommand: string, policy: MigrateRunPolicy);
+    /** The request whose operation this process is running right now. */
+    get requestInFlight(): BrokerRequest | null;
+    /** Answers this session's unanswered requests, one at a time. */
+    service(): Promise<void>;
+    private record;
+    private answer;
+    /** Releases the lock; call after the last `service` settled. */
+    close(): void;
+    private notADirectory;
+}