libutp

type BandwidthType ¶

type BandwidthType int

BandwidthType represents different classes of data which may be exchanged in the course of µTP connections. Every byte in a µTP packet is classified using one of these, and every byte that is not PayloadBandwidth is a form of overhead. A base.OnOverhead callback can be used with Socket objects to keep track of how much overhead of each type is getting used.

const (
	// PayloadBandwidth is the class of data which was directly specified by
	// the application layer. That is to say, this is application data.
	PayloadBandwidth BandwidthType = iota
	// ConnectOverhead is the class of data used for bytes which are used to
	// negotiate connections with a remote peer.
	ConnectOverhead
	// CloseOverhead is the class of data used for bytes which are used to
	// indicate that a connection should be closed.
	CloseOverhead
	// AckOverhead is the class of data used to communicate acknowledgement
	// of data received.
	AckOverhead
	// HeaderOverhead is the class of data used for bytes in µTP packet
	// headers.
	HeaderOverhead
	// RetransmitOverhead is the class of data used for bytes that are
	// retransmissions of data previously sent as PayloadBandwidth.
	RetransmitOverhead
)

type CallbackTable ¶

type CallbackTable struct {
	// OnRead is the OnReadCallback to be used by this socket.
	OnRead OnReadCallback
	// OnWrite is the OnWriteCallback to be used by this socket.
	OnWrite OnWriteCallback
	// GetRBSize is the GetRBSizeCallback to be used by this socket.
	GetRBSize GetRBSizeCallback
	// OnState is the OnStateChangeCallback to be used by this socket.
	OnState OnStateChangeCallback
	// OnError is the OnErrorCallback to be used by this socket.
	OnError OnErrorCallback
	// OnOverhead is the OnOverheadCallback to be used by this socket.
	OnOverhead OnOverheadCallback
}

CallbackTable contains a table of callbacks to be used by a Socket. Each Socket can have a different set of callbacks to call, if needed. Any members of the table can be left as nil, if you do not need that callback to be made.

A CallbackTable is assigned to a Socket by use of the SetCallbacks() method.

type ConnId ¶

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

ConnId holds id to be used to accepted connection by the utp server

func ReceConnId(connSeed uint32) *ConnId

func SendCid(connSeed uint32) *ConnId

func (c *ConnId) RecvId() uint32

func (c *ConnId) SendId() uint32

type ConnIdGenerator ¶

type ConnIdGenerator interface {
	// GenCid generates a random connection id
	GenCid(peer any, isInitiator bool) *ConnId
}

ConnIdGenerator generates connection id

func NewConnIdGenerator() ConnIdGenerator

type DefaultConnIdGenerator ¶

type DefaultConnIdGenerator struct {
	Cids map[any]bool
	// contains filtered or unexported fields
}

DefaultConnIdGenerator default connection id generator, it will generate random connection id

func (g *DefaultConnIdGenerator) GenCid(p any, isInitiator bool) *ConnId

func (g *DefaultConnIdGenerator) Remove(c *ConnId)

type GetRBSizeCallback ¶

type GetRBSizeCallback func(userdata interface{}) int

GetRBSizeCallback is the type of callback to be used when a socket needs to know the current size of the read buffer (how many bytes have been received by OnReadCallback, but have not yet been processed). This is used to determine the size of the read window (how many bytes our side is willing to accept from the remote all at once). If your OnReadCallback does not buffer any bytes, but instead always processes bytes immediately, this method can simply always return 0. The callback will be provided with the userdata parameter that was given when the callback was set (using (*Socket).SetCallbacks()).

type GlobalStats ¶

type GlobalStats struct {
	// NumRawRecv keeps a total of all packets received in each size bucket.
	NumRawRecv [5]uint32
	// NumRawSend keeps a total of all packets sent in each size bucket.
	NumRawSend [5]uint32
}

GlobalStats encapsulates statistics pertaining to all use of utp-go since the library was loaded. A snapshot of these statistics can be accessed with the libutp.GetGlobalStats() function.

Statistics in this struct are kept as totals for each of 5 different size buckets:

bucket[0] : size > 0 && size <= 23 bytes bucket[1] : size > 23 && size <= 373 bytes bucket[2] : size > 373 && size <= 723 bytes bucket[3] : size > 723 && size <= 1400 bytes bucket[4] : size > 1400 && size < MTU bytes

