Pillar v0.5.0 — The Messaging API & Documentation Consolidation

Pillar v0.5.0 — The Messaging API & Javadoc Consolidation

Iteration 5 extracts the internal core capabilities into a stable, public-facing API surface. It transforms Pillar from a closed routing proxy into an extensible platform, providing developers with type-safe distributed primitives for cross-server communication, mutual exclusion, and direct routing control, backed by exhaustive concurrency contracts.

Public API Surface & Distributed Primitives

Messaging API — Introduced a complete messaging suite (Pillar#messaging) backed by Redis Streams. Developers can now utilize one-way Pub/Sub (listen/send), asynchronous Request-Response with explicit timeouts (sendRequest), and universal network broadcast, entirely abstracted from the underlying transport layer.
Leases API — Introduced a distributed lock mechanism (Pillar#leases) for mutual exclusion across the fleet. Backend servers can now safely acquire exclusive leases over logical resources (e.g., preventing two lobbies from simultaneously booting the same minigame state).
Routing API — Exposed backend-driven actuation (Pillar#routing), allowing Paper servers to command the proxy to move players. Supports both direct routing (moveToServer) and role-based placement (moveToRole) using the same proxy-side P2C load-balancing algorithm.

API Hardening & Thread-Safety Contracts

Main-Thread Enforcement — Explicitly locked down CompletableFuture contracts. API futures always complete on internal Pillar dispatch threads. Calling join() or get() from the platform's main thread now throws an immediate IllegalStateException, forcibly preventing developers from introducing blocking operations that freeze the server.
Thread-Hopping Abstractions — Introduced MessageContext#sync for deterministic execution. It abstracts platform-specific threading guarantees: scheduling on the next tick for Paper when off-thread, while running inline to lock the worker pool on Velocity.
Records & Sum Types — Redesigned message payloads and routing outcomes to heavily utilize Java 21+ records and sealed interfaces, ensuring immutability and complete type-safety across the distributed boundary.

Upgrading from 0.4.0

Drop-in replacement. No breaking configuration changes. Requirements remain unchanged: Paper 26.1.2 and/or Velocity 3.4.0, Java 25, Redis 7. Plugin developers should migrate from internal classes to the new br.com.markineo.pillar.api package.

What's next (Iteration 6 — Maven Publication)

Iteration 6 will focus on decoupling the pillar-api module for public Maven publication via build.gradle and rebuilding the official documentation site to guide developers on utilizing the new distributed primitives.