forward

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 15, 2026 License: MIT Imports: 15 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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

func HandlePair(connA, connB net.Conn)

HandlePair starts bidirectional forwarding between two connections.

func IsClosedErr

func IsClosedErr(err error) bool

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

func OptimizeTCPConn(conn *net.TCPConn) error

OptimizeTCPConn applies common TCP optimizations.

func SpliceFileToFile

func SpliceFileToFile(srcFd, dstFd int, size int64) (int64, error)

SpliceFileToFile copies data between two file descriptors using splice. This is a lower-level API for advanced use cases.

func Tee

func Tee(srcFd, dst1Fd, dst2Fd int, size int64) (int64, error)

Tee duplicates data from src to both dst1 and dst2 using splice tee. Useful for monitoring/logging without extra memory copies.

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

type DataMessage struct {
	ConnID string // Connection ID
	Data   []byte // Data
}

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

type NewConnMessage struct {
	ConnID     string // Connection ID
	RemoteAddr string // Remote address
}

NewConnMessage represents a new connection notification.

type NewConnNotification

type NewConnNotification struct {
	ConnID     string
	RemoteAddr string
}

NewConnNotification is returned when a new connection notification is received.

func (NewConnNotification) Error

func (n NewConnNotification) Error() string

Error implements the error interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL