Requests в Adal

Обзор

Request — это один HTTP-запрос, полученный Adal Server. Каждый принятый вебхук становится отдельным Request. Постоянно сохранённый Request можно изучить в разделе Requests, а временный Request существует только в памяти во время автоматического жизненного цикла Delivery.

Adal сохраняет полученные HTTP-метод, URI, путь, строку запроса, заголовки и тело без скрытого преобразования содержимого. Request описывает, что получил Server; Delivery отслеживает отправку этого Request в один Destination. У одного Request может быть несколько независимых Deliveries с разными результатами.

Важно: Request подтверждает, что Adal принял вебхук. Успешный Delivery подтверждает, что Adal получил ожидаемый HTTP-ответ от Destination. Ни одно из этих событий не доказывает, что Destination завершил бизнес-операцию.

Жизненный цикл Request

1. Внешний сервис отправляет HTTP-запрос на URL Server.

2. Server проверяет метод, общий размер, доступные кредиты и другие правила приёма.

3. Каждый принятый вебхук становится Request в регионе Server и согласно текущей модели оплаты использует один кредит.

4. Adal создаёт независимый Delivery для каждого настроенного Destination.

5. Adal фиксирует каждую попытку и может запланировать автоматический повтор согласно конфигурации Destination.

6. При постоянном хранении данные Request и история доступны до запланированной даты удаления. При временной доставке Request находится в памяти Redis только до завершения всех Destinations или более раннего истечения временного retention.

Server без Destinations всё равно может принимать Requests для просмотра при включённом постоянном хранении, но автоматические Deliveries не создаются. В режиме временной доставки отсутствие Destinations означает, что работы Delivery нет, поэтому принятый Request удаляется из памяти сразу после обработки приёма. Отклонённый запрос не проходит этот цикл: у него нет Deliveries, а Adal сохраняет только минимальные диагностические данные.

Данные Request

В режиме постоянного хранения Adal сохраняет в региональной базе данные, необходимые для просмотра и Delivery, а тело помещает в региональное хранилище Cloudflare R2:

• HTTP-метод;

• полный URI, путь и строку запроса;

• заголовки и тело;

• отдельные размеры URI, заголовков и тела, а также общий размер;

• IP-адрес отправителя;

• время получения и запланированную дату удаления;

• Server и регион, принявшие Request;

• статус Request и связанные Deliveries;

• технические идентификаторы, связывающие записи.

Общий размер, сравниваемый с применимым ограничением, рассчитывается так:

Версия HTTP не хранится как отдельное поле Request. Переданный User-Agent остаётся доступен в заголовках. В обзоре также показывается Content-Type, но он описывает лишь формат, заявленный отправителем, и не доказывает, что тело является корректным JSON, XML, набором полей формы, текстом или другим заявленным форматом.

Adal не дополняет Request бизнес-данными и не исправляет некорректное содержимое. Проверяйте формат и смысл в приложении Destination.

В режиме временной доставки Adal не записывает эти данные Request или состояние Delivery в базу данных либо R2. Полный Request временно находится в памяти Redis только для автоматических Deliveries и повторных попыток.

Принятые и отклонённые Requests

Принятый Request прошёл проверки Server и аккаунта, использует один кредит и создаёт Deliveries для текущих Destinations Server. Сохранение его содержимого и истории зависит от выбранного режима.

Общий статус Request рассчитывается по всем связанным Deliveries:

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

Для отклонённого Request Adal сохраняет только минимальную диагностическую информацию: метод, время получения, причину отклонения, а также необходимые технические идентификаторы или рассчитанные счётчики. URI, путь, строка запроса, заголовки, тело, заявленный тип содержимого, IP-адрес отправителя и данные Delivery не сохраняются.

У отклонённых Requests нет Deliveries, их нельзя отправить через replay, они не используют кредиты, а отброшенное содержимое невозможно восстановить позднее.

Просмотр Request

Откройте Requests и выберите запись. Страница разделяет полученные HTTP-данные, состояние Request и технические идентификаторы.

Full URI содержит путь и строку запроса, а Path — только путь. Значения после ? также разбираются в панели параметров запроса. Размеры URI, заголовков и тела показаны отдельно; Total size является их суммой.

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

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

Deliveries и история попыток

Сводка Delivery перечисляет все Deliveries, связанные с Request. Если Delivery не был создан, страница показывает пустое состояние; это ожидаемо, когда у Server нет Destinations или запрос был отклонён.

Каждый Delivery отслеживается независимо. Request остаётся в статусе delivering, пока хотя бы один маршрут активен. Когда все маршруты получают окончательный результат, общий статус становится success, partial или failed.

Для временного Request успешный Delivery в один Destination не удаляет Request, пока в другом Destination ещё ожидается попытка или повтор. Adal удаляет полный Request и его временное состояние Delivery только после успеха или исчерпания попыток во всех Destinations, если раньше не истёк временный retention. Если он истёк первым, все незавершённые Deliveries и повторы прекращаются.

Любой ответ 2xx означает успешный Delivery. Ответы 4xx и 5xx, тайм-ауты и сетевые ошибки считаются неудачными и могут вызвать автоматический повтор согласно конфигурации Destination.

Подробности Delivery могут содержать:

• текущий статус и время создания;

• номер текущей или последней попытки;

• статус ответа или зафиксированную ошибку;

• продолжительность и время с момента получения Request;

• исходный Request и Destination;

• URL и метод Delivery;

• время и результат каждой попытки.

