brdcst

type Broadcast ¶

type Broadcast = coordt.StateMachine[BroadcastEvent, BroadcastState]

Broadcast is a type alias for a specific kind of state machine that any kind of broadcast strategy state machine must implement. Currently, there are the FollowUp and Static state machines.

type BroadcastEvent ¶

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

BroadcastEvent is an event intended to advance the state of a Broadcast state machine. Broadcast state machines only operate on events that implement this interface. An "Event" is the opposite of a "State." An "Event" flows into the state machine and a "State" flows out of it.

Currently, there are the FollowUp and Static state machines.

type BroadcastState ¶

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

BroadcastState must be implemented by all states that a Broadcast state machine can reach. There are multiple different broadcast state machines that all have in common to "emit" a BroadcastState and accept a BroadcastEvent. Recall, states are basically the "events" that a state machine emits which other state machines or behaviours could react upon.

type Config ¶

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

Config is an interface that all broadcast configurations must implement. Because we have multiple ways of broadcasting records to the network, like FollowUp or Static, the EventPoolStartBroadcast has a configuration field that depending on the concrete type of Config initializes the respective state machine. Then the broadcast operation will be performed based on the encoded rules in that state machine.

type ConfigFollowUp ¶

type ConfigFollowUp struct{}

ConfigFollowUp specifies the configuration for the FollowUp state machine.

func DefaultConfigFollowUp() *ConfigFollowUp

func (c *ConfigFollowUp) Validate() error

type ConfigOptimistic ¶

type ConfigOptimistic struct{}

ConfigOptimistic specifies the configuration for the [Optimistic] state machine.

func DefaultConfigOptimistic() *ConfigOptimistic

func (c *ConfigOptimistic) Validate() error

type ConfigPool ¶

type ConfigPool struct {
	// contains filtered or unexported fields
}

ConfigPool specifies the configuration for a broadcast Pool.

func DefaultConfigPool() *ConfigPool

func (cfg *ConfigPool) Validate() error

type ConfigStatic ¶

type ConfigStatic struct{}

ConfigStatic specifies the configuration for the Static state machine.

func DefaultConfigStatic() *ConfigStatic

func (c *ConfigStatic) Validate() error

type EventBroadcastNodeFailure ¶

type EventBroadcastNodeFailure[K kad.Key[K], N kad.NodeID[K]] struct {
	NodeID N     // the node the message was sent to and that has replied
	Error  error // the error that caused the failure, if any
}

EventBroadcastNodeFailure notifies a Broadcast state machine that a remote node (NodeID) has failed responding with closer nodes to the target key.

type EventBroadcastNodeResponse ¶

type EventBroadcastNodeResponse[K kad.Key[K], N kad.NodeID[K]] struct {
	NodeID      N   // the node the message was sent to and that replied
	CloserNodes []N // the closer nodes sent by the node
}

EventBroadcastNodeResponse notifies a Broadcast state machine that a remote node (NodeID) has successfully responded with closer nodes (CloserNodes) to the Target key that's stored on the Broadcast state machine

type EventBroadcastPoll ¶

type EventBroadcastPoll struct{}

EventBroadcastPoll is an event that signals a Broadcast state machine that it can perform housekeeping work such as time out queries.

type EventBroadcastStart ¶

type EventBroadcastStart[K kad.Key[K], N kad.NodeID[K]] struct {
	Target K   // the key we want to store the record for
	Seed   []N // the closest nodes we know so far and from where we start the operation
}

EventBroadcastStart is an event that instructs a broadcast state machine to start the operation.

type EventBroadcastStop ¶

type EventBroadcastStop struct{}

EventBroadcastStop notifies a Broadcast state machine to stop the operation. This comprises all in-flight queries.

type EventBroadcastStoreRecordFailure ¶

type EventBroadcastStoreRecordFailure[K kad.Key[K], N kad.NodeID[K], M coordt.Message] struct {
	NodeID  N     // the node the message was sent to
	Request M     // the message that was sent to the remote node
	Error   error // the error that caused the failure, if any
}

