Jobs, cron e a fila de mensagens mortas

Um trabalho é uma chamada em segundo plano para uma função. Coloque-o na fila de um servidor com uma chave 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,   // espere 60 segundos antes da primeira tentativa
  maxAttempts: 3,  // o padrão
})

Você lê uma tarefa com getJob(id) ou listJobs({ status, limit }) (limit está entre 1 e 500, padrão 50). O trabalho tem status, attempts, max_attempts, error e as datas scheduled_at, started_at, completed_at.

Um trabalho chama sua função como qualquer outra solicitação, com três diferenças que você deve tratar:

Deno.serve(async (req) => {
  const jobId = new URL(req.url).pathname.split('/').pop()
  const { month } = await req.json()
  // …construir e enviar o relatório, usando jobId como chave de idempotência
  return new Response('ok')
})

Uma chamada real registrada {"method":"JOB","path":"/jobs/d443d541-…","role":null,"userId":null,"body":"{\"items\":[\"a\",\"b\"],\"order\":42}"}.

Uma tarefa é executada sem usuário: não confie em x-aura-user-id. Se a obra pertencer a um usuário, coloque o ID do usuário na carga útil.

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

• Uma tarefa é executada pelo menos uma vez. Ele pode ser executado duas vezes se um trabalhador parar enquanto estiver em execução, portanto, torne a função idempotente.
• Uma tentativa com falha é repetida após um atraso fixo de 5 segundos, até que maxAttempts seja alcançado. O trabalho é então dead. O atraso e a contagem de tentativas padrão são configurações de serviço (JOB_RETRY_DELAY_SECS, JOB_MAX_RETRIES).
• Um trabalho que ainda é running após sua concessão (450 segundos por padrão) é recuperado pelo serviço.
• Os trabalhos concluídos são mantidos por 14 dias por padrão.

Na mesma execução real, um trabalho para uma função que não existe passou por esta sequência: a tentativa 1 falhou em 3 s com Fonction 'ghost' introuvable, a tentativa 2 falhou em cerca de 9 s e o trabalho tornou-se dead com attempts igual a max_attempts.

Os trabalhos inativos permanecem na fila e podem ser listados e repetidos. Essas rotas ainda não possuem método SDK: use HTTP com uma chave service_role.

# listar empregos mortos
curl "$AURA_URL/v1/functions/jobs/dlq" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# tentar novamente um trabalho
curl -X POST "$AURA_URL/v1/functions/jobs/$JOB_ID/retry" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# tente novamente todos os trabalhos mortos (até 1000)
curl -X POST "$AURA_URL/v1/functions/jobs/dlq/requeue" -H "apikey: $AURA_SERVICE_ROLE_KEY"
# → {"dados":{"requeued":1},"meta":null}

Uma nova tentativa coloca o trabalho de volta em pending sem redefinir seu contador de tentativas, portanto, ele obtém exatamente mais uma tentativa e retorna para dead se falhar novamente. Corrija a causa (implante a função ausente, por exemplo) antes de tentar novamente.

Uma entrada cron não chama a função em si: cada vez que é acionada, ela enfileira um trabalho.

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') // por NOME, não por ID

• O agendamento possui 5 campos (min hour day month weekday) ou 6 campos (sec min hour day month weekday). Uma programação de 5 campos obtém 0 segundos na frente: */1 * * * * é armazenado como 0 */1 * * * *.
• Aliases como @daily são recusados com um 400 que indica o formato esperado.
• Os horários estão em UTC.
• last_run e next_run são null até o primeiro disparo. Em uma execução real, uma programação criada às 15h40 foi disparada às 15h41:00 e depois mostrou next_run 15h42:00.
• A carga é congelada quando você cria a entrada.
• Excluir um nome desconhecido retorna 404. Excluir uma entrada do cron também impede que ela seja disparada.
• O SDK não possui getCronJob ou updateCronJob: exclua a entrada e crie-a novamente.

Para trabalho puramente de banco de dados, a extensão Postgres pg_cron evita a viagem de ida e volta para uma função: consulte a página Cron.