Backend
Background Work
Work that should outlive the response goes in waitUntil:
import { defineFunction, requireAuth, waitUntil } from "@rebasepro/server/functions";
export default defineFunction((app, { rebase }) => { app.post("/orders", requireAuth, async (c) => { const order = await c.req.json(); // The caller does not wait for this, but shutdown does. waitUntil(c, rebase.email.send({ to: "warehouse@example.com", subject: "New order", html: "<p>Pick and pack</p>" })); return c.json({ received: true }); });});An un-awaited promise looks equivalent and is not. waitUntil buys two things:
- On Node, the promise is tracked, so a graceful shutdown waits for it instead of the process exiting out from under a half-sent webhook. A floating promise at
SIGTERMis simply lost. - On an isolate-based host, the host is told to keep the isolate alive until the promise settles. Without it, work is dropped the moment the response resolves — silently, with a clean 200 in the logs.
A rejection is logged rather than left to the unhandled-rejection handler, so a failure names the route it came from.
Code that runs outside any request has no c to pass: a module-level initialiser, a helper that routes and crons share, work a cron run starts and does not wait for. Hand waitUntil the work alone:
import { waitUntil } from "@rebasepro/server/functions";
let ready: Promise<void> | undefined;
export function ensureCatalogue(): Promise<void> { ready ??= loadCatalogue().then(() => { // No request to attach it to, but shutdown still waits for it. waitUntil(rateNewSongs()); }); return ready;}The work is tracked for graceful shutdown and a rejection is logged, as with c. What it cannot do is keep an isolate alive, because that is the request’s execution context: pass c whenever there is a request. Work that a cron run, a job or a queue handler can simply await should be awaited instead; the run is what shutdown waits for, and its outcome is recorded with it.
Shutdown waits at most 5 seconds for this work. Work that takes minutes belongs in a cron job or a job, which are recorded and restartable. A cron job also runs one at a time across instances, whether the schedule or a manual trigger started it.