# Queue Job Visualizer (/docs/experiments/queue-job-visualizer)



Enqueue simulated jobs over HTTP, process them asynchronously with a **Queues consumer**, and track status transitions in **KV** (`queued` → `processing` → `done` / `failed`). The consumer simulates \~35% failure rate and retries via `message.retry()`.

## Features [#features]

* **POST /jobs** - Enqueue a resize or fetch job
* **GET /jobs/:id** - Poll job status from KV
* **Simulated failures** - Consumer retries up to 3 attempts before marking failed
* **KV state machine** - Full transition history on each job record

## API Reference [#api-reference]

### POST /jobs [#post-jobs]

Enqueue a new job.

<TypeTable
  type="{
  type: {
    description: &#x22;Job type: `resize` or `fetch`.&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
  target: {
    description: &#x22;Job target string (e.g. URL or filename, max 500 chars).&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
}"
/>

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

```bash
curl -X POST "https://your-worker.workers.dev/jobs" \
  -H "Content-Type: application/json" \
  -d '{"type":"fetch","target":"https://example.com/image.png"}'
```

#### Success Response (201) [#success-response-201]

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "fetch",
  "target": "https://example.com/image.png",
  "status": "queued",
  "attempts": 0,
  "enqueuedAt": "2025-06-20T12:00:00.000Z",
  "updatedAt": "2025-06-20T12:00:00.000Z"
}
```

#### Error Codes [#error-codes]

* `400` - Invalid JSON (`INVALID_BODY`), type (`INVALID_TYPE`), or target (`INVALID_TARGET`)

### GET /jobs/:id [#get-jobsid]

Returns the current job record from KV.

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

```bash
curl "https://your-worker.workers.dev/jobs/550e8400-e29b-41d4-a716-446655440000"
```

#### Success Response [#success-response]

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "fetch",
  "target": "https://example.com/image.png",
  "status": "done",
  "attempts": 1,
  "result": "Fetched https://example.com/image.png (simulated)",
  "enqueuedAt": "2025-06-20T12:00:00.000Z",
  "updatedAt": "2025-06-20T12:01:00.000Z"
}
```

#### Error Codes [#error-codes-1]

* `404` - Job not found (`NOT_FOUND`)

<Callout>
  Status may stay `queued` or `processing` briefly until the queue consumer runs. Poll until `done` or `failed`.
</Callout>

## Use Cases [#use-cases]

* Learn Queues producer (`send`) and consumer (`queue()` handler) setup
* Visualize async job lifecycles with KV-backed status
* Demonstrate retry semantics with `message.retry()` and `message.ack()`

## Limitations [#limitations]

* Jobs are simulated; no actual image resize or fetch occurs
* Failure rate is deterministic per job id + attempt (demo only)
* Requires KV namespace and Queue configured in `wrangler.json`

## 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/queue-job-visualizer)
  </Step>

  <Step>
    ### Configure KV and Queue [#configure-kv-and-queue]

    Create a KV namespace bound as `JOBS` and a queue named `queue-job-visualizer`.
  </Step>

  <Step>
    ### Test your deployment [#test-your-deployment]

    ```bash
    curl -X POST "https://your-worker.workers.dev/jobs" \
      -H "Content-Type: application/json" \
      -d '{"type":"resize","target":"photo.png"}'
    ```
  </Step>
</Steps>

## Local Development [#local-development]

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

## Configuration [#configuration]

| Binding      | Purpose                             |
| ------------ | ----------------------------------- |
| `JOBS_QUEUE` | Cloudflare Queue producer/consumer  |
| `JOBS`       | KV namespace for job status records |

## Cloudflare Features Used [#cloudflare-features-used]

* **[Workers](https://developers.cloudflare.com/workers/)** - Edge compute runtime
* **[Queues](https://developers.cloudflare.com/queues/)** - Async job processing
* **[Workers KV](https://developers.cloudflare.com/kv/)** - Job status storage