ApplicationErrorCode is an QUIC application error code.
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). Enable QUIC Stream Resets with Partial Delivery.
See https://datatracker.ietf.org/doc/html/draft-ietf-quic-reliable-stream-reset-07. 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. InitialMaxPathID enables the QUIC multipath extension
(draft-ietf-quic-multipath) by advertising the initial_max_path_id
transport parameter with the given value (the largest path id this
endpoint is initially willing to use). A nil pointer leaves multipath
disabled, and the parameter is not sent. Multipath is only negotiated when
both peers advertise the parameter. 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. InitialRTT is the RTT estimate used before receiving the first RTT sample.
If this value is zero, the estimate is set to 100 milliseconds. 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. MaxRemoteNATTraversalAddresses enables n0 QUIC NAT traversal (QNT) by
advertising the n0_nat_traversal transport parameter with the maximum
number of remote NAT-traversal addresses this endpoint will accept. A nil
pointer leaves QNT disabled, and the parameter is not sent. QNT is only
negotiated when both peers advertise a non-zero 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. ReceiveObservedAddressReports enables receiving QUIC Address Discovery
OBSERVED_ADDRESS frames: this endpoint accepts the peer's reports of its
own reflexive address and records the latest (highest seq_no). Mirrors
noq's TransportConfig::receive_observed_address_reports
(config/transport.rs:383). Together these two flags determine the
address-discovery role advertised in the observed_address transport
parameter; address discovery is negotiated only when each side's role
permits the corresponding direction (address_discovery.rs should_report). SendObservedAddressReports enables sending QUIC Address Discovery
OBSERVED_ADDRESS frames (draft-seemann-quic-address-discovery): on each
1-RTT packet received from the peer this endpoint reports the peer's source
address back to it. Mirrors noq's
TransportConfig::send_observed_address_reports (config/transport.rs:372). 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(ctx context.Context, isClient bool, connID ConnectionID) qlogwriter.Trace The QUIC versions that can be negotiated.
If not set, it uses all versions available. Clone clones a Config.
func (*Config).Clone() *Config
func Dial(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (*Conn, error)
func DialAddr(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (*Conn, error)
func DialAddrEarly(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (*Conn, error)
func DialEarly(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (*Conn, 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) (*Conn, error)
func (*Transport).DialEarly(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (*Conn, error)
func (*Transport).Listen(tlsConf *tls.Config, conf *Config) (*Listener, error)
func (*Transport).ListenEarly(tlsConf *tls.Config, conf *Config) (*EarlyListener, error)
func github.com/tmc/go-iroh/internal/netreport.(*Client).WithQUICConfig(cfg *Config) *netreport.Client
A Conn 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. AddNATTraversalAddress adds a local QNT candidate address.(*Conn) AddPath(t *Transport) (*Path, error) AddRemoteNATTraversalAddress adds a remote QNT candidate learned from an
authenticated address source outside the peer's ADD_ADDRESS frames, such as a
dialed endpoint ticket. AwaitObservedAddr returns the reflexive address the peer reported via the
QUIC Address Discovery OBSERVED_ADDRESS extension, waiting for the first
report if none has arrived yet (reports are sent after the handshake, so an
immediate read misses). Returns ok=false without waiting when address
discovery was not negotiated to receive reports, and when ctx ends or the
connection closes first. CloseWithError closes the connection with an error.
The error string will be sent to the peer. ConnectionState returns basic details about the QUIC connection.(*Conn) ConnectionStats() ConnectionStats 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. 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. InitiateNATTraversalRound starts one client-side QNT round. qng queues
REACH_OUT frames, owns NAT probe retry scheduling, matches PATH_RESPONSE
frames, and opens validated four-tuples as multipath paths. The returned
addresses are informational; qng, not socket, owns probing. LastPathAckID returns the PathID carried by the most recently received
PATH_ACK / PATH_ACK_ECN frame and whether any such frame has been received.
It lets a test confirm an acknowledgement arrived for a specific non-zero
path. It is safe to call from any goroutine. LocalAddr returns the local address of the QUIC connection. MaxDatagramSize returns the largest payload currently accepted by
SendDatagram. The size may change as the path MTU estimate changes. NATTraversalAddresses returns the remote ADD_ADDRESS set known to qng. NATTraversalRemoteAddrsReady returns a channel closed once this connection
first knows a remote NAT traversal candidate (peer ADD_ADDRESS frame or
[Conn.AddRemoteNATTraversalAddress]) — the earliest moment a QNT round can
start. It never closes when no candidate ever arrives, e.g. on the server
side of QNT, which receives no ADD_ADDRESS. NextConnection transitions a connection to be usable after a 0-RTT rejection.
It waits for the handshake to complete and then enables the connection for normal use.
This should be called when the server rejects 0-RTT and the application receives
[Err0RTTRejected] errors.
Note that 0-RTT rejection invalidates all data sent in 0-RTT packets. It is the
application's responsibility to handle this (for example by resending the data). ObservedAddr returns the most recent reflexive address the peer reported via
the QUIC Address Discovery OBSERVED_ADDRESS extension and whether one has been
received. It returns ok=false when address discovery was not negotiated to
receive reports, or when no report has arrived yet. OpenPath opens a second QUIC multipath path (draft-ietf-quic-multipath) over
the connection's existing socket, distinguished from PathIDZero by its own
connection IDs rather than its 4-tuple. It is the draft-multipath path-open,
NOT the RFC 9000 single-path migration AddPath: both paths stay alive.
OpenPath requires multipath to have been negotiated and the handshake to be
confirmed (PATH_NEW_CONNECTION_ID / PATH_CHALLENGE are 1-RTT-only). It hands
the request to the run goroutine, which provisions the per-path send/recv
state, issues a path connection ID, and begins the PATH_CHALLENGE validation.
The returned MultipathPath.Validated blocks until the path is usable.
tr is accepted for API parity with AddPath and future multi-socket paths; in
this build the second path shares the connection's socket (the peer demuxes
by connection ID), so tr may be nil. 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. PathAcksReceived returns the number of PATH_ACK / PATH_ACK_ECN frames this
connection has received for its non-zero multipath paths. It is safe to call
from any goroutine and is used to confirm a second path's packets were
acknowledged (driving that path's bytes-in-flight down). PathStats returns the live application-data recovery snapshot for the
multipath PathID pid (its own number space + congestion controller). It is a
test-support hook: the query runs on the connection's run goroutine — the
only goroutine permitted to read the lock-free sentPacketHandler — so it is
race-free. ok is false if pid is not an open path or the connection closed. Paths returns a snapshot of this connection's non-zero qng multipath paths.
The query runs on the connection's run goroutine because the path-open state
is owned there. It returns nil if no non-zero path has been opened or the
connection is closed. PerformanceStats returns zero counters in an ordinary build. QlogTrace returns the qlog trace of the QUIC connection.
It is nil if qlog is not enabled. ReceiveDatagram gets a message received in a QUIC datagram, as specified in RFC 9221. RemoteAddr returns the remote address of the QUIC connection. RemoteAddrValidated reports whether the peer's transport address was
validated by a QUIC address-validation token before this connection was
accepted. It is only meaningful on server-side early connections. RemoveNATTraversalAddress removes a local QNT candidate address. SendDatagram sends a message using a QUIC datagram, as specified in RFC 9221,
if the peer enabled datagram support.
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. SendDatagramOnPath queues a DATAGRAM to be sent over the multipath PathID pid.
It is the thread-safe entry point both the OpenPath initiator
(MultipathPath.SendDatagram) and the lazily-joined peer use to put data on a
non-zero path: it only touches pathDatagramQueue (a channel), never the
run-goroutine-owned multipathOut, so it is safe to call from any goroutine.
The run loop drops the datagram if pid is not an open path. SetMigrationFallbackRemote records a fallback remote for QNT active
migration. It is used when the connection was established directly but the
caller also knows a relay route for the peer.
func Dial(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (*Conn, error)
func DialAddr(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (*Conn, error)
func DialAddrEarly(ctx context.Context, addr string, tlsConf *tls.Config, conf *Config) (*Conn, error)
func DialEarly(ctx context.Context, c net.PacketConn, addr net.Addr, tlsConf *tls.Config, conf *Config) (*Conn, error)
func (*Conn).NextConnection(ctx context.Context) (*Conn, error)
func (*EarlyListener).Accept(ctx context.Context) (*Conn, error)
func (*Listener).Accept(ctx context.Context) (*Conn, error)
func (*Transport).Dial(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (*Conn, error)
func (*Transport).DialEarly(ctx context.Context, addr net.Addr, tlsConf *tls.Config, conf *Config) (*Conn, 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/tmc/go-iroh/internal/qng/internal/protocol.DefaultConnectionIDGenerator
ConnectionState records basic details about a QUIC connection. GSO says if generic segmentation offload is used. MultipathNegotiated reports whether both peers advertised the QUIC
multipath extension. SupportsDatagrams indicates support for QUIC datagrams (RFC 9221). SupportsStreamResetPartialDelivery indicates support for QUIC Stream Resets with Partial Delivery. 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 (*Conn).ConnectionState() ConnectionState
ConnectionStats contains statistics about the QUIC connection BytesLost is the number of bytes lost on the underlying connection (does
not monotonically increase, because packets that are declared lost can
subsequently be received). Does not include UDP or any other outer
framing. BytesReceived is the number of total bytes received on the underlying
connection, including duplicate data for streams. Does not include UDP or
any other outer framing. BytesSent is the number of bytes sent on the underlying connection,
including retransmissions. Does not include UDP or any other outer
framing. LatestRTT is the last RTT sample observed on the active network path. MeanDeviation estimates the variation in the RTT samples using a mean
variation. See https://www.rfc-editor.org/rfc/rfc9002#section-5.3 MinRTT is the estimate of the minimum RTT observed on the active network
path. PacketsLost is the number of packets lost on the underlying connection
(does not monotonically increase, because packets that are declared lost
can subsequently be received). PacketsReceived is the number of total packets received on the underlying
connection, including packets that were not processable. PacketsSent is the number of packets sent on the underlying connection,
including those that are determined to have been lost. SmoothedRTT is an exponentially weighted moving average of an endpoint's
RTT samples. See https://www.rfc-editor.org/rfc/rfc9002#section-5.3
func (*Conn).ConnectionStats() ConnectionStats
DatagramTooLargeError is returned from Conn.SendDatagram if the payload is too large to be sent.MaxDatagramPayloadSizeint64(*DatagramTooLargeError) Error() string(*DatagramTooLargeError) Is(target error) bool
*DatagramTooLargeError : 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 closes the listener.
Accept will return [ErrServerClosed] as soon as all connections in the accept queue have been accepted.
Early connections that are still in flight will be rejected with a CONNECTION_REFUSED error.
Already established (accepted) connections will be unaffected.
*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)
HandshakeTimeoutError indicates that the connection timed out before completing the handshake.
IdleTimeoutError indicates that the connection timed out because it was inactive for too long.
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/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)
MultipathPath is the application handle to a non-zero multipath PathID. It is
returned by Conn.OpenPath. Validated blocks until the path completes its
PATH_CHALLENGE/PATH_RESPONSE validation, at which point 1-RTT packets
(including application data) are scheduled over it by the run loop. PathID returns the draft-multipath PathID of this path. SendDatagram queues a DATAGRAM to be sent specifically over this multipath
path. The datagram is delivered to the peer's ordinary datagram receive queue
(DATAGRAM frames are not path-scoped on the wire), but it is guaranteed to
ride a 1-RTT packet addressed to this path's connection ID and drawn from this
path's packet-number space — which is what makes it observable as "data over
PathID n". Validated blocks until the path has been validated (a PATH_RESPONSE to our
PATH_CHALLENGE arrived) or ctx is done / the connection closed.
func (*Conn).OpenPath(tr *Transport) (*MultipathPath, error)
NATTraversalCandidate is a local address the application believes is worth
advertising to the peer for n0 QUIC NAT traversal. qng owns address-family
canonicalization before any address is put on the wire.Addrnetip.AddrPort
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.
github.com/quic-go/quic-go.OOBCapablePacketConn(interface)
*net.UDPConn
OOBCapablePacketConn : github.com/pion/datachannel.ReadDeadliner
OOBCapablePacketConn : github.com/pion/datachannel.WriteDeadliner
OOBCapablePacketConn : github.com/prometheus/common/expfmt.Closer
OOBCapablePacketConn : github.com/quic-go/quic-go.OOBCapablePacketConn
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 (*Conn).AddPath(t *Transport) (*Path, error)
PathInfo is a snapshot of one qng multipath path's application-facing state.
Path 0 is the initial path and is not listed here. The entries returned by
[Conn.Paths] are real qng non-zero paths provisioned by OpenPath or by a peer
packet that caused lazy path join. RemoteAddr is set only when qng has an
address that actually routes the path, currently for QNT-opened paths. BytesInFlight is the path's current application-data bytes in flight,
when HasBytesInFlight is true. BytesReceived is the cumulative 1-RTT/0-RTT application-data packet
bytes received on this path, when HasBytesReceived is true. It excludes
Initial/Handshake packets and UDP framing overhead. BytesSent is the cumulative 1-RTT/0-RTT application-data packet
bytes sent on this path, when HasBytesSent is true. It excludes
Initial/Handshake packets and UDP framing overhead. CongestionWindow is the path's current congestion window, when
HasCongestionWindow is true. HasBytesInFlight reports whether BytesInFlight was observed for this path. HasBytesReceived reports whether BytesReceived was observed for this path. HasBytesSent reports whether BytesSent was observed for this path. HasCongestionWindow reports whether CongestionWindow was observed for this
path. HasLoss reports whether LostPackets and LostBytes were observed for this
path. HasRTT reports whether SmoothedRTT was observed for this path. ID is the QUIC multipath PathID. LostBytes is the number of application-data bytes declared lost on this
path, when HasLoss is true. LostPackets is the number of application-data packets declared lost on
this path, when HasLoss is true. RemoteAddr is the remote UDP route for this path, when known. SmoothedRTT is the path's application-data RTT estimate, when HasRTT is
true. Validated reports whether the path completed PATH_CHALLENGE /
PATH_RESPONSE validation and can carry non-probing application data.
func (*Conn).Paths() []PathInfo
A ReceiveStream is a unidirectional Receive Stream. CancelRead aborts receiving on this stream.
It instructs 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. Peek fills b with stream data, without consuming the stream data.
It blocks until len(b) bytes are available, or an error occurs.
It respects the stream deadline set by SetReadDeadline.
If the stream ends before len(b) bytes are available,
it returns the number of bytes peeked along with io.EOF. Read reads data from the stream.
Read can be made to time out using [ReceiveStream.SetReadDeadline].
If the stream was canceled, the error is a [StreamError]. 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.
*ReceiveStream : github.com/tmc/go-iroh/internal/qng/quicvarint.Peeker
*ReceiveStream : github.com/pion/datachannel.ReadDeadliner
*ReceiveStream : github.com/quic-go/quic-go/quicvarint.Peeker
*ReceiveStream : io.Reader
func (*Conn).AcceptUniStream(ctx 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 reliable delivery of outstanding stream data.
Note that there is no guarantee if the peer will receive the FIN or the cancellation error first. Close closes the write-direction of the stream.
Future calls to Write are not permitted after calling Close.
It must not be called concurrently with Write.
It must not be called after calling CancelWrite. 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. ReadFrom implements [io.ReaderFrom]. It reads from r until EOF or error,
writing to the stream in buffer-sized chunks so each write stays on the
buffered fast path. Data is copied into stream-owned storage before each
chunk write returns. SetReliableBoundary marks the data written to this stream so far as reliable.
It is valid to call this function multiple times, thereby increasing the reliable size.
It only has an effect if the peer enabled support for the RESET_STREAM_AT extension,
otherwise, it is a no-op. 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. Write writes data to the stream.
Write can be made to time out using [SendStream.SetWriteDeadline].
If the stream was canceled, the error is a [StreamError]. Writev writes the buffers in order, amortizing the per-call lock and
bookkeeping across the vector. It returns the total number of bytes
written and advances bufs to reflect exactly what was consumed,
including a partially written element, so the caller can resume after a
short write. The stream copies data into owned storage before Writev
returns; the caller may reuse the underlying slices immediately.
Writev does not hold the stream for the whole vector. Elements too large
for the write buffer are delegated to Write, and another writer may
interleave between elements. The delivered byte stream is identical to
the equivalent sequence of Write calls.
To send a [net.Buffers], call Writev directly: [net.Buffers] implements
[io.WriterTo], which [io.Copy] prefers over [io.ReaderFrom], so
io.Copy(stream, &bufs) degrades to one Write call per element and never
batches.
For burst accounting, a Writev counts as one write for the group of
elements appended to the write buffer plus one per delegated element, so
a vector of mixed sizes is not accounted the same as either one Write or
N Writes.
Writev is intended to be no slower than the equivalent sequence of Write
calls; whether it is faster depends on the batch depth and on how many
elements exceed the write buffer.
*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.ReaderFrom
*SendStream : io.WriteCloser
*SendStream : io.Writer
func (*Conn).OpenUniStream() (*SendStream, error)
func (*Conn).OpenUniStreamSync(ctx context.Context) (*SendStream, error)
StatelessResetError indicates a stateless reset was received.
This can happen when the peer reboots, or when packets are misrouted.
See section 10.3 of RFC 9000 for details.
StatelessResetKey is a key used to derive stateless reset tokens.
CancelRead aborts receiving on this stream.
See [ReceiveStream.CancelRead] for more details. CancelWrite aborts sending on this stream.
See [SendStream.CancelWrite] for more details. Close closes the send-direction of the stream.
It does not close the receive-direction of the stream. The Context is canceled as soon as the write-side of the stream is closed.
See [SendStream.Context] for more details. Peek fills b with stream data, without consuming the stream data.
It blocks until len(b) bytes are available, or an error occurs.
It respects the stream deadline set by SetReadDeadline.
If the stream ends before len(b) bytes are available,
it returns the number of bytes peeked along with io.EOF. Read reads data from the stream.
Read can be made to time out using [Stream.SetReadDeadline] and [Stream.SetDeadline].
If the stream was canceled, the error is a [StreamError]. ReadFrom implements [io.ReaderFrom]. See [SendStream.ReadFrom]. SetDeadline sets the read and write deadlines associated with the stream.
It is equivalent to calling both SetReadDeadline and SetWriteDeadline. SetReadDeadline sets the deadline for future Read calls.
See [ReceiveStream.SetReadDeadline] for more details. SetReliableBoundary marks the data written to this stream so far as reliable.
It is valid to call this function multiple times, thereby increasing the reliable size.
It only has an effect if the peer enabled support for the RESET_STREAM_AT extension,
otherwise, it is a no-op. SetWriteDeadline sets the deadline for future Write calls.
See [SendStream.SetWriteDeadline] for more details. StreamID returns the stream ID. Write writes data to the stream.
Write can be made to time out using [Stream.SetWriteDeadline] or [Stream.SetDeadline].
If the stream was canceled, the error is a [StreamError]. Writev writes the buffers in order as one write episode.
See [SendStream.Writev].
*Stream : github.com/tmc/go-iroh/internal/qng/quicvarint.Peeker
*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 : github.com/quic-go/quic-go/quicvarint.Peeker
*Stream : internal/bisect.Writer
*Stream : io.Closer
*Stream : io.ReadCloser
*Stream : io.Reader
*Stream : io.ReaderFrom
*Stream : io.ReadWriteCloser
*Stream : io.ReadWriter
*Stream : io.WriteCloser
*Stream : io.Writer
func (*Conn).AcceptStream(ctx context.Context) (*Stream, error)
func (*Conn).OpenStream() (*Stream, error)
func (*Conn).OpenStreamSync(ctx context.Context) (*Stream, error)
StreamErrorCode is a QUIC stream error code. The meaning of the value is defined by the application.
The StreamID is the ID of a QUIC stream.
StreamLimitReachedError is returned from Conn.OpenStream and Conn.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.QlogTrace
* the context returned from Conn.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.
Recorder.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.
It abruptly terminates all existing connections, without sending a CONNECTION_CLOSE
to the peers. It is the application's responsibility to cleanly terminate existing
connections prior to calling Close.
If a server was started, it will be closed as well.
It is not possible to start any new server or dial new 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 (*Conn).AddPath(t *Transport) (*Path, error)
func (*Conn).OpenPath(tr *Transport) (*MultipathPath, error)
TransportError indicates an error that occurred on the QUIC transport layer.
Every transport error other than CONNECTION_REFUSED and APPLICATION_ERROR is
likely a bug in the implementation.
TransportErrorCode is a QUIC transport error code, see section 20 of RFC 9000.
A Version is a QUIC version number.
VersionNegotiationError indicates a failure to negotiate a QUIC version.
Package-Level Functions (total 11)
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 tls.Config.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.
SupportedVersions returns the support versions, sorted in descending order of preference.
Package-Level Variables (total 10)
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.
ErrNATTraversalNotEnoughAddresses is returned when QNT is negotiated but a
traversal round cannot start because either the local candidate set or the
peer's ADD_ADDRESS set is empty.
ErrNATTraversalNotNegotiated is returned by n0 QUIC NAT traversal operations
when the n0_nat_traversal extension has not been negotiated.
ErrNATTraversalTooManyAddresses is returned when a QNT address set is full.
ErrPathClosed is returned when trying to switch to a path that has been closed.
ErrPathLimit is returned by OpenPath when the peer has not yet advertised a
large enough MAX_PATH_ID, or when the requested path would exceed the local
limit. The condition can be transient immediately after handshake completion,
while the peer's MAX_PATH_ID frame is still in flight.
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.
Package-Level Constants (total 19)
AEADLimitReached is the AEAD_LIMIT_REACHED transport error code.
ApplicationErrorErrorCode is the APPLICATION_ERROR transport error code.
ConnectionIDLimitError is the CONNECTION_ID_LIMIT_ERROR transport error code.
ConnectionRefused is the CONNECTION_REFUSED transport error code.
CryptoBufferExceeded is the CRYPTO_BUFFER_EXCEEDED transport error code.
FinalSizeError is the FINAL_SIZE_ERROR transport error code.
FlowControlError is the FLOW_CONTROL_ERROR transport error code.
FrameEncodingError is the FRAME_ENCODING_ERROR transport error code.
InternalError is the INTERNAL_ERROR transport error code.
InvalidToken is the INVALID_TOKEN transport error code.
KeyUpdateError is the KEY_UPDATE_ERROR transport error code.
NoError is the NO_ERROR transport error code.
NoViablePathError is the NO_VIABLE_PATH_ERROR transport error code.
ProtocolViolation is the PROTOCOL_VIOLATION transport error code.
StreamLimitError is the STREAM_LIMIT_ERROR transport error code.
StreamStateError is the STREAM_STATE_ERROR transport error code.
TransportParameterError is the TRANSPORT_PARAMETER_ERROR transport error code.
Version1 is RFC 9000
Version2 is RFC 9369
The pages are generated with Goldsv0.8.4. (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.
