transport

Documentation

Overview

Package transport has the core types to work with transport layer connections.

Connections

Connections enable communication between two endpoints over an abstract transport. There are two types of connections:

• Stream connections, like TCP and the SOCK_STREAM Posix socket type. They are represented by StreamConn objects.
• Datagram connections, like UDP and the SOCK_DGRAM Posix socket type. They are represented by net.Conn objects.

We use "Packet" instead of "Datagram" in the method and type names related to datagrams because that is the convention in the Go standard library.

Each write and read on datagram connections represent a single datagram, while reads and writes on stream connections operate on byte sequences that may be independent of how those bytes are packaged.

Stream connections offer CloseRead and CloseWrite methods, which allows for a half-closed state (like TCP). In general, you communicate end of data ("EOF") to the other side of the connection by calling CloseWrite (TCP will send a FIN). CloseRead doesn't generate packets, but it allows for releasing resources (e.g. a read loop) and to signal errors to the peer if more data does arrive (TCP will usually send a RST).

Connections can be wrapped to create nested connections over a new transport. For example, a StreamConn could be over TCP, over TLS over TCP, over HTTP over TLS over TCP, over QUIC, among other options.

Dialers

Dialers enable the creation of connections given a host:port address while encapsulating the underlying transport or proxy protocol. The StreamDialer and PacketDialer types create stream (StreamConn) and datagram (net.Conn) connections, respectively, given an address.

Dialers can also be nested. For example, a TLS Stream Dialer can use a TCP dialer to create a StreamConn backed by a TCP connection, then create a TLS StreamConn backed by the TCP StreamConn. A SOCKS5-over-TLS Dialer could use the TLS Dialer to create the TLS StreamConn to the proxy before doing the SOCKS5 connection to the target address.

Index

• func MakeNetAddr(network, address string) (net.Addr, error)
• type FuncPacketDialer
  • func (f FuncPacketDialer) DialPacket(ctx context.Context, addr string) (net.Conn, error)
• type FuncPacketEndpoint
  • func (f FuncPacketEndpoint) ConnectPacket(ctx context.Context) (net.Conn, error)
• type FuncStreamDialer
  • func (f FuncStreamDialer) DialStream(ctx context.Context, addr string) (StreamConn, error)
• type FuncStreamEndpoint
  • func (f FuncStreamEndpoint) ConnectStream(ctx context.Context) (StreamConn, error)
• type PacketDialer
• type PacketDialerEndpoint
  • func (e *PacketDialerEndpoint) ConnectPacket(ctx context.Context) (net.Conn, error)
• type PacketEndpoint
• type PacketListener
• type PacketListenerDialer
  • func (e PacketListenerDialer) DialPacket(ctx context.Context, address string) (net.Conn, error)
• type StreamConn
  • func WrapConn(c StreamConn, r io.Reader, w io.Writer) StreamConn
• type StreamDialer
• type StreamDialerEndpoint
  • func (e *StreamDialerEndpoint) ConnectStream(ctx context.Context) (StreamConn, error)
• type StreamEndpoint
• type TCPDialer
  • func (d *TCPDialer) DialStream(ctx context.Context, addr string) (StreamConn, error)
• type TCPEndpoint
  • func (e *TCPEndpoint) ConnectStream(ctx context.Context) (StreamConn, error)
• type UDPDialer
  • func (d *UDPDialer) DialPacket(ctx context.Context, addr string) (net.Conn, error)
• type UDPEndpoint
  • func (e UDPEndpoint) ConnectPacket(ctx context.Context) (net.Conn, error)
• type UDPListener
  • func (l UDPListener) ListenPacket(ctx context.Context) (net.PacketConn, error)

Functions

func MakeNetAddr

func MakeNetAddr(network, address string) (net.Addr, error)

MakeNetAddr returns a net.Addr based on the network and address. This is a helper for code that needs to return or provide a net.Addr. The address must be in "host:port" format with the host being a domain name, IPv4 or IPv6. The network must be "tcp" or "udp". For IP hosts, the returned address will be of type *net.TCPAddr or *net.UDPAddr, based on the network argument. This is important because some of the standard library functions inspect the type of the address and might return an "invalid argument" error if the type is not the correct one.

