lousho/triggers هو نقطة التوسعة لآليتك الخاصة (TriggerAdapter وTriggerRegistry)، ومعه بعض الأدوات المساعدة المشتركة مع الـchannels والـschedules: أشكال WebhookAuth وverifySlackSignature() وparseCronExpression(). أما الـadapters الجاهزة للـwebhook وSlack وcron فقد حُذفت؛ راجع الانتقال من triggers.
الاختيار بين triggers وchannels وschedules
واجهة TriggerAdapter
listen تأخذ agent وonEvent معًا بقصد. الـagent هو الواجهة البسيطة: prompt يدخل ونص يخرج. والـonEvent هي نقطة الدخول التي يستدعيها الـadapter عندما ينطلق الـtrigger: الـcaller البسيط يمرّر (input) => agent.send(input)، والـcaller الذي عنده checkpointing أو approval gates أو تحكم بالإلغاء يمرّر onEvent تغلّف هذا كله. استدعِ stop() على الـhandle الذي ترجعه لإيقاف الـadapter.
دلالات الرد تختلف بين adapter وآخر. الـadapter الذي يكون ردّه هو الطلب المفتوح نفسه (webhook) ليس فيه reply()، والذي لا ينتظره مستدعٍ (ساعة) يسلّم النتيجة إلى مكان آخر، والذي عنده قناة رد منفصلة عن الطلب (chat) يطبّق reply().
اكتب adapter خاص بك بإرجاع handle من listen:
TriggerRegistry الـadapters بالاسم: register(name, adapter) وregisterMany() وget() وhas() وlist() وgetAll() وunregister() وclear() وsize(). وglobalTriggerRegistry هو instance مشترك.
مصادقة webhook
أشكالWebhookAuth هي مرجع webhookChannel({ auth }) (راجع Channels). وcheckWebhookAuth() وassertValidWebhookAuth() مُصدَّرتان لتستخدمهما في الـhandler الخاص بك.
header (الافتراضي x-signature-256)، algorithm (sha256 أو sha1، الافتراضي sha256)، prefix (الافتراضي sha256=؛ '' لـdigest مجرّد)، timestampHeader وtoleranceSeconds (ويُسمح أيضًا للـtimestamp أن يسبق الوقت المحلي بدقيقة على الأكثر). التواقيع وbearer tokens تُقارَن في زمن ثابت. والطلب الذي تفشل مصادقته يأخذ ردًّا عامًّا 401 {"error":"Unauthorized"} — الرد لا يذكر أي فحص فشل. والـauth غير الصالح يرمي LOUSHO_TRIGGER_INVALID. قدّم الـwebhooks عبر HTTPS (أنهِ TLS أمام الخادم) حتى لا تُرسَل الـtokens والـpayloads نصًّا صريحًا.
تواقيع طلبات Slack
slackChannel() يتحقق من كل طلب نيابةً عنك (راجع Slack في Channels). أما في الـhandler الخاص بك (slash commands والتفاعلات)، فتحقّق من الـbody الخام بـverifySlackSignature(): HMAC-SHA256 على v0:{X-Slack-Request-Timestamp}:{raw body}، يُقارَن في زمن ثابت مع X-Slack-Signature (v0=<hex>). الطلبات الأقدم من خمس دقائق، أو التي تسبق الوقت المحلي بأكثر من دقيقة، تُرفَض (الـtimestamp بالثواني، كما ترسله Slack). راجع توثيق Slack.
تعابير cron
defineSchedule() مع startSchedules() هو الذي يشغّل cron (راجع Schedules). وparseCronExpression(expr, timezone) وCronExpressionError مُصدَّرتان إذا احتجت أن تتحقق من صحة تعبير أو تحسب وقت الإطلاق التالي بـ.nextRun(after).
الصياغة المدعومة: *، القوائم (1,15)، النطاقات (1-5)، الخطوات (*/15 و10-40/10)، أسماء الأشهر (JAN) وأسماء أيام الأسبوع (MON)، و0 و7 كلاهما يعني الأحد. وفيها أيضًا اختصارات @hourly و@daily (أو @midnight) و@weekly و@monthly و@yearly (أو @annually). وكما في cron الكلاسيكي، إذا قيّدت يوم الشهر ويوم الأسبوع معًا فاليوم يطابق إن طابق أحدهما. التعبير غير الصالح يرمي CronExpressionError يذكر الحقل ويعرض مثالًا صالحًا.
حول تغيّر التوقيت الصيفي، الـjob ذو الساعة الثابتة الذي لا يوجد وقته (عند تقديم الساعة، مثلًا 30 2 * * *) يعمل مرة واحدة في أول لحظة بعد الفجوة (03:00) بدل أن يُتخطّى في ذلك اليوم، والوقت الذي يحدث مرتين (عند إرجاع الساعة) يُطلَق مرة واحدة؛ والجدول الذي يعمل كل ساعة يستمر يُطلَق كل ساعة.