A lightweight SQLite-based queue system for Val Town with priority support, scheduled execution, retries, and monitoring.

• ✅ SQLite-backed task queue with ACID guarantees
• ✅ Priority-based processing
• ✅ Delayed/scheduled task execution
• ✅ Automatic retry logic with configurable max attempts
• ✅ Dead letter queue for failed tasks
• ✅ Worker processing tasks every minute
• ✅ Built-in monitoring endpoint

curl https://lqw.web.val.run/schema

This creates the queue and dead_letter_queue tables.

curl -X POST https://lqw.web.val.run/enqueue \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "log_message",
    "payload": {
      "message": "Hello from the queue!",
      "level": "info"
    }
  }'

Response:

{
   "success": true,
   "task_id": "1",
   "status": "queued",
   "scheduled_for": null
}

curl https://lqw.web.val.run/monitor

View stats on task counts, processing durations, dead letter queue, and upcoming scheduled tasks.

curl -X POST https://lqw.web.val.run/enqueue \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "log_message",
    "payload": { "message": "Urgent!", "level": "info" },
    "priority": 10
  }'

curl -X POST https://lqw.web.val.run/enqueue \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "log_message",
    "payload": { "message": "See you later!", "level": "info" },
    "scheduled_for": '$(date -v+1H +%s)'
  }'

curl -X POST https://lqw.web.val.run/enqueue \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "send_email",
    "payload": {
      "to": "user@example.com",
      "subject": "Queue Test",
      "text": "Hello from the queue!"
    }
  }'

   curl -X POST https://lqw.web.val.run/enqueue \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "webhook",
    "payload": {
      "url": "https://example.com/webhook",
      "method": "POST",
      "body": { "event": "task_completed" }
    }
  }'

Add a new task type in processors.ts:

1. Add to the ProcessorMap type
2. Create a processor function (e.g., processMyTask)
3. Add it to the processors object
4. Add a Zod schema to types.ts
5. Update VALID_TASK_TYPES in api.ts

Example:

// In processors.ts
async function processMyTask(payload: MyTaskPayload) {
   // Your logic here
}

// Add to ProcessorMap type and processors object
const processors = {
   // ... existing
   my_task: processMyTask,
};

• task_type (required): One of the valid task types
• payload (required): Task-specific data
• priority (optional, default: 0): Higher = processed first
• max_attempts (optional, default: 3): Retries before DLQ
• scheduled_for (optional): Unix timestamp for delayed execution

• Processes up to 10 tasks per worker run
• Runs every minute (configure in Val Town)
• Respects priority and scheduled_for when selecting tasks
• Automatically retries failed tasks up to max_attempts times
• Moves tasks to dead letter queue after max retries

The /monitor endpoint returns:

• Task counts by status (pending, processing, completed, failed)
• Average processing duration per status
• Breakdown by task type
• Dead letter queue count and recent failures
• Upcoming scheduled tasks

1. Read the full README.md for detailed API reference
2. Check types.ts for all type definitions
3. Customize processors.ts with your own task types
4. Use the /monitor endpoint to track queue health