Request Lifecycle in Nexus Core

Step-by-step walkthrough of how Nexus Core processes an incoming Redis Streams packet from security validation through circuit breaker protection to response publication.

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

1. 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.

2. Security chain validation

   The packet passes through the three-stage security chain:

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

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

3. JSON parsed and protocol extracted

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

4. 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.

5. 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.

6. Route by RequestType

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

7. 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.
8. 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.

9. 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

Related Topics

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