Jobs, cron e la coda dei messaggi non recapitati

Un lavoro è una chiamata in background a una funzione. Accodalo da un server con una chiave service_role.

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,   // attendere 60 secondi prima del primo tentativo
  maxAttempts: 3,  // l'impostazione predefinita
})

Si rilegge un lavoro con getJob(id) o listJobs({ status, limit }) (limit è compreso tra 1 e 500, predefinito 50). Il lavoro ha un status, attempts, max_attempts, error e le date scheduled_at, started_at, completed_at.

Un lavoro chiama la tua funzione come qualsiasi altra richiesta, con tre differenze che devi gestire:

Deno.serve(async (req) => {
  const jobId = new URL(req.url).pathname.split('/').pop()
  const { month } = await req.json()
  // …crea e invia il report, utilizzando jobId come chiave di idempotenza
  return new Response('ok')
})

Una vera chiamata registrata {"method":"JOB","path":"/jobs/d443d541-…","role":null,"userId":null,"body":"{\"items\":[\"a\",\"b\"],\"order\":42}"}.

Un lavoro viene eseguito senza un utente: non fare affidamento su x-aura-user-id. Se l'opera appartiene a un utente, inserisci l'ID dell'utente nel payload.

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

• Un lavoro viene eseguito almeno una volta. Può essere eseguito due volte se un lavoratore si ferma mentre è in esecuzione, quindi rendi la funzione idempotente.
• Un tentativo fallito viene ritentato dopo un ritardo fisso di 5 secondi, fino al raggiungimento di maxAttempts. Il lavoro sarà quindi dead. Il ritardo e il conteggio dei tentativi predefiniti sono impostazioni del servizio (JOB_RETRY_DELAY_SECS, JOB_MAX_RETRIES).
• Un lavoro che è ancora running dopo il lease (450 secondi per impostazione predefinita) viene recuperato dal servizio.
• Per impostazione predefinita, i lavori finiti vengono conservati per 14 giorni.

Nella stessa esecuzione reale, un lavoro per una funzione che non esiste ha seguito questa sequenza: tentativo 1 fallito in 3 s con Fonction 'ghost' introuvable, tentativo 2 fallito in circa 9 s e il lavoro è diventato dead con attempts uguale a max_attempts.

I lavori morti rimangono in coda e possono essere elencati e ritentati. Questi percorsi non hanno ancora un metodo SDK: utilizza HTTP con una chiave service_role.

# elencare i lavori morti
curl "$AURA_URL/v1/functions/jobs/dlq" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# riprovare un lavoro
curl -X POST "$AURA_URL/v1/functions/jobs/$JOB_ID/retry" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# riprovare ogni lavoro morto (fino a 1000)
curl -X POST "$AURA_URL/v1/functions/jobs/dlq/requeue" -H "apikey: $AURA_SERVICE_ROLE_KEY"
# → {"data":{"requeued":1},"meta":null}

Un nuovo tentativo riporta il lavoro a pending senza reimpostare il contatore dei tentativi, quindi ottiene esattamente un altro tentativo e ritorna a dead se fallisce di nuovo. Correggere la causa (ad esempio, distribuire la funzione mancante) prima di riprovare.

Una voce cron non richiama la funzione stessa: ogni volta che viene attivata, accoda un lavoro.

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') // per NOME, non per ID

• La pianificazione ha 5 campi (min hour day month weekday) o 6 campi (sec min hour day month weekday). Una pianificazione a 5 campi ottiene 0 secondi in anticipo: */1 * * * * viene memorizzato come 0 */1 * * * *.
• Alias come @daily vengono rifiutati con un 400 che indica il formato previsto.
• Gli orari sono in UTC.
• last_run e next_run sono null fino alla prima cottura. In un'esecuzione reale, una pianificazione creata alle 15:40 è stata attivata alle 15:41:00 e quindi ha mostrato next_run 15:42:00.
• Il payload viene bloccato quando crei la voce.
• L'eliminazione di un nome sconosciuto restituisce 404. L'eliminazione di una voce cron ne impedisce anche l'attivazione.
• L'SDK non ha getCronJob o updateCronJob: elimina la voce e creala di nuovo.

Per il lavoro puramente di database, l'estensione Postgres pg_cron evita il viaggio di andata e ritorno verso una funzione: vedere la pagina Cron.