EventBroadcastStoreRecordFailure notifies a broadcast Broadcast state machine that storing a record with a remote node (NodeID) has failed. The message that was sent is held in Request, and the error will be in Error.

type EventBroadcastStoreRecordSuccess ¶

type EventBroadcastStoreRecordSuccess[K kad.Key[K], N kad.NodeID[K], M coordt.Message] struct {
	NodeID   N // the node the message was sent to
	Request  M // the message that was sent to the remote node
	Response M // the reply we got from the remote node (nil in many cases of the Amino DHT)
}

EventBroadcastStoreRecordSuccess notifies a broadcast Broadcast state machine that storing a record with a remote node (NodeID) was successful. The message that was sent is held in Request, and the returned value is contained in Response. However, in the case of the Amino DHT, nodes do not respond with a confirmation, so Response will always be nil. Check out [pb.Message.ExpectResponse] for information about which requests should receive a response.

type EventPoolGetCloserNodesFailure ¶

type EventPoolGetCloserNodesFailure[K kad.Key[K], N kad.NodeID[K]] struct {
	QueryID coordt.QueryID // the id of the query that sent the message
	NodeID  N              // the node the message was sent to and that has replied
	Target  K              // the key we want are searching closer nodes for
	Error   error          // the error that caused the failure, if any
}

EventPoolGetCloserNodesFailure notifies a Pool that a remote node (NodeID) has failed responding with closer nodes to the Target key for the broadcast operation with the given id (QueryID).

type EventPoolGetCloserNodesSuccess ¶

type EventPoolGetCloserNodesSuccess[K kad.Key[K], N kad.NodeID[K]] struct {
	QueryID     coordt.QueryID // the id of the broadcast operation that this response belongs to
	NodeID      N              // the node the message was sent to and that replied
	Target      K              // the key we want are searching closer nodes for
	CloserNodes []N            // the closer nodes sent by the node NodeID
}

EventPoolGetCloserNodesSuccess notifies a Pool that a remote node (NodeID) has successfully responded with closer nodes (CloserNodes) to the Target key for the broadcast operation with the given id (QueryID).

type EventPoolPoll ¶

type EventPoolPoll struct{}

EventPoolPoll is an event that signals the broadcast Pool state machine that it can perform housekeeping work such as time out queries.

type EventPoolStartBroadcast ¶

type EventPoolStartBroadcast[K kad.Key[K], N kad.NodeID[K], M coordt.Message] struct {
	QueryID coordt.QueryID // the unique ID for this operation
	Target  K              // the key we want to store the record for
	Message M              // the message that we want to send to the closest peers (this encapsulates the payload we want to store)
	Seed    []N            // the closest nodes we know so far and from where we start the operation
	Config  Config         // the configuration for this operation. Most importantly, this defines the broadcast strategy ([FollowUp] or [Static])
}

EventPoolStartBroadcast is an event that attempts to start a new broadcast operation. This is the entry point.

type EventPoolStopBroadcast ¶

type EventPoolStopBroadcast struct {
	QueryID coordt.QueryID // the id of the broadcast operation that should be stopped
}

EventPoolStopBroadcast notifies broadcast Pool to stop a broadcast operation.

type EventPoolStoreRecordFailure ¶

type EventPoolStoreRecordFailure[K kad.Key[K], N kad.NodeID[K], M coordt.Message] struct {
	QueryID coordt.QueryID // the id of the query that sent the message
	NodeID  N              // the node the message was sent to
	Request M              // the message that was sent to the remote node
	Error   error          // the error that caused the failure
}

EventPoolStoreRecordFailure noties the broadcast Pool that storing a record with a remote node (NodeID) has failed. The message that was sent is hold in Request, and the error will be in Error.

type EventPoolStoreRecordSuccess ¶

