net: tie listen() signal to server lifetime, async-iterable Server

Address review feedback on the net/promises API:

- `listen()` now passes its `signal` through to `server.listen()` so the
  signal aborts the server for its entire lifetime rather than only the
  pending listen. Aborting before the server is listening rejects the
  returned promise; aborting afterwards closes the server, matching
  net.Server's own `signal` behavior.
- `net.Server` is now async iterable: `for await (const socket of server)`
  yields each incoming connection as an alternative to the 'connection'
  event, mirroring readline.Interface.

Also update test-repl-tab-complete-require and test-repl-tab-complete-import
to account for the new `net/promises` builtin appearing in completions.

Refs: #21482
Assisted-by: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Ethan Arrowood <ethan@arrowood.dev>

Author: Ethan-Arrowood

doc/api/net.md

@@ -452,6 +452,35 @@ changes:
 Calls [`server.close()`][] and returns a promise that fulfills when the
 server has closed.
 
+### `server[Symbol.asyncIterator]()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* Returns: {AsyncIterator} An async iterator that yields each incoming
+  [`net.Socket`][].
+
+Returns an async iterator over the server's incoming connections, allowing them
+to be consumed with `for await...of` as an alternative to the [`'connection'`][]
+event. Iteration ends when the server emits [`'close'`][], and rejects if the
+server emits [`'error'`][].
+
+```mjs
+import { createServer } from 'node:net';
+
+const server = createServer().listen(8124);
+for await (const socket of server) {
+  socket.end('hello world!');
+}
+```
+
+Connections are buffered while the loop body is busy; the server does not stop
+accepting them, so a consumer that is slower than the connection rate can buffer
+without bound. Use [`server.maxConnections`][] to bound concurrency.
+
 ### `server.getConnections(callback)`
 
 <!-- YAML
@@ -2297,19 +2326,26 @@ added: REPLACEME
   * `connectionListener` {Function} Automatically set as a listener for the
     [`'connection'`][] event.
   * `signal` {AbortSignal} An `AbortSignal` that may be used to abort the
-    listening server.
+    server. Aborting before the server is listening rejects the returned
+    promise with an `AbortError`; aborting at any later point closes the
+    server, matching the `signal` option of [`server.listen()`][].
 * Returns: {Promise} Fulfills with a listening [`net.Server`][].
 
 Creates a [`net.Server`][] and begins listening. The returned promise is
 fulfilled with the server once its [`'listening'`][] event fires, and is
-rejected if the server fails to bind or the `signal` is aborted. When the
-promise rejects, the server is closed.
+rejected if the server fails to bind or the `signal` is aborted before it is
+listening. When the promise rejects, the server is closed.
+
+The resolved server is async iterable, so incoming connections can be consumed
+with `for await...of` (see `server[Symbol.asyncIterator]()`).
 
 ```mjs
 import { listen } from 'node:net/promises';
 
 const server = await listen({ port: 8124 });
-console.log('server bound to', server.address().port);
+for await (const socket of server) {
+  socket.end('hello world!');
+}
 ```
 
 [IPC]: #ipc-support

lib/internal/net/promises.js

@@ -55,16 +55,21 @@ async function listen(options = kEmptyObject) {
   }
 
   const lazy = lazyNet();
-  // Strip the signal so listen() does not install its own close-on-abort
-  // handler; rejecting and closing below tears the server down.
-  const serverOptions = { ...options, signal: undefined };
-  const server = lazy.createServer(serverOptions, connectionListener);
+  const server = lazy.createServer(options, connectionListener);
 
   try {
-    server.listen(serverOptions);
+    // Pass `signal` through to listen() so net installs its own
+    // close-on-abort handler: the signal aborts the server for its entire
+    // lifetime, not just the pending listen.
+    server.listen(options);
     await once(server, 'listening', signal !== undefined ? { signal } : kEmptyObject);
   } catch (err) {
-    server.close();
+    // On abort, net's signal handler already closes the server, so closing
+    // again would be redundant; on other failures (e.g. a bind error) there
+    // is no such handler, so close it here.
+    if (!signal?.aborted) {
+      server.close();
+    }
     throw err;
   }
   return server;

lib/net.js

@@ -37,6 +37,7 @@ const {
   ObjectSetPrototypeOf,
   Symbol,
   SymbolAsyncDispose,
+  SymbolAsyncIterator,
   SymbolDispose,
 } = primordials;
 
@@ -158,6 +159,7 @@ let dns;
 let BlockList;
 let SocketAddress;
 let netPromises;
