refactor(apps): extract shared execution-epoch guard from local-execution.ts

The generation-counter pattern protecting against an abandoned scope's
late cleanup corrupting a newer, currently-active one was independently
reimplemented in local-execution.ts, network-guard.ts, and env-guard.ts.
Extracts the shared logic into execution-epoch.ts's createEpochGuard();
network-guard.ts and env-guard.ts adopt it in later commits.

Author: tyffical

packages/plugins/apps/src/vite/execution-epoch.test.ts

@@ -0,0 +1,89 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the MIT License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2019-Present Datadog, Inc.
+
+import { createEpochGuard } from '@dd/apps-plugin/vite/execution-epoch';
+
+describe('execution-epoch — createEpochGuard', () => {
+    test('Should report a fresh scope as current and report no active scope before any start()', () => {
+        const guard = createEpochGuard();
+        expect(guard.hasActiveScope()).toBe(false);
+
+        const scope = guard.start();
+        expect(scope.isCurrent()).toBe(true);
+        expect(guard.hasActiveScope()).toBe(true);
+    });
+
+    test('Should invalidate an older scope once a newer one starts', () => {
+        const guard = createEpochGuard();
+        const older = guard.start();
+        expect(older.isCurrent()).toBe(true);
+
+        const newer = guard.start();
+        expect(older.isCurrent()).toBe(false);
+        expect(newer.isCurrent()).toBe(true);
+        expect(guard.hasActiveScope()).toBe(true);
+    });
+
+    test('Should make concludeIfCurrent a no-op returning false for an already-superseded scope', () => {
+        const guard = createEpochGuard();
+        const older = guard.start();
+        guard.start();
+
+        expect(older.concludeIfCurrent()).toBe(false);
+        // The newer scope must be unaffected by the older one's no-op conclude.
+        expect(guard.hasActiveScope()).toBe(true);
+    });
+
+    test('Should conclude a still-current scope, clearing hasActiveScope', () => {
+        const guard = createEpochGuard();
+        const scope = guard.start();
+
+        expect(scope.concludeIfCurrent()).toBe(true);
+        expect(scope.isCurrent()).toBe(false);
+        expect(guard.hasActiveScope()).toBe(false);
+    });
+
+    test('Should make a second concludeIfCurrent call on the same scope a no-op', () => {
+        const guard = createEpochGuard();
+        const scope = guard.start();
+
+        expect(scope.concludeIfCurrent()).toBe(true);
+        expect(scope.concludeIfCurrent()).toBe(false);
+    });
+
+    test('Should invalidate the active scope and clear hasActiveScope on forceInvalidate, without starting a new one', () => {
+        const guard = createEpochGuard();
+        const scope = guard.start();
+
+        guard.forceInvalidate();
+
+        expect(scope.isCurrent()).toBe(false);
+        expect(guard.hasActiveScope()).toBe(false);
+    });
+
+    test('Should make forceInvalidate followed by a fresh start() behave like an ordinary new scope', () => {
+        const guard = createEpochGuard();
+        const abandoned = guard.start();
+        guard.forceInvalidate();
+
+        const current = guard.start();
+
+        expect(abandoned.isCurrent()).toBe(false);
+        expect(current.isCurrent()).toBe(true);
+        expect(guard.hasActiveScope()).toBe(true);
+
+        // The abandoned scope's late conclude must not corrupt the new one.
+        expect(abandoned.concludeIfCurrent()).toBe(false);
+        expect(current.isCurrent()).toBe(true);
+    });
+
+    test('Should keep independently-created guards from sharing any state', () => {
+        const guardA = createEpochGuard();
+        const guardB = createEpochGuard();
+
+        const scopeA = guardA.start();
+        expect(guardB.hasActiveScope()).toBe(false);
+        expect(scopeA.isCurrent()).toBe(true);
+    });
+});

packages/plugins/apps/src/vite/execution-epoch.ts

@@ -0,0 +1,78 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the MIT License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2019-Present Datadog, Inc.
+
+/**
+ * The generation-counter guard against the "abandoned scope's late cleanup
+ * corrupts a newer, currently-active scope" race — shared by
+ * `network-guard.ts`, `env-guard.ts`, and `local-execution.ts`'s own
+ * execution bookkeeping, each of which independently reimplemented this
+ * exact pattern before this extraction.
+ *
+ * A `runScriptLocally` execution isn't cancelled on timeout, only abandoned
+ * — its `fn` may still be running (or, for a genuine hang, never settle) well
+ * after a newer execution has started. Any cleanup an abandoned scope's own
+ * `finally` performs on a shared, process-wide resource (network-guard's
+ * monkey-patches, env-guard's `process.env` swap) must not run once a newer
+ * scope has taken over — an equality check against `myGeneration` at the
+ * moment cleanup actually fires is what makes that check load-bearing rather
+ * than a race in itself: `activeGeneration` only changes under a later
+ * `start()`/`forceInvalidate()`, never out from under a still-current scope.
+ */
+export interface EpochScope {
+    /** True until a newer scope starts, or this one (or every scope) is concluded/invalidated. */
+    isCurrent(): boolean;
+    /**
+     * If this scope is still current, marks no scope as active and returns
+     * `true`; otherwise a no-op returning `false`. Use in a `finally` to gate
+     * cleanup of a shared resource on still owning it.
+     */
+    concludeIfCurrent(): boolean;
+}
+
+export interface EpochGuard {
+    /** Starts a new scope, superseding whichever one was previously active. */
+    start(): EpochScope;
+    /**
+     * True if some started scope hasn't yet been concluded or superseded —
+     * only needed by a consumer with its own separate "is anything currently
+     * active" query (e.g. `network-guard.ts`'s `runAllowed`).
+     */
+    hasActiveScope(): boolean;
+    /**
+     * Unconditionally invalidates the active scope, without starting a new
+     * one — the backstop for a scope whose own `fn` never settles (see
+     * `network-guard.ts`'s `forceReset` for why this exists independently of
+     * a scope's own `finally`).
+     */
+    forceInvalidate(): void;
+}
+
+export function createEpochGuard(): EpochGuard {
+    let currentGeneration = 0;
+    let activeGeneration: number | null = null;
+
+    return {
+        start() {
+            const myGeneration = ++currentGeneration;
+            activeGeneration = myGeneration;
+            return {
+                isCurrent: () => activeGeneration === myGeneration,
+                concludeIfCurrent: () => {
+                    if (activeGeneration === myGeneration) {
+                        activeGeneration = null;
+                        return true;
+                    }
+                    return false;
+                },
+            };
+        },
+        hasActiveScope() {
+            return activeGeneration !== null;
+        },
+        forceInvalidate() {
+            currentGeneration += 1;
+            activeGeneration = null;
+        },
+    };
+}

