net.quic: 13c - connection ID lifecycle (NEW_CONNECTION_ID/RETIRE_CONNECTION_ID)

Adds the RFC 9000 §19.15/§19.16 wire codec for NEW_CONNECTION_ID/
RETIRE_CONNECTION_ID frames (frame.v), previously falling through
parse_frame's generic "not yet implemented" branch, plus
generate_stateless_reset_token (stateless_reset.v) implementing RFC 9000
§10.3.2's recommended HMAC-SHA-256(static_key, connection_id) derivation,
cross-checked against the existing StatelessResetTracker.is_stateless_reset.

Also updates QuicConn.dispatch_one_rtt_frame (conn.v) to explicitly
acknowledge the two new frame types now flow through it instead of
silently landing in the generic informational-hint else-arm, documenting
why they're accepted-but-not-yet-acted-upon pending the (deliberately
deferred) active-connection-ID-set state machine.

Driving that active set (issuing more CIDs, active_connection_id_limit
accounting) remains out of scope, same as before this commit.

Author: Richard Wheeler

vlib/net/quic/PROGRESS.md

@@ -1321,11 +1321,39 @@ stacked-PR convention as Phase 12's 12a-12d.
     instead (same API, OS-backed, already used elsewhere in this codebase).
     This is a real gap in already-merged code (Phase 9, PR #28129), not
     Phase 13 work — flagged as a separate follow-up task, not fixed inline.
-- [ ] **13c** — Connection ID lifecycle: `NEW_CONNECTION_ID`/
-      `RETIRE_CONNECTION_ID` frames (currently fall through `frame.v`'s
-      generic "not yet implemented" branch), stateless reset token
-      generation per issued CID (`StatelessResetTracker` currently only
-      checks incoming tokens).
+- [x] **13c** — Connection ID lifecycle:
+  - [x] `NewConnectionIdFrame`/`RetireConnectionIdFrame` wire codec
+        (`frame.v`) — `encode_new_connection_id_frame`/
+        `parse_new_connection_id_frame` and their RETIRE_CONNECTION_ID
+        counterparts, types 0x18/0x19, previously falling through
+        `parse_frame`'s generic "not yet implemented" branch. Enforces the
+        two frame-local RFC 9000 §19.15 requirements (`retire_prior_to` ≤
+        `sequence_number`; connection ID length in 1-20 bytes), on both the
+        encode and decode sides so a caller can't construct a frame this
+        module's own parser would then reject. Every OTHER §19.15/§19.16
+        requirement (zero-length-DCID prohibition, duplicate/conflicting
+        sequence numbers, a RETIRE_CONNECTION_ID referencing the current
+        packet's own DCID) needs connection state `parse_frame` doesn't
+        have — deferred to the caller, the same division already
+        established for `HandshakeDoneFrame`'s role check.
+  - [x] `generate_stateless_reset_token` (`stateless_reset.v`) — RFC 9000
+        §10.3.2's recommended construction, `HMAC-SHA-256(static_key,
+        connection_id)` truncated to 16 bytes: a server-instance-local
+        secret plus the connection ID deterministically reproduces the
+        SAME token, so an endpoint that has lost all per-connection state
+        (the entire premise of a stateless reset) can still recompute it.
+        Cross-checked against `StatelessResetTracker.is_stateless_reset`
+        (already-existing, independently-written matching logic) — proving
+        a token this function generates is actually recognized by the
+        exact code that would validate it in production.
+  - **Deliberately still out of scope** (per `stateless_reset.v`'s own
+    long-standing note, unchanged by 13c): driving an ACTIVE SET of usable
+    connection IDs — issuing more as the peer retires them,
+    `active_connection_id_limit` accounting, `CONNECTION_ID_LIMIT_ERROR`
+    enforcement. That full lifecycle exists to support connection
+    migration, which PROGRESS.md already lists as a separate, explicitly
+    deferrable follow-up below — 13c ships the wire codec and the token
+    primitive it depends on, not the state machine that would consume them.
 - [ ] **13d** — UDP listener + connection demux: one socket routing many
       concurrent connections by connection ID (not 4-tuple, since QUIC
       supports migration) — no analog in the client's transport today; the

vlib/net/quic/conn.v

@@ -1029,6 +1029,24 @@ fn (mut c QuicConn) dispatch_one_rtt_frame(frame QuicFrame, now u64, mut result
 				}
 			}
 		}
+		NewConnectionIdFrame, RetireConnectionIdFrame {
+			// Legal here (RFC 9000 §12.4 Table 3 marks both 1-RTT-only,
+			// consistent with dispatch_pre_confirm_frame's own rejection
+			// of them in the Initial/Handshake spaces), accepted, but not
+			// yet acted upon: driving an ACTIVE SET of usable connection
+			// IDs (issuing more as the peer retires them,
+			// active_connection_id_limit accounting, the §19.15/§19.16
+			// requirements that need that same state -- e.g. §19.16's
+			// "sequence number greater than any previously sent" check)
+			// is a deliberately deferred state machine, not yet built --
+			// see stateless_reset.v's doc comment and PROGRESS.md's Phase
+			// 13c scope note. The wire codec these frames now decode
+			// through (frame.v) exists so that state machine has
+			// something to consume once it lands; until then, a peer
+			// sending either is simply ignored, the same as this
+			// function's own CryptoFrame arm ignores post-handshake
+			// CRYPTO for an unimplemented feature.
+		}
 		else {
 			// DATA_BLOCKED/STREAM_DATA_BLOCKED/STREAMS_BLOCKED: purely
 			// informational hints (RFC 9000 §19.12-§19.14 impose no MUST

vlib/net/quic/frame.v

@@ -211,6 +211,37 @@ pub:
 // analogous note).
 pub struct HandshakeDoneFrame {}
 
+// NewConnectionIdFrame represents a NEW_CONNECTION_ID frame (type 0x18, RFC
+// 9000 §19.15): the sender offering an additional connection ID (and its
+// associated stateless-reset token, see generate_stateless_reset_token in
+// stateless_reset.v) for the peer to use. `retire_prior_to` is validated
+// against `sequence_number` (§19.15's "MUST be less than or equal to"
+// requirement) by both parse_frame and encode_new_connection_id_frame;
+// every other requirement in that section (the zero-length-DCID
+// prohibition, duplicate-sequence-number handling) needs connection state
+// parse_frame doesn't have, so -- same division as HandshakeDoneFrame's
+// role check above -- it is deferred to the caller.
+pub struct NewConnectionIdFrame {
+pub:
+	sequence_number       u64
+	retire_prior_to       u64
+	connection_id         []u8
+	stateless_reset_token []u8 // always exactly 16 bytes (RFC 9000 §19.15)
+}
+
+// RetireConnectionIdFrame represents a RETIRE_CONNECTION_ID frame (type
+// 0x19, RFC 9000 §19.16): the sender will no longer use the connection ID
+// with this sequence number. Every normative check in §19.16 (sequence
+// number not greater than any previously sent, not equal to the DCID of
+// the packet carrying this frame, not sent by an endpoint using a
+// zero-length CID) needs connection state parse_frame doesn't have, so --
+// same division as HandshakeDoneFrame's role check above -- it is deferred
+// to the caller.
+pub struct RetireConnectionIdFrame {
+pub:
+	sequence_number u64
+}
+
 pub type QuicFrame = AckFrame
 	| ConnectionCloseFrame
 	| CryptoFrame
@@ -219,9 +250,11 @@ pub type QuicFrame = AckFrame
 	| MaxDataFrame
 	| MaxStreamDataFrame
 	| MaxStreamsFrame
+	| NewConnectionIdFrame
 	| PaddingFrame
 	| PingFrame
 	| ResetStreamFrame
+	| RetireConnectionIdFrame
 	| StopSendingFrame
 	| StreamDataBlockedFrame
 	| StreamFrame
@@ -243,6 +276,8 @@ const frame_type_data_blocked = u64(0x14)
 const frame_type_stream_data_blocked = u64(0x15)
 const frame_type_streams_blocked_bidi = u64(0x16)
 const frame_type_streams_blocked_uni = u64(0x17)
+const frame_type_new_connection_id = u64(0x18)
+const frame_type_retire_connection_id = u64(0x19)
 const frame_type_connection_close_transport = u64(0x1c)
 const frame_type_connection_close_application = u64(0x1d)
 const frame_type_handshake_done = u64(0x1e)
@@ -314,6 +349,14 @@ pub fn parse_frame(buf []u8) !(QuicFrame, int) {
 		return parse_streams_blocked_frame(buf, typ_len, typ == frame_type_streams_blocked_uni)
 	}
 
+	if typ == frame_type_new_connection_id {
+		return parse_new_connection_id_frame(buf, typ_len)
+	}
+
+	if typ == frame_type_retire_connection_id {
+		return parse_retire_connection_id_frame(buf, typ_len)
+	}
+
 	if typ == frame_type_connection_close_transport
 		|| typ == frame_type_connection_close_application {
 		return parse_connection_close_frame(buf, typ_len,
@@ -598,6 +641,60 @@ fn parse_streams_blocked_frame(buf []u8, start int, is_uni bool) !(QuicFrame, in
 	}), start + n1
 }
 
+fn parse_new_connection_id_frame(buf []u8, start int) !(QuicFrame, int) {
+	mut offset := start
+	sequence_number, n1 := decode_varint(buf[offset..])!
+	offset += n1
+	retire_prior_to, n2 := decode_varint(buf[offset..])!
+	offset += n2
+
+	// RFC 9000 §19.15: "The value in the Retire Prior To field MUST be
+	// less than or equal to the value in the Sequence Number field.
+	// Receiving a value in the Retire Prior To field that is greater than
+	// that in the Sequence Number field MUST be treated as a connection
+	// error of type FRAME_ENCODING_ERROR."
+	if retire_prior_to > sequence_number {
+		return error('quic: NEW_CONNECTION_ID frame: retire_prior_to ${retire_prior_to} exceeds sequence_number ${sequence_number} (RFC 9000 §19.15)')
+	}
+
+	if offset >= buf.len {
+		return error('quic: NEW_CONNECTION_ID frame: missing Length field')
+	}
+	length := int(buf[offset])
+	offset += 1
+	// RFC 9000 §19.15: "Values less than 1 and greater than 20 are invalid
+	// and MUST be treated as a connection error of type
+	// FRAME_ENCODING_ERROR." 20 is quic_v1_max_cid_len (header.v).
+	if length < 1 || length > quic_v1_max_cid_len {
+		return error('quic: NEW_CONNECTION_ID frame: connection ID length ${length} is outside the valid 1-${quic_v1_max_cid_len} range (RFC 9000 §19.15)')
+	}
+	if offset + length > buf.len {
+		return error('quic: NEW_CONNECTION_ID frame: declares a ${length}-byte connection ID exceeding the remaining buffer')
+	}
+	connection_id := buf[offset..offset + length].clone()
+	offset += length
+
+	if offset + 16 > buf.len {
+		return error('quic: NEW_CONNECTION_ID frame: missing 16-byte stateless reset token')
+	}
+	stateless_reset_token := buf[offset..offset + 16].clone()
+	offset += 16
+
+	return QuicFrame(NewConnectionIdFrame{
+		sequence_number:       sequence_number
+		retire_prior_to:       retire_prior_to
+		connection_id:         connection_id
+		stateless_reset_token: stateless_reset_token
+	}), offset
+}
+
+fn parse_retire_connection_id_frame(buf []u8, start int) !(QuicFrame, int) {
+	sequence_number, n1 := decode_varint(buf[start..])!
+	return QuicFrame(RetireConnectionIdFrame{
+		sequence_number: sequence_number
+	}), start + n1
+}
+
 fn parse_connection_close_frame(buf []u8, start int, is_application_error bool) !(QuicFrame, int) {
 	mut offset := start
 	error_code, n1 := decode_varint(buf[offset..])!
@@ -840,6 +937,38 @@ pub fn encode_streams_blocked_frame(direction StreamDirection, maximum_streams u
 	return out
 }
 
+// encode_new_connection_id_frame serializes a NEW_CONNECTION_ID frame.
+// Mirrors parse_new_connection_id_frame's exact validation (RFC 9000
+// §19.15) so a caller cannot construct a frame this same module's own
+// parser would then reject.
+pub fn encode_new_connection_id_frame(sequence_number u64, retire_prior_to u64, connection_id []u8, stateless_reset_token []u8) ![]u8 {
+	if retire_prior_to > sequence_number {
+		return error('quic: encode_new_connection_id_frame: retire_prior_to ${retire_prior_to} exceeds sequence_number ${sequence_number} (RFC 9000 §19.15)')
+	}
+	if connection_id.len < 1 || connection_id.len > quic_v1_max_cid_len {
+		return error('quic: encode_new_connection_id_frame: connection ID length ${connection_id.len} is outside the valid 1-${quic_v1_max_cid_len} range (RFC 9000 §19.15)')
+	}
+	if stateless_reset_token.len != 16 {
+		return error('quic: encode_new_connection_id_frame: stateless reset token must be exactly 16 bytes, got ${stateless_reset_token.len}')
+	}
+	mut out := encode_varint(frame_type_new_connection_id)!
+	out << encode_varint(sequence_number)!
+	out << encode_varint(retire_prior_to)!
+	out << u8(connection_id.len)
+	out << connection_id
+	out << stateless_reset_token
+	return out
+}
+
+// encode_retire_connection_id_frame serializes a RETIRE_CONNECTION_ID
+// frame. See RetireConnectionIdFrame's doc comment for which §19.16
+// requirements are the caller's responsibility rather than this function's.
+pub fn encode_retire_connection_id_frame(sequence_number u64) ![]u8 {
+	mut out := encode_varint(frame_type_retire_connection_id)!
+	out << encode_varint(sequence_number)!
+	return out
+}
+
 // encode_connection_close_frame serializes a CONNECTION_CLOSE frame.
 // `frame_type` is ignored (the Frame Type field is OMITTED from the wire
 // entirely, not encoded as a zero value) when `is_application_error` is

vlib/net/quic/frame_test.v

@@ -259,14 +259,14 @@ fn test_scaled_ack_delay_micros_saturates_at_exponent_ge_64() {
 }
 
 fn test_parse_frame_rejects_unimplemented_frame_type() {
-	// 0x18 (NEW_CONNECTION_ID) is a real, valid QUIC frame type this module
-	// simply doesn't implement yet -- connection ID rotation/migration is
-	// explicitly out of v1 scope (see stateless_reset.v's own doc comment)
-	// -- must be a clear "not implemented" error, not a wire-format error
-	// or a panic. (0x08 STREAM and 0x1e HANDSHAKE_DONE, both used here
-	// before their respective phases implemented them, would no longer
-	// demonstrate this.)
-	parse_frame([u8(0x18)]) or {
+	// 0x1a (PATH_CHALLENGE) is a real, valid QUIC frame type this module
+	// simply doesn't implement yet -- connection migration is explicitly a
+	// separate, deferrable follow-up (see PROGRESS.md's Phase 13 notes) --
+	// must be a clear "not implemented" error, not a wire-format error or
+	// a panic. (0x08 STREAM, 0x18 NEW_CONNECTION_ID, and 0x1e
+	// HANDSHAKE_DONE, all used here before their respective phases
+	// implemented them, would no longer demonstrate this.)
+	parse_frame([u8(0x1a)]) or {
 		assert err.msg().contains('not yet implemented')
 		return
 	}
@@ -736,3 +736,127 @@ fn test_streams_blocked_frame_round_trip_both_directions() {
 		}
 	}
 }
+
+fn test_new_connection_id_frame_round_trip() {
+	cid := [u8(1), 2, 3, 4, 5, 6, 7, 8]
+	token := []u8{len: 16, init: 0xab}
+	encoded := encode_new_connection_id_frame(3, 1, cid, token)!
+	assert encoded[0] == 0x18
+	frame, n := parse_frame(encoded)!
+	assert n == encoded.len
+	match frame {
+		NewConnectionIdFrame {
+			assert frame.sequence_number == 3
+			assert frame.retire_prior_to == 1
+			assert frame.connection_id == cid
+			assert frame.stateless_reset_token == token
+		}
+		else {
+			assert false, 'expected a NewConnectionIdFrame'
+		}
+	}
+}
+
+fn test_new_connection_id_frame_round_trip_at_max_cid_length() {
+	cid := []u8{len: quic_v1_max_cid_len, init: 0x42}
+	token := []u8{len: 16, init: 0}
+	encoded := encode_new_connection_id_frame(0, 0, cid, token)!
+	frame, _ := parse_frame(encoded)!
+	match frame {
+		NewConnectionIdFrame {
+			assert frame.connection_id == cid
+		}
+		else {
+			assert false, 'expected a NewConnectionIdFrame'
+		}
+	}
+}
+
+fn test_encode_new_connection_id_frame_rejects_retire_prior_to_above_sequence_number() {
+	encode_new_connection_id_frame(1, 2, [u8(1)], []u8{len: 16}) or {
+		assert err.msg().contains('retire_prior_to')
+		return
+	}
+	assert false, 'expected retire_prior_to > sequence_number to be rejected'
+}
+
+fn test_parse_new_connection_id_frame_rejects_retire_prior_to_above_sequence_number() {
+	mut buf := encode_varint(frame_type_new_connection_id)!
+	buf << encode_varint(u64(1))! // sequence_number
+	buf << encode_varint(u64(2))! // retire_prior_to > sequence_number
+	buf << u8(1)
+	buf << [u8(0xff)]
+	buf << []u8{len: 16}
+	parse_frame(buf) or {
+		assert err.msg().contains('retire_prior_to')
+		return
+	}
+	assert false, 'expected retire_prior_to > sequence_number to be rejected'
+}
+
+fn test_encode_new_connection_id_frame_rejects_zero_length_connection_id() {
+	encode_new_connection_id_frame(0, 0, []u8{}, []u8{len: 16}) or {
+		assert err.msg().contains('connection ID length')
+		return
+	}
+	assert false, 'expected a zero-length connection ID to be rejected'
+}
+
+fn test_encode_new_connection_id_frame_rejects_connection_id_above_20_bytes() {
+	encode_new_connection_id_frame(0, 0, []u8{len: quic_v1_max_cid_len + 1}, []u8{len: 16}) or {
+		assert err.msg().contains('connection ID length')
+		return
+	}
+	assert false, 'expected a connection ID longer than 20 bytes to be rejected'
+}
+
+fn test_parse_new_connection_id_frame_rejects_length_above_20_bytes() {
+	mut buf := encode_varint(frame_type_new_connection_id)!
+	buf << encode_varint(u64(0))!
+	buf << encode_varint(u64(0))!
+	buf << u8(21) // declares an invalid, over-20-byte connection ID length
+	buf << []u8{len: 21}
+	buf << []u8{len: 16}
+	parse_frame(buf) or {
+		assert err.msg().contains('connection ID length')
+		return
+	}
+	assert false, 'expected a declared length above 20 bytes to be rejected'
+}
+
+fn test_encode_new_connection_id_frame_rejects_wrong_token_length() {
+	encode_new_connection_id_frame(0, 0, [u8(1)], []u8{len: 15}) or {
+		assert err.msg().contains('16 bytes')
+		return
+	}
+	assert false, 'expected a non-16-byte stateless reset token to be rejected'
+}
+
+fn test_parse_new_connection_id_frame_rejects_truncated_token() {
+	mut buf := encode_varint(frame_type_new_connection_id)!
+	buf << encode_varint(u64(0))!
+	buf << encode_varint(u64(0))!
+	buf << u8(1)
+	buf << [u8(0xff)]
+	buf << []u8{len: 10} // short of the required 16-byte token
+	parse_frame(buf) or {
+		assert err.msg().contains('stateless reset token')
+		return
+	}
+	assert false, 'expected a truncated stateless reset token to be rejected'
+}
+
+fn test_retire_connection_id_frame_round_trip() {
+	encoded := encode_retire_connection_id_frame(7)!
+	assert encoded[0] == 0x19
+	frame, n := parse_frame(encoded)!
+	assert n == encoded.len
+	match frame {
+		RetireConnectionIdFrame {
+			assert frame.sequence_number == 7
+		}
+		else {
+			assert false, 'expected a RetireConnectionIdFrame'
+		}
+	}
+}