Request Lifecycle in Nexus Core

Every packet that enters Nexus Core travels through a deterministic sequence of steps before a response is sent. Understanding this lifecycle helps you reason about where failures occur, how caching decisions are made, and where your handleRequest() code fits in the flow. As of v1.6.4, inbound delivery is guaranteed by Redis Streams and all database calls are protected by circuit breakers and retry.

Lifecycle Steps

Incoming Redis Streams message received

Nexus Core reads the next available JSON message from the Redis Stream using a consumer group (XREADGROUP). The message is persisted in the stream until Nexus Core explicitly acknowledges it with XACK after successful processing, guaranteeing at-least-once delivery.

Security chain validation

The packet passes through the three-stage security chain:

HMAC-SHA256 signature verification
Timestamp window check (5-minute tolerance)
Nonce replay detection

If any stage fails, the packet is logged and dropped silently. No response is sent.

JSON parsed and protocol extracted

The raw JSON string is deserialized and the protocol field is extracted to identify the target DataAddon.

AddonRegistry lookup

Nexus Core queries the AddonRegistry for an addon registered under the given protocol ID. If no match is found, a WARN is logged and the packet is dropped.

handleRequest() called

The matching addon’s handleRequest() method is called synchronously with the source server ID, request type, and payload. If it returns false, an empty response is published to the source and processing stops.

Route by RequestType

The request type determines the subsequent path through the cache and persistence layers.

Cache and persistence operations

Depending on the request type:

GET_DATA: Check Redis L2 cache. On a hit, return the cached document. On a miss, query MongoDB, write the result to both cache layers, then return it.
SET_DATA / UPDATE_DATA / INCREMENT_DATA: Write to MongoDB, then update Redis L2 and L1 caches.
REMOVE_DATA: Delete from MongoDB, then invalidate both cache layers.
LOAD_CACHE: Fetch from MongoDB and warm both cache layers. No response payload.
RANKING / RANK_FINDER: Execute a sorted MongoDB query directly. Cache is bypassed.
BROADCAST: Publish the payload to the target server’s Redis channel. No MongoDB operation.

Circuit breaker and retry protection

All MongoDB and Redis cache calls in the previous step are wrapped in Resilience4j Circuit Breakers. If a backend service exceeds its error threshold, the circuit trips to OPEN and calls fail fast rather than queuing indefinitely. Transient failures are retried automatically using an exponential backoff policy with jitter, which prevents retry storms during recovery.

Acknowledge and publish response

After a successful operation, Nexus Core sends XACK to remove the message from the pending-entries list in the stream. The result is then serialized to JSON, signed with MessageAuth (if NEXUS_SIGNING_KEY is configured), and published to the originating server’s response channel. The response includes the protocol ID, the "nexus" source, and the response data.

Full Flow Diagram

Spigot Server (XADD to Redis Stream)
        │
        ▼
┌─────────────────────┐
│  Redis Stream        │  Consumer group XREADGROUP
│  (at-least-once)    │──► Nexus Core worker (virtual thread)
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│  Security Chain      │      ┌──────────────┐
│  sig → timestamp →  │─────►│  Failed?     │──► Log and drop
│  nonce              │      └──────────────┘
└────────┬────────────┘
         │ valid
         ▼
┌───────────────────┐
│  Parse JSON       │
│  Extract protocol │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  AddonRegistry    │      ┌─────────────┐
│  lookup(protocol) │─────►│ Not found?  │──► Log WARN and drop
└────────┬──────────┘      └─────────────┘
         │
         ▼
┌───────────────────┐
│  handleRequest()  │      ┌─────────────┐
│  (your code)      │─────►│  false?     │──► Send empty response
└────────┬──────────┘      └─────────────┘
         │ true
         ▼
┌───────────────────┐
│  Route by         │
│  RequestType      │
└────────┬──────────┘
         │
    ┌────┴───────────────────┐
    ▼                        ▼
 GET_DATA              SET_DATA / UPDATE /
    │                  INCREMENT / REMOVE
    ▼                        │
 Check Redis                 ▼
 cache            ┌─────────────────────┐
    │             │  Circuit Breaker     │
    ├── HIT ──►   │  + Retry (exp backoff│
    │  return     │  + jitter)           │
    │  cache      └────────┬────────────┘
    └── MISS ──►           │
    ┌──────────┐    Write MongoDB +
    │ Circuit  │    update/invalidate
    │ Breaker  │           │
    │ + Retry  │           ▼
    └────┬─────┘      Serialize response
         │                 │
         ▼                 │
    Query MongoDB +        │
    fill cache             │
         │                 │
         └────────┬────────┘
                  │
                  ▼
            XACK (stream)
                  │
                  ▼
         Sign response (MessageAuth)
                  │
                  ▼
         Publish to source channel

Security — the three-stage validation chain in detail
Request Types — all nine request types and their cache behaviors
DataAddon API — where handleRequest() fits

Get Started

Core Concepts

Building Addons

Reference

Request Lifecycle in Nexus Core

Lifecycle Steps

Full Flow Diagram

​Lifecycle Steps

​Full Flow Diagram

​Related Topics

Lifecycle Steps

Full Flow Diagram

Related Topics