Генерация видео через API: dead-letter очередь задач

Dead-letter очередь помогает приложению отдельно хранить задачи, которые не удалось безопасно обработать в обычной очереди. Для генерации видео это особенно важно: запрос может выполняться долго, а потеря ответа не означает, что внешняя операция не была создана. Прежде чем повторять отправку, установите состояние задачи и возможность идемпотентного повтора по договорённому контракту.

RussiaAPI — независимый сторонний API gateway, а не официальный сервис поставщиков моделей. Очередь ниже принадлежит вашему приложению: статья не утверждает, что gateway поддерживает DLQ, конкретные коды, отмену, возврат средств или сохранение результатов. Проверяйте доступные функции и условия в текущем договоре и документации.

Что отправлять в отдельную очередь

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

В DLQ передавайте локальный ID, категорию, число попыток, время последней попытки и ссылку на защищённую запись. Не помещайте туда prompt, подписанный URL, токены, заголовки, исходные изображения или персональные данные. Доступ, срок хранения и удаление определяются политикой вашей организации и договором. Документация Amazon SQS описывает общий механизм DLQ; особенности выбранной вами очереди необходимо проверить отдельно.

Состояние и дедупликация

До отправки создайте локальную запись с уникальным ID и сохраните намерение выполнить операцию. Если контракт поддерживает ключ идемпотентности, используйте его именно в предусмотренной форме и проверьте срок действия. В противном случае не придумывайте гарантию: после неизвестного исхода может потребоваться ручная сверка. Повторная отправка без такой проверки способна создать вторую задачу и дополнительные расходы.

Состояния вашего приложения могут быть «готова», «отправка», «неизвестный исход», «ожидание результата», «проверка человеком» и «завершена». Это внутренние категории, а не перечень статусов поставщика. Сопоставление с реальным ответом должно находиться в адаптере и опираться на проверенный контракт.

Пример локальной классификации

Этот пример Node.js не выполняет сетевых запросов и не моделирует конкретные коды поставщика:

function classify({ validInput, outcomeKnown, retrySafe, attempts }) {
  if (!validInput) return 'fix_input';
  if (!outcomeKnown) return 'reconcile';
  if (retrySafe && attempts < 3) return 'retry_with_backoff';
  return 'manual_review';
}
console.log(classify({ validInput: true, outcomeKnown: false, retrySafe: false, attempts: 1 }));

Число попыток здесь условное. В production задайте его по риску, текущим лимитам и бюджету, используйте задержку с jitter и сохраняйте общее ограничение времени. retrySafe должен определяться вашим контрактом и состоянием операции, а не только типом ошибки.

Процесс ручной проверки

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

Протестируйте падение worker до отправки и после неё, повторную доставку сообщения, просроченную ссылку на результат и отказ очереди. Проверьте, что никакой тест не использует реальные ключи или не создаёт платные задачи. Зафиксируйте наблюдения и версию контракта, а не обещайте поведение внешней системы по результатам одного прогона.

Контракт между worker и очередью

Разделите сообщение очереди и защищённую запись задания. В сообщении достаточно локального идентификатора и версии схемы; worker получает остальные разрешённые данные из хранилища с проверкой прав. Это упрощает ограничение доступа и не распространяет входные материалы по нескольким журналам. Если для расследования нужны дополнительные сведения, определите их перечень и срок хранения с владельцем данных заранее.

До запуска проверьте особенности выбранной очереди: срок видимости сообщения, повторную доставку, правила удаления и порядок сообщений. Эти свойства отличаются у разных систем. В частности, документация Amazon SQS предупреждает, что применение DLQ может нарушить точный порядок операций FIFO. Если последовательность кадров или операций важна, проектируйте обработку зависимостей отдельно и не переносите свойства SQS на другие продукты.

Пример жизненного цикла задачи

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

Если ответ об успешном создании получен, приложение связывает локальную запись с разрешённым внешним идентификатором и ожидает результат по подтверждённому контракту. Если соединение оборвалось в момент отправки, исход неизвестен: worker не должен считать, что задача не создана. Сверка состояния возможна только при наличии документированного способа; иначе случай передаётся человеку. Локальный ID сам по себе не гарантирует идемпотентность на внешней стороне.

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

Повторы, пределы и наблюдаемость

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

Следите за числом сообщений в DLQ, возрастом ожидающих случаев и долей неизвестных исходов. Настройте уведомление ответственному сотруднику и проверяйте не только размер очереди, но и возможность восстановить ход обработки по локальному ID. Эти метрики не должны включать prompt, секретные ссылки или персональные данные. Условия удаления и доступа определяются политикой организации и выбранной системой.

Как безопасно вернуть задачу в работу

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

Разделите инцидент и повторную обработку

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

FAQ

DLQ автоматически исправляет задачу?

Нет. Она выделяет неуспешные случаи для контролируемого разбора; автоматический повтор требует отдельной проверки безопасности и условий контракта.

Что делать после таймаута отправки?

Сначала считайте исход неизвестным. Если интерфейс предоставляет способ сверки, проверьте состояние; иначе направьте задачу на ручное решение.

Нужно ли хранить ссылки на видео в очереди?

Обычно достаточно локальной ссылки на защищённую запись. Подписанные URL и секреты не следует помещать в обычные сообщения очереди или логи.

Следующий шаг

Прочитайте про очередь задач видео API и DLQ для video webhook. В RussiaAPI проверьте доступные маршруты и условия до интеграции.