quic: refactor/improve/document QuicSocket listening event

PR-URL: #34247
Reviewed-By: Anna Henningsen <anna@addaleax.net>

Author: jasnell

doc/api/quic.md

@@ -1371,6 +1371,17 @@ Emitted before the `'close'` event if the `QuicSocket` was destroyed with an
 
 The `'error'` event will not be emitted multiple times.
 
+#### Event: `'listening'`
+<!-- YAML
+added: REPLACEME
+-->
+
+Emitted after `quicsocket.listen()` is called and the `QuicSocket` has started
+listening for incoming `QuicServerSession`s.  The callback is invoked with
+no arguments.
+
+The `'listening'` event will not be emitted multiple times.
+
 #### Event: `'ready'`
 <!-- YAML
 added: REPLACEME

lib/internal/quic/core.js

@@ -1166,7 +1166,13 @@ class QuicSocket extends EventEmitter {
       port,
       state.alpn,
       options);
-    process.nextTick(emit.bind(this, 'listening'));
+    process.nextTick(() => {
+      try {
+        this.emit('listening');
+      } catch (error) {
+        this.destroy(error);
+      }
+    });
   }
 
   // When the QuicSocket listen() function is called, the first step is to bind

test/parallel/test-quic-server-listening-event-error-async.js

@@ -0,0 +1,33 @@
+// Flags: --no-warnings
+'use strict';
+
+const common = require('../common');
+if (!common.hasQuic)
+  common.skip('missing quic');
+
+const assert = require('assert');
+const {
+  key,
+  cert,
+  ca,
+} = require('../common/quic');
+
+const { createQuicSocket } = require('net');
+
+const options = { key, cert, ca, alpn: 'zzz' };
+
+const server = createQuicSocket({ server: options });
+
+server.on('session', common.mustNotCall());
+
+server.listen();
+
+server.on('error', common.mustCall((error) => {
+  assert.strictEqual(error.message, 'boom');
+}));
+
+server.on('ready', common.mustCall());
+
+server.on('listening', common.mustCall(async () => {
+  throw new Error('boom');
+}));

test/parallel/test-quic-server-listening-event-error.js

@@ -0,0 +1,33 @@
+// Flags: --no-warnings
+'use strict';
+
+const common = require('../common');
+if (!common.hasQuic)
+  common.skip('missing quic');
+
+const assert = require('assert');
+const {
+  key,
+  cert,
+  ca,
+} = require('../common/quic');
+
+const { createQuicSocket } = require('net');
+
+const options = { key, cert, ca, alpn: 'zzz' };
+
+const server = createQuicSocket({ server: options });
+
+server.on('session', common.mustNotCall());
+
+server.listen();
+
+server.on('error', common.mustCall((error) => {
+  assert.strictEqual(error.message, 'boom');
+}));
+
+server.on('ready', common.mustCall());
+
+server.on('listening', common.mustCall(() => {
+  throw new Error('boom');
+}));