Magnus (Server-Side)

!Build Status !Minecraft Version !Fabric !Kotlin !GitHub Release

!PostgreSQL !Redis !Trivy !License

A modular, high-performance, and resilient synchronization suite for Minecraft Fabric servers. Features real-time inventory sync, cross-server chat, and global player management.

Features

Core Sync

• Multi-Server Sync: Syncs Inventory, Ender Chest, Health, Hunger, XP, Potion Effects.
• High Performance: Uses Redis for sub-millisecond data retrieval.
• Persistence: Uses PostgreSQL for permanent reliable storage.
• Fault Tolerance:
  • Circuit Breaker: Detects database failures automatically.
  • Local Fallback: Saves data to disk if the database goes down.
  • Auto-Recovery: "The Janitor" service automatically restores data when the database comes back online.

Modules

Module	Description
Inventory Sync	Core synchronization of inventory, ender chest, health, hunger, XP, and potion effects. Enabled by default.
Global Chat	Syncs chat messages across all servers via Redis pub/sub. Raw text format for compatibility with LuckPerms, Stylist, etc.
Global Player List	Maintains a global player count with heartbeat. Provides /glist command.
Session Lock	Prevents concurrent logins by locking player sessions during sync. Players are held in queue until their data is safely transferred.

Security

Feature	Default	Description
Message Signing	✅ Enabled	HMAC-SHA256 prevents message injection attacks
Auto-Generated Secret	✅	32-byte cryptographic secret generated on first run
Replay Prevention	30 sec	Messages older than 30 seconds are rejected
Payload Size Limits	64KB	Prevents DoS via oversized messages
SSL/TLS Support	Optional	Encrypt Redis connections

Configuration

Magnus requires a PostgreSQL database and a Redis instance to function.

1. Generate Config: Start your server once to generate the default configuration file at config/magnus.json.
2. Edit Config: Stop the server and open config/magnus.json:

{
    "postgresUrl": "jdbc:postgresql://your-db-host:5432/magnus",
    "postgresUser": "your_user",
    "postgresPass": "your_password",
    "redisHost": "your-redis-host",
    "redisPort": 6379,
    "redisPass": null,
    "serverName": "survival",
    "enableInventorySync": true,
    "enableGlobalChat": false,
    "enableGlobalPlayerList": false,
    "enableSessionLock": false,
    "enableMessageSigning": true,
    "messageSigningSecret": "auto-generated-on-first-run",
    "redisSsl": false
}

3. Launch: Restart your server. Magnus will automatically verify the connection and create the necessary database schema.

[!IMPORTANT] Multi-Server Setup: Copy the messageSigningSecret from the first server to all other servers. All servers must use the same secret.

Configuration Options

Option	Default	Description
serverName	"default"	Unique identifier for this server (e.g., "survival", "lobby")
enableInventorySync	true	Enable inventory/player data synchronization. Disable for lobby servers.
enableGlobalChat	false	Enable cross-server chat synchronization
enableGlobalPlayerList	false	Enable global player list and /glist command
enableSessionLock	false	Enable session locking to prevent concurrent logins
enableMessageSigning	true	Enable HMAC message signing (recommended)
redisSsl	false	Enable SSL/TLS for Redis connections

Commands

Command	Description
/glist	Shows total player count and players grouped by server (requires enableGlobalPlayerList)

Architecture

For detailed flow diagrams and behavior documentation:

• Core Sync Flow - Data synchronization and fault tolerance
• Global Chat Flow - Cross-server chat messaging
• Global Player List Flow - Player list heartbeat and /glist
• Session Lock Flow - Login queue and session locking
• Message Security Flow - HMAC signing and replay prevention
• Server Lifecycle Flow - Startup and shutdown sequence