xorbie

package module
v0.0.19 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 1, 2026 License: Apache-2.0, MIT Imports: 23 Imported by: 0

README

xorbie

A network neutral Kademlia library.

Test Status go.dev reference

Architecture

Xorbie has been designed to provide deterministic behaviour with bounded use of memory and CPU, and to be fully testable in isolation from the network. It employs a passive state machine model to encapsulate the decision logic required to implement a Kademlia DHT. A passive state machine does not perform I/O or start goroutines; instead a caller advances it with the current time and an event, and it returns a state describing the action to take next. The caller carries out the network work and reports each outcome back as a further event. Time and every input arrive as arguments, so the same sequence of events produces the same result, and a test can drive a machine on any clock without a network. Each advance does a bounded amount of work, so a machine's demand on memory and CPU stays within known limits.

The Coordinator and its four behaviours wrap these machines in a running system and carry out the work the machines ask for.

Coordinator

The Coordinator is the main interface for integrating Xorbie into a DHT implementation. It holds the routing table and the network-size estimator, and exposes the operations a DHT implementation calls: finding the closest nodes to a key, sending a message to those nodes, and publishing a record. It runs a single event loop over the four behaviours. Each behaviour signals when it has work ready, the loop calls that behaviour to take its next step, and the event the step produces is routed to the behaviour that acts on it. One loop drives every behaviour, so at most one runs at any instant.

The single event loop is not the bottleneck it might appear. Almost all of a DHT's time is spent waiting on network I/O, which far outweighs the time spent advancing state machines: an advance takes a few microseconds, while a request waits hundreds of milliseconds for a reply. The requests themselves are carried out off the core loop, so while they are in flight the loop is free to advance other machines, feeding them the results of earlier requests or moving their internal state on. The loop is idle far more than it is busy.

RoutingBehaviour

The RoutingBehaviour maintains the routing table. It composes four state machines, each with its own concern:

  • Bootstrap fills an empty or short table by looking up the local node's own key and adding the neighbours it finds.
  • Include checks a newly discovered node's connectivity before admitting it to the table.
  • Probe re-checks nodes already in the table and removes any that fail a check or stop responding.
  • Explore fills sparse buckets by looking up synthesised keys that fall within them and offering the nodes it finds to Include.
QueryBehaviour

The QueryBehaviour coordinates the query pool. A query is one iterative Kademlia lookup that walks towards a target key. The pool holds the lookups in progress and bounds how many run at once. The behaviour runs the lookups a DHT implementation submits and reports each lookup's progress and final result to the caller that started it.

PublishBehaviour

The PublishBehaviour stores records with the nodes closest to their keys. It has two principal responsibilities:

The first is publishing a single record, run through a pool of publish strategies with one strategy per record, fixed when the publish starts:

  • Static stores the record with a quorum of nodes that is already known, without a lookup.
  • FollowUp looks up the nodes closest to a target key and stores the record once the lookup has settled.
  • Optimistic looks up the target key too, but stores the record on a node as soon as the walk shows the node is likely one of the closest, rather than waiting for the lookup to finish.

The second responsibility is re-announcing the records a node holds, which two machines drive together. Survey partitions the keyspace into regions and enumerates the members of each region in turn, spreading one pass over every region across a configured interval. As each region is surveyed the Region publish stores every key that falls on nodes in that region with the closest from those discovered in the survey.

NetworkBehaviour

The NetworkBehaviour is the only behaviour that communicates with other nodes. It sends the requests the other behaviours ask for and reports the responses back to them. It holds one handler per node, each sending to its node a single request at a time, and bounds the number of requests outstanding both per node and across all nodes.

The DHT implementation

Xorbie coordinates the outbound work of a Kademlia DHT: lookups, publishing and routing table maintenance. It is network-neutral: it does not hold addresses, define a wire format or assume a network's defaults. A DHT implementation supplies those and drives the Coordinator. Its responsibilities are:

  • Types and message contract. Define the key, node id and message types, and give a message its target key and the closer nodes carried in a reply.
  • Configuration. Supply the network's parameters and helpers: the replication factor, request timeouts, survey and explore intervals.
  • Lifecycle. Construct the Coordinator, initiate a bootstrap, and close it on shutdown.
  • Transport. Implement a router that fulfils Xorbie's request to send a message to a node and returns the reply using the DHT's chosen network stack.
  • Routing table. Provide a concrete routing table implementation for Xorbie to maintain.
  • Inbound requests. Answer requests from other nodes, returning closer nodes and storing and serving records.
  • Records. Hold the records the node is responsible for and supply the keys the survey re-announces.

License

SPDX-License-Identifier: Apache-2.0 OR MIT

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrEventDropped = errors.New("event dropped")

ErrEventDropped is the error reported to the caller of an operation whose event was dropped because the behaviour that would have carried it out had no queue space.

View Source 
var ErrRequestDropped = errors.New("request dropped")

ErrRequestDropped is the error reported for a request dropped because no capacity was available for it, either for the node it was addressed to or across all nodes.

Functions

This section is empty.

Types

type Behaviour 

type Behaviour[I BehaviourEvent, O BehaviourEvent] interface {
	// Ready returns a channel that signals when the behaviour is ready to perform work.
	// A behaviour must signal whenever it has work available, including work that has
	// become available through the passage of time rather than through an event. It may
	// signal when it has none.
	Ready() <-chan struct{}

	// Notify informs the behaviour of an event. The behaviour may perform the event
	// immediately and queue the result, causing the behaviour to become ready.
	// It is safe to call Notify from the Perform method.
	Notify(ctx context.Context, ev I)

	// Perform gives the behaviour the opportunity to perform work or to return a queued
	// result as an event.
	Perform(ctx context.Context) (O, bool)
}

Behaviour is a unit of the coordinator that consumes inbound events of type I and emits outbound events of type O.

type BehaviourEvent 

type BehaviourEvent interface {
	// contains filtered or unexported methods
}

BehaviourEvent is an event passed between the coordinator and its behaviours.

type BufferedRoutingNotifier 

type BufferedRoutingNotifier[K kad.Key[K], N kad.NodeID[K]] struct {
	// contains filtered or unexported fields
}

A BufferedRoutingNotifier is a RoutingNotifier that buffers RoutingNotification events and provides methods to expect occurrences of specific events. It is designed for use in a test environment.

func NewBufferedRoutingNotifier 

func NewBufferedRoutingNotifier[K kad.Key[K], N kad.NodeID[K]]() *BufferedRoutingNotifier[K, N]

