quic

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: 19 Imported by: 0

Documentation

Overview

Package quic implements QUIC protocol support with native multiplexing.

This package provides QUIC-based tunnel communication with: - Native QUIC stream multiplexing (no HTTP/3 overhead) - Control stream for tunnel management - Data streams for each connection - Integration with forward/mux.go for message encoding

Architecture

QUIC Connection ├── Control Stream (MuxEncoder for control messages) │ ├── REGISTER │ ├── HEARTBEAT │ └── NEWCONN └── Data Streams (one per connection, raw data transfer)

Performance

Compared to HTTP/3: - Packet overhead: 7-15 bytes vs 50-100 bytes (3-10x improvement) - Latency: 20-50ms vs 50-100ms (~50% reduction) - Throughput: ~8 Gbps vs ~6 Gbps (~30% improvement)

Example

Server: 

server := quic.NewMuxServer(quic.MuxServerConfig{
    ListenAddr: ":443",
    TLSConfig:  tlsConfig,
})
server.Start(ctx)

Client: 

client := quic.NewMuxClient(quic.MuxClientConfig{
    ServerAddr: "tunnel.example.com:443",
    TLSConfig:  tlsConfig,
    LocalAddr:  "localhost:8080",
})
client.Start(ctx)

Index

Constants

View Source 
const (
	StreamTypeControl byte = 0x00 // Control stream
	StreamTypeData    byte = 0x01 // Data stream
)

Stream types

View Source 
const (
	MsgTypeRegister     byte = 0x01 // Tunnel registration
	MsgTypeRegisterAck  byte = 0x02 // Registration response
	MsgTypeHeartbeat    byte = 0x03 // Heartbeat
	MsgTypeHeartbeatAck byte = 0x04 // Heartbeat response
	MsgTypeNewConn      byte = 0x05 // New connection notification
	MsgTypeCloseConn    byte = 0x06 // Connection close
	MsgTypeError        byte = 0x07 // Error message
	MsgTypeData         byte = 0x08 // Data message (for single-stream mode)
)

Control message types

View Source 
const (
	ProtocolTCP  byte = 0x01
	ProtocolHTTP byte = 0x02
)

Protocol types

Variables

View Source 
var (
	ErrInvalidMessageType   = errors.New("invalid message type")
	ErrInvalidStreamType    = errors.New("invalid stream type")
	ErrAuthenticationFailed = errors.New("authentication failed")
	ErrNoAvailablePort      = errors.New("no available port")
	ErrTunnelNotFound       = errors.New("tunnel not found")
	ErrConnectionClosed     = errors.New("connection closed")
)

Errors

Functions

func DefaultConfig 

func DefaultConfig() *quic.Config

DefaultConfig returns default QUIC configuration

func IsQUICClosedErr 

func IsQUICClosedErr(err error) bool

IsQUICClosedErr returns true if the error indicates a normal QUIC connection close

Types

type ClientStats added in v1.1.0 

type ClientStats struct {
	TunnelID    string
	PublicURL   string
	Connected   bool
	ActiveConns int64
	TotalConns  int64
	BytesIn     int64
	BytesOut    int64
}

ClientStats client statistics

type MuxClient added in v1.1.0 

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

MuxClient QUIC multiplexing client

func NewMuxClient added in v1.1.0 

func NewMuxClient(config MuxClientConfig) *MuxClient

NewMuxClient creates a new QUIC multiplexing client

func (*MuxClient) GetStats added in v1.1.0 

func (s *MuxClient) GetStats() ClientStats

GetStats returns client statistics

func (*MuxClient) PublicURL added in v1.1.0 

func (s *MuxClient) PublicURL() string

PublicURL returns the public URL

func (*MuxClient) Start added in v1.1.0 

func (s *MuxClient) Start(ctx context.Context) error

Start starts the client

func (*MuxClient) Stop added in v1.1.0 

func (s *MuxClient) Stop() error

Stop stops the client

func (*MuxClient) TunnelID added in v1.1.0 

func (s *MuxClient) TunnelID() string

TunnelID returns the tunnel ID

type MuxClientConfig added in v1.1.0 

