Magnus (Server-Side)

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 & Drift Prevention	60 sec	Messages older than 60 seconds or with timestamps >60s in the future 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,
    "enableGlobalServerState": false,
    "enableSessionLock": false,
    "enableMessageSigning": true,
    "messageSigningSecret": "auto-generated-on-first-run",
    "signatureTimestampToleranceMs": 60000,
    "redisSsl": false,
    "serverStateHeartbeatIntervalMs": 2500
}

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
enableGlobalServerState	false	Publish read-only live server facts for agent tools
enableSessionLock	false	Enable session locking to prevent concurrent logins
enableMessageSigning	true	Enable HMAC message signing (recommended)
signatureTimestampToleranceMs	60000	HMAC signature timestamp tolerance in milliseconds (for message age and clock drift)
redisSsl	false	Enable SSL/TLS for Redis connections
serverStateHeartbeatIntervalMs	2500	Server-state heartbeat interval in milliseconds

Commands

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

Development

Prerequisites

• Docker Desktop

All development tasks run inside a Docker container. You don't need Java, Gradle, PostgreSQL, or Redis installed on your host.

Commands

Command	Description
make build	Compile and package the mod
make test	Run all tests (unit + integration)
make lint	Run Detekt static analysis
make shell	Open a shell in the dev container
make up	Start PostgreSQL and Redis for manual testing
make down	Stop all services

First Run

make build

The first build downloads all dependencies (including Minecraft assets) and caches them in a persistent Docker volume. Subsequent builds are significantly faster.

Running Tests

make test

Integration tests use Testcontainers to spin up isolated PostgreSQL and Redis instances automatically.

Code Quality

make lint

This project uses Detekt for Kotlin static analysis. Configuration is in detekt.yml.

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