npp

Documentation

Index

• func DialContext(ctx context.Context, network, laddr, raddr string) (net.Conn, error)
• type Config
• type Dialer
  • func NewDialer(ctx context.Context, options ...Option) (*Dialer, error)
  • func (m *Dialer) Close() error
  • func (m *Dialer) Dial(addr auth.Addr) (net.Conn, error)
  • func (m *Dialer) DialContext(ctx context.Context, addr auth.Addr) (net.Conn, error)
• type Listener
  • func NewListener(ctx context.Context, addr string, options ...Option) (*Listener, error)
  • func (m *Listener) Accept() (net.Conn, error)
  • func (m *Listener) Addr() net.Addr
  • func (m *Listener) Close() error
  • func (m *Listener) Metrics() ListenerMetrics
• type ListenerMetrics
• type NATPuncher
• type Option
  • func WithLogger(log *zap.Logger) Option
  • func WithNPPBacklog(backlog int) Option
  • func WithNPPBackoff(min, max time.Duration) Option
  • func WithRelayDialer(dialer *relay.Dialer) Option
  • func WithRelayListener(listener *relay.Listener) Option
  • func WithRendezvous(cfg rendezvous.Config, credentials credentials.TransportCredentials) Option
• type Port

Functions

func DialContext

func DialContext(ctx context.Context, network, laddr, raddr string) (net.Conn, error)

DialContext allows to dial the remote peer with SO_REUSEPORT and SO_REUSEADDR options configured.

Types

type Config

type Config struct {
	Rendezvous         rendezvous.Config `yaml:"rendezvous"`
	Relay              relay.Config      `yaml:"relay"`
	Backlog            int               `yaml:"backlog" default:"128"`
	MinBackoffInterval time.Duration     `yaml:"min_backoff_interval" default:"500ms"`
	MaxBackoffInterval time.Duration     `yaml:"max_backoff_interval" default:"8000ms"`
}

type Dialer

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

Dialer represents an NPP dialer.

This structure acts like an usual dialer with an exception that the address must be an authenticated endpoint and the connection establishment process is done via NAT Punching Protocol.

func NewDialer

func NewDialer(ctx context.Context, options ...Option) (*Dialer, error)

NewDialer constructs a new dialer that is aware of NAT Punching Protocol.

func (*Dialer) Close

func (m *Dialer) Close() error

Close closes the dialer.

Any blocked operations will be unblocked and return errors.

func (*Dialer) Dial

func (m *Dialer) Dial(addr auth.Addr) (net.Conn, error)

Dial dials the given verified address using NPP.

func (*Dialer) DialContext

func (m *Dialer) DialContext(ctx context.Context, addr auth.Addr) (net.Conn, error)

DialContext connects to the given verified address using NPP and the provided context.

The provided Context must be non-nil. If the context expires before the connection is complete, an error is returned. Once successfully connected, any expiration of the context will not affect the connection.

type Listener

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

Listener specifies a net.Listener wrapper that is aware of NAT Punching Protocol and can switch to it when it's required to establish a connection.

Options are: rendezvous server, private IPs usage, relay server(s) if any.

func NewListener

func NewListener(ctx context.Context, addr string, options ...Option) (*Listener, error)

NewListener constructs a new NPP listener that will listen the specified network address with TCP protocol, switching to the NPP when there is no pending connections available.

func (*Listener) Accept

func (m *Listener) Accept() (net.Conn, error)

Accept waits for and returns the next connection to the listener.

This method will firstly check whether there are pending sockets in the listener, returning immediately if so. Then an attempt to communicate with the Rendezvous server occurs by publishing server's ID to check if there are someone wanted to connect with us. Simultaneously additional sockets are constructed after resolution to make punching mechanism work. This can consume a meaningful amount of file descriptors, so be prepared to enlarge your limits.

func (*Listener) Addr

func (m *Listener) Addr() net.Addr

func (*Listener) Close

func (m *Listener) Close() error

func (*Listener) Metrics

func (m *Listener) Metrics() ListenerMetrics

type ListenerMetrics

type ListenerMetrics struct {
	RendezvousAddr       net.Addr
	NumConnectionsDirect uint64
	NumConnectionsNAT    uint64
	NumConnectionsRelay  uint64
}

type NATPuncher

type NATPuncher interface {
	// Dial dials the given address.
	// Should be used only on client side.
	Dial(addr common.Address) (net.Conn, error)
	// DialContext connects to the address using the provided context.
	// Should be used only on client side.
	DialContext(ctx context.Context, addr common.Address) (net.Conn, error)
	// Accept blocks the current execution context until a new connection
	// arrives.
	//
	// Indented to be used on server side.
	Accept() (net.Conn, error)
	// @antmat said that this method is clearly self-descriptive and much obvious. Wow.
	AcceptContext(ctx context.Context) (net.Conn, error)
	// RemoteAddr returns rendezvous remote address.
	RemoteAddr() net.Addr
	// Close closes the puncher.
	// Any blocked operations will be unblocked and return errors.
	Close() error
}

NATPuncher describes an interface of NAT Punching Protocol.

It should be used to penetrate a NAT while connecting two peers located either under the same or different firewalls with network address translation enabled.

type Option

type Option func(o *options) error

Option is a function that configures the listener or dialer.

func WithLogger

func WithLogger(log *zap.Logger) Option

WithLogger is an option that specifies provided logger used for the internal logging. Nil value is supported and can be passed to deactivate the logging system entirely.

func WithNPPBacklog

func WithNPPBacklog(backlog int) Option

WithNPPBacklog is an option that specifies NPP backlog size.

func WithNPPBackoff

func WithNPPBackoff(min, max time.Duration) Option

WithNPPBackoff is an option that specifies NPP timeouts.

func WithRelayDialer

func WithRelayDialer(dialer *relay.Dialer) Option

WithRelayDialer is an option that activates Relay fallback on a NPP dialer.

One or more Relay TCP addresses must be specified in "addrs" argument. Hostname resolution is performed for each of them for environments with dynamic DNS addition/removal. Thus, a single Relay endpoint as a hostname should fit the best.

func WithRelayListener

func WithRelayListener(listener *relay.Listener) Option

WithRelayListener is an option that activates Relay fallback on a NPP listener.

Without this option no intermediate server will be used for relaying TCP.

func WithRendezvous

func WithRendezvous(cfg rendezvous.Config, credentials credentials.TransportCredentials) Option

WithRendezvous is an option that specifies Rendezvous client settings.

Without this option no intermediate server will be used for obtaining peer's endpoints and the entire connection establishment process will fall back to the old good plain TCP connection.

type Port

type Port uint16