type EventPoolStoreRecordSuccess[K kad.Key[K], N kad.NodeID[K], M coordt.Message] struct {
	QueryID  coordt.QueryID // the id of the query that sent the message
	NodeID   N              // the node the message was sent to
	Request  M              // the message that was sent to the remote node
	Response M              // the reply we got from the remote node (nil in many cases of the Amino DHT)
}

EventPoolStoreRecordSuccess noties the broadcast Pool that storing a record with a remote node (NodeID) was successful. The message that was sent is held in Request, and the returned value is contained in Response. However, in the case of the Amino DHT, nodes do not respond with a confirmation, so Response will always be nil. Check out [pb.Message.ExpectResponse] for information about which requests should receive a response.

type FollowUp ¶

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

FollowUp is a Broadcast state machine and encapsulates the logic around doing a "classic" put operation. This mimics the algorithm employed in the original go-libp2p-kad-dht v1 code base. It first queries the closest nodes to a certain target key, and after they were discovered, it "follows up" with storing the record with these closest nodes.

func NewFollowUp[K kad.Key[K], N kad.NodeID[K], M coordt.Message](qid coordt.QueryID, pool *query.Pool[K, N, M], msg M, cfg *ConfigFollowUp) *FollowUp[K, N, M]

func (f *FollowUp[K, N, M]) Advance(ctx context.Context, ev BroadcastEvent) (out BroadcastState)

type Pool ¶

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

Pool is a coordt.StateMachine that manages all running broadcast operations. In the future it could limit the number of concurrent operations, but right now it is just keeping track of all running broadcasts. The referenced query.Pool is passed down to the respective broadcast state machines. This is not nice because it breaks the hierarchy but makes things way easier.

Conceptually, a broadcast consists of finding the closest nodes to a certain key and then storing the record with them. There are a few different strategies that can be applied. For now, these are the FollowUp and the Static strategies. In the future, we also want to support Reprovide Sweep. However, this requires a different type of query as we are not looking for the closest nodes but rather enumerating the keyspace. In any case, this broadcast Pool would keep track of all running broadcasts.

func NewPool[K kad.Key[K], N kad.NodeID[K], M coordt.Message](self N, cfg *ConfigPool) (*Pool[K, N, M], error)

func (p *Pool[K, N, M]) Advance(ctx context.Context, ev PoolEvent) (out PoolState)

type PoolEvent ¶

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

PoolEvent is an event intended to advance the state of the broadcast Pool state machine. The Pool state machine only operates on events that implement this interface. An "Event" is the opposite of a "State." An "Event" flows into the state machine and a "State" flows out of it.

type PoolState ¶

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

PoolState must be implemented by all states that a Pool can reach. States are basically the events that the Pool emits that other state machines or behaviours could react upon.

type StateBroadcastFindCloser ¶

type StateBroadcastFindCloser[K kad.Key[K], N kad.NodeID[K]] struct {
	QueryID coordt.QueryID // the id of the broadcast operation that wants to send the message
	NodeID  N              // the node to send the message to
	Target  K              // the key that the query wants to find closer nodes for
}

StateBroadcastFindCloser indicates to the broadcast Pool or any other upper layer that a Broadcast state machine wants to query the given node (NodeID) for closer nodes to the target key (Target).

type StateBroadcastFinished ¶

type StateBroadcastFinished[K kad.Key[K], N kad.NodeID[K]] struct {
	QueryID   coordt.QueryID // the id of the broadcast operation that has finished
	Contacted []N            // all nodes we contacted to store the record (successful or not)
	Errors    map[string]struct {
		Node N     // a node from the Contacted slice
		Err  error // the error that happened when contacting that Node
	}
}

StateBroadcastFinished indicates that a Broadcast state machine has finished its operation. During that operation, all nodes in Contacted have been contacted to store the record. The Contacted slice does not contain the nodes we have queried to find the closest nodes to the target key - only the ones that we eventually contacted to store the record. The Errors map maps the string representation of any node N in the Contacted slice to a potential error struct that contains the original Node and error. In the best case, this Errors map is empty.

