Cloudflare Queues

Cloudflare Queues

Complete knowledge domain for Cloudflare Queues - flexible message queue for asynchronous processing and background tasks on Workers.

---

Auto-Trigger Keywords

Primary Keywords

• cloudflare queues
• queues workers
• message queue
• queue bindings
• async processing
• background jobs
• queue consumer
• queue producer
• workers queue
• message broker

Secondary Keywords

• batch processing
• send queue
• sendBatch
• queue handler
• message retry
• queue ack
• acknowledge message
• dead letter queue
• dlq
• queue delay
• delay message
• consumer concurrency
• queue backlog
• wrangler queues

Error-Based Keywords

• queue timeout
• batch retry
• message lost
• queue throughput exceeded
• consumer not scaling
• queue storage limit
• Too Many Requests queue
• message retention exceeded
• visibility timeout
• max retries reached
• queue delivery failed
• consumer error

Framework Integration Keywords

• hono queues
• queues hono
• cloudflare workers queues
• wrangler queue
• queue api workers

---

What This Skill Does

This skill provides complete Cloudflare Queues knowledge including:

• ✅ Queue Creation - Create, configure, and manage queues with wrangler
• ✅ Producer Patterns - send(), sendBatch() with delays
• ✅ Consumer Patterns - Basic, explicit ack, DLQ, retry strategies
• ✅ Pull-Based Consumers - Consume from non-Workers environments via HTTP polling
• ✅ HTTP Publishing - Publish messages from external systems via REST API
• ✅ R2 Event Integration - Trigger queue messages on R2 object events
• ✅ Batching Configuration - max_batch_size, max_batch_timeout
• ✅ Retry Strategies - Implicit, explicit, with exponential backoff
• ✅ Dead Letter Queues - Handle permanently failed messages
• ✅ Explicit Acknowledgement - ack(), retry(), ackAll(), retryAll()
• ✅ Message Delays - Delay delivery up to 12 hours
• ✅ Consumer Concurrency - Auto-scaling up to 250 concurrent invocations
• ✅ Error Handling - Timeouts, retries, rate limits
• ✅ Performance Optimization - Batching, concurrency, cost reduction

Agents & Commands

Autonomous Agents:

• queue-debugger - 9-phase diagnostic analysis for systematic troubleshooting
• queue-optimizer - Performance tuning and cost optimization recommendations

Interactive Commands:

• /queue-setup - Interactive wizard for complete queue setup
• /queue-troubleshoot - Quick diagnostic for common issues
• /queue-monitor - Real-time metrics and status display

---

Known Issues Prevented

Issue	Description	Prevention
Batch retry on single failure	One message fails → entire batch retried	Use explicit ack() for non-idempotent operations
Messages deleted without DLQ	After max_retries, messages permanently lost	Configure dead_letter_queue in consumer
Throughput exceeded	>5000 msg/s per queue causes errors	Document limit + implement retry logic
Message too large	>128 KB fails to send	Validate message size before sending
Ordering not guaranteed	Messages arrive out of order	Use timestamps, don't rely on delivery order
Consumer timeout	Default 30s CPU limit too low	Set limits.cpu_ms up to 300000 (5 min)
No explicit ack	DB writes/API calls repeated on retry	Always ack() after successful operations
Rate limit errors	API rate limits (1200 req/5min)	Implement exponential backoff

---

When to Use This Skill

✅ Use this skill when:

• Decoupling application components
• Processing tasks asynchronously
• Handling background jobs (emails, notifications, data processing)
• Buffering calls to external APIs
• Implementing task queues
• Managing workload spikes
• Rate limiting upstream services
• Building event-driven architectures
• Processing webhooks asynchronously
• Scheduling delayed tasks

❌ When NOT to use:

• You need real-time processing (<1 second latency)
• You need guaranteed FIFO ordering (use Durable Objects)
• You need strict message ordering
• Messages >128 KB (split them or use R2 references)
• You need synchronous responses
• You need transactional guarantees across operations

---

Quick Example

import { Hono } from 'hono';

type Bindings = {
  MY_QUEUE: Queue;
};

const app = new Hono<{ Bindings: Bindings }>();

// Producer: Send message to queue
app.post('/tasks', async (c) => {
  const task = await c.req.json();

  // Send single message
  await c.env.MY_QUEUE.send({
    type: 'process-order',
    orderId: task.orderId,
    userId: task.userId,
  });

  return c.json({ status: 'queued' });
});

// Producer: Send batch of messages
app.post('/tasks/batch', async (c) => {
  const tasks = await c.req.json();

  // Send up to 100 messages at once
  await c.env.MY_QUEUE.sendBatch(
    tasks.map((task) => ({
      body: {
        type: 'process-order',
        orderId: task.orderId,
      },
    }))
  );

  return c.json({ status: 'queued', count: tasks.length });
});

export default app;

// Consumer: Process messages from queue
export default {
  async queue(
    batch: MessageBatch,
    env: Env,
    ctx: ExecutionContext
  ): Promise<void> {
    // Process each message
    for (const message of batch.messages) {
      try {
        // Your processing logic
        await processOrder(message.body);

        // Explicitly acknowledge success
        message.ack();
      } catch (error) {
        console.error(`Failed to process message ${message.id}:`, error);

        // Retry with exponential backoff
        message.retry({
          delaySeconds: Math.min(60 * message.attempts, 3600),
        });
      }
    }
  },
};

---

Files Included

• SKILL.md - Complete Queues knowledge domain
• templates/wrangler-queues-config.jsonc - Producer + Consumer bindings
• templates/queues-producer.ts - Send messages (single + batch)
• templates/queues-consumer-basic.ts - Basic consumer (implicit ack)
• templates/queues-consumer-explicit-ack.ts - Explicit ack pattern
• templates/queues-dlq-pattern.ts - Dead letter queue setup
• templates/queues-retry-with-delay.ts - Retry with exponential backoff
• reference/wrangler-commands.md - Complete CLI reference
• reference/producer-api.md - send/sendBatch API details
• reference/consumer-api.md - queue handler + batch operations
• reference/best-practices.md - Patterns, concurrency, optimization

---

Dependencies

• cloudflare-worker-base - For Hono + Vite + Worker setup
• wrangler - For queue management CLI

---

Production Status

✅ Production Ready

This skill is based on:

• Official Cloudflare Queues documentation
• Cloudflare Workers SDK examples
• Production-tested patterns
• Latest package versions (verified 2025-10-21)

---

Related Skills

• cloudflare-worker-base - Base Worker setup with Hono
• cloudflare-d1 - Serverless SQLite database
• cloudflare-r2 - Object storage
• cloudflare-kv - Key-value storage
• cloudflare-workers-ai - AI inference on Workers

---

Last Updated: 2025-10-21 Status: Production Ready ✅ Maintainer: Claude Skills Maintainers | maintainers@example.com