# Task Queue (/experiments/task-queue)



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 [#api-endpoints]

### POST /enqueue [#post-enqueue]

Enqueues a message for async processing.

**`message`** `string` (required)

Task payload (max 500 characters).

#### Example Request [#example-request]

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

#### Example Response [#example-response]

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

#### Error Responses [#error-responses]

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

### GET /stats [#get-stats]

Returns enqueue and process counts.

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

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

<Callout>
  `processed` may lag behind `enqueued` until the queue consumer runs. This is expected async behavior.
</Callout>

## Use Cases [#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 [#deployment]

<Steps>
  <Step>
    ### Click the deploy button [#click-the-deploy-button]

    [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/shrinathsnayak/cloudflare-experiments/tree/main/apps/experiments/task-queue)
  </Step>

  <Step>
    ### Create queue and KV [#create-queue-and-kv]

    Create the `task-queue` queue and KV namespace in your Cloudflare dashboard. Update `wrangler.json` bindings.
  </Step>

  <Step>
    ### Enqueue and check stats [#enqueue-and-check-stats]

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

## Local Development [#local-development]

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

## Configuration [#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 [#cloudflare-features-used]

* [Queues](https://developers.cloudflare.com/queues/) - async message processing
* [Workers KV](https://developers.cloudflare.com/kv/) - enqueue/process statistics