codeQ | The Queue for Event-Driven Agents

System Architecture

CORE FEATURES

Disk Persistence

Backed by KVRocks (RocksDB on SSD). Keeps list operations O(1) while storing massive datasets on disk, not RAM.

Strict Leases

Workers claim exclusive leases (TTL). Crashed workers automatically release tasks back to the pool, guaranteeing at-least-once delivery.

Priority Tiers

Supports 10 priority levels (0-9). High-priority tasks jump the queue, ensuring critical agent operations are processed first.

Backoff & DLQ

Configurable exponential backoff with jitter. Tasks exceeding `maxAttempts` move to a Dead Letter Queue (DLQ) for inspection.

Reactive Signals

Pull-based consumption with advisory Webhook signals. Wakes up idle workers immediately when new priority tasks arrive.

Result Storage

Task results are persisted and queryable. Supports result callbacks (Webhooks) to notify upstream agents upon completion.

Get started

# 1. Install codeQ CLI via npm
$ npm install -g @codeq/cli

# 2. Verify installation
$ codeq --version
codeq version 1.2.4

# 3. Configure connection (optional)
$ codeq config set endpoint http://localhost:8080

# 1. Start the codeQ server
$ helm install codeq ./helm/codeq --set kvrocks.enabled=true

# 2. Enqueue a high-priority task for video rendering
$ codeq task create \
    --event render_video \
    --priority 9 \
    --payload '{"jobId": 500, "codec": "h264"}'

# 3. Inspect queue depth
$ codeq queue inspect render_video
> PENDING: 1 | IN_PROGRESS: 0 | DELAYED: 0

# 4. Start a CLI worker pool (for testing)
$ codeq worker start --events render_video --concurrency 5

✔ Worker connected. Processing tasks..._

package main

func workerLoop() {
    client := codeq.NewClient("http://codeq-api:8080")
    
    for {
        // 1. Claim a task with a 60s lease
        task, err := client.Claim([]string{"render_video"}, 60)
        
        if task == nil {
            time.Sleep(5 * time.Second) // Backoff
            continue
        }

        // 2. Process work (Execute Agent logic)
        result, err := processVideo(task.Payload)

        // 3. Submit Result (Atomic Completion)
        if err != nil {
            client.Nack(task.ID, err.Error()) // Trigger Retry
        } else {
            client.Complete(task.ID, result)  // Clear Lease
        }
    }
}

Benchmark

Why store queue data in RAM? codeQ leverages SSDs via KVRocks to provide massive capacity at a fraction of the cost of Redis.

Storage Cost vs Capacity

INFRASTRUCTURE

codeQ (SSD) scales linearly in cost, whereas standard Redis (RAM) hits a vertical cost wall as queue depth increases.

Latency vs Queue Depth

STABILITY

O(1)

Enqueue/Dequeue Time

~1ms

Added Latency (vs RAM)

Technical FAQ

Why use KVRocks instead of Redis?

Redis stores everything in RAM, which is expensive for large queues or historical result data. KVRocks implements the Redis protocol but stores data on SSD (via RocksDB). This allows terabytes of queue data at a fraction of the cost, with only a negligible (~1ms) latency penalty.

How does the Lease system work?

Unlike "fire-and-forget" systems, codeQ requires workers to Claim a task. This grants an exclusive lease (e.g., 60s). If the worker crashes or fails to heartbeat, codeQ automatically returns the task to the pending queue when the lease expires, guaranteeing reliability.

Is delivery strictly FIFO?

codeQ favors availability and throughput over global ordering. Tasks are FIFO within a specific shard and priority tier (0-9), but strict global ordering is not guaranteed across shards in distributed setups.