wspacket

type CentralState[
	PktIn any, PktOut OutboundPacket,
	DeltaIn, DeltaOut any,
] interface {
	// UpdateFromPeer updates the central state with
	// new information originating from a remote peer.
	//
	// If the delta does not add new information to the state,
	// this method must return [ErrRedundantUpdate].
	//
	// This method must return nil on success or [ErrRedundantUpdate]
	// if the packet contained no new information.
	// Any other error value is treated as a protocol violation,
	// which will result in a disconnection from the peer.
	UpdateFromPeer(context.Context, DeltaIn) error

	// NewOutboundRemoteState returns an OutboundRemoteState instance
	// that contains a copy of the state in the current central state,
	// and a Stream that is valid for the returned state.
	//
	// Returning the stream here avoids the possibility
	// of a data race between constructing the state
	// and observing the stream.
	NewOutboundRemoteState(context.Context) (
		OutboundRemoteState[PktIn, PktOut, DeltaIn, DeltaOut],
		*dpubsub.Stream[DeltaOut],
		error,
	)

	// NewInboundRemoteState returns a new [InboundRemoteState]
	// that contains a copy of the state in the current central state,
	// and a Stream that is valid for the returned state.
	//
	// Returning the stream here avoids the possibility
	// of a data race between constructing the state
	// and observing the stream.
	NewInboundRemoteState(context.Context) (
		InboundRemoteState[PktIn, DeltaIn, DeltaOut],
		*dpubsub.Stream[DeltaOut],
		error,
	)
}

type InboundRemoteState[PktIn, DeltaIn, DeltaOut any] interface {
	// Apply the outbound delta that was dispatched from the [CentralState].
	// Wingspan internals handle routing this request.
	//
	// The purpose of the inbound state being aware of central state
	// is to affect the return value of CheckIncoming,
	// in order to avoid sending redundant values back to the central state.
	ApplyUpdateFromCentral(DeltaOut) error

	// ApplyUpdateFromPeer indicates that the given inbound delta
	// was accepted by the central state (or was noted as redundant
	// due to a concurrent update from another peer).
	//
	// For many implementations of InboundRemoteState,
	// ApplyUpdateFromPeer will be a no-op.
	//
	// It is possible although unlikely that a call to
	// ApplyUpdateFromCentral could occur before ApplyUpdateFromPeer,
	// so the implementation must handle that case gracefully,
	// returning nil.
	ApplyUpdateFromPeer(DeltaIn) error

	// Parse an incoming packet.
	// This should simply consume bytes from the reader
	// and produce a packet.
	ParsePacket(io.Reader) (PktIn, error)

	// Convert the lightweight packet to a delta value for the [CentralState].
	// Wingspan internals call this if the inbound state passes CheckIncoming.
	// This allows expensive work to be skipped for redundant packets.
	PacketToDelta(PktIn) (DeltaIn, error)

	// Determine if this is a packet we've seen before,
	// or if it is a packet this peer has already sent
	// (which is a protocol violation).
	//
	// Immediately after Wingspan internals parse a packet from a peer,
	// the packet is passed to CheckIncoming.
	// This method must return [ErrAlreadyHavePacket],
	// [ErrDuplicateSentPacket], or nil.
	//
	// If CheckIncoming returns nil,
	// the Wingspan internals route the packet to
	// [OutboundRemoteState.AddUnverifiedFromPeer]
	// and to [CentralState.UpdateFromPeer].
	//
	// The implementation is responsible for ensuring
	// that multiple calls with the same delta
	// return ErrDuplicateSentPacket on the second or later calls.
	CheckIncoming(PktIn) error
}

type OutboundPacket interface {
	// Bytes is the raw byte slice that needs to be sent
	// to the peer over a QUIC stream.
	//
	// To minimize allocations,
	// independent packets should return the same underlying slice.
	// Callers will not modify the slice.
	Bytes() []byte

	// After sending a packet to a peer,
	// Wingspan internals call MarkSent
	// in order to update the [OutboundRemoteState],
	// which will influence future calls to [OutboundRemoteState.UnsentPackets].
	MarkSent()
}

type OutboundRemoteState[
	PktIn any, PktOut OutboundPacket,
	DeltaIn, DeltaOut any,
] interface {
	// Apply the outbound delta that was dispatched from the [CentralState].
	// Wingspan internals handle routing this request.
	//
	// An update from the central state indicates a new packet
	// that should be included in the UnsentPackets output,
	// unless there was a prior call to AddUnverifiedFromPeer
	// that matches the update.
	// In that case, the state should treat the delta
	// as though the peer already has it.
	ApplyUpdateFromCentral(DeltaOut) error

	// AddUnverifiedFromPeer is called after
	// successfully parsing an inbound delta from a packet,
	// on the corresponding inbound worker,
	// but before Wingspan internals pass the delta
	// to the [CentralState] for verification.
	//
	// The implementation should optimistically accumulate
	// delta values in a buffer, removing entries upon
	// a corresponding call to ApplyUpdateFromCentral.
	//
	// In the event that the peer provides an invalid delta,
	// the session will stop using this state value
	// once the delta is determined to be invalid
	// (implying that the peer cannot be trusted).
	//
	// The implementation must gracefully handle an unverified delta
	// arriving after a call to ApplyUpdateFromCentral,
	// although that case is unlikely.
	//
	// Returning an error from this method will cause the session
	// to close the underlying connection to the peer.
	AddUnverifiedFromPeer(DeltaIn) error

	// An iterator over the packets in the OutboundRemoteState
	// which have not yet been sent.
	//
	// Wingspan internals will not call ApplyUpdateFromCentral
	// while the iterator is active,
	// but AddUnverifiedFromPeer may be called
	// (which ought to be fine since
	// that should not affect the iteration).
	//
	// It is possible that there may be many calls
	// to ApplyUpdateFromCentral or AddUnverifiedFromPeer
	// before UnsentPackets is called again.
	UnsentPackets() iter.Seq[PktOut]
}