transport

Documentation

Index

• Constants
• Variables
• func BuiltinNetworkName(network Network) (string, bool)
• type Conn
• type Listener
• type Manager
  • func NewManager(defaultNet Network) *Manager
  • func (m *Manager) Close() error
  • func (m *Manager) DefaultNetwork() Network
  • func (m *Manager) Dial(ctx context.Context, u *url.URL) (Conn, error)
  • func (m *Manager) DialWithOptions(ctx context.Context, u *url.URL, opts Options) (Conn, error)
  • func (m *Manager) HasTransport(scheme string) bool
  • func (m *Manager) Listen(ctx context.Context, u *url.URL) (Listener, error)
  • func (m *Manager) ListenWithOptions(ctx context.Context, u *url.URL, opts Options) (Listener, error)
  • func (m *Manager) MapNetwork(pattern string, network Network) error
  • func (m *Manager) NetworkMappings() map[string]Network
  • func (m *Manager) RegisterTransport(t Transport) error
  • func (m *Manager) SetDefaultNetwork(network Network)
  • func (m *Manager) UnmapNetwork(pattern string) error
  • func (m *Manager) UnregisterTransport(scheme string)
• type Network
  • func NewBuiltinNetwork(kind string) (Network, error)
• type Options
• type TCPTransport
  • func NewTCPTransport() *TCPTransport
  • func (t *TCPTransport) Dial(ctx context.Context, network Network, u *url.URL, opts Options) (Conn, error)
  • func (t *TCPTransport) Listen(ctx context.Context, network Network, u *url.URL, opts Options) (Listener, error)
  • func (t *TCPTransport) Schemes() []string
• type TLSTransport
  • func NewTLSTransport(config *tls.Config) *TLSTransport
  • func (t *TLSTransport) Dial(ctx context.Context, network Network, u *url.URL, opts Options) (Conn, error)
  • func (t *TLSTransport) Listen(ctx context.Context, network Network, u *url.URL, opts Options) (Listener, error)
  • func (t *TLSTransport) Schemes() []string
• type Transport

Constants

const (
	NetworkKindNative = "native"
)

Variables

var (
	ErrClosed                     = errors.New("transport manager closed")
	ErrNoNetwork                  = errors.New("transport network unavailable")
	ErrUnsupportedScheme          = errors.New("transport scheme is not registered")
	ErrTransportAlreadyRegistered = errors.New("transport scheme already registered")
	ErrNilTransport               = errors.New("transport is nil")
	ErrInvalidPattern             = errors.New("transport network pattern is invalid")
	ErrSourceInterfaceUnsupported = errors.New("transport source interface is not supported by selected network")
	ErrUnsupportedNetwork         = errors.New("transport network is not supported")
)

Functions

func BuiltinNetworkName

func BuiltinNetworkName(network Network) (string, bool)

Types

type Conn

type Conn = net.Conn

type Listener

type Listener = net.Listener

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager routes Dial and Listen calls to registered transports and selects the gonnect.Network to use from a default network plus optional host-pattern mappings.

Manager is safe for concurrent use. Mapping changes are live: replacing, adding or removing a matching network closes all affected listeners, dialed connections and listener-accepted child connections so no resource survives on the wrong network.

Example:

mgr := transport.NewManager(defaultNet)
if err := mgr.RegisterTransport(transport.NewTCPTransport()); err != nil {
	return err
}
if err := mgr.RegisterTransport(transport.NewTLSTransport(tlsCfg)); err != nil {
	return err
}

u, err := url.Parse("tcp://127.0.0.1:9001")
if err != nil {
	return err
}
conn, err := mgr.Dial(context.Background(), u)
if err != nil {
	return err
}
defer conn.Close()

Example with host-specific network mapping:

mgr := transport.NewManager(defaultNet)
_ = mgr.RegisterTransport(transport.NewTCPTransport())
_ = mgr.MapNetwork("*.onion", torNet)
_ = mgr.MapNetwork("*.i2p", i2pNet)

conn, err := mgr.Dial(context.Background(), mustParseURL("tcp://peer.onion:9001"))

