proxy

package
v1.0.38 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source
const (
	CommandLocal byte = 0x00
	CommandProxy byte = 0x01

	FamilyUnspec byte = 0x00
	FamilyIPv4   byte = 0x10
	FamilyIPv6   byte = 0x20
	FamilyUnix   byte = 0x30

	TransportUnspec byte = 0x00
	TransportStream byte = 0x01
	TransportDgram  byte = 0x02
)
View Source
const (
	ValkeyChannelRoutingEvents = routing.ValkeyChannelRoutingEvents
	ValkeyRouteKeyPrefix       = routing.ValkeyRouteKeyPrefix
)
View Source
const MaxHandshakePacketLength = 32768

MaxHandshakePacketLength is the maximum allowed length of a Minecraft handshake packet (32KB). Minecraft strings can be up to 32767 characters, and Forge/Fabric/FML clients embed extended channel tokens in the address field.

Variables

View Source
var (
	// ProxyV2Signature is the 12-byte magic prefix for PROXY protocol v2
	ProxyV2Signature = []byte{0x0D, 0x0A, 0x0D, 0x0A, 0x00, 0x0D, 0x0A, 0x51, 0x55, 0x49, 0x54, 0x0A}

	ErrTruncatedHeader = errors.New("truncated PROXY protocol v2 header")
	ErrInvalidVersion  = errors.New("unsupported PROXY protocol version (must be v2)")
)

Functions

func GetContainerIP

func GetContainerIP(cli DockerInspector, containerID string, networkName string) (string, error)

GetContainerIP gets the IP address of a container on the specified network using the provided Docker client

func NewMockValkeyClient

func NewMockValkeyClient() *routing.MockValkeyClient

NewMockValkeyClient returns an in-memory Valkey client.

func NewRespClient

func NewRespClient(addr string, password ...string) *routing.RespClient

NewRespClient creates a new RESP client for Valkey or Dragonfly.

func WriteHandshakePacket

func WriteHandshakePacket(w io.Writer, packet *HandshakePacket) error

WriteHandshakePacket writes a handshake packet to the connection

func WriteProxyV2Header

func WriteProxyV2Header(w io.Writer, srcAddr, dstAddr net.Addr) error

WriteProxyV2Header writes a PROXY protocol v2 header to the writer for preserving client IP

func WriteVarInt

func WriteVarInt(w io.Writer, value VarInt) error

WriteVarInt writes a variable-length integer to the writer

Types

type ActivityHandler

type ActivityHandler func(serverID string)

ActivityHandler defines a callback fired when a client shows real login intent (handshake NextState 2 or 3) for a server. Status pings are excluded so scanners and server-list refreshes can never hold a server awake (MINE-120).

type Config

type Config struct {
	ListenAddr       string // Address to listen on (e.g., ":25565" or ":8080")
	Logger           *logger.Logger
	ProxyProtocol    bool            // Whether PROXY protocol v2 support is enabled on this listener
	WakeHandler      WakeHandler     // Callback to unpause hibernated container upon player connect (MINE-18)
	ActivityHandler  ActivityHandler // Callback to reset idle tracking upon login intent (MINE-120)
	SleepWakeHandler WakeHandler     // Callback to boot a deeply-asleep container upon login intent (MINE-121)
	// AcceptsTransfers controls handshake NextState=3. Nil accepts transfers
	// (Carbon's default). A pointer to false disconnects them before wake or dial.
	// Velocity defaults the same switch to false; this panel is a hostname router.
	AcceptsTransfers *bool
	// LoginRateLimit is the minimum gap between handshakes from one client IP
	// on this listen port. Zero disables the limit. Status and login share it.
	// Established play sessions are not interrupted (MINE-204).
	LoginRateLimit time.Duration
}

Config holds proxy configuration

type DirectKnockManager

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

DirectKnockManager manages direct port TCP listeners for deeply-asleep servers that do not have a proxy hostname (i.e. direct-port servers).

func NewDirectKnockManager

func NewDirectKnockManager(wakeHandler WakeHandler, log *logger.Logger) *DirectKnockManager

NewDirectKnockManager creates a new DirectKnockManager.

func (*DirectKnockManager) HasKnock

func (m *DirectKnockManager) HasKnock(serverID string) bool

HasKnock reports whether a direct knock listener is active for serverID.

func (*DirectKnockManager) SetAcceptsTransfers

func (m *DirectKnockManager) SetAcceptsTransfers(accept bool)

SetAcceptsTransfers disables handshake NextState=3 when false. The default is true (MINE-203). Velocity's accepts-transfers defaults to false.

