Commentail 1.2.0: почтовые бэкенды Django и очередь задач проекта

Выпустил Commentail 1.2.0. В этой версии упростил подключение библиотеки к инфраструктуре существующего Django-проекта: письма могут использовать его почтовый бэкенд, а фоновая обработка — его очередь задач. Заодно обновил форму комментария и обработку некорректного ввода. Общий обзор библиотеки есть на странице проекта; здесь — изменения выпуска.

Отправка писем через EMAIL_BACKEND

Commentail теперь использует настроенный в Django EMAIL_BACKEND для подтверждения гостевой почты и отправки писем из своей очереди. Если проект уже отправляет почту через API сервиса, можно подключить соответствующий бэкенд Django. Для него больше не требуется заполнять SMTP-параметры, которые этот транспорт не использует.

Сам бэкенд устанавливается и настраивается в проекте сайта. В EMAIL_BACKEND нужен путь к его Python-классу; ключ API, адрес отправителя и таймаут задаются по документации выбранного бэкенда. В Commentail не добавлен отдельный SDK почтового провайдера. Секреты остаются в окружении проекта или хранилище секретов.

Для локальной проверки гостевого сценария можно вывести письма в консоль:

EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"
DEFAULT_FROM_EMAIL = "comments@example.invalid"

Такой бэкенд позволяет пройти сценарий без внешнего почтового сервиса, но письма будут в выводе фонового процесса, а не во входящих. Ссылки из них нужно хранить приватно: они дают доступ к действиям с комментарием.

Доступность гостевой формы проверяется по настройкам. Эта проверка не обращается к провайдеру и не подтверждает правильность его ключей. Для отметки письма как отправленного бэкенд должен сообщить о принятии одного сообщения. Если он лишь передаёт письмо в другую очередь, дальнейшую доставку нужно отслеживать средствами этой очереди или провайдера.

Для стороннего бэкенда следует настроить конечный сетевой таймаут короче MAIL_LEASE_SECONDS — по умолчанию это 300 секунд. SMTP-защита от долгой отправки сохранена; специфичный для SMTP аргумент таймаута не передаётся произвольным бэкендам. Подробности — в руководстве по почте и фоновой обработке.

Фоновая обработка в очереди задач проекта

Для периодической задачи появился публичный вызов commentail.background.process_pending(). Он обрабатывает почтовую очередь и удаляет истёкшие неподтверждённые комментарии, а также очищает истёкшие CAPTCHA, подтверждения гостей, билеты форм и старые события лимитов. Если проект уже использует Celery или другую очередь задач, отдельное расписание для команды Commentail не требуется.

Например, в установленном приложении проекта с Celery можно добавить такую задачу. Имя myapp нужно заменить на имя своего приложения:

from celery import shared_task
from commentail.background import process_pending


@shared_task(name="myapp.process_commentail")
def process_commentail_task():
    return process_pending(mail_limit=100)

При стандартной настройке Celery с пространством параметров CELERY добавьте запись в существующий CELERY_BEAT_SCHEDULE, сохранив остальные задачи проекта:

CELERY_BEAT_SCHEDULE = {
    # Keep the project's other periodic tasks here.
    "commentail-every-minute": {
        "task": "myapp.process_commentail",
        "schedule": 60.0,
    },
}

Celery остаётся необязательной зависимостью: Commentail не устанавливает его, не регистрирует задачи и не настраивает брокер. Вызов синхронный, поэтому другая очередь может использовать такую же обёртку. Запускать её нужно после инициализации Django, с базой и настройками сайта, вне transaction.atomic() и с включённым autocommit. Вызов внутри транзакции завершается ошибкой до очистки и отправки.

Параметр mail_limit по умолчанию равен 100. Он ограничивает число захватов почтовых заданий за проход, включая отложенные и отменённые, но не объём очистки. Результат — словарь с ключами sent и removed: число сообщений, принятых бэкендом, и число удалённых истёкших неподтверждённых комментариев.

Источник состояния писем по-прежнему находится в базе Commentail: сохраняются захват заданий, проверки доступа, повторные попытки и первоначальные сроки защищённых ссылок. Задержка очереди не продлевает ссылку. Неопределённый результат отправки всё ещё может привести к повторному письму; очередь задач не даёт гарантии однократной доставки.

Выберите одно расписание раз в минуту: задачу проекта или python manage.py process_commentail. Если уже работает SMTP и минутный запуск команды, менять настройки ради этого выпуска не нужно.

Изменения формы комментария

Действие «Отменить ответ» перенесено вниз, к кнопке отправки. В обычном состоянии это компактное текстовое действие; при наведении или фокусе клавиатуры появляется фон кнопки. Сохранены отмена без полной перезагрузки, обычная навигация без JavaScript и возврат фокуса к действию «Ответить».

Гостевая форма стала компактнее: уменьшены интервалы, сокращено поле ответа на арифметическую CAPTCHA, обновление задачи расположено рядом с ним. Подсказка уточняет, что подтверждение почты происходит после отправки. Кнопка отправки использует цвета текста сайта, без жёстко заданной светлой или тёмной палитры.

Если шаблоны формы переопределены в проекте, они сохраняют приоритет. Чтобы получить новую компоновку, нужно сравнить свои commentail/form.html и commentail/captcha.html с установленной версией. Обновление пакета не переписывает шаблоны сайта.

Проверка ввода и защита ссылок в логах

Слишком длинные числовые идентификаторы в навигации и фильтрах проверяются до преобразования в число. Нулевые байты в тексте комментария и имени гостя отклоняются, как и гостевой email длиннее поля хранения. Некорректный ввод получает ошибку проверки вместо ошибки сервера или базы. При восстановлении черновика обычной HTML-формы неподдерживаемые нулевые байты убираются с сохранением остального текста.

Исправлено скрытие секретов защищённых ссылок в логах Django: оно работает и тогда, когда имя параметра с токеном записано через процентное кодирование. Логи прокси, веб-сервера и внешние системы сбора ошибок нужно настраивать отдельно.

Для этого выпуска также проверен Wagtail 8.0.1 в поддерживаемых сочетаниях с Wagtail 8; границы совместимости сохранены. Версии зависимостей тестового окружения обновлены с учётом известных уязвимостей. Эти фиксации относятся к тестовому окружению библиотеки и не заменяют управление зависимостями сайта.

Как обновиться с 1.1.0

Сначала сохраните базу, настройки, шаблоны, media, SECRET_KEY и точные версии зависимостей. Проверьте переход на восстановленной тестовой базе с локальной отправкой почты:

python -m pip install --upgrade commentail==1.2.0
python manage.py migrate
python manage.py check
python manage.py collectstatic --noinput

По сравнению с 1.1.0 новых миграций Commentail нет; у обновляемых фреймворков могут быть свои. Существующие комментарии, настройки, подписки, выданные ссылки и почтовые задания сохраняются. Сроки ссылок не продлеваются.

После сборки статики обновите кешированные ресурсы и перезапустите приложение и фоновые процессы обычным способом своего проекта. Проверьте гостевую отправку и подтверждение почты, модерацию, ответы, доступные правки и отписку. Отдельно пройдите форму с клавиатуры, без JavaScript и в используемых темах сайта. Если подключаете очередь проекта, проверьте реальный запуск задачи через её worker и уберите прежнее отдельное расписание команды.

Полный порядок перехода — в заметках к релизу, список изменений — в changelog.