type MuxClientConfig struct {
	// Server
	ServerAddr string

	// TLS
	TLSConfig *tls.Config

	// QUIC
	QUICConfig *quic.Config

	// Tunnel
	TunnelID  string // Optional, auto-generated if empty
	Protocol  byte   // ProtocolTCP or ProtocolHTTP
	LocalAddr string // Local service address

	// Authentication
	AuthToken string

	// Reconnect
	ReconnectInterval time.Duration
	MaxReconnectTries int // 0 = infinite
}

MuxClientConfig client configuration

func DefaultMuxClientConfig added in v1.1.0 

func DefaultMuxClientConfig() MuxClientConfig

DefaultMuxClientConfig returns default client config

type MuxServer added in v1.1.0 

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

MuxServer QUIC multiplexing server

func NewMuxServer added in v1.1.0 

func NewMuxServer(config MuxServerConfig) *MuxServer

NewMuxServer creates a new QUIC multiplexing server

func (*MuxServer) Addr added in v1.1.0 

func (s *MuxServer) Addr() net.Addr

Addr returns the server's listening address

func (*MuxServer) Dial added in v1.1.0 

func (s *MuxServer) Dial(ctx context.Context, addr string) (net.Conn, error)

Dial connects to the specified address (implements tunnel.Protocol) Note: For MuxServer, this returns an error as it's a server-only implementation

func (*MuxServer) Forwarder added in v1.1.0 

func (s *MuxServer) Forwarder() forward.Forwarder

Forwarder returns the forwarder (implements tunnel.Protocol)

func (*MuxServer) GetStats added in v1.1.0 

func (s *MuxServer) GetStats() ServerStats

GetStats returns server statistics

func (*MuxServer) Listen added in v1.1.0 

func (s *MuxServer) Listen(addr string) (net.Listener, error)

Listen creates a listener on the specified address (implements tunnel.Protocol) Note: For MuxServer, this is a no-op as the server is started via Start()

func (*MuxServer) Name added in v1.1.0 

func (s *MuxServer) Name() string

Name returns the protocol name (implements tunnel.Protocol)

func (*MuxServer) Start added in v1.1.0 

func (s *MuxServer) Start(ctx context.Context) error

Start starts the server

func (*MuxServer) Stop added in v1.1.0 

func (s *MuxServer) Stop() error

Stop stops the server

type MuxServerConfig added in v1.1.0 

type MuxServerConfig struct {
	// Network
	ListenAddr string // UDP address, e.g., ":443"

	// TLS
	TLSConfig *tls.Config

	// QUIC
	QUICConfig *quic.Config

	// Authentication
	AuthToken string

	// TCP tunnel port range
	PortRangeStart int // e.g., 10000
	PortRangeEnd   int // e.g., 20000

	// Limits
	MaxTunnels        int
	MaxConnsPerTunnel int

	// Timeouts
	TunnelTimeout time.Duration
	ConnTimeout   time.Duration
}

MuxServerConfig server configuration

func DefaultMuxServerConfig added in v1.1.0 

func DefaultMuxServerConfig() MuxServerConfig

DefaultMuxServerConfig returns default server config

type PortManager added in v1.1.0 

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

PortManager manages port allocation

func NewPortManager added in v1.1.0 

func NewPortManager(start, end int) *PortManager

NewPortManager creates a port manager

func (*PortManager) Allocate added in v1.1.0 

func (m *PortManager) Allocate() (int, error)

Allocate allocates a port

func (*PortManager) Release added in v1.1.0 

func (m *PortManager) Release(port int)

Release releases a port

type ServerStats added in v1.1.0 

type ServerStats struct {
	ActiveTunnels int64
	TotalTunnels  int64
	ActiveConns   int64
	TotalConns    int64
	BytesIn       int64
	BytesOut      int64
}

ServerStats server statistics

type Tunnel added in v1.1.0 

type Tunnel struct {
	ID        string
	Protocol  byte
	LocalAddr string
	PublicURL string
	Port      int

	// QUIC connection
	Conn quic.Connection

	// Control stream
	ControlStream quic.Stream

	// External connections (server -> external)
	ExternalConns sync.Map // connID -> net.Conn

	// Data streams (server -> client)
	DataStreams sync.Map // connID -> quic.Stream

	// Stats
	CreatedAt  time.Time
	LastActive atomic.Int64
	// contains filtered or unexported fields
}

Tunnel tunnel information

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.