[worker] Add a packaged startup wrapper

packages/worker/README.md

@@ -42,3 +42,18 @@ Github action builds a docker image for every PR with any change in `infra/eas-b
 ### VM template
 
 Github action builds a new vm template for every PR with any change in `infra/eas-build-worker-images/ios/{{ templateName }}`.
+
+### Packaged startup
+
+Existing services run `src/services/worker/dist/main.js`. In the worker archive,
+that path points to `bin/bootstrap.cjs`. The bootstrap loads only Node built-ins
+and starts `bin/start-worker.sh`. The shell then uses `exec` to start the normal
+worker with the original Node binary, options, and arguments.
+
+Put setup that must precede worker imports or Node startup options in the shell.
+The bootstrap forwards SIGINT, SIGTERM, IPC messages, and the worker exit status.
+It remains the supervised parent process; test service shutdown on both platforms
+before deployment. A failure in the startup shell prevents the worker from
+loading. Direct execution of `packages/worker/dist/main.js` bypasses this hook.
+
+Run `yarn workspace @expo/worker test:startup` for the process-level checks.

packages/worker/bin/bootstrap.cjs

@@ -0,0 +1,53 @@
+// This entry point must only load Node built-ins before the startup shell runs.
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+
+const worker = spawn(
+  '/bin/bash',
+  [
+    path.join(__dirname, 'start-worker.sh'),
+    process.execPath,
+    ...process.execArgv,
+    path.join(__dirname, '../dist/main.js'),
+    ...process.argv.slice(2),
+  ],
+  { stdio: process.send ? ['inherit', 'inherit', 'inherit', 'ipc'] : 'inherit' }
+);
+
+const signals = ['SIGINT', 'SIGTERM'];
+for (const signal of signals) {
+  process.on(signal, () => worker.kill(signal));
+}
+
+// Retain the readiness channel used by process managers in development.
+if (process.send) {
+  worker.on('message', message => {
+    if (process.connected) {
+      process.send(message, () => {});
+    }
+  });
+  process.on('message', message => {
+    if (worker.connected) {
+      worker.send(message, () => {});
+    }
+  });
+  process.on('disconnect', () => {
+    if (worker.connected) {
+      worker.disconnect();
+    }
+  });
+}
+
+worker.on('error', error => {
+  process.stderr.write(`Worker startup failed: ${error.stack ?? error}\n`, () => process.exit(1));
+});
+worker.on('exit', (code, signal) => {
+  if (signal) {
+    for (const forwarded of signals) {
+      process.removeAllListeners(forwarded);
+    }
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 1);
+  }
+});

packages/worker/bin/start-worker.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Startup setup belongs here, before the normal worker's Node process starts.
+exec "$@"

packages/worker/package.json

@@ -11,11 +11,12 @@
     "compile": "tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run build",
     "test": "yarn test:unit",
-    "test:unit": "./resources/jest --config jest.config.unit.ts",
+    "test:unit": "yarn test:startup && ./resources/jest --config jest.config.unit.ts",
     "test:unit:watch": "./resources/jest --config jest.config.unit.ts --watch",
     "test:integration": "./resources/jest --runInBand --config jest.config.integration.ts",
     "test:integration:watch": "./resources/jest --runInBand --config jest.config.integration.ts --watchAll",
-    "typecheck": "tsc"
+    "typecheck": "tsc",
+    "test:startup": "node --test tests/*.test.cjs"
   },
   "dependencies": {
     "@babel/core": "7.24.7",

packages/worker/package.sh

@@ -120,10 +120,10 @@ fi
 
 # Create backward-compatible symlink for orchestrator
 # The orchestrator expects ./src/services/worker/dist/main.js
-# but the new structure has ./packages/worker/dist/main.js
+# Route it through the packaged startup wrapper before loading worker modules.
 # We're only symlinking the specific file to discover any other legacy path usage
 mkdir -p "$target_root_dir/src/services/worker/dist"
-ln -s ../../../../packages/worker/dist/main.js "$target_root_dir/src/services/worker/dist/main.js"
+ln -s ../../../../packages/worker/bin/bootstrap.cjs "$target_root_dir/src/services/worker/dist/main.js"
 
 tar zcf $OUTPUT_FILE -C $target_root_dir .
 

packages/worker/tests/startup.test.cjs

@@ -0,0 +1,100 @@
+const assert = require('node:assert/strict');
+const { spawn } = require('node:child_process');
+const { once } = require('node:events');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test } = require('node:test');
+
+function archive(t, main, shell) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'worker-startup-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const worker = path.join(root, 'packages/worker');
+  fs.mkdirSync(path.join(worker, 'dist'), { recursive: true });
+  fs.cpSync(path.join(__dirname, '../bin'), path.join(worker, 'bin'), { recursive: true });
+  fs.writeFileSync(path.join(worker, 'dist/main.js'), main);
+  if (shell) {
+    fs.writeFileSync(path.join(worker, 'bin/start-worker.sh'), shell);
+  }
+  // Exercise the path that existing images run, including Node's symlink resolution.
+  const legacy = path.join(root, 'src/services/worker/dist/main.js');
+  fs.mkdirSync(path.dirname(legacy), { recursive: true });
+  fs.symlinkSync('../../../../packages/worker/bin/bootstrap.cjs', legacy);
+  return legacy;
+}
+
+function launch(t, entry, args = []) {
+  const child = spawn(process.execPath, [entry, ...args], {
+    stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+  });
+  t.after(() => {
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill('SIGKILL');
+    }
+  });
+  return child;
+}
+
+test(
+  'startup settings reach the worker before its first module runs',
+  { timeout: 10000 },
+  async t => {
+    const entry = archive(
+      t,
+      'process.send({ ready: true, args: process.argv.slice(2), setting: process.env.STARTUP_TEST }); process.on("message", () => process.exit(7));',
+      '#!/bin/bash\nset -euo pipefail\nexport STARTUP_TEST=installed\nexec "$@"\n'
+    );
+    const child = launch(t, entry, ['argument with spaces']);
+    const exited = once(child, 'exit');
+    assert.deepEqual((await once(child, 'message'))[0], {
+      ready: true,
+      args: ['argument with spaces'],
+      setting: 'installed',
+    });
+    child.send('stop');
+    assert.deepEqual(await exited, [7, null]);
+  }
+);
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  test(`forwards ${signal} and preserves termination status`, { timeout: 10000 }, async t => {
+    const entry = archive(t, 'process.send("ready"); setInterval(() => {}, 1000);');
+    const child = launch(t, entry);
+    const exited = once(child, 'exit');
+    await once(child, 'message');
+    child.kill(signal);
+    assert.deepEqual(await exited, [null, signal]);
+  });
+}
+
+test('startup failure prevents loading the worker', { timeout: 10000 }, async t => {
+  const entry = archive(
+    t,
+    'process.send("must not start");',
+    '#!/bin/bash\nset -euo pipefail\nexit 42\nexec "$@"\n'
+  );
+  const child = launch(t, entry);
+  const messages = [];
+  child.on('message', message => messages.push(message));
+  assert.deepEqual(await once(child, 'exit'), [42, null]);
+  assert.deepEqual(messages, []);
+});
+
+test('runs without IPC and retains stdout, stderr, and exit code', { timeout: 10000 }, async t => {
+  const entry = archive(
+    t,
+    'console.log("worker output"); console.error("worker error"); process.exit(9);'
+  );
+  const child = spawn(process.execPath, [entry], { stdio: ['ignore', 'pipe', 'pipe'] });
+  let stdout = '';
+  let stderr = '';
+  child.stdout.on('data', data => {
+    stdout += data;
+  });
+  child.stderr.on('data', data => {
+    stderr += data;
+  });
+  assert.deepEqual(await once(child, 'close'), [9, null]);
+  assert.equal(stdout, 'worker output\n');
+  assert.equal(stderr, 'worker error\n');
+});