Jobs, cron en de wachtrij voor dode letters

Een taak is één achtergrondaanroep voor een functie. Zet het in de wachtrij vanaf een server met een service_role-sleutel.

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,   // wacht 60 seconden vóór de eerste poging
  maxAttempts: 3,  // de standaard
})

Je leest een taak terug met getJob(id) of listJobs({ status, limit }) (limit ligt tussen 1 en 500, standaard 50). De taak heeft de namen status, attempts, max_attempts, error en de datums scheduled_at, started_at, completed_at.

Een baan roept uw functie op zoals elk ander verzoek, met drie verschillen die u moet afhandelen:

Deno.serve(async (req) => {
  const jobId = new URL(req.url).pathname.split('/').pop()
  const { month } = await req.json()
  // …het rapport bouwen en verzenden, met behulp van jobId als idempotentiesleutel
  return new Response('ok')
})

Een echt gesprek geregistreerd {"method":"JOB","path":"/jobs/d443d541-…","role":null,"userId":null,"body":"{\"items\":[\"a\",\"b\"],\"order\":42}"}.

Een taak wordt uitgevoerd zonder gebruiker: vertrouw niet op x-aura-user-id. Als het werk van een gebruiker is, plaatst u de ID van de gebruiker in de payload.

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

• Een taak wordt minstens één keer uitgevoerd. Het kan twee keer worden uitgevoerd als een werker stopt terwijl het actief is, dus maak de functie idempotent.
• Een mislukte poging wordt na een vaste vertraging van 5 seconden opnieuw geprobeerd, totdat maxAttempts is bereikt. De taak is dan dead. De vertraging en het standaard aantal pogingen zijn service-instellingen (JOB_RETRY_DELAY_SECS, JOB_MAX_RETRIES).
• Een taak die na het leasen nog steeds running is (standaard 450 seconden), wordt door de service teruggevorderd.
• Voltooide opdrachten worden standaard 14 dagen bewaard.

In dezelfde echte run doorliep een taak voor een functie die niet bestaat deze reeks: poging 1 mislukte na 3 s met Fonction 'ghost' introuvable, poging 2 mislukte na ongeveer 9 s en de taak werd dead met attempts gelijk aan max_attempts.

Dode opdrachten blijven in de wachtrij staan en kunnen worden weergegeven en opnieuw worden geprobeerd. Deze routes hebben nog geen SDK-methode: gebruik HTTP met een service_role sleutel.

# lijst dode banen
curl "$AURA_URL/v1/functions/jobs/dlq" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# probeer één taak opnieuw
curl -X POST "$AURA_URL/v1/functions/jobs/$JOB_ID/retry" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# probeer elke dode taak opnieuw (tot 1000)
curl -X POST "$AURA_URL/v1/functions/jobs/dlq/requeue" -H "apikey: $AURA_SERVICE_ROLE_KEY"
# → {"data":{"opnieuw in de wachtrij geplaatst":1},"meta":null}

Bij een nieuwe poging wordt de taak teruggezet naar pending zonder de pogingenteller opnieuw in te stellen, zodat de taak nog precies één poging krijgt en terugkeert naar dead als de taak opnieuw mislukt. Verhelp de oorzaak (implementeer bijvoorbeeld de ontbrekende functie) voordat u het opnieuw probeert.

Een cron-invoer roept de functie zelf niet aan: elke keer dat deze wordt geactiveerd, wordt er een taak in de wachtrij geplaatst.

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') // op NAAM, niet op ID

• Het schema heeft 5 velden (min hour day month weekday) of 6 velden (sec min hour day month weekday). Een schema met 5 velden krijgt 0 seconden voorsprong: */1 * * * * wordt opgeslagen als 0 */1 * * * *.
• Aliassen zoals @daily worden geweigerd met een 400 die het verwachte formaat aangeeft.
• De tijden zijn in UTC.
• last_run en next_run zijn null tot het eerste schot. In een echte run werd een schema dat om 15:40 was gemaakt, om 15:41:00 afgevuurd en vervolgens next_run 15:42:00 weergegeven.
• De payload wordt bevroren wanneer u de invoer maakt.
• Het verwijderen van een onbekende naam retourneert 404. Het verwijderen van een cron-item zorgt er ook voor dat het niet meer wordt geactiveerd.
• De SDK heeft geen getCronJob of updateCronJob: verwijder het item en maak het opnieuw.

Voor puur databasewerk vermijdt de extensie Postgres pg_cron de retourvlucht naar een functie: zie de pagina Cron.