Quick Start Guide

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

🎯 What You Get

✅ 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

🚀 Getting Started

1. Initialize the Database

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

This creates the queue and dead_letter_queue tables.

2. Enqueue Your First Task

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
}

3. Monitor the Queue

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

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

📋 Available Task Types

Type	Purpose	Payload
log_message	Log to console	`{ message: string, level: "info" \| "warning" \| "error" }`
send_email	Send email via Val Town	`{ to: string, subject: string, text: string }`
webhook	POST to an external URL	`{ url: string, method?: string, body?: any, headers?: object }`
http_request	Make HTTP requests	`{ url: string, method?: string, body?: any, headers?: object }`

💡 Common Examples

High Priority Task

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
  }'

Scheduled Task (1 hour from now)

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)'
  }'

Send Email

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!"
    }
  }'

Call a Webhook

   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" }
    }
  }'

📁 File Structure

File	Purpose
`api.ts`	HTTP endpoints (`/schema`, `/enqueue`, `/monitor`)
`schema.ts`	Database schema initialization
`types.ts`	TypeScript types and Zod schemas
`processors.ts`	Task execution logic for each task type
`worker.ts`	Cron that processes queued tasks

🔧 Customizing Task Types

Add a new task type in processors.ts:

Add to the ProcessorMap type
Create a processor function (e.g., processMyTask)
Add it to the processors object
Add a Zod schema to types.ts
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,
};

⚙️ Configuration

Enqueue Parameters

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

Worker Behavior

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

📊 Monitoring

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

🔍 Next Steps

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