fix(emulator): reject TCP start() Promise on port binding errors (#277)

Fixes TCP transport start() method to properly reject the Promise when port binding fails or initialization hangs. Previously, errors were only logged to console, causing applications to hang indefinitely on port conflicts.

Changes:
- Added reject parameter to Promise constructor in start() method
- Error events during initialization now reject the Promise instead of just logging
- Added 10-second timeout to prevent hanging when server never emits events
- Errors after successful initialization continue to be logged (existing behavior)
- Added type cast for error event to satisfy TypeScript compiler
- Comprehensive test coverage for port binding errors and timeout scenarios

Root cause: Promise constructor only had resolve parameter, no reject. When modbus-serial ServerTCP emitted error events during initialization, they were logged but never propagated to the caller, leaving the Promise pending forever.

Testing:
- New test: Port binding error rejection (EADDRINUSE scenario)
- New test: Initialization timeout (hanging server scenario)
- All 1607 existing tests pass
- Preserves existing error handling behavior for post-initialization errors

Follow-up issues:
- #274 (HIGH): Event listener cleanup on initialization failure
- #275 (HIGH): Race condition when calling stop() during initialization
- #276 (MEDIUM): Error messages should include host/port context

Closes #254

Author: groupsky

packages/emulator/src/transports/tcp.test.ts

@@ -178,6 +178,77 @@ describe('TcpTransport', () => {
   })
 
   describe('error handling', () => {
+    it('should reject start() on port binding error', async () => {
+      // Test for issue #254: start() should reject when port binding fails
+      const { ServerTCP } = await import('modbus-serial')
+      const bindError = new Error('listen EADDRINUSE: address already in use')
+      let errorCallback: ((err: Error) => void) | undefined
+      ;(ServerTCP as any).mockImplementationOnce((vector: any, _options: any) => {
+        capturedServiceVector = vector
+        initializedListener = undefined
+        errorListener = undefined
+
+        const localMockInstance = {
+          close: jest.fn((cb: (err: Error | null) => void) => cb(null)),
+          on: jest.fn((event: string, listener: any) => {
+            if (event === 'initialized') {
+              initializedListener = listener
+            } else if (event === 'error') {
+              errorListener = listener
+              errorCallback = listener
+            }
+          }),
+          removeAllListeners: jest.fn(),
+          socks: new Map(),
+        }
+
+        // Simulate error during initialization (instead of initialized event)
+        setImmediate(() => {
+          if (errorCallback) {
+            errorCallback(bindError)
+          }
+        })
+
+        return localMockInstance
+      })
+
+      const testTransport = new TcpTransport({ host: 'localhost', port: 8502 })
+      await expect(testTransport.start()).rejects.toThrow(
+        'listen EADDRINUSE: address already in use'
+      )
+    })
+
+    it('should reject start() on initialization timeout', async () => {
+      // Test for issue #254: start() should timeout if server never emits initialized or error
+      const { ServerTCP } = await import('modbus-serial')
+
+      ;(ServerTCP as any).mockImplementationOnce((vector: any, _options: any) => {
+        capturedServiceVector = vector
+        initializedListener = undefined
+        errorListener = undefined
+
+        const localMockInstance = {
+          close: jest.fn((cb: (err: Error | null) => void) => cb(null)),
+          on: jest.fn((event: string, listener: any) => {
+            if (event === 'initialized') {
+              initializedListener = listener
+            } else if (event === 'error') {
+              errorListener = listener
+            }
+          }),
+          removeAllListeners: jest.fn(),
+          socks: new Map(),
+        }
+
+        // Don't emit initialized or error - simulate hanging server
+
+        return localMockInstance
+      })
+
+      const testTransport = new TcpTransport({ host: 'localhost', port: 8502 })
+      await expect(testTransport.start()).rejects.toThrow(/timeout/i)
+    }, 15000) // Increase test timeout to allow for implementation timeout
+
     it('should reject on stop error', async () => {
       const { ServerTCP } = await import('modbus-serial')
       const closeError = new Error('Failed to close server')

packages/emulator/src/transports/tcp.ts

@@ -83,17 +83,34 @@ export class TcpTransport extends BaseTransport {
     const server = new ServerTCP(serviceVector, options)
     this.server = server
 
-    // Wait for initialized event
-    return new Promise<void>((resolve) => {
+    // Wait for initialized event with timeout
+    return new Promise<void>((resolve, reject) => {
+      let isInitializing = true
+
+      const timeout = setTimeout(() => {
+        isInitializing = false
+        delete this.server
+        reject(new Error('TCP server initialization timeout after 10s'))
+      }, 10000)
+
       server.on('initialized', () => {
+        clearTimeout(timeout)
+        isInitializing = false
         this.started = true
         resolve()
       })
 
-      // Handle errors
-      server.on('error', (err) => {
-        // Log error but don't stop server
-        console.error('TCP transport error:', err)
+      // Handle errors - cast to EventEmitter as modbus-serial types don't include 'error' event
+      ;(server as unknown as EventEmitter).on('error', (err: Error) => {
+        if (isInitializing) {
+          clearTimeout(timeout)
+          isInitializing = false
+          delete this.server
+          reject(err)
+        } else {
+          // Log errors that occur after initialization
+          console.error('TCP transport error:', err)
+        }
       })
     })
   }