packages/plugins/apps/src/vite/local-execution.test.ts

@@ -878,7 +878,7 @@ describe('local-execution — executeScriptLocally', () => {
 
             const makeLoadModule = (actionCatalogDelayMs: number): LoadModule => {
                 return async (specifier: string) => {
-                    if (specifier === func.absolutePath) {
+                    if (specifier === func.absolutePath + LOCAL_EXECUTION_LOAD_SUFFIX) {
                         return { example: () => 'result' };
                     }
                     if (specifier === '@datadog/action-catalog/action-execution') {

packages/plugins/apps/src/vite/local-execution.ts

@@ -22,6 +22,8 @@ import type { Logger } from '@dd/core/types';
 import type { BackendFunction } from '../backend/types';
 import { LOCAL_EXECUTION_LOAD_SUFFIX } from '../constants';
 
+import { createEpochGuard } from './execution-epoch';
+
 type BackendOutputs = { data: unknown };
 
 interface ActionCallArgs {
@@ -107,13 +109,15 @@ function assertConnectionIdAllowed(
 let queueTail: Promise<unknown> = Promise.resolve();
 
 /**
- * Bumped once per execution, in `runScriptLocally`, before anything else.
- * On timeout, an execution checks this against its own epoch to decide
+ * Started once per execution, in `runScriptLocally`, before anything else.
+ * On timeout, an execution checks its own scope against this to decide
  * whether it's safe to poison the shared action-catalog registration — see
  * `runScriptLocally`'s own comment for why this check, rather than a
- * per-call guard, is what actually protects that path.
+ * per-call guard, is what actually protects that path. See
+ * `execution-epoch.ts` for the shared generation-counter pattern this and
+ * `network-guard.ts`/`env-guard.ts` all rely on.
  */
-let currentExecutionEpoch = 0;
+const executionEpoch = createEpochGuard();
 
 function enqueue<T>(run: () => Promise<T>): Promise<T> {
     const result = queueTail.then(run);
@@ -446,11 +450,11 @@ async function runScriptLocally(
     // execution may already be running (having registered its own valid
     // implementation) by the time this one's `fn()` finally settles or its
     // timeout fires, and clobbering ITS registration would be the same bug
-    // in a new shape. `currentExecutionEpoch` gates that everywhere (see
-    // `concludeExecution` below) — including the `finally` block, since
-    // settling late for an abandoned execution is exactly the case this
-    // guards against, not just the timeout path.
-    const myEpoch = ++currentExecutionEpoch;
+    // in a new shape. `scope` gates that everywhere (see `concludeExecution`
+    // below) — including the `finally` block, since settling late for an
+    // abandoned execution is exactly the case this guards against, not just
+    // the timeout path.
+    const scope = executionEpoch.start();
     let abandoned = false;
     let reRegisterActionCatalog: ((nextExecuteAction: ExecuteAction) => void) | undefined;
     let poisonBackendRuntime: BackendRuntimePoison | undefined;
@@ -504,11 +508,19 @@ async function runScriptLocally(
     // which for an abandoned execution can be well after a newer one has
     // already started and registered, so the check is load-bearing there.
     // Kept in one place so both call sites stay consistent.
+    //
+    // Poisons BEFORE concluding, not after: `register()`'s own re-registration
+    // guard (see `registerActionCatalogIfInstalled`) checks `scope.isCurrent()`
+    // too, and the poison calls below route back through that same `register`
+    // closure — concluding first would make the scope look already-inactive
+    // to that inner check, silently skipping the poison it was meant to
+    // perform.
     const concludeExecution = () => {
-        if (currentExecutionEpoch === myEpoch) {
+        if (scope.isCurrent()) {
             abandoned = true;
             poisonActionCatalogRegistration();
             poisonBackendRuntimeRegistration();
+            scope.concludeIfCurrent();
         }
     };
 
@@ -518,18 +530,16 @@ async function runScriptLocally(
         Source: LOCAL_DEV_SOURCE,
     };
 
-    const isCurrent = () => currentExecutionEpoch === myEpoch;
-
     const run = async (): Promise<BackendOutputs> => {
         (globalThis as Record<string, unknown>).$ = $;
         [reRegisterActionCatalog, poisonBackendRuntime] = await Promise.all([
             registerActionCatalogIfInstalled(
                 loadModule,
                 guardedExecuteAction,
                 func.allowedConnectionIds,
-                isCurrent,
+                scope.isCurrent,
             ),
-            registerBackendRuntimeIfInstalled(loadModule, $, isCurrent, func.name),
+            registerBackendRuntimeIfInstalled(loadModule, $, scope.isCurrent, func.name),
         ]);
         if (abandoned) {
             // This execution was already abandoned while the registration