harden local execution: signal reporting, shutdown cleanup, edge-case coverage

- Report the OS signal (SIGSEGV/SIGKILL/etc.) when a child is killed rather
  than exiting normally, instead of an opaque "exited with code null" --
  distinguishes an OOM kill or native-module crash from a plain crash.
- Track live children in a Set; export killAllLocalExecutionChildren() for
  the dev server to call on its own shutdown so executions in flight don't
  leave orphaned Node processes behind.
- Add regression coverage for behavior that already worked but had no test:
  non-serializable return values (circular references) produce a clean
  rejection instead of hanging, and concurrent $.Actions calls within a
  single execution resolve to their own correct results.

Milestone 1 of APPS-2792's local Node execution kickoff plan.

Author: tyffical

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

@@ -23,7 +23,11 @@ import type { BackendFunction } from '../backend/types';
 import { generateDevVirtualEntryContent } from '../backend/virtual-entry';
 
 import { getBaseBackendBuildConfig } from './build-config';
-import { executeScriptLocally } from './local-execution';
+import {
+    executeScriptLocally,
+    getMostRecentlyForkedChildForTest,
+    killAllLocalExecutionChildren,
+} from './local-execution';
 
 const log = getMockLogger();
 
@@ -135,4 +139,112 @@ describe('executeScriptLocally (real bundle, no mocks)', () => {
             'deliberate bug in a real bundled backend function',
         );
     }, 20_000);
+
+    test('returns a clean, actionable error when the backend function returns a non-serializable value (a circular reference), instead of hanging or crashing opaquely', async () => {
+        const workingDir = getTempWorkingDir(`local-exec-poc-circular-${Date.now()}`);
+        const sourceCode = `
+            export async function circular() {
+                const obj = {};
+                obj.self = obj;
+                return obj;
+            }
+        `;
+        const code = await bundleRealBackendFunction(workingDir, 'circular', sourceCode);
+
+        const func: BackendFunction = {
+            relativePath: 'src/circular',
+            name: 'circular',
+            absolutePath: `${workingDir}/src/circular.backend.ts`,
+            allowedConnectionIds: [],
+        };
+
+        await expect(executeScriptLocally(code, func, [], log)).rejects.toThrow(
+            /circular|serializ/i,
+        );
+    }, 20_000);
+
+    test('resolves each concurrent $.Actions call within a single execution to its own correct result, not a mixed-up one', async () => {
+        const workingDir = getTempWorkingDir(`local-exec-poc-concurrent-actions-${Date.now()}`);
+        const sourceCode = `
+            export async function concurrentActions() {
+                const [a, b, c] = await Promise.all([
+                    $.Actions.slack.chat.postMessage({ inputs: { channel: '#a' }, connectionId: 'connection:slack:poc' }),
+                    $.Actions.github.issues.create({ inputs: { title: 'b' }, connectionId: 'connection:slack:poc' }),
+                    $.Actions.jira.jira.createIssue({ inputs: { summary: 'c' }, connectionId: 'connection:slack:poc' }),
+                ]);
+                return { a, b, c };
+            }
+        `;
+        const code = await bundleRealBackendFunction(workingDir, 'concurrentActions', sourceCode);
+
+        const func: BackendFunction = {
+            relativePath: 'src/concurrentActions',
+            name: 'concurrentActions',
+            absolutePath: `${workingDir}/src/concurrentActions.backend.ts`,
+            allowedConnectionIds: ['connection:slack:poc'],
+        };
+
+        const outputs = await executeScriptLocally(code, func, [], log);
+
+        expect(outputs.data).toMatchObject({
+            a: { stub: true, fqn: 'com.datadoghq.slack.chat.postMessage' },
+            b: { stub: true, fqn: 'com.datadoghq.github.issues.create' },
+            c: { stub: true, fqn: 'com.datadoghq.jira.jira.createIssue' },
+        });
+    }, 20_000);
+
+    test('reports the signal when a child process is killed rather than exiting normally (e.g. an OOM-killed or crashed native module), instead of an opaque "code null" error', async () => {
+        const workingDir = getTempWorkingDir(`local-exec-poc-signal-${Date.now()}`);
+        // A function that never resolves -- gives the test time to kill the
+        // child with a signal before it would otherwise finish or time out.
+        const sourceCode = `
+            export async function hangs() {
+                return new Promise(() => {});
+            }
+        `;
+        const code = await bundleRealBackendFunction(workingDir, 'hangs', sourceCode);
+
+        const func: BackendFunction = {
+            relativePath: 'src/hangs',
+            name: 'hangs',
+            absolutePath: `${workingDir}/src/hangs.backend.ts`,
+            allowedConnectionIds: [],
+        };
+
+        const execution = executeScriptLocally(code, func, [], log, 5_000);
+        const child = getMostRecentlyForkedChildForTest();
+        // Give the child a moment to actually start running before killing it,
+        // so this exercises a real in-flight kill, not a race with fork() itself.
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, 200));
+        child?.kill('SIGSEGV');
+
+        await expect(execution).rejects.toThrow(/SIGSEGV/);
+    }, 20_000);
+
+    test('killAllLocalExecutionChildren terminates an in-flight child (dev-server shutdown must not leave orphaned processes)', async () => {
+        const workingDir = getTempWorkingDir(`local-exec-poc-shutdown-${Date.now()}`);
+        const sourceCode = `
+            export async function hangs() {
+                return new Promise(() => {});
+            }
+        `;
+        const code = await bundleRealBackendFunction(workingDir, 'hangs', sourceCode);
+
+        const func: BackendFunction = {
+            relativePath: 'src/hangs',
+            name: 'hangs',
+            absolutePath: `${workingDir}/src/hangs.backend.ts`,
+            allowedConnectionIds: [],
+        };
+
+        const execution = executeScriptLocally(code, func, [], log, 5_000);
+        const child = getMostRecentlyForkedChildForTest();
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, 200));
+
+        expect(child?.killed).toBe(false);
+        killAllLocalExecutionChildren();
+
+        await expect(execution).rejects.toThrow();
+        expect(child?.killed).toBe(true);
+    }, 20_000);
 });

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

