partialmessages

type PartialMessagesExtension[PeerState any] struct {
	Logger *slog.Logger

	// OnEmitGossip is called when the application should send gossip to the given
	// peers. The application SHOULD call PublishPartial to send partial
	// messages to these peers.
	//
	// The Application may persist some state in the peerStates map. The peers
	// to gossip to will have a zero-value PeerState in the map.
	OnEmitGossip func(topic string, groupID []byte, gossipPeers []peer.ID, peerStates map[peer.ID]PeerState)

	// OnIncomingRPC is called whenever we receive an encoded
	// partial message from a peer. This function MUST be fast and non-blocking.
	// If you need to do slow work (e.g. validation), dispatch the work to your
	// own goroutine.
	//
	// This function SHOULD update the peer's PeerState with the received
	// rpc.PartsMetadata and rpc.PartialMessage.
	//
	// An implementation may be able to infer some peer state from the
	// rpc.PartialMessage, for example:
	//  - peer's received state (we can infer they have a part if they have given it us)
	//  - our last update to a peer (they can infer an update if they have given us a part)
	//
	// If the rpc should be ignored, the application can leave peerStates unmodified
	OnIncomingRPC func(from peer.ID, peerStates map[peer.ID]PeerState, rpc *pb.PartialMessagesExtension) error

	// PeerInitiatedGroupLimitPerTopic limits the number of Group states all
	// peers can initialize per topic. A group state is initialized by a peer if
	// the peer's message marks the first time we've seen a group id.
	PeerInitiatedGroupLimitPerTopic int

	// PeerInitiatedGroupLimitPerTopicPerPeer limits the number of Group states
	// a single peer can initialize per topic. A group state is initialized by a
	// peer if the peer's message marks the first time we've seen a group id.
	PeerInitiatedGroupLimitPerTopicPerPeer int

	// GroupTTLByHeatbeat is how many heartbeats we store Group state for after
	// publishing a partial message for the group.
	GroupTTLByHeatbeat int
	// contains filtered or unexported fields
}

type PartsMetadata []byte

type PeerInfo struct {
	// If RequestedPartialMessage is false, the peer does not want encoded
	// partial messages. The encoded message in a PublishAction MUST be
	// empty for this peer. The implementation SHOULD still send relevant
	// partsMetadataToSend.
	RequestedPartialMessage bool
}

type PublishAction struct {
	// EncodedPartialMessage is the encoded PartialMessage that will be sent to
	// this peer.
	EncodedPartialMessage []byte
	// EncodedPartsMetadata is the PartsMetadata that will be sent to this peer.
	EncodedPartsMetadata []byte

	// Err signals an error that will be bubbled up to the caller of
	// PublishPartial. Returning an error does not prevent other PublishActions
	// from executing or affect the PeerState map.
	Err error
}

type PublishActionsFn[PeerState any] func(peerStates map[peer.ID]PeerState, peerRequestsPartial func(peer.ID) bool) iter.Seq2[peer.ID, PublishAction]

type Router interface {
	SendRPC(p peer.ID, r *pb.PartialMessagesExtension, urgent bool)
	MeshPeers(topic string) iter.Seq[peer.ID]
	PeerRequestsPartial(peer peer.ID, topic string) bool
}