NewBufferedRoutingNotifier returns a new BufferedRoutingNotifier.

func (*BufferedRoutingNotifier[K, N]) Expect 

func (w *BufferedRoutingNotifier[K, N]) Expect(ctx context.Context, expected RoutingNotification) (RoutingNotification, error)

Expect blocks until a RoutingNotification of the same type as expected is seen, or the context is done.

func (*BufferedRoutingNotifier[K, N]) ExpectRoutingRemoved 

func (w *BufferedRoutingNotifier[K, N]) ExpectRoutingRemoved(ctx context.Context, id N) (*EventRoutingRemoved[K, N], error)

ExpectRoutingRemoved blocks until an EventRoutingRemoved event is seen for the specified node id

func (*BufferedRoutingNotifier[K, N]) ExpectRoutingUpdated 

func (w *BufferedRoutingNotifier[K, N]) ExpectRoutingUpdated(ctx context.Context, id N) (*EventRoutingUpdated[K, N], error)

ExpectRoutingUpdated blocks until an EventRoutingUpdated event is seen for the specified node id

func (*BufferedRoutingNotifier[K, N]) Notify 

func (w *BufferedRoutingNotifier[K, N]) Notify(ctx context.Context, ev RoutingNotification)

type Coordinator 

type Coordinator[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	// contains filtered or unexported fields
}

A Coordinator coordinates the state machines that comprise a Kademlia DHT

func NewCoordinator 

func NewCoordinator[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]](
	self N,
	rtr coordt.Router[K, N, M],
	rt routing.RoutingTableCpl[K, N],
	cfg *CoordinatorConfig[K, N, M],
) (*Coordinator[K, N, M], error)

NewCoordinator creates a Coordinator, starts its event loop and returns it.

func (*Coordinator[K, N, M]) AddNodes 

func (c *Coordinator[K, N, M]) AddNodes(ctx context.Context, ids []N) error

AddNodes suggests new DHT nodes to be added to the routing table. If the routing table is updated as a result of this operation an EventRoutingUpdated notification is emitted on the routing notification channel.

func (*Coordinator[K, N, M]) Bootstrap 

func (c *Coordinator[K, N, M]) Bootstrap(ctx context.Context) error

Bootstrap instructs the dht to begin bootstrapping the routing table from the nodes configured as RoutingConfig.BootstrapPeers. A bootstrap also starts automatically whenever the routing table holds fewer than RoutingConfig.BootstrapMinimumPopulation nodes.

func (*Coordinator[K, N, M]) Close 

func (c *Coordinator[K, N, M]) Close() error

Close cleans up all resources associated with this Coordinator.

func (*Coordinator[K, N, M]) GetClosestNodes 

func (c *Coordinator[K, N, M]) GetClosestNodes(ctx context.Context, k K, n int) ([]N, error)

GetClosestNodes requests the n closest nodes to the key from the node's local routing table.

func (*Coordinator[K, N, M]) ID 

func (c *Coordinator[K, N, M]) ID() N

ID returns the node id the coordinator runs on.

func (*Coordinator[K, N, M]) IsRoutable 

func (c *Coordinator[K, N, M]) IsRoutable(ctx context.Context, id N) bool

IsRoutable reports whether the supplied node is present in the local routing table.

func (*Coordinator[K, N, M]) NetworkSize added in v0.0.6 

func (c *Coordinator[K, N, M]) NetworkSize() (netsize.Estimate, error)

NetworkSize reports the estimated number of nodes in the network, measured from the results of the lookups the coordinator has performed. It returns netsize.ErrNotEnoughData when too few lookups have completed for an estimate to be made.

func (*Coordinator[K, N, M]) NotifyConnectivity 

func (c *Coordinator[K, N, M]) NotifyConnectivity(ctx context.Context, id N)

NotifyConnectivity notifies the coordinator that a node has passed a connectivity check which means it is connected and supports finding closer nodes

func (*Coordinator[K, N, M]) NotifyNonConnectivity 

func (c *Coordinator[K, N, M]) NotifyNonConnectivity(ctx context.Context, id N)

NotifyNonConnectivity notifies the coordinator that a node has failed a connectivity check which means it is not connected and/or it doesn't support finding closer nodes

func (*Coordinator[K, N, M]) Publish added in v0.0.14 

func (c *Coordinator[K, N, M]) Publish(ctx context.Context, msg M) (coordt.PublishStats, error)

Publish stores msg with the nodes closest to its key, selecting the most efficient strategy it can. It tries the optimistic strategy first and falls back to the follow up strategy when the network size is not yet known. It returns when the publish has finished, with the counts of what it did.

func (*Coordinator[K, N, M]) PublishFollowUp added in v0.0.11 

func (c *Coordinator[K, N, M]) PublishFollowUp(ctx context.Context, msg M) (coordt.PublishStats, error)

PublishFollowUp stores msg with the nodes closest to its key, waiting until the lookup for that key has settled before following up by sending the message. It returns when the publish has finished, with the counts of what it did.

func (*Coordinator[K, N, M]) PublishOptimistic added in v0.0.11 

func (c *Coordinator[K, N, M]) PublishOptimistic(ctx context.Context, msg M) (coordt.PublishStats, error)

PublishOptimistic stores msg with nodes close to its key, storing with each node as the lookup finds it rather than waiting for the lookup to settle. It returns when the publish has finished, with the counts of what it did.

The strategy derives its distance thresholds from the size of the network, which is not known until enough lookups have completed. Until then this stores nothing and returns netsize.ErrNotEnoughData, leaving the caller to fall back to Coordinator.PublishFollowUp.

func (*Coordinator[K, N, M]) PublishStatic added in v0.0.11 

func (c *Coordinator[K, N, M]) PublishStatic(ctx context.Context, msg M, nodes []N, quorum int) (coordt.PublishStats, error)

PublishStatic stores msg with the given nodes only, succeeding once quorum of them store the record. It returns when the publish has finished, with the counts of what it did.

func (*Coordinator[K, N, M]) QueryClosest 

func (c *Coordinator[K, N, M]) QueryClosest(ctx context.Context, target K, fn coordt.QueryFunc[K, N, M], numResults int) ([]N, coordt.QueryStats, error)

QueryClosest starts a query that attempts to find the closest nodes to the target key. It returns the closest nodes found to the target key and statistics on the actions of the query.

