swarm

package
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 23, 2025 License: MIT Imports: 32 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	// TCP 拨号相对于最后一次 QUIC 拨号延迟的时间
	PublicTCPDelay  = 250 * time.Millisecond
	PrivateTCPDelay = 30 * time.Millisecond

	// QUIC 拨号相对于前一次 QUIC 拨号延迟的时间
	PublicQUICDelay  = 250 * time.Millisecond
	PrivateQUICDelay = 30 * time.Millisecond

	// RelayDelay 是中继拨号相对于直连地址延迟的时间
	RelayDelay = 500 * time.Millisecond

	// 其他传输地址的延迟。这将应用于 /webrtc-direct
	PublicOtherDelay  = 1 * time.Second
	PrivateOtherDelay = 100 * time.Millisecond
)

250ms 的值来自 Happy Eyeballs RFC 8305。这是一个 RTT 的粗略估计

View Source 
const ConcurrentFdDials = 160

ConcurrentFdDials 是通过消耗文件描述符的传输进行的并发出站拨号数量

View Source 
const DialAttempts = 1

DialAttempts 控制一个goroutine尝试拨号给定peer的次数 注意:这已经降到1,因为我们现在有太多拨号。要添加回来,在Dial(.)中添加循环

Variables

View Source 
var (
	// ErrDialBackoff 当对某个peer拨号过于频繁时由退避代码返回
	ErrDialBackoff = errors.New("拨号退避")

	// ErrDialRefusedBlackHole 当我们处于黑洞环境时返回
	ErrDialRefusedBlackHole = errors.New("由于黑洞拒绝拨号")

	// ErrDialToSelf 当尝试拨号到自己时返回
	ErrDialToSelf = errors.New("尝试拨号到自己")

	// ErrNoTransport 当我们不知道给定multiaddr的传输协议时返回
	ErrNoTransport = errors.New("没有传输协议")

	// ErrAllDialsFailed 当连接peer最终失败时返回
	ErrAllDialsFailed = errors.New("所有拨号失败")

	// ErrNoAddresses 当我们找不到要拨号的peer的任何地址时返回
	ErrNoAddresses = errors.New("没有地址")

	// ErrNoGoodAddresses 当我们找到peer的地址但无法使用任何一个时返回
	ErrNoGoodAddresses = errors.New("没有可用地址")

	// ErrGaterDisallowedConnection 当gater阻止我们与peer建立连接时返回
	ErrGaterDisallowedConnection = errors.New("gater禁止与peer建立连接")
)
View Source 
var BackoffBase = time.Second * 5

BackoffBase 是退避的基本时间量(默认:5秒)

View Source 
var BackoffCoef = time.Second

BackoffCoef 是退避系数(默认:1秒)

View Source 
var BackoffMax = time.Minute * 5

BackoffMax 是最大退避时间(默认:5分钟)

View Source 
var DefaultPerPeerRateLimit = 8

DefaultPerPeerRateLimit 是每个peer的并发出站拨号数量

View Source 
var ErrAddrFiltered = errors.New("地址被过滤")

ErrAddrFiltered 在尝试注册到被过滤地址的连接时返回。 除非底层传输出现异常,否则不应该看到此错误

View Source 
var ErrConnClosed = errors.New("连接已关闭")

ErrConnClosed 在操作已关闭的连接时返回

View Source 
var ErrDialTimeout = errors.New("拨号超时")

ErrDialTimeout 表示由于全局超时导致拨号失败

View Source 
var ErrQUICDraft29 errQUICDraft29

ErrQUICDraft29 包装 ErrNoTransport 并提供更有意义的错误消息

View Source 
var ErrSwarmClosed = errors.New("swarm 已关闭")

ErrSwarmClosed 在尝试操作已关闭的 swarm 时返回。

Functions

func DefaultDialRanker 

func DefaultDialRanker(addrs []ma.Multiaddr) []network.AddrDelay

DefaultDialRanker 确定出站连接尝试的排序 参数:

  • addrs: []ma.Multiaddr 待排序的多地址列表

返回值:

  • []network.AddrDelay 排序后的地址延迟列表

地址分为三个不同的组:

  • 私有地址(本地主机和本地网络(RFC 1918))
  • 公共地址
  • 中继地址

在每个组内,地址按照下面描述的排序逻辑进行排序。 然后我们按照这个排序拨号地址,在拨号尝试之间应用短暂的超时。 这种排序逻辑大大减少了同时拨号尝试的数量,同时在绝大多数情况下不会引入额外的延迟。

私有地址和公共地址组并行拨号。 如果我们有任何非中继选项,中继地址的拨号会延迟 500ms。