type StateBroadcastIdle ¶

type StateBroadcastIdle struct{}

StateBroadcastIdle means that a Broadcast state machine has finished all of its operation. This state will be emitted if the state machine is polled to advance its state but has already finished its operation. The last meaningful state will be StateBroadcastFinished. Being idle is different from waiting for network I/O to finish (see StateBroadcastWaiting).

type StateBroadcastStoreRecord ¶

type StateBroadcastStoreRecord[K kad.Key[K], N kad.NodeID[K], M coordt.Message] struct {
	QueryID coordt.QueryID // the id of the broadcast operation that wants to send the message
	NodeID  N              // the node to send the message to
	Message M              // the message the broadcast behaviour wants to send
}

StateBroadcastStoreRecord indicates to the broadcast Pool or any other upper layer that a Broadcast state machine wants to store a record using the given Message with the given NodeID.

type StateBroadcastWaiting ¶

type StateBroadcastWaiting struct {
	QueryID coordt.QueryID // the id of the broadcast operation that is waiting
}

StateBroadcastWaiting indicates that a Broadcast state machine is waiting for network I/O to finish. It means the state machine isn't idle, but that there are operations in-flight that it is waiting on to finish.

type StatePoolBroadcastFinished ¶

type StatePoolBroadcastFinished[K kad.Key[K], N kad.NodeID[K]] struct {
	QueryID   coordt.QueryID // the id of the broadcast operation that has finished
	Contacted []N            // all nodes we contacted to store the record (successful or not)
	Errors    map[string]struct {
		Node N     // a node from the Contacted slice
		Err  error // the error that happened when contacting that Node
	}
}

StatePoolBroadcastFinished indicates that the broadcast operation with the id QueryID has finished. During that operation, all nodes in Contacted have been contacted to store the record. The Contacted slice does not contain the nodes we have queried to find the closest nodes to the target key - only the ones that we eventually contacted to store the record. The Errors map maps the string representation of any node N in the Contacted slice to a potential error struct that contains the original Node and error. In the best case, this Errors map is empty.

type StatePoolFindCloser ¶

type StatePoolFindCloser[K kad.Key[K], N kad.NodeID[K]] struct {
	QueryID coordt.QueryID // the id of the broadcast operation that wants to send the message
	Target  K              // the key that the query wants to find closer nodes for
	NodeID  N              // the node to send the message to
}

StatePoolFindCloser indicates to the broadcast behaviour that a broadcast state machine and indirectly the broadcast pool wants to query the given node (NodeID) for closer nodes to the target key (Target).

type StatePoolIdle ¶

type StatePoolIdle struct{}

StatePoolIdle means that the broadcast Pool is not managing any broadcast operations at this time.

type StatePoolStoreRecord ¶

type StatePoolStoreRecord[K kad.Key[K], N kad.NodeID[K], M coordt.Message] struct {
	QueryID coordt.QueryID // the id of the broadcast operation that wants to send the message
	NodeID  N              // the node to send the message to
	Message M              // the message that should be sent to the remote node
}

StatePoolStoreRecord indicates to the upper layer that the broadcast Pool wants to store a record using the given Message with the given NodeID. The network behaviour should take over and notify the [coord.PooledBroadcastBehaviour] about updates.

type StatePoolWaiting ¶

type StatePoolWaiting struct{}

StatePoolWaiting indicates that the broadcast Pool is waiting for network I/O to finish. It means the Pool isn't idle, but there are operations in-flight that it is waiting on to finish.

type Static ¶

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

Static is a Broadcast state machine and encapsulates the logic around doing a put operation to a static set of nodes. That static set of nodes is given by the list of seed nodes in the EventBroadcastStart event.

func NewStatic[K kad.Key[K], N kad.NodeID[K], M coordt.Message](qid coordt.QueryID, msg M, cfg *ConfigStatic) *Static[K, N, M]

func (f *Static[K, N, M]) Advance(ctx context.Context, ev BroadcastEvent) (out BroadcastState)