event

Documentation

Overview

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.

Index

• Variables
• type AddrAction
• type Bus
• type CancelFunc
• type Emitter
• type EmitterOpt
• type EvtLocalAddressesUpdated
• type EvtLocalProtocolsUpdated
• type EvtLocalReachabilityChanged
• type EvtNATDeviceTypeChanged
• type EvtPeerConnectednessChanged
• type EvtPeerIdentificationCompleted
• type EvtPeerIdentificationFailed
• type EvtPeerProtocolsUpdated
• type GenericDHTEvent
• type RawJSON
• type Subscription
• type SubscriptionOpt
• type UpdatedAddress

Variables

var WildcardSubscription = new(wildcardSubscriptionType)

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

Types

type AddrAction

type AddrAction int

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 (
	// Unknown means that the event producer was unable to determine why the address
	// is in the current state.
	Unknown AddrAction = iota

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

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

	// Removed means that the address was removed from the Host.
	Removed
)

type Bus

type Bus interface {
	// 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:
	//        [...]
	//    }
	//  }
	Subscribe(eventType interface{}, opts ...SubscriptionOpt) (Subscription, error)

	// 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{})
	Emitter(eventType interface{}, opts ...EmitterOpt) (Emitter, error)

	// 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.
	GetAllEventTypes() []reflect.Type
}

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

type CancelFunc

type CancelFunc = func()

CancelFunc closes a subscriber.

type Emitter

type Emitter interface {
	io.Closer

	// 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.
	Emit(evt interface{}) error
}

Emitter represents an actor that emits events onto the eventbus.

type EmitterOpt

type EmitterOpt = func(interface{}) error

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

type EvtLocalAddressesUpdated

type EvtLocalAddressesUpdated struct {

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

	// 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.
	Current []UpdatedAddress

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

	// 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.
	SignedPeerRecord *record.Envelope
}

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.

type EvtLocalProtocolsUpdated

type EvtLocalProtocolsUpdated struct {
	// Added enumerates the protocols that were added locally.
	Added []protocol.ID
	// Removed enumerates the protocols that were removed locally.
	Removed []protocol.ID
}

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.

type EvtLocalReachabilityChanged

type EvtLocalReachabilityChanged struct {
	Reachability network.Reachability
}

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.

type EvtNATDeviceTypeChanged

type EvtNATDeviceTypeChanged struct {
	// TransportProtocol is the Transport Protocol for which the NAT Device Type has been determined.
	TransportProtocol network.NATTransportProtocol
	// 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.
	NatDeviceType network.NATDeviceType
}

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.

type EvtPeerConnectednessChanged

type EvtPeerConnectednessChanged struct {
	// Peer is the remote peer who's connectedness has changed.
	Peer peer.ID
	// Connectedness is the new connectedness state.
	Connectedness network.Connectedness
}

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 of 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 re-try network requests.

type EvtPeerIdentificationCompleted

type EvtPeerIdentificationCompleted struct {
	// Peer is the ID of the peer whose identification succeeded.
	Peer peer.ID
}

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

type EvtPeerIdentificationFailed

type EvtPeerIdentificationFailed struct {
	// Peer is the ID of the peer whose identification failed.
	Peer peer.ID
	// Reason is the reason why identification failed.
	Reason error
}

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

type EvtPeerProtocolsUpdated

type EvtPeerProtocolsUpdated struct {
	// Peer is the peer whose protocols were updated.
	Peer peer.ID
	// Added enumerates the protocols that were added by this peer.
	Added []protocol.ID
	// Removed enumerates the protocols that were removed by this peer.
	Removed []protocol.ID
}

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

type GenericDHTEvent

type GenericDHTEvent struct {
	// Type is the type of the DHT event that occured.
	Type string

	// Raw is the raw JSON representation of the event payload.
	Raw RawJSON
}

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.

type RawJSON

type RawJSON string

RawJSON is a type that contains a raw JSON string.

type Subscription

type Subscription interface {
	io.Closer

	// Out returns the channel from which to consume events.
	Out() <-chan interface{}

	// Name returns the name for the subscription
	Name() string
}

Subscription represents a subscription to one or multiple event types.

type SubscriptionOpt

type SubscriptionOpt = func(interface{}) error

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

type UpdatedAddress

type UpdatedAddress struct {
	// Address contains the address that was updated.
	Address ma.Multiaddr

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

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