quic 0.0.1 → 0.0.2

data/ext/quic/connection_client.c

@@ -6,30 +6,89 @@
 #include <sys/socket.h>
 #include <time.h>
 
+#include <openssl/err.h>
 #include <openssl/rand.h>
 
 /* Buffer size for #write_pkt. NGTCP2_MAX_UDP_PAYLOAD_SIZE (1200) is the
    minimum destlen ngtcp2 accepts. Revisit when PMTUD is enabled (Phase 4+). */
 #define QUIC_WRITE_PKT_BUFLEN NGTCP2_MAX_UDP_PAYLOAD_SIZE
 
-static int quic_crypto_initialized = 0;
+/* picotls sends a key share only for the first entry; the others are offered
+   in supported_groups and reached via HelloRetryRequest. X25519 is first so
+   the common case stays 1-RTT. */
+static ptls_key_exchange_algorithm_t *quic_key_exchanges[] = {
+  &ptls_openssl_x25519,
+  &ptls_openssl_secp256r1,
+#if PTLS_OPENSSL_HAVE_SECP384R1
+  &ptls_openssl_secp384r1,
+#endif
+  NULL,
+};
+
+static ptls_cipher_suite_t *quic_cipher_suites[] = {
+  &ptls_openssl_aes128gcmsha256,
+  &ptls_openssl_aes256gcmsha384,
+#if PTLS_OPENSSL_HAVE_CHACHA20_POLY1305
+  &ptls_openssl_chacha20poly1305sha256,
+#endif
+  NULL,
+};
+
+/* The system default store is loaded once per process: reading the CA bundle
+   takes several milliseconds. X509_STORE is reference counted and safe to
+   share across verifications; creation runs under the GVL. Never freed. */
+static X509_STORE *quic_default_store;
+
+static X509_STORE *
+quic_get_default_store(void)
+{
+  if (quic_default_store == NULL) {
+    X509_STORE *store = X509_STORE_new();
+    if (store == NULL || X509_STORE_set_default_paths(store) != 1) {
+      X509_STORE_free(store);
+      rb_raise(rb_eRuntimeError, "failed to load the default certificate store");
+    }
+    quic_default_store = store;
+  }
+  return quic_default_store;
+}
 
 typedef struct {
   ngtcp2_conn *conn;
-  SSL_CTX *ssl_ctx;
-  SSL *ssl;
+  /* Referenced by cptls.ptls, which only keeps the pointer, so this has to
+     outlive the ptls_t. */
+  ptls_context_t tls_ctx;
+  /* Referenced by tls_ctx.verify_certificate when verify_mode is :peer. Holds
+     a reference to an X509_STORE, released in quic_client_free. */
+  ptls_openssl_verify_certificate_t verify_cert;
+  bool verify_cert_initialized;
+  /* Filled by quic_override_verify_cb during the handshake so that a failed
+     read_pkt can raise CertificateVerifyFailed with the X509 error. */
+  bool verify_failed;
+  int verify_result;  /* X509_V_ERR_*, 0 when the server sent no certificate */
+  /* The TLS native handle handed to ngtcp2 (&cptls, not cptls.ptls). */
+  ngtcp2_crypto_picotls_ctx cptls;
+  /* [0]: QUIC transport params, filled in by ngtcp2; [1]: terminator. */
+  ptls_raw_extension_t tls_exts[2];
+  /* ALPN list handed to picotls, which keeps the pointers for the whole
+     handshake (unlike SSL_set_alpn_protos, which copies). The entries point
+     into alpn_buf, and both are owned by this struct. */
+  ptls_iovec_t *alpn;
+  size_t alpn_count;
+  uint8_t *alpn_buf;
   ngtcp2_cid scid;
   ngtcp2_cid dcid;
   /* ngtcp2 1.x requires applications to associate an ngtcp2_conn with the
-     TLS object via SSL_set_app_data so that crypto callbacks (e.g.
-     add_handshake_data) can recover the conn. The ref must outlive ssl. */
+     TLS object so that crypto callbacks (e.g. add_handshake_data) can recover
+     the conn. picotls carries it in the ptls_t's data pointer, set via
+     ptls_get_data_ptr. The ref must outlive the ptls_t. */
   ngtcp2_crypto_conn_ref conn_ref;
-  /* Back-reference to the Quic::Connection::Client Ruby object that owns
+  /* Back-reference to the QUIC::Connection::Client Ruby object that owns
      this struct. ngtcp2 stream callbacks receive a void* user_data equal
      to this struct, and they look up @streams via owner. We are stored
      INSIDE owner via TypedData_Wrap_Struct, so owner is guaranteed alive
-     while we exist (no dmark needed). GC.compact may relocate owner and
-     leave this field stale; a dcompact slot is a Phase 5 follow-up. */
+     while we exist (no dmark needed). GC.compact may relocate owner, so
+     quic_client_compact updates this field via rb_gc_location. */
   VALUE owner;
 } quic_client_t;
 