在每个组(私有、公共、中继地址)内,我们应用以下排序逻辑:

  1. 如果同时存在 IPv6 QUIC 和 IPv4 QUIC 地址,我们采用类似 Happy Eyeballs RFC 8305 的排序方式。 首先拨号端口号最小的 IPv6 QUIC 地址。 之后我们拨号端口号最小的 IPv4 QUIC 地址,对于公共地址延迟 250ms(PublicQUICDelay),对于本地地址延迟 30ms(PrivateQUICDelay)。 之后我们拨号所有剩余的地址,对于公共地址延迟 250ms(PublicQUICDelay),对于本地地址延迟 30ms(PrivateQUICDelay)。
  2. 如果只存在 QUIC IPv6 或 QUIC IPv4 地址中的一种,首先拨号端口号最小的 QUIC 地址。之后我们拨号剩余的 QUIC 地址,对于公共地址延迟 250ms(PublicQUICDelay),对于本地地址延迟 30ms(PrivateQUICDelay)。
  3. 如果存在 QUIC 或 WebTransport 地址,TCP 地址的拨号相对于最后一次 QUIC 拨号会延迟: 我们倾向于最终建立 QUIC 连接。对于公共地址,引入的延迟是 250ms(PublicTCPDelay),对于私有地址是 30ms(PrivateTCPDelay)。
  4. 对于 TCP 地址,我们采用类似 QUIC 的策略,并针对第 6 点中描述的 TCP 握手时间较长进行了优化。 如果同时存在 IPv6 TCP 和 IPv4 TCP 地址,我们采用 Happy Eyeballs 风格的排序。 首先拨号端口号最小的 IPv6 TCP 地址。之后,拨号端口号最小的 IPv4 TCP 地址,对于公共地址延迟 250ms(PublicTCPDelay),对于本地地址延迟 30ms(PrivateTCPDelay)。 之后我们拨号所有剩余的地址,对于公共地址延迟 250ms(PublicTCPDelay),对于本地地址延迟 30ms(PrivateTCPDelay)。
  5. 如果只存在 TCP IPv6 或 TCP IPv4 地址中的一种,首先拨号端口号最小的 TCP 地址。 之后我们拨号剩余的 TCP 地址,对于公共地址延迟 250ms(PublicTCPDelay),对于本地地址延迟 30ms(PrivateTCPDelay)。
  6. 当 TCP 套接字已连接并等待安全和多路复用升级时,我们停止新的拨号 2*PublicTCPDelay 以允许升级完成。
  7. WebRTC Direct 和其他 IP 传输地址在最后一次 QUIC 或 TCP 拨号后 1 秒拨号。 只有当对等节点没有任何其他可用的传输时,我们才需要拨号这些地址,在这种情况下,这些地址会立即拨号。

我们首先拨号端口号最小的地址,因为它们更可能是监听端口。

func NoDelayDialRanker 

func NoDelayDialRanker(addrs []ma.Multiaddr) []network.AddrDelay

NoDelayDialRanker 对地址进行无延迟排序。这对于同时连接请求很有用。 参数:

  • addrs: []ma.Multiaddr 待排序的多地址列表

返回值:

  • []network.AddrDelay 排序后的地址延迟列表

Types

type BlackHoleState 

type BlackHoleState int

BlackHoleState 表示黑洞检测器的状态

func (BlackHoleState) String 

func (st BlackHoleState) String() string

String 返回状态的字符串表示 返回值:

  • string 状态的字符串描述

type BlackHoleSuccessCounter 

type BlackHoleSuccessCounter struct {
	// N 表示:
	// 1. 评估黑洞状态前所需的最小完成拨号次数
	// 2. 在阻塞状态下探测黑洞状态的最小请求次数
	N int
	// MinSuccesses 是最近 n 次拨号中需要的最小成功次数,用于判断是否未被阻塞
	MinSuccesses int
	// Name 是检测器的名称
	Name string
	// contains filtered or unexported fields
}

BlackHoleSuccessCounter 为拨号提供黑洞过滤功能 此过滤器应与 UDP 或 IPv6 地址过滤器一起使用,以检测 UDP 或 IPv6 黑洞 在黑洞环境中,如果最近 N 次拨号中成功次数少于 MinSuccesses,则拨号请求会被拒绝 如果在阻塞状态下请求成功,过滤器状态将重置,并在重新评估黑洞状态之前允许 N 个后续请求 当其他并发拨号成功时取消的拨号将被计为失败 足够大的 N 可以防止这种情况下的误报

func (*BlackHoleSuccessCounter) HandleRequest 

func (b *BlackHoleSuccessCounter) HandleRequest() BlackHoleState

HandleRequest 返回请求的黑洞过滤结果 返回值:

  • BlackHoleState 黑洞检测器的状态

func (*BlackHoleSuccessCounter) RecordResult 

func (b *BlackHoleSuccessCounter) RecordResult(success bool)

RecordResult 记录拨号的结果 参数:

  • success: bool 拨号是否成功

说明:

  • 在阻塞状态下成功拨号会将过滤器状态更改为探测状态
  • 仅当最近 n 次结果中的成功比例小于过滤器的最小成功比例时,失败的拨号才会阻塞后续请求

