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

• 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

POST /schedule

Schedule a one-off reminder.

Example Request

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

Success Response (201)

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

Error Codes

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

GET /status/:id

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

Example Request

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

Success Response (scheduled)

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

Success Response (fired)

{
  "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

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

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

• 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

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

Local Development

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

Poll status after the delay:

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

Configuration

Cloudflare Features Used

• Workers - Edge compute runtime
• Durable Objects - Per-schedule state and alarms
• Alarm API - One-off delayed execution via setAlarm()