Gregius Data – Retry Queue

Overview

The Retry Queue subsystem recovers automatically from transient database sync failures. When a sync operation fails, the error is classified and, if recoverable, queued for automatic retry with exponential backoff. Items that exhaust all retry attempts move to a dead letter queue for operator review and manual recovery.

Prerequisites

• WordPress 6.9+ with Gregius Data plugin installed and activated
• Sync subsystem configured with at least one active connection
• WP-Cron enabled for automatic background retry processing

---

How It Works

Error classification

When a database sync operation fails, the error message is evaluated against known error patterns. Transient errors (connection timeouts, deadlocks) are queued for retry. Permanent errors (schema mismatches, permission denied) are logged but not queued. Unrecognized errors default to retry-safe, preventing silent data loss.

Retry lifecycle

Queued items are processed in the background via WP-Cron every 60 seconds. Items whose scheduled retry time has not yet elapsed are skipped. On each retry attempt, the operation is reconstructed from stored context data and re-executed. A successful retry removes the item from the queue and updates sync metadata.

Dead letter queue

Items that fail three consecutive retries are promoted to the dead letter queue with a timestamp. The dead letter queue is capped at 100 items using a rolling window – oldest items are automatically discarded when the limit is exceeded. Operators can manually retry individual dead letter items or clear the entire queue.

---

Retry Schedule

Attempt	Delay	Cumulative Window
1st	5 seconds	5 seconds
2nd	30 seconds	35 seconds
3rd	300 seconds (5 minutes)	5 minutes 35 seconds
Exhausted	—	Moved to dead letter

After the third failed attempt, the item is moved to the dead letter queue. The total window from first failure to dead letter is approximately 5 minutes 35 seconds, covering brief network hiccups, connection pool resets, and server restarts.

---

Queue Dashboard

Queue status is available via the plugin’s React dashboard Retry Queue card, which auto-refreshes every 30 seconds. Three REST endpoints provide programmatic access:

Endpoint	Purpose	Permission
GET /sync/retry-queue	View pending and dead letter items	Admin
POST /sync/retry-queue/retry/{index}	Move a dead letter item back to the retry queue	Admin
DELETE /sync/retry-queue/clear	Clear all dead letter items	Admin

On plugin deactivation, the WP-Cron event is unscheduled but queue data is preserved for recovery on reactivation. On plugin uninstall, all queue data is removed.

---

Error Classification Reference

Transient errors are automatically queued for retry:

Category	Example Patterns
Connection failures	connection refused, server closed the connection, lost connection
Timeouts	connection timed out, statement timeout, query execution timeout
Resource contention	deadlock detected, too many connections, lock wait timeout
Temporary failures	server has gone away, could not connect, temporary failure

Permanent errors are logged but not queued:

Category	Example Patterns
Schema errors	column does not exist, relation does not exist, table does not exist
Constraint violations	unique constraint, foreign key constraint, duplicate key
Data errors	invalid input syntax, value too long, out of range
Permission errors	permission denied, authentication failed, insufficient privilege

Unknown errors (no pattern match) default to retry-safe to prevent silent data loss.

---