connmgr

Documentation

Overview

connmgr 包为 dep2p 提供连接跟踪和管理接口。

本包导出的 ConnManager 接口允许 dep2p 对打开的连接总数强制执行上限。 为了避免服务中断,连接可以使用元数据进行标记,并可选择性地进行"保护",以确保不会随意切断重要连接。

Index

• type BumpFn
  • func BumpOverwrite() BumpFn
  • func BumpSumBounded(min, max int) BumpFn
  • func BumpSumUnbounded() BumpFn
• type ConnManager
• type ConnectionGater
• type DecayFn
  • func DecayExpireWhenInactive(after time.Duration) DecayFn
  • func DecayFixed(minuend int) DecayFn
  • func DecayLinear(coef float64) DecayFn
  • func DecayNone() DecayFn
• type Decayer
  • func SupportsDecay(mgr ConnManager) (Decayer, bool)
• type DecayingTag
• type DecayingValue
• type GetConnLimiter
• type NullConnMgr
  • func (NullConnMgr) CheckLimit(l GetConnLimiter) error
  • func (NullConnMgr) Close() error
  • func (NullConnMgr) GetTagInfo(peer.ID) *TagInfo
  • func (NullConnMgr) IsProtected(peer.ID, string) bool
  • func (NullConnMgr) Notifee() network.Notifiee
  • func (NullConnMgr) Protect(peer.ID, string)
  • func (NullConnMgr) TagPeer(peer.ID, string, int)
  • func (NullConnMgr) TrimOpenConns(ctx context.Context)
  • func (NullConnMgr) Unprotect(peer.ID, string) bool
  • func (NullConnMgr) UntagPeer(peer.ID, string)
  • func (NullConnMgr) UpsertTag(peer.ID, string, func(int) int)
• type TagInfo

Types

type BumpFn

type BumpFn func(value DecayingValue, delta int) (after int)

BumpFn 将增量应用到现有分数上,并返回新分数。

非平凡的提升函数包括指数提升、移动平均、上限等。

func BumpOverwrite

func BumpOverwrite() BumpFn

BumpOverwrite 返回一个提升函数,用新值直接覆盖当前值。 返回值:

• BumpFn: 覆盖式的提升函数

func BumpSumBounded

func BumpSumBounded(min, max int) BumpFn

BumpSumBounded 返回一个提升函数,在指定范围内累加分数。 参数:

• min: 允许的最小值
• max: 允许的最大值

返回值:

• BumpFn: 有界累加的提升函数

func BumpSumUnbounded

func BumpSumUnbounded() BumpFn

BumpSumUnbounded 返回一个提升函数,简单地将增量加到当前分数上,不设上限。 返回值:

• BumpFn: 无界累加的提升函数

type ConnManager

type ConnManager interface {
	// TagPeer 使用字符串标记对等点,并为该标记关联一个权重。
	TagPeer(peer.ID, string, int)

	// UntagPeer 从对等点移除标记的值。
	UntagPeer(p peer.ID, tag string)

	// UpsertTag 更新现有标记或插入新标记。
	//
	// 连接管理器调用 upsert 函数,提供标记的当前值(如果不存在则为零)。
	// 返回值用作标记的新值。
	UpsertTag(p peer.ID, tag string, upsert func(int) int)

	// GetTagInfo 返回与对等点关联的元数据,如果没有为该对等点记录元数据则返回 nil。
	GetTagInfo(p peer.ID) *TagInfo

	// TrimOpenConns 基于实现定义的启发式方法终止打开的连接。
	TrimOpenConns(ctx context.Context)

	// Notifee 返回一个可以回调的实现,用于通知已打开和关闭的连接。
	Notifee() network.Notifiee

	// Protect 保护对等点不被修剪其连接。
	//
	// 标记允许系统的不同部分管理保护而不互相干扰。
	//
	// 使用相同标记多次调用 Protect() 是幂等的。
	// 它们不进行引用计数,所以在使用相同标记多次调用 Protect() 后,
	// 使用相同标记的单个 Unprotect() 调用将撤销保护。
	Protect(id peer.ID, tag string)

	// Unprotect 移除可能已在指定标记下对对等点设置的保护。
	//
	// 返回值表示在此调用之后,对等点是否通过其他标记继续受到保护。
	// 更多信息请参见 Protect() 的说明。
	Unprotect(id peer.ID, tag string) (protected bool)

	// IsProtected 如果对等点受某个标记保护则返回 true；
	// 如果标记为空字符串,则当对等点受任何标记保护时返回 true
	IsProtected(id peer.ID, tag string) (protected bool)

	// CheckLimit 如果连接管理器的内部连接限制超过提供的系统限制,则返回错误。
	CheckLimit(l GetConnLimiter) error

	// Close 关闭连接管理器并停止后台进程。
	Close() error
}

