Documentation
¶
Overview ¶
Package forward provides platform-optimized data forwarding.
Package forward provides Linux-specific zero-copy forwarding using splice.
Package forward provides platform-optimized data forwarding with multiplexing support.
This file extends the forward package to support multiplexed connections, where multiple virtual connections share a single physical connection (e.g., QUIC stream).
Architecture ¶
Original Forwarder:
Forward(src, dst) - Direct bidirectional forwarding, no protocol encapsulation
Extended MuxForwarder:
ForwardMux(localConn, muxConn, connID, encoder) - Forward with protocol encapsulation
Use Cases ¶
- Server TCP Handler: Use Forwarder (independent connections)
- Client TCP Tunnel: Use MuxForwarder (shared stream with protocol prefix)
- HTTP Request-Response: Use HTTPMuxForwarder (non-bidirectional)
Protocol Format ¶
Binary message format (optimized):
[1 byte: type][2 bytes: id_len][id][4 bytes: payload_len][payload]
Index ¶
- Variables
- func BufferForward(src, dst net.Conn, bp *backpressure.Controller, bufSize int) error
- func CopyForward(src, dst net.Conn, bp *backpressure.Controller) error
- func HandlePair(connA, connB net.Conn)
- func IsClosedErr(err error) bool
- func OptimizeTCPConn(conn *net.TCPConn) error
- func SpliceFileToFile(srcFd, dstFd int, size int64) (int64, error)
- func Tee(srcFd, dst1Fd, dst2Fd int, size int64) (int64, error)
- type BidirectionalMuxForwarder
- type BinaryProtocol
- func (p *BinaryProtocol) Decode(data []byte) (MessageType, string, []byte, error)
- func (p *BinaryProtocol) Encode(msg *Message) ([]byte, error)
- func (p *BinaryProtocol) EncodeClose(connID string) ([]byte, error)
- func (p *BinaryProtocol) EncodeData(connID string, data []byte) ([]byte, error)
- func (p *BinaryProtocol) EncodeNewConn(connID, remoteAddr string) ([]byte, error)
- func (p *BinaryProtocol) EncodeRequest(reqID string, data []byte) ([]byte, error)
- func (p *BinaryProtocol) EncodeResponse(reqID string, data []byte) ([]byte, error)
- func (p *BinaryProtocol) Release(buf []byte)
- type DataMessage
- type DefaultMuxDecoder
- type DefaultMuxEncoder
- func (e *DefaultMuxEncoder) EncodeClose(connID string) ([]byte, error)
- func (e *DefaultMuxEncoder) EncodeData(connID string, data []byte) ([]byte, error)
- func (e *DefaultMuxEncoder) EncodeNewConn(connID, remoteAddr string) ([]byte, error)
- func (e *DefaultMuxEncoder) EncodeRequest(reqID string, data []byte) ([]byte, error)
- func (e *DefaultMuxEncoder) EncodeResponse(reqID string, data []byte) ([]byte, error)
- func (e *DefaultMuxEncoder) Release(buf []byte)
- type Forwarder
- type HTTPMuxForwarder
- type Message
- type MessageType
- type MuxConnManager
- func (m *MuxConnManager) AddConnection(connID string, localConn net.Conn)
- func (m *MuxConnManager) Close()
- func (m *MuxConnManager) GetConnection(connID string) (net.Conn, bool)
- func (m *MuxConnManager) HandleIncoming(data []byte) error
- func (m *MuxConnManager) RemoveConnection(connID string)
- func (m *MuxConnManager) Stats() MuxConnStats
- type MuxConnStats
- type MuxDecoder
- type MuxEncoder
- type MuxForwarder
- type NewConnMessage
- type NewConnNotification
Constants ¶
This section is empty.
Variables ¶
var ( ErrMessageTooShort = fmt.Errorf("message too short") ErrInvalidMessage = fmt.Errorf("invalid message format") )
Protocol errors
Functions ¶
func BufferForward ¶
func BufferForward(src, dst net.Conn, bp *backpressure.Controller, bufSize int) error
BufferForward forwards data using buffer pool with backpressure control.
func CopyForward ¶
func CopyForward(src, dst net.Conn, bp *backpressure.Controller) error
CopyForward is a generic forward implementation using buffer pool. Used as fallback for platforms without special optimizations.
func HandlePair ¶
HandlePair starts bidirectional forwarding between two connections.
func IsClosedErr ¶
IsClosedErr returns true if the error indicates a normal connection close. Returns false for nil error (no error means not a "closed" error).
func OptimizeTCPConn ¶
OptimizeTCPConn applies common TCP optimizations.
func SpliceFileToFile ¶
SpliceFileToFile copies data between two file descriptors using splice. This is a lower-level API for advanced use cases.
Types ¶
type BidirectionalMuxForwarder ¶
type BidirectionalMuxForwarder interface {
ForwardBidirectionalMux(
ctx context.Context,
localConn net.Conn,
muxConn io.ReadWriter,
connID string,
encoder MuxEncoder,
decoder MuxDecoder,
) error
}
BidirectionalMuxForwarder defines the interface for bidirectional multiplexed forwarding.
func NewBidirectionalMuxForwarder ¶
func NewBidirectionalMuxForwarder() BidirectionalMuxForwarder
NewBidirectionalMuxForwarder creates a new bidirectional multiplexed forwarder.
type BinaryProtocol ¶
type BinaryProtocol struct {
// contains filtered or unexported fields
}
BinaryProtocol implements MuxEncoder and MuxDecoder with binary encoding. Uses buffer pools for memory efficiency.
func NewBinaryProtocol ¶
func NewBinaryProtocol() *BinaryProtocol
NewBinaryProtocol creates a new binary protocol instance.
func (*BinaryProtocol) Decode ¶
func (p *BinaryProtocol) Decode(data []byte) (MessageType, string, []byte, error)
Decode decodes a binary message. Returns slices pointing to the original data (zero-copy).
func (*BinaryProtocol) Encode ¶
func (p *BinaryProtocol) Encode(msg *Message) ([]byte, error)
Encode encodes a message to binary format. Format: [1 byte: type][2 bytes: id_len][id][4 bytes: payload_len][payload]
func (*BinaryProtocol) EncodeClose ¶
func (p *BinaryProtocol) EncodeClose(connID string) ([]byte, error)
EncodeClose encodes a close message.
func (*BinaryProtocol) EncodeData ¶
func (p *BinaryProtocol) EncodeData(connID string, data []byte) ([]byte, error)
EncodeData encodes a data message.
func (*BinaryProtocol) EncodeNewConn ¶
func (p *BinaryProtocol) EncodeNewConn(connID, remoteAddr string) ([]byte, error)
EncodeNewConn encodes a new connection notification.
func (*BinaryProtocol) EncodeRequest ¶
func (p *BinaryProtocol) EncodeRequest(reqID string, data []byte) ([]byte, error)
EncodeRequest encodes an HTTP request message.
func (*BinaryProtocol) EncodeResponse ¶
func (p *BinaryProtocol) EncodeResponse(reqID string, data []byte) ([]byte, error)
EncodeResponse encodes an HTTP response message.
func (*BinaryProtocol) Release ¶
func (p *BinaryProtocol) Release(buf []byte)
Release returns the buffer to the pool.
type DataMessage ¶
DataMessage represents a data message.
type DefaultMuxDecoder ¶
type DefaultMuxDecoder struct {
Delimiter byte
}
DefaultMuxDecoder implements MuxDecoder for the text-based protocol.
func NewDefaultMuxDecoder ¶
func NewDefaultMuxDecoder() *DefaultMuxDecoder
NewDefaultMuxDecoder creates a new default mux decoder.
func (*DefaultMuxDecoder) Decode ¶
func (d *DefaultMuxDecoder) Decode(data []byte) (MessageType, string, []byte, error)
Decode decodes a message.
type DefaultMuxEncoder ¶
type DefaultMuxEncoder struct {
Delimiter byte
// contains filtered or unexported fields
}
DefaultMuxEncoder implements MuxEncoder with a text-based protocol. Optimized with buffer pool and avoiding fmt.Sprintf allocations. Thread-safe for concurrent use.
func NewDefaultMuxEncoder ¶
func NewDefaultMuxEncoder() *DefaultMuxEncoder
NewDefaultMuxEncoder creates a new default mux encoder.
func (*DefaultMuxEncoder) EncodeClose ¶
func (e *DefaultMuxEncoder) EncodeClose(connID string) ([]byte, error)
EncodeClose encodes a close message.
func (*DefaultMuxEncoder) EncodeData ¶
func (e *DefaultMuxEncoder) EncodeData(connID string, data []byte) ([]byte, error)
EncodeData encodes a data message.
func (*DefaultMuxEncoder) EncodeNewConn ¶
func (e *DefaultMuxEncoder) EncodeNewConn(connID, remoteAddr string) ([]byte, error)
EncodeNewConn encodes a new connection notification.
func (*DefaultMuxEncoder) EncodeRequest ¶
func (e *DefaultMuxEncoder) EncodeRequest(reqID string, data []byte) ([]byte, error)
EncodeRequest encodes an HTTP request message.
func (*DefaultMuxEncoder) EncodeResponse ¶
func (e *DefaultMuxEncoder) EncodeResponse(reqID string, data []byte) ([]byte, error)
EncodeResponse encodes an HTTP response message.
func (*DefaultMuxEncoder) Release ¶
func (e *DefaultMuxEncoder) Release(buf []byte)
Release releases the encoded buffer back to pool. For this implementation, it's a no-op since we return copies.
type Forwarder ¶
type Forwarder interface {
// Forward copies data from src to dst.
Forward(src, dst net.Conn) error
}
Forwarder defines the interface for data forwarding.
func NewForwarder ¶
func NewForwarder() Forwarder
NewForwarder creates a platform-optimized forwarder. The actual implementation is determined by build constraints: - Linux: uses unix.Splice for zero-copy - macOS/FreeBSD: uses TCP_NOPUSH optimization - Windows: uses IOCP with large buffers
type HTTPMuxForwarder ¶
type HTTPMuxForwarder interface {
ForwardHTTP(ctx context.Context, reqData []byte, muxConn io.ReadWriter, reqID string, encoder MuxEncoder, decoder MuxDecoder, timeout time.Duration) ([]byte, error)
}
HTTPMuxForwarder handles HTTP request-response forwarding over a multiplexed connection.
func NewHTTPMuxForwarder ¶
func NewHTTPMuxForwarder() HTTPMuxForwarder
NewHTTPMuxForwarder creates a new HTTP multiplexed forwarder.
type Message ¶
type Message struct {
Type MessageType // Message type
ID string // Connection ID or Request ID
Payload []byte // Data payload
}
Message represents a multiplexed message.
type MessageType ¶
type MessageType int
MessageType represents the type of multiplexed message.
const ( // MsgTypeData is a data message for TCP forwarding. MsgTypeData MessageType = iota // MsgTypeClose is a connection close notification. MsgTypeClose // MsgTypeRequest is an HTTP request message. MsgTypeRequest // MsgTypeResponse is an HTTP response message. MsgTypeResponse // MsgTypeHandshake is a handshake message. MsgTypeHandshake // MsgTypeNewConn is a new connection notification (server -> client). MsgTypeNewConn )
func (MessageType) String ¶
func (mt MessageType) String() string
String returns the string representation of the message type.
type MuxConnManager ¶
type MuxConnManager struct {
// contains filtered or unexported fields
}
MuxConnManager manages multiple connections over a shared multiplexed connection.
func NewMuxConnManager ¶
func NewMuxConnManager(muxConn io.ReadWriter, encoder MuxEncoder, decoder MuxDecoder) *MuxConnManager
NewMuxConnManager creates a new multiplexed connection manager.
func (*MuxConnManager) AddConnection ¶
func (m *MuxConnManager) AddConnection(connID string, localConn net.Conn)
AddConnection adds a new connection and starts forwarding.
func (*MuxConnManager) Close ¶
func (m *MuxConnManager) Close()
Close closes the manager and all connections.
func (*MuxConnManager) GetConnection ¶
func (m *MuxConnManager) GetConnection(connID string) (net.Conn, bool)
GetConnection gets a connection by ID.
func (*MuxConnManager) HandleIncoming ¶
func (m *MuxConnManager) HandleIncoming(data []byte) error
HandleIncoming handles an incoming message from the mux connection.
func (*MuxConnManager) RemoveConnection ¶
func (m *MuxConnManager) RemoveConnection(connID string)
RemoveConnection removes a connection.
func (*MuxConnManager) Stats ¶
func (m *MuxConnManager) Stats() MuxConnStats
Stats returns the current statistics.
type MuxConnStats ¶
type MuxConnStats struct {
ActiveConnections int64
TotalConnections int64
BytesIn int64
BytesOut int64
}
MuxConnStats holds statistics for the mux connection manager.
type MuxDecoder ¶
type MuxDecoder interface {
// Decode decodes a message.
// Returns the message type, ID (conn_id or req_id), payload, and error.
Decode(data []byte) (msgType MessageType, id string, payload []byte, err error)
}
MuxDecoder defines the interface for decoding multiplexed messages.
type MuxEncoder ¶
type MuxEncoder interface {
// EncodeData encodes a data message.
EncodeData(connID string, data []byte) ([]byte, error)
// EncodeClose encodes a close message.
EncodeClose(connID string) ([]byte, error)
// EncodeRequest encodes an HTTP request message.
EncodeRequest(reqID string, data []byte) ([]byte, error)
// EncodeResponse encodes an HTTP response message.
EncodeResponse(reqID string, data []byte) ([]byte, error)
// EncodeNewConn encodes a new connection notification.
EncodeNewConn(connID, remoteAddr string) ([]byte, error)
// Release releases the encoded buffer back to pool (optional).
Release(buf []byte)
}
MuxEncoder defines the interface for encoding multiplexed messages. Implementations can use different protocols (text, binary, etc.).
type MuxForwarder ¶
type MuxForwarder interface {
// ForwardMux forwards data from localConn to muxConn with protocol encapsulation.
ForwardMux(ctx context.Context, localConn net.Conn, muxConn io.Writer, connID string, encoder MuxEncoder) error
}
MuxForwarder defines the interface for multiplexed forwarding.
func NewMuxForwarder ¶
func NewMuxForwarder() MuxForwarder
NewMuxForwarder creates a new multiplexed forwarder with optimizations.
type NewConnMessage ¶
NewConnMessage represents a new connection notification.
type NewConnNotification ¶
NewConnNotification is returned when a new connection notification is received.
func (NewConnNotification) Error ¶
func (n NewConnNotification) Error() string
Error implements the error interface.