Update docs with max retry option

Author: 1v4n4

docs/diagram.md

@@ -3,45 +3,63 @@
 
 
 flowchart TD
-A[Service start] --> B[Connect to RabbitMQ]
+
+A[Service start] --> A1[Validate options<br/>positive integers only]
+A1 --> B[Connect to RabbitMQ]
+
 B --> C[Register signal & process handlers]
-C --> D[Create consumer<br/>noAck=false<br/>requeue=false<br/>prefetch=2*concurrency]
-D --> E[Log initial queue depth]
+
+C --> D[Create consumer<br/>noAck=false<br/>requeue=false<br/>prefetch=2*concurrency<br/>consumerTag=hostname.tag]
+
+D --> E[Log queue depth if available]
 
 E --> F[Message received]
 
-F --> G{Valid JSON?}
+%% retry limit guard
+F --> R0{maxRetries configured?}
+R0 -- Yes --> R1[Read x-death count]
+R1 --> R2{Retries exceeded?}
+R2 -- Yes --> R3[ACK and DROP]
+R2 -- No --> G
+R0 -- No --> G
+
+%% json parsing
+G{Valid JSON?}
 G -- No --> G1[NACK]
 G1 --> G2{Redelivered?}
 G2 -- No --> G3[REQUEUE]
 G2 -- Yes --> G4[DLQ / DROP]
 
+%% schema validation
 G -- Yes --> H{Valid schema?}
 H -- No --> H1[NACK]
 H1 --> H2{Redelivered?}
 H2 -- No --> H3[REQUEUE]
 H2 -- Yes --> H4[DLQ / DROP]
 
+%% normalization
 H -- Yes --> I{schema == action v2?}
-I -- Yes --> J[Normalize IDs<br/>Decrypt PII if enabled]
+I -- Yes --> J[Normalize IDs<br/>Decrypt PII if keystore]
 I -- No --> K[Skip normalization]
 
-L[syncer call]
-J --> L
+%% business processing
+J --> L[syncer call]
 K --> L
 
 L --> M{syncer result}
+
 M -- true --> N[ACK]
+
 M -- false --> O[NACK]
 O --> O1{Redelivered?}
 O1 -- No --> O2[REQUEUE]
 O1 -- Yes --> O3[DLQ / DROP]
 
 M -- throws / non-boolean --> P[Fatal error]
 P --> Q[Log error]
-Q --> R[Process exit]
+Q --> S[Graceful shutdown]
 
-R --> S[Shutdown handler]
+%% shutdown
 S --> T[Close consumer]
 T --> U[Close connection]
 U --> V[Exit]

docs/workflow.md

@@ -3,88 +3,144 @@
 ## 1. Connection & Startup
 
 1. The service connects to RabbitMQ using `connect(queueUrl)`
-2. Signal and process handlers are registered:
 
+2. Signal and process handlers are registered:
    - `SIGINT`, `SIGTERM` → graceful shutdown
    - `uncaughtException`, `unhandledRejection` → log and exit
 
 3. A consumer is created with:
-
    - `noAck: false`
    - `requeue: false`
    - bounded `concurrency`
    - `prefetch = 2 × concurrency`
+   - consumer tag = `<hostname>.<tag || package name>`
 
-On startup, the consumer logs the **current queue depth**.
+4. Consumer options are validated:
+   - `concurrency`, `prefetch`, `maxRetries` must be **positive integers (> 0)**
+   - invalid values throw at startup
+
+On startup, the consumer logs the **queue depth if available** from consumer stats.
 
 ---
 
 ## 2. Message Intake
 
 For each message received:
 
-1. The message body is parsed as JSON
+### 2.1 Retry limit guard (`x-death` header)
+
+If `maxRetries` is configured:
+
+- retry count is read from `message.headers['x-death'][0].count`
+- if retry count **exceeds maxRetries**:
+
+```
+ACK and drop (message considered permanently failed)
+```
+
+No further processing occurs.
+
+---
+
+### 2.2 JSON parsing
 
-   - ❌ Invalid JSON → **NACK**
-   - First failure → **requeue**
-   - Redelivered → **dead-letter**
+The message body is parsed as JSON.
 
-2. The message schema is validated
-   Accepted schemas:
+- ❌ Invalid JSON → **NACK**
+- First failure → **requeue**
+- Redelivered → **dead-letter**
 
-   - `proca:action:2`
+---
 
-   - `proca:event:2`
+### 2.3 Schema validation
 
-   - ❌ Unknown schema → **NACK**
+Accepted schemas:
 
-   - First failure → **requeue**
+- `proca:action:2`
+- `proca:event:2`
 
-   - Redelivered → **dead-letter**
+If schema is unknown:
+
+- ❌ Unknown schema → **NACK**
+- First failure → **requeue**
+- Redelivered → **dead-letter**
 
 ---
 
 ## 3. Message Normalization (Action v2 only)
 
 If `schema === proca:action:2`:
 
-- IDs are copied into their nested objects for convenience:
+### ID normalization
 
-  - `campaign.id`
-  - `action.id`
-  - `org.id`
-  - `actionPage.id`
+IDs are copied into nested objects for convenience:
 
-- If a keystore is configured:
+- `campaign.id`
+- `action.id`
+- `org.id`
+- `actionPage.id`
 
-  - `personalInfo` is decrypted
-  - decrypted fields are merged into `contact`
+---
+
+### Optional PII decryption
+
+If:
+
+- `personalInfo` exists
+- `keyStore` is configured
+
+Then:
+
+- `personalInfo` is decrypted
+- decrypted fields are merged into `contact`
+- decrypted values overwrite existing fields
 
 No side effects occur at this stage.
 
 ---
 
 ## 4. Business Processing (`syncer`)
 
-The normalized message is passed to the user-provided `syncer(msg)`.
+The normalized message is passed to the user-provided:
+
+```
+await syncer(msg)
+```
 
 ### Expected contract
 
-The `syncer` **must** return a boolean:
+The `syncer` **must return a boolean**.
 
-| syncer result                 | Consumer behavior                       |
-| ----------------------------- | --------------------------------------- |
-| `true`                        | **ACK** (message removed from queue)    |
-| `false`                       | **NACK** (retry once, then dead-letter) |
-| throws or returns non-boolean | **Fatal error → process exit**          |
+| syncer result | Consumer behavior                     |
+| ------------- | ------------------------------------- |
+| `true`        | **ACK** (message removed)             |
+| `false`       | **NACK → requeue once → dead-letter** |
+| throws        | **Fatal error → process exit**        |
+| non-boolean   | **Fatal error → process exit**        |
 
 ---
 
 ## 5. Retry & Dead-Letter Strategy
 
-- Messages are retried **at most once**
-- Retry detection uses `message.redelivered`
-- Second failure → **DROP** (dead-letter exchange)
+Two independent retry controls exist.
+
+### 5.1 Consumer redelivery guard
+
+- First failure → requeue
+- If message is redelivered again → **DROP → dead-letter**
+
+This prevents infinite retry loops.
+
+---
+
+### 5.2 Retry limit (`maxRetries`)
+
+If configured:
+
+- retry count is read from RabbitMQ `x-death` header
+- when exceeded → **ACK and drop**
+
+This is used when queues already implement retry pipelines via DLX.
 
 ---
 
@@ -97,19 +153,25 @@ If the `syncer`:
 
 Then:
 
-1. The error is logged
-2. The process exits immediately
+1. Error is logged
+2. Consumer closes
+3. Connection closes
+4. Process exits immediately
+
+This is treated as a **permanent system failure**, not a message failure.
 
 ---
 
 ## 7. Shutdown Behavior
 
 On shutdown (`SIGINT`, `SIGTERM`, fatal error):
 
-1. The consumer is closed
-2. The RabbitMQ connection is closed
+1. Consumer is closed
+2. RabbitMQ connection is closed
 3. Final ACK/NACK counters are logged
-4. The process exits
+4. Process exits
+
+Shutdown is graceful unless the process crashes unexpectedly.
 
 ---
 
@@ -121,10 +183,16 @@ The following counters are tracked in memory:
 - `count.ack` – successfully processed messages
 - `count.nack` – rejected / retried messages
 
+Counters reset on process restart.
+
 ---
 
 ## Summary (TL;DR)
 
-- **Good messages** → ACK
-- **Recoverable failures** → retry once → DLQ
-- **Bad code or corrupted data** → crash fast
+- Valid message + handler success → ACK
+- Recoverable failure → requeue once → DLQ
+- Retry limit exceeded → ACK and drop
+- Invalid message → requeue once → DLQ
+- Handler crash or contract violation → process exits immediately
+
+---

src/queue.ts

@@ -139,8 +139,6 @@ export const syncQueue = async (
       if (maxRetries) {
         const deaths = message.headers?.['x-death']?.[0]?.count ?? 0;
 
-        console.log('x-death header:', deaths, 'headers', message.headers);
-
         if (deaths > maxRetries) {
           console.error(
             `retry limit exceeded (${deaths} > ${maxRetries}) — ACK and drop`