From e2031b7aeb0985abbffefe7a31ccef3d342bcd6f Mon Sep 17 00:00:00 2001 From: Mark Rushakoff Date: Mon, 14 Apr 2025 01:44:29 -0400 Subject: [PATCH] use clickable links in documentation, fix list styling (#4955) * Update comment styles 1. Use doc links (the square brackets around identifiers) to make clickable links on pkg.go.dev (https://go.dev/doc/comment#doclinks) 2. Indent lists so that they are rendered properly -- at which point go fmt updates the bullet character to a dash (https://go.dev/doc/comment#lists) 3. Add a couple missing punctuation marks These all will improve the experience of browsing the quic-go docs on pkg.go.dev. * ignore SA1019 for the ConnectionTracingID * ci: exclude ConnectionTracing(ID, Key) from staticlint in http3 --------- Co-authored-by: Marten Seemann --- .golangci.yml | 10 +++++++++- client.go | 10 +++++----- config.go | 2 +- interface.go | 35 +++++++++++++++++++---------------- server.go | 20 ++++++++++---------- sys_conn.go | 2 +- transport.go | 8 ++++---- 7 files changed, 49 insertions(+), 38 deletions(-) diff --git a/.golangci.yml b/.golangci.yml index cf30c9d48..9533f0b40 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -46,7 +46,15 @@ linters: - linters: - staticcheck path: _test\.go - text: 'SA1029:' + text: 'SA1029:' # inappropriate key in call to context.WithValue + # WebTransport still relies on the ConnectionTracingID and ConnectionTracingKey. + # See https://github.com/quic-go/quic-go/issues/4405 for more details. + - linters: + - staticcheck + paths: + - http3/ + - integrationtests/self/http_test.go + text: 'SA1019:.+quic\.ConnectionTracing(ID|Key)' paths: - internal/handshake/cipher_suite.go - third_party$ diff --git a/client.go b/client.go index 29a715cc6..26cd83584 100644 --- a/client.go +++ b/client.go @@ -15,7 +15,7 @@ var generateConnectionIDForInitial = protocol.GenerateConnectionIDForInitial // DialAddr establishes a new QUIC connection to a server. // It resolves the address, and then creates a new UDP connection to dial the QUIC server. // When the QUIC connection is closed, this UDP connection is closed. -// See Dial for more details. +// See [Dial] for more details. func DialAddr(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (Connection, error) { udpConn, err := net.ListenUDP("udp", &net.UDPAddr{IP: net.IPv4zero, Port: 0}) if err != nil { @@ -33,7 +33,7 @@ func DialAddr(ctx context.Context, addr string, tlsConf *tls.Config, conf *Confi } // DialAddrEarly establishes a new 0-RTT QUIC connection to a server. -// See DialAddr for more details. +// See [DialAddr] for more details. func DialAddrEarly(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (EarlyConnection, error) { udpConn, err := net.ListenUDP("udp", &net.UDPAddr{IP: net.IPv4zero, Port: 0}) if err != nil { @@ -56,7 +56,7 @@ func DialAddrEarly(ctx context.Context, addr string, tlsConf *tls.Config, conf * } // DialEarly establishes a new 0-RTT QUIC connection to a server using a net.PacketConn. -// See Dial for more details. +// See [Dial] for more details. func DialEarly(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (EarlyConnection, error) { dl, err := setupTransport(c, tlsConf, false) if err != nil { @@ -71,12 +71,12 @@ func DialEarly(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tl } // Dial establishes a new QUIC connection to a server using a net.PacketConn. -// If the PacketConn satisfies the OOBCapablePacketConn interface (as a net.UDPConn does), +// If the PacketConn satisfies the [OOBCapablePacketConn] interface (as a [net.UDPConn] does), // ECN and packet info support will be enabled. In this case, ReadMsgUDP and WriteMsgUDP // will be used instead of ReadFrom and WriteTo to read/write packets. // The tls.Config must define an application protocol (using NextProtos). // -// This is a convenience function. More advanced use cases should instantiate a Transport, +// This is a convenience function. More advanced use cases should instantiate a [Transport], // which offers configuration options for a more fine-grained control of the connection establishment, // including reusing the underlying UDP socket for multiple QUIC connections. func Dial(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error) { diff --git a/config.go b/config.go index d42bdc1c5..540a3240b 100644 --- a/config.go +++ b/config.go @@ -8,7 +8,7 @@ import ( "github.com/quic-go/quic-go/quicvarint" ) -// Clone clones a Config +// Clone clones a Config. func (c *Config) Clone() *Config { copy := *c return © diff --git a/interface.go b/interface.go index 4c006ce0c..343f0142b 100644 --- a/interface.go +++ b/interface.go @@ -44,19 +44,22 @@ type TokenStore interface { } // Err0RTTRejected is the returned from: -// * Open{Uni}Stream{Sync} -// * Accept{Uni}Stream -// * Stream.Read and Stream.Write +// - Open{Uni}Stream{Sync} +// - Accept{Uni}Stream +// - Stream.Read and Stream.Write +// // when the server rejects a 0-RTT connection attempt. var Err0RTTRejected = errors.New("0-RTT rejected") -// ConnectionTracingKey can be used to associate a ConnectionTracer with a Connection. +// ConnectionTracingKey can be used to associate a [logging.ConnectionTracer] with a [Connection]. // It is set on the Connection.Context() context, // as well as on the context passed to logging.Tracer.NewConnectionTracer. +// // Deprecated: Applications can set their own tracing key using Transport.ConnContext. var ConnectionTracingKey = connTracingCtxKey{} // ConnectionTracingID is the type of the context value saved under the ConnectionTracingKey. +// // Deprecated: Applications can set their own tracing key using Transport.ConnContext. type ConnectionTracingID uint64 @@ -66,9 +69,9 @@ type connTracingCtxKey struct{} // context returned by tls.Config.ClientInfo.Context. var QUICVersionContextKey = handshake.QUICVersionContextKey -// Stream is the interface implemented by QUIC streams -// In addition to the errors listed on the Connection, -// calls to stream functions can return a StreamError if the stream is canceled. +// Stream is the interface implemented by QUIC streams. +// In addition to the errors listed on the [Connection], +// calls to stream functions can return a [StreamError] if the stream is canceled. type Stream interface { ReceiveStream SendStream @@ -141,12 +144,12 @@ type SendStream interface { // A Connection is a QUIC connection between two peers. // Calls to the connection (and to streams) can return the following types of errors: -// * ApplicationError: for errors triggered by the application running on top of QUIC -// * TransportError: for errors triggered by the QUIC transport (in many cases a misbehaving peer) -// * IdleTimeoutError: when the peer goes away unexpectedly (this is a net.Error timeout error) -// * HandshakeTimeoutError: when the cryptographic handshake takes too long (this is a net.Error timeout error) -// * StatelessResetError: when we receive a stateless reset -// * VersionNegotiationError: returned by the client, when there's no version overlap between the peers +// - [ApplicationError]: for errors triggered by the application running on top of QUIC +// - [TransportError]: for errors triggered by the QUIC transport (in many cases a misbehaving peer) +// - [IdleTimeoutError]: when the peer goes away unexpectedly (this is a [net.Error] timeout error) +// - [HandshakeTimeoutError]: when the cryptographic handshake takes too long (this is a net.Error timeout error) +// - [StatelessResetError]: when we receive a stateless reset +// - [VersionNegotiationError]: returned by the client, when there's no version overlap between the peers type Connection interface { // AcceptStream returns the next stream opened by the peer, blocking until one is available. // If the connection was closed due to a timeout, the error satisfies @@ -236,7 +239,7 @@ type TokenGeneratorKey = handshake.TokenProtectorKey // as they are allowed by RFC 8999. type ConnectionID = protocol.ConnectionID -// ConnectionIDFromBytes interprets b as a Connection ID. It panics if b is +// ConnectionIDFromBytes interprets b as a [ConnectionID]. It panics if b is // longer than 20 bytes. func ConnectionIDFromBytes(b []byte) ConnectionID { return protocol.ParseConnectionID(b) @@ -354,7 +357,7 @@ type ClientInfo struct { AddrVerified bool } -// ConnectionState records basic details about a QUIC connection +// ConnectionState records basic details about a QUIC connection. type ConnectionState struct { // TLS contains information about the TLS connection state, incl. the tls.ConnectionState. TLS tls.ConnectionState @@ -367,6 +370,6 @@ type ConnectionState struct { Used0RTT bool // Version is the QUIC version of the QUIC connection. Version Version - // GSO says if generic segmentation offload is used + // GSO says if generic segmentation offload is used. GSO bool } diff --git a/server.go b/server.go index c364a37a9..3eb8e1d43 100644 --- a/server.go +++ b/server.go @@ -17,7 +17,7 @@ import ( "github.com/quic-go/quic-go/logging" ) -// ErrServerClosed is returned by the Listener or EarlyListener's Accept method after a call to Close. +// ErrServerClosed is returned by the [Listener] or [EarlyListener]'s Accept method after a call to Close. var ErrServerClosed = errServerClosed{} type errServerClosed struct{} @@ -146,11 +146,11 @@ func (l *Listener) Accept(ctx context.Context) (Connection, error) { } // Close closes the listener. -// Accept will return ErrServerClosed as soon as all connections in the accept queue have been accepted. +// Accept will return [ErrServerClosed] as soon as all connections in the accept queue have been accepted. // QUIC handshakes that are still in flight will be rejected with a CONNECTION_REFUSED error. // The effect of closing the listener depends on how it was created: -// * if it was created using Transport.Listen, already established connections will be unaffected -// * if it was created using the Listen convenience method, all established connection will be closed immediately +// - if it was created using [Transport.Listen], already established connections will be unaffected +// - if it was created using the [Listen] convenience method, all established connection will be closed immediately func (l *Listener) Close() error { return l.baseServer.Close() } @@ -186,7 +186,7 @@ func (l *EarlyListener) Addr() net.Addr { } // ListenAddr creates a QUIC server listening on a given address. -// See Listen for more details. +// See [Listen] for more details. func ListenAddr(addr string, tlsConf *tls.Config, config *Config) (*Listener, error) { conn, err := listenUDP(addr) if err != nil { @@ -199,7 +199,7 @@ func ListenAddr(addr string, tlsConf *tls.Config, config *Config) (*Listener, er }).Listen(tlsConf, config) } -// ListenAddrEarly works like ListenAddr, but it returns connections before the handshake completes. +// ListenAddrEarly works like [ListenAddr], but it returns connections before the handshake completes. func ListenAddrEarly(addr string, tlsConf *tls.Config, config *Config) (*EarlyListener, error) { conn, err := listenUDP(addr) if err != nil { @@ -221,16 +221,16 @@ func listenUDP(addr string) (*net.UDPConn, error) { } // Listen listens for QUIC connections on a given net.PacketConn. -// If the PacketConn satisfies the OOBCapablePacketConn interface (as a net.UDPConn does), +// If the PacketConn satisfies the [OOBCapablePacketConn] interface (as a [net.UDPConn] does), // ECN and packet info support will be enabled. In this case, ReadMsgUDP and WriteMsgUDP // will be used instead of ReadFrom and WriteTo to read/write packets. // A single net.PacketConn can only be used for a single call to Listen. // // The tls.Config must not be nil and must contain a certificate configuration. -// Furthermore, it must define an application control (using NextProtos). +// Furthermore, it must define an application control (using [NextProtos]). // The quic.Config may be nil, in that case the default values will be used. // -// This is a convenience function. More advanced use cases should instantiate a Transport, +// This is a convenience function. More advanced use cases should instantiate a [Transport], // which offers configuration options for a more fine-grained control of the connection establishment, // including reusing the underlying UDP socket for outgoing QUIC connections. // When closing a listener created with Listen, all established QUIC connections will be closed immediately. @@ -239,7 +239,7 @@ func Listen(conn net.PacketConn, tlsConf *tls.Config, config *Config) (*Listener return tr.Listen(tlsConf, config) } -// ListenEarly works like Listen, but it returns connections before the handshake completes. +// ListenEarly works like [Listen], but it returns connections before the handshake completes. func ListenEarly(conn net.PacketConn, tlsConf *tls.Config, config *Config) (*EarlyListener, error) { tr := &Transport{Conn: conn, isSingleUse: true} return tr.ListenEarly(tlsConf, config) diff --git a/sys_conn.go b/sys_conn.go index 6bfa3011d..8159a1469 100644 --- a/sys_conn.go +++ b/sys_conn.go @@ -14,7 +14,7 @@ import ( ) // OOBCapablePacketConn is a connection that allows the reading of ECN bits from the IP header. -// If the PacketConn passed to Dial or Listen satisfies this interface, quic-go will use it. +// If the PacketConn passed to the [Transport] satisfies this interface, quic-go will use it. // In this case, ReadMsgUDP() will be used instead of ReadFrom() to read packets. type OOBCapablePacketConn interface { net.PacketConn diff --git a/transport.go b/transport.go index c6bc4ca8f..a7775fb14 100644 --- a/transport.go +++ b/transport.go @@ -17,7 +17,7 @@ import ( "github.com/quic-go/quic-go/logging" ) -// ErrTransportClosed is returned by the Transport's Listen or Dial method after it was closed. +// ErrTransportClosed is returned by the [Transport]'s Listen or Dial method after it was closed. var ErrTransportClosed = &errTransportClosed{} type errTransportClosed struct { @@ -49,7 +49,7 @@ var errListenerAlreadySet = errors.New("listener already set") // This means that a single UDP socket can be used for listening for incoming connections, as well as // for dialing an arbitrary number of outgoing connections. // A Transport handles a single net.PacketConn, and offers a range of configuration options -// compared to the simple helper functions like Listen and Dial that this package provides. +// compared to the simple helper functions like [Listen] and [Dial] that this package provides. type Transport struct { // A single net.PacketConn can only be handled by one Transport. // Bad things will happen if passed to multiple Transports. @@ -165,7 +165,7 @@ type Transport struct { // Listen starts listening for incoming QUIC connections. // There can only be a single listener on any net.PacketConn. -// Listen may only be called again after the current Listener was closed. +// Listen may only be called again after the current listener was closed. func (t *Transport) Listen(tlsConf *tls.Config, conf *Config) (*Listener, error) { s, err := t.createServer(tlsConf, conf, false) if err != nil { @@ -176,7 +176,7 @@ func (t *Transport) Listen(tlsConf *tls.Config, conf *Config) (*Listener, error) // ListenEarly starts listening for incoming QUIC connections. // There can only be a single listener on any net.PacketConn. -// Listen may only be called again after the current Listener was closed. +// ListenEarly may only be called again after the current listener was closed. func (t *Transport) ListenEarly(tlsConf *tls.Config, conf *Config) (*EarlyListener, error) { s, err := t.createServer(tlsConf, conf, true) if err != nil {