nodes

type NodeDescriptorLookup interface {
	// Lookup looks up a node descriptor given its identifier.
	Lookup(id signature.PublicKey) *node.Node

	// LookupByPeerID looks up a node descriptor given its P2P peer ID.
	LookupByPeerID(id signature.PublicKey) *node.Node

	// LookupTags looks up tags for a given node.
	LookupTags(id signature.PublicKey) []string

	// GetNodes returns current list of nodes.
	GetNodes() []*node.Node

	// WatchNodeUpdates subscribes to notifications about node descriptor updates.
	//
	// For non-Versioned descriptor lookups there should be NO Versioned events.
	// On subscription the current nodes will be sent immediately.
	WatchNodeUpdates() (<-chan *NodeUpdate, pubsub.ClosableSubscription, error)

	// Versioned returns true if this descriptor lookup is versioned.
	//
	// Versioned descriptor lookups are suitable to track versioned groups of nodes
	// (e.g. committees versioned by the group number), while non-versioned lookups
	// are suitable for watching non-versioned groups of nodes (e.g. all nodes,
	// or all nodes registered for a specific runtime).
	Versioned() bool
}

type NodeFilterFunc func(*node.Node, []string) bool

type NodeUpdate struct {
	Update *node.Node
	Delete *signature.PublicKey
	Reset  bool

	Freeze      *VersionEvent
	BumpVersion *VersionEvent
}

type VersionEvent struct {
	Version int64
}

type VersionedNodeDescriptorWatcher interface {
	NodeDescriptorLookup

	// Reset clears the watcher so it doesn't watch any nodes.
	Reset()

	// Freeze freezes the node descriptor watcher so no new nodes can be watched.
	//
	// In order to watch new nodes, the caller must first call Reset. Calling this method on an
	// already frozen watcher may result in a panic.
	//
	// The version argument may be used to signal which committee version this is.
	Freeze(version int64)

	// BumpVersion updates the committee version without performing a reset.
	//
	// This method may be used when the new committee version is exactly the same as the old one
	// without introducing a needless reset.
	//
	// The watcher must have previously been frozen. Calling this method on an unfrozen watcher may
	// result in a panic.
	BumpVersion(version int64)

	// WatchNode starts watching a given node.
	//
	// It returns the latest version of the node descriptor.
	WatchNode(ctx context.Context, id signature.PublicKey) (*node.Node, error)

	// WatchNodeWithTag starts watching a given node, tagging it with a specific tag.
	//
	// It returns the latest version of the node descriptor.
	WatchNodeWithTag(ctx context.Context, id signature.PublicKey, tag string) (*node.Node, error)
}