Cooldown: тривалість, вихід і шлях у Need Check

Як сендер потрапляє в 🧊, скільки там сидить, що має статися, щоб його випустили, і за яких умов замість випуску він отримує 🚨 Need Check. Окремо: що з цього реально керується групами.

• 1. Як стартує cooldown
• 2. Скільки триває
• 3. Warm-up гейт і вихід
• 4. Два шляхи в Need Check
• 5. Картина в prod
• 6. Керування через групи

1. Як стартує cooldown

Єдиний живий тригер сьогодні — лічильник failed_in_row. Кожен фейл кастомерської відправки проходить через record_failed_send(): лічильник +1, рядок історії 📉 (EVENT 109), і одразу виклик check_deliverability_limits().

• Що рахується фейлом: вебхук message_sent з success=false, вебхук message_failed, і 125-таймаут без guid (детектор таймаутів у scheduler). Фінальна спроба після retry лічильник не інкрементує, лише запускає перевірку.
• Що скидає лічильник у 0: будь-яка доставка (вебхук delivered), а також сам вихід із cooldown.
• Поріг: failed_in_row ≥ 2 за замовчуванням, або Group.failed_in_row активної на цей момент групи.

Два інші тригери, які видно в коді, вимкнені: check_blocking_servers (24h fail-rate) не стоїть у розкладі, __check_messages_limitation (ліміти 900/24h і OTP_LIMITS_1_HOUR) закоментований. У prod за 7 днів усі 10 648 стартів cooldown мають причину «failed in row».

otp_service/servers/deliverability_limits.py:40–153, otp_service/webhooks.py:268–345, otp_service/scheduler.py:386

2. Скільки триває

Тривалість визначає cooldown_times — скільки cooldown-ів сендер уже пройшов з моменту останнього скидання. Це драбина з двох сходинок і обривом:

Світла частина смуги — мінімум діапазону, насичена — випадковий добір усередині діапазону (random.randint).

Що ще додається до тривалості

• Продовження через непідтверджений warm-up: до 2 разів по 55–70 хв. Найгірший випадок для cooldown #1 — близько 2 год плюс ще ~2 год продовжень.
• Пауза після виходу: next_send_date = cooldown_end_date + 10 хв. Сендер вийшов, але кастомерські повідомлення отримує ще через 10 хвилин.
• Крок планувальника: check_cooldown_servers ходить кожні 2 хв (jitter до 5), тож реальний вихід відстає від cooldown_end_date на 0–7 хв.

Коли cooldown_times повертається в 0

• Автоматично: якщо за останні 14 год у сендера ≥ 11 доставлених (≥ 2, якщо він у preheating). Але ця перевірка живе всередині check_deliverability_limits() у гілці «поріг ще не досягнуто» — тобто спрацьовує лише в момент чергового фейлу. Сендер, який доставляє без жодного фейлу, лічильник не скидає, і він чекає на нього до першої невдачі.
• Вручну: адмін-дії recovery / mark as active (reset_deliverability_counters), старт preheat, chat-preheat.
• Не скидається при виході з cooldown: скидається тільки failed_in_row.

deliverability_limits.py:100–153 (драбина), 205–250 (start_cooldown), cooldown.py:36–160

3. Warm-up гейт і вихід

Cooldown не закінчується сам по себе в cooldown_end_date. У цей момент планувальник виносить вердикт: чи довів сендер, що вміє доставляти. Доказом є одна внутрішня server-to-server відправка (warm-up), запланована ще в start_cooldown().

• Слот має нижню межу: не раніше ніж +20–30 хв від старту (для довгих) або +5–10 хв (для коротких). Cooldown коротший за ~10–15 хв слота не вміщує взагалі.
• Відправка: preheat_otp_sender_names (кожні 5 хв, jitter 15) бере сендерів у cooldown лише в останні 75 хв до end_date, шле p2p-повідомлення іншому сендеру, записує cooldown_warmup_uuid / sent_date (EVENT 104 🧊📨).
• Підтвердження: вебхук message_sent від сендера (service=imessage) або inbound на приймачі → cooldown_warmup_delivered=True (EVENT 105 🧊✅). Вікно 3 год, uuid не обов'язковий: будь-яка успішна p2p-доставка в cooldown зараховується.

Вердикт у момент end_date

При будь-якому випуску: cooldown=False, failed_in_row=0, cooldown_start_date=None; історія отримує рядок «Cooldown finished 💧» (EVENT 100) з вердиктом у note.

cooldown.py:36–160 (вердикти), 163–203 (продовження), 206–245 (підтвердження); preheat.py:211–320; webhooks → confirm_cooldown_warmup_delivery

4. Два шляхи в Need Check

Cooldown переводить сендер у 🚨 двома незалежними механізмами. Вони рахують різне і мають різний почерк в історії.