func (*DirectKnockManager) SetWakeHandler

func (m *DirectKnockManager) SetWakeHandler(h WakeHandler)

SetWakeHandler updates the wake callback used when a client attempts to join.

func (*DirectKnockManager) StartKnock

func (m *DirectKnockManager) StartKnock(server *db.Server) error

StartKnock starts a TCP listener on the server's port.

func (*DirectKnockManager) StopAll

func (m *DirectKnockManager) StopAll()

StopAll stops all active direct knock listeners.

func (*DirectKnockManager) StopKnock

func (m *DirectKnockManager) StopKnock(serverID string)

StopKnock stops the direct knock listener for a specific server.

type DockerInspector

type DockerInspector interface {
	ContainerInspect(ctx context.Context, containerID string, options client.ContainerInspectOptions) (client.ContainerInspectResult, error)
}

DockerInspector is the subset of the Docker client used for container IP resolution. It exists so tests can fake inspection without a daemon.

type HTTPProxy

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

HTTPProxy handles HTTP reverse proxying with Host header based routing

func NewHTTPProxy

func NewHTTPProxy(cfg *Config) *HTTPProxy

NewHTTPProxy creates a new HTTP reverse proxy instance

func (*HTTPProxy) AddRoute

func (p *HTTPProxy) AddRoute(serverID, hostname, backendHost string, backendPort int)

AddRoute adds a new routing rule

func (*HTTPProxy) GetRoutes

func (p *HTTPProxy) GetRoutes() map[string]*Route

GetRoutes returns a copy of all current routes

func (*HTTPProxy) IsRunning

func (p *HTTPProxy) IsRunning() bool

IsRunning returns whether the proxy is running

func (*HTTPProxy) RemoveRoute

func (p *HTTPProxy) RemoveRoute(hostname string)

RemoveRoute removes a routing rule

func (*HTTPProxy) ServeHTTP

func (p *HTTPProxy) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler for routing requests

func (*HTTPProxy) SetRouteDown

func (p *HTTPProxy) SetRouteDown(hostname string, down bool)

SetRouteDown sets the deep-sleep state for a route (MINE-121)

func (*HTTPProxy) SetRouteHibernated

func (p *HTTPProxy) SetRouteHibernated(hostname string, hibernated bool)

SetRouteHibernated sets the hibernation state for a route

func (*HTTPProxy) Start

func (p *HTTPProxy) Start() error

Start starts the HTTP proxy server

func (*HTTPProxy) Stop

func (p *HTTPProxy) Stop() error

Stop stops the HTTP proxy server

func (*HTTPProxy) UpdateRoute

func (p *HTTPProxy) UpdateRoute(hostname, backendHost string, backendPort int)

UpdateRoute updates the backend for a route

type HandshakePacket

type HandshakePacket struct {
	ProtocolVersion VarInt
	ServerAddress   string
	ServerPort      uint16
	NextState       VarInt // 1 status, 2 login, 3 transfer (then Login)
}

HandshakePacket represents the initial handshake packet from a Minecraft client

func ReadHandshakePacket

func ReadHandshakePacket(r io.Reader) (*HandshakePacket, error)

ReadHandshakePacket reads a handshake packet from the connection

type Manager

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

Manager handles the lifecycle of the proxy and manages routes

func NewManager

func NewManager(store *db.Store, cfg *config.Config, logger *logger.Logger, dockerCli ...DockerInspector) *Manager

NewManager creates a new proxy manager

func (*Manager) AddListener

func (m *Manager) AddListener(listener *db.ProxyListener) error

AddListener creates and starts a proxy instance for a new listener

func (*Manager) AddModuleRoute

func (m *Manager) AddModuleRoute(module *db.Module, server *db.Server) error

AddModuleRoute adds a proxy route for a module's ports Modules use their own ports on the same hostname as their parent server

func (*Manager) AllocateProxyPort

func (m *Manager) AllocateProxyPort(serverID string) (int, error)

AllocateProxyPort allocates a proxy port for a server

func (*Manager) EnsureDefaultListener

func (m *Manager) EnsureDefaultListener() (*db.ProxyListener, error)

Creates default proxy listener if proxy is enabled

func (*Manager) GetContainerIP

func (m *Manager) GetContainerIP(containerID string) (string, error)

GetContainerIP gets the IP address of a container using the Manager's Docker client

func (*Manager) GetDirectKnockManager

func (m *Manager) GetDirectKnockManager() *DirectKnockManager

GetDirectKnockManager returns the direct knock manager instance.