Types

type FuncPacketDialer

type FuncPacketDialer func(ctx context.Context, addr string) (net.Conn, error)

FuncPacketDialer is a PacketDialer that uses the given function to dial.

func (FuncPacketDialer) DialPacket

func (f FuncPacketDialer) DialPacket(ctx context.Context, addr string) (net.Conn, error)

DialPacket implements the PacketDialer interface.

type FuncPacketEndpoint

type FuncPacketEndpoint func(ctx context.Context) (net.Conn, error)

FuncPacketEndpoint is a PacketEndpoint that uses the given function to connect.

func (FuncPacketEndpoint) ConnectPacket

func (f FuncPacketEndpoint) ConnectPacket(ctx context.Context) (net.Conn, error)

ConnectPacket implements the PacketEndpoint interface.

type FuncStreamDialer

type FuncStreamDialer func(ctx context.Context, addr string) (StreamConn, error)

FuncStreamDialer is a StreamDialer that uses the given function to dial.

func (FuncStreamDialer) DialStream

func (f FuncStreamDialer) DialStream(ctx context.Context, addr string) (StreamConn, error)

DialStream implements the StreamDialer interface.

type FuncStreamEndpoint

type FuncStreamEndpoint func(ctx context.Context) (StreamConn, error)

FuncStreamEndpoint is a StreamEndpoint that uses the given function to connect.

func (FuncStreamEndpoint) ConnectStream

func (f FuncStreamEndpoint) ConnectStream(ctx context.Context) (StreamConn, error)

ConnectStream implements the StreamEndpoint interface.

type PacketDialer

type PacketDialer interface {
	// DialPacket connects to `addr`.
	// `addr` has the form "host:port", where "host" can be a domain name or IP address.
	DialPacket(ctx context.Context, addr string) (net.Conn, error)
}

PacketDialer provides a way to dial a destination and establish datagram connections.

type PacketDialerEndpoint

type PacketDialerEndpoint struct {
	Dialer  PacketDialer
	Address string
}

PacketDialerEndpoint is a PacketEndpoint that connects to the given address using the specified PacketDialer.

func (*PacketDialerEndpoint) ConnectPacket

func (e *PacketDialerEndpoint) ConnectPacket(ctx context.Context) (net.Conn, error)

ConnectPacket implements PacketEndpoint.ConnectPacket.

type PacketEndpoint

type PacketEndpoint interface {
	// ConnectPacket creates a connection bound to an endpoint, returning the connection.
	ConnectPacket(ctx context.Context) (net.Conn, error)
}

PacketEndpoint represents an endpoint that can be used to establish packet connections (like UDP) to a fixed destination.

type PacketListener

type PacketListener interface {
	// ListenPacket creates a PacketConn that can be used to relay packets (such as UDP) through a proxy.
	ListenPacket(ctx context.Context) (net.PacketConn, error)
}

PacketListener provides a way to create a local unbound packet connection to send packets to different destinations.

type PacketListenerDialer

type PacketListenerDialer struct {
	// The PacketListener that is used to create the net.PacketConn to bind on Dial. Must be non nil.
	Listener PacketListener
}

PacketListenerDialer is a PacketDialer that connects to the destination using the specified PacketListener.

func (PacketListenerDialer) DialPacket

func (e PacketListenerDialer) DialPacket(ctx context.Context, address string) (net.Conn, error)

DialPacket implements PacketDialer.DialPacket. The address is in "host:port" format and the host must be either a full IP address (not "[::]") or a domain. The address must be supported by the WriteTo call of the net.PacketConn returned by the PacketListener. For example, a net.UDPConn only supports IP addresses, not domain names. If the host is a domain name, consider pre-resolving it to avoid resolution calls.

type StreamConn