@@ -38,8 +97,15 @@ quic_client_free(void *ptr)
 {
   quic_client_t *c = (quic_client_t *)ptr;
   if (c->conn) ngtcp2_conn_del(c->conn);
-  if (c->ssl) SSL_free(c->ssl);
-  if (c->ssl_ctx) SSL_CTX_free(c->ssl_ctx);
+  if (c->cptls.ptls) {
+    /* Safe even when configure_client_session never ran or failed midway. */
+    ngtcp2_crypto_picotls_deconfigure_session(&c->cptls);
+    ptls_free(c->cptls.ptls);
+  }
+  /* After ptls_free: the ptls_t references verify_cert through tls_ctx. */
+  if (c->verify_cert_initialized) ptls_openssl_dispose_verify_certificate(&c->verify_cert);
+  xfree(c->alpn);
+  xfree(c->alpn_buf);
   xfree(c);
 }
 
@@ -50,9 +116,20 @@ quic_client_size(const void *ptr)
   return sizeof(quic_client_t);
 }
 
+/* GC.compact may relocate the owner Client object. Follow it so the
+   void* user_data ngtcp2 callbacks receive (which equals this struct,
+   stored inside owner) keeps resolving @streams / @accept_queue. The
+   raw ngtcp2/picotls pointers are outside Ruby's heap and are left alone. */
+static void
+quic_client_compact(void *ptr)
+{
+  quic_client_t *c = (quic_client_t *)ptr;
+  c->owner = rb_gc_location(c->owner);
+}
+
 static const rb_data_type_t quic_client_data_type = {
-  "Quic::Connection::Client",
-  {NULL, quic_client_free, quic_client_size,},
+  "QUIC::Connection::Client",
+  {NULL, quic_client_free, quic_client_size, quic_client_compact,},
   NULL, NULL,
   RUBY_TYPED_FREE_IMMEDIATELY,
 };
@@ -177,7 +254,7 @@ quic_fill_settings(ngtcp2_settings *settings, VALUE st)
   settings->no_pmtud = RTEST(no_pmtud) ? 1 : 0;
 }
 
-/* Shared helper: look up the Quic::Stream registered for stream_id in the
+/* Shared helper: look up the QUIC::Stream registered for stream_id in the
    owner Client's @streams Hash. Returns Qnil if not found (which can happen
    if the stream was already removed by a previous stream_close callback). */
 static VALUE
