package holepunch

import "github.com/libp2p/go-libp2p/p2p/protocol/holepunch"

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 DirectDialTimeout(timeout time.Duration) 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, opts ...Option) (*Service, error)
• func (s *Service) Close() error
• func (s *Service) DirectConnect(p peer.ID) error
• func (s *Service) SetLegacyBehavior(legacyBehavior bool)
• 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 DirectDialTimeout ¶

func DirectDialTimeout(timeout time.Duration) Option

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.

func (*Service) SetLegacyBehavior ¶

func (s *Service) SetLegacyBehavior(legacyBehavior bool)

SetLegacyBehavior is only exposed for testing purposes. Do not set this unless you know what you are doing.

type StartHolePunchEvt ¶

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

Source Files ¶

filter.go holepuncher.go metrics.go svc.go tracer.go util.go

Directories ¶