func (*Manager) GetModuleRoutes

func (m *Manager) GetModuleRoutes() map[int]map[string]*Route

GetModuleRoutes returns all module proxy routes

func (*Manager) GetRoutes

func (m *Manager) GetRoutes() map[string]*Route

GetRoutes returns all current proxy routes from all proxies

func (*Manager) InitDirectKnocks

func (m *Manager) InitDirectKnocks()

StopDirectKnock stops any active direct knock listener for a server. InitDirectKnocks initializes direct knock listeners for all eligible asleep servers.

func (*Manager) IsRunning

func (m *Manager) IsRunning() bool

IsRunning returns whether any proxy is running

func (*Manager) RemoveListener

func (m *Manager) RemoveListener(port int) error

RemoveListener stops and removes a proxy instance for a listener

func (*Manager) RemoveModuleRoute

func (m *Manager) RemoveModuleRoute(moduleID string) error

RemoveModuleRoute removes proxy routes for a module's ports

func (*Manager) RemoveRouteByHostname

func (m *Manager) RemoveRouteByHostname(hostname string, listenerID string) error

Removes a route using the hostname

func (*Manager) RemoveServerRoute

func (m *Manager) RemoveServerRoute(serverID string) error

RemoveServerRoute removes a route for a server

func (*Manager) SetActivityHandler

func (m *Manager) SetActivityHandler(h ActivityHandler)

SetActivityHandler configures the login-intent activity callback across proxies (MINE-120). Stored so proxies created later also receive it.

func (*Manager) SetSleepWakeHandler

func (m *Manager) SetSleepWakeHandler(h WakeHandler)

SetSleepWakeHandler configures the deep-sleep boot callback across proxies (MINE-121). Stored so proxies created later also receive it.

func (*Manager) SetValkeySync

func (m *Manager) SetValkeySync(sync *ValkeySyncManager)

SetValkeySync configures the Valkey / Dragonfly routing sync manager

func (*Manager) SetWakeHandler

func (m *Manager) SetWakeHandler(h WakeHandler)

SetWakeHandler configures the wake callback for hibernated servers across proxies (MINE-18)

func (*Manager) Start

func (m *Manager) Start() error

Start initializes and starts the proxy if enabled

func (*Manager) Stop

func (m *Manager) Stop() error

Stop stops all proxy instances

func (*Manager) StopDirectKnock

func (m *Manager) StopDirectKnock(serverID string)

func (*Manager) UpdateModuleRoute

func (m *Manager) UpdateModuleRoute(module *db.Module, server *db.Server) error

UpdateModuleRoute updates proxy routes for a module's ports

func (*Manager) UpdateServerRoute

func (m *Manager) UpdateServerRoute(server *db.Server) error

UpdateServerRoute updates or creates a route for a server

type MinecraftProxy

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

MinecraftProxy handles Minecraft protocol proxying with handshake parsing for hostname-based routing

func NewMinecraftProxy

func NewMinecraftProxy(cfg *Config) *MinecraftProxy

NewMinecraftProxy creates a new Minecraft proxy instance

func (*MinecraftProxy) AddRoute

func (p *MinecraftProxy) AddRoute(serverID, hostname, backendHost string, backendPort int)

AddRoute adds a new routing rule

func (*MinecraftProxy) GetRoutes

func (p *MinecraftProxy) GetRoutes() map[string]*Route

GetRoutes returns a copy of all current routes

func (*MinecraftProxy) IsRunning

func (p *MinecraftProxy) IsRunning() bool

IsRunning returns whether the proxy is running

func (*MinecraftProxy) RemoveRoute

func (p *MinecraftProxy) RemoveRoute(hostname string)

RemoveRoute removes a routing rule

func (*MinecraftProxy) SetActivityHandler

func (p *MinecraftProxy) SetActivityHandler(h ActivityHandler)

SetActivityHandler configures the login-intent activity callback (MINE-120)

func (*MinecraftProxy) SetRouteActive

func (p *MinecraftProxy) SetRouteActive(hostname string, active bool)

SetRouteActive enables or disables a route

func (*MinecraftProxy) SetRouteDown

func (p *MinecraftProxy) SetRouteDown(hostname string, down bool)

SetRouteDown marks a route's backend as deeply asleep (or back). Clearing the flag also clears any recorded boot attempt for the hostname.

func (*MinecraftProxy) SetRouteHibernated

func (p *MinecraftProxy) SetRouteHibernated(hostname string, hibernated bool)

SetRouteHibernated enables or disables hibernation state for a route