@@ -221,6 +298,15 @@ quic_recv_stream_data_cb(ngtcp2_conn *conn, uint32_t flags, int64_t stream_id,
   quic_stream_t *s;
   TypedData_Get_Struct(stream, quic_stream_t, &quic_stream_data_type, s);
 
+  /* Surface peer-initiated (server) streams to #accept_stream. For a client
+     connection the low stream-id bit marks the initiator: 1 == server. Push
+     once, on first data arrival, then mark so later data does not re-enqueue. */
+  if (!s->accept_queued && (stream_id & 0x01)) {
+    VALUE accept_queue = rb_ivar_get(c->owner, rb_intern("@accept_queue"));
+    rb_ary_push(accept_queue, stream);
+    s->accept_queued = true;
+  }
+
   if (datalen > 0) {
     VALUE recv_buffer = rb_ivar_get(stream, rb_intern("@recv_buffer"));
     rb_str_buf_cat(recv_buffer, (const char *)data, (long)datalen);
@@ -308,6 +394,117 @@ quic_stream_reset_cb(ngtcp2_conn *conn, int64_t stream_id, uint64_t final_size,
   return 0;
 }
 
+/* Record the X509 verification result so read_pkt can raise a descriptive
+   error. The verdict itself is left to picotls: ret is returned unchanged.
+   Runs synchronously inside read_pkt with the GVL held; it only writes to the
+   struct and never touches Ruby objects. */
+static int
+quic_override_verify_cb(ptls_openssl_override_verify_certificate_t *self,
+                        ptls_t *tls, int ret, int ossl_ret, X509 *cert,
+                        STACK_OF(X509) *chain)
+{
+  (void)self;
+  (void)cert;
+  (void)chain;
+  ngtcp2_crypto_conn_ref *ref = *ptls_get_data_ptr(tls);
+  quic_client_t *c = (quic_client_t *)ref->user_data;
+  if (ret != 0) {
+    c->verify_failed = true;
+    c->verify_result = ossl_ret;
+  }
+  return ret;
+}
+
+static ptls_openssl_override_verify_certificate_t quic_override_verify = {
+  quic_override_verify_cb,
+};
+
+/* Validate a ca_file / ca_path setting and return it as a String, or Qnil.
+   Accepts a String or anything responding to #to_path. Every misconfiguration
+   of the verification settings raises ArgumentError, including a wrong type. */
+static VALUE
+quic_verify_path_value(VALUE value, const char *name)
+{
+  if (NIL_P(value)) return Qnil;
+
+  VALUE path = value;
+  if (!RB_TYPE_P(path, T_STRING)) {
+    if (rb_respond_to(path, rb_intern("to_path"))) {
+      path = rb_funcall(path, rb_intern("to_path"), 0);
+    }
+    if (!RB_TYPE_P(path, T_STRING)) {
+      rb_raise(rb_eArgError, "%s must be a String or Pathname (got %"PRIsVALUE")",
+               name, rb_obj_class(value));
+    }
+  }
+  /* Raises ArgumentError when the path contains a NUL byte. */
+  StringValueCStr(path);
+  return path;
+}
+
+/* Install picotls's certificate verifier on c->tls_ctx according to the
+   verify_mode / ca_file / ca_path settings. Leaves verify_certificate NULL
+   for verify_mode :none, which skips verification altogether. */
+static void
+quic_client_setup_verify(quic_client_t *c, VALUE settings_v, VALUE server_name)
+{
+  VALUE mode = rb_funcall(settings_v, rb_intern("verify_mode"), 0);
+  /* ca_file and ca_path are not even type-checked under :none. */
+  if (mode == ID2SYM(rb_intern("none"))) return;
+  if (mode != ID2SYM(rb_intern("peer"))) {
+    rb_raise(rb_eArgError, "verify_mode must be :peer or :none (got %+"PRIsVALUE")", mode);
+  }
+
+  VALUE ca_file = quic_verify_path_value(rb_funcall(settings_v, rb_intern("ca_file"), 0), "ca_file");
+  VALUE ca_path = quic_verify_path_value(rb_funcall(settings_v, rb_intern("ca_path"), 0), "ca_path");
+
+  /* An empty name makes OpenSSL clear its host list and skip the name check,
+     and both SNI and the check would silently stop at an embedded NUL. */
+  if (RSTRING_LEN(server_name) == 0 ||
+      memchr(RSTRING_PTR(server_name), '\0', (size_t)RSTRING_LEN(server_name)) != NULL) {
+    rb_raise(rb_eArgError,
+             "server_name must be a non-empty string without NUL bytes when verify_mode is :peer");
+  }
+  /* X509_LOOKUP_hash_dir does not check that the directory exists. */
+  if (!NIL_P(ca_path) && !RTEST(rb_funcall(rb_cFile, rb_intern("directory?"), 1, ca_path))) {
+    rb_raise(rb_eArgError, "ca_path is not a directory: %"PRIsVALUE, ca_path);
+  }
+
+  X509_STORE *store;
+  bool own_store = !NIL_P(ca_file) || !NIL_P(ca_path);
+  if (own_store) {
+    /* Trust only what was given; the system store is not consulted. */
+    store = X509_STORE_new();
+    if (store == NULL) {
+      rb_raise(rb_eRuntimeError, "X509_STORE_new failed");
+    }
+    if (X509_STORE_load_locations(store,
+                                  NIL_P(ca_file) ? NULL : RSTRING_PTR(ca_file),
+                                  NIL_P(ca_path) ? NULL : RSTRING_PTR(ca_path)) != 1) {
+      X509_STORE_free(store);
+      /* libcrypto is shared with Ruby's openssl extension; do not leave our
+         failure on its error queue. */
+      ERR_clear_error();
+      if (NIL_P(ca_file)) {
+        rb_raise(rb_eArgError, "failed to load ca_path: %"PRIsVALUE, ca_path);
+      }
+      rb_raise(rb_eArgError, "failed to load ca_file: %"PRIsVALUE, ca_file);
+    }
+  } else {
+    store = quic_get_default_store();
+  }
+
+  /* init takes its own reference on the store, so ours can go right away. */
+  int rv = ptls_openssl_init_verify_certificate(&c->verify_cert, store);
+  if (own_store) X509_STORE_free(store);
+  if (rv != 0) {
+    rb_raise(rb_eRuntimeError, "ptls_openssl_init_verify_certificate failed");
+  }
+  c->verify_cert_initialized = true;
+  c->verify_cert.override_callback = &quic_override_verify;
+  c->tls_ctx.verify_certificate = &c->verify_cert.super;
+}
+
 static VALUE
 quic_client_open(int argc, VALUE *argv, VALUE klass)
 {
@@ -334,13 +531,6 @@ quic_client_open(int argc, VALUE *argv, VALUE klass)
   quic_require_binary(remote_sockaddr, "remote_sockaddr");
   Check_Type(server_name, T_STRING);
 
-  if (!quic_crypto_initialized) {
-    if (ngtcp2_crypto_quictls_init() != 0) {
-      rb_raise(rb_eRuntimeError, "ngtcp2_crypto_quictls_init failed");
-    }
-    quic_crypto_initialized = 1;
-  }
-
   VALUE self = quic_client_alloc(klass);
   rb_ivar_set(self, rb_intern("@server_name"), server_name);
 
@@ -348,26 +538,13 @@ quic_client_open(int argc, VALUE *argv, VALUE klass)
   TypedData_Get_Struct(self, quic_client_t, &quic_client_data_type, c);
   c->owner = self;
 
-  c->ssl_ctx = SSL_CTX_new(TLS_client_method());
-  if (!c->ssl_ctx) {
-    rb_raise(rb_eRuntimeError, "SSL_CTX_new failed");
-  }
-  if (ngtcp2_crypto_quictls_configure_client_context(c->ssl_ctx) != 0) {
-    rb_raise(rb_eRuntimeError, "ngtcp2_crypto_quictls_configure_client_context failed");
-  }
-
-  c->ssl = SSL_new(c->ssl_ctx);
-  if (!c->ssl) {
-    rb_raise(rb_eRuntimeError, "SSL_new failed");
-  }
-  SSL_set_connect_state(c->ssl);
-  SSL_set_tlsext_host_name(c->ssl, RSTRING_PTR(server_name));
-
+  /* Copy the ALPN list into memory owned by c: picotls keeps the pointers
+     for the whole handshake, so ALLOCA_N would not survive. An empty list
+     means no ALPN extension, matching the old skip-SSL_set_alpn_protos path. */
   VALUE alpn_ary = rb_funcall(settings_v, rb_intern("alpn"), 0);
   Check_Type(alpn_ary, T_ARRAY);
   long n_alpn = RARRAY_LEN(alpn_ary);
   if (n_alpn > 0) {
-    /* RFC 7301 wire format: 1-byte length prefix + bytes, concatenated. */
     size_t total = 0;
     for (long i = 0; i < n_alpn; i++) {
       VALUE entry = RARRAY_AREF(alpn_ary, i);
@@ -376,30 +553,44 @@ quic_client_open(int argc, VALUE *argv, VALUE klass)
       if (len < 1 || len > 255) {
         rb_raise(rb_eArgError, "alpn entry must be 1-255 bytes (got %ld)", len);
       }
-      total += 1 + (size_t)len;
+      total += (size_t)len;
     }
-    /* total <= 256 * 256 = 65536; ALLOCA_N is safe at this size. */
-    unsigned char *wire = ALLOCA_N(unsigned char, total);
-    unsigned char *p = wire;
+    c->alpn_buf = ALLOC_N(uint8_t, total);
+    c->alpn = ALLOC_N(ptls_iovec_t, n_alpn);
+    uint8_t *p = c->alpn_buf;
     for (long i = 0; i < n_alpn; i++) {
       VALUE entry = RARRAY_AREF(alpn_ary, i);
-      long len = RSTRING_LEN(entry);
-      *p++ = (unsigned char)len;
-      memcpy(p, RSTRING_PTR(entry), (size_t)len);
+      size_t len = (size_t)RSTRING_LEN(entry);
+      memcpy(p, RSTRING_PTR(entry), len);
+      c->alpn[i] = ptls_iovec_init(p, len);
       p += len;
     }
-    /* SSL_set_alpn_protos returns 0 on success (counter-intuitive). */
-    if (SSL_set_alpn_protos(c->ssl, wire, (unsigned int)total) != 0) {
-      rb_raise(rb_eRuntimeError, "SSL_set_alpn_protos failed");
-    }
+    c->alpn_count = (size_t)n_alpn;
   }
 
-  /* Link the SSL handle back to this client so ngtcp2's crypto callbacks
-     (add_handshake_data, set_encryption_secrets, ...) can resolve the
-     ngtcp2_conn via SSL_get_app_data -> ngtcp2_crypto_conn_ref. */
+  /* quic_client_alloc already zeroed the struct, but calling ctx_init keeps
+     the ngtcp2-side initialization explicit and the TLS setup in one place. */
+  ngtcp2_crypto_picotls_ctx_init(&c->cptls);
+  c->tls_ctx = (ptls_context_t){
+    .random_bytes = ptls_openssl_random_bytes,
+    .get_time = &ptls_get_time,
+    .key_exchanges = quic_key_exchanges,
+    .cipher_suites = quic_cipher_suites,
+    /* No session resumption yet, so this has no effect today. Keep it so that
+       when resumption is added, PSK-only (non-forward-secret) resumption is
+       refused rather than silently accepted. */
+    .require_dhe_on_psk = 1,
+  };
+  if (ngtcp2_crypto_picotls_configure_client_context(&c->tls_ctx) != 0) {
+    rb_raise(rb_eRuntimeError, "ngtcp2_crypto_picotls_configure_client_context failed");
+  }
+
+  /* ptls_client_new keeps a pointer to tls_ctx, so the verifier has to be in
+     place before it runs. */
+  quic_client_setup_verify(c, settings_v, server_name);
+
   c->conn_ref.get_conn = quic_client_get_conn;
   c->conn_ref.user_data = c;
-  SSL_set_app_data(c->ssl, &c->conn_ref);
 
   c->scid.datalen = 8;
   if (RAND_bytes(c->scid.data, 8) != 1) {
@@ -450,13 +641,42 @@ quic_client_open(int argc, VALUE *argv, VALUE klass)
     quic_raise_ngtcp2_error(rv);
   }
 
-  ngtcp2_conn_set_tls_native_handle(c->conn, c->ssl);
+  /* The TLS session is built last: configure_client_session derives the QUIC
+     transport parameters from the conn, so it needs the conn to exist. */
+  c->cptls.ptls = ptls_client_new(&c->tls_ctx);
+  if (c->cptls.ptls == NULL) {
+    rb_raise(rb_eRuntimeError, "ptls_client_new failed");
+  }
+  /* Let ngtcp2's crypto callbacks (add_handshake_data,
+     set_encryption_secrets, ...) resolve the ngtcp2_conn from the ptls_t. */
+  *ptls_get_data_ptr(c->cptls.ptls) = &c->conn_ref;
+  /* [0] is filled in by configure_client_session with the QUIC transport
+     parameters; [1] terminates the list. */
+  c->tls_exts[0].type = UINT16_MAX;
+  c->tls_exts[1].type = UINT16_MAX;
+  c->cptls.handshake_properties.additional_extensions = c->tls_exts;
+  if (ngtcp2_crypto_picotls_configure_client_session(&c->cptls, c->conn) != 0) {
+    rb_raise(rb_eRuntimeError, "ngtcp2_crypto_picotls_configure_client_session failed");
+  }
+  c->cptls.handshake_properties.client.negotiated_protocols.list = c->alpn;
+  c->cptls.handshake_properties.client.negotiated_protocols.count = c->alpn_count;
+  /* ptls_set_server_name copies the name. */
+  if (ptls_set_server_name(c->cptls.ptls, RSTRING_PTR(server_name),
+                           (size_t)RSTRING_LEN(server_name)) != 0) {
+    rb_raise(rb_eRuntimeError, "ptls_set_server_name failed");
+  }
+
+  ngtcp2_conn_set_tls_native_handle(c->conn, &c->cptls);
 
-  /* Stream registry: stream_id (Integer) -> Quic::Stream.
+  /* Stream registry: stream_id (Integer) -> QUIC::Stream.
      Populated by #open_bidi_stream / #open_uni_stream and the stream_open
      callback. Entries are removed in the stream_close callback. */
   rb_ivar_set(self, rb_intern("@streams"), rb_hash_new());
 
+  /* FIFO of peer-initiated (server) streams awaiting #accept_stream. The
+     recv_stream_data callback pushes each new server stream here once. */
+  rb_ivar_set(self, rb_intern("@accept_queue"), rb_ary_new());
+
   return self;
 }
 
@@ -613,6 +833,36 @@ quic_client_write_pkt(int argc, VALUE *argv, VALUE self)
   return buffer;
 }
 
+NORETURN(static void quic_client_raise_error(quic_client_t *c, int rv));
+
+/* Like quic_raise_ngtcp2_error, but for errors from read_pkt, where the TLS
+   handshake runs: NGTCP2_ERR_CRYPTO carries the TLS alert this client sent,
+   and becomes CertificateVerifyFailed when the verifier rejected the peer. */
+static void
+quic_client_raise_error(quic_client_t *c, int rv)
+{
+  if (rv != NGTCP2_ERR_CRYPTO) quic_raise_ngtcp2_error(rv);
+
+  /* 0 means "not set" to ngtcp2; close_notify (0) is never sent for a
+     verification failure, so report it as nil. */
+  uint8_t alert = ngtcp2_conn_get_tls_alert(c->conn);
+  VALUE exc;
+  if (c->verify_failed) {
+    VALUE msg = c->verify_result
+      ? rb_sprintf("certificate verify failed (%s)",
+                   X509_verify_cert_error_string(c->verify_result))
+      : rb_str_new_cstr("certificate verify failed (server sent no certificate)");
+    exc = rb_exc_new_str(rb_eQUICErrorCertificateVerifyFailed, msg);
+    rb_ivar_set(exc, rb_intern("@verify_result"),
+                c->verify_result ? INT2NUM(c->verify_result) : Qnil);
+  } else {
+    exc = rb_exc_new_cstr(rb_eQUICErrorCryptoError, ngtcp2_strerror(rv));
+  }
+  rb_ivar_set(exc, rb_intern("@code"), INT2NUM(rv));
+  rb_ivar_set(exc, rb_intern("@tls_alert"), alert ? INT2NUM(alert) : Qnil);
+  rb_exc_raise(exc);
+}
+
 struct quic_read_pkt_args {
   quic_client_t *c;
   VALUE packet;
@@ -630,7 +880,7 @@ quic_read_pkt_body(VALUE arg)
                                 quic_now());
   if (rv != 0) {
     /* NORETURN: longjmp passes through rb_ensure so unlock still fires. */
-    quic_raise_ngtcp2_error(rv);
+    quic_client_raise_error(a->c, rv);
   }
   return Qnil;
 }
