simplewhitelist

README

Gate Simple Whitelist

An ultra-lightweight, high-performance whitelist plugin for the Gate Minecraft proxy.

Features

• ⚡ Zero-Lock Reads: Uses Go sync/atomic.Pointer for 100% lock-free evaluation during player logins (zero mutex contention).
• 🚀 Zero Heap Allocation on Deny: Pre-marshals the kick message once on startup to eliminate allocations.
• 🎯 Multiple Matching Types: Whitelist by Nicknames (case-insensitive), UUIDs, or IP addresses / CIDR subnet blocks.
• 🔄 Hot Reload: In-game /simplewhitelist reload command.
• 🌐 Container & Pelican Ready: Fully compatible with containerized deployments and the Pelican/Pterodactyl panel.

---

Installation

1. Add the package to your Gate proxy

go get github.com/username/gate-simplewhitelist

2. Register the plugin in your main.go / gate.go

package main

import (
	"github.com/username/gate-simplewhitelist"
	"go.minekube.com/gate/cmd/gate"
	"go.minekube.com/gate/pkg/edition/java/proxy"
)

func main() {
	proxy.Plugins = append(proxy.Plugins,
		simplewhitelist.Plugin,
	)

	gate.Execute()
}

---

Configuration

The configuration file is automatically created at config/whitelist.toml:

# Set to true to block anyone not listed below.
enabled = true

# Disconnect message shown to unwhitelisted players.
kick_message = "&cYou are not whitelisted on this server!"

# Allowed player nicknames (case-insensitive)
nicks = [
    "Steve",
    "Alex",
]

# Allowed player UUIDs
uuids = [
    # "069a79f4-44e9-4726-a5be-fca90e38aaf5",
]

# Allowed IP addresses or CIDR subnets
ips = [
    # "127.0.0.1",
    # "192.168.1.50",
    # "10.0.0.0/24",
]

---

In-Game Commands

Command	Description
/simplewhitelist reload	Reloads config/whitelist.toml without restarting the proxy.

---

Pelican / Pterodactyl Panel Integration

If using the Gate Pelican Egg, add this package to your GATE_PLUGINS setting:

github.com/username/gate-simplewhitelist

Pelican will automatically download, bundle, and compile the plugin directly into your proxy binary!

---

📄 License

Apache 2.0 © Andrei

Documentation

Index

• Variables
• func RegisterCommands(p *proxy.Proxy, mgr *Manager)
• type ListConfig
• type ListState
• type Manager
  • func NewManager(configDir string) *Manager
  • func (m *Manager) AddWhitelist(rawTarget string) (TargetType, string, bool, error)
  • func (m *Manager) IsWhitelisted(username string, id uuid.UUID, remoteAddr net.Addr) (bool, c.Component)
  • func (m *Manager) Load() error
  • func (m *Manager) RemoveWhitelist(rawTarget string) (TargetType, string, bool, error)
  • func (m *Manager) SetWhitelistEnabled(enabled bool) error
  • func (m *Manager) WhitelistState() *ListState
• type SuggestionFunc
  • func (f SuggestionFunc) Suggestions(ctx *brigodier.CommandContext, builder *brigodier.SuggestionsBuilder) *brigodier.Suggestions
• type TargetType
  • func DetectTargetType(input string) (TargetType, string)

Variables

var Plugin = proxy.Plugin{
	Name: "SimpleWhitelist",
	Init: func(ctx context.Context, p *proxy.Proxy) error {
		log := logr.FromContextOrDiscard(ctx)
		mgr := NewManager("config")

		if err := mgr.Load(); err != nil {
			log.Error(err, "Failed to load simple whitelist configuration")
			return err
		}

		event.Subscribe(p.Event(), 0, func(e *proxy.LoginEvent) {
			if !e.Allowed() {
				return
			}
			pl := e.Player()

			if !pl.HasPermission("simplewhitelist.bypass") {
				if whitelisted, reason := mgr.IsWhitelisted(pl.Username(), pl.ID(), pl.RemoteAddr()); !whitelisted {
					e.Deny(reason)
					return
				}
			}
		})

		RegisterCommands(p, mgr)

		log.Info("SimpleWhitelist loaded (nicks, uuids, ips, in-game management active)")
		return nil
	},
}

Plugin is the ultra-lightweight, zero-fluff simple whitelist plugin for Gate proxy.

Functions

func RegisterCommands

func RegisterCommands(p *proxy.Proxy, mgr *Manager)

RegisterCommands registers /whitelist, /simplewhitelist, and /swl command trees into Gate.

Types

type ListConfig

type ListConfig struct {
	Enabled     bool     `toml:"enabled"`
	KickMessage string   `toml:"kick_message"`
	Nicks       []string `toml:"nicks"`
	UUIDs       []string `toml:"uuids"`
	IPs         []string `toml:"ips"`
}

ListConfig represents the TOML file structure for whitelist.

type ListState

type ListState struct {
	Enabled     bool
	KickMessage string
	Nicks       map[string]struct{}
	UUIDs       map[string]struct{}
	IPs         []net.IP
	IPNets      []*net.IPNet
	RawNicks    []string
	RawUUIDs    []string
	RawIPs      []string
	KickReason  c.Component
}

ListState holds parsed, fast O(1) in-memory structures for login evaluations.

type Manager

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

Manager handles concurrent in-memory caching and persistent TOML storage for whitelist.

func NewManager

func NewManager(configDir string) *Manager

NewManager initializes a Manager instance.

func (*Manager) AddWhitelist

func (m *Manager) AddWhitelist(rawTarget string) (TargetType, string, bool, error)

AddWhitelist adds an entry to the whitelist and persists to disk.

func (*Manager) IsWhitelisted

func (m *Manager) IsWhitelisted(username string, id uuid.UUID, remoteAddr net.Addr) (bool, c.Component)

IsWhitelisted checks if a player is allowed by the whitelist.

func (*Manager) Load

func (m *Manager) Load() error

Load reads whitelist.toml from disk.

func (*Manager) RemoveWhitelist

func (m *Manager) RemoveWhitelist(rawTarget string) (TargetType, string, bool, error)

RemoveWhitelist removes an entry from the whitelist and persists to disk.

func (*Manager) SetWhitelistEnabled

func (m *Manager) SetWhitelistEnabled(enabled bool) error

SetWhitelistEnabled enables or disables the whitelist and saves to disk.

func (*Manager) WhitelistState

func (m *Manager) WhitelistState() *ListState

WhitelistState returns the current active whitelist state.

type SuggestionFunc

type SuggestionFunc func(ctx *brigodier.CommandContext, builder *brigodier.SuggestionsBuilder) *brigodier.Suggestions

SuggestionFunc adapts a function into a brigodier.SuggestionProvider.

func (SuggestionFunc) Suggestions

func (f SuggestionFunc) Suggestions(ctx *brigodier.CommandContext, builder *brigodier.SuggestionsBuilder) *brigodier.Suggestions

Suggestions implements brigodier.SuggestionProvider.

type TargetType

type TargetType string

TargetType identifies the kind of entity added or removed.

const (
	TargetNick TargetType = "Nick"
	TargetUUID TargetType = "UUID"
	TargetIP   TargetType = "IP"
	TargetCIDR TargetType = "CIDR"
)

func DetectTargetType

func DetectTargetType(input string) (TargetType, string)

DetectTargetType classifies an input string into IP, CIDR, UUID, or Nick.