ConnManager 跟踪与对等点的连接,并允许使用者为每个对等点关联元数据。

它允许基于实现定义的启发式方法修剪连接。 ConnManager 允许 dep2p 对打开的连接总数强制执行上限。

支持衰减标签的 ConnManager 实现了 Decayer 接口。 如果支持,请使用 SupportsDecay 函数安全地将实例转换为 Decayer。

type ConnectionGater

type ConnectionGater interface {
	// InterceptPeerDial 测试是否允许我们拨号指定的对等节点。
	//
	// 当拨号对等节点时,由 network.Network 实现调用。
	InterceptPeerDial(p peer.ID) (allow bool)

	// InterceptAddrDial 测试是否允许我们为给定对等节点拨号指定的多地址。
	//
	// 在 network.Network 实现解析对等节点地址后、拨号每个地址之前调用。
	InterceptAddrDial(peer.ID, ma.Multiaddr) (allow bool)

	// InterceptAccept 测试是否允许新生的入站连接。
	//
	// 由升级器调用,或由传输直接调用(例如 QUIC、蓝牙),
	// 在从其套接字接受连接后立即调用。
	InterceptAccept(network.ConnMultiaddrs) (allow bool)

	// InterceptSecured 测试是否允许给定的已认证连接。
	//
	// 由升级器在执行安全握手之后、协商多路复用器之前调用,
	// 或由传输在完全相同的检查点直接调用。
	InterceptSecured(network.Direction, peer.ID, network.ConnMultiaddrs) (allow bool)

	// InterceptUpgraded 测试是否允许完全功能的连接。
	//
	// 此时已选择多路复用器。
	// 当拒绝连接时,控制器可以返回一个 DisconnectReason。
	// 更多信息请参考 ConnectionGater 类型的 godoc。
	//
	// 注意:go-dep2p 实现目前忽略断开连接原因。
	InterceptUpgraded(network.Conn) (allow bool, reason control.DisconnectReason)
}

ConnectionGater 可以由支持主动入站或出站连接控制的类型实现。

ConnectionGater 是主动的,而 ConnManager 倾向于被动。

在连接建立/升级生命周期的不同阶段,将会调用 ConnectionGater 进行咨询。 在整个过程中会调用特定的函数,允许你在该阶段拦截连接。

InterceptPeerDial 在即将进行出站对等节点拨号请求时调用,在该对等节点的地址可用/解析之前。
在这个阶段阻止连接通常用于黑名单场景。

InterceptAddrDial 在即将向特定地址的对等节点进行出站拨号时调用。
在这个阶段阻止连接通常用于地址过滤。

InterceptAccept 在传输监听器收到入站连接请求时立即调用,在任何升级发生之前。
接受已经安全和/或多路复用的连接的传输(例如可能是 QUIC)必须调用此方法,以确保正确性/一致性。

InterceptSecured 在完成安全握手并验证对等节点身份后,对入站和出站连接都会调用。