func (*BlackHoleSuccessCounter) State 

func (b *BlackHoleSuccessCounter) State() BlackHoleState

State 返回当前状态 返回值:

  • BlackHoleState 黑洞检测器的当前状态

type Clock 

type Clock interface {
	// Now 返回当前时间
	// 返回值:
	//   - time.Time 当前时间
	Now() time.Time

	// Since 返回从指定时刻到现在的时间间隔
	// 参数:
	//   - t: time.Time 起始时刻
	// 返回值:
	//   - time.Duration 时间间隔
	Since(t time.Time) time.Duration

	// InstantTimer 创建一个在指定时刻触发的定时器
	// 参数:
	//   - when: time.Time 触发时刻
	// 返回值:
	//   - InstantTimer 定时器接口
	InstantTimer(when time.Time) InstantTimer
}

Clock 定义一个可以创建基于时刻触发定时器的时钟接口

type Conn 

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

Conn 是 swarm 使用的连接类型。通常情况下,你不会直接使用此类型

func (*Conn) Close 

func (c *Conn) Close() error

Close 关闭此连接

返回值:

  • error 关闭过程中的错误,如果有的话

注意:

  • 此方法不会等待关闭通知完成,因为这可能在打开通知时造成死锁
  • 所有打开通知必须在触发关闭通知之前完成

func (*Conn) ConnState 

func (c *Conn) ConnState() network.ConnectionState

ConnState 返回安全连接状态,包括早期数据结果 如果不支持则返回空

返回值:

  • network.ConnectionState 连接状态

func (*Conn) GetStreams 

func (c *Conn) GetStreams() []network.Stream

GetStreams 返回与此连接关联的所有流

返回值:

  • []network.Stream 流的切片

func (*Conn) ID 

func (c *Conn) ID() string

ID 返回连接的唯一标识符

返回值:

  • string 格式为 "<peer id 的前10个字符>-<全局连接序号>"

func (*Conn) IsClosed 

func (c *Conn) IsClosed() bool

IsClosed 检查连接是否已关闭

返回值:

  • bool 如果连接已关闭返回 true,否则返回 false

func (*Conn) LocalMultiaddr 

func (c *Conn) LocalMultiaddr() ma.Multiaddr

LocalMultiaddr 返回本地端的多地址

返回值:

  • ma.Multiaddr 本地端的多地址

func (*Conn) LocalPeer 

func (c *Conn) LocalPeer() peer.ID

LocalPeer 返回连接本地端的对等点标识

返回值:

  • peer.ID 本地端的对等点标识

func (*Conn) NewStream 

func (c *Conn) NewStream(ctx context.Context) (network.Stream, error)

NewStream 从此连接创建新的流

参数:

  • ctx: context.Context 上下文对象

返回值:

  • network.Stream 新创建的流
  • error 创建过程中的错误,如果有的话

func (*Conn) RemoteMultiaddr 

func (c *Conn) RemoteMultiaddr() ma.Multiaddr

RemoteMultiaddr 返回远程端的多地址

返回值:

  • ma.Multiaddr 远程端的多地址

func (*Conn) RemotePeer 

func (c *Conn) RemotePeer() peer.ID

RemotePeer 返回连接远程端的对等点标识

返回值:

  • peer.ID 远程端的对等点标识

func (*Conn) RemotePublicKey 

func (c *Conn) RemotePublicKey() ic.PubKey

RemotePublicKey 返回远程端对等点的公钥

返回值:

  • ic.PubKey 远程端的公钥

func (*Conn) Scope 

func (c *Conn) Scope() network.ConnScope

Scope 返回连接的作用域

返回值:

  • network.ConnScope 连接作用域

func (*Conn) Stat 

func (c *Conn) Stat() network.ConnStats

Stat 返回此连接的元数据

返回值:

  • network.ConnStats 连接统计信息

func (*Conn) String 

func (c *Conn) String() string

String 返回连接的字符串表示

返回值:

  • string 连接的描述性字符串

type DialBackoff 

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

DialBackoff 是用于跟踪peer拨号退避的类型 Dialbackoff用于避免过度拨号相同的死亡peer 每当我们在peer的所有地址上完全超时时,我们将地址添加到DialBackoff 然后,每当我们再次尝试拨号该peer时,我们检查每个地址是否退避 如果它在退避中,我们不拨号该地址并立即退出 如果拨号成功,该peer及其所有地址都会从退避中移除

注意:

  • 可以安全使用其零值
  • 它是线程安全的
  • 使用后移动此类型是不安全的

func (*DialBackoff) AddBackoff 

func (db *DialBackoff) AddBackoff(p peer.ID, addr ma.Multiaddr)

AddBackoff 将peer的地址添加到退避

退避不是指数级的,而是二次方的,根据以下公式计算: 

BackoffBase + BakoffCoef * PriorBackoffs^2