The supplied [QueryFunc] is called after each successful request to a node with the ID of the node, the response received from the find nodes request made to the node and the current query stats. The query terminates when [QueryFunc] returns an error or when the query has visited the configured minimum number of closest nodes. fn may be nil, in which case the query terminates only when it has visited the configured minimum number of closest nodes.

numResults specifies the minimum number of nodes to successfully contact before considering iteration complete. The query is considered to be exhausted when it has received responses from at least this number of nodes and there are no closer nodes remaining to be contacted. CoordinatorConfig.ReplicationFactor is used if this value is less than 1.

func (*Coordinator[K, N, M]) QueryMessage 

func (c *Coordinator[K, N, M]) QueryMessage(ctx context.Context, msg M, fn coordt.QueryFunc[K, N, M], numResults int) ([]N, coordt.QueryStats, error)

QueryMessage starts a query that iterates over the closest nodes to the target key in the supplied message. The message is sent to each node that is visited.

The supplied [QueryFunc] is called after each successful request to a node with the ID of the node, the response received from the find nodes request made to the node and the current query stats. The query terminates when [QueryFunc] returns an error or when the query has visited the configured minimum number of closest nodes. fn may be nil, in which case the query terminates only when it has visited the configured minimum number of closest nodes.

numResults specifies the minimum number of nodes to successfully contact before considering iteration complete. The query is considered to be exhausted when it has received responses from at least this number of nodes and there are no closer nodes remaining to be contacted. CoordinatorConfig.ReplicationFactor is used if this value is less than 1.

func (*Coordinator[K, N, M]) SetRoutingNotifier 

func (c *Coordinator[K, N, M]) SetRoutingNotifier(rn RoutingNotifier)

SetRoutingNotifier registers rn as the sink for routing notifications, replacing any previous one.

type CoordinatorConfig 

type CoordinatorConfig[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	// Logger is a structured logger that will be used when logging.
	Logger *slog.Logger

	// MeterProvider is the the meter provider to use when initialising metric instruments.
	MeterProvider metric.MeterProvider

	// TracerProvider is the tracer provider to use when initialising tracing
	TracerProvider trace.TracerProvider

	// ReplicationFactor is the number of nodes a record is stored with, which is also the
	// number of closest nodes a lookup converges on and the number of nodes an operation
	// seeds itself with. Kademlia calls this k.
	ReplicationFactor int

	// Network is the configuration used for the [NetworkBehaviour] which sends requests to other nodes.
	Network NetworkConfig

	// Routing is the configuration used for the [RoutingBehaviour] which maintains the health of the routing table.
	Routing RoutingConfig[K, N]

	// Query is the configuration used for the [QueryBehaviour] which manages the execution of user queries.
	Query QueryConfig[K, N]

	// Publish is the configuration used for the [PublishBehaviour] which manages the storing of records with other nodes.
	Publish PublishConfig[K, N, M]
}

CoordinatorConfig configures a Coordinator.

func DefaultCoordinatorConfig 

func DefaultCoordinatorConfig[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]]() *CoordinatorConfig[K, N, M]

DefaultCoordinatorConfig returns a CoordinatorConfig with default values.

func (*CoordinatorConfig[K, N, M]) Validate 

func (cfg *CoordinatorConfig[K, N, M]) Validate() error

Validate checks the configuration options and returns an error if any have invalid values.

type CtxEvent 

type CtxEvent[E any] struct {
	Ctx   context.Context
	Event E
}

CtxEvent holds and event with an associated context which may carry deadlines or tracing information pertinent to the event.

type EventAddNode 

type EventAddNode[K kad.Key[K], N kad.NodeID[K]] struct {
	NodeID N
}

EventAddNode notifies the routing behaviour of a potential new node.

type EventBootstrapFinished 

type EventBootstrapFinished struct {
	Stats query.QueryStats

	// Err records why the bootstrap ended when it ended for a reason other than visiting
	// every node it could, and is nil otherwise.
	Err error
}

EventBootstrapFinished is emitted by the coordinator when a bootstrap has finished, either through running to completion or by being canceled.

type EventGetCloserNodesFailure 

type EventGetCloserNodesFailure[K kad.Key[K], N kad.NodeID[K]] struct {
	ActivityID coordt.ActivityID
	To         N // To is the node that the GetCloserNodes request was sent to.
	Target     K
	Err        error
}

EventGetCloserNodesFailure notifies a behaviour that a GetCloserNodes request, initiated by an EventOutboundGetCloserNodes event has failed to produce a valid response.

type EventGetCloserNodesSuccess 

type EventGetCloserNodesSuccess[K kad.Key[K], N kad.NodeID[K]] struct {
	ActivityID  coordt.ActivityID
	To          N // To is the node that the GetCloserNodes request was sent to.
	Target      K
	CloserNodes []N
}

EventGetCloserNodesSuccess notifies a behaviour that a GetCloserNodes request, initiated by an EventOutboundGetCloserNodes event has produced a successful response.

type EventNotifyConnectivity 

type EventNotifyConnectivity[K kad.Key[K], N kad.NodeID[K]] struct {
	NodeID N
}

EventNotifyConnectivity notifies a behaviour that a node's connectivity and support for finding closer nodes has been confirmed such as from a successful query response or an inbound query. This should not be used for general connections to the host but only when it is confirmed that the node responds to requests for closer nodes.

type EventNotifyNonConnectivity 

type EventNotifyNonConnectivity[K kad.Key[K], N kad.NodeID[K]] struct {
	NodeID N
}

EventNotifyNonConnectivity notifies a behaviour that a node does not have connectivity and/or does not support finding closer nodes is known.

type EventOutboundGetCloserNodes 

type EventOutboundGetCloserNodes[K kad.Key[K], N kad.NodeID[K]] struct {
	ActivityID coordt.ActivityID
	To         N
	Target     K
	Deadline   time.Time
	Notify     Notify[BehaviourEvent]
}

EventOutboundGetCloserNodes instructs the NetworkBehaviour to ask a node for the nodes closest to a target key.

type EventOutboundSendMessage 

type EventOutboundSendMessage[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	ActivityID coordt.ActivityID
	To         N
	Message    M
	Deadline   time.Time
	Notify     Notify[BehaviourEvent]
}

EventOutboundSendMessage instructs the NetworkBehaviour to send a message to a node.

type EventPublishFinished added in v0.0.11 

