diff --git a/content/docs/http3/datagrams.md b/content/docs/http3/datagrams.md index 1436c12..d8f4d20 100644 --- a/content/docs/http3/datagrams.md +++ b/content/docs/http3/datagrams.md @@ -78,7 +78,7 @@ The `http3.ClientConn` manages a single QUIC connection to a remote server. The client is required to check that the server enabled HTTP datagrams support by checking the SETTINGS: ```go -// ... dial a quic.Connection to the target server +// ... dial a quic.Conn to the target server // make sure to set the "h3" ALPN tr := &http3.Transport{ EnableDatagrams: true, diff --git a/content/docs/quic/client.md b/content/docs/quic/client.md index c1ba80a..cad620c 100644 --- a/content/docs/quic/client.md +++ b/content/docs/quic/client.md @@ -134,7 +134,7 @@ As mentioned above, the client applies the flow control limits used on the initi Upon rejecting 0-RTT, the server discards all 0-RTT packets sent by the client. This results in the invalidation of all opened streams and any data sent. quic-go does not automatically retransmit data sent in 0-RTT after completion of the handshake. It's the application's responsibility to detect this error and respond appropriately. -The `quic.Connection` returned by `DialEarly` behaves as if it had been [closed]({{< relref "connection.md#closing" >}}): all calls to `OpenStream`, `AcceptStream`, as well as `Read` and `Write` calls on streams return a `quic.Err0RTTRejected`. **However, the underlying QUIC connection remains open**, it is only used as a signal to the application that all data sent so far was not processed by the server. To continue communication, the application can transition to using `NextConnection`: +The `quic.Conn` returned by `DialEarly` behaves as if it had been [closed]({{< relref "connection.md#closing" >}}): all calls to `OpenStream`, `AcceptStream`, as well as `Read` and `Write` calls on streams return a `quic.Err0RTTRejected`. **However, the underlying QUIC connection remains open**, it is only used as a signal to the application that all data sent so far was not processed by the server. To continue communication, the application can transition to using `NextConnection`: ```go conn, err := tr.DialEarly(ctx, , , ) diff --git a/content/docs/quic/connection-migration.md b/content/docs/quic/connection-migration.md index e46d044..1eaceed 100644 --- a/content/docs/quic/connection-migration.md +++ b/content/docs/quic/connection-migration.md @@ -39,7 +39,7 @@ tr1 := &quic.Transport{ tr2 := &quic.Transport{ Conn: conn2, // for example: a connection bound to the cellular interface } -var conn quic.Connection // connection established on tr1 +var conn *quic.Conn // connection established on tr1 path, err := conn.AddPath(tr2) // ... error handling diff --git a/content/docs/quic/connection.md b/content/docs/quic/connection.md index e346511..412c2d5 100644 --- a/content/docs/quic/connection.md +++ b/content/docs/quic/connection.md @@ -4,7 +4,7 @@ toc: true weight: 4 --- -The `quic.Connection` is the central object to send and receive application data. Data is not sent directly on the connection, but either on [streams]({{< relref "streams.md" >}}), or (optionally) in so-called [datagrams]({{< relref "datagrams.md" >}}). +The `quic.Conn` is the central object to send and receive application data. Data is not sent directly on the connection, but either on [streams]({{< relref "streams.md" >}}), or (optionally) in so-called [datagrams]({{< relref "datagrams.md" >}}). ## Using the Connection Context {#conn-context} @@ -50,7 +50,7 @@ This allows applications to clean up state that might they might have created in ## Closing a Connection {#closing} -At any point during the connection, a `quic.Connection` can be closed by calling `CloseWithError`: +At any point during the connection, a `quic.Conn` can be closed by calling `CloseWithError`: ```go conn.CloseWithError(0x42, "I don't want to talk to you anymore 🙉") diff --git a/content/docs/quic/datagrams.md b/content/docs/quic/datagrams.md index 5213a5c..ce4f277 100644 --- a/content/docs/quic/datagrams.md +++ b/content/docs/quic/datagrams.md @@ -6,13 +6,13 @@ weight: 10 ## The Unreliable Datagram Extension -Unreliable datagrams are not part of QUIC (RFC 9000) itself, but a feature that is added by a QUIC extension ([RFC 9221](https://datatracker.ietf.org/doc/html/rfc9221)). As other extensions, it can be negotiated during the handshake. Support can be enabled by setting the `quic.Config.EnableDatagram` flag. Note that this doesn't guarantee that the peer also supports datagrams. Whether or not the feature negotiation succeeded can be learned from the `ConnectionState.SupportsDatagrams` obtained from `Connection.ConnectionState()`. +Unreliable datagrams are not part of QUIC (RFC 9000) itself, but a feature that is added by a QUIC extension ([RFC 9221](https://datatracker.ietf.org/doc/html/rfc9221)). As other extensions, it can be negotiated during the handshake. Support can be enabled by setting the `quic.Config.EnableDatagram` flag. Note that this doesn't guarantee that the peer also supports datagrams. Whether or not the feature negotiation succeeded can be learned from the `ConnectionState.SupportsDatagrams` obtained from `Conn.ConnectionState()`. QUIC DATAGRAMs are a new QUIC frame type sent in QUIC 1-RTT packets (i.e. after completion of the handshake). Therefore, they're end-to-end encrypted and congestion-controlled. However, if a DATAGRAM frame is deemed lost by QUIC's loss detection mechanism, they are not retransmitted. ## Sending and Receiving Datagrams -Datagrams are sent using the `SendDatagram` method on the `quic.Connection`: +Datagrams are sent using the `SendDatagram` method on the `quic.Conn`: ```go conn.SendDatagram([]byte("foobar")) diff --git a/content/docs/quic/metrics.md b/content/docs/quic/metrics.md index 5fa6f40..4e47eca 100644 --- a/content/docs/quic/metrics.md +++ b/content/docs/quic/metrics.md @@ -4,7 +4,7 @@ toc: true weight: 91 --- -quic-go can expose metrics via Prometheus, providing a comprehensive overview of its operation. By leveraging the Tracer and ConnectionTracer interfaces, quic-go captures various events. These are the same interfaces used for [qlog event logging]({{< relref "qlog.md" >}}). +quic-go can expose metrics via Prometheus, providing a comprehensive overview of its operation. By leveraging the `Tracer` and `ConnectionTracer` structs, quic-go captures various events. These are the same structs used for [qlog event logging]({{< relref "qlog.md" >}}). ## Enabling Metrics Collection diff --git a/content/docs/quic/server.md b/content/docs/quic/server.md index e88cb55..9d65c87 100644 --- a/content/docs/quic/server.md +++ b/content/docs/quic/server.md @@ -23,7 +23,7 @@ for { } ``` -The listener `ln` can now be used to accept incoming QUIC connections by (repeatedly) calling the `Accept` method (see below for more information on the `quic.Connection`). +The listener `ln` can now be used to accept incoming QUIC connections by (repeatedly) calling the `Accept` method (see below for more information on the `quic.Conn`). This listener can be closed independently from the underlying transport. Connections that are already established and accepted won't be affected, but clients won't be able to establish new connections. @@ -103,7 +103,7 @@ go func() { As soon as the connection is accepted, it can open streams and send application data. If [datagram support]({{< relref "datagrams.md" >}}) is negotiated, datagrams can be sent as well. -At any point, the application can wait for completion of the handshake by blocking on the channel returned by `Connection.HandshakeComplete()`. +At any point, the application can wait for completion of the handshake by blocking on the channel returned by `Conn.HandshakeComplete()`. ## 0-RTT diff --git a/content/docs/quic/streams.md b/content/docs/quic/streams.md index a1fb625..705778d 100644 --- a/content/docs/quic/streams.md +++ b/content/docs/quic/streams.md @@ -4,11 +4,11 @@ toc: true weight: 6 --- -QUIC is a stream-multiplexed transport. A `quic.Connection` fundamentally differs from the `net.Conn` and the `net.PacketConn` interface defined in the standard library. +QUIC is a stream-multiplexed transport. A QUIC connection fundamentally differs from the `net.Conn` and the `net.PacketConn` interface defined in the standard library. -Data is sent and received on (unidirectional and bidirectional) streams, not on the connection itself. The stream state machine is described in detail in [Section 3 of RFC 9000](https://datatracker.ietf.org/doc/html/rfc9000#section-3). +Application data is sent and received on (unidirectional and bidirectional) streams, not on the connection itself. The stream state machine is described in detail in [Section 3 of RFC 9000](https://datatracker.ietf.org/doc/html/rfc9000#section-3). -In addition to QUIC streams, application data can also sent in so-called QUIC datagram frames (see [datagrams]({{< relref path="datagrams.md" >}})), if implementations can negotiate support for it. +In addition to QUIC streams, application data can also be sent in so-called QUIC datagram frames (see [datagrams]({{< relref path="datagrams.md" >}})), if endpoints declare support for it. ## Stream Types @@ -97,7 +97,7 @@ In case the application is no longer interest in receiving data from a `quic.Rec ### Bidirectional Stream -Using QUIC streams is pretty straightforward. A bidirectional stream (`quic.Stream`) implements both these interfaces. Conceptually, a bidirectional stream can be thought of as the composition of two unidirectional streams in opposite directions. +Using QUIC streams is pretty straightforward. Conceptually, a bidirectional stream (`quic.Stream`) can be thought of as the composition of two unidirectional streams in opposite directions. {{< callout type="warning" >}} Calling `Close` on a `quic.Stream` closes the send side of the stream. Note that for bidirectional streams, `Close` _only_ closes the send side of the stream. It is still possible to read from the stream until the peer closes or resets the stream. diff --git a/content/docs/webtransport/session.md b/content/docs/webtransport/session.md index 933ed03..0de0e2d 100644 --- a/content/docs/webtransport/session.md +++ b/content/docs/webtransport/session.md @@ -6,7 +6,7 @@ weight: 3 A WebTransport Session functions similarly to a [QUIC Connection]({{< relref "../quic/connection.md" >}}), enabling the opening and accepting of streams, as well as the sending and receiving of datagrams. -The API of `webtransport.Session` is _almost_ identical to that of `quic.Connection`, with a few minor differences: For example, QUIC allows streams to be reset using a 62-bit error code, whereas WebTransport limits the error code range to 32 bits. +The API of `webtransport.Session` is _almost_ identical to that of `quic.Conn`, with a few minor differences: For example, QUIC allows streams to be reset using a 62-bit error code, whereas WebTransport limits the error code range to 32 bits. ## Closing a WebTransport Session @@ -15,7 +15,7 @@ The WebTransport session can be closed by calling the `CloseWithError` method: sess.CloseWithError(1234, "please stop talking to me 🤐") ``` -Similar to closing a `quic.Connection`, this action causes all calls to `AcceptStream` and `OpenStream`, as well as stream `Read` and `Write` calls, to return immediately. +Similar to closing a `quic.Conn`, this action causes all calls to `AcceptStream` and `OpenStream`, as well as stream `Read` and `Write` calls, to return immediately. {{< callout type="warning" >}} `CloseWithError` only closes the WebTransport session, but not the underlying QUIC connection.