其中PriorBackoffs是之前的退避次数

参数:

  • p: peer.ID peer标识符
  • addr: ma.Multiaddr 多地址

func (*DialBackoff) Backoff 

func (db *DialBackoff) Backoff(p peer.ID, addr ma.Multiaddr) (backoff bool)

Backoff 返回客户端是否应该退避拨号地址addr的peer p

参数:

  • p: peer.ID peer标识符
  • addr: ma.Multiaddr 多地址

返回值:

  • bool 是否应该退避

func (*DialBackoff) Clear 

func (db *DialBackoff) Clear(p peer.ID)

Clear 移除退避记录。客户端应在成功拨号后调用此方法

参数:

  • p: peer.ID peer标识符

type DialError 

type DialError struct {
	// Peer 是目标节点的ID
	Peer peer.ID
	// DialErrors 记录每个传输层的错误
	DialErrors []TransportError
	// Cause 是导致拨号失败的根本原因
	Cause error
	// Skipped 记录由于超出最大错误数而跳过的错误数量
	Skipped int
}

DialError 是拨号时返回的错误类型

func (*DialError) Error 

func (e *DialError) Error() string

Error 实现error接口,返回格式化的错误信息 返回值:

  • string 格式化后的错误信息

func (*DialError) Timeout 

func (e *DialError) Timeout() bool

Timeout 检查错误是否为超时错误 返回值:

  • bool 如果是超时错误返回true,否则返回false

func (*DialError) Unwrap 

func (e *DialError) Unwrap() []error

Unwrap 实现错误链,返回所有子错误 返回值:

  • []error 包含所有子错误的切片

type InstantTimer 

type InstantTimer interface {
	// Reset 重置定时器到指定时刻
	// 参数:
	//   - d: time.Time 目标时刻
	// 返回值:
	//   - bool 是否成功重置
	Reset(d time.Time) bool

	// Stop 停止定时器
	// 返回值:
	//   - bool 是否成功停止
	Stop() bool

	// Ch 返回定时器的通道
	// 返回值:
	//   - <-chan time.Time 定时器通道
	Ch() <-chan time.Time
}

InstantTimer 定义一个在特定时刻触发的定时器接口,而不是基于持续时间

type MetricsTracer 

type MetricsTracer interface {
	// OpenedConnection 记录新建连接的指标
	// 参数:
	//   - direction: 连接方向(入站/出站)
	//   - pubKey: 对端的公钥
	//   - connState: 连接状态信息
	//   - localAddr: 本地多地址
	OpenedConnection(network.Direction, crypto.PubKey, network.ConnectionState, ma.Multiaddr)

	// ClosedConnection 记录关闭连接的指标
	// 参数:
	//   - direction: 连接方向
	//   - duration: 连接持续时间
	//   - connState: 连接状态信息
	//   - localAddr: 本地多地址
	ClosedConnection(network.Direction, time.Duration, network.ConnectionState, ma.Multiaddr)

	// CompletedHandshake 记录完成握手的指标
	// 参数:
	//   - duration: 握手耗时
	//   - connState: 连接状态信息
	//   - localAddr: 本地多地址
	CompletedHandshake(time.Duration, network.ConnectionState, ma.Multiaddr)

	// FailedDialing 记录拨号失败的指标
	// 参数:
	//   - addr: 目标多地址
	//   - dialErr: 拨号错误
	//   - cause: 错误原因
	FailedDialing(ma.Multiaddr, error, error)

	// DialCompleted 记录拨号完成的指标
	// 参数:
	//   - success: 是否成功
	//   - totalDials: 总拨号次数
	//   - latency: 拨号延迟
	DialCompleted(success bool, totalDials int, latency time.Duration)

	// DialRankingDelay 记录拨号排序延迟的指标
	// 参数:
	//   - d: 延迟时间
	DialRankingDelay(d time.Duration)

	// UpdatedBlackHoleSuccessCounter 更新黑洞过滤器计数器
	// 参数:
	//   - name: 过滤器名称
	//   - state: 过滤器状态
	//   - nextProbeAfter: 下次探测前需等待的请求数
	//   - successFraction: 成功率
	UpdatedBlackHoleSuccessCounter(name string, state BlackHoleState, nextProbeAfter int, successFraction float64)
}

MetricsTracer 定义了指标追踪器接口 用于收集和记录网络连接相关的各种指标

func NewMetricsTracer 

func NewMetricsTracer(opts ...MetricsTracerOption) MetricsTracer

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

  • opts: 配置选项列表

返回值:

  • MetricsTracer 指标追踪器实例

type MetricsTracerOption 

type MetricsTracerOption func(*metricsTracerSetting)

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

func WithRegisterer 

func WithRegisterer(reg prometheus.Registerer) MetricsTracerOption

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

  • reg: Prometheus 注册器

返回值:

  • MetricsTracerOption 配置函数

type Option 

type Option func(*Swarm) error

