Background tasks

Run heavy or slow work outside the request/response cycle: a request returns immediately and the work happens later, in the background, with retries and de-duplication. Use it for anything that would blow the request budget or that should survive the response: processing an upload, calling an external API, an ingestion pipeline, sending a batch of emails.

A task runs in an ephemeral isolate: the platform loads your app's code, runs one handler, and tears it down. The app does not have to be serving HTTP for a task to run.

Declare handlers with withTasks

Wrap your default HTTP handler with withTasks and pass a map of named task handlers. The default export stays your request handler; onvibe reads the task handlers from it.

import { enqueueTask, withTasks } from "./.onvibe/helpers.ts";

async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);
  if (req.method === "POST" && url.pathname === "/import") {
    const { fileId } = await req.json();
    const { taskId } = await enqueueTask("process_import", { fileId }, {
      dedupKey: `import:${fileId}`,
    });
    return Response.json({ taskId }, { status: 202 });
  }
  return new Response("hello");
}

export default withTasks(handler, {
  // Each handler gets the payload you passed to enqueueTask. Keep it IDEMPOTENT:
  // a task can run more than once on retry; the source of truth is your database.
  process_import: async ({ fileId }) => {
    const res = await fetch(`https://api.example.com/files/${fileId}`); // external fetch is allowed
    // ...heavy work, write results to your Postgres...
    return { processed: true };
  },
});

Enqueue work with enqueueTask

const { taskId, deduplicated } = await enqueueTask("process_import", { fileId }, {
  dedupKey: "import:42",  // optional: won't enqueue a second task while one with this key is active
  maxAttempts: 3,         // optional: retries on failure (exponential backoff)
});

• enqueueTask(name, data?, opts?) returns { taskId, deduplicated }. name must match a handler registered in withTasks.
• De-dup is scoped to your app: dedupKey never collides with other apps.
• Enqueue from anywhere in your handler — a request, a cron, or even another task.

Check status with checkTask

const status = await checkTask(taskId);
// null if no such task, else:
// { status: "pending" | "running" | "done" | "failed", result?: unknown, error?: string }
if (status?.status === "done") {
  // status.result is whatever the task handler returned
}

Notes

• Idempotency is your job: a task may run more than once (retries, timeouts). Make handlers safe to re-run; keep the real state in your database.
• Retries: failures retry with exponential backoff up to maxAttempts (default 3), then the task is failed (its error is in checkTask().error).
• External network: task handlers can fetch the public internet (RSS, third-party APIs, LLMs).
• Timeouts: a task that runs too long is considered stuck and retried.
• Tasks vs cron: cron fires your normal handler on a schedule (see scheduled tasks); tasks run a withTasks handler you enqueue on demand, off the request path.