Documentation
¶
Index ¶
- Constants
- Variables
- func GetContainerIP(cli DockerInspector, containerID string, networkName string) (string, error)
- func NewMockValkeyClient() *routing.MockValkeyClient
- func NewRespClient(addr string, password ...string) *routing.RespClient
- func WriteHandshakePacket(w io.Writer, packet *HandshakePacket) error
- func WriteProxyV2Header(w io.Writer, srcAddr, dstAddr net.Addr) error
- func WriteVarInt(w io.Writer, value VarInt) error
- type ActivityHandler
- type Backend
- type Config
- type DirectKnockManager
- func (m *DirectKnockManager) HasKnock(serverID string) bool
- func (m *DirectKnockManager) SetAcceptsTransfers(accept bool)
- func (m *DirectKnockManager) SetWakeHandler(h WakeHandler)
- func (m *DirectKnockManager) StartKnock(server *db.Server) error
- func (m *DirectKnockManager) StopAll()
- func (m *DirectKnockManager) StopKnock(serverID string)
- type DockerInspector
- type HTTPProxy
- func (p *HTTPProxy) AddRoute(serverID, hostname, backendHost string, backendPort int)
- func (p *HTTPProxy) GetRoutes() map[string]*Route
- func (p *HTTPProxy) IsRunning() bool
- func (p *HTTPProxy) RemoveRoute(hostname string)
- func (p *HTTPProxy) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (p *HTTPProxy) SetRouteDown(hostname string, down bool)
- func (p *HTTPProxy) SetRouteHibernated(hostname string, hibernated bool)
- func (p *HTTPProxy) Start() error
- func (p *HTTPProxy) Stop() error
- func (p *HTTPProxy) UpdateRoute(hostname, backendHost string, backendPort int)
- type HandshakePacket
- type KnockAction
- type Manager
- func (m *Manager) AddListener(listener *db.ProxyListener) error
- func (m *Manager) AddModuleRoute(module *db.Module, server *db.Server) error
- func (m *Manager) AllocateProxyPort(serverID string) (int, error)
- func (m *Manager) Apply(ctx context.Context, plan RoutePlan) error
- func (m *Manager) EnsureDefaultListener() (*db.ProxyListener, error)
- func (m *Manager) GetContainerIP(containerID string) (string, error)
- func (m *Manager) GetDirectKnockManager() *DirectKnockManager
- func (m *Manager) GetModuleRoutes() map[int]map[string]*Route
- func (m *Manager) GetRoutes() map[string]*Route
- func (m *Manager) InitDirectKnocks()
- func (m *Manager) IsRunning() bool
- func (m *Manager) RemoveListener(port int) error
- func (m *Manager) RemoveModuleRoute(moduleID string) error
- func (m *Manager) RemoveRouteByHostname(hostname string, listenerID string) error
- func (m *Manager) RemoveServerRoute(serverID string) error
- func (m *Manager) SetActivityHandler(h ActivityHandler)
- func (m *Manager) SetSleepWakeHandler(h WakeHandler)
- func (m *Manager) SetValkeySync(sync *ValkeySyncManager)
- func (m *Manager) SetWakeHandler(h WakeHandler)
- func (m *Manager) Start() error
- func (m *Manager) Stop() error
- func (m *Manager) StopDirectKnock(serverID string)
- func (m *Manager) UpdateModuleRoute(module *db.Module, server *db.Server) error
- func (m *Manager) UpdateServerRoute(server *db.Server) error
- type MinecraftProxy
- func (p *MinecraftProxy) AddRoute(serverID, hostname, backendHost string, backendPort int)
- func (p *MinecraftProxy) GetRoutes() map[string]*Route
- func (p *MinecraftProxy) IsRunning() bool
- func (p *MinecraftProxy) RemoveRoute(hostname string)
- func (p *MinecraftProxy) SetActivityHandler(h ActivityHandler)
- func (p *MinecraftProxy) SetRouteActive(hostname string, active bool)
- func (p *MinecraftProxy) SetRouteDown(hostname string, down bool)
- func (p *MinecraftProxy) SetRouteHibernated(hostname string, hibernated bool)
- func (p *MinecraftProxy) SetSleepWakeHandler(h WakeHandler)
- func (p *MinecraftProxy) SetWakeHandler(h WakeHandler)
- func (p *MinecraftProxy) Start() error
- func (p *MinecraftProxy) Stop() error
- func (p *MinecraftProxy) UpdateRoute(hostname, backendHost string, backendPort int)
- type MockValkeyClient
- type PlanAction
- type PlanInput
- type Proxier
- type ProxyConn
- type ProxyHeader
- type RespClient
- type Route
- type RouteInfo
- type RoutePlan
- type RoutingEvent
- type TCPProxy
- func (p *TCPProxy) AddRoute(serverID, hostname, backendHost string, backendPort int)
- func (p *TCPProxy) GetRoutes() map[string]*Route
- func (p *TCPProxy) IsRunning() bool
- func (p *TCPProxy) RemoveRoute(hostname string)
- func (p *TCPProxy) SetRouteDown(hostname string, down bool)
- func (p *TCPProxy) SetRouteHibernated(hostname string, hibernated bool)
- func (p *TCPProxy) Start() error
- func (p *TCPProxy) Stop() error
- func (p *TCPProxy) UpdateRoute(hostname, backendHost string, backendPort int)
- type UDPProxy
- func (p *UDPProxy) AddRoute(serverID, hostname, backendHost string, backendPort int)
- func (p *UDPProxy) GetRoutes() map[string]*Route
- func (p *UDPProxy) IsRunning() bool
- func (p *UDPProxy) RemoveRoute(hostname string)
- func (p *UDPProxy) SetRouteDown(hostname string, down bool)
- func (p *UDPProxy) SetRouteHibernated(hostname string, hibernated bool)
- func (p *UDPProxy) Start() error
- func (p *UDPProxy) Stop() error
- func (p *UDPProxy) UpdateRoute(hostname, backendHost string, backendPort int)
- type ValkeyClient
- type ValkeySyncManager
- func (v *ValkeySyncManager) BroadcastRouteAdd(ctx context.Context, serverID, hostname, backendHost string, ...) error
- func (v *ValkeySyncManager) BroadcastRouteRemove(ctx context.Context, hostname string, proxyPort int) error
- func (v *ValkeySyncManager) Close() error
- func (v *ValkeySyncManager) SetRemoteHandler(handler func(event *RoutingEvent))
- func (v *ValkeySyncManager) Start(ctx context.Context) error
- type VarInt
- type WakeHandler
Constants ¶
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 )
const ( ValkeyChannelRoutingEvents = routing.ValkeyChannelRoutingEvents ValkeyRouteKeyPrefix = routing.ValkeyRouteKeyPrefix )
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 ¶
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 ¶
WriteProxyV2Header writes a PROXY protocol v2 header to the writer for preserving client IP
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
// HibernatedMOTD is the server-list text for a freezer-paused route.
// Empty uses the default that tells the player a join will wake the server.
HibernatedMOTD string
// HibernatedFavicon is an optional data URL sent with that status response.
HibernatedFavicon string
}
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 ¶
NewHTTPProxy creates a new HTTP reverse proxy instance
func (*HTTPProxy) RemoveRoute ¶
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 ¶
SetRouteDown sets the deep-sleep state for a route (MINE-121)
func (*HTTPProxy) SetRouteHibernated ¶
SetRouteHibernated sets the hibernation state for a route
func (*HTTPProxy) UpdateRoute ¶
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 KnockAction ¶ added in v1.0.39
type KnockAction int
KnockAction is the direct-port wake listener change a plan asks for.
const ( KnockNone KnockAction = iota KnockStart KnockStop )
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 ¶
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 ¶
AllocateProxyPort allocates a proxy port for a server
func (*Manager) Apply ¶ added in v1.0.39
Apply executes a route plan. It performs no store reads; the only I/O is the Valkey broadcast and the direct-knock listener.
func (*Manager) EnsureDefaultListener ¶
func (m *Manager) EnsureDefaultListener() (*db.ProxyListener, error)
Creates default proxy listener if proxy is enabled
func (*Manager) GetContainerIP ¶
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 ¶
GetModuleRoutes returns all module proxy routes
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) RemoveListener ¶
RemoveListener stops and removes a proxy instance for a listener
func (*Manager) RemoveModuleRoute ¶
RemoveModuleRoute removes proxy routes for a module's ports
func (*Manager) RemoveRouteByHostname ¶
Removes a route using the hostname
func (*Manager) RemoveServerRoute ¶
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) StopDirectKnock ¶
func (*Manager) UpdateModuleRoute ¶
UpdateModuleRoute updates proxy routes for a module's ports
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) 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 PlanAction ¶ added in v1.0.39
type PlanAction int
PlanAction is the route mutation a plan asks the manager to perform.
const ( PlanNone PlanAction = iota PlanUpsert PlanRemove PlanDown )
type PlanInput ¶ added in v1.0.39
type PlanInput struct {
Server *db.Server
Node *db.Node
Listener *db.ProxyListener
Hostname string
Backend Backend
BackendErr error
ListenerErr error
ProxyEnabled bool
HasProxies bool
}
PlanInput is everything route policy needs. Store and Docker lookups are performed by the manager before PlanFor is called, so PlanFor stays pure.
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 ¶
ProxyConn wraps a net.Conn to intercept buffered reads and override RemoteAddr
func (*ProxyConn) RemoteAddr ¶
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 ¶
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 RoutePlan ¶ added in v1.0.39
type RoutePlan struct {
Action PlanAction
Knock KnockAction
Server *db.Server
ServerID string
ServerName string
Hostname string
Backend Backend
Hibernated bool
Down bool
ListenerPort int
ListenerErr error
BackendErr error
}
RoutePlan describes the complete route change for one server.
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 ¶
NewTCPProxy creates a new raw TCP proxy instance
func (*TCPProxy) AddRoute ¶
AddRoute sets the backend for TCP proxy (only one route supported, like UDP)
func (*TCPProxy) RemoveRoute ¶
RemoveRoute removes the backend route
func (*TCPProxy) SetRouteDown ¶
SetRouteDown is a no-op for TCPProxy (deep sleep is a Minecraft-protocol feature, MINE-121)
func (*TCPProxy) SetRouteHibernated ¶
SetRouteHibernated is a no-op for TCPProxy
func (*TCPProxy) UpdateRoute ¶
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 (*UDPProxy) RemoveRoute ¶
RemoveRoute removes the backend route
func (*UDPProxy) SetRouteDown ¶
SetRouteDown is a no-op for UDPProxy (deep sleep is a Minecraft-protocol feature, MINE-121)
func (*UDPProxy) SetRouteHibernated ¶
SetRouteHibernated is a no-op for UDPProxy
func (*UDPProxy) UpdateRoute ¶
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 (*ValkeySyncManager) BroadcastRouteRemove ¶
func (*ValkeySyncManager) Close ¶
func (v *ValkeySyncManager) Close() error
func (*ValkeySyncManager) SetRemoteHandler ¶
func (v *ValkeySyncManager) SetRemoteHandler(handler func(event *RoutingEvent))
type VarInt ¶
type VarInt int32
VarInt reads/writes variable-length integers as used in Minecraft protocol
func ReadVarInt ¶
ReadVarInt reads a variable-length integer from the reader