Задания Cron в Orbit

Задания cron планируют повторяющиеся HTTP-запросы к развёрнутому проекту, так что ночная очистка, почасовая синхронизация или еженедельный дайджест выполняются вовремя без необходимости запускать отдельный планировщик.

Где находятся задания Cron

Откройте Orbit, нажмите на проект и выберите Crons в группе Configure на вкладке проекта. На странице, названной Cron jobs, описывается её назначение: планирование HTTP-запросов к развёрнутому проекту с использованием стандартного пятипольного синтаксиса cron в UTC или сокращений @hourly, @daily, @weekly и @monthly.

На странице показан Target host, на который будет выполнен вызов, чтобы вы могли с первого взгляда подтвердить, что он указывает на правильное развёртывание.

Как это работает

Orbit не запускает ваш код в планировщике. Он вызывает URL на вашем проекте по расписанию, и ваш код выполняет работу.

Это означает, что объект, который вы планируете, является обычным маршрутом в вашем приложении, например /api/cron/cleanup. Всё, что ваше приложение может сделать в ответ на запрос, оно может сделать по расписанию.

Создание задания Cron

1. Нажмите New cron.
2. Дайте ему Name (название) длиной до 120 символов.
3. Установите Path на вашем проекте, начиная с косой черты.
4. Выберите Schedule (расписание) из предустановок или введите выражение.
5. Выберите Method (метод). GET является значением по умолчанию.
6. Добавьте Request body (тело запроса), если метод является POST, PUT или PATCH.
7. Установите Timeout (тайм-аут) между 1 и 300 секундами. По умолчанию 30.
8. Оставьте опцию Generate a Bearer secret отмеченной, если у вас нет собственной аутентификации.
9. Нажмите Create cron.

Предустановки расписания

Или напишите своё пятипольное выражение: минута, час, день месяца, месяц, день недели.

Аутентификация вызова

Если оставить опцию Bearer secret отмеченной, генерируется случайный токен, отправляемый в виде заголовка Authorization при каждом выполнении. Он отображается один раз сразу после создания с примечанием, что больше не будет показан.

Скопируйте его и проверьте его в своём обработчике:

export async function GET(req) {
  const auth = req.headers.get('authorization');
  if (auth !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response('Unauthorized', { status: 401 });
  }
  // do the work
}

Сохраните секрет, используя переменные окружения проекта: см. Переменные окружения в Orbit.

Вы также можете отправить свои собственные заголовки вместо этого, если ваше приложение уже имеет схему аутентификации.

Чтение списка заданий

Каждое задание показывает:

• Schedule (расписание), выражение, по которому оно выполняется.
• Next (далее), когда оно будет выполнено в следующий раз.
• Last (последний), когда оно последний раз выполнялось и как это прошло.
• Счётчик ok / fail (успешно / неудачно).
• Last error (последняя ошибка), где последний сбой оставил сообщение.
• Значок PAUSED (пауза), когда оно отключено.

Четыре действия находятся в каждой строке: Run now (запустить сейчас), Pause (пауза) или Resume (возобновить) и Delete (удалить).

Run now выполняет задание немедленно, независимо от его расписания, и сообщает результат. Это правильный способ протестировать новое задание, а не ждать следующего срабатывания.

Результаты выполнения

Каждое выполнение записывается со статусом, кодом ответа, длительностью, ошибкой и тем, что его вызвало, поэтому задание, которое периодически завершается с ошибкой, оставляет след, который вы можете прочитать, а не единственное "последняя ошибка".

Выбор тайм-аута

Тайм-аут относится к каждому выполнению, между 1 и 300 секундами, по умолчанию 30.

Установите его немного выше реального наихудшего случая работы, но не намного выше. Щедрый тайм-аут для задания, которое зависло, означает пять минут ожидания разработчика без движения. Жёсткий тайм-аут для задания, которое легитимно занимает две минуты, означает постоянный сбой и вводящее в заблуждение предупреждение.

Ещё лучше держите обработчик быстрым: пусть он ставит в очередь работу и возвращает немедленно, вместо того чтобы выполнять работу встроенной. Задание cron, которое возвращается за 200 миллисекунд, никогда не превышает тайм-аут.

Ограничения

Проект может содержать до 50 заданий cron. Это за проект, поэтому учётная запись с несколькими проектами имеет больше в итоге.

Если вам нужно что-то планировать для стадии тестирования вместо боевой версии, используйте Cron triggers в Settings. Эта карточка позволяет выбрать окружение и ограничена десятью триггерами на проект. См. Параметры проекта Orbit.

Удаление задания

Нажмите Delete и подтвердите. Подтверждение отмечает, что история выполнения также будет удалена, поэтому если вы хотите иметь запись о том, как работало задание, запишите её перед удалением.

Приостановите, а не удаляйте, когда вы временно останавливаете задание. Приостановка сохраняет конфигурацию, секрет и историю нетронутыми.

Практические рекомендации

Сделайте обработчики идемпотентными. Вызов cron может быть повторён, и Run now может быть нажата, пока плановое выполнение уже выполняется. Ваш обработчик должен справляться с выполнением дважды без выполнения работы дважды.

Не планируйте всё на час. 0 * * * * для каждого задания означает, что каждое задание конкурирует в один и тот же момент. Распределите их: 7 * * * *, 23 * * * * и так далее.

Записывайте внутри вашего обработчика. Запись о выполнении показывает вам код ответа и длительность. То, что на самом деле произошло, - это бизнес вашего приложения, и вам это понадобится, когда задание молча ничего не делает.

Устранение неполадок

Каждое выполнение FAILED с кодом 401. Ваш обработчик отклоняет запрос. Проверьте, совпадает ли секрет, хранящийся в переменных окружения, с сгенерированным здесь, включая префикс Bearer при сравнении.

Каждое выполнение FAILED с кодом 404. Путь не существует в развёрнутом проекте. Протестируйте его в браузере для целевого хоста, показанного на странице.

Выполнения TIMEOUT. Обработчик выполняет слишком много встроенным образом. Разделите работу или увеличьте тайм-аут, если работа действительно занимает столько времени и это не цикл без выхода.

Next никогда не меняется. Задание приостановлено. Ищите значок PAUSED.

Задание выполняется в неправильное время. Проверьте UTC относительно вашего локального времени. Это наиболее распространённый сюрприз с плановыми заданиями.

Куда идти дальше

• Переменные окружения в Orbit для хранения секрета cron.
• Параметры проекта Orbit для триггеров cron для каждого окружения.
• Вебхуки Orbit для получения уведомлений при возникновении проблем.