InterceptUpgraded 在 dep2p 完全将连接升级为安全、多路复用的通道后,
对入站和出站连接都会调用。

此接口可用于实现*严格/主动*的连接管理策略,例如: - 达到最大连接数后的硬限制 - 维护对等节点黑名单 - 按传输配额限制连接

实验性功能:未来将支持 DISCONNECT 协议/消息。 这允许控制器和其他组件传达连接关闭的意图,以减少潜在的重连尝试。

目前,InterceptUpgraded 在阻止连接时可以返回非零的 DisconnectReason, 但随着我们完善此功能,此接口可能在未来发生变化。 只有此方法可以处理 DisconnectReason 的原因是, 我们需要流多路复用功能来打开控制协议流以传输消息。

type DecayFn

type DecayFn func(value DecayingValue) (after int, rm bool)

DecayFn 对对等节点的分数应用衰减。 实现必须在注册标签时提供的时间间隔调用DecayFn。

它接收衰减值的副本,并返回应用衰减后的分数,以及一个标志以指示是否应删除该标签。

func DecayExpireWhenInactive

func DecayExpireWhenInactive(after time.Duration) DecayFn

DecayExpireWhenInactive 返回一个衰减函数,在指定时间内没有提升时使标签过期。 参数:

• after: 无活动后过期的时间间隔

返回值:

• DecayFn: 基于不活动时间的衰减函数

func DecayFixed

func DecayFixed(minuend int) DecayFn

DecayFixed 返回一个固定衰减函数,每次从当前值中减去指定的数值。 当值首次达到0或负数时删除标签。 参数:

• minuend: 每次衰减要减去的固定值

返回值:

• DecayFn: 执行固定衰减的函数

func DecayLinear

func DecayLinear(coef float64) DecayFn

DecayLinear 返回一个线性衰减函数,对标签值应用一个分数系数。 使用 math.Floor 向下取整,当结果为0时删除标签。 参数:

• coef: 衰减系数(0-1之间的小数)

返回值:

• DecayFn: 执行线性衰减的函数

func DecayNone

func DecayNone() DecayFn

DecayNone 返回一个不执行任何衰减的衰减函数。 返回值:

• DecayFn: 衰减函数,保持标签值不变

type Decayer

type Decayer interface {
	io.Closer

	// RegisterDecayingTag 创建并注册一个新的衰减标签,当且仅当具有提供名称的标签不存在时。否则,返回错误。
	//
	// 调用者提供刷新标签的时间间隔,以及衰减函数和提升函数。
	// 有关更多信息,请参阅DecayFn和BumpFn的godoc。
	RegisterDecayingTag(name string, interval time.Duration, decayFn DecayFn, bumpFn BumpFn) (DecayingTag, error)
}

Decayer 由支持衰减标签的连接管理器实现。 衰减标签是一个其值会随时间自动衰减的标签。

实际的衰减行为封装在用户提供的衰减函数(DecayFn)中。 该函数在每个时间间隔(由interval参数确定)被调用,并返回标签的新值,或者标签是否应该被删除。

我们不直接设置衰减标签的值。 相反,我们通过增量来"提升"衰减标签。 这会调用BumpFn函数,传入旧值和增量,来确定新值。

这种可插拔的设计提供了很大的灵活性和多功能性。 容易实现的行为包括:

• 每个时间间隔将标签值减1,或减半。
• 每次提升值时,将其与当前值相加。
• 每次提升时指数级提高分数。
• 将输入分数相加,但保持在最小值和最大值范围内。

本包提供了常用的DecayFns和BumpFns。

func SupportsDecay

func SupportsDecay(mgr ConnManager) (Decayer, bool)

SupportsDecay 评估提供的 ConnManager 是否支持衰减,如果支持,则返回 Decayer 对象。 更多信息请参考 Decayer 的 godoc 文档。

type DecayingTag

