Task Queue

Reference implementation for Queues - enqueue tasks over HTTP and process them asynchronously

A minimal reference for Queues: HTTP requests enqueue messages via a producer binding; a queue() consumer processes them in the background. KV tracks enqueue and process counts.

API Endpoints

POST /enqueue

Enqueues a message for async processing.

message string (required)

Task payload (max 500 characters).

Example Request

curl -X POST "https://your-worker.workers.dev/enqueue" \
  -H "Content-Type: application/json" \
  -d '{"message": "sync analytics"}'

Example Response

{
  "queued": true,
  "message": "sync analytics",
  "enqueuedAt": "2025-06-20T12:00:00.000Z"
}

Error Responses

{
  "error": "Missing or invalid message (required string, max 500 chars)",
  "code": "INVALID_MESSAGE"
}

GET /stats

Returns enqueue and process counts.

curl "https://your-worker.workers.dev/stats"

{
  "enqueued": 10,
  "processed": 8
}

processed may lag behind enqueued until the queue consumer runs. This is expected async behavior.

Use Cases

Learn producer (TASK_QUEUE.send) and consumer (queue()) setup
Decouple HTTP responses from slow background work
Webhook delivery, email sending, or data pipeline triggers
Building retryable async workflows on Cloudflare

Deployment

Click the deploy button

Create queue and KV

Create the task-queue queue and KV namespace in your Cloudflare dashboard. Update wrangler.json bindings.

Enqueue and check stats

curl -X POST "https://your-worker.workers.dev/enqueue" \
  -H "Content-Type: application/json" \
  -d '{"message": "hello"}'
curl "https://your-worker.workers.dev/stats"

Local Development

cd apps/experiments/task-queue
npm install
npm run dev

Configuration

wrangler.json declares:

Queue producer TASK_QUEUE → queue task-queue
Queue consumer on task-queue (batch size 10, 5s timeout)
KV binding STATS for counters

Cloudflare Features Used

Queues - async message processing
Workers KV - enqueue/process statistics

Task Queue

On this page