type EventPublishFinished[K kad.Key[K], N kad.NodeID[K]] struct {
	ActivityID coordt.ActivityID
	Contacted  []N
	Errors     map[string]struct {
		Node N
		Err  error
	}

	// QueryStats holds the stats of the lookup that found the nodes the record was stored
	// with, and is zero for a publish that ran no lookup.
	QueryStats query.QueryStats

	// Err records why the publish ended when it ended without being attempted, and is
	// nil otherwise. A publish that ran records per node outcomes in Errors instead.
	Err error
}

EventPublishFinished is emitted by the coordinator when a publishing a record to the network has finished, either through running to completion or by being canceled.

type EventQueryFinished 

type EventQueryFinished[K kad.Key[K], N kad.NodeID[K]] struct {
	ActivityID   coordt.ActivityID
	Stats        query.QueryStats
	ClosestNodes []N

	// Err records why the query ended when it ended for a reason other than visiting
	// every node it could, and is nil otherwise. ClosestNodes is not populated when
	// Err is set.
	Err error
}

EventQueryFinished is emitted by the coordinator when a query has finished, either through running to completion or by being canceled.

type EventQueryProgressed 

type EventQueryProgressed[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	ActivityID coordt.ActivityID
	NodeID     N
	Response   M
	Stats      query.QueryStats
}

EventQueryProgressed is emitted by the coordinator when a query has received a response from a node.

type EventRoutingPoll 

type EventRoutingPoll struct{}

EventRoutingPoll notifies a routing behaviour that it may proceed with any pending work.

type EventRoutingRemoved 

type EventRoutingRemoved[K kad.Key[K], N kad.NodeID[K]] struct {
	NodeID N
}

EventRoutingRemoved is emitted by the coordinator when new node has been removed from the routing table.

type EventRoutingUpdated 

type EventRoutingUpdated[K kad.Key[K], N kad.NodeID[K]] struct {
	NodeID N
}

EventRoutingUpdated is emitted by the coordinator when a new node has been verified and added to the routing table.

type EventSendMessageFailure 

type EventSendMessageFailure[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	ActivityID coordt.ActivityID
	Request    M
	To         N // To is the node that the SendMessage request was sent to.
	Target     K
	Err        error
}

EventSendMessageFailure notifies a behaviour that a SendMessage request, initiated by an EventOutboundSendMessage event has failed to produce a valid response.

type EventSendMessageSuccess 

type EventSendMessageSuccess[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	ActivityID  coordt.ActivityID
	Request     M
	To          N // To is the node that the SendMessage request was sent to.
	Response    M
	CloserNodes []N
}

EventSendMessageSuccess notifies a behaviour that a SendMessage request, initiated by an EventOutboundSendMessage event has produced a successful response.

type EventStartBootstrap 

type EventStartBootstrap[K kad.Key[K], N kad.NodeID[K]] struct {
	// SeedNodes are the nodes the bootstrap should start from. When empty the nodes
	// configured as [RoutingConfig.BootstrapPeers] are used.
	SeedNodes []N
}

EventStartBootstrap instructs the RoutingBehaviour to start a bootstrap.

type EventStartFindCloserQuery 

type EventStartFindCloserQuery[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	ActivityID        coordt.ActivityID
	Target            K
	KnownClosestNodes []N
	Notify            QueryMonitor[K, N, M, *EventQueryFinished[K, N]]
	NumResults        int // the minimum number of nodes to successfully contact before considering iteration complete
}

EventStartFindCloserQuery instructs the QueryBehaviour to start a query for the nodes closest to a target key.

type EventStartFollowUpPublish added in v0.0.11 

type EventStartFollowUpPublish[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	ActivityID        coordt.ActivityID
	Target            K
	Message           M
	KnownClosestNodes []N
	Notify            QueryMonitor[K, N, M, *EventPublishFinished[K, N]]
}

EventStartFollowUpPublish starts a publish that finds the nodes closest to the target key before storing the record with any of them.

type EventStartMessageQuery 

type EventStartMessageQuery[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	ActivityID        coordt.ActivityID
	Target            K
	Message           M
	KnownClosestNodes []N
	Notify            QueryMonitor[K, N, M, *EventQueryFinished[K, N]]
	NumResults        int // the minimum number of nodes to successfully contact before considering iteration complete
}

EventStartMessageQuery instructs the QueryBehaviour to start a query that sends a message to each node it visits.

type EventStartOptimisticPublish added in v0.0.11 

type EventStartOptimisticPublish[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	ActivityID        coordt.ActivityID
	Target            K
	Message           M
	KnownClosestNodes []N
	NetworkSize       int
	Notify            QueryMonitor[K, N, M, *EventPublishFinished[K, N]]
}

EventStartOptimisticPublish starts a publish that stores the record with nodes as the walk towards the target key finds them.

type EventStartStaticPublish added in v0.0.11 

type EventStartStaticPublish[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	ActivityID coordt.ActivityID
	Target     K
	Message    M
	Nodes      []N
	Quorum     int
	Notify     QueryMonitor[K, N, M, *EventPublishFinished[K, N]]
}

EventStartStaticPublish starts a publish that stores the record with a fixed set of nodes, succeeding once Quorum of them store it.

type EventStopQuery 

type EventStopQuery struct {
	ActivityID coordt.ActivityID
}

EventStopQuery instructs the QueryBehaviour to stop a running query.

type NetworkBehaviour 

type NetworkBehaviour[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	// contains filtered or unexported fields
}

NetworkBehaviour sends requests to other nodes through a node handler per node.

func NewNetworkBehaviour 

func NewNetworkBehaviour[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]](rtr coordt.Router[K, N, M], cfg *NetworkConfig) (*NetworkBehaviour[K, N, M], error)

NewNetworkBehaviour returns a new NetworkBehaviour that sends requests through rtr.

func (*NetworkBehaviour[K, N, M]) Close 

func (b *NetworkBehaviour[K, N, M]) Close()

Close stops all the node handlers managed by the behaviour, releasing the goroutines they use to send messages. It is safe to call Close more than once.

func (*NetworkBehaviour[K, N, M]) Notify 

func (b *NetworkBehaviour[K, N, M]) Notify(ctx context.Context, ev BehaviourEvent)

Notify hands a request to the node handler for the node it is addressed to. It does not block: a request that finds no available capacity is dropped and reported back to whoever asked for it as an ordinary failure, since blocking here would stop the event loop that is the only thing able to drain the handler.

func (*NetworkBehaviour[K, N, M]) Perform 

func (b *NetworkBehaviour[K, N, M]) Perform(ctx context.Context) (BehaviourEvent, bool)