type DecayingTag interface {
	// Name 返回标签的名称。
	Name() string

	// Interval 是此标签将滴答的有效时间间隔。
	// 在注册时,根据衰减器的分辨率,所需的时间间隔可能会被覆盖,此方法允许您获取有效的时间间隔。
	Interval() time.Duration

	// Bump 对标签值应用增量,调用其提升函数。
	// 提升将异步应用,非nil错误表示排队时出现故障。
	Bump(peer peer.ID, delta int) error

	// Remove 从对等节点中移除衰减标签。
	// 移除将异步应用,非nil错误表示排队时出现故障。
	Remove(peer peer.ID) error

	// Close 关闭衰减标签。
	// Decayer将停止跟踪此标签,并且连接管理器中持有此标签的所有对等节点的状态将被更新。
	//
	// 删除是异步执行的。
	//
	// 一旦删除,标签就不应再使用,后续调用Bump/Remove将返回错误。
	//
	// 重复调用Remove不会返回错误,但如果无法将第一个实际移除排队(例如,当系统积压时),则会返回错误。
	Close() error
}

DecayingTag 表示一个衰减标签。 该标签是一个长期存在的通用对象,用于操作对等节点的标签值。

type DecayingValue

type DecayingValue struct {
	// Tag 指向此值所属的标签。
	Tag DecayingTag

	// Peer 是与此值关联的对等节点ID。
	Peer peer.ID

	// Added 是首次为标签和对等节点添加此值的时间戳。
	Added time.Time

	// LastVisit 是最后一次访问的时间戳。
	LastVisit time.Time

	// Value 是标签的当前值。
	Value int
}

DecayingValue 表示衰减标签的值。

type GetConnLimiter

type GetConnLimiter interface {
	// GetConnLimit 返回实现组件的总连接限制。
	GetConnLimit() int
}

GetConnLimiter 提供对组件总连接限制的访问。

type NullConnMgr

type NullConnMgr struct{}

NullConnMgr 是一个不提供任何功能的 ConnMgr。

func (NullConnMgr) CheckLimit

func (NullConnMgr) CheckLimit(l GetConnLimiter) error

func (NullConnMgr) Close

func (NullConnMgr) Close() error

func (NullConnMgr) GetTagInfo

func (NullConnMgr) GetTagInfo(peer.ID) *TagInfo

func (NullConnMgr) IsProtected

func (NullConnMgr) IsProtected(peer.ID, string) bool

func (NullConnMgr) Notifee

func (NullConnMgr) Notifee() network.Notifiee

func (NullConnMgr) Protect

func (NullConnMgr) Protect(peer.ID, string)

func (NullConnMgr) TagPeer

func (NullConnMgr) TagPeer(peer.ID, string, int)

func (NullConnMgr) TrimOpenConns

func (NullConnMgr) TrimOpenConns(ctx context.Context)

func (NullConnMgr) Unprotect

func (NullConnMgr) Unprotect(peer.ID, string) bool

func (NullConnMgr) UntagPeer

func (NullConnMgr) UntagPeer(peer.ID, string)

func (NullConnMgr) UpsertTag

func (NullConnMgr) UpsertTag(peer.ID, string, func(int) int)

type TagInfo

type TagInfo struct {
	// FirstSeen 记录第一次看到此对等点的时间戳
	FirstSeen time.Time

	// Value 表示此对等点的总体评分值,由所有标记的权重总和计算得出
	Value int

	// Tags 将标记 ID 映射到数值。
	// 每个标记代表一个特定的属性或行为,其对应的数值表示该属性的权重或重要性。
	// 例如 "app=bitswap:5" 表示此对等点在 bitswap 协议中的权重为 5。
	Tags map[string]int

	// Conns 将连接 ID(如远程多地址)映射到其创建时间。
	// 用于跟踪与此对等点的所有活动连接及其建立时间。
	// 连接 ID 通常是远程多地址的字符串表示。
	Conns map[string]time.Time
}

TagInfo 存储与对等点关联的元数据。