The size of the packet header is included in the packet size for this purpose. The packet header is either 20 or 23 bytes, depending on the µTP protocol version in use.

func GetGlobalStats() GlobalStats

type GotIncomingConnection ¶

type GotIncomingConnection func(userdata interface{}, s *Socket)

GotIncomingConnection is the type of callback to be called when a new incoming µTP connection has been established by the socket layer. The Socket for the new connection is passed as 's'. The new Socket can be considered connected and writable immediately.

The callback will be provided with the userdata parameter that was given along with this callback in the corresponding call to IsIncomingUTP(). The callback is responsible for getting the Socket ready to do work; typically, this involves setting callbacks for it with (*Socket).SetCallbacks().

If you want to reject the new connection, it may be closed immediately with (*Socket).Close().

type OnErrorCallback ¶

type OnErrorCallback func(userdata interface{}, err error)

OnErrorCallback is the type of callback to be used when something goes wrong with a connection. Currently, the possible errors which cause an OnErrorCallback are syscall.ECONNREFUSED, syscall.ECONNRESET, and syscall.ETIMEDOUT. All of these probably need to be considered fatal errors in the context of the connection.

The callback will be provided with the userdata parameter that was given when the callback was set (using (*Socket).SetCallbacks()). The callback is responsible for calling (*Socket).Close() if appropriate to tear down the connection.

type OnOverheadCallback ¶

type OnOverheadCallback func(userdata interface{}, send bool, count int, bandwidthType BandwidthType)

OnOverheadCallback is the type of callback to be used when any data is sent over the network. Each byte is accounted by µTP into one of the BandwidthType data classes, and when sent, the use of that class of data is reported to the application using this OnOverheadCallback. The callback will be provided with the userdata parameter that was given when the callback was set (using (*Socket).SetCallbacks()). This callback can be used to maintain statistics about the amount of overhead used to communicate with µTP.

(Use of the PayloadBandwidth BandwidthType is also reported to this callback, although strictly speaking it is not really "overhead".)

type OnReadCallback ¶

type OnReadCallback func(userdata interface{}, bytes []byte)

OnReadCallback is the type of callback to be used when a socket has received application data from the peer. The callback will be provided with the userdata parameter that was given when the callback was set (using (*Socket).SetCallbacks()). The callback is expected to process or buffer all of the data in the 'bytes' slice. Other methods on the Socket object, such as (*Socket).Write(), may be called while the callback is running, if appropriate.

type OnStateChangeCallback ¶

type OnStateChangeCallback func(userdata interface{}, state State)

OnStateChangeCallback is the type of callback to be used when a socket changes its socket state. The callback will be provided with the userdata parameter that was given when the callback was set (using (*Socket).SetCallbacks()). The 'state' parameter will hold the new state of the Socket. It may be important to provide this callback in order to know when a connection is established, and a Socket can accept data, or when a connection has been closed.

type OnWriteCallback ¶

type OnWriteCallback func(userdata interface{}, bytes []byte)

OnWriteCallback is the type of callback to be used when a socket is ready to send more application data to the peer. The application will already have indicated that it _wants_ to send some amount of data using the (*Socket).Write() method, but the data to be sent is not determined until this callback is made. The callback will be provided with the userdata parameter that was given when the callback was set (using (*Socket).SetCallbacks()). The callback is expected to fill in the entire 'bytes' slice. (It should be guaranteed that the slice will not be greater in size than the amount of application that is ready to be sent, as indicated by the last call to (*Socket).Write().)

Once received, the µTP layer takes responsibility for delivering those bytes.

type PacketSendCallback ¶

type PacketSendCallback func(userdata interface{}, p []byte, addr *net.UDPAddr)

PacketSendCallback is the type of callback to be used when the µTP socket layer wants to transmit data over the underlying packet connection (which is probably UDP). The callback will be provided with the userdata parameter that was given along with this callback in the corresponding call to IsIncomingUTP() or Create(). The callback is responsible for actually transmitting the packet to the destination address.

The callback is allowed to buffer the outgoing data instead of transmitting it immediately, if desired, but the data should be transmitted as soon as feasible.

type Socket ¶

type Socket struct {
	ConnSeed uint32
	// Connection ID for packets I receive
	ConnIDRecv uint32
	// Connection ID for packets I send
	ConnIDSend uint32
	// contains filtered or unexported fields
}

