zerocopy

type ClientPackUnpacker interface {
	ClientPacker
	ClientUnpacker
}

type ClientPacker interface {
	// ClientPackerInfo returns information about the client packer.
	ClientPackerInfo() ClientPackerInfo

	// PackInPlace packs the payload in-place into a packet ready for sending and returns
	// the destination address, packet start offset, packet length, or an error if packing fails.
	PackInPlace(ctx context.Context, b []byte, targetAddr conn.Addr, payloadStart, payloadLen int) (destAddrPort netip.AddrPort, packetStart, packetLen int, err error)
}

type ClientPackerInfo struct {
	Headroom Headroom
}

type ClientUnpacker interface {
	// ClientUnpackerInfo returns information about the client unpacker.
	ClientUnpackerInfo() ClientUnpackerInfo

	// UnpackInPlace unpacks the packet in-place and returns packet source address, payload start offset, payload length, or an error if unpacking fails.
	UnpackInPlace(b []byte, packetSourceAddrPort netip.AddrPort, packetStart, packetLen int) (payloadSourceAddrPort netip.AddrPort, payloadStart, payloadLen int, err error)
}

type ClientUnpackerInfo struct {
	Headroom Headroom
}

type Headroom struct {
	// Front is the minimum space required at the beginning of the buffer before payload.
	Front int

	// Rear is the minimum space required at the end of the buffer after payload.
	Rear int
}

type ServerPackUnpacker interface {
	ServerPacker
	ServerUnpacker
}

type ServerPacker interface {
	// ServerPackerInfo returns information about the server packer.
	ServerPackerInfo() ServerPackerInfo

	// PackInPlace packs the payload in-place into a packet ready for sending and returns
	// packet start offset, packet length, or an error if packing fails.
	PackInPlace(b []byte, sourceAddrPort netip.AddrPort, payloadStart, payloadLen, maxPacketLen int) (packetStart, packetLen int, err error)
}

type ServerPackerInfo struct {
	Headroom Headroom
}

type ServerUnpacker interface {
	// ServerUnpackerInfo returns information about the server unpacker.
	ServerUnpackerInfo() ServerUnpackerInfo

	// UnpackInPlace unpacks the packet in-place and returns target address, payload start offset, payload length, or an error if unpacking fails.
	UnpackInPlace(b []byte, sourceAddrPort netip.AddrPort, packetStart, packetLen int) (targetAddr conn.Addr, payloadStart, payloadLen int, err error)

	// NewPacker creates a new server session for the current client session and returns the server session's packer, or an error.
	NewPacker() (ServerPacker, error)
}

type ServerUnpackerInfo struct {
	Headroom Headroom
}

type UDPClient interface {
	// Info returns information about the client.
	Info() UDPClientInfo

	// NewSession creates a new client session, and returns the created session or an error.
	// The returned [UDPClientSessionInfo] is always valid, even when session creation fails.
	NewSession(ctx context.Context) (UDPClientSessionInfo, UDPClientSession, error)
}

type UDPClientInfo struct {
	// Name is the name of the UDP client.
	Name string

	// PackerHeadroom is the headroom required by the packet packer.
	PackerHeadroom Headroom
}

type UDPClientSession struct {
	// MaxPacketSize is the maximum size of outgoing packets.
	MaxPacketSize int

	// Packer is the packet packer for the session.
	Packer ClientPacker

	// Unpacker is the packet unpacker for the session.
	Unpacker ClientUnpacker

	// Close closes the session.
	Close func() error
}

type UDPClientSessionInfo struct {
	// Name is the name of the UDP client.
	Name string

	// PackerHeadroom is the headroom required by the packet packer.
	PackerHeadroom Headroom

	// MTU is the MTU of the client's designated network path.
	MTU int

	// ListenConfig is the [conn.ListenConfig] for opening client sockets.
	ListenConfig conn.ListenConfig
}

type UDPNATServer interface {
	// Info returns information about the server.
	Info() UDPNATServerInfo

	// NewUnpacker creates a new packet unpacker for the session.
	//
	// The returned unpacker is then used by the caller to unpack the incoming packet.
	// Upon successful unpacking, the unpacker's NewPacker method can be called to create
	// a corresponding packet packer.
	NewUnpacker() (ServerUnpacker, error)
}

type UDPNATServerInfo struct {
	// UnpackerHeadroom is the headroom required by the packet unpacker.
	UnpackerHeadroom Headroom
}

type UDPSessionServer interface {
	// Info returns information about the server.
	Info() UDPSessionServerInfo

	// SessionInfo extracts session ID from a received packet b.
	//
	// The returned session ID is then used by the caller to look up the session table.
	// If no matching entries were found, NewUnpacker should be called to create a new
	// packet unpacker for the packet.
	SessionInfo(b []byte) (csid uint64, err error)

	// NewUnpacker creates a new packet unpacker for the specified client session.
	//
	// The returned unpacker is then used by the caller to unpack the incoming packet.
	// Upon successful unpacking, the unpacker's NewPacker method can be called to create
	// a corresponding server session.
	NewUnpacker(b []byte, csid uint64) (serverUnpacker ServerUnpacker, username string, err error)
}

type UDPSessionServerInfo struct {
	// UnpackerHeadroom is the headroom required by the packet unpacker.
	UnpackerHeadroom Headroom

	// MinNATTimeout is the server's minimum allowed NAT timeout.
	// 0 means no requirement.
	MinNATTimeout time.Duration
}