الوظائف والكرون وقائمة انتظار الرسائل الميتة

الوظيفة هي مكالمة خلفية واحدة لوظيفة ما. قم بإضافته من خادم باستخدام مفتاح 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,   // انتظر 60 ثانية قبل المحاولة الأولى
  maxAttempts: 3,  // الافتراضي
})

لقد قرأت مهمة باستخدام getJob(id) أو listJobs({ status, limit }) (limit يقع بين 1 و500، الافتراضي 50). تحتوي الوظيفة على status, attempts, max_attempts, error والتواريخ scheduled_at, started_at, completed_at.

تستدعي الوظيفة وظيفتك مثل أي طلب آخر، مع وجود ثلاثة اختلافات يجب عليك التعامل معها:

Deno.serve(async (req) => {
  const jobId = new URL(req.url).pathname.split('/').pop()
  const { month } = await req.json()
  // ...قم بإنشاء التقرير وإرساله باستخدام jobId كمفتاح للعجز
  return new Response('ok')
})

تم تسجيل مكالمة حقيقية {"method":"JOB","path":"/jobs/d443d541-…","role":null,"userId":null,"body":"{\"items\":[\"a\",\"b\"],\"order\":42}"}.

يتم تشغيل المهمة بدون مستخدم: لا تعتمد على x-aura-user-id. إذا كان العمل يخص مستخدمًا، ضع معرف المستخدم في الحمولة.

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

• يتم تشغيل المهمة مرة واحدة على الأقل. يمكن أن تعمل مرتين إذا توقف العامل أثناء تشغيلها، لذلك تجعل الوظيفة غير فعالة.
• تتم إعادة محاولة المحاولة الفاشلة بعد تأخير ثابت قدره 5 ثوانٍ، حتى يتم الوصول إلى maxAttempts. المهمة إذن هي dead. التأخير وعدد المحاولات الافتراضي هما إعدادات الخدمة (JOB_RETRY_DELAY_SECS, JOB_MAX_RETRIES).
• تتم استعادة المهمة التي لا تزال running بعد عقد الإيجار الخاص بها (450 ثانية بشكل افتراضي) بواسطة الخدمة.
• يتم الاحتفاظ بالمهام المكتملة لمدة 14 يومًا بشكل افتراضي.

في نفس التشغيل الحقيقي، مرت مهمة وظيفة غير موجودة بهذا التسلسل: فشلت المحاولة 1 في 3 ثوانٍ مع Fonction 'ghost' introuvable، وفشلت المحاولة 2 في حوالي 9 ثوانٍ، وأصبحت المهمة dead مع attempts تساوي max_attempts.

تبقى المهام الميتة في قائمة الانتظار ويمكن إدراجها وإعادة المحاولة. لا تحتوي هذه المسارات على طريقة SDK حتى الآن: استخدم HTTP مع مفتاح service_role.

# قائمة الوظائف الميتة
curl "$AURA_URL/v1/functions/jobs/dlq" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# أعد محاولة مهمة واحدة
curl -X POST "$AURA_URL/v1/functions/jobs/$JOB_ID/retry" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# أعد محاولة كل مهمة ميتة (حتى 1000)
curl -X POST "$AURA_URL/v1/functions/jobs/dlq/requeue" -H "apikey: $AURA_SERVICE_ROLE_KEY"
# → {"بيانات":{"requeued":1},"meta":null}

تؤدي إعادة المحاولة إلى إعادة المهمة إلى pending دون إعادة تعيين عداد المحاولات، لذلك تحصل على محاولة أخرى بالضبط وتعود إلى dead إذا فشلت مرة أخرى. قم بإصلاح السبب (نشر الوظيفة المفقودة، على سبيل المثال) قبل إعادة المحاولة.

لا يستدعي إدخال cron الوظيفة نفسها: في كل مرة يتم تشغيلها، فإنها تقوم بإدراج وظيفة في قائمة الانتظار.

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') // بالاسم وليس بالمعرف

• يحتوي الجدول على 5 حقول (min hour day month weekday) أو 6 حقول (sec min hour day month weekday). يحصل الجدول المكون من 5 حقول على 0 ثانية في المقدمة: */1 * * * * يتم تخزينه كـ 0 */1 * * * *.
• يتم رفض الأسماء المستعارة مثل @daily باستخدام 400 الذي يوضح التنسيق المتوقع.
• الأوقات بالتوقيت العالمي المنسق.
• last_run و next_run هما null حتى الإطلاق الأول. في التشغيل الحقيقي، تم تشغيل الجدول الزمني الذي تم إنشاؤه في الساعة 15:40 في الساعة 15:41:00 ثم أظهر next_run 15:42:00.
• يتم تجميد الحمولة عند إنشاء الإدخال.
• يؤدي حذف اسم غير معروف إلى إرجاع 404. يؤدي حذف إدخال cron أيضًا إلى منعه من الإطلاق.
• لا يحتوي SDK على getCronJob أو updateCronJob: احذف الإدخال وأنشئه مرة أخرى.

بالنسبة إلى عمل قاعدة البيانات البحتة، يتجنب الامتداد Postgres pg_cron الرحلة ذهابًا وإيابًا إلى إحدى الوظائف: راجع صفحة Cron.