fix(functions): report discovery crashes instead of blaming the timeout

[IzaakGough]

Fixes #7775 (and #5888)

Problem

User code failed to load. Cannot determine backend specification is common and hard to act on. Four reasons:

1. It says "timeout" even when your code crashed. Discovery polls the admin server until it answers. If the child dies while loading we just keep getting ECONNREFUSED until the budget runs out, so the real error never surfaces. detectFromOutputPath already handles this; HTTP discovery didn't.

2. FUNCTIONS_DISCOVERY_TIMEOUT is in seconds but the error printed milliseconds, and named neither the variable nor the unit:

   FUNCTIONS_DISCOVERY_TIMEOUT=1   ->   "Timeout after 1000"
   

   So the =30000 people pass around is 8.3 hours, not 30 seconds. It "works" by disabling the timeout.

3. The poll loop had no backoff. Measured against a refused port: ~144k attempts/sec, ~110% of one core, taken from the process we're waiting on.

4. The timeout timer was never cleared on the success path.

Changes

• detectFromPort races the child's exit, so a crash reports its exit code and stderr. serveAdmin returns { kill, serverExited }.
• Exit listeners move to spawn time. Neither event replays, so a server that died before kill() ran left a shutdown that never resolved. (Same bug as the Python one in Killed deploy orphans the Python discovery server (serving.py); orphans wedge and later deploys hang forever on connect ETIMEDOUT #10847.)
• FUNCTIONS_DISCOVERY_TIMEOUT accepts s and ms suffixes. Bare numbers still mean seconds, but a suspiciously large one now warns.
• Timeout message names the variable and uses seconds.
• 100ms backoff between polls, raced against the timeout. Matches functionsRuntimeWorker.
• clearTimeout on success.

Before / after

Slow load:

- Timeout after 10000. See https://...'
+ Timed out after 10s. If your code is slow to load, set FUNCTIONS_DISCOVERY_TIMEOUT
+ to allow more time (in seconds, e.g. FUNCTIONS_DISCOVERY_TIMEOUT=60). See https://...

Crash while loading, which previously showed the message above after a full 10s:

+ The functions process exited with code 134 before it could be analyzed.
+
+ FATAL ERROR: JavaScript heap out of memory

Testing

Unit tests for the env var parsing, the timeout message, and discovery ending on server exit. Existing detectFromPort tests unchanged. Also verified end to end against a real emulator, both slow-loading and crashing codebases.

[gemini-code-assist]

Code Review

This pull request improves function discovery error handling by reporting server crashes immediately instead of masking them as timeouts, and refactors FUNCTIONS_DISCOVERY_TIMEOUT parsing to support explicit unit suffixes. The review feedback highlights three key improvements: handling process spawn errors in serverExited to prevent potential hangs, utilizing the existing sleep utility from src/utils.ts per the style guide, and limiting the stderr buffer size to avoid potential memory issues.

[gemini-code-assist]

If the child process fails to start/spawn (e.g., due to a system error like ENOENT or EACCES), it will emit an "error" event instead of an "exit" event. Since serverExited only listens to "exit", it will never reject on spawn errors, causing discovery to hang until the timeout. Add an "error" event listener to serverExited to reject immediately with the spawn error.

    const serverExited = new Promise<never>((_resolve, reject) => {
      childProcess.once("exit", (code, signal) => {
        if (!armed) {
          return;
        }
        const how = code === null ? `signal ${String(signal)}` : `code ${code}`;
        const details = stderr.trim();
        reject(
          new FirebaseError(
            `User code failed to load. Cannot determine backend specification. ` +
              `The functions process exited with ${how} before it could be analyzed.` +
              (details ? `\\n\\n${details}` : ""),
          ),
        );
      });
      childProcess.once("error", (err) => {
        if (!armed) {
          return;
        }
        reject(
          new FirebaseError(
            `User code failed to load. Cannot determine backend specification. ` +
              `The functions process failed to start: ${err.message}`,
            { original: err },
          ),
        );
      });
    });

[gemini-code-assist]

Use the existing sleep utility from src/utils.ts instead of redefining it, as per the repository style guide.

Suggested change

	const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
	import { sleep } from "../../../../utils";

References

1. Look for existing utilities first: Before writing common helper functions (e.g., for logging, file system operations, promises, string manipulation), check src/utils.ts to see if a suitable function already exists. ^(link)

[gemini-code-assist]

Buffer stderr with a size limit to prevent potential memory issues or Out-Of-Memory (OOM) errors if the child process produces excessive logs.

Suggested change

	let stderr = "";
	childProcess.stderr?.on("data", (chunk: Buffer) => {
	stderr += chunk.toString();
	});
	let stderr = "";
	childProcess.stderr?.on("data", (chunk: Buffer) => {
	if (stderr.length < 64 * 1024) {
	stderr += chunk.toString();
	}
	});