quic: add proper error codes & messages for QUIC failures

Signed-off-by: Tim Perry <pimterry@gmail.com>
PR-URL: #63198
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>

Author: pimterry

lib/eslint.config_partial.mjs

@@ -23,7 +23,7 @@ const noRestrictedSyntax = [
     message: "`btoa` supports only latin-1 charset, use Buffer.from(str).toString('base64') instead",
   },
   {
-    selector: 'NewExpression[callee.name=/Error$/]:not([callee.name=/^(AssertionError|NghttpError|AbortError|NodeAggregateError|QuotaExceededError)$/])',
+    selector: 'NewExpression[callee.name=/Error$/]:not([callee.name=/^(AssertionError|NghttpError|AbortError|NodeAggregateError|QuicError|QuotaExceededError)$/])',
     message: "Use an error exported by 'internal/errors' instead.",
   },
   {

lib/internal/errors.js

@@ -1689,14 +1689,12 @@ E('ERR_PERFORMANCE_INVALID_TIMESTAMP',
 E('ERR_PERFORMANCE_MEASURE_INVALID_OPTIONS', '%s', TypeError);
 E('ERR_PROXY_INVALID_CONFIG', '%s', Error);
 E('ERR_PROXY_TUNNEL', '%s', Error);
-E('ERR_QUIC_APPLICATION_ERROR', 'A QUIC application error occurred. %d [%s]', Error);
 E('ERR_QUIC_CONNECTION_FAILED', 'QUIC connection failed', Error);
 E('ERR_QUIC_ENDPOINT_CLOSED', 'QUIC endpoint closed: %s (%d)', Error);
 E('ERR_QUIC_OPEN_STREAM_FAILED', 'Failed to open QUIC stream', Error);
 E('ERR_QUIC_STREAM_ABORTED', '%s', Error);
 E('ERR_QUIC_STREAM_RESET',
   'The QUIC stream was reset by the peer with error code %d', Error);
-E('ERR_QUIC_TRANSPORT_ERROR', 'A QUIC transport error occurred. %d [%s]', Error);
 E('ERR_QUIC_VERSION_NEGOTIATION_ERROR', 'The QUIC session requires version negotiation', Error);
 E('ERR_REQUIRE_ASYNC_MODULE', function(filename, parentFilename) {
   let message = 'require() cannot be used on an ESM ' +

lib/internal/quic/quic.js

@@ -9,6 +9,7 @@ const {
   ArrayPrototypePush,
   BigInt,
   DataViewPrototypeGetByteLength,
+  ErrorCaptureStackTrace,
   FunctionPrototypeBind,
   Number,
   ObjectDefineProperties,
@@ -108,13 +109,11 @@ const {
     ERR_INVALID_THIS,
     ERR_MISSING_ARGS,
     ERR_OUT_OF_RANGE,
-    ERR_QUIC_APPLICATION_ERROR,
     ERR_QUIC_CONNECTION_FAILED,
     ERR_QUIC_ENDPOINT_CLOSED,
     ERR_QUIC_OPEN_STREAM_FAILED,
     ERR_QUIC_STREAM_ABORTED,
     ERR_QUIC_STREAM_RESET,
-    ERR_QUIC_TRANSPORT_ERROR,
     ERR_QUIC_VERSION_NEGOTIATION_ERROR,
   },
 } = require('internal/errors');
@@ -738,10 +737,12 @@ setCallbacks({
    * @param {number} errorType
    * @param {number} code
    * @param {string} [reason]
+   * @param {string} [errorName] Decoded TLS alert name when `code` is a
+   *   CRYPTO_ERROR; otherwise undefined.
    */
-  onSessionClose(errorType, code, reason) {
-    debug('session close callback', errorType, code, reason);
-    this[kOwner][kFinishClose](errorType, code, reason);
+  onSessionClose(errorType, code, reason, errorName) {
+    debug('session close callback', errorType, code, reason, errorName);
+    this[kOwner][kFinishClose](errorType, code, reason, errorName);
   },
 
   /**
@@ -931,8 +932,12 @@ setCallbacks({
       // was an abnormal termination even if the session closed cleanly.
       const resetCode = getQuicStreamState(this[kOwner]).resetCode;
       if (resetCode !== undefined && resetCode > 0n) {
-        error = new ERR_QUIC_APPLICATION_ERROR(
-          resetCode, `stream reset with code ${resetCode}`);
+        error = makeQuicError(
+          'ERR_QUIC_APPLICATION_ERROR',
+          'QUIC application error',
+          'application',
+          resetCode,
+          `stream reset with code ${resetCode}`);
       }
     }
     debug(`stream ${this[kOwner].id} closed callback with error: ${error}`);
@@ -1054,21 +1059,50 @@ class QuicError extends Error {
   }
 }
 
-// Converts a raw QuicError array [type, code, reason] from C++ into a
-// proper Node.js Error object.
+// Build the human-readable message for an ERR_QUIC_TRANSPORT_ERROR or
+// ERR_QUIC_APPLICATION_ERROR. `errorName` is the symbolic name for
+// the wire code when known: either the OpenSSL-decoded TLS alert
+// (CRYPTO_ERROR; 0x100..0x1ff) or one of the named transport codes
+// from RFC 9000 (e.g. PROTOCOL_VIOLATION). Otherwise undefined.
+// `reason` is the peer-supplied UTF-8 reason string from the
+// CONNECTION_CLOSE / RESET_STREAM frame, often empty.
+function quicErrorMessage(prefix, errorCode, reason, errorName) {
+  let msg = `${prefix} `;
+  msg += errorName ? `${errorName} (${errorCode})` : `${errorCode}`;
+  if (reason) msg += `: ${reason}`;
+  return msg;
+}
+
+function makeQuicError(code, prefix, type, errorCode, reason, errorName) {
+  const err = new QuicError(
+    quicErrorMessage(prefix, errorCode, reason, errorName),
+    { errorCode, code, type });
+  ErrorCaptureStackTrace(err, makeQuicError);
+  if (reason) err.reason = reason;
+  if (errorName) err.errorName = errorName;
+  return err;
+}
+
 function convertQuicError(error) {
   const type = error[0];
   const code = error[1];
   const reason = error[2];
+  const errorName = error[3];
   switch (type) {
     case 'transport':
-      return new ERR_QUIC_TRANSPORT_ERROR(code, reason);
+      return makeQuicError('ERR_QUIC_TRANSPORT_ERROR',
+                           'QUIC transport error',
+                           'transport', code, reason, errorName);
     case 'application':
-      return new ERR_QUIC_APPLICATION_ERROR(code, reason);
+      return makeQuicError('ERR_QUIC_APPLICATION_ERROR',
+                           'QUIC application error',
+                           'application', code, reason, errorName);
     case 'version_negotiation':
       return new ERR_QUIC_VERSION_NEGOTIATION_ERROR();
     default:
-      return new ERR_QUIC_TRANSPORT_ERROR(code, reason);
+      return makeQuicError('ERR_QUIC_TRANSPORT_ERROR',
+                           'QUIC transport error',
+                           'transport', code, reason, errorName);
   }
 }
 
@@ -3575,7 +3609,7 @@ class QuicSession {
    * @param {number} code
    * @param {string} [reason]
    */
-  [kFinishClose](errorType, code, reason) {
+  [kFinishClose](errorType, code, reason, errorName) {
     // If code is zero, then we closed without an error. Yay! We can destroy
     // safely without specifying an error.
     if (code === 0n) {
@@ -3584,7 +3618,8 @@ class QuicSession {
       return;
     }
 
-    debug('finishing closing the session with an error', errorType, code, reason);
+    debug('finishing closing the session with an error',
+          errorType, code, reason, errorName);
 
     // If the local side initiated this close with an error code (via
     // close({ code })), this is an intentional shutdown; not an error.
@@ -3611,10 +3646,14 @@ class QuicSession {
     // session would leak with `closed` hanging forever.
     switch (errorType) {
       case 0: /* Transport Error */
-        this.destroy(new ERR_QUIC_TRANSPORT_ERROR(code, reason));
+        this.destroy(makeQuicError('ERR_QUIC_TRANSPORT_ERROR',
+                                   'QUIC transport error',
+                                   'transport', code, reason, errorName));
         break;
       case 1: /* Application Error */
-        this.destroy(new ERR_QUIC_APPLICATION_ERROR(code, reason));
+        this.destroy(makeQuicError('ERR_QUIC_APPLICATION_ERROR',
+                                   'QUIC application error',
+                                   'application', code, reason, errorName));
         break;
       case 2: /* Version Negotiation Error */
         this.destroy(new ERR_QUIC_VERSION_NEGOTIATION_ERROR());
@@ -3623,7 +3662,9 @@ class QuicSession {
         this.destroy();
         break;
       default:
-        this.destroy(new ERR_QUIC_TRANSPORT_ERROR(code, reason));
+        this.destroy(makeQuicError('ERR_QUIC_TRANSPORT_ERROR',
+                                   'QUIC transport error',
+                                   'transport', code, reason, errorName));
         break;
     }
   }
@@ -3874,9 +3915,13 @@ class QuicSession {
     // decide. In 'strict' mode, the handshake already failed at the C++
     // level (SSL_VERIFY_PEER) so we won't reach here.
     if (inner.verifyPeer === 'auto' && validationErrorReason !== undefined) {
-      const err = new ERR_QUIC_TRANSPORT_ERROR(
-        0, `Peer certificate validation failed: ${validationErrorReason}` +
-           ` [${validationErrorCode}]`);
+      const err = makeQuicError(
+        'ERR_QUIC_TRANSPORT_ERROR',
+        'QUIC transport error',
+        'transport',
+        0n,
+        `Peer certificate validation failed: ${validationErrorReason}` +
+          ` [${validationErrorCode}]`);
       inner.pendingOpen.reject?.(err);
       inner.pendingOpen.resolve = undefined;
       inner.pendingOpen.reject = undefined;

src/quic/bindingdata.cc

@@ -435,6 +435,14 @@ QUIC_JS_CALLBACKS(V)
 
 #undef V
 
+Local<String> BindingData::error_name_string(const char* name) {
+  auto& slot = error_name_strings_[name];
+  if (slot.IsEmpty()) {
+    slot.Set(env()->isolate(), OneByteString(env()->isolate(), name));
+  }
+  return slot.Get(env()->isolate());
+}
+
 JS_METHOD_IMPL(BindingData::SetCallbacks) {
   auto env = Environment::GetCurrent(args);
   auto isolate = env->isolate();

src/quic/bindingdata.h

@@ -305,6 +305,8 @@ class BindingData final
 
   std::unordered_map<Endpoint*, BaseObjectPtr<BaseObject>> listening_endpoints;
 
+  v8::Local<v8::String> error_name_string(const char* name);
+
   size_t current_ngtcp2_memory_ = 0;
 
   // The following set up various storage and accessors for common strings,
@@ -357,6 +359,9 @@ class BindingData final
   QUIC_JS_CALLBACKS(V)
 #undef V
 
+  // Lazy cache backing error_name_string()
+  std::unordered_map<const char*, v8::Eternal<v8::String>> error_name_strings_;
+
   std::unique_ptr<SessionManager> session_manager_;
 
   // Type-erased arena storage. The concrete AliasedStructArena<T> types

src/quic/data.cc

@@ -1,13 +1,15 @@
 #if HAVE_OPENSSL && HAVE_QUIC
 #include "guard.h"
 #ifndef OPENSSL_NO_QUIC
-#include "data.h"
 #include <env-inl.h>
 #include <memory_tracker-inl.h>
 #include <ngtcp2/ngtcp2.h>
 #include <node_sockaddr-inl.h>
+#include <openssl/ssl.h>
 #include <string_bytes.h>
 #include <v8.h>
+#include "bindingdata.h"
+#include "data.h"
 #include "defs.h"
 #include "util.h"
 
@@ -363,6 +365,62 @@ std::optional<int> QuicError::get_crypto_error() const {
   return code() & ~NGTCP2_CRYPTO_ERROR;
 }
 
+const char* QuicError::name() const {
+  // CRYPTO_ERROR carries a TLS alert in its low byte (RFC 9001 sec. 4.8).
+  // OpenSSL's SSL_alert_desc_string_long owns a stable string for every
+  // alert it knows about; we filter out the "unknown" placeholder so the
+  // JS side can present `errorName` as undefined for unrecognised alerts.
+  if (auto alert = get_crypto_error()) {
+    const char* n = SSL_alert_desc_string_long(*alert);
+    if (n != nullptr && std::string_view(n) != "unknown") return n;
+    return nullptr;
+  }
+  // Named transport-layer error codes from RFC 9000 sec. 20.1 (and the
+  // RFC 9368 version-negotiation extension). Application error codes are
+  // opaque to QUIC, so we only decode for transport.
+  if (type() != Type::TRANSPORT) return nullptr;
+  switch (code()) {
+    case NGTCP2_NO_ERROR:
+      return "NO_ERROR";
+    case NGTCP2_INTERNAL_ERROR:
+      return "INTERNAL_ERROR";
+    case NGTCP2_CONNECTION_REFUSED:
+      return "CONNECTION_REFUSED";
+    case NGTCP2_FLOW_CONTROL_ERROR:
+      return "FLOW_CONTROL_ERROR";
+    case NGTCP2_STREAM_LIMIT_ERROR:
+      return "STREAM_LIMIT_ERROR";
+    case NGTCP2_STREAM_STATE_ERROR:
+      return "STREAM_STATE_ERROR";
+    case NGTCP2_FINAL_SIZE_ERROR:
+      return "FINAL_SIZE_ERROR";
+    case NGTCP2_FRAME_ENCODING_ERROR:
+      return "FRAME_ENCODING_ERROR";
+    case NGTCP2_TRANSPORT_PARAMETER_ERROR:
+      return "TRANSPORT_PARAMETER_ERROR";
+    case NGTCP2_CONNECTION_ID_LIMIT_ERROR:
+      return "CONNECTION_ID_LIMIT_ERROR";
+    case NGTCP2_PROTOCOL_VIOLATION:
+      return "PROTOCOL_VIOLATION";
+    case NGTCP2_INVALID_TOKEN:
+      return "INVALID_TOKEN";
+    case NGTCP2_APPLICATION_ERROR:
+      return "APPLICATION_ERROR";
+    case NGTCP2_CRYPTO_BUFFER_EXCEEDED:
+      return "CRYPTO_BUFFER_EXCEEDED";
+    case NGTCP2_KEY_UPDATE_ERROR:
+      return "KEY_UPDATE_ERROR";
+    case NGTCP2_AEAD_LIMIT_REACHED:
+      return "AEAD_LIMIT_REACHED";
+    case NGTCP2_NO_VIABLE_PATH:
+      return "NO_VIABLE_PATH";
+    case NGTCP2_VERSION_NEGOTIATION_ERROR:
+      return "VERSION_NEGOTIATION_ERROR";
+    default:
+      return nullptr;
+  }
+}
+
 MaybeLocal<Value> QuicError::ToV8Value(Environment* env) const {
   if ((type() == Type::TRANSPORT && code() == NGTCP2_NO_ERROR) ||
       (type() == Type::APPLICATION &&
@@ -384,6 +442,7 @@ MaybeLocal<Value> QuicError::ToV8Value(Environment* env) const {
       type_str,
       BigInt::NewFromUnsigned(env->isolate(), code()),
       Undefined(env->isolate()),
+      Undefined(env->isolate()),
   };
 
   // Note that per the QUIC specification, the reason, if present, is
@@ -397,6 +456,13 @@ MaybeLocal<Value> QuicError::ToV8Value(Environment* env) const {
     return {};
   }
 
+  // Attach a human-readable name for known wire codes (RFC 9000 sec. 20.1
+  // names and OpenSSL TLS alert descriptions for CRYPTO_ERROR). Unknown
+  // codes leave the slot as undefined.
+  if (const char* n = name()) {
+    argv[3] = BindingData::Get(env).error_name_string(n);
+  }
+
   return Array::New(env->isolate(), argv, arraysize(argv)).As<Value>();
 }
 

src/quic/data.h

@@ -265,6 +265,9 @@ class QuicError final : public MemoryRetainer {
   bool is_crypto_error() const;
   std::optional<int> get_crypto_error() const;
 
+  // Returns a human-readable name for this error if known, or nullptr
+  const char* name() const;
+
   // Note that since application errors are application-specific and we
   // don't know which application is being used here, it is possible that
   // the comparing two different QuicError instances from different applications

src/quic/session.cc

@@ -3065,7 +3065,7 @@ void Session::CheckStreamIdleTimeout(uint64_t now) {
       // Without this, the peer's stream sits orphaned until the
       // session closes.
       auto error =
-          QuicError::ForTransport(NGTCP2_ERR_PROTO, "stream idle timeout");
+          QuicError::ForNgtcp2Error(NGTCP2_ERR_PROTO, "stream idle timeout");
       ShutdownStream(id, error);
       stream->Destroy(error);
       STAT_INCREMENT(Stats, streams_idle_timed_out);
@@ -3451,12 +3451,21 @@ void Session::EmitClose(const QuicError& error) {
       Integer::New(env()->isolate(), static_cast<int>(error.type())),
       BigInt::NewFromUnsigned(env()->isolate(), error.code()),
       Undefined(env()->isolate()),
+      Undefined(env()->isolate()),
   };
   if (error.reason().length() > 0 &&
       !ToV8Value(env()->context(), error.reason()).ToLocal(&argv[2])) {
     return;
   }
 
+  // Attach a human-readable name for known wire codes (RFC 9000 sec. 20.1
+  // names and OpenSSL TLS alert descriptions for CRYPTO_ERROR). Unknown
+  // codes leave the slot as undefined. See QuicError::name() for the
+  // matching path on stream-level errors.
+  if (const char* n = error.name()) {
+    argv[3] = BindingData::Get(env()).error_name_string(n);
+  }
+
   MakeCallback(
       BindingData::Get(env()).session_close_callback(), arraysize(argv), argv);