@@ -760,19 +1010,104 @@ quic_client_open_uni_stream(VALUE self)
   return stream;
 }
 
+/* Send an application CONNECTION_CLOSE (frame type 0x1d) to the peer and
+   transition the underlying ngtcp2_conn to the closing period. One UDP
+   datagram is written to the bound socket; ngtcp2 handles closing-period
+   retransmits via the caller's pump loop. Calling #close on a connection
+   that is already in the closing or draining period is a no-op (= returns
+   nil without doing any I/O). */
+static VALUE
+quic_client_close_m(int argc, VALUE *argv, VALUE self)
+{
+  VALUE opts = Qnil;
+  rb_scan_args(argc, argv, "0:", &opts);
+
+  uint64_t error_code = 0;
+  const uint8_t *reason_ptr = (const uint8_t *)"";
+  size_t reason_len = 0;
+
+  if (!NIL_P(opts)) {
+    VALUE error_code_v = rb_hash_aref(opts, ID2SYM(rb_intern("error_code")));
+    VALUE reason_v = rb_hash_aref(opts, ID2SYM(rb_intern("reason")));
+    if (!NIL_P(error_code_v)) {
+      error_code = NUM2ULL(error_code_v);
+    }
+    if (!NIL_P(reason_v)) {
+      Check_Type(reason_v, T_STRING);
+      reason_ptr = (const uint8_t *)RSTRING_PTR(reason_v);
+      reason_len = (size_t)RSTRING_LEN(reason_v);
+    }
+  }
+
+  quic_client_t *c;
+  TypedData_Get_Struct(self, quic_client_t, &quic_client_data_type, c);
+
+  /* Idempotent: a subsequent #close after the conn already entered the
+     closing/draining period does not emit another CONNECTION_CLOSE. */
+  if (ngtcp2_conn_in_closing_period(c->conn) ||
+      ngtcp2_conn_in_draining_period(c->conn)) {
+    return Qnil;
+  }
+
+  VALUE sock = rb_ivar_get(self, rb_intern("@sock"));
+  if (NIL_P(sock)) {
+    rb_raise(rb_eQUICErrorNotBound,
+             "QUIC::Connection::Client#bind(sock) has not been called");
+  }
+
+  ngtcp2_ccerr ccerr;
+  ngtcp2_ccerr_set_application_error(&ccerr, error_code,
+                                     reason_len > 0 ? reason_ptr : NULL,
+                                     reason_len);
+
+  ngtcp2_path_storage path_storage;
+  ngtcp2_path_storage_zero(&path_storage);
+  ngtcp2_pkt_info pi;
+  memset(&pi, 0, sizeof(pi));
+
+  VALUE buffer = rb_str_buf_new(QUIC_WRITE_PKT_BUFLEN);
+  uint8_t *dest = (uint8_t *)RSTRING_PTR(buffer);
+
+  ngtcp2_ssize n = ngtcp2_conn_write_connection_close(
+      c->conn, &path_storage.path, &pi, dest,
+      (size_t)QUIC_WRITE_PKT_BUFLEN, &ccerr, quic_now());
+
+  /* Pre-handshake or otherwise not in a state where CONNECTION_CLOSE can be
+     emitted (ngtcp2 returns NGTCP2_ERR_INVALID_STATE). Spec treats this as
+     best-effort: silently no-op rather than surface an error. The Ruby
+     Client is effectively dead from here. */
+  if (n == NGTCP2_ERR_INVALID_STATE) {
+    return Qnil;
+  }
+
+  if (n < 0) {
+    rb_str_set_len(buffer, 0);
+    quic_raise_ngtcp2_error((int)n);
+  }
+
+  if (n == 0) {
+    return Qnil;
+  }
+
+  rb_str_set_len(buffer, n);
+  rb_funcall(sock, rb_intern("send"), 2, buffer, INT2NUM(0));
+  return Qnil;
+}
+
 void
