quic: add proper error codes & messages for QUIC failures

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);