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){
 letmessage='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.
 constresetCode=getQuicStreamState(this[kOwner]).resetCode;
 if(resetCode!==undefined&&resetCode>0n){
-error=newERR_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.
+functionquicErrorMessage(prefix,errorCode,reason,errorName){
+letmsg=`${prefix} `;
+msg+=errorName ? `${errorName} (${errorCode})` : `${errorCode}`;
+if(reason)msg+=`: ${reason}`;
+returnmsg;
+}
+
+functionmakeQuicError(code,prefix,type,errorCode,reason,errorName){
+consterr=newQuicError(
+quicErrorMessage(prefix,errorCode,reason,errorName),
+{ errorCode, code, type });
+ErrorCaptureStackTrace(err,makeQuicError);
+if(reason)err.reason=reason;
+if(errorName)err.errorName=errorName;
+returnerr;
+}
+
 functionconvertQuicError(error){
 consttype=error[0];
 constcode=error[1];
 constreason=error[2];
+consterrorName=error[3];
 switch(type){
 case'transport':
-returnnewERR_QUIC_TRANSPORT_ERROR(code,reason);
+returnmakeQuicError('ERR_QUIC_TRANSPORT_ERROR',
+'QUIC transport error',
+'transport',code,reason,errorName);
 case'application':
-returnnewERR_QUIC_APPLICATION_ERROR(code,reason);
+returnmakeQuicError('ERR_QUIC_APPLICATION_ERROR',
+'QUIC application error',
+'application',code,reason,errorName);
 case'version_negotiation':
 returnnewERR_QUIC_VERSION_NEGOTIATION_ERROR();
 default:
-returnnewERR_QUIC_TRANSPORT_ERROR(code,reason);
+returnmakeQuicError('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){
 case0: /* Transport Error */
-this.destroy(newERR_QUIC_TRANSPORT_ERROR(code,reason));
+this.destroy(makeQuicError('ERR_QUIC_TRANSPORT_ERROR',
+'QUIC transport error',
+'transport',code,reason,errorName));
 break;
 case1: /* Application Error */
-this.destroy(newERR_QUIC_APPLICATION_ERROR(code,reason));
+this.destroy(makeQuicError('ERR_QUIC_APPLICATION_ERROR',
+'QUIC application error',
+'application',code,reason,errorName));
 break;
 case2: /* Version Negotiation Error */
 this.destroy(newERR_QUIC_VERSION_NEGOTIATION_ERROR());
@@ -3623,7 +3662,9 @@ class QuicSession {
 this.destroy();
 break;
 default:
-this.destroy(newERR_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){
-consterr=newERR_QUIC_TRANSPORT_ERROR(
-0,`Peer certificate validation failed: ${validationErrorReason}`+
-` [${validationErrorCode}]`);
+consterr=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(constchar* 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(constchar* 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<constchar*, 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 {
 returncode() & ~NGTCP2_CRYPTO_ERROR;
 }
 
+constchar* 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()) {
+constchar* n = SSL_alert_desc_string_long(*alert);
+if (n != nullptr && std::string_view(n) != "unknown") return n;
+returnnullptr;
+ }
+// 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) returnnullptr;
+switch (code()) {
+caseNGTCP2_NO_ERROR:
+return"NO_ERROR";
+caseNGTCP2_INTERNAL_ERROR:
+return"INTERNAL_ERROR";
+caseNGTCP2_CONNECTION_REFUSED:
+return"CONNECTION_REFUSED";
+caseNGTCP2_FLOW_CONTROL_ERROR:
+return"FLOW_CONTROL_ERROR";
+caseNGTCP2_STREAM_LIMIT_ERROR:
+return"STREAM_LIMIT_ERROR";
+caseNGTCP2_STREAM_STATE_ERROR:
+return"STREAM_STATE_ERROR";
+caseNGTCP2_FINAL_SIZE_ERROR:
+return"FINAL_SIZE_ERROR";
+caseNGTCP2_FRAME_ENCODING_ERROR:
+return"FRAME_ENCODING_ERROR";
+caseNGTCP2_TRANSPORT_PARAMETER_ERROR:
+return"TRANSPORT_PARAMETER_ERROR";
+caseNGTCP2_CONNECTION_ID_LIMIT_ERROR:
+return"CONNECTION_ID_LIMIT_ERROR";
+caseNGTCP2_PROTOCOL_VIOLATION:
+return"PROTOCOL_VIOLATION";
+caseNGTCP2_INVALID_TOKEN:
+return"INVALID_TOKEN";
+caseNGTCP2_APPLICATION_ERROR:
+return"APPLICATION_ERROR";
+caseNGTCP2_CRYPTO_BUFFER_EXCEEDED:
+return"CRYPTO_BUFFER_EXCEEDED";
+caseNGTCP2_KEY_UPDATE_ERROR:
+return"KEY_UPDATE_ERROR";
+caseNGTCP2_AEAD_LIMIT_REACHED:
+return"AEAD_LIMIT_REACHED";
+caseNGTCP2_NO_VIABLE_PATH:
+return"NO_VIABLE_PATH";
+caseNGTCP2_VERSION_NEGOTIATION_ERROR:
+return"VERSION_NEGOTIATION_ERROR";
+default:
+returnnullptr;
+ }
+}
+
 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 (constchar* n = name()) {
+ argv[3] = BindingData::Get(env).error_name_string(n);
+ }
+
 returnArray::New(env->isolate(), argv, arraysize(argv)).As<Value>();
 }
 

src/quic/data.h

@@ -265,6 +265,9 @@ class QuicError final : public MemoryRetainer {
 boolis_crypto_error() const;
  std::optional<int> get_crypto_error() const;
 
+// Returns a human-readable name for this error if known, or nullptr
+constchar* 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 (constchar* n = error.name()) {
+ argv[3] = BindingData::Get(env()).error_name_string(n);
+ }
+
 MakeCallback(
 BindingData::Get(env()).session_close_callback(), arraysize(argv), argv);