func (*NetworkBehaviour[K, N, M]) Ready 

func (b *NetworkBehaviour[K, N, M]) Ready() <-chan struct{}

type NetworkCommand 

type NetworkCommand interface {
	BehaviourEvent
	// contains filtered or unexported methods
}

NetworkCommand is a type of BehaviourEvent that instructs a NetworkBehaviour to perform an action.

type NetworkConfig 

type NetworkConfig struct {
	// Logger is a structured logger that will be used when logging.
	Logger *slog.Logger

	// Tracer is the tracer that should be used to trace execution.
	Tracer trace.Tracer

	// Meter is the meter that should be used to record metrics.
	Meter metric.Meter

	// Capacity is the maximum number of requests that may be queued or in flight across
	// all nodes.
	Capacity int

	// NodeCapacity is the maximum number of requests that may be queued or in flight for
	// any one node.
	NodeCapacity int

	// IdleTimeout is how long an unused node handler is kept before it is evicted and the
	// goroutine it uses to send messages is released.
	IdleTimeout time.Duration
}

NetworkConfig configures a NetworkBehaviour.

func DefaultNetworkConfig 

func DefaultNetworkConfig() *NetworkConfig

DefaultNetworkConfig returns a NetworkConfig with default values.

func (*NetworkConfig) Validate 

func (cfg *NetworkConfig) Validate() error

Validate checks the configuration options and returns an error if any have invalid values.

type NodeHandler 

type NodeHandler[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	// contains filtered or unexported fields
}

A NodeHandler sends requests to a single node, one at a time, from a goroutine of its own. Requests that arrive with no available capacity are dropped rather than queued.

func NewNodeHandler 

func NewNodeHandler[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]](self N, rtr coordt.Router[K, N, M], slots *slots, cfg *NetworkConfig, onIdle func(*NodeHandler[K, N, M]) bool) *NodeHandler[K, N, M]

NewNodeHandler returns a new NodeHandler that sends requests to node self through rtr.

func (*NodeHandler[K, N, M]) Close 

func (h *NodeHandler[K, N, M]) Close()

Close stops the handler from sending any further requests and discards the requests it has accepted but not yet sent. It is safe to call Close more than once.

func (*NodeHandler[K, N, M]) ID 

func (h *NodeHandler[K, N, M]) ID() N

ID returns the id of the node the handler sends requests to.

func (*NodeHandler[K, N, M]) Notify 

func (h *NodeHandler[K, N, M]) Notify(ctx context.Context, ev NodeHandlerRequest) bool

Notify accepts a request to be sent to the handler's node, reporting whether capacity was available for it. It does not block.

type NodeHandlerRequest 

type NodeHandlerRequest interface {
	BehaviourEvent
	// contains filtered or unexported methods
}

NodeHandlerRequest is a BehaviourEvent a node handler sends to its node.

type NodeHandlerResponse 

type NodeHandlerResponse interface {
	BehaviourEvent
	// contains filtered or unexported methods
}

NodeHandlerResponse is a BehaviourEvent carrying a node's reply back to the behaviour that made the request.

type Notify 

type Notify[E BehaviourEvent] interface {
	Notify(ctx context.Context, ev E)
}

Notify is the interface that a components to implement to be notified of BehaviourEvent's.

type NotifyFunc 

type NotifyFunc[E BehaviourEvent] func(ctx context.Context, ev E)

NotifyFunc adapts a function to the Notify interface.

func (NotifyFunc[E]) Notify 

func (f NotifyFunc[E]) Notify(ctx context.Context, ev E)

type PublishBehaviour added in v0.0.11 

type PublishBehaviour[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	// contains filtered or unexported fields
}

PublishBehaviour stores records with other nodes and runs the region survey and reprovide.

func NewPublishBehaviour added in v0.0.11 

func NewPublishBehaviour[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]](publishPool *publish.Pool[K, N, M], self N, rt kad.RoutingTable[K, N], cfg *PublishConfig[K, N, M]) (*PublishBehaviour[K, N, M], error)

NewPublishBehaviour returns a new PublishBehaviour that publishes through publishPool.

func (*PublishBehaviour[K, N, M]) Notify added in v0.0.11 

func (b *PublishBehaviour[K, N, M]) Notify(ctx context.Context, ev BehaviourEvent)

func (*PublishBehaviour[K, N, M]) Perform added in v0.0.11 

func (b *PublishBehaviour[K, N, M]) Perform(ctx context.Context) (out BehaviourEvent, performed bool)

func (*PublishBehaviour[K, N, M]) Ready added in v0.0.11 

func (b *PublishBehaviour[K, N, M]) Ready() <-chan struct{}

type PublishCommand added in v0.0.11 

type PublishCommand interface {
	BehaviourEvent
	// contains filtered or unexported methods
}

PublishCommand is a type of BehaviourEvent that instructs a PublishBehaviour to perform an action.

type PublishConfig added in v0.0.11 

type PublishConfig[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	// Logger is a structured logger that will be used when logging.
	Logger *slog.Logger

	// Tracer is the tracer that should be used to trace execution.
	Tracer trace.Tracer

	// Meter is the meter that should be used to record metrics.
	Meter metric.Meter

	// QueueCapacity is the maximum number of events that may be waiting to be processed by
	// the behaviour. Events arriving when the queue is full are dropped. It must be larger
	// than [NetworkConfig.Capacity], since a node handler queues a response here before
	// releasing the capacity it held, so that many responses can be waiting at once.
	QueueCapacity int

	// VerifyResponse reports whether a node's reply to a stored record shows that it stored
	// the record, returning a nil error when it did. A nil VerifyResponse takes every reply
	// that is not itself an error as a success.
	VerifyResponse func(req, resp M) error

	// OptimisticIndividualCertainty is how sure an optimistic publish must be that a node it
	// stores with during its lookup is really one of the ReplicationFactor closest to the key.
	OptimisticIndividualCertainty float64

	// OptimisticSetStrictness is the probability that the closest set is in fact further from
	// the key than an optimistic publish's set threshold.
	OptimisticSetStrictness float64

	// Keystore enumerates the keys this node provides by prefix, so a region publish can find
	// every key inside a surveyed region. Region publishing is disabled if it is nil.
	Keystore keystore.Keystore[K]

	// RecordSource builds the message that stores a region key. Region publishing is disabled
	// if it is nil.
	RecordSource func(k K) M

	// RegionReplication is the number of closest nodes a region publish stores each key with.
	RegionReplication int

	// RegionMaxInFlight is the greatest number of per-key publishes a region publish may have in
	// flight at once.
	RegionMaxInFlight int

	// EnableSurvey turns on the region survey, which keeps a region map current by surveying each
	// region on a schedule. When enabled a survey target function must be supplied.
	EnableSurvey bool

	// SurveyTargetFunc mints a key inside a region from its prefix, used to survey the region. It
	// must be supplied when the survey is enabled.
	SurveyTargetFunc publish.PrefixTargetFunc[K]

	// SurveyInterval is the time within which every region in the network is surveyed once.
	SurveyInterval time.Duration

	// SurveyRegionTimeout is the maximum time to allow for surveying a region.
	SurveyRegionTimeout time.Duration

	// SurveyRequestConcurrency is the maximum number of concurrent requests that a region survey may have in flight.
	SurveyRequestConcurrency int

	// SurveyRequestTimeout is the timeout the behaviour should use when attempting to contact a node while surveying a region.
	SurveyRequestTimeout time.Duration

	// SurveyWalkInBound is the number of nodes a region survey contacts without finding a region member
	// before concluding the region is empty.
	SurveyWalkInBound int

	// SurveyInitialPrefixLen is the prefix length the region map is seeded with, giving 2^SurveyInitialPrefixLen regions.
	SurveyInitialPrefixLen int

	// SurveyMinPopulation is the region population at or below which two sibling regions merge.
	SurveyMinPopulation int

	// SurveyMaxPopulation is the region population above which a region splits.
	SurveyMaxPopulation int
}