Option 定义 Swarm 的配置选项函数类型

func WithConnectionGater 

func WithConnectionGater(gater connmgr.ConnectionGater) Option

WithConnectionGater 设置连接过滤器 参数:

  • gater: connmgr.ConnectionGater 连接过滤器对象

返回值:

  • Option 配置选项函数

func WithDialRanker 

func WithDialRanker(d network.DialRanker) Option

WithDialRanker 设置拨号排序器 参数:

  • d: network.DialRanker 拨号排序器对象

返回值:

  • Option 配置选项函数

注意:

  • 拨号排序器不能为空

func WithDialTimeout 

func WithDialTimeout(t time.Duration) Option

WithDialTimeout 设置拨号超时时间 参数:

  • t: time.Duration 超时时间

返回值:

  • Option 配置选项函数

func WithDialTimeoutLocal 

func WithDialTimeoutLocal(t time.Duration) Option

WithDialTimeoutLocal 设置本地拨号超时时间 参数:

  • t: time.Duration 超时时间

返回值:

  • Option 配置选项函数

func WithIPv6BlackHoleSuccessCounter 

func WithIPv6BlackHoleSuccessCounter(f *BlackHoleSuccessCounter) Option

WithIPv6BlackHoleSuccessCounter 配置 IPv6 黑洞检测 参数:

  • f: *BlackHoleSuccessCounter 黑洞检测计数器

返回值:

  • Option 配置选项函数

注意:

  • n 是评估黑洞状态的滑动窗口大小
  • min 是不阻塞请求所需的最小成功数

func WithMetrics 

func WithMetrics(reporter metrics.Reporter) Option

WithMetrics 设置指标报告器 参数:

  • reporter: metrics.Reporter 指标报告器对象

返回值:

  • Option 配置选项函数

func WithMetricsTracer 

func WithMetricsTracer(t MetricsTracer) Option

WithMetricsTracer 设置指标追踪器 参数:

  • t: MetricsTracer 指标追踪器对象

返回值:

  • Option 配置选项函数

func WithMultiaddrResolver 

func WithMultiaddrResolver(resolver network.MultiaddrDNSResolver) Option

WithMultiaddrResolver 设置多地址解析器 参数:

  • resolver: network.MultiaddrDNSResolver 多地址解析器对象

返回值:

  • Option 配置选项函数

func WithReadOnlyBlackHoleDetector 

func WithReadOnlyBlackHoleDetector() Option

WithReadOnlyBlackHoleDetector 配置只读黑洞检测 返回值:

  • Option 配置选项函数

注意:

  • 只读模式下未知状态的拨号请求会被拒绝
  • 不会更新检测器状态
  • 适用于需要准确提供可达性信息的服务(如 AutoNAT)

func WithResourceManager 

func WithResourceManager(m network.ResourceManager) Option

WithResourceManager 设置资源管理器 参数:

  • m: network.ResourceManager 资源管理器对象

返回值:

  • Option 配置选项函数

func WithUDPBlackHoleSuccessCounter 

func WithUDPBlackHoleSuccessCounter(f *BlackHoleSuccessCounter) Option

WithUDPBlackHoleSuccessCounter 配置 UDP 黑洞检测 参数:

  • f: *BlackHoleSuccessCounter 黑洞检测计数器

返回值:

  • Option 配置选项函数

注意:

  • n 是评估黑洞状态的滑动窗口大小
  • min 是不阻塞请求所需的最小成功数

type OrderedListener 

type OrderedListener interface {
	// ListenOrder 返回监听器的设置顺序
	// 一些传输层可能会选择性地使用其他已设置的监听器
	// 例如 WebRTC 可能会重用 QUIC 的 UDP 端口,但前提是 QUIC 先设置
	// 返回值越小,设置顺序越靠前
	ListenOrder() int
}

OrderedListener 接口定义了监听器的设置顺序

type RealClock 

type RealClock struct{}

RealClock 实现了 Clock 接口的真实时钟

func (RealClock) InstantTimer 

func (RealClock) InstantTimer(when time.Time) InstantTimer

InstantTimer 创建一个在指定时刻触发的定时器 参数:

  • when: time.Time 触发时刻

返回值:

  • InstantTimer 定时器接口

func (RealClock) Now 

func (RealClock) Now() time.Time

Now 返回当前时间 返回值:

  • time.Time 当前时间

func (RealClock) Since 

func (RealClock) Since(t time.Time) time.Duration

Since 返回从指定时刻到现在的时间间隔 参数:

  • t: time.Time 起始时刻

返回值:

  • time.Duration 时间间隔

type RealTimer 

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

RealTimer 实现了 InstantTimer 接口的真实定时器

func (RealTimer) Ch 

func (t RealTimer) Ch() <-chan time.Time

Ch 返回定时器的通道 返回值:

  • <-chan time.Time 定时器通道

func (RealTimer) Reset 

func (t RealTimer) Reset(d time.Time) bool