Socket represents a µTP socket, which roughly corresponds to one connection to an internet peer. It is important to distinguish µTP sockets from UDP sockets; although µTP may be used over UDP, there is not a 1-1 correlation from µTP sockets to UDP sockets.

Sockets are created using the mx.Create() method (for outgoing connections) or in the course of processing an incoming packet with mx.IsIncomingUTP() (for incoming connections). In the latter case, the socket object will be provided to your code by way of the GotIncomingConnection callback.

Sockets created directly with Create() will need to have the appropriate callbacks registered (with SetCallbacks()) before they can initiate the outgoing connection. To initiate the outgoing connection, use the Connect() method.

Sockets received by way of a GotIncomingConnection callback represent incoming connections, and should not have Connect() called on them.

When your code wants to send data on a Socket, use the Write() method to indicate the amount of data that is ready to be sent. At the appropriate time, the Socket will use the OnWriteCallback to collect the actual data. The OnWriteCallback will only accept a limited amount of data; enough to fill a single packet. If there is more data than that to be sent, it is appropriate to call Write() again with the new total amount (the amount given to Write() is considered the _total_ amount of data which is ready to be written; it is not added to the amount previously indicated).

When data is received from the other end of the connection, the Socket will call its OnReadCallback to pass the received data on to your code.

If a connection times out or is rejected or reset by the peer, the Socket will call its OnErrorCallback.

When a connection becomes writable (connected enough to accept outgoing data), or a connection is closed, the Socket's OnStateChangeCallback will be called.

Your code must call mx.CheckTimeouts() periodically; as often as desired to give the µTP code a chance to notice that a socket has timed out. No background threads remain running to manage µTP state; µTP code is only run when your code calls into it (usually via mx.IsIncomingUTP(), mx.CheckTimeouts(), or the Socket methods).

See the documentation on the various types of callback to learn more.

func (s *Socket) Close() error

func (s *Socket) Connect()

func (s *Socket) GetDelays() (ours int32, theirs int32, age uint32)

func (s *Socket) GetOverhead() int

func (s *Socket) GetPacketSize() int

func (s *Socket) GetPeerName() *net.UDPAddr

func (s *Socket) GetUDPMTU() int

func (s *Socket) GetUDPOverhead() int

func (s *Socket) RBDrained()

func (s *Socket) SetCallbacks(funcs *CallbackTable, userdata interface{})

func (s *Socket) SetLogger(logger *zap.Logger)

func (s *Socket) SetSockOpt(opt, val int) bool

func (s *Socket) Write(numBytes int) bool

type SocketMapKey ¶

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

type SocketMultiplexer ¶

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

SocketMultiplexer coordinates µTP sockets that are sharing a single underlying PacketConn.

func NewSocketMultiplexer(logger *zap.Logger, packetTimeCallback func() time.Duration, maxPacketSize int) *SocketMultiplexer

func (mx *SocketMultiplexer) CheckTimeouts()

func (mx *SocketMultiplexer) Create(sendToCB PacketSendCallback, sendToUserdata interface{}, addr *net.UDPAddr, cid *ConnId) (*Socket, error)

func (mx *SocketMultiplexer) HandleICMP(buffer []byte, toAddr *net.UDPAddr) bool

func (mx *SocketMultiplexer) IsIncomingUTP(incomingCB GotIncomingConnection, sendToCB PacketSendCallback, sendToUserdata interface{}, buffer []byte, toAddr *net.UDPAddr) bool

func (mx *SocketMultiplexer) SetPacketTimeCallback(cb func() time.Duration)

type State ¶

type State int

State represents the state of a µTP socket. It is important to distinguish this type from connState, which is the state of a µTP _connection_. State conveys what a socket is prepared to do, while connState indicates a point in the µTP protocol state diagram. For most purposes, code using utp-go will only need to deal with State.

func (s State) String() string

type Stats ¶

type Stats struct {
	NBytesRecv uint64 // total bytes received
	NBytesXmit uint64 // total bytes transmitted
	ReXmit     uint32 // retransmit counter
	FastReXmit uint32 // fast retransmit counter
	NXmit      uint32 // transmit counter
	NRecv      uint32 // receive counter (total)
	NDupRecv   uint32 // duplicate receive counter
}

Stats collects statistics for a particular Socket when utp-go is built with the 'utpstats' build tag. The (*Socket).GetStats() method will be made available when that build tag is present, and it will return a current copy of the Stats table for that socket.

When the utpstats build tag is not used, no per-socket statistics will be collected.