@@ -16,13 +16,39 @@
  */
 
 import type { Logger } from '@dd/core/types';
+import type { ChildProcess } from 'child_process';
 import { fork } from 'child_process';
 import * as path from 'path';
 
 import type { BackendFunction } from '../backend/types';
 
 type BackendOutputs = { data: unknown };
 
+// Tracks every child currently executing a backend function, so the dev
+// server can kill them all on its own shutdown instead of leaving orphaned
+// Node processes behind (see killAllLocalExecutionChildren below). A Set
+// rather than a single reference because multiple executions can be
+// in-flight concurrently -- each gets its own forked child (pooling is
+// deliberately deferred, see the design doc's Timeline section).
+const liveChildren = new Set<ChildProcess>();
+
+/**
+ * Kill every backend-function child process currently executing. Call this
+ * from the dev server's own shutdown handling (SIGINT/SIGTERM/process exit)
+ * once local execution is wired in -- not yet called anywhere, since this
+ * file isn't wired into createDevServerMiddleware yet.
+ */
+export function killAllLocalExecutionChildren(): void {
+    for (const child of liveChildren) {
+        child.kill();
+    }
+}
+
+/** Test-only: exposes the most recently forked child so tests can exercise real signal-based kills. */
+export function getMostRecentlyForkedChildForTest(): ChildProcess | undefined {
+    return Array.from(liveChildren).at(-1);
+}
+
 interface ActionRequestMessage {
     type: 'action-request';
     id: number;
@@ -73,16 +99,25 @@ export function executeScriptLocally(
         // `env`, never inherit process.env wholesale -- see the design doc's
         // Secrets Handling section (never hand secrets to the child).
         const child = fork(LOCAL_EXEC_CHILD_SCRIPT, [], { stdio: 'inherit', env: {} });
+        liveChildren.add(child);
         let settled = false;
 
+        const settle = (fn: () => void) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            liveChildren.delete(child);
+            fn();
+        };
+
         const timer = setTimeout(() => {
-            if (!settled) {
-                settled = true;
+            settle(() => {
                 child.kill();
                 reject(
                     new Error(`Local execution of "${func.name}" timed out after ${timeoutMs}ms`),
                 );
-            }
+            });
         }, timeoutMs);
 
         child.on('message', (msg: ChildMessage) => {
@@ -105,38 +140,46 @@ export function executeScriptLocally(
                 return;
             }
 
-            if (msg.type === 'result' && !settled) {
-                settled = true;
-                clearTimeout(timer);
-                resolve({ data: msg.result });
+            if (msg.type === 'result') {
+                settle(() => {
+                    clearTimeout(timer);
+                    resolve({ data: msg.result });
+                });
                 return;
             }
 
-            if (msg.type === 'error' && !settled) {
-                settled = true;
-                clearTimeout(timer);
-                reject(new Error(msg.error));
+            if (msg.type === 'error') {
+                settle(() => {
+                    clearTimeout(timer);
+                    reject(new Error(msg.error));
+                });
             }
         });
 
-        child.on('exit', (code) => {
-            if (!settled) {
-                settled = true;
+        child.on('exit', (code, signal) => {
+            settle(() => {
                 clearTimeout(timer);
+                // A signal (not a plain exit code) means the OS terminated the
+                // process directly -- most commonly an OOM kill (SIGKILL) or a
+                // native-module crash (SIGSEGV/SIGABRT). Report it explicitly:
+                // "exited with code null" is meaningless to a developer trying
+                // to tell an OOM apart from a native-module crash.
+                const cause = signal
+                    ? `was killed by signal ${signal}`
+                    : `exited with code ${code}`;
                 reject(
                     new Error(
-                        `Local execution of "${func.name}" exited with code ${code} before reporting a result`,
+                        `Local execution of "${func.name}" ${cause} before reporting a result`,
                     ),
                 );
-            }
+            });
         });
 
         child.on('error', (err) => {
-            if (!settled) {
-                settled = true;
+            settle(() => {
                 clearTimeout(timer);
                 reject(err);
-            }
+            });
         });
 
         child.send({ type: 'execute', scriptBody, backendFunctionArgs: args });