agmission/Development/server/docs/DLQ_API_REFERENCE.md

# DLQ API Reference

**Navigation:** [📖 Index](DLQ_INDEX.md) | [🚀 Quick Start](DLQ_QUICKSTART.md) | [📚 API Reference](DLQ_API_REFERENCE.md) | [🔧 Operations](DLQ_OPERATIONS.md) | [🏗️ System Guide](DLQ_SYSTEM_GUIDE.md)

---

Global Dead Letter Queue (DLQ) API for all queue types.

## Base URL

```
/api/dlq/:queueName/*
```

**Supported Queues:**
- `partner_tasks` (or `dev_partner_tasks` in development)
- `jobs` (or `dev_jobs` in development)
- Any future queue types

---

## Endpoints

### 1. Get DLQ Messages

**Endpoint:** `GET /api/dlq/:queueName/messages`

Peek at messages in the DLQ without consuming them.

**Parameters:**
- `queueName` (path) - Queue name (e.g., 'partner_tasks', 'dev_jobs')

**Query Parameters:**
- `limit` (optional) - Maximum messages to retrieve (default: 50)

**Example:**
```bash
curl -X GET "http://localhost:4100/api/dlq/partner_tasks/messages?limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "messages": [
    {
      "taskInfo": { "logFileName": "example.log", "partnerId": "..." },
      "errorMessage": "Connection timeout",
      "retryCount": 2,
      "enqueuedAt": "2025-12-19T10:30:00Z",
      "headers": { "x-retry-count": "2" }
    }
  ]
}
```

---

### 2. Get DLQ Statistics

**Endpoint:** `GET /api/dlq/:queueName/stats`

Get comprehensive statistics about a specific DLQ.

**Parameters:**
- `queueName` (path) - Queue name

**Example:**
```bash
curl -X GET http://localhost:4100/api/dlq/partner_tasks/stats \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "dlq": {
    "messageCount": 5,
    "consumerCount": 0,
    "queueName": "dev_partner_tasks_failed"
  }
}
```

---

### 3. Retry All DLQ Messages

**Endpoint:** `POST /api/dlq/:queueName/retryAll`

Retry all messages in the DLQ (or up to maxMessages).

**Parameters:**
- `queueName` (path) - Queue name

**Body:**
```json
{
  "maxMessages": 100
}
```

**Example:**
```bash
curl -X POST http://localhost:4100/api/dlq/partner_tasks/retryAll \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"maxMessages": 50}'
```

**Response:**
```json
{
  "success": true,
  "retriedCount": 50,
  "message": "Retried 50 messages from DLQ"
}
```

---

### 4. Retry by Position

**Endpoint:** `POST /api/dlq/:queueName/retryByPosition`

Retry messages by 0-based position range.

**Parameters:**
- `queueName` (path) - Queue name

**Body:**
```json
{
  "startPosition": 0,
  "endPosition": 10
}
```

**Example:**
```bash
curl -X POST http://localhost:4100/api/dlq/partner_tasks/retryByPosition \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startPosition": 0, "endPosition": 10}'
```

---

### 5. Retry by Header Match

**Endpoint:** `POST /api/dlq/:queueName/retryByHeader`

Retry messages matching specific header criteria.

**Parameters:**
- `queueName` (path) - Queue name

**Body:**
```json
{
  "headerKey": "x-retry-count",
  "headerValue": "1"
}
```

**Example:**
```bash
curl -X POST http://localhost:4100/api/dlq/partner_tasks/retryByHeader \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"headerKey": "x-retry-count", "headerValue": "1"}'
```

---

### 6. Purge DLQ

**Endpoint:** `DELETE /api/dlq/:queueName/purge`

⚠️ **DANGEROUS** - Permanently delete all messages in the DLQ.

**Parameters:**
- `queueName` (path) - Queue name

**Body:**
```json
{
  "confirm": true
}
```

**Example:**
```bash
curl -X DELETE http://localhost:4100/api/dlq/partner_tasks/purge \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'
```

---

## Multi-Queue Examples

### Partner Queue
```bash
POST /api/dlq/partner_tasks/retryAll
GET  /api/dlq/partner_tasks/messages
```

### Job Queue
```bash
POST /api/dlq/dev_jobs/retryAll
GET  /api/dlq/dev_jobs/messages
```

### Future Queues
```bash
POST /api/dlq/notifications/retryAll
POST /api/dlq/analytics/retryAll
```

---

## Authentication

All endpoints require admin authentication via Bearer token:

```
Authorization: Bearer YOUR_JWT_TOKEN
```

---

## Error Responses

All error responses follow the project's standard error format with an `error` object containing a `.tag` field:

**401 Unauthorized (AppAuthError):**
```json
{
  "error": {
    ".tag": "not_authorized"
  }
}
```

**409 Bad Request (AppParamError):**
```json
{
  "error": {
    ".tag": "invalid_param",
    "message": "queueName parameter is required"
  }
}
```

**500 Internal Server Error (AppError):**
```json
{
  "error": {
    ".tag": "unknown_app_error",
    "message": "Failed to connect to RabbitMQ"
  }
}
```

**Note:** The `message` field is only included in development mode. In production, only the `.tag` field is returned for security.

---

## Related Documentation

### 📚 DLQ Documentation

- **[📖 DLQ Index](DLQ_INDEX.md)** - Documentation overview
- **[🚀 Quick Start](DLQ_QUICKSTART.md)** - Get started in 5 minutes
- **[🔧 Operations Guide](DLQ_OPERATIONS.md)** - Advanced operations
- **[🏗️ System Guide](DLQ_SYSTEM_GUIDE.md)** - Architecture details

### 🔗 Additional Resources

- [Postman Collection](Partner_DLQ_API.postman_collection.json) - API testing
- [Global DLQ Refactoring](../GLOBAL_DLQ_REFACTORING_COMPLETE.md) - Architecture changes
- [Web Dashboard](../public/dlq-monitor.html) - Monitoring interface