Example with per-call options:

ln, err := mgr.ListenWithOptions(
	context.Background(),
	mustParseURL("tls://[fe80::1]:0?sni=node.example"),
	transport.Options{SourceInterface: "eth0"},
)

func NewManager

func NewManager(defaultNet Network) *Manager

NewManager creates a Manager using defaultNet for hosts that do not match a more specific mapping.

A nil defaultNet is allowed and causes unmatched Dial and Listen calls to be rejected until a non-nil default or explicit matching host mapping is set.

func (*Manager) Close

func (m *Manager) Close() error

func (*Manager) DefaultNetwork

func (m *Manager) DefaultNetwork() Network

func (*Manager) Dial

func (m *Manager) Dial(ctx context.Context, u *url.URL) (Conn, error)

func (*Manager) DialWithOptions

func (m *Manager) DialWithOptions(
	ctx context.Context,
	u *url.URL,
	opts Options,
) (Conn, error)

func (*Manager) HasTransport

func (m *Manager) HasTransport(scheme string) bool

func (*Manager) Listen

func (m *Manager) Listen(ctx context.Context, u *url.URL) (Listener, error)

func (*Manager) ListenWithOptions

func (m *Manager) ListenWithOptions(
	ctx context.Context,
	u *url.URL,
	opts Options,
) (Listener, error)

func (*Manager) MapNetwork

func (m *Manager) MapNetwork(pattern string, network Network) error

func (*Manager) NetworkMappings

func (m *Manager) NetworkMappings() map[string]Network

func (*Manager) RegisterTransport

func (m *Manager) RegisterTransport(t Transport) error

func (*Manager) SetDefaultNetwork

func (m *Manager) SetDefaultNetwork(network Network)

func (*Manager) UnmapNetwork

func (m *Manager) UnmapNetwork(pattern string) error

func (*Manager) UnregisterTransport

func (m *Manager) UnregisterTransport(scheme string)

type Network

type Network = gonnect.Network

func NewBuiltinNetwork

func NewBuiltinNetwork(kind string) (Network, error)

type Options

type Options struct {
	SourceInterface string
}

Options carries per-call transport hints.

Transports should apply only the fields they understand and ignore the rest. The current built-in TCP and TLS transports treat SourceInterface as a best-effort hint: they use it when the selected gonnect.Network and underlying sockets support it and otherwise fall back to the normal dial/listen path.

type TCPTransport

type TCPTransport struct{}

func NewTCPTransport

func NewTCPTransport() *TCPTransport

func (*TCPTransport) Dial

func (t *TCPTransport) Dial(
	ctx context.Context,
	network Network,
	u *url.URL,
	opts Options,
) (Conn, error)

func (*TCPTransport) Listen

func (t *TCPTransport) Listen(
	ctx context.Context,
	network Network,
	u *url.URL,
	opts Options,
) (Listener, error)

func (*TCPTransport) Schemes

func (t *TCPTransport) Schemes() []string

type TLSTransport

type TLSTransport struct {
	Config *tls.Config
}

func NewTLSTransport

func NewTLSTransport(config *tls.Config) *TLSTransport

func (*TLSTransport) Dial

func (t *TLSTransport) Dial(
	ctx context.Context,
	network Network,
	u *url.URL,
	opts Options,
) (Conn, error)

func (*TLSTransport) Listen

func (t *TLSTransport) Listen(
	ctx context.Context,
	network Network,
	u *url.URL,
	opts Options,
) (Listener, error)

func (*TLSTransport) Schemes

func (t *TLSTransport) Schemes() []string

type Transport

type Transport interface {
	Schemes() []string
	Dial(ctx context.Context, network Network, u *url.URL, opts Options) (Conn, error)
	Listen(
		ctx context.Context,
		network Network,
		u *url.URL,
		opts Options,
	) (Listener, error)
}

Transport creates or accepts carrier connections for one or more URL schemes.

Implementations receive the selected gonnect.Network, the original URL and per-call Options. They should ignore URL fields or options they do not use.