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

Обзор

Adal — инфраструктура для приёма, просмотра, хранения и доставки HTTP-вебхуков. Сервис ставит наблюдаемый слой между внешним отправителем и вашим приложением: принимает запрос по постоянному публичному URL, показывает его содержимое и передаёт настроенным получателям.

Основная модель состоит из четырёх сущностей: Сервер принимает вебхук, принятый вебхук становится Запросом, Получатель задаёт цель пересылки, а Доставка связывает конкретный запрос с конкретным получателем.

Как связаны основные сущности

1. Внешний сервис отправляет вебхук на URL сервера Adal.
2. Сервер проверяет условия приёма и сохраняет принятый HTTP-запрос как Запрос Adal.
3. Для каждого настроенного получателя создаётся отдельная доставка.
4. Adal или Adal CLI выполняет попытку доставки и сохраняет её результат.
5. После временной ошибки Adal может выполнить дополнительные попытки по расписанию получателя.

Один сервер принимает много запросов. Один запрос может направляться нескольким получателям, поэтому у него может быть несколько независимых доставок. У каждой доставки — собственная история попыток и конечный результат.

Сервер (Server)

Сервер — публичная точка входа для вебхуков. У него есть постоянный региональный URL, который указывается во внешнем сервисе, например GitHub, Stripe или Telegram.

Сервер определяет:

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

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

Запрос (Request)

Запрос — запись об отдельном HTTP-запросе, поступившем на сервер Adal. Каждый принятый вебхук становится самостоятельным Запросом с собственным идентификатором, временем приёма, статусом и датой удаления.

Принятый запрос содержит данные, необходимые для просмотра и доставки:

• HTTP-метод, полный URI, путь и параметры строки запроса;
• заголовки и тело;
• время приёма, размер и технические сведения;
• связанные доставки и историю их попыток.

Принятие не равно доставке. Наличие Запроса означает, что Adal принял вебхук. Оно не означает, что какой-либо получатель уже получил или обработал его.

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

Получатель (Destination)

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

Direct HTTP

Adal отправляет запрос из своей инфраструктуры прямо на публичный HTTP- или HTTPS-адрес. Этот вариант подходит для доступного из интернета приложения и не требует запущенного Adal CLI.

Adal CLI

Adal передаёт запрос по защищённому исходящему соединению подключённому CLI, а CLI отправляет его локальному или приватному сервису. Приложению не нужен публичный IP-адрес или временный туннель.

Несколько получателей образуют fan-out: один Запрос доставляется в несколько систем. Ошибка одного маршрута не отменяет успешную доставку по другому.

Доставка и попытка доставки

Доставка описывает передачу конкретного Запроса конкретному Получателю. Попытка доставки — один фактический сетевой вызов внутри этой доставки. Первая отправка и каждый автоматический или ручной повтор сохраняются в её истории.

Для Direct HTTP запрос отправляет Adal, а для локального маршрута — подключённый Adal CLI. Получателю передаются сохранённые метод, URI, заголовки и тело запроса.

Попытка успешна, когда Adal получает HTTP-ответ со статусом 2xx . Статусы 4xx и 5xx , сетевые ошибки и тайм-ауты считаются неуспешными.

Повторная попытка и Replay

Оба действия отправляют данные снова, но работают на разных уровнях:

Автоматические повторы выполняются по настройкам каждого получателя. Ручной повтор позволяет снова выполнить конкретную доставку. Replay заново проводит сохранённый запрос через текущий маршрут сервера, например после изменения приложения или получателей.

Повтор возможен после потери ответа или тайм-аута, когда приложение уже успело выполнить действие. Поэтому повторы и Replay могут создавать дубликаты и повторные побочные эффекты; доставка «ровно один раз» не гарантируется.

Регион и срок хранения

Регион выбирается при создании сервера, входит в его публичный URL и определяет, где Adal принимает и обрабатывает запросы. Данные Запросов и Доставок остаются привязаны к выбранному региону.

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

Удаление сервера останавливает новый приём и удаляет его получателей. Уже принятые Запросы могут оставаться до своей запланированной даты удаления. Поддомен удалённого сервера не используется повторно.

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

Безопасность и граница ответственности

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

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

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

• проверять подпись или другой способ аутентификации отправителя;
• проверять формат и допустимые значения входных данных;
• быть идемпотентным и безопасно обрабатывать повторную доставку;
• удалять дубликаты по стабильному идентификатору события провайдера, если он доступен;
• вести собственные журналы, мониторинг и обработку ошибок;
• учитывать частичные сбои при fan-out и повторные побочные эффекты.

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

Краткий словарь

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

• Быстрый старт — создайте первый маршрут и отправьте тестовый вебхук.
• Серверы — URL, регионы, методы, ограничения и удаление.
• Запросы — содержимое, статусы, просмотр и Replay.
• Получатели — Direct HTTP, Adal CLI и история доставки.
• Повторные попытки — расписание, ручные действия и идемпотентность.
• Хранение данных — региональность, сроки и удаление.
• Безопасность — защита данных, соединений и учётных данных.