Adal не хранит заголовки или тело ответа Destination. Используйте результат, время и диагностические сведения вместе с собственными логами приложения Destination.

Ручной повтор снова отправляет постоянно сохранённый Request в один выбранный Destination. Он не создаёт новый Request и не влияет на другие маршруты. Согласно текущей модели оплаты ручной повтор использует один дополнительный кредит, автоматические повторы — нет. После удаления временного Request ручной повтор недоступен.

Replay Request

Replay создаёт новый Request из сохранённого и снова отправляет его через текущий процесс Server.

Для Replay требуется постоянное хранение. После завершения in-memory жизненного цикла временный Request нельзя использовать для Replay.

• исходный Request не изменяется;

• новый Request хранится отдельно и ссылается на исходный;

• Adal использует Destinations, настроенные для Server в момент replay;

• новый Request получает собственные Deliveries и историю попыток;

• согласно текущей модели оплаты replay использует один кредит;

• replay доступен только пока необходимые исходные данные хранятся в Adal.

Replay может повторить необратимый побочный эффект. До запуска оцените последствия и убедитесь, что все затронутые обработчики безопасно выполнять повторно.

Дубликаты и идемпотентность

Автоматические и ручные повторы могут доставить один Request несколько раз. Replay создаёт новый Request в Adal, но он может представлять то же событие провайдера. Adal не предоставляет exactly-once delivery.

Destination можно настроить на получение заголовка идемпотентности Adal:

Deliveries и повторы одного Request используют одинаковый ключ Adal. Replay создаёт новый Request с новым ключом, поэтому один этот заголовок не позволяет обнаружить то же событие провайдера после replay.

Обработчики Destination должны:

• проверять подпись отправителя и валидировать все входные данные;

• быть идемпотентными;

• использовать стабильный идентификатор события провайдера для устранения дублей, если он доступен;

• сохранять идентификатор события атомарно с бизнес-операцией;

• возвращать 2xx только после принятия ответственности за обработку.

Retention и удаление

Постоянно сохраняемые Requests хранятся ограниченное время, определяемое планом и конфигурацией Server. Retention начинается при приёме Request, а в его подробностях указывается запланированная дата удаления, если это применимо.

После окончания retention Adal безвозвратно удаляет сохранённое содержимое Request и связанные данные Delivery. Request больше нельзя просмотреть, восстановить, отправить вручную или через replay.

Для временной доставки retention — максимальный срок работы in-memory процесса. Adal удаляет Request раньше, как только Deliveries во все Destinations успешны или исчерпали попытки. Если срок истекает первым, оставшаяся работа прекращается. Временные Requests не записываются в базу данных, R2, резервные копии или обычные журналы приложения.

Удаление Server останавливает приём новых запросов и запускает безвозвратное удаление его Destinations, ранее принятых Requests, сохранённого содержимого, метаданных, истории Delivery и данных Replay. Обычно удаление завершается быстро, но при большом количестве Requests может занять несколько секунд. Requests не сохраняются до индивидуальных запланированных дат удаления и не могут быть восстановлены.

Важно: Используйте собственные базы данных, журналы приложения, резервные копии и механизмы восстановления для долгосрочного хранения бизнес-данных. Retention Requests в Adal является временным и зависит от плана.

Безопасность Requests

Любой, кто знает публичный URL Server, может отправить на него запрос. Наличие Request и успешный Delivery не доказывают подлинность отправителя или безопасность содержимого.

• проверяйте подписи вебхуков согласно актуальной документации провайдера;

• разрешайте на Server только ожидаемые HTTP-методы;

• валидируйте структуру, типы, размеры, тип содержимого и допустимые значения;

• не считайте одни лишь заголовки или IP-адрес отправителя доказательством подлинности;

• обеспечивайте идемпотентность и учитывайте дубли событий;

• защищайте URL Server, доступ к панели управления, токены и учётные данные Destination;

• выбирайте подходящие регион и срок retention;

• не помещайте полные данные Request в обычные логи, аналитику, уведомления и отчёты об ошибках.

Некоторые схемы подписи требуют точного исходного тела. Если провайдер требует этого, проверяйте подпись по исходным байтам до разбора или повторной сериализации payload.

Adal шифрует чувствительные данные Requests при хранении и использует защищённые соединения при передаче, но не заменяет аутентификацию, авторизацию, валидацию и контроль доступа в вашем приложении.

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

Request не появился в панели управления

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

Request отклонён

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

Request принят, но Delivery отсутствует

Убедитесь, что у Server есть Destination. Проверяйте каждый маршрут независимо: прямой HTTP-сервис может быть недоступен, а маршрут Adal CLI — ожидать подключения.

Тело отличается от ожидаемого

Сравните Content-Type, сохранённое тело, кодировку и документацию провайдера. Adal сохраняет полученные данные, но не гарантирует, что отправитель сформировал корректное содержимое заявленного формата.

Adal показывает успех, но операция не выполнена

Результат 2xx означает, что Adal получил ожидаемый HTTP-ответ. Проверьте состояние и логи приложения Destination: его внутренняя транзакция, очередь или последующая обработка всё ещё могут завершиться ошибкой.

Событие обработано дважды

Проверьте автоматические и ручные повторы, а также replay. Устраняйте дубли по стабильному идентификатору события провайдера. Ключ идемпотентности Adal позволяет распознать повторный Delivery одного Request, но меняется при создании нового Request через replay.

Связанные страницы

• Servers

• Основные понятия

• Destinations

• Повторные попытки Delivery

• Хранение данных и retention

• Adal CLI