PublishConfig configures a PublishBehaviour.

func DefaultPublishConfig added in v0.0.11 

func DefaultPublishConfig[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]]() *PublishConfig[K, N, M]

DefaultPublishConfig returns a PublishConfig with default values.

func (*PublishConfig[K, N, M]) Validate added in v0.0.11 

func (cfg *PublishConfig[K, N, M]) Validate() error

Validate checks the configuration options and returns an error if any have invalid values.

type PublishWaiter added in v0.0.11 

type PublishWaiter[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	// contains filtered or unexported fields
}

A PublishWaiter implements QueryMonitor for publishes

func NewPublishWaiter added in v0.0.11 

func NewPublishWaiter[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]](n int) *PublishWaiter[K, N, M]

NewPublishWaiter returns a PublishWaiter whose progress channel buffers n events.

func (*PublishWaiter[K, N, M]) Finished added in v0.0.11 

func (w *PublishWaiter[K, N, M]) Finished() <-chan CtxEvent[*EventPublishFinished[K, N]]

func (*PublishWaiter[K, N, M]) NotifyFinished added in v0.0.11 

func (w *PublishWaiter[K, N, M]) NotifyFinished() chan<- CtxEvent[*EventPublishFinished[K, N]]

func (*PublishWaiter[K, N, M]) NotifyProgressed added in v0.0.11 

func (w *PublishWaiter[K, N, M]) NotifyProgressed() chan<- CtxEvent[*EventQueryProgressed[K, N, M]]

func (*PublishWaiter[K, N, M]) Progressed added in v0.0.11 

func (w *PublishWaiter[K, N, M]) Progressed() <-chan CtxEvent[*EventQueryProgressed[K, N, M]]

type QueryBehaviour 

type QueryBehaviour[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	// contains filtered or unexported fields
}

QueryBehaviour holds the behaviour and state for managing a pool of queries.

func NewQueryBehaviour 

func NewQueryBehaviour[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]](self N, cfg *QueryConfig[K, N]) (*QueryBehaviour[K, N, M], error)

NewQueryBehaviour initialises a new QueryBehaviour, setting up the query pool and other internal state.

func (*QueryBehaviour[K, N, M]) Notify 

func (p *QueryBehaviour[K, N, M]) Notify(ctx context.Context, ev BehaviourEvent)

Notify receives a behaviour event and takes appropriate actions such as starting, stopping, or updating queries. It also queues events for later processing and triggers the advancement of the query pool if applicable.

func (*QueryBehaviour[K, N, M]) Perform 

func (p *QueryBehaviour[K, N, M]) Perform(ctx context.Context) (out BehaviourEvent, performed bool)

Perform executes the next available task from the queue of pending events or advances the query pool. Returns an event containing the result of the work performed and a true value, or nil and a false value if no event was generated.

func (*QueryBehaviour[K, N, M]) Ready 

func (p *QueryBehaviour[K, N, M]) Ready() <-chan struct{}

Ready returns a channel that signals when the query behaviour is ready to perform work.

type QueryCommand 

type QueryCommand interface {
	BehaviourEvent
	// contains filtered or unexported methods
}

QueryCommand is a type of BehaviourEvent that instructs a QueryBehaviour to perform an action.

type QueryConfig 

type QueryConfig[K kad.Key[K], N kad.NodeID[K]] struct {
	// Logger is a structured logger that will be used when logging.
	Logger *slog.Logger

	// Tracer is the tracer that should be used to trace execution.
	Tracer trace.Tracer

	// Meter is the meter that should be used to record metrics.
	Meter metric.Meter

	// NetworkSize is the estimator that the results of completed queries are reported to.
	// A nil estimator means results are not reported.
	NetworkSize *netsize.Estimator[K, N]

	// QueueCapacity is the maximum number of events that may be waiting to be processed by
	// the behaviour. Events arriving when the queue is full are dropped. It must be larger
	// than [NetworkConfig.Capacity], since a node handler queues a response here before
	// releasing the capacity it held, so that many responses can be waiting at once.
	QueueCapacity int

	// Concurrency is the maximum number of queries that may be waiting for message responses at any one time.
	Concurrency int

	// Timeout the time to wait before terminating a query that is not making progress.
	Timeout time.Duration

	// RequestConcurrency is the maximum number of concurrent requests that each query may have in flight.
	RequestConcurrency int

	// RequestTimeout is the timeout queries should use for contacting a single node
	RequestTimeout time.Duration
}

QueryConfig configures a QueryBehaviour.

func DefaultQueryConfig 

func DefaultQueryConfig[K kad.Key[K], N kad.NodeID[K]]() *QueryConfig[K, N]

DefaultQueryConfig returns a QueryConfig with default values.

func (*QueryConfig[K, N]) Validate 

func (cfg *QueryConfig[K, N]) Validate() error

Validate checks the configuration options and returns an error if any have invalid values.

type QueryMonitor 