type StreamConn interface {
	net.Conn
	// Closes the Read end of the connection, allowing for the release of resources.
	// No more reads should happen.
	CloseRead() error
	// Closes the Write end of the connection. An EOF or FIN signal can be
	// sent to the connection target.
	CloseWrite() error
}

StreamConn is a net.Conn that allows for closing only the reader or writer end of it, supporting half-open state.

func WrapConn

func WrapConn(c StreamConn, r io.Reader, w io.Writer) StreamConn

WrapConn wraps an existing StreamConn with a new io.Reader and io.Writer, but preserves the original StreamConn.CloseRead and StreamConn.CloseWrite.

type StreamDialer

type StreamDialer interface {
	// DialStream connects to `raddr`.
	// `raddr` has the form "host:port", where "host" can be a domain name or IP address.
	DialStream(ctx context.Context, raddr string) (StreamConn, error)
}

StreamDialer provides a way to dial a destination and establish stream connections.

type StreamDialerEndpoint

type StreamDialerEndpoint struct {
	Dialer  StreamDialer
	Address string
}

StreamDialerEndpoint is a StreamEndpoint that connects to the specified address using the specified StreamDialer.

func (*StreamDialerEndpoint) ConnectStream

func (e *StreamDialerEndpoint) ConnectStream(ctx context.Context) (StreamConn, error)

ConnectStream implements StreamEndpoint.ConnectStream.

type StreamEndpoint

type StreamEndpoint interface {
	// ConnectStream establishes a connection with the endpoint, returning the connection.
	ConnectStream(ctx context.Context) (StreamConn, error)
}

StreamEndpoint represents an endpoint that can be used to establish stream connections (like TCP) to a fixed destination.

type TCPDialer

type TCPDialer struct {
	Dialer net.Dialer
}

TCPDialer is a StreamDialer that uses the standard net.Dialer to dial. It provides a convenient way to use a net.Dialer when you need a StreamDialer.

func (*TCPDialer) DialStream

func (d *TCPDialer) DialStream(ctx context.Context, addr string) (StreamConn, error)

type TCPEndpoint

type TCPEndpoint struct {
	// The Dialer used to create the net.Conn on Connect().
	Dialer net.Dialer
	// The endpoint address (host:port) to pass to Dial.
	// If the host is a domain name, consider pre-resolving it to avoid resolution calls.
	Address string
}

TCPEndpoint is a StreamEndpoint that connects to the specified address using the specified StreamDialer.

func (*TCPEndpoint) ConnectStream

func (e *TCPEndpoint) ConnectStream(ctx context.Context) (StreamConn, error)

ConnectStream implements StreamEndpoint.ConnectStream.

type UDPDialer

type UDPDialer struct {
	Dialer net.Dialer
}

UDPDialer is a PacketDialer that uses the standard net.Dialer to dial. It provides a convenient way to use a net.Dialer when you need a PacketDialer.

func (*UDPDialer) DialPacket

func (d *UDPDialer) DialPacket(ctx context.Context, addr string) (net.Conn, error)

DialPacket implements PacketDialer.DialPacket.

type UDPEndpoint

type UDPEndpoint struct {
	// The Dialer used to create the net.Conn on Connect().
	Dialer net.Dialer
	// The endpoint address ("host:port") to pass to Dial.
	// If the host is a domain name, consider pre-resolving it to avoid resolution calls.
	Address string
}

UDPEndpoint is a PacketEndpoint that connects to the specified address using UDP.

func (UDPEndpoint) ConnectPacket

func (e UDPEndpoint) ConnectPacket(ctx context.Context) (net.Conn, error)

ConnectPacket implements PacketEndpoint.ConnectPacket.

type UDPListener

type UDPListener struct {
	net.ListenConfig
	// The local address to bind to, as specified in [net.ListenPacket].
	Address string
}

UDPListener is a PacketListener that uses the standard net.ListenConfig.ListenPacket to listen.

func (UDPListener) ListenPacket

func (l UDPListener) ListenPacket(ctx context.Context) (net.PacketConn, error)

ListenPacket implements PacketListener.ListenPacket