func (*MinecraftProxy) SetSleepWakeHandler

func (p *MinecraftProxy) SetSleepWakeHandler(h WakeHandler)

SetSleepWakeHandler configures the deep-sleep boot callback (MINE-121)

func (*MinecraftProxy) SetWakeHandler

func (p *MinecraftProxy) SetWakeHandler(h WakeHandler)

SetWakeHandler configures the wake callback for hibernated servers

func (*MinecraftProxy) Start

func (p *MinecraftProxy) Start() error

Start starts the proxy server

func (*MinecraftProxy) Stop

func (p *MinecraftProxy) Stop() error

Stop stops the proxy server

func (*MinecraftProxy) UpdateRoute

func (p *MinecraftProxy) UpdateRoute(hostname, backendHost string, backendPort int)

UpdateRoute updates the backend for a route

type MockValkeyClient

type MockValkeyClient = routing.MockValkeyClient

MockValkeyClient provides an in-memory client for testing or standalone execution.

type Proxier

type Proxier interface {
	Start() error
	Stop() error
	AddRoute(serverID, hostname, backendHost string, backendPort int)
	RemoveRoute(hostname string)
	UpdateRoute(hostname, backendHost string, backendPort int)
	SetRouteHibernated(hostname string, hibernated bool)
	SetRouteDown(hostname string, down bool)
	GetRoutes() map[string]*Route
	IsRunning() bool
}

Proxier is the interface for all proxy types (TCP, UDP, Minecraft, HTTP)

type ProxyConn

type ProxyConn struct {
	net.Conn
	// contains filtered or unexported fields
}

ProxyConn wraps a net.Conn to intercept buffered reads and override RemoteAddr

func (*ProxyConn) Read

func (c *ProxyConn) Read(b []byte) (int, error)

func (*ProxyConn) RemoteAddr

func (c *ProxyConn) RemoteAddr() net.Addr

type ProxyHeader

type ProxyHeader struct {
	Version   byte
	Command   byte
	Transport byte
	SrcAddr   *net.TCPAddr
	DstAddr   *net.TCPAddr
}

ProxyHeader contains the parsed PROXY protocol v2 details

func ParseProxyV2Header

func ParseProxyV2Header(r io.Reader) (*ProxyHeader, error)

ParseProxyV2Header reads and parses a PROXY protocol v2 header from the reader

func WrapConnWithProxyProtocol

func WrapConnWithProxyProtocol(conn net.Conn) (net.Conn, *ProxyHeader, error)

WrapConnWithProxyProtocol peeks the incoming connection for PROXY protocol v2 signature. If present, it consumes and parses the header, returning a wrapped connection with real client RemoteAddr. If absent, it transparently returns the connection without modifying the payload stream.

type RespClient

type RespClient = routing.RespClient

RespClient implements a lightweight Go-native Redis RESP protocol client.

type Route

type Route struct {
	ServerID    string
	Hostname    string
	BackendHost string
	BackendPort int
	Active      bool
	Hibernated  bool
	// Down marks a deeply-asleep backend (container stopped, zero RAM).
	// Down routes never dial: pings get a cached MOTD, logins trigger a
	// boot via SleepWakeHandler and are held until the SLP health gate
	// passes (MINE-121).
	Down bool
}

Route represents a routing rule from hostname to backend server

type RouteInfo

type RouteInfo = routing.RouteInfo

RouteInfo holds stored route details in Valkey / Dragonfly KV.

type RoutingEvent

type RoutingEvent struct {
	Action      string `json:"action"` // "add", "update", "remove"
	ServerID    string `json:"server_id"`
	Hostname    string `json:"hostname"`
	BackendHost string `json:"backend_host,omitempty"`
	BackendPort int    `json:"backend_port,omitempty"`
	ProxyPort   int    `json:"proxy_port"`
	OriginNode  string `json:"origin_node"`
	Timestamp   int64  `json:"timestamp"`
}

RoutingEvent represents a pub/sub broadcast event for route synchronization.

type TCPProxy

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

TCPProxy handles raw TCP forwarding without protocol parsing

func NewTCPProxy

func NewTCPProxy(cfg *Config) *TCPProxy

NewTCPProxy creates a new raw TCP proxy instance

func (*TCPProxy) AddRoute

func (p *TCPProxy) AddRoute(serverID, hostname, backendHost string, backendPort int)

AddRoute sets the backend for TCP proxy (only one route supported, like UDP)

func (*TCPProxy) GetRoutes

func (p *TCPProxy) GetRoutes() map[string]*Route

