صف و کار پس‌زمینه

cloudhost queues create emails-dead
cloudhost queues create emails --dead-letter-queue emails-dead --max-retries 5
# created queue emails
cloudhost queues ls

صف پیام‌هایی را نگه می‌دارد که هر کدام یک مقدار JSON تا ۱۲۸ کیلوبایت است، تا مصرف‌کننده آن‌ها را بردارد. صف مرده صف دیگری از همین تیم است. پیش‌فرض‌ها: مهلت پردازش ۳۰ ثانیه، سه بار تلاش دوباره (با تأخیر ۵، ۱۰ و ۲۰ ثانیه) و نگه‌داری تا سقف طرح. تحویل «دست‌کم یک‌بار» است و ترتیب به بهترین شکل ممکن حفظ می‌شود، نه تضمینی.

[[queues.producers]]
binding = "JOBS"
queue   = "emails"

delay_seconds تحویل را عقب می‌اندازد (تا یک ساعت در طرح رایگان، تا ۷ روز در حرفه‌ای). dedup_id جلوی تکرار را می‌گیرد: همان شناسه در ۱۰ دقیقه فقط یک‌بار پذیرفته می‌شود و بقیه در duplicates شمرده می‌شوند. هر دسته تا ۱۰۰ پیام و ۲۵۶ کیلوبایت. فرستادن با API به کلیدی با نقش توسعه‌دهنده یا بالاتر نیاز دارد. شکل قدیمی [[queue]] با binding و name هم هنوز پذیرفته است.

# in the consumer's project file: on deploy this function becomes the queue's consumer
[[queues.consumers]]
queue             = "emails"
max_batch_size    = 10
max_batch_wait_ms = 2000
max_retries       = 5
dead_letter_queue = "emails-dead"

بازگشت عادی یعنی همهٔ دسته تایید شد؛ پرتاب خطا یعنی پیام‌های تاییدنشده دوباره امتحان شوند. batch.ackAll() و batch.retryAll() هم هست. ممکن است پیامی دوباره برسد، پس مصرف‌کننده باید با تکرار سازگار باشد.

اگر مصرف‌کننده تا پایان مهلت پردازش جواب ندهد، دسته به صف برمی‌گردد و دوباره تحویل می‌شود. یک فانکشن می‌تواند مصرف‌کنندهٔ چند صف باشد؛ batch.queue نام صف را می‌دهد. هر صف یک مصرف‌کننده دارد: یک فانکشن، یک آدرس یا دریافت دستی.

cloudhost queues consumer emails --url https://example.com/hooks/emails --concurrency 4
# signing secret (shown once): whsec_…
cloudhost queues consumer rotate-secret emails   # a new secret; the old one stops signing

پلتفرم هر پیام را جداگانه با یک POST به آدرس HTTPS شما می‌فرستد؛ بدنه همان بدنهٔ پیام به شکل JSON است. هدرها طبق استاندارد Standard Webhooks‌اند، پس هر کتابخانهٔ Standard Webhooks امضا را بررسی می‌کند:

• webhook-id: شناسهٔ پیام، برای کنار گذاشتن تکرارها.
• webhook-timestamp: زمان ارسال به ثانیهٔ یونیکس.
• webhook-signature: v1,<base64>، یعنی HMAC-SHA256 روی id.timestamp.body با کلید whsec_ صف.
• queue-name و queue-attempt: نام صف و شمارهٔ این تلاش.

پاسخ ۲xx یعنی پیام تایید شد. هر پاسخ دیگر، یا بی‌پاسخی تا پایان مهلت پردازش، یعنی تلاش دوباره با تأخیر. کلید امضا فقط یک‌بار نشان داده می‌شود؛ آن را در اسرار برنامهٔ گیرنده نگه دارید. آدرسهای خصوصی و داخلی پذیرفته نمی‌شوند.

cloudhost queues consumer emails --pull
cloudhost queues pull emails --max 10 --visibility-timeout 60
cloudhost queues ack emails <lease_id> <lease_id>
cloudhost queues ack emails <lease_id> --retry --delay 30

