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" // 打洞尝试
)

事件类型常量

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

Protocol 是用于打洞的 dep2p 协议标识

const (
	// ServiceName 是打洞服务的名称
	ServiceName = "dep2p.holepunch"
)

Variables

var ErrClosed = errors.New("打洞服务正在关闭")

ErrClosed 当打洞服务关闭时返回此错误

var ErrHolePunchActive = errors.New("另一个打洞尝试正在进行中")

ErrHolePunchActive 当另一个打洞尝试正在进行时，DirectConnect 会返回此错误

var StreamTimeout = 1 * time.Minute

StreamTimeout 是打洞协议流的超时时间

Types

type AddrFilter

type AddrFilter interface {
	// FilterLocal 过滤发送给远程对等节点的多地址
	// 参数:
	//   - remoteID: peer.ID 远程节点 ID
	//   - maddrs: []ma.Multiaddr 多地址列表
	//
	// 返回值:
	//   - []ma.Multiaddr 过滤后的多地址列表
	FilterLocal(remoteID peer.ID, maddrs []ma.Multiaddr) []ma.Multiaddr

	// FilterRemote 过滤从远程对等节点接收到的多地址
	// 参数:
	//   - remoteID: peer.ID 远程节点 ID
	//   - maddrs: []ma.Multiaddr 多地址列表
	//
	// 返回值:
	//   - []ma.Multiaddr 过滤后的多地址列表
	FilterRemote(remoteID peer.ID, maddrs []ma.Multiaddr) []ma.Multiaddr
}

AddrFilter 定义了多地址过滤的接口

type DirectDialEvt

type DirectDialEvt struct {
	Success      bool          // 是否成功
	EllapsedTime time.Duration // 耗时
	Error        string        `json:",omitempty"` // 错误信息
}

DirectDialEvt 直接拨号事件

type EndHolePunchEvt

type EndHolePunchEvt struct {
	Success      bool          // 是否成功
	EllapsedTime time.Duration // 耗时
	Error        string        `json:",omitempty"` // 错误信息
}

EndHolePunchEvt 结束打洞事件

type Event

type Event struct {
	Timestamp int64       // UNIX 纳秒时间戳
	Peer      peer.ID     // 本地节点 ID
	Remote    peer.ID     // 远程节点 ID
	Type      string      // 事件类型
	Evt       interface{} // 具体事件
}

Event 事件结构体

type EventTracer

type EventTracer interface {
	Trace(evt *Event)
}

EventTracer 事件追踪器接口

type HolePunchAttemptEvt

type HolePunchAttemptEvt struct {
	Attempt int // 尝试次数
}

HolePunchAttemptEvt 打洞尝试事件

type MetricsTracer

type MetricsTracer interface {
	// HolePunchFinished 记录打洞完成的指标
	HolePunchFinished(side string, attemptNum int, theirAddrs []ma.Multiaddr, ourAddr []ma.Multiaddr, directConn network.ConnMultiaddrs)
	// DirectDialFinished 记录直接拨号完成的指标
	DirectDialFinished(success bool)
}

MetricsTracer 定义了打洞指标追踪器的接口

func NewMetricsTracer

func NewMetricsTracer(opts ...MetricsTracerOption) MetricsTracer

NewMetricsTracer 创建一个新的指标追踪器 参数:

• opts: ...MetricsTracerOption 配置选项

返回值:

• MetricsTracer 指标追踪器实例

type MetricsTracerOption

type MetricsTracerOption func(*metricsTracerSetting)

MetricsTracerOption 定义了配置指标追踪器的函数类型

func WithRegisterer

func WithRegisterer(reg prometheus.Registerer) MetricsTracerOption

WithRegisterer 返回一个设置注册器的选项函数 参数:

• reg: prometheus.Registerer Prometheus 注册器

返回值:

• MetricsTracerOption 配置函数

type Option

type Option func(*Service) error

Option 是配置 Service 的函数类型

func WithAddrFilter

func WithAddrFilter(f AddrFilter) Option

WithAddrFilter 是一个 Service 选项,用于启用多地址过滤功能 参数:

• f: AddrFilter 地址过滤器接口

返回值:

• Option Service 选项函数

说明:

• 允许只向远程对等节点发送观察到的地址的子集
• 例如,只宣告 TCP 或 QUIC 多地址而不是两者都宣告
• 也允许只考虑远程对等节点向我们宣告的多地址的子集
• 理论上,此 API 还允许在两种情况下添加多地址

func WithMetricsAndEventTracer

func WithMetricsAndEventTracer(mt MetricsTracer, et EventTracer) Option

WithMetricsAndEventTracer 同时使用 MetricsTracer 和 EventTracer 启用打洞追踪 参数:

• mt: MetricsTracer 指标追踪器
• et: EventTracer 事件追踪器

返回值:

• Option 配置选项函数

func WithMetricsTracer

func WithMetricsTracer(mt MetricsTracer) Option

WithMetricsTracer 使用 MetricsTracer 启用打洞追踪 参数:

• mt: MetricsTracer 指标追踪器

返回值:

• Option 配置选项函数

func WithTracer

func WithTracer(et EventTracer) Option

WithTracer 使用 EventTracer 启用打洞追踪 参数:

• et: EventTracer 事件追踪器

返回值:

• Option 配置选项函数

type ProtocolErrorEvt

type ProtocolErrorEvt struct {
	Error string // 错误信息
}

ProtocolErrorEvt 协议错误事件

type Service

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

Service 在支持 DCUtR 协议的每个节点上运行

func NewService

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

NewService 创建一个可用于打洞的新服务 该服务在所有支持 DCUtR 协议的主机上运行,无论它们是否在 NAT/防火墙后面 该服务处理 DCUtR 流(当我们通过中继建立连接后,由 NAT/防火墙后的节点发起)

参数:

• h: host.Host 本地节点
• ids: identify.IDService 标识服务
• listenAddrs: func() []ma.Multiaddr 返回公共地址的函数
• opts: ...Option 可选的配置选项

返回值:

• *Service 打洞服务实例
• error 错误信息

注意:

• listenAddrs 必须只返回公共地址

func (*Service) Close

func (s *Service) Close() error

Close 关闭打洞服务

返回值:

• error 关闭过程中的错误

func (*Service) DirectConnect

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

DirectConnect 仅用于测试目的 TODO: 为此找到解决方案

参数:

• p: peer.ID 对等点 ID

返回值:

• error 错误信息

type StartHolePunchEvt

type StartHolePunchEvt struct {
	RemoteAddrs []string      // 远程地址列表
	RTT         time.Duration // 往返时延
}

StartHolePunchEvt 开始打洞事件