type QueryMonitor[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N], E TerminalQueryEvent] interface {
	// NotifyProgressed returns a channel that can be used to send notification that a
	// query has made progress. If the notification cannot be sent then it will be
	// queued and retried at a later time. If the query completes before the progress
	// notification can be sent the notification will be discarded.
	NotifyProgressed() chan<- CtxEvent[*EventQueryProgressed[K, N, M]]

	// NotifyFinished returns a channel that can be used to send the notification that a
	// query has completed. It is up to the implemention to ensure that the channel has enough
	// capacity to receive the single notification.
	// The sender must close all other QueryNotifier channels before sending on the NotifyFinished channel.
	// The sender may attempt to drain any pending notifications before closing the other channels.
	// The NotifyFinished channel will be closed once the sender has attempted to send the Finished notification.
	NotifyFinished() chan<- CtxEvent[E]
}

A QueryMonitor receives event notifications on the progress of a query

type QueryMonitorHook 

type QueryMonitorHook[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N], E TerminalQueryEvent] struct {
	BeforeProgressed func()
	BeforeFinished   func()
	// contains filtered or unexported fields
}

QueryMonitorHook wraps a QueryMonitor interface and provides hooks that are invoked before calls to the QueryMonitor methods are forwarded.

func NewQueryMonitorHook 

func NewQueryMonitorHook[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N], E TerminalQueryEvent](qm QueryMonitor[K, N, M, E]) *QueryMonitorHook[K, N, M, E]

NewQueryMonitorHook returns a QueryMonitorHook wrapping qm with no-op hooks.

func (*QueryMonitorHook[K, N, M, E]) NotifyFinished 

func (n *QueryMonitorHook[K, N, M, E]) NotifyFinished() chan<- CtxEvent[E]

func (*QueryMonitorHook[K, N, M, E]) NotifyProgressed 

func (n *QueryMonitorHook[K, N, M, E]) NotifyProgressed() chan<- CtxEvent[*EventQueryProgressed[K, N, M]]

type QueryWaiter 

type QueryWaiter[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]] struct {
	// contains filtered or unexported fields
}

A QueryWaiter implements QueryMonitor for general queries

func NewQueryWaiter 

func NewQueryWaiter[K kad.Key[K], N kad.NodeID[K], M coordt.Message[K, N]](n int) *QueryWaiter[K, N, M]

NewQueryWaiter returns a QueryWaiter whose progress channel buffers n events.

func (*QueryWaiter[K, N, M]) Finished 

func (w *QueryWaiter[K, N, M]) Finished() <-chan CtxEvent[*EventQueryFinished[K, N]]

func (*QueryWaiter[K, N, M]) NotifyFinished 

func (w *QueryWaiter[K, N, M]) NotifyFinished() chan<- CtxEvent[*EventQueryFinished[K, N]]

func (*QueryWaiter[K, N, M]) NotifyProgressed 

func (w *QueryWaiter[K, N, M]) NotifyProgressed() chan<- CtxEvent[*EventQueryProgressed[K, N, M]]

func (*QueryWaiter[K, N, M]) Progressed 

func (w *QueryWaiter[K, N, M]) Progressed() <-chan CtxEvent[*EventQueryProgressed[K, N, M]]

type RoutingBehaviour 

type RoutingBehaviour[K kad.Key[K], N kad.NodeID[K]] struct {
	// contains filtered or unexported fields
}

A RoutingBehaviour provides the behaviours for bootstrapping and maintaining a DHT's routing table.

func ComposeRoutingBehaviour 

func ComposeRoutingBehaviour[K kad.Key[K], N kad.NodeID[K]](
	self N,
	bootstrap coordt.StateMachine[routing.BootstrapEvent, routing.BootstrapState],
	include coordt.StateMachine[routing.IncludeEvent, routing.IncludeState],
	probe coordt.StateMachine[routing.ProbeEvent, routing.ProbeState],
	explore coordt.StateMachine[routing.ExploreEvent, routing.ExploreState],
	cfg *RoutingConfig[K, N],
) (*RoutingBehaviour[K, N], error)

ComposeRoutingBehaviour creates a RoutingBehaviour composed of the supplied state machines. The state machines are assumed to pre-configured so any RoutingConfig values relating to the state machines will not be applied.

func NewRoutingBehaviour 

func NewRoutingBehaviour[K kad.Key[K], N kad.NodeID[K]](self N, rt routing.RoutingTableCpl[K, N], cfg *RoutingConfig[K, N]) (*RoutingBehaviour[K, N], error)

NewRoutingBehaviour returns a new RoutingBehaviour maintaining routing table rt.

func (*RoutingBehaviour[K, N]) Notify 

func (r *RoutingBehaviour[K, N]) Notify(ctx context.Context, ev BehaviourEvent)

func (*RoutingBehaviour[K, N]) Perform 

func (r *RoutingBehaviour[K, N]) Perform(ctx context.Context) (out BehaviourEvent, performed bool)

func (*RoutingBehaviour[K, N]) Ready 

func (r *RoutingBehaviour[K, N]) Ready() <-chan struct{}

type RoutingCommand 

type RoutingCommand interface {
	BehaviourEvent
	// contains filtered or unexported methods
}

RoutingCommand is a type of BehaviourEvent that instructs a RoutingBehaviour to perform an action.

type RoutingConfig 