-Init_quic_connection_client(VALUE rb_mQuicConnectionArg)
-{
-  rb_cQuicConnectionClient = rb_define_class_under(rb_mQuicConnectionArg, "Client", rb_cObject);
-  rb_define_alloc_func(rb_cQuicConnectionClient, quic_client_alloc);
-  rb_define_singleton_method(rb_cQuicConnectionClient, "_open", quic_client_open, -1);
-  rb_define_method(rb_cQuicConnectionClient, "write_pkt", quic_client_write_pkt, -1);
-  rb_define_method(rb_cQuicConnectionClient, "read_pkt",  quic_client_read_pkt,  -1);
-  rb_define_method(rb_cQuicConnectionClient, "expiry", quic_client_expiry, 0);
-  rb_define_method(rb_cQuicConnectionClient, "handle_expiry", quic_client_handle_expiry, 0);
-  rb_define_method(rb_cQuicConnectionClient, "handshake_completed?", quic_client_handshake_completed_p, 0);
-  rb_define_method(rb_cQuicConnectionClient, "in_closing_period?", quic_client_in_closing_period_p, 0);
-  rb_define_method(rb_cQuicConnectionClient, "in_draining_period?", quic_client_in_draining_period_p, 0);
-  rb_define_method(rb_cQuicConnectionClient, "open_bidi_stream", quic_client_open_bidi_stream, 0);
-  rb_define_method(rb_cQuicConnectionClient, "open_uni_stream", quic_client_open_uni_stream, 0);
+Init_quic_connection_client(VALUE rb_mQUICConnectionArg)
+{
+  rb_cQUICConnectionClient = rb_define_class_under(rb_mQUICConnectionArg, "Client", rb_cObject);
+  rb_define_alloc_func(rb_cQUICConnectionClient, quic_client_alloc);
+  rb_define_singleton_method(rb_cQUICConnectionClient, "_open", quic_client_open, -1);
+  rb_define_method(rb_cQUICConnectionClient, "write_pkt", quic_client_write_pkt, -1);
+  rb_define_method(rb_cQUICConnectionClient, "read_pkt",  quic_client_read_pkt,  -1);
+  rb_define_method(rb_cQUICConnectionClient, "expiry", quic_client_expiry, 0);
+  rb_define_method(rb_cQUICConnectionClient, "handle_expiry", quic_client_handle_expiry, 0);
+  rb_define_method(rb_cQUICConnectionClient, "handshake_completed?", quic_client_handshake_completed_p, 0);
+  rb_define_method(rb_cQUICConnectionClient, "in_closing_period?", quic_client_in_closing_period_p, 0);
+  rb_define_method(rb_cQUICConnectionClient, "in_draining_period?", quic_client_in_draining_period_p, 0);
+  rb_define_method(rb_cQUICConnectionClient, "open_bidi_stream", quic_client_open_bidi_stream, 0);
+  rb_define_method(rb_cQUICConnectionClient, "open_uni_stream", quic_client_open_uni_stream, 0);
+  rb_define_method(rb_cQUICConnectionClient, "close", quic_client_close_m, -1);
 }