event

type AddrAction int

type Bus interface {
	// Subscribe 创建一个新的订阅。
	//
	// eventType 可以是指向单个事件类型的指针,也可以是指向多个事件类型的指针切片,
	// 以便一次性订阅多个事件类型(在单个订阅和通道下)。
	//
	// 未能及时消费通道可能导致发布者阻塞。
	//
	// 如果你想订阅总线上发出的所有事件,请使用 `WildcardSubscription` 作为 `eventType`:
	//
	//  eventbus.Subscribe(WildcardSubscription)
	//
	// 简单示例
	//
	//  sub, err := eventbus.Subscribe(new(EventType))
	//  defer sub.Close()
	//  for e := range sub.Out() {
	//    event := e.(EventType) // 保证安全
	//    [...]
	//  }
	//
	// 多类型示例
	//
	//  sub, err := eventbus.Subscribe([]interface{}{new(EventA), new(EventB)})
	//  defer sub.Close()
	//  for e := range sub.Out() {
	//    select e.(type):
	//      case EventA:
	//        [...]
	//      case EventB:
	//        [...]
	//    }
	//  }
	Subscribe(eventType interface{}, opts ...SubscriptionOpt) (Subscription, error)

	// Emitter 创建一个新的事件发射器。
	//
	// eventType 接受类型化的 nil 指针,并使用类型信息进行连接。
	//
	// 示例:
	//  em, err := eventbus.Emitter(new(EventT))
	//  defer em.Close() // 使用完发射器后必须调用此函数
	//  em.Emit(EventT{})
	Emitter(eventType interface{}, opts ...EmitterOpt) (Emitter, error)

	// GetAllEventTypes 返回此总线知道的所有事件类型(具有发射器和订阅者)。
	// 它会忽略 WildcardSubscription。
	//
	// 调用者可以保证此函数只返回值类型;
	// 不会返回指针类型。
	GetAllEventTypes() []reflect.Type
}

type CancelFunc = func()

type Emitter interface {
	io.Closer

	// Emit 在事件总线上发出一个事件。
	// 如果订阅该主题的任何通道被阻塞,Emit 的调用也会被阻塞。
	//
	// 使用错误的事件类型调用此函数将导致 panic。
	Emit(evt interface{}) error
}

type EmitterOpt = func(interface{}) error

type EvtLocalAddressesUpdated struct {

	// Diffs 表示此事件是否包含主机先前地址集的差异。
	Diffs bool

	// Current 包含主机的所有当前监听地址。
	// 如果 Diffs == true,则每个 UpdatedAddress 的 Action 字段将告诉你一个地址是被 Added,还是从先前状态 Maintained。
	Current []UpdatedAddress

	// Removed 包含从主机中移除的地址。
	// 此字段仅在 Diffs == true 时设置。
	Removed []UpdatedAddress

	// SignedPeerRecord 包含我们自己更新后的 peer.PeerRecord,列出了 Current 中枚举的地址。
	// 它被包装在 record.Envelope 中并由主机的私钥签名。
	SignedPeerRecord *record.Envelope
}

type EvtLocalProtocolsUpdated struct {
	// Added 列举了本地添加的协议。
	Added []protocol.ID
	// Removed 列举了本地移除的协议。
	Removed []protocol.ID
}

type EvtLocalReachabilityChanged struct {
	Reachability network.Reachability
}

type EvtNATDeviceTypeChanged struct {
	// TransportProtocol 是已确定 NAT 设备类型的传输协议。
	TransportProtocol network.NATTransportProtocol
	// NatDeviceType 表示该传输协议的 NAT 设备类型。
	// 目前可以是 `Cone NAT` 或 `Symmetric NAT`。
	// 请参阅 `network.NATDeviceType` 枚举的详细文档,以更好地理解这些类型的含义以及它们如何影响连接性和打洞。
	NatDeviceType network.NATDeviceType
}

type EvtPeerConnectednessChanged struct {
	// Peer 是连接状态发生变化的远程对等节点。
	Peer peer.ID
	// Connectedness 是新的连接状态。
	Connectedness network.Connectedness
}

type EvtPeerIdentificationCompleted struct {
	// Peer 是身份识别成功的对等节点的ID。
	Peer peer.ID

	// Conn 是我们识别的连接。
	Conn network.Conn

	// ListenAddrs 是对等节点正在监听的地址列表。
	ListenAddrs []multiaddr.Multiaddr

	// Protocols 是对等节点在此连接上公布的协议列表。
	Protocols []protocol.ID

	// SignedPeerRecord 是对等节点提供的已签名对等记录。可能为nil。
	SignedPeerRecord *record.Envelope

	// AgentVersion 类似于浏览器中的UserAgent字符串,或者BitTorrent中的客户端版本,
	// 包含客户端名称和客户端信息。
	AgentVersion string

	// ProtocolVersion 是identify消息中的协议版本字段。
	ProtocolVersion string

	// ObservedAddr 是对等节点观察到的我方连接地址。
	// 这未经验证,对等节点可能在此返回任何内容。
	ObservedAddr multiaddr.Multiaddr
}

type EvtPeerIdentificationFailed struct {
	// Peer 是身份识别失败的对等节点的ID。
	Peer peer.ID
	// Reason 是身份识别失败的原因。
	Reason error
}

type EvtPeerProtocolsUpdated struct {
	// Peer 是协议发生更新的对等节点。
	Peer peer.ID
	// Added 列举了该对等节点添加的协议。
	Added []protocol.ID
	// Removed 列举了该对等节点移除的协议。
	Removed []protocol.ID
}

type GenericDHTEvent struct {
	// Type 是发生的 DHT 事件的类型
	Type string

	// Raw 是事件载荷的原始 JSON 表示
	Raw RawJSON
}

type RawJSON string

type Subscription interface {
	io.Closer

	// Out 返回用于消费事件的通道。
	Out() <-chan interface{}

	// Name 返回订阅的名称
	Name() string
}

type SubscriptionOpt = func(interface{}) error

type UpdatedAddress struct {
	// Address 包含被更新的地址。
	Address ma.Multiaddr

	// Action 表示在事件期间对地址采取的操作。如果事件生产者无法生成差异,则可能为 Unknown。
	Action AddrAction
}