refactor(gateway): inject platform into isMuslLibc, broaden exit-as-failure

Address review feedback on #36:

- isMuslLibc(platform = process.platform): accept the platform as an
  argument so tests don't need to mutate process.platform (which is
  non-configurable in some Node versions and would have thrown there).
  All 6 tests now pass the platform explicitly.

- Spawn 'exit' handler: previously only recorded spawnFailure when
  code !== 0 && code !== null, so exits via signal (code===null, e.g.
  OOM) or a clean exit-0 before readiness still fell through to the
  generic 30s timeout. Now records spawnFailure for any exit-before-
  ready, with the descriptor adapting to "code N" vs "signal X". Also
  guarded against overwriting a spawn-error reason that already populated
  spawnFailure.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: NitayRabi

src/gateway-manager.ts

@@ -156,8 +156,10 @@ export class IBGatewayManager {
   // Detect whether the current Linux system uses musl libc (Alpine, etc.) rather than glibc.
   // The bundled glibc JRE cannot exec on musl — its ELF interpreter /lib64/ld-linux-x86-64.so.2
   // does not exist there, producing an opaque ENOENT at spawn time.
-  static isMuslLibc(): boolean {
-    if (process.platform !== 'linux') {
+  // The platform argument is injected so tests can exercise the matrix without mutating
+  // process.platform (which is non-configurable on some Node versions).
+  static isMuslLibc(platform: NodeJS.Platform = process.platform): boolean {
+    if (platform !== 'linux') {
       return false;
     }
     // process.report.getReport() exposes glibcVersionRuntime when glibc is present.
@@ -384,10 +386,16 @@ export class IBGatewayManager {
 
       this.gatewayProcess.on('exit', (code, signal) => {
         this.log(`🛑 Gateway process exited with code ${code}, signal ${signal}`);
-        if (!this.isReady && code !== 0 && code !== null) {
+        // Any exit before the gateway became ready is a failure: a clean exit-0 means the JVM
+        // terminated without ever opening the HTTP port (e.g. config error), and code===null
+        // means the process was killed by a signal (e.g. OOM). Recording spawnFailure for all
+        // of these makes waitForGateway() bail out fast instead of polling for 30s.
+        if (!this.isReady && !this.spawnFailure) {
+          const exitDescriptor =
+            code !== null ? `code ${code}` : `signal ${signal ?? 'unknown'}`;
           this.spawnFailure = {
-            reason: `IB Gateway process exited with code ${code} before becoming ready`,
-            details: stderrTail.trim() || `(no stderr captured; signal=${signal ?? 'none'})`,
+            reason: `IB Gateway process exited (${exitDescriptor}) before becoming ready`,
+            details: stderrTail.trim() || `(no stderr captured)`,
           };
         }
         this.gatewayProcess = null;

test/gateway-manager.test.ts

@@ -12,66 +12,56 @@ vi.mock('fs', async () => {
 });
 
 describe('IBGatewayManager.isMuslLibc', () => {
-  const originalPlatform = process.platform;
   const originalReport = (process as unknown as { report?: unknown }).report;
 
   afterEach(() => {
-    Object.defineProperty(process, 'platform', { value: originalPlatform });
     Object.defineProperty(process, 'report', { configurable: true, value: originalReport });
     vi.mocked(fs.existsSync).mockReset();
-    vi.mocked(fs.existsSync).mockImplementation((p: fs.PathLike) => {
-      // Default: nothing exists unless a test opts in.
-      return false;
-    });
+    vi.mocked(fs.existsSync).mockImplementation(() => false);
   });
 
   it('returns false on non-Linux platforms without consulting libc', () => {
-    Object.defineProperty(process, 'platform', { value: 'darwin' });
     vi.mocked(fs.existsSync).mockReturnValue(true); // would lie if consulted
-    expect(IBGatewayManager.isMuslLibc()).toBe(false);
+    expect(IBGatewayManager.isMuslLibc('darwin')).toBe(false);
+    expect(IBGatewayManager.isMuslLibc('win32')).toBe(false);
   });
 
   it('returns false on Linux when process.report exposes a glibc runtime version', () => {
-    Object.defineProperty(process, 'platform', { value: 'linux' });
     Object.defineProperty(process, 'report', { configurable: true, value: {
       getReport: () => ({ header: { glibcVersionRuntime: '2.36' } }),
     } });
-    expect(IBGatewayManager.isMuslLibc()).toBe(false);
+    expect(IBGatewayManager.isMuslLibc('linux')).toBe(false);
   });
 
   it('returns true on Linux when glibcVersionRuntime is missing and the musl loader is on disk', () => {
-    Object.defineProperty(process, 'platform', { value: 'linux' });
     Object.defineProperty(process, 'report', { configurable: true, value: {
       getReport: () => ({ header: {} }),
     } });
     vi.mocked(fs.existsSync).mockImplementation(
       (p: fs.PathLike) => p === '/lib/ld-musl-x86_64.so.1',
     );
-    expect(IBGatewayManager.isMuslLibc()).toBe(true);
+    expect(IBGatewayManager.isMuslLibc('linux')).toBe(true);
   });
 
   it('returns true when only the aarch64 musl loader is present', () => {
-    Object.defineProperty(process, 'platform', { value: 'linux' });
     Object.defineProperty(process, 'report', { configurable: true, value: {
       getReport: () => ({ header: {} }),
     } });
     vi.mocked(fs.existsSync).mockImplementation(
       (p: fs.PathLike) => p === '/lib/ld-musl-aarch64.so.1',
     );
-    expect(IBGatewayManager.isMuslLibc()).toBe(true);
+    expect(IBGatewayManager.isMuslLibc('linux')).toBe(true);
   });
 
   it('returns false when neither glibc nor a musl loader is detectable', () => {
-    Object.defineProperty(process, 'platform', { value: 'linux' });
     Object.defineProperty(process, 'report', { configurable: true, value: {
       getReport: () => ({ header: {} }),
     } });
     vi.mocked(fs.existsSync).mockReturnValue(false);
-    expect(IBGatewayManager.isMuslLibc()).toBe(false);
+    expect(IBGatewayManager.isMuslLibc('linux')).toBe(false);
   });
 
   it('falls back to the filesystem check if process.report.getReport throws', () => {
-    Object.defineProperty(process, 'platform', { value: 'linux' });
     Object.defineProperty(process, 'report', { configurable: true, value: {
       getReport: () => {
         throw new Error('not available');
@@ -80,6 +70,6 @@ describe('IBGatewayManager.isMuslLibc', () => {
     vi.mocked(fs.existsSync).mockImplementation(
       (p: fs.PathLike) => p === '/lib/ld-musl-x86_64.so.1',
     );
-    expect(IBGatewayManager.isMuslLibc()).toBe(true);
+    expect(IBGatewayManager.isMuslLibc('linux')).toBe(true);
   });
 });