Run background jobs

A run has 10 seconds. Most work fits; some doesn’t: emailing 3,000 people waiting for a product, importing 20,000 stock levels from an ERP, or asking for a review a week after delivery. Background jobs split that work into short runs. Any work can queue a job, now or later, and Littleworks delivers it at least once, retries it when it fails and shows what failed.

Job works#

A job runs a published work whose trigger is {"type": "job"}. It runs at the work’s current version when the job runs, not when it was queued, like any other real run: same deadline, capabilities, logs and Runs entry. Its input is exactly what was queued, checked against the work’s inputSchema when it is queued and again when it runs. A job work never runs on its own; other works (events, schedules, Flow, pages, URLs, and job works themselves) queue it.

{
  "name": "back_in_stock.send",
  "feature": "back_in_stock",
  "title": "Email one batch of back-in-stock signups",
  "trigger": { "type": "job" },
  "inputSchema": {
    "type": "object",
    "properties": { "productId": { "type": "string" } },
    "required": ["productId"]
  }
}

context.trigger is "job", and context.job describes the job: {id, key, attempt, maxAttempts, previousRunIds, enqueuedAt, scheduledFor, enqueuedBy, rootId, generation}. rootId and generation place it in a chain of continuations.

Queue jobs#

// Queue one job. Returns {id, status: "queued" | "duplicate", runAt}.
await jobs.enqueue("reviews.request", { orderId }, { delaySeconds: 7 * 86400, key: `review:${orderId}` });

// Queue up to 50 jobs of one work at once.
await jobs.enqueueMany("stock.notify", batches.map((b, i) => ({ input: b, key: `${event.id}:${i}` })));

// Queue this work again with new input: the next page of a long task.
await jobs.continue({ cursor: page.nextCursor });

// Cancel a queued (not running) job by key or id.
await jobs.cancel("reviews.request", { key: `review:${orderId}` });

• Kept only if the run completes. Jobs a run queues are held until the run finishes, whatever it returns. If the run throws, times out or is interrupted, they are discarded, and a retry of that run queues them again. A crashed run never leaves half a chain behind.
• Continue at most once. jobs.continue is enqueue of the current work with the key continue:<job id>, so a job continues once even when its run is retried. Long work is a chain of short runs: do a page, then continue with a cursor.
• Always key fan-out. Without a key, queuing twice queues two jobs. Key each batch by what it covers, such as the event ID and batch number, so a repeated event or retried run queues nothing twice.

// Event work: when a product is back in stock, queue the emails as a background job.
export default async ({ input, jobs }) => {
  const productId = "gid://shopify/Product/" + input.payload.product_id;
  // Keyed by the event: a repeated delivery or a retried run queues it once.
  return jobs.enqueue("back_in_stock.send", { productId }, { key: `restock:${input.event.id}` });
};

// Job work: email the next 50 waiting signups, mark them, and continue until none are left.
export default async ({ input, db, http, secrets, jobs }) => {
  const signups = db.collection("signups");
  const page = await signups.list({ where: { productId: input.productId, status: "waiting" }, limit: 50 });
  if (!page.items.length) return { done: true };
  await http.fetch("https://api.email.example/batch", {
    method: "POST",
    headers: { Authorization: `Bearer ${await secrets.get("EMAIL_API_KEY")}` },
    body: JSON.stringify({ to: page.items.map((s) => s.data.email), template: "back-in-stock" }),
  });
  // Mark them so the next step moves on to the next 50.
  await db.batch(page.items.map((s) => ({ type: "update", collection: "signups", id: s.id, revision: s.revision, data: { ...s.data, status: "notified" } })));
  await jobs.continue({ productId: input.productId });
  return { emailed: page.items.length };
};

