holepunch

Documentation

Index

• Constants
• Variables
• type AddrFilter
• type DirectDialEvt
• type EndHolePunchEvt
• type Event
• type EventTracer
• type HolePunchAttemptEvt
• type MetricsTracer
  • func NewMetricsTracer(opts ...MetricsTracerOption) MetricsTracer
• type MetricsTracerOption
  • func WithRegisterer(reg prometheus.Registerer) MetricsTracerOption
• type Option
  • func WithAddrFilter(f AddrFilter) Option
  • func WithMetricsAndEventTracer(mt MetricsTracer, et EventTracer) Option
  • func WithMetricsTracer(mt MetricsTracer) Option
  • func WithTracer(et EventTracer) Option
• type ProtocolErrorEvt
• type Service
  • func NewService(h host.Host, ids identify.IDService, listenAddrs func() []ma.Multiaddr, ...) (*Service, error)
  • func (s *Service) Close() error
  • func (s *Service) DirectConnect(p peer.ID) error
• type StartHolePunchEvt

Constants

const (
	DirectDialEvtT       = "DirectDial"
	ProtocolErrorEvtT    = "ProtocolError"
	StartHolePunchEvtT   = "StartHolePunch"
	EndHolePunchEvtT     = "EndHolePunch"
	HolePunchAttemptEvtT = "HolePunchAttempt"
)

Event Types

const Protocol protocol.ID = "/libp2p/dcutr"

Protocol is the libp2p protocol for Hole Punching.

const (
	ServiceName = "libp2p.holepunch"
)

Variables

var ErrClosed = errors.New("hole punching service closing")

ErrClosed is returned when the hole punching is closed

var ErrHolePunchActive = errors.New("another hole punching attempt to this peer is active")

ErrHolePunchActive is returned from DirectConnect when another hole punching attempt is currently running

var StreamTimeout = 1 * time.Minute

StreamTimeout is the timeout for the hole punch protocol stream.

Types

type AddrFilter

type AddrFilter interface {
	// FilterLocal filters the multi addresses that are sent to the remote peer.
	FilterLocal(remoteID peer.ID, maddrs []ma.Multiaddr) []ma.Multiaddr
	// FilterRemote filters the multi addresses received from the remote peer.
	FilterRemote(remoteID peer.ID, maddrs []ma.Multiaddr) []ma.Multiaddr
}

AddrFilter defines the interface for the multi address filtering.

type DirectDialEvt

type DirectDialEvt struct {
	Success      bool
	EllapsedTime time.Duration
	Error        string `json:",omitempty"`
}

Event Objects

type EndHolePunchEvt

type EndHolePunchEvt struct {
	Success      bool
	EllapsedTime time.Duration
	Error        string `json:",omitempty"`
}

type Event

type Event struct {
	Timestamp int64       // UNIX nanos
	Peer      peer.ID     // local peer ID
	Remote    peer.ID     // remote peer ID
	Type      string      // event type
	Evt       interface{} // the actual event
}

type EventTracer

type EventTracer interface {
	Trace(evt *Event)
}

type HolePunchAttemptEvt

type HolePunchAttemptEvt struct {
	Attempt int
}

type MetricsTracer

type MetricsTracer interface {
	HolePunchFinished(side string, attemptNum int, theirAddrs []ma.Multiaddr, ourAddr []ma.Multiaddr, directConn network.ConnMultiaddrs)
	DirectDialFinished(success bool)
}

func NewMetricsTracer

func NewMetricsTracer(opts ...MetricsTracerOption) MetricsTracer

type MetricsTracerOption

type MetricsTracerOption func(*metricsTracerSetting)

func WithRegisterer

func WithRegisterer(reg prometheus.Registerer) MetricsTracerOption

type Option

type Option func(*Service) error

func WithAddrFilter

func WithAddrFilter(f AddrFilter) Option

WithAddrFilter is a Service option that enables multiaddress filtering. It allows to only send a subset of observed addresses to the remote peer. E.g., only announce TCP or QUIC multi addresses instead of both. It also allows to only consider a subset of received multi addresses that remote peers announced to us. Theoretically, this API also allows to add multi addresses in both cases.

func WithMetricsAndEventTracer

func WithMetricsAndEventTracer(mt MetricsTracer, et EventTracer) Option

WithMetricsAndEventTracer enables holepunch tracking with MetricsTracer and EventTracer

func WithMetricsTracer

func WithMetricsTracer(mt MetricsTracer) Option

WithMetricsTracer enables holepunch Tracing with MetricsTracer mt

func WithTracer

func WithTracer(et EventTracer) Option

WithTracer enables holepunch tracing with EventTracer et

type ProtocolErrorEvt

type ProtocolErrorEvt struct {
	Error string
}

type Service

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

The Service runs on every node that supports the DCUtR protocol.

func NewService

func NewService(h host.Host, ids identify.IDService, listenAddrs func() []ma.Multiaddr, opts ...Option) (*Service, error)

NewService creates a new service that can be used for hole punching The Service runs on all hosts that support the DCUtR protocol, no matter if they are behind a NAT / firewall or not. The Service handles DCUtR streams (which are initiated from the node behind a NAT / Firewall once we establish a connection to them through a relay.

listenAddrs MUST only return public addresses.

func (*Service) Close

func (s *Service) Close() error

Close closes the Hole Punch Service.

func (*Service) DirectConnect

func (s *Service) DirectConnect(p peer.ID) error

DirectConnect is only exposed for testing purposes. TODO: find a solution for this.

type StartHolePunchEvt

type StartHolePunchEvt struct {
	RemoteAddrs []string
	RTT         time.Duration
}