Reset 重置定时器到指定时刻 参数:

  • d: time.Time 目标时刻

返回值:

  • bool 是否成功重置

func (RealTimer) Stop 

func (t RealTimer) Stop() bool

Stop 停止定时器 返回值:

  • bool 是否成功停止

type ResolverFromMaDNS 

type ResolverFromMaDNS struct {
	*madns.Resolver
}

ResolverFromMaDNS 包装了 madns.Resolver

func (ResolverFromMaDNS) ResolveDNSAddr 

func (r ResolverFromMaDNS) ResolveDNSAddr(ctx context.Context, expectedPeerID peer.ID, maddr ma.Multiaddr, recursionLimit int, outputLimit int) ([]ma.Multiaddr, error)

ResolveDNSAddr 实现 MultiaddrDNSResolver 接口，解析 DNS 地址 参数:

  • ctx: context.Context 上下文
  • expectedPeerID: peer.ID 期望的对等点ID
  • maddr: ma.Multiaddr 要解析的多地址
  • recursionLimit: int 递归限制
  • outputLimit: int 输出限制

返回值:

  • []ma.Multiaddr 解析后的多地址列表
  • error 解析过程中的错误

func (ResolverFromMaDNS) ResolveDNSComponent 

func (r ResolverFromMaDNS) ResolveDNSComponent(ctx context.Context, maddr ma.Multiaddr, outputLimit int) ([]ma.Multiaddr, error)

ResolveDNSComponent 实现 MultiaddrDNSResolver 接口，解析 DNS 组件 参数:

  • ctx: context.Context 上下文
  • maddr: ma.Multiaddr 要解析的多地址
  • outputLimit: int 输出限制

返回值:

  • []ma.Multiaddr 解析后的多地址列表
  • error 解析过程中的错误

type Stream 

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

Stream 是 swarm 使用的流类型。通常情况下,你不会直接使用这个类型

func (*Stream) Close 

func (s *Stream) Close() error

Close 关闭流,关闭两端并释放所有相关资源

返回值:

  • error 关闭过程中的错误,如果有的话

func (*Stream) CloseRead 

func (s *Stream) CloseRead() error

CloseRead 关闭流的读取端 此函数不释放资源,使用完流后需调用 Close 或 Reset

返回值:

  • error 关闭读取端过程中的错误,如果有的话

func (*Stream) CloseWrite 

func (s *Stream) CloseWrite() error

CloseWrite 关闭流的写入端,刷新所有数据并发送 EOF 此函数不释放资源,使用完流后需调用 Close 或 Reset

返回值:

  • error 关闭写入端过程中的错误,如果有的话

func (*Stream) Conn 

func (s *Stream) Conn() network.Conn

Conn 返回与此流关联的连接对象

返回值:

  • network.Conn 关联的网络连接对象

func (*Stream) ID 

func (s *Stream) ID() string

ID 返回流的唯一标识符字符串 格式: <peer id 的前10个字符>-<全局连接序号>-<全局流序号>

返回值:

  • string 流的唯一标识符

func (*Stream) Protocol 

func (s *Stream) Protocol() protocol.ID

Protocol 返回在此流上协商的协议(如果已设置)

返回值:

  • protocol.ID 协议标识符

func (*Stream) Read 

func (s *Stream) Read(p []byte) (int, error)

Read 从流中读取字节

参数:

  • p: []byte 用于存储读取数据的字节切片

返回值:

  • int 实际读取的字节数
  • error 读取过程中的错误,如果有的话

func (*Stream) Reset 

func (s *Stream) Reset() error

Reset 重置流,向两端发送错误信号并释放所有相关资源

返回值:

  • error 重置过程中的错误,如果有的话

func (*Stream) Scope 

func (s *Stream) Scope() network.StreamScope

Scope 返回流的作用域

返回值:

  • network.StreamScope 流的作用域对象

func (*Stream) SetDeadline 

func (s *Stream) SetDeadline(t time.Time) error

SetDeadline 设置流的读写超时时间

参数:

  • t: time.Time 超时时间点

返回值:

  • error 设置过程中的错误,如果有的话

func (*Stream) SetProtocol 

func (s *Stream) SetProtocol(p protocol.ID) error

SetProtocol 设置此流的协议

参数:

  • p: protocol.ID 要设置的协议标识符

返回值:

  • error 设置过程中的错误,如果有的话

注意:

  • 这实际上只是记录了我们在此流上使用的协议,并不会执行实际的协议协商
  • 协议协商通常由 Host 完成

func (*Stream) SetReadDeadline 

func (s *Stream) SetReadDeadline(t time.Time) error

SetReadDeadline 设置流的读取超时时间

参数:

  • t: time.Time 超时时间点

返回值:

  • error 设置过程中的错误,如果有的话

func (*Stream) SetWriteDeadline 

func (s *Stream) SetWriteDeadline(t time.Time) error

