Tasks & Scheduler

Tasks run long jobs outside page rendering: there is no render deadline and full I/O concurrency is available. Unlike the Queue, a task has built-in status, progress and a result. The scheduler triggers work at set times, from a cron expression.

Writing tasks

A task worker starts once and is reused from one job to the next. Declare your tasks with defineTask, then start the worker with startTaskWorker, both imported from @bext-stack/framework/task-worker:

import { defineTask, startTaskWorker } from "@bext-stack/framework/task-worker";

defineTask("generate-report", async (ctx, payload) => {
  ctx.log("starting", payload);

  const rows = await ctx.db.all("SELECT * FROM sales WHERE month = ?", [payload.month]);
  await ctx.progress({ pct: 50 });

  const url = await buildPdf(rows);
  await ctx.kv.set(`report:${ctx.jobId}`, { url });

  return { url }; // becomes the job's `result`
});

startTaskWorker();

Call defineTask at the module's top level, before startTaskWorker(). This file is a worker entry point, not a route: it runs as its own long-lived process, outside page rendering. The platform registers your app's worker entry and starts it on demand; running tasks must be enabled for your app.

The task ctx

ctx carries the full BextSdk (see the SDK Overview) plus task-specific fields:

A handler's return value becomes the job's result (null if the handler returns nothing). A thrown error moves the job to the error status with its message.

Running a task and tracking its status

A task run takes these parameters:

The framework client has no method to start a run: runs are started through the platform, for example by a schedule. Starting a run answers immediately with { jobId, status: "queued" }. The work continues in the background; the job status can then be read, recent jobs listed (50 by default, 500 at most), or a job canceled.

A job status looks like this:

{
  "id": "…", "task": "generate-report", "status": "…", "progress": {},
  "result": {}, "error": null, "trigger": "…",
  "createdAt": "…", "updatedAt": "…", "finishedAt": "…"
}

status is one of queued, running, success, error, timeout or canceled. progress holds the last value passed to ctx.progress, result the handler's return value, and error the error message on failure.

Only a queued or running job can be canceled. Canceling moves the job to canceled without stopping a handler that is already running or aborting ctx.signal: the handler runs to the end, but its result is discarded and the status stays canceled. Finished jobs are kept for 7 days, then deleted.

The scheduler

The scheduler registers recurring work. As with queue handlers, the framework client has no call to register a schedule: schedules are set up for your app through the platform. A schedule is defined by:

Cron expressions take 5 fields, or 6 with seconds first, plus the @hourly, @daily (or @midnight), @weekly, @monthly and @yearly (or @annually) shortcuts. For the day of the week, 0 and 7 both mean Sunday. Expressions are validated on registration: an invalid expression is rejected. Registering a name again updates that schedule. Schedules can be listed and canceled by name.

An HTTP schedule POSTs this body to its handler_url, where scheduled_for is a Unix timestamp in seconds:

{ "name": "nightly-report", "app_id": "<app-id>", "scheduled_for": 1767236400 }

The handler_url follows the same rule as queue handlers: a URL on your app's domain, among the callback URLs the platform has authorised for your app.

Tasks, queue or scheduler

Where to next