Documentation
¶
Overview ¶
Package quicconn provides a net.PacketConn adapter for feeding QUIC stacks (such as quic-go) with datagrams originating from a generic net.Conn.
Typical usage is tunneling QUIC over a UDP-capable proxy (e.g. a SOCKS5 UDP associate). Some proxy clients expose the UDP relay as a stream-like net.Conn. QUIC, however, requires a net.PacketConn. This package bridges the gap by wrapping that net.Conn and implementing net.PacketConn on top.
Two encapsulation modes are supported:
- EncapRaw — pass raw UDP payloads through; the dialer / proxy stack is assumed to take care of any required encapsulation.
- EncapSocks5 — add / remove RFC 1928 UDP ASSOCIATE headers on the fly, so you can drive a UDP relay directly using a plain net.Conn.
The adapter also exposes optional SetReadBuffer / SetWriteBuffer methods. quic-go detects these via type assertions and will attempt to tune socket buffers when available. If the underlying connection doesn't support them, these methods no-op and return nil. See: https://github.com/quic-go/quic-go/wiki/UDP-Buffer-Sizes
Index ¶
- Variables
- type EncapMode
- type QuicPacketConn
- func (q *QuicPacketConn) Close() error
- func (q *QuicPacketConn) LocalAddr() net.Addr
- func (q *QuicPacketConn) ReadFrom(p []byte) (int, net.Addr, error)
- func (q *QuicPacketConn) SetDeadline(t time.Time) error
- func (q *QuicPacketConn) SetReadBuffer(n int) error
- func (q *QuicPacketConn) SetReadDeadline(t time.Time) error
- func (q *QuicPacketConn) SetWriteBuffer(n int) error
- func (q *QuicPacketConn) SetWriteDeadline(t time.Time) error
- func (q *QuicPacketConn) WriteTo(p []byte, addr net.Addr) (int, error)
Constants ¶
This section is empty.
Variables ¶
var ErrDefaultTargetRequired = errors.New("defaultTarget required for QUIC/UDP")
ErrDefaultTargetRequired is returned when a destination address is needed but neither an explicit addr nor defaultTarget are provided.
Functions ¶
This section is empty.
Types ¶
type EncapMode ¶ added in v1.0.110
type EncapMode int
EncapMode describes how UDP datagrams are encapsulated over the underlying net.Conn transport.
const ( // EncapRaw forwards raw datagrams as-is. Use this when the component that // created the underlying net.Conn already handles UDP encapsulation (e.g., // a SOCKS5 client that returns a UDP-capable net.Conn). EncapRaw EncapMode = iota // EncapSocks5 wraps outgoing datagrams in RFC 1928 UDP ASSOCIATE headers and // strips those headers on receive. Use this when you talk to a SOCKS5 UDP // relay over a plain net.Conn and need to perform the encapsulation yourself. EncapSocks5 )
type QuicPacketConn ¶
type QuicPacketConn struct {
// contains filtered or unexported fields
}
QuicPacketConn adapts a stream-like net.Conn into a packet-oriented net.PacketConn suitable for QUIC. When mode is EncapSocks5, it performs RFC 1928 UDP encapsulation/decapsulation on the fly.
The defaultTarget is used as the destination for WriteTo when addr is nil, and as a fallback source address in ReadFrom when the relay doesn't expose a peer address.
func New ¶
New creates a new QuicPacketConn adapter around a connected transport.
Parameters:
- conn: a connected transport (e.g., a UDP-capable proxy connection).
- defaultTarget: default peer address used when WriteTo is called with addr == nil, and used as a fallback source address in ReadFrom when the relay does not supply one.
- mode: encapsulation mode (EncapRaw or EncapSocks5).
Default target requirements:
- EncapRaw: defaultTarget MUST be non-nil. If it is nil, New panics. In raw mode the adapter cannot infer a UDP peer address from a generic net.Conn.
- EncapSocks5: defaultTarget may be nil because the SOCKS5 UDP header carries the peer address. Providing a non-nil defaultTarget is still recommended as a fallback for relays that might strip the header.
The returned value implements net.PacketConn and can be passed to QUIC dialers (e.g., quic-go's quic.Dial).
func (*QuicPacketConn) Close ¶
func (q *QuicPacketConn) Close() error
Close closes the underlying connection.
func (*QuicPacketConn) LocalAddr ¶
func (q *QuicPacketConn) LocalAddr() net.Addr
LocalAddr reports the local network address. It delegates to the underlying connection.
func (*QuicPacketConn) ReadFrom ¶
ReadFrom reads a single datagram into p and returns the number of bytes, the source address, and any error encountered. In EncapSocks5 mode, it removes the RFC 1928 header and returns the payload with decoded source address. If no header is present, the packet is treated as raw.
func (*QuicPacketConn) SetDeadline ¶
func (q *QuicPacketConn) SetDeadline(t time.Time) error
SetDeadline sets both read and write deadlines on the underlying connection.
func (*QuicPacketConn) SetReadBuffer ¶
func (q *QuicPacketConn) SetReadBuffer(n int) error
SetReadBuffer optionally sets the receive buffer size if the underlying connection exposes such an option (e.g., *net.UDPConn or any type with SetReadBuffer(int) error). If unsupported, this method is a no-op and returns nil. quic-go probes for this method via type assertion.
func (*QuicPacketConn) SetReadDeadline ¶
func (q *QuicPacketConn) SetReadDeadline(t time.Time) error
SetReadDeadline sets the read deadline on the underlying connection.
func (*QuicPacketConn) SetWriteBuffer ¶
func (q *QuicPacketConn) SetWriteBuffer(n int) error
SetWriteBuffer optionally sets the send buffer size if the underlying connection exposes such an option (e.g., *net.UDPConn or any type with SetWriteBuffer(int) error). If unsupported, this method is a no-op and returns nil. quic-go probes for this method via type assertion.
func (*QuicPacketConn) SetWriteDeadline ¶
func (q *QuicPacketConn) SetWriteDeadline(t time.Time) error
SetWriteDeadline sets the write deadline on the underlying connection.
Source Files