tokio-web

Async job queue API in Rust. Submit shell commands, poll for results. Jobs persist across restarts via SQLite.

Built with Axum + Tokio + sqlx.

Architecture

POST /jobs  ──► insert row (pending) ──► spawn tokio task
                                               │
                                     set status = running
                                               │
                                       sh -c <command>
                                               │
                              ┌────────────────┴────────────────┐
                           success                            failure
                              │                                  │
                    status = done                       status = failed
                    result  = stdout                    error   = stderr

Each job runs in a detached tokio::spawn task. The SQLite connection pool is shared across all handlers via Axum's State extractor.

Quick start

cargo run
# Server on 0.0.0.0:3000, database written to jobs.db

Override the database path:

DATABASE_URL=sqlite:/tmp/jobs.db cargo run

API

GET /health

curl http://localhost:3000/health

{"status": "ok"}

POST /jobs

Submit a command for async execution.

curl -s -X POST http://localhost:3000/jobs \
  -H 'Content-Type: application/json' \
  -d '{"command": "sleep 2 && echo done"}'

{"id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending"}

GET /jobs/:id

Poll for status and result.

curl -s http://localhost:3000/jobs/550e8400-e29b-41d4-a716-446655440000

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "done",
  "command": "sleep 2 && echo done",
  "result": "done\n",
  "error": null
}

Status lifecycle: pending → running → done | failed

Tests

cargo test

Five integration tests run against an in-memory SQLite database — no setup required.

Security note

This server executes arbitrary shell commands. Do not expose it to untrusted input without adding authentication.