SetWriteDeadline 设置流的写入超时时间

参数:

  • t: time.Time 超时时间点

返回值:

  • error 设置过程中的错误,如果有的话

func (*Stream) Stat 

func (s *Stream) Stat() network.Stats

Stat 返回此流的元数据信息

返回值:

  • network.Stats 流的统计信息

func (*Stream) String 

func (s *Stream) String() string

String 返回流的字符串表示

返回值:

  • string 包含传输、本地地址、本地节点、远程地址、远程节点信息的字符串

func (*Stream) Write 

func (s *Stream) Write(p []byte) (int, error)

Write 向流中写入字节,每次调用都会刷新

参数:

  • p: []byte 要写入的字节切片

返回值:

  • int 实际写入的字节数
  • error 写入过程中的错误,如果有的话

type Swarm 

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

Swarm 是一个连接多路复用器 允许打开和关闭与其他对等点的连接,同时使用相同的通道进行所有通信 通道发送/接收消息时会注明目标或源对等点

func NewSwarm 

func NewSwarm(local peer.ID, peers peerstore.Peerstore, eventBus event.Bus, opts ...Option) (*Swarm, error)

NewSwarm 构造一个 Swarm 参数:

  • local: peer.ID 本地节点 ID
  • peers: peerstore.Peerstore 对等点存储
  • eventBus: event.Bus 事件总线
  • opts: ...Option 可选配置项

返回值:

  • *Swarm swarm 对象
  • error 错误信息

注意:

  • 如果创建事件发射器失败会返回错误

func (*Swarm) AddListenAddr 

func (s *Swarm) AddListenAddr(a ma.Multiaddr) error

AddListenAddr 告诉 swarm 监听单个地址 与 Listen 不同,此方法不会尝试过滤掉错误的地址

参数:

  • a: 要监听的多地址

返回值:

  • error: 如果监听失败则返回错误

func (*Swarm) AddTransport 

func (s *Swarm) AddTransport(t transport.Transport) error

AddTransport 向 swarm 添加一个传输层 参数:

  • t: transport.Transport 传输层对象

返回值:

  • error 错误信息

注意:

  • 满足 go-dep2p-transport 的 Network 接口

func (*Swarm) Backoff 

func (s *Swarm) Backoff() *DialBackoff

Backoff 返回此swarm的DialBackoff对象 返回值:

  • *DialBackoff 拨号退避对象

func (*Swarm) CanDial 

func (s *Swarm) CanDial(p peer.ID, addr ma.Multiaddr) bool

CanDial 检查是否可以拨号到指定peer和地址

参数:

  • p: peer.ID peer标识符
  • addr: ma.Multiaddr 要检查的地址

返回值:

  • bool 是否可以拨号

func (*Swarm) Close 

func (s *Swarm) Close() error

Close 关闭 swarm 返回值:

  • error 错误信息

func (*Swarm) ClosePeer 

func (s *Swarm) ClosePeer(p peer.ID) error

ClosePeer 关闭与给定对等点的所有连接 参数:

  • p: peer.ID 对等点ID

返回值:

  • error 错误信息

func (*Swarm) Connectedness 

func (s *Swarm) Connectedness(p peer.ID) network.Connectedness

Connectedness 返回我们与给定对等点的连接性状态 参数:

  • p: peer.ID 对等点ID

返回值:

  • network.Connectedness 连接性状态

注意:

  • 要检查我们是否有打开的连接,使用 `s.Connectedness(p) == network.Connected`

func (*Swarm) Conns 

func (s *Swarm) Conns() []network.Conn

Conns 返回所有连接的切片 返回值:

  • []network.Conn 所有连接的列表

func (*Swarm) ConnsToPeer 

func (s *Swarm) ConnsToPeer(p peer.ID) []network.Conn

ConnsToPeer 返回与对等点的所有活动连接 参数:

  • p: peer.ID 对等点ID

返回值:

  • []network.Conn 连接列表

注意:

  • TODO: 考虑将连接列表从最佳到最差排序。目前,它按从最旧到最新排序

func (*Swarm) DialPeer 

func (s *Swarm) DialPeer(ctx context.Context, p peer.ID) (network.Conn, error)

DialPeer 连接到peer。使用network.WithForceDirectDial强制直接连接 这个想法是Swarm的客户端不需要知道连接将通过什么网络进行。 Swarm可以使用它选择的任何网络。 这允许我们使用各种传输协议,进行NAT穿透/中继等来实现连接。

参数:

  • ctx: context.Context 上下文对象
  • p: peer.ID 目标peer标识符

返回值:

  • network.Conn 建立的连接
  • error 可能的错误

func (*Swarm) Done 

func (s *Swarm) Done() <-chan struct{}

Done 返回一个在 swarm 关闭时关闭的通道 返回值:

  • <-chan struct{} 关闭通道

func (*Swarm) InterfaceListenAddresses 

