# DO Alarm Scheduler (/docs/experiments/do-alarm-scheduler)



Schedule a one-off reminder **N seconds in the future** using the Durable Object **Alarm API** (`setAlarm`). Poll `GET /status/:id` to confirm when the alarm fired - since there is no push channel in this demo, polling is the intended pattern.

## Features [#features]

* **POST /schedule** - Schedule a reminder with `{ seconds, message }`
* **GET /status/:id** - Poll for `scheduled` or `fired` status
* **Alarm API** - `storage.setAlarm()` + `alarm()` handler
* **One DO per schedule** - Each schedule id maps to its own Durable Object instance

## API Reference [#api-reference]

### POST /schedule [#post-schedule]

Schedule a one-off reminder.

<TypeTable
  type="{
  seconds: {
    description: &#x22;Delay before the alarm fires (1–300 seconds).&#x22;,
    type: &#x22;number&#x22;,
    required: true,
  },
  message: {
    description: &#x22;Reminder message (max 500 characters).&#x22;,
    type: &#x22;string&#x22;,
    required: true,
  },
}"
/>

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

```bash
curl -X POST "https://your-worker.workers.dev/schedule" \
  -H "Content-Type: application/json" \
  -d '{"seconds":30,"message":"Check the deploy"}'
```

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

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Check the deploy",
  "seconds": 30,
  "status": "scheduled",
  "scheduledFor": "2025-06-20T12:00:30.000Z"
}
```

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

* `400` - Invalid JSON (`INVALID_BODY`), seconds (`INVALID_SECONDS`), or message (`INVALID_MESSAGE`)
* `502` - Schedule failed (`SCHEDULE_ERROR`)

### GET /status/:id [#get-statusid]

Poll schedule status. After the alarm fires, `status` becomes `fired` and `firedAt` is set.

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

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

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

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Check the deploy",
  "seconds": 30,
  "status": "scheduled",
  "scheduledFor": "2025-06-20T12:00:30.000Z"
}
```

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

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Check the deploy",
  "seconds": 30,
  "status": "fired",
  "scheduledFor": "2025-06-20T12:00:30.000Z",
  "firedAt": "2025-06-20T12:00:30.123Z"
}
```

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

* `400` - Missing id (`INVALID_ID`)
* `404` - Schedule not found (`NOT_FOUND`)

## Use Cases [#use-cases]

* Learn Durable Object Alarm API (`setAlarm`, `alarm()` handler)
* Prototype delayed tasks without Cron Triggers or external schedulers
* Build polling-based reminder demos before adding webhooks or email

## Limitations [#limitations]

* Max delay 300 seconds (5 minutes) for the demo
* No push notification when alarm fires; client must poll
* One alarm per Durable Object instance (one schedule id)

## 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/do-alarm-scheduler)
  </Step>

  <Step>
    ### Deploy [#deploy]

    Durable Object migration for `AlarmScheduler` is included in `wrangler.json`.
  </Step>

  <Step>
    ### Test scheduling [#test-scheduling]

    ```bash
    curl -X POST "https://your-worker.workers.dev/schedule" \
      -H "Content-Type: application/json" \
      -d '{"seconds":10,"message":"Hello from the alarm"}'
    ```
  </Step>
</Steps>

## Local Development [#local-development]

```bash
cd apps/experiments/do-alarm-scheduler
npm install
npm run dev
```

Poll status after the delay:

```bash
curl "http://localhost:8787/status/YOUR_SCHEDULE_ID"
```

## Configuration [#configuration]

| Binding     | Purpose                                           |
| ----------- | ------------------------------------------------- |
| `SCHEDULER` | Durable Object namespace (`AlarmScheduler` class) |

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

* **[Workers](https://developers.cloudflare.com/workers/)** - Edge compute runtime
* **[Durable Objects](https://developers.cloudflare.com/durable-objects/)** - Per-schedule state and alarms
* **Alarm API** - One-off delayed execution via `setAlarm()`