type RoutingConfig[K kad.Key[K], N kad.NodeID[K]] struct {
	// Logger is a structured logger that will be used when logging.
	Logger *slog.Logger

	// Tracer is the tracer that should be used to trace execution.
	Tracer trace.Tracer

	// Meter is the meter that should be used to record metrics.
	Meter metric.Meter

	// NetworkSize is the estimator that the results of completed explores are reported to.
	// A nil estimator means results are not reported.
	NetworkSize *netsize.Estimator[K, N]

	// QueueCapacity is the maximum number of events that may be waiting to be processed by
	// the behaviour. Events arriving when the queue is full are dropped. It must be larger
	// than [NetworkConfig.Capacity], since a node handler queues a response here before
	// releasing the capacity it held, so that many responses can be waiting at once.
	QueueCapacity int

	// BootstrapTimeout is the time the behaviour should wait before terminating a bootstrap if it is not making progress.
	BootstrapTimeout time.Duration

	// BootstrapRequestConcurrency is the maximum number of concurrent requests that the behaviour may have in flight during bootstrap.
	BootstrapRequestConcurrency int

	// BootstrapRequestTimeout is the timeout the behaviour should use when attempting to contact a node during bootstrap.
	BootstrapRequestTimeout time.Duration

	// BootstrapPeers is the list of nodes used to bootstrap the routing table.
	BootstrapPeers []N

	// BootstrapMinimumPopulation is the routing table population below which the behaviour should
	// start a bootstrap automatically. Zero means a bootstrap is only ever started on request.
	BootstrapMinimumPopulation int

	// BootstrapRetryInterval is the minimum time the behaviour should leave between bootstraps
	// started because the routing table population is below BootstrapMinimumPopulation.
	BootstrapRetryInterval time.Duration

	// ConnectivityCheckTimeout is the timeout the behaviour should use when performing a connectivity check.
	ConnectivityCheckTimeout time.Duration

	// ProbeRequestConcurrency is the maximum number of concurrent requests that the behaviour may have in flight while performing
	// connectivity checks for nodes in the routing table.
	ProbeRequestConcurrency int

	// ProbeCheckInterval is the time interval the behaviour should use between connectivity checks for the same node in the routing table.
	ProbeCheckInterval time.Duration

	// IncludeQueueCapacity is the maximum number of nodes the behaviour should keep queued as candidates for inclusion in the routing table.
	IncludeQueueCapacity int

	// IncludeRequestConcurrency is the maximum number of concurrent requests that the behaviour may have in flight while performing
	// connectivity checks for nodes in the inclusion candidate queue.
	IncludeRequestConcurrency int

	// EnableExplore turns on the routing table explore, which increases routing table occupancy by
	// exploring the network. When enabled an explore cpl function must be supplied.
	EnableExplore bool

	// ExploreCplFunc mints a node id that occupies a given routing table bucket, used to synthesise
	// explore targets. It must be supplied when the explore is enabled.
	ExploreCplFunc routing.NodeIDForCplFunc[K, N]

	// ExploreTimeout is the time the behaviour should wait before terminating an exploration of a routing table bucket if it is not making progress.
	ExploreTimeout time.Duration

	// ExploreRequestConcurrency is the maximum number of concurrent requests that the behaviour may have in flight while exploring the
	// network to increase routing table occupancy.
	ExploreRequestConcurrency int

	// ExploreRequestTimeout is the timeout the behaviour should use when attempting to contact a node while exploring the
	// network to increase routing table occupancy.
	ExploreRequestTimeout time.Duration

	// ExploreMaximumCpl is the maximum CPL (common prefix length) the behaviour should explore to increase routing table occupancy.
	// All CPLs from this value to zero will be explored on a repeating schedule.
	ExploreMaximumCpl int

	// ExploreInterval is the base time interval the behaviour should leave between explorations of the same CPL.
	// See the documentation for [routing.DynamicExploreSchedule] for the precise formula used to calculate explore intervals.
	ExploreInterval time.Duration

	// ExploreIntervalMultiplier is a factor that is applied to the base time interval for CPLs lower than the maximum to increase the delay between
	// explorations for lower CPLs.
	// See the documentation for [routing.DynamicExploreSchedule] for the precise formula used to calculate explore intervals.
	ExploreIntervalMultiplier float64

	// ExploreIntervalJitter is a factor that is used to increase the calculated interval for an exploration by a small random amount.
	// It must be between 0 and 0.05. When zero, no jitter is applied.
	// See the documentation for [routing.DynamicExploreSchedule] for the precise formula used to calculate explore intervals.
	ExploreIntervalJitter float64
}

RoutingConfig configures a RoutingBehaviour.

func DefaultRoutingConfig 

func DefaultRoutingConfig[K kad.Key[K], N kad.NodeID[K]]() *RoutingConfig[K, N]

DefaultRoutingConfig returns a RoutingConfig with default values.

func (*RoutingConfig[K, N]) Validate 

func (cfg *RoutingConfig[K, N]) Validate() error

Validate checks the configuration options and returns an error if any have invalid values.

type RoutingNotification 

type RoutingNotification interface {
	BehaviourEvent
	// contains filtered or unexported methods
}

RoutingNotification is a BehaviourEvent reporting a change to the routing table.

type RoutingNotifier 

type RoutingNotifier interface {
	Notify(context.Context, RoutingNotification)
}

RoutingNotifier receives RoutingNotification events from the coordinator.

type Telemetry 

type Telemetry struct {
	Tracer trace.Tracer
	// contains filtered or unexported fields
}

Telemetry is the struct that holds a reference to all metrics and the tracer used by the coordinator and its components. Make sure to also register the [MeterProviderOpts] with your custom or the global metric.MeterProvider.

func NewTelemetry 

func NewTelemetry(meterProvider metric.MeterProvider, tracerProvider trace.TracerProvider) (*Telemetry, error)

NewTelemetry initializes a Telemetry struct with the given meter and tracer providers.

func (*Telemetry) RecordEventLoopPass 

func (t *Telemetry) RecordEventLoopPass(ctx context.Context, busy time.Duration)

RecordEventLoopPass records one pass of the coordinator's event loop and the time it spent working. The rate at which that time accumulates is the loop's occupancy: the fraction of wall clock time its single worker goroutine is unavailable to take on anything else.

type TerminalQueryEvent 

type TerminalQueryEvent interface {
	BehaviourEvent
	// contains filtered or unexported methods
}

TerminalQueryEvent is a type of BehaviourEvent that indicates a query has completed.

Source Files

View all Source files

Directories

Path Synopsis
internal
kadtest
nettest
tiny
Package tiny implements Kademlia types suitable for tiny test networks
 Package tiny implements Kademlia types suitable for tiny test networks
Package keystore holds the keys a node provides, enumerable by prefix so a region publish can find every key that falls inside a surveyed region.
 Package keystore holds the keys a node provides, enumerable by prefix so a region publish can find every key that falls inside a surveyed region.
Package netsize estimates how many nodes are in the network from the results of lookups returned by queries and exploration.
 Package netsize estimates how many nodes are in the network from the results of lookups returned by queries and exploration.
Package prefix maintains a map of a Kademlia keyspace divided into regions.
 Package prefix maintains a map of a Kademlia keyspace divided into regions.
Package publish contains state machines that implement strategies for publishing records to the network.
 Package publish contains state machines that implement strategies for publishing records to the network.
Package query contains state machines that implement strategies for querying the network.
 Package query contains state machines that implement strategies for querying the network.
Package routing contains state machines that implement strategies for maintaining a routing table.
 Package routing contains state machines that implement strategies for maintaining a routing table.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.