Решта NC за тиждень: 10 з адмінки і 12 від chat-preheat (внутрішня відправка впала в SMS).

deliverability_limits.py:100–101, 252–275 (шлях A); cooldown.py:127–143 (шлях B)

5. Картина в prod за 7 днів

Старти cooldown за номером у драбині

Мінімуми 10–15 хв на кожній сходинці — це сендери в групах: групова затримка заміняє драбину повністю (див. розділ 6). Різкий спад 8 404 → 778 означає, що більшість сендерів після #1 встигають назбирати 11 доставок і скинути лічильник.

Планова тривалість, усі старти

Вердикти при виході (EVENT 100)

Warm-up відправок 13 060, підтверджень 9 230, продовжень 3 252. Тобто ~86% виходів проходять з доказом доставки, ~10% fail-open, ~4% нейтральних.

6. Керування cooldown через групи

Група (otp_service.models.Group) — це набір параметрів з часовим вікном. Сендер може бути в кількох групах; у момент фейлу береться та, чиє вікно накриває поточний час, з найвищим priority. Якщо груп нема або жодна не активна зараз — дефолти з розділу 2.

Поля групи і що вони змінюють

failed_in_row

Поріг фейлів підряд для входу в cooldown. Дефолт 2. Значення 1 = кожен фейл одразу cooldown. 0 ігнорується (діє дефолт 2).

cooldown_delay_from / _to

Тривалість cooldown у хвилинах, випадково з діапазону. Заміняє драбину цілком: і 60–120 для #1–#3, і 12–14 год для #4–#5. Обидва значення мають бути > 0, інакше діє драбина.

send_from / send_to_message_interval

Пауза між кастомерськими відправками сендера (next_send_date), хвилини. Не про cooldown, але саме це визначає, як швидко сендер назбирає 11 доставок для скидання cooldown_times.

from_time / to_time

Вікно дії групи за часом сервера (UTC). Може переходити через північ (22:00 → 08:00). Дефолт 00:00–23:59:59, тобто завжди.

priority

Хто виграє при перетині вікон. Більше = важливіше. Унікальне серед усіх груп (валідація в Group.clean).

Як затримка групи взаємодіє з гейтом

Рецепти

• Швидко виявляти мертві девайси. Група з cooldown_delay 15–45: п'ять cooldown-ів проходять за 3–5 год замість ~34, і шлях A спрацьовує в межах робочої зміни. Ціна — менше часу «відлежатись» для живого, але тимчасово нестабільного акаунта.
• Дати когорті довшу повідь. failed_in_row 3–4 плюс cooldown_delay 120–240: рідше входить, довше сидить, warm-up гарантовано вміщується.
• Різна поведінка вдень і вночі. Дві групи на тих самих сендерах: 08:00–20:00 з короткою затримкою і високим priority, 20:00–08:00 з довгою. Через межу вікна нічого не «перестрибує»: параметри читаються лише в момент фейлу.
• Уникати затримок < 15 хв. Вони не економлять нічого суттєвого, але позбавляють систему єдиного доказу доставки (див. таблицю вище).

Що є в prod зараз

З 660 Active сендерів у групах лише 132; решта 528 живуть на дефолтній драбині. «Інші» — переважно Deleted / Lost / Need Check, що лишились у групах як хвіст від старих батчів. Жодна група з вікном не використовується: «High frequency» порожня.

Де керувати

• Django admin. Розділ Groups: список показує вікно, priority, кількість серверів і send-інтервал; у формі є список серверів з лінками. Прив'язка сендера до груп — поле groups у формі Server.
• Manage API (заголовок Authorization: <MANAGE_SERVERS_API_AUTH_KEY>, префікс api/v1/4fa5e0fd/servers/):

# групи
GET   groups/                      список
POST  groups/                      створити: name, priority, failed_in_row,
                                   cooldown_delay_from, cooldown_delay_to,
                                   send_from_message_interval, send_to_message_interval,
                                   from_time, to_time ("HH:MM[:SS]" або null)
GET   groups/<uuid>/               деталі
PATCH groups/<uuid>/               змінити будь-яке з полів вище
DELETE groups/<uuid>/

# прив'язки, серверо-центрично (до 500 items за запит)
POST  groups/assignments/          set:    items[{server:{region,unit} | uuid, groups:[uuid…]}]
POST  groups/assignments/add/      add
POST  groups/assignments/remove/   remove

# прив'язки, групо-центрично
POST  groups/<uuid>/servers/        set список серверів групи
POST  groups/<uuid>/servers/add/
POST  groups/<uuid>/servers/remove/

Зміна параметрів групи діє з наступного фейлу: уже запущений cooldown свою cooldown_end_date не перераховує.

otp_service/models.py:1177–1215 (Group), 632–642 (get_group_for_current_time); otp_service/servers/groups.py; otp_service/urls_statistics.py:26–35