> ## Documentation Index
> Fetch the complete documentation index at: https://nexus-core.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Nexus Core Changelog
> Complete version history for Nexus Core, from the first stable release (v1.0.0) through the latest release (v1.7.0), newest first.
This page lists every Nexus Core release, newest first. Breaking behavior changes and security patches are highlighted.
## v1.7.0 — Multi-Database Support and Architecture Refactor (Sep 11, 2026)
This is the first major version release since v1.0.0 and introduces a fully abstracted database layer. Nexus Core is no longer hard-wired to MongoDB: addons can now target PostgreSQL, MySQL, or any supported adapter through a unified provider/driver interface.
**Database provider/driver abstraction:**
* The persistence layer has been refactored behind a generic **database provider interface**. MongoDB remains supported as the default adapter; PostgreSQL and MySQL adapters are shipping as the first additional targets.
* Addons declare which provider they use through configuration rather than hard-coded MongoDB calls. The framework handles connection routing at runtime.
**Dynamic connection routing:**
* Database connections are resolved at request time based on each addon's cache context and the active configuration. Multiple data sources can be live simultaneously; different addons can target different databases within the same Nexus Core instance.
**Configuration schema update:**
* The configuration schema has been extended to support multiple named data source definitions. Each data source entry specifies its driver type, connection URI, and any driver-specific options. The existing single-MongoDB configuration continues to work as the `default` data source.
**Integration test suites:**
* New integration test suites have been added for each supported database adapter, covering connection lifecycle, CRUD operations, and Nexus Core protocol compatibility.
**Breaking change:** `DataAddon#getDatabase()` and `DataAddon#getCollection()` semantics depend on the selected driver. Addons targeting MongoDB are unaffected if they rely on the default data source. Addons that directly reference MongoDB-specific APIs will need to migrate to the new provider interface to use non-MongoDB adapters.
## v1.6.6 — Reliability, Security, and Dashboard Refresh (Sep 8, 2026)
This release strengthens message delivery guarantees, cache mutation ordering, persistence correctness, and authentication defaults, while shipping a redesigned dashboard.
**Reliability and data integrity:**
* **Premature acknowledgement fix:** Messages are now acknowledged (`XACK`) only after tracked tasks and MongoDB persistence complete successfully. Previously, a failure mid-processing could result in an acknowledged-but-lost write. Failed operations can now be safely retried.
* **Pending write isolation:** Pending writes are preserved independently from the L1 Caffeine cache. Cache eviction or `L1InvalidationBus` invalidation no longer risks discarding queued persistence operations.
* **Per-key locking fix:** Concurrent mutations for the same key are now processed in a predictable, serialized order. Improves consistency under high write concurrency.
* **Persistence failures surface correctly:** Storage failures now propagate up to the message processing layer instead of being silently swallowed and acknowledged. The circuit breaker and retry logic introduced in v1.6.4 can now act on these failures.
**Security:**
* **Unsigned messages rejected by default.** Nexus Core now rejects inbound messages that lack a valid `sig` field when `NEXUS_SIGNING_KEY` is set, with no fallback to unsigned processing. An explicit compatibility flag is available for environments that still need to accept legacy unsigned messages during a transition period.
* Message consumption now starts only after application initialization has fully completed, eliminating a race window where messages could arrive before addons were registered.
The default behavior change for unsigned messages may break Spigot-side clients that are not yet signing their outbound packets. Set `NEXUS_SIGNING_KEY` on both sides before upgrading, or enable the explicit legacy compatibility flag during your transition.
**Dashboard refresh:**
* Improved overall interface design, refined layouts, and better visual consistency.
* Cleaner and more modern appearance across all panels.
* Improved usability and administration experience.
**Runtime regression tests:**
* Added regression coverage for critical message-processing guarantees. All checks passed: 27 Redis/MongoDB checks, 8 HTTP checks, 2 signature policy checks.
## v1.6.5 — Two-Tier L1/L2 Caching with Caffeine (Sep 7, 2026)
This release upgrades the L1 in-memory cache from a raw `ConcurrentHashMap` to **Caffeine** with bounded capacity and per-entry TTL, adds a `l1CacheEnabled()` opt-out per addon, introduces the `L1InvalidationBus` for instant cross-instance cache invalidation, and ships a full cache metrics panel and key browser in the web dashboard.
**L1 cache upgrade (Caffeine):**
* Replaced `RedisDataContainer`'s raw `ConcurrentHashMap` L1 layer with **Caffeine** (`maximumSize=100,000`). Eviction uses the **W-TinyLFU** policy, which provides near-optimal hit rates under skewed access patterns.
* Per-entry TTL is driven by each addon's `getCacheTTL()` value. Entries expire automatically without a background sweep thread.
* Added dependency: `caffeine:3.1.8`.
**`DataAddon#l1CacheEnabled()` (new opt-out method):**
* Override and return `false` to bypass L1 entirely for an addon. Reads will always pass through to Redis (L2) first. Useful for large payloads or rarely-accessed data where memory trade-off is not worth it. Default is `true` (L1 enabled).
**`L1InvalidationBus` (cluster-ready invalidation):**
* Added a dedicated Redis Pub/Sub channel that broadcasts cache key invalidations the instant a `SET_DATA` or `REMOVE_DATA` operation completes. This replaces waiting on the existing 10-second L1 sync poll for invalidation events.
* Gated behind the `NEXUS_CLUSTER_MODE` environment variable (default `false`). When Nexus Core runs as a single instance (the current default), the bus is disabled and there is zero overhead. Set `NEXUS_CLUSTER_MODE=true` when scaling Nexus Core horizontally.
**`CacheMetrics`:**
* Added per-addon counters for L1, L2, and L3 (MongoDB) hits and a hit-ratio snapshot.
**Web dashboard additions:**
* `GET /api/cache-metrics` — per-addon L1/L2/L3 hit counts and L1 hit ratio.
* `GET /api/addons/{addonId}/keys` — paginated key listing using Redis `SCAN` (not `KEYS`, to avoid blocking Redis).
* `GET /api/keys/value` — fetch a single key's raw value and the layer it was served from (L1 or L2).
* `GET /api/stats` extended with `l1Hits`, `l2Hits`, `l3Hits`, `l1HitRatio`, and `clusterMode` fields.
* New **L1 hit ratio** stat card with sparkline history.
* New **Cache Performance** table showing per-addon L1/L2/L3 breakdown with a visual ratio bar.
* New **Key Browser** panel: select an addon, page through its cached keys using SCAN cursor pagination, and expand a row to inspect its live JSON value and source layer.
* Full TR/EN i18n coverage for all new UI strings.
No behavior change for existing addons. L1 stays enabled by default with the same TTL semantics as before. `DataAddon` subclasses require no code changes unless you want to opt out of L1 for a specific addon.
## v1.6.4 — Redis Streams Migration and Fault Tolerance (Sep 6, 2026)
This release is a major reliability upgrade. The messaging pipeline migrates from Redis Pub/Sub to **Redis Streams**, and Resilience4j **Circuit Breakers** and **Exponential Backoff Retry** are added to protect against database and cache outages.
**Redis Streams migration (at-least-once delivery):**
* Replaced fire-and-forget Redis Pub/Sub with **Redis Streams** (`XADD`, `XREADGROUP`, `XACK`). Messages are now persisted in the stream until explicitly acknowledged, guaranteeing at-least-once delivery.
* Added **consumer group** processing to enable distributed load balancing across multiple worker instances.
* Unacknowledged messages are retained across reconnects, preventing data loss during node failovers or network interruptions.
**Circuit Breaker integration (Resilience4j):**
* Wrapped MongoDB and Redis calls in **Resilience4j Circuit Breakers** to isolate failing endpoints immediately instead of exhausting thread pools.
* When a backend service error rate exceeds the threshold, the circuit trips to `OPEN` state, shedding unprocessable load and allowing downstream systems time to recover.
**Exponential Backoff Retry:**
* Failed database mutations and packet delivery attempts now automatically retry using an **exponential backoff policy**.
* **Jitter** is added to retry intervals to prevent retry storms (thundering herd problem) during recovery phases.
* Retry and circuit breaker logic is wired directly into the Java 21 virtual thread executors introduced in v1.6.3.
**Breaking change:** Applications that connect directly to the `darkland_nexus` Redis Pub/Sub channel must update their configuration to use Redis Streams consumer groups. `DataAddon` subclasses and custom `RequestHandler` implementations require no code changes.
## v1.6.3 — Virtual Thread Executors (Sep 5, 2026)
This release replaces legacy internal Redis worker threads with dedicated virtual thread executors, improving task isolation and scalability.
**What changed:**
* Replaced gacy internal Redis worker threads with **dedicated virtual thread executors** (`Executors.newVirtualThreadPerTaskExecutor()`).
* Added **separate outbound and MongoDB executors** in `RedisManager` to isolate task types and prevent contention.
* Updated `MongoManager` to accept and use the **shared MongoDB executor** passed from `RedisManager`, ensuring all async database operations run through a single, consistent executor pool.
* Migrated all `MongoManager` `supplyAsync` and `runAsync` calls to execute through the dedicated executor.
* Updated application initialization (`NexusApplication`) to pass the MongoDB executor from `RedisManager` to `MongoManager`.
**Why this matters:**
Virtual threads (Project Loom) are low-cost and managed by the JVM scheduler, so Nexus Core no longer needs to manage platform thread pools manually for outbound and database tasks. Separating the Redis outbound executor from the MongoDB executor prevents a burst of database queries from starving Redis publishes, and vice versa.
No breaking changes. Existing DataAddon subclasses require no modifications.
## v1.6.2 — Handler Registry and Request Dispatch (Sep 5, 2026)
This release refactors request handling inside `DataAddon` from a monolithic dispatch model to a **pluggable handler registry**.
**What changed:**
* Introduced the `RequestHandler` functional interface (`void handle(DataAddon, String source, NexusJsonDataContainer)`). Each request type is now handled by a dedicated, registered handler object instead of a single overloaded method body.
* Added the `registerHandler(RequestType, RequestHandler)` method to `DataAddon`. Subclasses can override or add handlers for specific request types at construction time.
* `DataAddon` now calls `registerDefaultHandlers()` in its constructor, pre-registering built-in handler classes for `GET_DATA`, `SET_DATA`, `REMOVE_DATA`, `INCREMENT_DATA`, `RANKING`, and `RANK_FINDER`.
* Added the `dispatch(String source, RequestType, NexusJsonDataContainer)` final method. `NexusReceiver` now calls `addon.dispatch(...)` after `addon.handleRequest(...)` returns `true`.
* Extracted request logic into dedicated handler classes under `protocol/handlers/`: `GetDataHandler`, `SetDataHandler`, `RemoveDataHandler`, `IncrementDataHandler`, `RankingHandler`, `RankFinderHandler`.
* Added `supportedRequestTypes()` on `DataAddon` returning the unmodifiable set of registered handler keys.
**Migration notes:**
`handleRequest()` continues to function as a **gate**: return `true` to allow dispatch, `false` to stop processing. The actual data handling now happens inside the registered `RequestHandler`. Override `registerDefaultHandlers()` or call `registerHandler(...)` in your subclass constructor to customise behaviour for a specific request type.
## v1.6.1 — Per-Addon Validation Chains (Sep 5, 2026)
This release gives each `DataAddon` its own additional validation chain, allowing addons to enforce custom message rules before any handler runs.
**What changed:**
* Added `additionalValidators()` to `DataAddon`. Override this method to return a list of `MessageValidator` instances specific to your addon. The default implementation returns an empty list.
* Added `getAdditionalValidationChain()` on `DataAddon`. Returns a lazily-initialized, immutable `MessageValidationChain` built from the validators returned by `additionalValidators()`. The chain is initialized once via double-checked locking.
* `NexusReceiver` now calls `addon.getAdditionalValidationChain().runAll(requestData)` immediately before `addon.handleRequest(...)`. A rejection from any validator in the chain stops processing for that message.
**How to add per-addon validation:**
```java theme={null}
@Override
protected List additionalValidators() {
return List.of(
message -> message.containsKey("playerUuid")
? ValidationResult.ok()
: ValidationResult.reject("playerUuid field is required")
);
}
```
## v1.6.0 — Security and Dependency Upgrades (Sep 4, 2026)
This release addresses high and critical CVEs and aligns the project with current Spring Security standards.
**Vulnerability mitigations:**
* Resolved Spring Security authorization bypass CVEs.
* Applied Tomcat path traversal patches.
* Addressed Jackson DoS and unsafe deserialization vulnerabilities.
**Dependency upgrades:**
| Dependency | Previous | New |
| ---------------- | -------- | ---------- |
| Spring Boot | 3.x | **4.1.1** |
| Jackson Databind | previous | **2.22.2** |
| MongoDB Driver | previous | **5.6.1** |
**Security architecture:**
* Refactored `SecurityConfig` to fully conform to modern Spring Security 6 standards.
* Updated `DaoAuthenticationProvider` wiring and exposed `AuthenticationManager` as a proper Spring bean.
Spring Boot 4.x is a major version upgrade. If you extend or customize `SecurityConfig` or any Spring MVC configuration, review the [Spring Boot 4.0 migration guide](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide) before upgrading. DataAddon subclasses are not affected.
## v1.5.5 — Security and Compatibility (Sep 4, 2026)
This release improves the determinism and security of the core messaging pipeline and is recommended for all users relying on Nexus Core's security infrastructure.
**Security improvements:**
* Added **nonce and timestamp** validation for improved replay attack protection across the message pipeline.
* Updated the encryption pipeline to use an **ordered algorithm flow**, ensuring deterministic processing of security operations.
* Introduced **chained key rotation**: a more structured and secure mechanism for transitioning signing keys without downtime.
* Improved consistency and determinism across all security-related operations.
**Compatibility and core improvements:**
* Migrated relevant `Map` implementations to **`TreeMap`** where deterministic field ordering is required (affects HMAC signature computation over packet contents).
* Improved data consistency between Nexus Core components.
* Refactored several core operations for better compatibility and reliability.
* Improved interoperability with existing Nexus integrations.
Upgrading to v1.5.5 is recommended for all deployments that rely on Nexus Core's security and messaging infrastructure. No public API changes; existing DataAddon subclasses require no modifications.
## v1.5.1 — Security Maintenance Release (Sep 3, 2026)
This release extends message authentication to the outbound direction, making signing fully symmetric.
**Security improvements:**
* **Outbound HMAC-SHA256 signing**: Nexus Core now signs every outgoing message using the `MessageAuth` system and `NEXUS_SIGNING_KEY`. Responses include `timestamp`, `nonce`, and `sig` fields.
* Signing applied to all `DataAddon` publish operations.
* Signing applied to `RedisDataContainer` heartbeat messages.
* Added warnings at startup when `NEXUS_SIGNING_KEY` is not configured.
* Message signing is fully symmetric with the existing `NexusReceiver` inbound validation system.
**Improvements:**
* Improved consistency between incoming and outgoing Redis message authentication.
* Strengthened protection against forged Redis messages and message replay attacks in both directions.
* Maintained backward compatibility: clients that do not yet verify outbound signatures continue to work.
For full protection in both directions, ensure `NEXUS_SIGNING_KEY` is set on both Nexus Core and all connected Spigot server components.
## v1.5 — Web Panel Release (Sep 2, 2026)
* **Added Web Panel**: Spring Boot-based management interface replacing the legacy Swing App Dashboard.
* **Removed legacy App Dashboard**: The Swing UI is no longer included.
* Added various stability, performance, and maintainability improvements across the project.
* This release focuses on providing a more flexible and modern management experience.
## v1.4.2 — Nexus Engine Stability (Jun 3)
* Made the `NexusApplication` singleton instance `volatile` to prevent stale references in concurrent environments.
* Wrapped `URLClassLoader` with `try-with-resources` to release file handles immediately after JAR loading.
* Resolved a parallel MongoDB connection race condition by adding a 10-second startup delay to the scheduled task.
* `getInfluxDBManager()` now returns `Optional`, enforcing explicit null handling.
* **Critical bug fix**: Fixed a telemetry bug in `handleIncrementData` where the old JSON payload was pushed instead of the updated one.
* Improved performance by caching `getApplication()` and `getRedisManager()` calls in local variables.
* Added early input validation before Redis tasks are started.
* Modernized `Optional` handling via `.ifPresent(...)` and pruned unused imports.
## v1.4.1 — MongoDB Reliability (May 23)
* Added connection timeout handling for the MongoDB client.
* Implemented periodic MongoDB health checks through a watchdog system.
* Added automatic detection of connection failure states.
* Integrated Redis-based scheduled task execution for system monitoring.
* Added fail-safe shutdown mechanism for critical database failures.
* Added Swing-based user notifications for critical runtime errors.
* **Behavior change:** The application now shuts down gracefully if MongoDB becomes unavailable at runtime.
## v1.4.0 — Zero-Touch Startup and Ranking Protocols (Apr 29)
* **Persistent configuration**: Redis and MongoDB credentials are stored in a config file and loaded automatically on subsequent launches.
* **Global Ranking Protocol**: Asynchronous Top-N leaderboard retrieval with dynamic ASC/DESC sorting (`RANKING` request type).
* **Rank Finder Protocol**: Calculates a key's position in a global ranking using optimized MongoDB queries (`RANK_FINDER` request type).
* Added `.remove(String key)` to `NexusJsonDataContainer` for removing fields before serialization.
* Resolved Jackson compatibility issues by migrating to native Java structures.
* Improved `CompletableFuture` usage to prevent ranking queries from blocking the main communication thread.
## v1.3.0 — The Synchronization Update (Apr 27)
* Added real-time data flow and cross-instance communication protocols.
* **Dynamic cache TTL**: Each `DataAddon` now defines its own `getCacheTTL()` value.
* **L1/L2 auto-sync**: Redis Keyspace Notifications (`notify-keyspace-events Ex`) automatically clear the local RAM cache when a Redis key expires.
* **Sliding TTL**: Touch-to-renew logic keeps active data cached while inactive data is evicted after TTL.
* Improved inbound/outbound worker threads for non-blocking operation under heavy load.
* Cached reflection-based field and annotation scanning inside `DataAddon` to reduce serialization overhead.
* Enhanced `JedisPool` configuration for better stability in high-concurrency environments.
## v1.2.0 — DataAddon Performance Overhaul (Apr 26)
* **`INCREMENT_DATA` protocol**: Atomic numeric field increments (`int`/`long`/`double`) without a full `SET_DATA` round trip.
* `ObjectMapper` is now a shared static final constant across all `DataAddon` instances, reducing GC pressure.
* Field scanning (`getDeclaredFields()`) performed once and cached with double-checked locking.
* `modelInitComp()` no longer runs for models served from the L1 in-memory cache.
* **Bug fixes**: Eliminated silent data corruption in `modelInit()` under concurrent load; added per-key locking to prevent concurrent increment race conditions; fixed null-unboxing NPE in `handleRemove()` using `Boolean.TRUE.equals()`.
* Migrated all logging to `java.util.logging` with structured `[DataAddon/]` prefixes.
## v1.1.0 — Cache Layer Overhaul (Apr 25)
* Complete architectural redesign of `RedisDataContainer` data synchronization.
* **Redis-master cache hierarchy**: Strict priority order `Redis → L1 Cache → MongoDB`. Redis is the single source of truth.
* Keys evicted or expired from Redis are automatically restored from L1, marked dirty, and re-persisted to MongoDB.
* Reconciliation task processes entries in batches of 50 (was: all at once) to prevent MongoDB load spikes.
* Added O(1) reverse index (`id → key`) for `getDataModelFromId()` replacing O(n) linear scan.
* **Bug fixes**: Data loss on flush failure; TOCTOU race in `removeModel()`; deadlock during reconciliation; `addModelFix()` leaving Redis empty.
## v1.0.0 — First Stable Release (Apr 24)
* Core orchestration layer implemented with `GET_DATA`, `SET_DATA`, `REMOVE_DATA`, `UPDATE_DATA`, and the `DataAddon` plugin system.
* First production-ready stable build.
## Related topics
- [Installing Nexus Core](/installation.md)
- [Configuring Nexus Core](/configuration.md)
- [Request Types in Nexus Core](/concepts/request-types.md)
- [System Architecture of Nexus Core](/concepts/architecture.md)
- [Get Started with Nexus Core](/quickstart.md)