From 0ac0c1e72c705514ac82f55f5287892d44d3b45d Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Mon, 14 Apr 2025 12:41:17 +0800 Subject: [PATCH] improve documentation for the ConnectionIDGenerator (#5043) --- interface.go | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/interface.go b/interface.go index 2553c728a..4c006ce0c 100644 --- a/interface.go +++ b/interface.go @@ -242,21 +242,16 @@ func ConnectionIDFromBytes(b []byte) ConnectionID { return protocol.ParseConnectionID(b) } -// A ConnectionIDGenerator is an interface that allows clients to implement their own format -// for the Connection IDs that servers/clients use as SrcConnectionID in QUIC packets. -// -// Connection IDs generated by an implementation should always produce IDs of constant size. +// A ConnectionIDGenerator allows the application to take control over the generation of Connection IDs. +// Connection IDs generated by an implementation must be of constant length. type ConnectionIDGenerator interface { - // GenerateConnectionID generates a new ConnectionID. - // Generated ConnectionIDs should be unique and observers should not be able to correlate two ConnectionIDs. + // GenerateConnectionID generates a new Connection ID. + // Generated Connection IDs must be unique and observers should not be able to correlate two Connection IDs. GenerateConnectionID() (ConnectionID, error) - // ConnectionIDLen tells what is the length of the ConnectionIDs generated by the implementation of - // this interface. - // Effectively, this means that implementations of ConnectionIDGenerator must always return constant-size - // connection IDs. Valid lengths are between 0 and 20 and calls to GenerateConnectionID. - // 0-length ConnectionsIDs can be used when an endpoint (server or client) does not require multiplexing connections - // in the presence of a connection migration environment. + // ConnectionIDLen returns the length of Connection IDs generated by this implementation. + // Implementations must return constant-length Connection IDs with lengths between 0 and 20 bytes. + // A length of 0 can only be used when an endpoint doesn't need to multiplex connections during migration. ConnectionIDLen() int }