// Job work: import one page of an ERP's stock levels, then continue with the next page.
export default async ({ input, http, secrets, shopify, jobs, context, log }) => {
  const key = await secrets.get("ERP_API_KEY");
  const page = await (await http.fetch(`https://erp.example.com/stock?cursor=${input.cursor ?? ""}`, {
    headers: { Authorization: `Bearer ${key}` },
  })).json();
  // inventorySetQuantities takes up to 250 quantities in one call.
  await shopify.admin.graphql(SET_QUANTITIES, { input: toQuantities(page.items) });
  if (page.nextCursor) await jobs.continue({ cursor: page.nextCursor });
  log.info("Page", context.job.generation + 1, "attempt", context.job.attempt);
  return { imported: page.items.length, more: Boolean(page.nextCursor) };
};

How delivery works#

• At least once. In rare cases, such as an instance stopping after Shopify accepted a change but before the run was recorded, a job’s attempt can start again. Use context.job.attempt, previousRunIds and your own records (an emailedAt field, a processed cursor) so repeating it does no harm.
• Retries. A run that throws, times out or exceeds a resource limit is retried after 1 minute, 10 minutes, 1 hour and 6 hours, up to maxAttempts. A returned 4xx or 5xx response counts as handled and isn’t retried; throw to ask for a retry.
• Waiting doesn’t use attempts. A busy store waits a minute. When the run allowance is used up, jobs wait up to 24 hours for it, then expire with a notice. Jobs for a paused work wait up to 7 days and run when it is resumed; the work’s page can cancel them instead. Deleting the work or uninstalling the app cancels them.
• Failures stay visible. A job that fails its last attempt is kept for 7 days with its error and every run, with a notice on the work. Retry it after a fix with retry_job or the Retry button on the work’s page; it gets a fresh set of attempts.
• Pace. Each store runs at most 2 jobs at a time, in their own lane: an import never delays Shopify events (up to 6 at a time) or storefront traffic, and one store’s queue never delays another store’s. Due jobs run oldest first, without a strict order; a chain of continuations runs one step at a time.
• Shopify throttling. A job that hits Shopify’s rate limit (SHOPIFY_THROTTLED) is retried a minute later. To go faster, read extensions.cost.throttleStatus from the response and continue with a short delay before the bucket runs dry.

Runs and pricing#

Every job attempt that starts a run counts as one run against the store’s allowance, like any other run. Queuing, de-duplicating, cancelling and waiting are free. Jobs usually make big work cheaper in runs, because each run does up to ten seconds of work: 3,000 back-in-stock emails, sent 50 to an API request, take about 60 runs. Usage shows job runs as Background jobs, and the notice for one work taking most of a day’s runs covers runaway chains.

Test and watch#

• Test a job work directly. invoke_function with input and trigger: {job: {attempt?, previousRunIds?, key?}} fills context.job as a queued job would. From the CLI: littleworks invoke back_in_stock.send '{"productId":"gid://shopify/Product/1"}' --job.
• Jobs from test runs are test jobs. A test run’s jobs run the target’s newest version as test runs, at most 200 a day per store, due within 1 hour, and a chain stops after 20 steps. Like every test run, they use the store’s real Shopify data and call real external services, so test a fan-out with a small list first.
• Watch. list_jobs (CLI: littleworks jobs) lists jobs with their status, attempts, runs and error; inputs are never returned, only their size. cancel_jobs (littleworks jobs cancel <work>) cancels queued ones and retry_job (littleworks jobs retry <id>) re-queues a failed one. get_function shows a job work’s queued, running, succeeded and failed jobs. In Shopify admin, Works filters by Runs from: Background jobs, and a job work’s page shows its jobs and failed jobs with Retry and Cancel.
• Locally. With npm run dev:local, queued jobs run from the local maintenance loop. npm run local:tick -- --at <time> runs the jobs due by then, so delayed jobs and retries can be tried without waiting.

Limits#

Jobs reach only the store’s own job works, and only a running work can queue them, so storefront visitors can’t queue jobs directly. A public URL work that queues a job per request should key it, so repeated requests don’t multiply. For bulk Shopify writes, prefer mutations that take many items at once, such as inventorySetQuantities (250 quantities), productVariantsBulkUpdate (a product’s variants) and metafieldsSet (25 metafields), over one mutation per record.