Jobs, Cron und die Warteschlange für unzustellbare Nachrichten

Ein Job ist ein Hintergrundaufruf einer Funktion. Stellen Sie es mit einem service_role-Schlüssel von einem Server in die Warteschlange.

import { createClient } from '@aurabase/aurabase-js'

const admin = createClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

const { data: job, error } = await admin.functions.enqueueJob('send-report', {
  payload: { month: '2026-10' },
  delaySecs: 60,   // Warten Sie 60 Sekunden vor dem ersten Versuch
  maxAttempts: 3,  // die Standardeinstellung
})

Sie lesen einen Job mit getJob(id) oder listJobs({ status, limit }) zurück (limit liegt zwischen 1 und 500, Standard 50). Der Job hat ein status, attempts, max_attempts, error und die Daten scheduled_at, started_at, completed_at.

Ein Job ruft Ihre Funktion wie jede andere Anfrage auf, mit drei Unterschieden, die Sie berücksichtigen müssen:

Deno.serve(async (req) => {
  const jobId = new URL(req.url).pathname.split('/').pop()
  const { month } = await req.json()
  // …den Bericht erstellen und senden, wobei jobId als Idempotenzschlüssel verwendet wird
  return new Response('ok')
})

Ein echter Anruf wurde protokolliert {"method":"JOB","path":"/jobs/d443d541-…","role":null,"userId":null,"body":"{\"items\":[\"a\",\"b\"],\"order\":42}"}.

Ein Job wird ohne Benutzer ausgeführt: Verlassen Sie sich nicht auf x-aura-user-id. Wenn das Werk einem Benutzer gehört, geben Sie die Benutzer-ID in die Nutzlast ein.

pending ──claimed──▶ running ──▶ completed
   ▲                    │
   └── after 5 s ◀── failed (attempts left)
                        └──▶ dead (no attempts left)

• Ein Job wird mindestens einmal ausgeführt. Sie kann zweimal ausgeführt werden, wenn ein Worker während der Ausführung stoppt. Machen Sie die Funktion daher idempotent.
• Ein fehlgeschlagener Versuch wird nach einer festen Verzögerung von 5 Sekunden wiederholt, bis maxAttempts erreicht ist. Der Job ist dann dead. Die Verzögerung und die Standardversuchsanzahl sind Diensteinstellungen (JOB_RETRY_DELAY_SECS, JOB_MAX_RETRIES).
• Ein Job, der nach seiner Lease (standardmäßig 450 Sekunden) immer noch running ist, wird vom Dienst zurückgefordert.
• Abgeschlossene Aufträge werden standardmäßig 14 Tage lang aufbewahrt.

Im selben realen Lauf durchlief ein Job für eine Funktion, die nicht existiert, diese Sequenz: Versuch 1 schlug nach 3 s mit Fonction 'ghost' introuvable fehl, Versuch 2 schlug nach etwa 9 s fehl und der Job wurde zu dead mit attempts gleich max_attempts.

Abgebrochene Jobs bleiben in der Warteschlange und können aufgelistet und erneut versucht werden. Für diese Routen gibt es noch keine SDK-Methode: Verwenden Sie HTTP mit einem service_role-Schlüssel.

# Listen Sie tote Jobs auf
curl "$AURA_URL/v1/functions/jobs/dlq" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# Versuchen Sie es erneut mit einem Job
curl -X POST "$AURA_URL/v1/functions/jobs/$JOB_ID/retry" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# Wiederholen Sie jeden toten Job (bis zu 1000)
curl -X POST "$AURA_URL/v1/functions/jobs/dlq/requeue" -H "apikey: $AURA_SERVICE_ROLE_KEY"
# → {"data":{"requeued":1},"meta":null}

Bei einem erneuten Versuch wird der Auftrag auf pending zurückgesetzt, ohne dass sein Versuchszähler zurückgesetzt wird. Er erhält also genau einen weiteren Versuch und kehrt zu dead zurück, wenn er erneut fehlschlägt. Beheben Sie die Ursache (stellen Sie beispielsweise die fehlende Funktion bereit), bevor Sie es erneut versuchen.

Ein Cron-Eintrag ruft nicht die Funktion selbst auf: Bei jedem Auslösen wird ein Job in die Warteschlange gestellt.

await admin.functions.createCronJob('nightly-cleanup', '0 3 * * *', 'cleanup', {
  payload: { dryRun: false },
})

const { data: crons } = await admin.functions.listCronJobs()
await admin.functions.deleteCronJob('nightly-cleanup') // nach NAME, nicht nach ID

• Der Zeitplan hat 5 Felder (min hour day month weekday) oder 6 Felder (sec min hour day month weekday). Ein Zeitplan mit 5 Feldern erhält 0 Sekunden vor: */1 * * * * wird als 0 */1 * * * * gespeichert.
• Aliase wie @daily werden mit einem 400 abgelehnt, das das erwartete Format angibt.
• Die Zeiten sind in UTC angegeben.
• last_run und next_run sind bis zur ersten Zündung null. In einem echten Lauf wurde ein um 15:40 Uhr erstellter Zeitplan um 15:41:00 Uhr ausgelöst und zeigte dann next_run 15:42:00 Uhr an.
• Die Nutzdaten werden eingefroren, wenn Sie den Eintrag erstellen.
• Das Löschen eines unbekannten Namens gibt 404 zurück. Das Löschen eines Cron-Eintrags verhindert auch, dass er ausgelöst wird.
• Das SDK hat kein getCronJob oder updateCronJob: Löschen Sie den Eintrag und erstellen Sie ihn erneut.

Für reine Datenbankarbeit vermeidet die Erweiterung Postgres pg_cron den Roundtrip zu einer Funktion: siehe Seite Cron.