func (s *Swarm) InterfaceListenAddresses() ([]ma.Multiaddr, error)

InterfaceListenAddresses 返回此 swarm 监听的地址列表 它会将"任意接口"地址(/ip4/0.0.0.0, /ip6/::)展开为已知的本地接口地址 返回值:

  • []ma.Multiaddr 监听地址列表
  • error 可能的错误

func (*Swarm) Listen 

func (s *Swarm) Listen(addrs ...ma.Multiaddr) error

Listen 为所有给定地址设置监听器 只要成功监听至少一个地址就返回

参数:

  • addrs: 要监听的多地址列表

返回值:

  • error: 如果没有成功监听任何地址则返回错误

func (*Swarm) ListenAddresses 

func (s *Swarm) ListenAddresses() []ma.Multiaddr

ListenAddresses 返回此 swarm 监听的地址列表 返回值:

  • []ma.Multiaddr 监听地址列表

func (*Swarm) ListenClose 

func (s *Swarm) ListenClose(addrs ...ma.Multiaddr)

ListenClose 停止并删除给定地址的监听器 如果一个地址属于某个监听器提供的地址之一,那么该监听器将关闭其提供的所有地址 例如,如果关闭一个 `/quic` 地址,那么 QUIC 监听器将关闭并同时关闭任何 `/quic-v1` 地址

参数:

  • addrs: 要关闭的多地址列表

func (*Swarm) LocalPeer 

func (s *Swarm) LocalPeer() peer.ID

LocalPeer 返回与swarm关联的本地对等点ID 返回值:

  • peer.ID 本地对等点ID

func (*Swarm) NewStream 

func (s *Swarm) NewStream(ctx context.Context, p peer.ID) (network.Stream, error)

NewStream 在与对等点的任何可用连接上创建新流,必要时进行拨号 参数:

  • ctx: context.Context 上下文对象
  • p: peer.ID 对等点ID

返回值:

  • network.Stream 新建的流对象
  • error 错误信息

注意:

  • 使用 network.WithAllowLimitedConn 在有限(中继)连接上打开流

func (*Swarm) Notify 

func (s *Swarm) Notify(f network.Notifiee)

Notify 注册Notifiee以在事件发生时接收信号 参数:

  • f: network.Notifiee 通知接收者

func (*Swarm) Peers 

func (s *Swarm) Peers() []peer.ID

Peers 返回swarm连接到的对等点集合的副本 返回值:

  • []peer.ID 对等点ID列表

func (*Swarm) Peerstore 

func (s *Swarm) Peerstore() peerstore.Peerstore

Peerstore 返回此 swarm 的对等点存储 返回值:

  • peerstore.Peerstore 对等点存储对象

func (*Swarm) ResourceManager 

func (s *Swarm) ResourceManager() network.ResourceManager

ResourceManager 返回资源管理器 返回值:

  • network.ResourceManager 资源管理器对象

func (*Swarm) SetStreamHandler 

func (s *Swarm) SetStreamHandler(handler network.StreamHandler)

SetStreamHandler 设置新流的处理程序 参数:

  • handler: network.StreamHandler 流处理程序

func (*Swarm) StopNotify 

func (s *Swarm) StopNotify(f network.Notifiee)

StopNotify 取消注册Notifiee以接收信号 参数:

  • f: network.Notifiee 通知接收者

func (*Swarm) StreamHandler 

func (s *Swarm) StreamHandler() network.StreamHandler

StreamHandler 获取新流的处理程序 返回值:

  • network.StreamHandler 流处理程序

func (*Swarm) String 

func (s *Swarm) String() string

String 返回Network的字符串表示形式 返回值:

  • string 字符串表示

func (*Swarm) TransportForDialing 

func (s *Swarm) TransportForDialing(a ma.Multiaddr) transport.Transport

TransportForDialing 获取用于拨号给定多地址的适当传输层 参数:

  • a: ma.Multiaddr 多地址对象

返回值:

  • transport.Transport 传输层对象

注意:

  • 如果没有找到合适的传输层,返回 nil

func (*Swarm) TransportForListening 

func (s *Swarm) TransportForListening(a ma.Multiaddr) transport.Transport

TransportForListening 获取用于监听给定多地址的适当传输层 参数:

  • a: ma.Multiaddr 多地址对象

返回值:

  • transport.Transport 传输层对象

注意:

  • 如果没有找到合适的传输层,返回 nil

type TransportError 

type TransportError struct {
	// Address 是尝试连接的多地址
	Address ma.Multiaddr
	// Cause 是具体的错误原因
	Cause error
}

TransportError 是拨号特定地址时返回的错误类型

func (*TransportError) Error 

func (e *TransportError) Error() string

Error 实现error接口,返回格式化的错误信息 返回值:

  • string 格式化后的错误信息

func (*TransportError) Unwrap 

func (e *TransportError) Unwrap() error

Unwrap 返回底层错误 返回值:

  • error 底层的错误对象

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.