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

# 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="JSON parsed and protocol extracted">
    The raw JSON string is deserialized and the `protocol` field is extracted to identify the target DataAddon.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Route by RequestType">
    The request type determines the subsequent path through the cache and persistence layers.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Full Flow Diagram

```text theme={null}
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](/concepts/security) — the three-stage validation chain in detail
* [Request Types](/concepts/request-types) — all nine request types and their cache behaviors
* [DataAddon API](/addons/data-addon-api) — where `handleRequest()` fits


## Related topics

- [Request Types in Nexus Core](/concepts/request-types.md)
- [Packet Security and Replay Protection in Nexus Core](/concepts/security.md)
- [DataAddon Overview: Defining Data Schemas in Nexus Core](/addons/overview.md)
- [Protocol and Packet Structure Reference](/reference/packet-structure.md)
- [Nexus Core Changelog](/reference/changelog.md)