+let kFirstEventParam;
 let autoSelectFamilyDefault = getOptionValue('--network-family-autoselection');
 let autoSelectFamilyAttemptTimeoutDefault = getOptionValue('--network-family-autoselection-attempt-timeout');
 
@@ -2763,6 +2765,14 @@ Server.prototype[SymbolAsyncDispose] = async function() {
   await FunctionPrototypeCall(promisify(this.close), this);
 };
 
+Server.prototype[SymbolAsyncIterator] = function() {
+  kFirstEventParam ??= require('internal/events/symbols').kFirstEventParam;
+  return EventEmitter.on(this, 'connection', {
+    close: ['close'],
+    [kFirstEventParam]: true,
+  });
+};
+
 Server.prototype._emitCloseIfDrained = function() {
   debug('SERVER _emitCloseIfDrained');
 

test/parallel/test-net-promises-listen.js

@@ -2,6 +2,7 @@
 const common = require('../common');
 const assert = require('assert');
 const net = require('net');
+const { once } = require('events');
 const { listen } = require('net/promises');
 
 (async () => {
@@ -13,6 +14,18 @@ const { listen } = require('net/promises');
     server.close();
   }
 
+  // The signal aborts the server for its entire lifetime, not just the
+  // pending listen: aborting after it is listening closes the server.
+  {
+    const controller = new AbortController();
+    const server = await listen({ port: 0, signal: controller.signal });
+    assert.strictEqual(server.listening, true);
+    const closed = once(server, 'close');
+    controller.abort();
+    await closed;
+    assert.strictEqual(server.listening, false);
+  }
+
   // The connectionListener option receives incoming connections.
   {
     const server = await listen({

test/parallel/test-net-server-async-iterator.js

@@ -0,0 +1,50 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+const net = require('net');
+const { once } = require('events');
+
+(async () => {
+  // `for await...of` yields each incoming connection as a net.Socket.
+  {
+    const server = net.createServer().listen(0);
+    await once(server, 'listening');
+    const { port } = server.address();
+
+    const total = 3;
+    const clients = [];
+    for (let i = 0; i < total; i++) {
+      clients.push(net.connect(port));
+    }
+
+    let count = 0;
+    for await (const socket of server) {
+      assert.ok(socket instanceof net.Socket);
+      socket.end();
+      if (++count === total) break;
+    }
+    assert.strictEqual(count, total);
+
+    // Breaking out of the loop stops iterating but does not close the server.
+    assert.strictEqual(server.listening, true);
+
+    server.close();
+    for (const client of clients) {
+      client.destroy();
+    }
+  }
+
+  // Iteration ends cleanly when the server closes.
+  {
+    const server = net.createServer().listen(0);
+    await once(server, 'listening');
+    process.nextTick(() => server.close());
+
+    let count = 0;
+    for await (const socket of server) {
+      count++;
+      socket.end();
+    }
+    assert.strictEqual(count, 0);
+  }
+})().then(common.mustCall());

test/parallel/test-repl-tab-complete-import.js

@@ -52,11 +52,12 @@ replServer.complete("import\t( 'n", common.mustSucceed((data) => {
     assert.notStrictEqual(lastIndex, -1);
   });
   assert.strictEqual(completions[lastIndex + 1], '');
-  // There is only one Node.js module that starts with n:
+  // The Node.js modules that start with n:
   assert.strictEqual(completions[lastIndex + 2], 'net');
-  assert.strictEqual(completions[lastIndex + 3], '');
+  assert.strictEqual(completions[lastIndex + 3], 'net/promises');
+  assert.strictEqual(completions[lastIndex + 4], '');
   // It's possible to pick up non-core modules too
-  for (const completion of completions.slice(lastIndex + 4)) {
+  for (const completion of completions.slice(lastIndex + 5)) {
     assert.match(completion, /^n/);
   }
 }));

test/parallel/test-repl-tab-complete-require.js

@@ -67,11 +67,12 @@ const { startNewREPLServer } = require('../common/repl');
         assert.notStrictEqual(lastIndex, -1);
       }
       assert.strictEqual(data[0][lastIndex + 1], '');
-      // There is only one Node.js module that starts with n:
+      // The Node.js modules that start with n:
       assert.strictEqual(data[0][lastIndex + 2], 'net');
-      assert.strictEqual(data[0][lastIndex + 3], '');
+      assert.strictEqual(data[0][lastIndex + 3], 'net/promises');
+      assert.strictEqual(data[0][lastIndex + 4], '');
       // It's possible to pick up non-core modules too
-      for (const completion of data[0].slice(lastIndex + 4)) {
+      for (const completion of data[0].slice(lastIndex + 5)) {
         assert.match(completion, /^n/);
       }
     })