GetRoutes returns the current route (TCP only has one)

func (*TCPProxy) IsRunning

func (p *TCPProxy) IsRunning() bool

IsRunning returns whether the proxy is running

func (*TCPProxy) RemoveRoute

func (p *TCPProxy) RemoveRoute(hostname string)

RemoveRoute removes the backend route

func (*TCPProxy) SetRouteDown

func (p *TCPProxy) SetRouteDown(hostname string, down bool)

SetRouteDown is a no-op for TCPProxy (deep sleep is a Minecraft-protocol feature, MINE-121)

func (*TCPProxy) SetRouteHibernated

func (p *TCPProxy) SetRouteHibernated(hostname string, hibernated bool)

SetRouteHibernated is a no-op for TCPProxy

func (*TCPProxy) Start

func (p *TCPProxy) Start() error

Start starts the TCP proxy server

func (*TCPProxy) Stop

func (p *TCPProxy) Stop() error

Stop stops the TCP proxy server

func (*TCPProxy) UpdateRoute

func (p *TCPProxy) UpdateRoute(hostname, backendHost string, backendPort int)

UpdateRoute updates the backend address

type UDPProxy

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

UDPProxy handles UDP forwarding for modules like Geyser Implements the Proxier interface

func NewUDPProxy

func NewUDPProxy(cfg *Config) *UDPProxy

NewUDPProxy creates a new UDP proxy

func (*UDPProxy) AddRoute

func (p *UDPProxy) AddRoute(serverID, hostname, backendHost string, backendPort int)

AddRoute sets the backend for UDP proxy (only one route supported)

func (*UDPProxy) GetRoutes

func (p *UDPProxy) GetRoutes() map[string]*Route

GetRoutes returns the current route (UDP only has one)

func (*UDPProxy) IsRunning

func (p *UDPProxy) IsRunning() bool

IsRunning returns whether the proxy is running

func (*UDPProxy) RemoveRoute

func (p *UDPProxy) RemoveRoute(hostname string)

RemoveRoute removes the backend route

func (*UDPProxy) SetRouteDown

func (p *UDPProxy) SetRouteDown(hostname string, down bool)

SetRouteDown is a no-op for UDPProxy (deep sleep is a Minecraft-protocol feature, MINE-121)

func (*UDPProxy) SetRouteHibernated

func (p *UDPProxy) SetRouteHibernated(hostname string, hibernated bool)

SetRouteHibernated is a no-op for UDPProxy

func (*UDPProxy) Start

func (p *UDPProxy) Start() error

Start starts the UDP proxy

func (*UDPProxy) Stop

func (p *UDPProxy) Stop() error

Stop stops the UDP proxy

func (*UDPProxy) UpdateRoute

func (p *UDPProxy) UpdateRoute(hostname, backendHost string, backendPort int)

UpdateRoute updates the backend address

type ValkeyClient

type ValkeyClient = routing.ValkeyClient

ValkeyClient is an interface for Valkey/Dragonfly KV and pub/sub operations.

type ValkeySyncManager

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

ValkeySyncManager orchestrates routing synchronization with Valkey / Dragonfly.

func NewValkeySyncManager

func NewValkeySyncManager(client ValkeyClient, nodeID string, log *logger.Logger) *ValkeySyncManager

func (*ValkeySyncManager) BroadcastRouteAdd

func (v *ValkeySyncManager) BroadcastRouteAdd(ctx context.Context, serverID, hostname, backendHost string, backendPort, proxyPort int) error

func (*ValkeySyncManager) BroadcastRouteRemove

func (v *ValkeySyncManager) BroadcastRouteRemove(ctx context.Context, hostname string, proxyPort int) error

func (*ValkeySyncManager) Close

func (v *ValkeySyncManager) Close() error

func (*ValkeySyncManager) SetRemoteHandler

func (v *ValkeySyncManager) SetRemoteHandler(handler func(event *RoutingEvent))

func (*ValkeySyncManager) Start

func (v *ValkeySyncManager) Start(ctx context.Context) error

type VarInt

type VarInt int32

VarInt reads/writes variable-length integers as used in Minecraft protocol

func ReadVarInt

func ReadVarInt(r io.Reader) (VarInt, error)

ReadVarInt reads a variable-length integer from the reader

func (VarInt) Len

func (v VarInt) Len() int

Len returns the length of the VarInt when encoded

type WakeHandler

type WakeHandler func(ctx context.Context, serverID string) error

WakeHandler defines a callback for waking/unfreezing a hibernated server container

Jump to

Keyboard shortcuts

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