1package event
2
3import (
4	"github.com/libp2p/go-libp2p-core/record"
5	ma "github.com/multiformats/go-multiaddr"
6)
7
8// AddrAction represents an action taken on one of a Host's listen addresses.
9// It is used to add context to address change events in EvtLocalAddressesUpdated.
10type AddrAction int
11
12const (
13	// Unknown means that the event producer was unable to determine why the address
14	// is in the current state.
15	Unknown AddrAction = iota
16
17	// Added means that the address is new and was not present prior to the event.
18	Added
19
20	// Maintained means that the address was not altered between the current and
21	// previous states.
22	Maintained
23
24	// Removed means that the address was removed from the Host.
25	Removed
26)
27
28// UpdatedAddress is used in the EvtLocalAddressesUpdated event to convey
29// address change information.
30type UpdatedAddress struct {
31	// Address contains the address that was updated.
32	Address ma.Multiaddr
33
34	// Action indicates what action was taken on the address during the
35	// event. May be Unknown if the event producer cannot produce diffs.
36	Action AddrAction
37}
38
39// EvtLocalAddressesUpdated should be emitted when the set of listen addresses for
40// the local host changes. This may happen for a number of reasons. For example,
41// we may have opened a new relay connection, established a new NAT mapping via
42// UPnP, or been informed of our observed address by another peer.
43//
44// EvtLocalAddressesUpdated contains a snapshot of the current listen addresses,
45// and may also contain a diff between the current state and the previous state.
46// If the event producer is capable of creating a diff, the Diffs field will be
47// true, and event consumers can inspect the Action field of each UpdatedAddress
48// to see how each address was modified.
49//
50// For example, the Action will tell you whether an address in
51// the Current list was Added by the event producer, or was Maintained without
52// changes. Addresses that were removed from the Host will have the AddrAction
53// of Removed, and will be in the Removed list.
54//
55// If the event producer is not capable or producing diffs, the Diffs field will
56// be false, the Removed list will always be empty, and the Action for each
57// UpdatedAddress in the Current list will be Unknown.
58//
59// In addition to the above, EvtLocalAddressesUpdated also contains the updated peer.PeerRecord
60// for the Current set of listen addresses, wrapped in a record.Envelope and signed by the Host's private key.
61// This record can be shared with other peers to inform them of what we believe are our  diallable addresses
62// a secure and authenticated way.
63type EvtLocalAddressesUpdated struct {
64
65	// Diffs indicates whether this event contains a diff of the Host's previous
66	// address set.
67	Diffs bool
68
69	// Current contains all current listen addresses for the Host.
70	// If Diffs == true, the Action field of each UpdatedAddress will tell
71	// you whether an address was Added, or was Maintained from the previous
72	// state.
73	Current []UpdatedAddress
74
75	// Removed contains addresses that were removed from the Host.
76	// This field is only set when Diffs == true.
77	Removed []UpdatedAddress
78
79	// SignedPeerRecord contains our own updated peer.PeerRecord, listing the addresses enumerated in Current.
80	// wrapped in a record.Envelope and signed by the Host's private key.
81	SignedPeerRecord *record.Envelope
82}
83