trm-core 9.10.6 → 10.0.1

package/dist/actions/commons/utils/packageCleanup.d.ts

@@ -0,0 +1,168 @@
+import { InstallTransport } from "../../../systemConnector";
+import { Transport } from "../../../transport";
+import { TransportBinary, TrmPackage } from "../../../trmPackage";
+import { AbstractRegistry } from "../../../registry";
+import { DEVCLASS, E071, TADIR, TDEVC, ZTRM_OBJ_LOCK } from "../../../client";
+import type { InstallPackageReplacements } from "../../install";
+import { ActionLockScope } from "./actionLocks";
+type CleanupObject = Pick<E071, 'pgmid' | 'object' | 'objName'>;
+/** Rollback state written while removing the objects of an installed release. */
+export interface PackageCleanupRevert {
+    /** SAP packages generated by the action. */
+    sapPackages: DEVCLASS[];
+    /**
+     * Transportable packages created to export the objects of a temporary (`$`) installation.
+     * Not part of the action's packages: they are deleted by {@link deleteCleanupStagingPackages}.
+     */
+    stagingPackages?: DEVCLASS[];
+    /**
+     * Custom namespaces imported only to stage objects of a temporary installation.
+     * Deleted with the staging packages.
+     */
+    temporaryNamespaces?: string[];
+    dele?: TransportBinary;
+    /** Set before the deletion transport import: only then the objects must be restored from `dele`. */
+    deleImportStarted?: boolean;
+    cleanupOriginalTadir?: TADIR[];
+    cleanupTemporaryPackages?: TDEVC[];
+    updateCleanupTransport?: Transport;
+    updateTablesBackupTransport?: Transport;
+    retainedTables?: TransportBinary;
+    /**
+     * Tables kept installed by an upgrade, set with {@link PackageCleanupRevert.retainedTables}: a rollback of the
+     * incoming import must not delete them, the backup restores their previous definition.
+     */
+    retainedTableObjects?: CleanupObject[];
+    /** Customizing transports whose rows were added to the deletion transport. */
+    cleanupCustomizingSources?: string[];
+    /** Set before forwarding the deletion transport, as the TMS queue may change even when the call fails. */
+    deleInTargetTms?: boolean;
+}
+/** Minimum workflow context needed to remove an installed release from the target system. */
+export interface PackageCleanupContext {
+    lockScope?: ActionLockScope;
+    rawInput: {
+        packageData: {
+            name: string;
+            registry: AbstractRegistry;
+        };
+        contextData?: {
+            noInquirer?: boolean;
+            /** Packages installed on the target system: SAP packages of other installations are never cleaned up. */
+            systemPackages?: TrmPackage[];
+        };
+    };
+    runtime?: {
+        /** Installed release whose objects are removed. */
+        update: TrmPackage;
+        /** Install package mappings recorded for the installed release. */
+        previousInstallPackages: InstallPackageReplacements[];
+        /** Transports recorded for the installed release; its customizing comes from the `CUST` ones. */
+        previousInstallTransports?: InstallTransport[];
+        dele?: Transport;
+        /**
+         * Objects already deleted by this run (the uninstalls of the TRM packages installed underneath):
+         * the system may still list them for a while after their deletion transport import.
+         */
+        deletedObjects?: Pick<E071, 'pgmid' | 'object' | 'objName'>[];
+    };
+    revert?: PackageCleanupRevert;
+}
+/** What remains on the system once the cleanup is complete. */
+export type PackageCleanupTarget = {
+    /** Objects shipped by the incoming release. Empty when uninstalling. */
+    incomingObjects: TADIR[];
+    /** SAP packages that hold the incoming release. Empty when uninstalling. */
+    keptDevclasses: string[];
+    /** Logger/Inquirer prefix shown while the cleanup runs. */
+    prefix: string;
+    /** Action name used in abort messages, e.g. `Update`. */
+    actionName: string;
+    /**
+     * When `true`, an unauthorized deletion transport request is rethrown after restoring
+     * object assignments. Otherwise it only logs a manual cleanup warning.
+     */
+    requireDeletion: boolean;
+    /**
+     * When `true`, the customizing rows shipped by the installed release are kept.
+     * Otherwise they are always deleted, without asking.
+     */
+    keepCustomizing?: boolean;
+    /**
+     * Table content the incoming release imports after the cleanup: rows it ships again are rewritten,
+     * so only the others are listed and confirmed. A row without `tabkey` is a whole table.
+     * Empty when uninstalling.
+     */
+    incomingCustomizing?: CustomizingRow[];
+};
+/** A row of table content carried by a transport: a key of a table, or the whole table without `tabkey`. */
+export type CustomizingRow = {
+    table: string;
+    tabkey?: string;
+};
+/**
+ * TRM packages, other than `installed`, installed in one of `devclasses` (normalized SAP package
+ * names, usually the live subtree of the installed release).
+ */
+export declare function getPackagesInstalledIn(systemPackages: TrmPackage[], installed: TrmPackage, devclasses: Set<string>): TrmPackage[];
+/**
+ * Locks on those of `objects` that removing `installed` certainly deletes: the objects of its
+ * installed transport still in its SAP packages. These would abort the cleanup at its objects
+ * lock check, so they can be checked before asking anything. Objects added locally or moved
+ * outside the installation are left out, as the cleanup may keep them.
+ */
+export declare function getInstalledObjectsLocks(installed: TrmPackage, previousInstallPackages: InstallPackageReplacements[], systemPackages: TrmPackage[], objects: CleanupObject[]): Promise<ZTRM_OBJ_LOCK[]>;
+/** Deletes every temporary package, reporting the first failure after the cleanup pass. */
+export declare function deleteTemporaryCleanupPackages(temporaryPackages: Array<Pick<E071, 'objName'>>): Promise<void>;
+/**
+ * Deletes the staging packages created by the cleanup, once their objects were assigned back.
+ * Every package is attempted; the first failure is thrown afterwards.
+ */
+export declare function deleteCleanupStagingPackages(context: PackageCleanupContext): Promise<void>;
+/**
+ * Assigns the objects that still exist back to their previous TADIR rows. Every object is
+ * attempted; the first failure is thrown afterwards.
+ */
+export declare function restoreTadirAssignments(originals: TADIR[]): Promise<void>;
+/** Creates a short-lived transportable package, in `namespace` when set, so CTS can export local objects. */
+export declare function createStagingPackage(context: Pick<PackageCleanupContext, 'revert'>, namespace: string): Promise<string>;
+/**
+ * Removes the objects of the installed release (`context.runtime.update`) that are not part
+ * of `target`, through a deletion transport generated by the registry.
+ *
+ * Shared by upgrades, where the target is the incoming release, and by uninstalls, where the
+ * target is empty. It also removes SAP packages left empty, locally added objects (after
+ * confirmation), the package namespace when no other package uses it, and the customizing rows
+ * of the installed release. Tables shipped again by the target are kept and
+ * backed up so a rollback preserves their data.
+ */
+export declare function cleanupInstalledPackage(context: PackageCleanupContext, target: PackageCleanupTarget): Promise<void>;
+/**
+ * Whether the deletion transport generated by {@link cleanupInstalledPackage} must be carried
+ * through the landscape. Objects of a temporary (`$`) installation only exist on this system.
+ */
+export declare function isDeletionForwardable(context: PackageCleanupContext): boolean;
+/**
+ * Adds the deletion transport to the import queue of the landscape target system, so the
+ * removed objects are also deleted there.
+ * For a clean landscape, it has to be imported before any transport of a later release.
+ */
+export declare function forwardDeletionTransport(context: PackageCleanupContext, targetSystem: string): Promise<void>;
+/**
+ * Removes a transport from the import queue of `targetSystem`. Only the queue of the connected
+ * system can be changed: another system's queue would need its credentials, so the operator is
+ * warned to remove it manually. Returns whether the transport was removed.
+ */
+export declare function removeFromImportQueue(trkorr: string, targetSystem: string, description: string): Promise<boolean>;
+/** Removes the deletion transport from the target system import queue, when it was forwarded. */
+export declare function revertForwardedDeletionTransport(context: PackageCleanupContext, targetSystem: string): Promise<void>;
+/**
+ * Rolls back {@link cleanupInstalledPackage}: recreates deleted temporary packages, deletes the
+ * deletion transport or, once its import started, re-imports the copy of the deleted objects,
+ * restores retained tables, and restores object assignments.
+ * With `restore` set to `false` (a later destructive cleanup failed), previous state is not
+ * restored over objects that were not deleted: only the unreleased transports are deleted.
+ * Every independent operation is attempted; the first failure is thrown afterwards.
+ */
+export declare function revertInstalledPackageCleanup(context: PackageCleanupContext, restore?: boolean): Promise<void>;
+export {};