package event

Import Path
	github.com/libp2p/go-libp2p/core/event (on go.dev)

Dependency Relation
	imports 7 packages, and imported by 14 packages


Involved Source Files

	    addrs.go
	    bus.go
	    dht.go
	
		Package event contains the abstractions for a local event bus, along with the standard events
		that libp2p subsystems may emit.
		
		Source code is arranged as follows:
		  - doc.go: this file.
		  - bus.go: abstractions for the event bus.
		  - rest: event structs, sensibly categorised in files by entity, and following this naming convention:
		    Evt[Entity (noun)][Event (verb past tense / gerund)]
		    The past tense is used to convey that something happened, whereas the gerund form of the verb (-ing)
		    expresses that a process is in progress. Examples: EvtConnEstablishing, EvtConnEstablished.

	    identify.go
	    nattype.go
	    network.go
	    protocol.go
	    reachability.go


Package-Level Type Names (total 20)


	/* sort by:  |  */
	
		AddrAction represents an action taken on one of a Host's listen addresses.
		It is used to add context to address change events in EvtLocalAddressesUpdated.

		
			const Added
			const Maintained
			const Removed
			const Unknown


	
		Bus is an interface for a type-based event delivery system.

		
			
				Emitter creates a new event emitter.
				
				eventType accepts typed nil pointers, and uses the type information for wiring purposes.
				
				Example:
				 em, err := eventbus.Emitter(new(EventT))
				 defer em.Close() // MUST call this after being done with the emitter
				 em.Emit(EventT{})

			
				GetAllEventTypes returns all the event types that this bus knows about
				(having emitters and subscribers). It omits the WildcardSubscription.
				
				The caller is guaranteed that this function will only return value types;
				no pointer types will be returned.

			
				Subscribe creates a new Subscription.
				
				eventType can be either a pointer to a single event type, or a slice of pointers to
				subscribe to multiple event types at once, under a single subscription (and channel).
				
				Failing to drain the channel may cause publishers to block.
				
				If you want to subscribe to ALL events emitted in the bus, use
				`WildcardSubscription` as the `eventType`:
				
				 eventbus.Subscribe(WildcardSubscription)
				
				Simple example
				
				 sub, err := eventbus.Subscribe(new(EventType))
				 defer sub.Close()
				 for e := range sub.Out() {
				   event := e.(EventType) // guaranteed safe
				   [...]
				 }
				
				Multi-type example
				
				 sub, err := eventbus.Subscribe([]interface{}{new(EventA), new(EventB)})
				 defer sub.Close()
				 for e := range sub.Out() {
				   select e.(type):
				     case EventA:
				       [...]
				     case EventB:
				       [...]
				   }
				 }

		
			func github.com/libp2p/go-libp2p/core/host.Host.EventBus() Bus
			func github.com/libp2p/go-libp2p/p2p/host/basic.(*BasicHost).EventBus() Bus
			func github.com/libp2p/go-libp2p/p2p/host/blank.(*BlankHost).EventBus() Bus
			func github.com/libp2p/go-libp2p/p2p/host/eventbus.NewBus(opts ...eventbus.Option) Bus
			func github.com/libp2p/go-libp2p/p2p/host/routed.(*RoutedHost).EventBus() Bus
		
			func github.com/libp2p/go-libp2p/p2p/host/blank.WithEventBus(eventBus Bus) blankhost.Option
			func github.com/libp2p/go-libp2p/p2p/host/pstoremanager.NewPeerstoreManager(pstore peerstore.Peerstore, eventBus Bus, network network.Network, opts ...pstoremanager.Option) (*pstoremanager.PeerstoreManager, error)
			func github.com/libp2p/go-libp2p/p2p/net/swarm.NewSwarm(local peer.ID, peers peerstore.Peerstore, eventBus Bus, opts ...swarm.Option) (*swarm.Swarm, error)


	
		CancelFunc closes a subscriber.


	
		Emitter represents an actor that emits events onto the eventbus.

		
			( Emitter) Close() error
			
				Emit emits an event onto the eventbus. If any channel subscribed to the topic is blocked,
				calls to Emit will block.
				
				Calling this function with wrong event type will cause a panic.

		
			 Emitter : github.com/prometheus/common/expfmt.Closer
			 Emitter : io.Closer
		
			func Bus.Emitter(eventType interface{}, opts ...EmitterOpt) (Emitter, error)


	
		EmitterOpt represents an emitter option. Use the options exposed by the implementation of choice.


	
		EvtAutoRelayAddrsUpdated is sent by the autorelay when the node's relay addresses are updated

		
			RelayAddrs []ma.Multiaddr


	
		EvtHostReachableAddrsChanged is sent when host's reachable or unreachable addresses change
		Reachable, Unreachable, and Unknown only contain Public IP or DNS addresses
		
		Experimental: This API is unstable. Any changes to this event will be done without a deprecation notice.

		
			Reachable []ma.Multiaddr
			Unknown []ma.Multiaddr
			Unreachable []ma.Multiaddr


	
		EvtLocalAddressesUpdated should be emitted when the set of listen addresses for
		the local host changes. This may happen for a number of reasons. For example,
		we may have opened a new relay connection, established a new NAT mapping via
		UPnP, or been informed of our observed address by another peer.
		
		EvtLocalAddressesUpdated contains a snapshot of the current listen addresses,
		and may also contain a diff between the current state and the previous state.
		If the event producer is capable of creating a diff, the Diffs field will be
		true, and event consumers can inspect the Action field of each UpdatedAddress
		to see how each address was modified.
		
		For example, the Action will tell you whether an address in
		the Current list was Added by the event producer, or was Maintained without
		changes. Addresses that were removed from the Host will have the AddrAction
		of Removed, and will be in the Removed list.
		
		If the event producer is not capable or producing diffs, the Diffs field will
		be false, the Removed list will always be empty, and the Action for each
		UpdatedAddress in the Current list will be Unknown.
		
		In addition to the above, EvtLocalAddressesUpdated also contains the updated peer.PeerRecord
		for the Current set of listen addresses, wrapped in a record.Envelope and signed by the Host's private key.
		This record can be shared with other peers to inform them of what we believe are our diallable addresses
		a secure and authenticated way.

		
			
				Current contains all current listen addresses for the Host.
				If Diffs == true, the Action field of each UpdatedAddress will tell
				you whether an address was Added, or was Maintained from the previous
				state.

			
				Diffs indicates whether this event contains a diff of the Host's previous
				address set.

			
				Removed contains addresses that were removed from the Host.
				This field is only set when Diffs == true.

			
				SignedPeerRecord contains our own updated peer.PeerRecord, listing the addresses enumerated in Current.
				wrapped in a record.Envelope and signed by the Host's private key.



	
		EvtLocalProtocolsUpdated should be emitted when stream handlers are attached or detached from the local host.
		For handlers attached with a matcher predicate (host.SetStreamHandlerMatch()), only the protocol ID will be
		included in this event.

		
			
				Added enumerates the protocols that were added locally.

			
				Removed enumerates the protocols that were removed locally.



	
		EvtLocalReachabilityChanged is an event struct to be emitted when the local's
		node reachability changes state.
		
		This event is usually emitted by the AutoNAT subsystem.

		
			Reachability network.Reachability


	
		EvtNATDeviceTypeChanged is an event struct to be emitted when the type of the NAT device changes for a Transport Protocol.
		
		Note: This event is meaningful ONLY if the AutoNAT Reachability is Private.
		Consumers of this event should ALSO consume the `EvtLocalReachabilityChanged` event and interpret
		this event ONLY if the Reachability on the `EvtLocalReachabilityChanged` is Private.

		
			
				NatDeviceType indicates the type of the NAT Device for the Transport Protocol.
				Currently, it can be either a `Cone NAT` or a `Symmetric NAT`. Please see the detailed documentation
				on `network.NATDeviceType` enumerations for a better understanding of what these types mean and
				how they impact Connectivity and Hole Punching.

			
				TransportProtocol is the Transport Protocol for which the NAT Device Type has been determined.



	
		EvtPeerConnectednessChanged should be emitted every time the "connectedness" to a
		given peer changes. Specifically, this event is emitted in the following
		cases:
		
		  - Connectedness = Connected: Every time we transition from having no
		    connections to a peer to having at least one connection to the peer.
		  - Connectedness = NotConnected: Every time we transition from having at least
		    one connection to a peer to having no connections to the peer.
		
		Additional connectedness states may be added in the future. This list should
		not be considered exhaustive.
		
		Take note:
		
		  - It's possible to have _multiple_ connections to a given peer.
		  - Both libp2p and networks are asynchronous.
		
		This means that all the following situations are possible:
		
		A connection is cut and is re-established:
		
		  - Peer A observes a transition from Connected -> NotConnected -> Connected
		  - Peer B observes a transition from Connected -> NotConnected -> Connected
		
		Explanation: Both peers observe the connection die. This is the "nice" case.
		
		A connection is cut and is re-established.
		
		  - Peer A observes a transition from Connected -> NotConnected -> Connected.
		  - Peer B observes no transition.
		
		Explanation: Peer A re-establishes the dead connection. Peer B observes the
		new connection form before it observes the old connection die.
		
		A connection is cut:
		
		  - Peer A observes no transition.
		  - Peer B observes no transition.
		
		Explanation: There were two connections and one was cut. This connection
		might have been in active use but neither peer will observe a change in
		"connectedness". Peers should always make sure to retry network requests.

		
			
				Connectedness is the new connectedness state.

			
				Peer is the remote peer whose connectedness has changed.



	
		EvtPeerIdentificationCompleted is emitted when the initial identification round for a peer is completed.

		
			
				AgentVersion is like a UserAgent string in browsers, or client version in
				bittorrent includes the client name and client.

			
				Conn is the connection we identified.

			
				ListenAddrs is the list of addresses the peer is listening on.

			
				ObservedAddr is the our side's connection address as observed by the
				peer. This is not verified, the peer could return anything here.

			
				Peer is the ID of the peer whose identification succeeded.

			
				ProtocolVersion is the protocolVersion field in the identify message

			
				Protocols is the list of protocols the peer advertised on this connection.

			
				SignedPeerRecord is the provided signed peer record of the peer. May be nil.



	
		EvtPeerIdentificationFailed is emitted when the initial identification round for a peer failed.

		
			
				Peer is the ID of the peer whose identification failed.

			
				Reason is the reason why identification failed.



	
		EvtPeerProtocolsUpdated should be emitted when a peer we're connected to adds or removes protocols from their stack.

		
			
				Added enumerates the protocols that were added by this peer.

			
				Peer is the peer whose protocols were updated.

			
				Removed enumerates the protocols that were removed by this peer.



	
		GenericDHTEvent is a type that encapsulates an actual DHT event by carrying
		its raw JSON.
		
		Context: the DHT event system is rather bespoke and a bit messy at the time,
		so until we unify/clean that up, this event bridges the gap. It should only
		be consumed for informational purposes.
		
		EXPERIMENTAL: this will likely be removed if/when the DHT event types are
		hoisted to core, and the DHT event system is reconciled with the eventbus.

		
			
				Raw is the raw JSON representation of the event payload.

			
				Type is the type of the DHT event that occurred.



	
		RawJSON is a type that contains a raw JSON string.


	
		Subscription represents a subscription to one or multiple event types.

		
			( Subscription) Close() error
			
				Name returns the name for the subscription

			
				Out returns the channel from which to consume events.

		
			 Subscription : github.com/polarsignals/frostdb/query/logicalplan.Named
			 Subscription : github.com/prometheus/common/expfmt.Closer
			 Subscription : io.Closer
		
			func Bus.Subscribe(eventType interface{}, opts ...SubscriptionOpt) (Subscription, error)


	
		SubscriptionOpt represents a subscriber option. Use the options exposed by the implementation of choice.


	
		UpdatedAddress is used in the EvtLocalAddressesUpdated event to convey
		address change information.

		
			
				Action indicates what action was taken on the address during the
				event. May be Unknown if the event producer cannot produce diffs.

			
				Address contains the address that was updated.





Package-Level Variables (only one)


	
		WildcardSubscription is the type to subscribe to receive all events
		emitted in the eventbus.




Package-Level Constants (total 4)


	
		Added means that the address is new and was not present prior to the event.


	
		Maintained means that the address was not altered between the current and
		previous states.


	
		Removed means that the address was removed from the Host.


	
		Unknown means that the event producer was unable to determine why the address
		is in the current state.