ClientHelloInfo contains information about an incoming connection attempt.
Deprecated: Use ClientInfo instead.
ClientInfo contains information about an incoming connection attempt. AddrVerified says if the remote address was verified using QUIC's Retry mechanism.
Note that the Retry mechanism costs one network roundtrip,
and is not performed unless Transport.MaxUnvalidatedHandshakes is surpassed. RemoteAddr is the remote address on the Initial packet.
Unless AddrVerified is set, the address is not yet verified, and could be a spoofed IP address.
A ClientToken is a token received by the client.
It can be used to skip address validation on future connection attempts.
func TokenStore.Pop(key string) (token *ClientToken)
func TokenStore.Put(key string, token *ClientToken)
Config contains all configuration data needed for a QUIC server or client. Allow0RTT allows the application to decide if a 0-RTT connection attempt should be accepted.
Only valid for the server. AllowConnectionWindowIncrease is called every time the connection flow controller attempts
to increase the connection flow control window.
If set, the caller can prevent an increase of the window. Typically, it would do so to
limit the memory usage.
To avoid deadlocks, it is not valid to call other functions on the connection or on streams
in this callback. DisablePathMTUDiscovery disables Path MTU Discovery (RFC 8899).
This allows the sending of QUIC packets that fully utilize the available MTU of the path.
Path MTU discovery is only available on systems that allow setting of the Don't Fragment (DF) bit. Enable QUIC datagram support (RFC 9221). GetConfigForClient is called for incoming connections.
If the error is not nil, the connection attempt is refused. HandshakeIdleTimeout is the idle timeout before completion of the handshake.
If we don't receive any packet from the peer within this time, the connection attempt is aborted.
Additionally, if the handshake doesn't complete in twice this time, the connection attempt is also aborted.
If this value is zero, the timeout is set to 5 seconds. InitialConnectionReceiveWindow is the initial size of the stream-level flow control window for receiving data.
If the application is consuming data quickly enough, the flow control auto-tuning algorithm
will increase the window up to MaxConnectionReceiveWindow.
If this value is zero, it will default to 512 KB.
Values larger than the maximum varint (quicvarint.Max) will be clipped to that value. InitialPacketSize is the initial size (and the lower limit) for packets sent.
Under most circumstances, it is not necessary to manually set this value,
since path MTU discovery quickly finds the path's MTU.
If set too high, the path might not support packets of that size, leading to a timeout of the QUIC handshake.
Values below 1200 are invalid. InitialStreamReceiveWindow is the initial size of the stream-level flow control window for receiving data.
If the application is consuming data quickly enough, the flow control auto-tuning algorithm
will increase the window up to MaxStreamReceiveWindow.
If this value is zero, it will default to 512 KB.
Values larger than the maximum varint (quicvarint.Max) will be clipped to that value. KeepAlivePeriod defines whether this peer will periodically send a packet to keep the connection alive.
If set to 0, then no keep alive is sent. Otherwise, the keep alive is sent on that period (or at most
every half of MaxIdleTimeout, whichever is smaller). MaxConnectionReceiveWindow is the connection-level flow control window for receiving data.
If this value is zero, it will default to 15 MB.
Values larger than the maximum varint (quicvarint.Max) will be clipped to that value. MaxIdleTimeout is the maximum duration that may pass without any incoming network activity.
The actual value for the idle timeout is the minimum of this value and the peer's.
This value only applies after the handshake has completed.
If the timeout is exceeded, the connection is closed.
If this value is zero, the timeout is set to 30 seconds. MaxIncomingStreams is the maximum number of concurrent bidirectional streams that a peer is allowed to open.
If not set, it will default to 100.
If set to a negative value, it doesn't allow any bidirectional streams.
Values larger than 2^60 will be clipped to that value. MaxIncomingUniStreams is the maximum number of concurrent unidirectional streams that a peer is allowed to open.
If not set, it will default to 100.
If set to a negative value, it doesn't allow any unidirectional streams.
Values larger than 2^60 will be clipped to that value. MaxStreamReceiveWindow is the maximum stream-level flow control window for receiving data.
If this value is zero, it will default to 6 MB.
Values larger than the maximum varint (quicvarint.Max) will be clipped to that value. The TokenStore stores tokens received from the server.
Tokens are used to skip address validation on future connection attempts.
The key used to store tokens is the ServerName from the tls.Config, if set
otherwise the token is associated with the server's IP address.Tracerfunc(context.Context, logging.Perspective, ConnectionID) *logging.ConnectionTracer The QUIC versions that can be negotiated.
If not set, it uses all versions available. Clone clones a Config.
func (*Config).Clone() *Config
func github.com/libp2p/go-libp2p/p2p/transport/quicreuse.(*ConnManager).ClientConfig() *Config
func Dial(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error)
func DialAddr(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (Connection, error)
func DialAddrEarly(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (EarlyConnection, error)
func DialEarly(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (EarlyConnection, error)
func Listen(conn net.PacketConn, tlsConf *tls.Config, config *Config) (*Listener, error)
func ListenAddr(addr string, tlsConf *tls.Config, config *Config) (*Listener, error)
func ListenAddrEarly(addr string, tlsConf *tls.Config, config *Config) (*EarlyListener, error)
func ListenEarly(conn net.PacketConn, tlsConf *tls.Config, config *Config) (*EarlyListener, error)
func (*Transport).Dial(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error)
func (*Transport).DialEarly(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (EarlyConnection, error)
func (*Transport).Listen(tlsConf *tls.Config, conf *Config) (*Listener, error)
func (*Transport).ListenEarly(tlsConf *tls.Config, conf *Config) (*EarlyListener, error)
func github.com/libp2p/go-libp2p/p2p/transport/quicreuse.QUICTransport.Dial(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error)
func github.com/libp2p/go-libp2p/p2p/transport/quicreuse.QUICTransport.Listen(tlsConf *tls.Config, conf *Config) (quicreuse.QUICListener, error)
func github.com/libp2p/go-libp2p/p2p/transport/quicreuse.RefCountedQUICTransport.Dial(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error)
func github.com/libp2p/go-libp2p/p2p/transport/quicreuse.RefCountedQUICTransport.Listen(tlsConf *tls.Config, conf *Config) (quicreuse.QUICListener, error)
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 AcceptStream returns the next stream opened by the peer, blocking until one is available. AcceptUniStream returns the next unidirectional stream opened by the peer, blocking until one is available.( Connection) AddPath(*Transport) (*Path, error) CloseWithError closes the connection with an error.
The error string will be sent to the peer. ConnectionState returns basic details about the QUIC connection.
Warning: This API should not be considered stable and might change soon. Context returns a context that is cancelled when the connection is closed.
The cancellation cause is set to the error that caused the connection to
close, or `context.Canceled` in case the listener is closed first. LocalAddr returns the local address. OpenStream opens a new bidirectional QUIC stream.
There is no signaling to the peer about new streams:
The peer can only accept the stream after data has been sent on the stream,
or the stream has been reset or closed.
When reaching the peer's stream limit, it is not possible to open a new stream until the
peer raises the stream limit. In that case, a StreamLimitReachedError is returned. OpenStreamSync opens a new bidirectional QUIC stream.
It blocks until a new stream can be opened.
There is no signaling to the peer about new streams:
The peer can only accept the stream after data has been sent on the stream,
or the stream has been reset or closed. OpenUniStream opens a new outgoing unidirectional QUIC stream.
There is no signaling to the peer about new streams:
The peer can only accept the stream after data has been sent on the stream,
or the stream has been reset or closed.
When reaching the peer's stream limit, it is not possible to open a new stream until the
peer raises the stream limit. In that case, a StreamLimitReachedError is returned. OpenUniStreamSync opens a new outgoing unidirectional QUIC stream.
It blocks until a new stream can be opened.
There is no signaling to the peer about new streams:
The peer can only accept the stream after data has been sent on the stream,
or the stream has been reset or closed. ReceiveDatagram gets a message received in a datagram, as specified in RFC 9221. RemoteAddr returns the address of the peer. SendDatagram sends a message using a QUIC datagram, as specified in RFC 9221.
There is no delivery guarantee for DATAGRAM frames, they are not retransmitted if lost.
The payload of the datagram needs to fit into a single QUIC packet.
In addition, a datagram may be dropped before being sent out if the available packet size suddenly decreases.
If the payload is too large to be sent at the current time, a DatagramTooLargeError is returned.EarlyConnection(interface)
*github.com/quic-go/quic-go/http3.ClientConn
func Dial(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error)
func DialAddr(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (Connection, error)
func EarlyConnection.NextConnection(context.Context) (Connection, error)
func (*Listener).Accept(ctx context.Context) (Connection, error)
func (*Transport).Dial(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error)
func github.com/libp2p/go-libp2p/p2p/transport/quicreuse.(*ConnManager).DialQUIC(ctx context.Context, raddr ma.Multiaddr, tlsConf *tls.Config, allowWindowIncrease func(conn Connection, delta uint64) bool) (Connection, error)
func github.com/libp2p/go-libp2p/p2p/transport/quicreuse.Listener.Accept(context.Context) (Connection, error)
func github.com/libp2p/go-libp2p/p2p/transport/quicreuse.QUICListener.Accept(ctx context.Context) (Connection, error)
func github.com/libp2p/go-libp2p/p2p/transport/quicreuse.QUICTransport.Dial(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error)
func github.com/libp2p/go-libp2p/p2p/transport/quicreuse.RefCountedQUICTransport.Dial(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (Connection, error)
func github.com/quic-go/quic-go/http3.(*Server).ServeQUICConn(conn Connection) error
func github.com/quic-go/quic-go/http3.(*Transport).NewClientConn(conn Connection) *http3.ClientConn
func github.com/quic-go/webtransport-go.(*Server).ServeQUICConn(conn Connection) error
A ConnectionID is a QUIC Connection ID, as defined in RFC 9000.
It is not able to handle QUIC Connection IDs longer than 20 bytes,
as they are allowed by RFC 8999.
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. 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. GenerateConnectionID generates a new Connection ID.
Generated Connection IDs must be unique and observers should not be able to correlate two Connection IDs.
*github.com/quic-go/quic-go/internal/protocol.DefaultConnectionIDGenerator
ConnectionState records basic details about a QUIC connection. GSO says if generic segmentation offload is used. SupportsDatagrams indicates whether the peer advertised support for QUIC datagrams (RFC 9221).
When true, datagrams can be sent using the Connection's SendDatagram method.
This is a unilateral declaration by the peer - receiving datagrams is only possible if
datagram support was enabled locally via Config.EnableDatagrams. TLS contains information about the TLS connection state, incl. the tls.ConnectionState. Used0RTT says if 0-RTT resumption was used. Version is the QUIC version of the QUIC connection.
func Connection.ConnectionState() ConnectionState
func EarlyConnection.ConnectionState() ConnectionState
func github.com/quic-go/quic-go/http3.Connection.ConnectionState() ConnectionState
func github.com/quic-go/webtransport-go.(*Session).ConnectionState() ConnectionState
ConnectionTracingID is the type of the context value saved under the ConnectionTracingKey.
Deprecated: Applications can set their own tracing key using Transport.ConnContext.
DatagramTooLargeError is returned from Connection.SendDatagram if the payload is too large to be sent.MaxDatagramPayloadSizeint64(*DatagramTooLargeError) Error() string(*DatagramTooLargeError) Is(target error) bool
*DatagramTooLargeError : error
An EarlyConnection is a connection that is handshaking.
Data sent during the handshake is encrypted using the forward secure keys.
When using client certificates, the client's identity is only verified
after completion of the handshake. AcceptStream returns the next stream opened by the peer, blocking until one is available. AcceptUniStream returns the next unidirectional stream opened by the peer, blocking until one is available.( EarlyConnection) AddPath(*Transport) (*Path, error) CloseWithError closes the connection with an error.
The error string will be sent to the peer. ConnectionState returns basic details about the QUIC connection.
Warning: This API should not be considered stable and might change soon. Context returns a context that is cancelled when the connection is closed.
The cancellation cause is set to the error that caused the connection to
close, or `context.Canceled` in case the listener is closed first. HandshakeComplete blocks until the handshake completes (or fails).
For the client, data sent before completion of the handshake is encrypted with 0-RTT keys.
For the server, data sent before completion of the handshake is encrypted with 1-RTT keys,
however the client's identity is only verified once the handshake completes. LocalAddr returns the local address.( EarlyConnection) NextConnection(context.Context) (Connection, error) OpenStream opens a new bidirectional QUIC stream.
There is no signaling to the peer about new streams:
The peer can only accept the stream after data has been sent on the stream,
or the stream has been reset or closed.
When reaching the peer's stream limit, it is not possible to open a new stream until the
peer raises the stream limit. In that case, a StreamLimitReachedError is returned. OpenStreamSync opens a new bidirectional QUIC stream.
It blocks until a new stream can be opened.
There is no signaling to the peer about new streams:
The peer can only accept the stream after data has been sent on the stream,
or the stream has been reset or closed. OpenUniStream opens a new outgoing unidirectional QUIC stream.
There is no signaling to the peer about new streams:
The peer can only accept the stream after data has been sent on the stream,
or the stream has been reset or closed.
When reaching the peer's stream limit, it is not possible to open a new stream until the
peer raises the stream limit. In that case, a StreamLimitReachedError is returned. OpenUniStreamSync opens a new outgoing unidirectional QUIC stream.
It blocks until a new stream can be opened.
There is no signaling to the peer about new streams:
The peer can only accept the stream after data has been sent on the stream,
or the stream has been reset or closed. ReceiveDatagram gets a message received in a datagram, as specified in RFC 9221. RemoteAddr returns the address of the peer. SendDatagram sends a message using a QUIC datagram, as specified in RFC 9221.
There is no delivery guarantee for DATAGRAM frames, they are not retransmitted if lost.
The payload of the datagram needs to fit into a single QUIC packet.
In addition, a datagram may be dropped before being sent out if the available packet size suddenly decreases.
If the payload is too large to be sent at the current time, a DatagramTooLargeError is returned.
EarlyConnection : Connection
func DialAddrEarly(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (EarlyConnection, error)
func DialEarly(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (EarlyConnection, error)
func (*EarlyListener).Accept(ctx context.Context) (EarlyConnection, error)
func (*Transport).DialEarly(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (EarlyConnection, error)
func github.com/quic-go/quic-go/http3.QUICEarlyListener.Accept(context.Context) (EarlyConnection, error)
An EarlyListener listens for incoming QUIC connections, and returns them before the handshake completes.
For connections that don't use 0-RTT, this allows the server to send 0.5-RTT data.
This data is encrypted with forward-secure keys, however, the client's identity has not yet been verified.
For connection using 0-RTT, this allows the server to accept and respond to streams that the client opened in the
0-RTT data it sent. Note that at this point during the handshake, the live-ness of the
client has not yet been confirmed, and the 0-RTT data could have been replayed by an attacker. Accept returns a new connections. It should be called in a loop. Addr returns the local network addr that the server is listening on. Close the server. All active connections will be closed.
*EarlyListener : github.com/quic-go/quic-go/http3.QUICEarlyListener
*EarlyListener : github.com/prometheus/common/expfmt.Closer
*EarlyListener : io.Closer
func ListenAddrEarly(addr string, tlsConf *tls.Config, config *Config) (*EarlyListener, error)
func ListenEarly(conn net.PacketConn, tlsConf *tls.Config, config *Config) (*EarlyListener, error)
func (*Transport).ListenEarly(tlsConf *tls.Config, conf *Config) (*EarlyListener, error)
A Listener listens for incoming QUIC connections.
It returns connections once the handshake has completed. Accept returns new connections. It should be called in a loop. Addr returns the local network address that the server is listening on. Close closes the listener.
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.
Already established (accepted)connections will be unaffected.
*Listener : github.com/libp2p/go-libp2p/p2p/transport/quicreuse.QUICListener
*Listener : github.com/prometheus/common/expfmt.Closer
*Listener : io.Closer
func Listen(conn net.PacketConn, tlsConf *tls.Config, config *Config) (*Listener, error)
func ListenAddr(addr string, tlsConf *tls.Config, config *Config) (*Listener, error)
func (*Transport).Listen(tlsConf *tls.Config, conf *Config) (*Listener, error)
OOBCapablePacketConn is a connection that allows the reading of ECN bits from the IP header.
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. Close closes the connection.
Any blocked ReadFrom or WriteTo operations will be unblocked and return errors. LocalAddr returns the local network address, if known. ReadFrom reads a packet from the connection,
copying the payload into p. It returns the number of
bytes copied into p and the return address that
was on the packet.
It returns the number of bytes read (0 <= n <= len(p))
and any error encountered. Callers should always process
the n > 0 bytes returned before considering the error err.
ReadFrom can be made to time out and return an error after a
fixed time limit; see SetDeadline and SetReadDeadline.( OOBCapablePacketConn) ReadMsgUDP(b, oob []byte) (n, oobn, flags int, addr *net.UDPAddr, err error) SetDeadline sets the read and write deadlines associated
with the connection. It is equivalent to calling both
SetReadDeadline and SetWriteDeadline.
A deadline is an absolute time after which I/O operations
fail instead of blocking. The deadline applies to all future
and pending I/O, not just the immediately following call to
Read or Write. After a deadline has been exceeded, the
connection can be refreshed by setting a deadline in the future.
If the deadline is exceeded a call to Read or Write or to other
I/O methods will return an error that wraps os.ErrDeadlineExceeded.
This can be tested using errors.Is(err, os.ErrDeadlineExceeded).
The error's Timeout method will return true, but note that there
are other possible errors for which the Timeout method will
return true even if the deadline has not been exceeded.
An idle timeout can be implemented by repeatedly extending
the deadline after successful ReadFrom or WriteTo calls.
A zero value for t means I/O operations will not time out.( OOBCapablePacketConn) SetReadBuffer(int) error SetReadDeadline sets the deadline for future ReadFrom calls
and any currently-blocked ReadFrom call.
A zero value for t means ReadFrom will not time out. SetWriteDeadline sets the deadline for future WriteTo calls
and any currently-blocked WriteTo call.
Even if write times out, it may return n > 0, indicating that
some of the data was successfully written.
A zero value for t means WriteTo will not time out.( OOBCapablePacketConn) SyscallConn() (syscall.RawConn, error)( OOBCapablePacketConn) WriteMsgUDP(b, oob []byte, addr *net.UDPAddr) (n, oobn int, err error) WriteTo writes a packet with payload p to addr.
WriteTo can be made to time out and return an Error after a
fixed time limit; see SetDeadline and SetWriteDeadline.
On packet-oriented connections, write timeouts are rare.
*net.UDPConn
OOBCapablePacketConn : github.com/pion/datachannel.ReadDeadliner
OOBCapablePacketConn : github.com/pion/datachannel.WriteDeadliner
OOBCapablePacketConn : github.com/prometheus/common/expfmt.Closer
OOBCapablePacketConn : io.Closer
OOBCapablePacketConn : net.PacketConn
OOBCapablePacketConn : syscall.Conn
Path is a network path. Close abandons a path.
It is not possible to close the path that’s currently active.
After closing, it is not possible to probe this path again.(*Path) Probe(ctx context.Context) error Switch switches the QUIC connection to this path.
It immediately stops sending on the old path, and sends on this new path.
*Path : github.com/prometheus/common/expfmt.Closer
*Path : io.Closer
func Connection.AddPath(*Transport) (*Path, error)
func EarlyConnection.AddPath(*Transport) (*Path, error)
A ReceiveStream is a unidirectional Receive Stream. CancelRead aborts receiving on this stream.
It will ask the peer to stop transmitting stream data.
Read will unblock immediately, and future Read calls will fail.
When called multiple times or after reading the io.EOF it is a no-op.( ReceiveStream) Read(p []byte) (n int, err error) SetReadDeadline sets the deadline for future Read calls and
any currently-blocked Read call.
A zero value for t means Read will not time out. StreamID returns the stream ID.Stream(interface)
github.com/quic-go/quic-go/http3.RequestStream(interface)
github.com/quic-go/quic-go/http3.Stream(interface)
ReceiveStream : github.com/pion/datachannel.ReadDeadliner
ReceiveStream : io.Reader
func Connection.AcceptUniStream(context.Context) (ReceiveStream, error)
func EarlyConnection.AcceptUniStream(context.Context) (ReceiveStream, error)
A SendStream is a unidirectional Send Stream. CancelWrite aborts sending on this stream.
Data already written, but not yet delivered to the peer is not guaranteed to be delivered reliably.
Write will unblock immediately, and future calls to Write will fail.
When called multiple times it is a no-op.
When called after Close, it aborts delivery. Note that there is no guarantee if
the peer will receive the FIN or the reset first.( SendStream) Close() error The Context is canceled as soon as the write-side of the stream is closed.
This happens when Close() or CancelWrite() is called, or when the peer
cancels the read-side of their stream.
The cancellation cause is set to the error that caused the stream to
close, or `context.Canceled` in case the stream is closed without error. SetWriteDeadline sets the deadline for future Write calls
and any currently-blocked Write call.
Even if write times out, it may return n > 0, indicating that
some data was successfully written.
A zero value for t means Write will not time out. StreamID returns the stream ID.( SendStream) Write([]byte) (int, error)Stream(interface)
github.com/quic-go/quic-go/http3.RequestStream(interface)
github.com/quic-go/quic-go/http3.Stream(interface)
SendStream : github.com/miekg/dns.Writer
SendStream : github.com/pion/datachannel.WriteDeadliner
SendStream : github.com/prometheus/common/expfmt.Closer
SendStream : internal/bisect.Writer
SendStream : io.Closer
SendStream : io.WriteCloser
SendStream : io.Writer
func Connection.OpenUniStream() (SendStream, error)
func Connection.OpenUniStreamSync(context.Context) (SendStream, error)
func EarlyConnection.OpenUniStream() (SendStream, error)
func EarlyConnection.OpenUniStreamSync(context.Context) (SendStream, error)
func github.com/quic-go/quic-go/http3.Connection.OpenUniStream() (SendStream, error)
func github.com/quic-go/quic-go/http3.Connection.OpenUniStreamSync(context.Context) (SendStream, error)
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. CancelRead aborts receiving on this stream.
It will ask the peer to stop transmitting stream data.
Read will unblock immediately, and future Read calls will fail.
When called multiple times or after reading the io.EOF it is a no-op. CancelWrite aborts sending on this stream.
Data already written, but not yet delivered to the peer is not guaranteed to be delivered reliably.
Write will unblock immediately, and future calls to Write will fail.
When called multiple times it is a no-op.
When called after Close, it aborts delivery. Note that there is no guarantee if
the peer will receive the FIN or the reset first.( Stream) Close() error The Context is canceled as soon as the write-side of the stream is closed.
This happens when Close() or CancelWrite() is called, or when the peer
cancels the read-side of their stream.
The cancellation cause is set to the error that caused the stream to
close, or `context.Canceled` in case the stream is closed without error.( Stream) Read(p []byte) (n int, err error) SetDeadline sets the read and write deadlines associated
with the connection. It is equivalent to calling both
SetReadDeadline and SetWriteDeadline. SetReadDeadline sets the deadline for future Read calls and
any currently-blocked Read call.
A zero value for t means Read will not time out. SetWriteDeadline sets the deadline for future Write calls
and any currently-blocked Write call.
Even if write times out, it may return n > 0, indicating that
some data was successfully written.
A zero value for t means Write will not time out. StreamID returns the stream ID.( Stream) Write([]byte) (int, error)
github.com/quic-go/quic-go/http3.RequestStream(interface)
github.com/quic-go/quic-go/http3.Stream(interface)
Stream : ReceiveStream
Stream : SendStream
Stream : github.com/miekg/dns.Writer
Stream : github.com/pion/datachannel.ReadDeadliner
Stream : github.com/pion/datachannel.WriteDeadliner
Stream : github.com/pion/stun.Connection
Stream : github.com/pion/stun/v3.Connection
Stream : github.com/prometheus/common/expfmt.Closer
Stream : internal/bisect.Writer
Stream : io.Closer
Stream : io.ReadCloser
Stream : io.Reader
Stream : io.ReadWriteCloser
Stream : io.ReadWriter
Stream : io.WriteCloser
Stream : io.Writer
func Connection.AcceptStream(context.Context) (Stream, error)
func Connection.OpenStream() (Stream, error)
func Connection.OpenStreamSync(context.Context) (Stream, error)
func EarlyConnection.AcceptStream(context.Context) (Stream, error)
func EarlyConnection.OpenStream() (Stream, error)
func EarlyConnection.OpenStreamSync(context.Context) (Stream, error)
func github.com/quic-go/quic-go/http3.Connection.OpenStream() (Stream, error)
func github.com/quic-go/quic-go/http3.Connection.OpenStreamSync(context.Context) (Stream, error)
StreamLimitReachedError is returned from Connection.OpenStream and Connection.OpenUniStream
when it is not possible to open a new stream because the number of opens streams reached
the peer's stream limit.( StreamLimitReachedError) Error() string
StreamLimitReachedError : error
TokenGeneratorKey is a key used to encrypt session resumption tokens.
Pop searches for a ClientToken associated with the given key.
Since tokens are not supposed to be reused, it must remove the token from the cache.
It returns nil when no token is found. Put adds a token to the cache with the given key. It might get called
multiple times in a connection.
func NewLRUTokenStore(maxOrigins, tokensPerOrigin int) TokenStore
The Transport is the central point to manage incoming and outgoing QUIC connections.
QUIC demultiplexes connections based on their QUIC Connection IDs, not based on the 4-tuple.
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. A single net.PacketConn can only be handled by one Transport.
Bad things will happen if passed to multiple Transports.
A number of optimizations will be enabled if the connections implements the OOBCapablePacketConn interface,
as a *net.UDPConn does.
1. It enables the Don't Fragment (DF) bit on the IP header.
This is required to run DPLPMTUD (Path MTU Discovery, RFC 8899).
2. It enables reading of the ECN bits from the IP header.
This allows the remote node to speed up its loss detection and recovery.
3. It uses batched syscalls (recvmmsg) to more efficiently receive packets from the socket.
4. It uses Generic Segmentation Offload (GSO) to efficiently send batches of packets (on Linux).
After passing the connection to the Transport, it's invalid to call ReadFrom or WriteTo on the connection. ConnContext is called when the server accepts a new connection. To reject a connection return
a non-nil error.
The context is closed when the connection is closed, or when the handshake fails for any reason.
The context returned from the callback is used to derive every other context used during the
lifetime of the connection:
* the context passed to crypto/tls (and used on the tls.ClientHelloInfo)
* the context used in Config.Tracer
* the context returned from Connection.Context
* the context returned from SendStream.Context
It is not used for dialed connections. Use for generating new connection IDs.
This allows the application to control of the connection IDs used,
which allows routing / load balancing based on connection IDs.
All Connection IDs returned by the ConnectionIDGenerator MUST
have the same length. The length of the connection ID in bytes.
It can be any value between 1 and 20.
Due to the increased risk of collisions, it is not recommended to use connection IDs shorter than 4 bytes.
If unset, a 4 byte connection ID will be used. DisableVersionNegotiationPackets disables the sending of Version Negotiation packets.
This can be useful if version information is exchanged out-of-band.
It has no effect for clients. MaxTokenAge is the maximum age of the resumption token presented during the handshake.
These tokens allow skipping address resumption when resuming a QUIC connection,
and are especially useful when using 0-RTT.
If not set, it defaults to 24 hours.
See section 8.1.3 of RFC 9000 for details. The StatelessResetKey is used to generate stateless reset tokens.
If no key is configured, sending of stateless resets is disabled.
It is highly recommended to configure a stateless reset key, as stateless resets
allow the peer to quickly recover from crashes and reboots of this node.
See section 10.3 of RFC 9000 for details. The TokenGeneratorKey is used to encrypt session resumption tokens.
If no key is configured, a random key will be generated.
If multiple servers are authoritative for the same domain, they should use the same key,
see section 8.1.3 of RFC 9000 for details. A Tracer traces events that don't belong to a single QUIC connection.
Tracer.Close is called when the transport is closed. VerifySourceAddress decides if a connection attempt originating from unvalidated source
addresses first needs to go through source address validation using QUIC's Retry mechanism,
as described in RFC 9000 section 8.1.2.
Note that the address passed to this callback is unvalidated, and might be spoofed in case
of an attack.
Validating the source address adds one additional network roundtrip to the handshake,
and should therefore only be used if a suspiciously high number of incoming connection is recorded.
For most use cases, wrapping the Allow function of a rate.Limiter will be a reasonable
implementation of this callback (negating its return value). Close stops listening for UDP datagrams on the Transport.Conn.
If any listener was started, it will be closed as well.
It is invalid to start new listeners or connections after that. Dial dials a new connection to a remote host (not using 0-RTT). DialEarly dials a new connection, attempting to use 0-RTT if possible. 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. ListenEarly starts listening for incoming QUIC connections.
There can only be a single listener on any net.PacketConn.
ListenEarly may only be called again after the current listener was closed. ReadNonQUICPacket reads non-QUIC packets received on the underlying connection.
The detection logic is very simple: Any packet that has the first and second bit of the packet set to 0.
Note that this is stricter than the detection logic defined in RFC 9443. WriteTo sends a packet on the underlying connection.
*Transport : github.com/prometheus/common/expfmt.Closer
*Transport : io.Closer
func Connection.AddPath(*Transport) (*Path, error)
func EarlyConnection.AddPath(*Transport) (*Path, error)
ConnectionIDFromBytes interprets b as a [ConnectionID]. It panics if b is
longer than 20 bytes.
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),
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],
which offers configuration options for a more fine-grained control of the connection establishment,
including reusing the underlying UDP socket for multiple QUIC connections.
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.
DialAddrEarly establishes a new 0-RTT QUIC connection to a server.
See [DialAddr] for more details.
DialEarly establishes a new 0-RTT QUIC connection to a server using a net.PacketConn.
See [Dial] for more details.
Listen listens for QUIC connections on a given net.PacketConn.
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]).
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],
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.
ListenAddr creates a QUIC server listening on a given address.
See [Listen] for more details.
ListenAddrEarly works like [ListenAddr], but it returns connections before the handshake completes.
ListenEarly works like [Listen], but it returns connections before the handshake completes.
NewLRUTokenStore creates a new LRU cache for tokens received by the client.
maxOrigins specifies how many origins this cache is saving tokens for.
tokensPerOrigin specifies the maximum number of tokens per origin.
Package-Level Variables (total 7)
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.
Err0RTTRejected is the returned from:
- Open{Uni}Stream{Sync}
- Accept{Uni}Stream
- Stream.Read and Stream.Write
when the server rejects a 0-RTT connection attempt.
ErrPathClosed is returned when trying to switch to a path that has been closed.
ErrPathNotValidated is returned when trying to use a path before path probing has completed.
ErrServerClosed is returned by the [Listener] or [EarlyListener]'s Accept method after a call to Close.
ErrTransportClosed is returned by the [Transport]'s Listen or Dial method after it was closed.
QUICVersionContextKey can be used to find out the QUIC version of a TLS handshake from the
context returned by tls.Config.ClientInfo.Context.
The pages are generated with Goldsv0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
