peerstore

type AddrBook interface {
	// AddAddr 调用 AddAddrs(p, []ma.Multiaddr{addr}, ttl)
	AddAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)

	// AddAddrs 为AddrBook提供要使用的地址，具有给定的TTL（生存时间）
	// 在TTL之后，地址将不再有效
	// 如果管理器有更长的TTL，则该地址的操作为空操作
	AddAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)

	// SetAddr 调用 mgr.SetAddrs(p, addr, ttl)
	SetAddr(p peer.ID, addr ma.Multiaddr, ttl time.Duration)

	// SetAddrs 设置地址的TTL。这会清除之前的任何TTL
	// 当我们收到地址有效性的最佳估计时使用此方法
	SetAddrs(p peer.ID, addrs []ma.Multiaddr, ttl time.Duration)

	// UpdateAddrs 更新具有给定oldTTL的给定对等点的关联地址，使其具有给定的newTTL
	UpdateAddrs(p peer.ID, oldTTL time.Duration, newTTL time.Duration)

	// Addrs 返回给定对等点的所有已知（且有效）地址
	Addrs(p peer.ID) []ma.Multiaddr

	// AddrStream 返回一个通道，该通道会接收给定对等点的所有地址
	// 如果在调用后添加了新地址，这些地址也会通过该通道发送
	AddrStream(context.Context, peer.ID) <-chan ma.Multiaddr

	// ClearAddresses 移除所有先前存储的地址
	ClearAddrs(p peer.ID)

	// PeersWithAddrs 返回AddrBook中存储的所有对等点ID
	PeersWithAddrs() peer.IDSlice
}

type CertifiedAddrBook interface {
	// ConsumePeerRecord 存储签名的对等点记录和其包含的地址，持续时间为ttl
	// 签名对等点记录中包含的地址将在ttl后过期
	// 如果任何地址已存在于对等点存储中，它将在现有ttl和提供的ttl的最大值处过期
	// 当与对等点关联的所有地址（无论是自认证的还是非自认证的）从AddrBook中移除时，签名的对等点记录本身将过期
	//
	// 要删除签名的对等点记录，请使用`AddrBook.UpdateAddrs`、`AddrBook.SetAddrs`或`AddrBook.ClearAddrs`，并将ttl设为0
	// 注意：未来对ConsumePeerRecord的调用不会使先前调用的自认证地址过期
	//
	// `accepted`返回值表示记录已成功处理
	// 如果`accepted`为false但未返回错误，则表示记录被忽略，很可能是因为存在具有更大seq值的同一对等点的较新记录
	//
	// 包含签名对等点记录的信封可以通过调用GetPeerRecord(peerID)获取
	ConsumePeerRecord(s *record.Envelope, ttl time.Duration) (accepted bool, err error)

	// GetPeerRecord 返回包含对等点记录的信封，如果不存在记录则返回nil
	GetPeerRecord(p peer.ID) *record.Envelope
}

type KeyBook interface {
	// PubKey 返回对等点的公钥
	PubKey(peer.ID) ic.PubKey

	// AddPubKey 存储对等点的公钥
	AddPubKey(peer.ID, ic.PubKey) error

	// PrivKey 返回对等点的私钥（如果已知）
	PrivKey(peer.ID) ic.PrivKey

	// AddPrivKey 存储对等点的私钥
	AddPrivKey(peer.ID, ic.PrivKey) error

	// PeersWithKeys 返回KeyBook中存储的所有对等点ID
	PeersWithKeys() peer.IDSlice

	// RemovePeer 移除与对等点关联的所有密钥
	RemovePeer(peer.ID)
}

type Metrics interface {
	// RecordLatency 记录新的延迟测量
	RecordLatency(peer.ID, time.Duration)

	// LatencyEWMA 返回对等点延迟所有测量的指数加权移动平均值
	LatencyEWMA(peer.ID) time.Duration

	// RemovePeer 移除存储的对等点的所有指标
	RemovePeer(peer.ID)
}

type PeerMetadata interface {
	// Get/Put 是其他对等点相关键值对的简单注册表
	// 如果我们发现经常使用某些内容，它应该成为自己的方法集。这是最后的手段
	Get(p peer.ID, key string) (interface{}, error)
	Put(p peer.ID, key string, val interface{}) error

	// RemovePeer 移除存储的对等点的所有值
	RemovePeer(peer.ID)
}

type Peerstore interface {
	io.Closer

	AddrBook
	KeyBook
	PeerMetadata
	Metrics
	ProtoBook

	// PeerInfo 返回给定peer.ID的peer.PeerInfo结构
	// 这是Peerstore中关于该对等点信息的一个小切片，对其他服务有用
	PeerInfo(peer.ID) peer.AddrInfo

	// Peers 返回所有内部存储中存储的对等点ID
	Peers() peer.IDSlice

	// RemovePeer 移除除地址外的所有对等点相关信息
	// 要移除地址，请使用`AddrBook.ClearAddrs`或将地址TTL设置为0
	RemovePeer(peer.ID)
}

type ProtoBook interface {
	// GetProtocols 获取对等点支持的协议列表
	GetProtocols(peer.ID) ([]protocol.ID, error)

	// AddProtocols 为对等点添加协议
	AddProtocols(peer.ID, ...protocol.ID) error

	// SetProtocols 设置对等点的协议
	SetProtocols(peer.ID, ...protocol.ID) error

	// RemoveProtocols 移除对等点的指定协议
	RemoveProtocols(peer.ID, ...protocol.ID) error

	// SupportsProtocols 从给定的协议中返回对等点支持的协议集
	// 如果返回的错误不为nil，则结果不确定
	SupportsProtocols(peer.ID, ...protocol.ID) ([]protocol.ID, error)

	// FirstSupportedProtocol 返回对等点在给定协议中支持的第一个协议
	// 如果对等点不支持任何给定的协议，此函数将返回空的protocol.ID和nil错误
	// 如果返回的错误不为nil，则结果不确定
	FirstSupportedProtocol(peer.ID, ...protocol.ID) (protocol.ID, error)

	// RemovePeer 移除与对等点关联的所有协议
	RemovePeer(peer.ID)
}