برای برنامه‌هایی بیرون از پلتفرم: تا ۱۰۰ پیام بردارید، پردازش کنید و با lease_id هر کدام تایید کنید. پیامی که تا پایان مهلت پردازش تایید یا دوباره‌سپاری نشود، به صف برمی‌گردد. دریافت دستی فقط روی صفی کار می‌کند که مصرف‌کننده‌اش pull است (not_pull).

پس از هر شکست، پیام با تأخیری که از retry_delay_s (پیش‌فرض ۵ ثانیه) شروع می‌شود و هر بار دو برابر می‌شود دوباره می‌آید (حداکثر ۱۲ ساعت). وقتی max_retries (تا ۱۰۰) تمام شد، پیام به صف مرده می‌رود و نام صف مبدأ و علت کنارش می‌ماند. بدون صف مرده پیام دور ریخته می‌شود.

cloudhost queues dead-letters emails                  # browse what failed
cloudhost queues dead-letters retry emails --limit 100 # back into emails, attempts reset
cloudhost queues retry emails <id> <id>                # only these
cloudhost queues dead-letters purge emails             # delete them
cloudhost queues redrive emails-dead                   # from the dead-letter queue: each back where it came from

صف مرده یک صف معمولی است: می‌توانید پیام‌هایش را ببینید، برگردانید یا پاک کنید. علت را برطرف کنید و بعد پیام‌ها را برگردانید؛ با تلاش‌های جدید شروع می‌شوند. پاک‌کردن به تایید دومرحله‌ای نیاز دارد.

cloudhost schedules create "0 3 * * *" --queue emails --name nightly --body '{"task":"digest"}'
cloudhost schedules create "*/15 * * * *" --url https://example.com/hooks/tick --tz UTC
cloudhost schedules ls
cloudhost schedules pause <id>
cloudhost schedules rm <id>

زمان‌بندی با یک عبارت cron (پنج فیلد) در منطقهٔ زمانی دلخواه (پیش‌فرض Asia/Tehran) یک پیام می‌فرستد: به یک صف، به یک فانکشن یا به یک آدرس. آدرسها همان‌طور امضا می‌شوند که مصرف با آدرس؛ کلید امضای هر زمان‌بندی فقط هنگام ایجاد نشان داده می‌شود. last_at و last_status آخرین اجرا را نشان می‌دهند. طرح رایگان ۱۰ زمان‌بندی دارد و حرفه‌ای ۱٬۰۰۰.

cloudhost queues stats emails --range 24h
#   backlog 12 (ready 9, delayed 1, in flight 2), oldest 4s, 2 KB
#   per minute: sent 40, delivered 39, acked 38, failed 1, dead 0
cloudhost queues messages emails --state in_flight
cloudhost queues pause emails      # sends still accepted
cloudhost queues resume emails

GET /v1/queues/<name>/stats شمار پیام‌های منتظر، تأخیری و در حال پردازش، حجم، سن قدیمی‌ترین پیام و نرخ هر دقیقه در ۵ دقیقهٔ اخیر را می‌دهد؛ …/observability همان نمودارها را در ۱ ساعت، ۲۴ ساعت یا ۷ روز. در داشبورد: صف‌ها، با نمودار، مصرف‌کننده، نگاهی به پیام‌ها (بدون تغییر)، صف مرده، زمان‌بندی‌ها و تنظیمات.

هر عملیات یک ارسال، یک تحویل یا یک تایید/تلاش دوباره تا ۶۴ کیلوبایت است؛ پیام بزرگ‌تر به ازای هر ۶۴ کیلوبایت یک عملیات حساب می‌شود. قیمت: هر یک میلیون عملیات ۸۰٬۰۰۰ تومان، از کیف پول ریالی. در طرح رایگان پس از ۱۰٬۰۰۰ عملیات در روز درخواست‌ها با 429 ops_limit رد می‌شوند تا روز بعد؛ صف پُر (queue_full) هم ارسال جدید را رد می‌کند. در فاکتور، عملیات صف یک سطر جدا دارد.