Свой адаптер на любом языке

​

Модель транспорта

• Платформа говорит с вашим адаптером, а не с Veriqa. Адаптер сам принимает вебхуки платформы или опрашивает её, проверяет события и сам отвечает на verification-handshake платформы. GET-маршрута для HTTP-канала Veriqa не открывает.
• Адаптер отправляет события в Veriqa на маршруты, которые есть у каждого канала: /api/channels/{channelType}/webhook или /api/channels/{channelType}/webhook/{tenant}. Событие по транзакции уходит на маршрут тенанта этой транзакции — того, что пришёл в поле tenant вызовов deep-link и send-prompt этой транзакции; null — маршрут без сегмента тенанта. Второй раз Veriqa тенанта не сообщит: связь «транзакция → тенант» храните у себя.
• Свой публичный вход адаптер защищает сам. Rate-limit Veriqa охраняет её собственные маршруты; вход, который адаптер открывает платформе, нуждается в своей защите от мусорного трафика.
• Veriqa вызывает адаптер по одному адресу, Http:BaseUrl, — за всем, что ей нужно от канала.
• Учётные данные платформы остаются у адаптера. Veriqa их не запрашивает и не хранит.
• Одна регистрация — один внешний адаптер: один адрес, один секрет транспорта, одни факты канала. Без Http:Tenant она обслуживает всех тенантов установки. Тенант со своей реализацией получает свою регистрацию под своим именем (например shop-a-zalo), и Http:Tenant называет этого тенанта.
• Стандартный образ Veriqa регистрирует HTTP-каналы всегда: канал добавляется переменными окружения и перезапуском контейнера, без пересборки образа. Embedded-хост подключает пакет Veriqa.Core.ChannelAdapter.Http и добавляет один вызов:

authServer.AddChannelAdapters(adapters => adapters.AddHttpChannels());

​

Конфигурация

{
  "Veriqa": {
    "Channels": {
      "acme-chat": {
        "InboundVerification": "signature",
        "Http": {
          "BaseUrl": "https://acme-adapter.internal/",
          "DisplayName": "Acme Chat",
          "Capabilities": {
            "SupportsInChannelConfirmation": true,
            "DeliversOutcomeNotice": true
          }
        }
      }
    }
  }
}

Veriqa__Channels__acme-chat__InboundVerification=signature
Veriqa__Channels__acme-chat__Http__BaseUrl=https://acme-adapter.internal/
Veriqa__Channels__acme-chat__Http__TransportSecret=whsec_<base64 от 24–64 случайных байт>
Veriqa__Channels__acme-chat__Http__Capabilities__SupportsInChannelConfirmation=true

• Факты канала и кнопку задаёт оператор — ключами Http:Capabilities:* (по ключу на свойство ChannelCapabilities), Http:DisplayName и Http:IconSvgPath. Сетевого манифеста нет: Veriqa не спрашивает адаптер, что он умеет. Незаданный факт получает безопасное умолчание ChannelCapabilities — все булевы false, единственный вид контента plain_text, своего правила об эмодзи у канала нет (RendersEmoji не задан), номера телефона канал не даёт (Номер телефона).
• Http:Tenant называет тенанта-владельца регистрации. Она обслуживает только его; у остальных тенантов этого канала нет — ни на входящем маршруте, ни в событиях, ни в исходящих вызовах. Ключ не задан — регистрация обслуживает всех тенантов установки.
• Http:AdapterSettings — непрозрачная строка до 8192 символов, которую Veriqa пересылает дословно в каждом вызове и никогда не читает. У неё уровни ядра и тенанта; значение тенанта заменяет значение ядра целиком.
• Http:AllowInsecureHttp разрешает базовый URL со схемой http. Только для изолированной внутренней сети (соседний контейнер); при старте Veriqa пишет предупреждение.
• Все значения Http:* фиксируются на старте, кроме Http:AdapterSettings, который резолвится на каждый вызов. Остальные меняются только перезапуском.
• Имя канала — в формате из раздела Имя канала, а имена каналов поставки Veriqa зарезервированы, даже если встроенный канал в хост не подключён: max, telegram, whatsapp, email, instagram, messenger, wechat, viber. Резерв растёт с выходом новых встроенных каналов.
• Ошибка конфигурации, найденная на старте, останавливает его с сообщением, называющим ключ или секцию канала, — например: базовый URL не задан или не абсолютный, базовый URL со схемой http без Http:AllowInsecureHttp, не задан Http:TransportSecret, секрет не в форме whsec_, один секрет у двух регистраций, запрещённая схема deep link, таймаут не в форме hh:mm:ss, Http:AdapterSettings длиннее 8192 символов, зарезервированное имя или имя, которое уже занято другим каналом хоста. Пустой Http:Tenant — тоже ошибка: чтобы обслуживать всех тенантов, ключ удаляют.

​

Номер телефона

"Capabilities": {
  "SupportedMessageKinds": [ "plain_text", "phone_number_request" ],
  "PhoneNumber": {
    "Acquisition": [ "OnRequest" ],
    "Proof": "Proven"
  }
}

Veriqa__Channels__acme-chat__Http__Capabilities__SupportedMessageKinds__0=plain_text
Veriqa__Channels__acme-chat__Http__Capabilities__SupportedMessageKinds__1=phone_number_request
Veriqa__Channels__acme-chat__Http__Capabilities__PhoneNumber__Acquisition__0=OnRequest
Veriqa__Channels__acme-chat__Http__Capabilities__PhoneNumber__Proof=Proven

​

Старт по коду

"Capabilities": {
  "CodeStart": {
    "LinkCarriesTransaction": false,
    "MessageTemplate": "/veriqa {code}"
  }
}

Veriqa__Channels__acme-chat__Http__Capabilities__CodeStart__LinkCarriesTransaction=false
Veriqa__Channels__acme-chat__Http__Capabilities__CodeStart__MessageTemplate="/veriqa {code}"
Veriqa__Channels__acme-chat__Http__UnmatchedCodeReplyText=<Natural Key вашего ответа>

​

Wire-контракт

• Коды ошибок. Коды, которые называет провод, — в схеме, и любой другой код тоже принимается. Код error пишется в лог и больше ничего не решает, за одним исключением: channel_cannot_continue в ответе на send-prompt сразу завершает транзакцию отказом. Любой другой error действует по своей операции, и после него вызов не повторяется:
  • send-prompt — транзакция остаётся открытой и ждёт нового auth_start пользователя или истечения срока;
  • deep-link — у пользователя нет входа в ваш канал: страница входа рисуется без него;
  • send-message, report-outcome — отказ пишется в лог и учитывается в метриках, и только.
• deep-link идемпотентен: повторный вызов по той же транзакции возвращает тот же url и не создаёт нового состояния.
• У ответа есть границы. Ответ читается не более 1 МБ и сверх лимита отвергается, редиректы не выполняются, deep link принимается только абсолютным URI со схемой https или из Http:DeepLinkSchemes, не длиннее 2048 символов.
• Таймауты и повторы. Попытка ждёт Http:OperationTimeout (по умолчанию 10 с); deep-link — Http:DeepLinkTimeout (2 с), потому что стоит на пути страницы входа. send-prompt, send-message и report-outcome повторяются при транспортном отказе — нет соединения, таймаут, 5xx, 429 — до трёх раз, все попытки в пределах Http:RetryBudget (20 с). Больше не повторяется ничего: 200 с error, 3xx, прочие 4xx, слишком большой или некорректный ответ. deep-link и health — одна попытка.
• Второе действие запроса номера возвращается одним из двух способов — тем, который позволяет платформа: событием phone_step_action либо событием unaddressed, чей text равен подписи второй кнопки. Незнакомый Veriqa action делает событие unrelated. На саму кнопку «поделиться» отвечает phone_shared.
• Номер телефона в идентичности. identity.phone_number любого события принимается как номер пользователя — это способ «автоматически», — а identity.phone_number_verified: true — только в пределах Proof, объявленного регистрацией (см. Номер телефона).
• auth_start_by_code уходит на тот маршрут, что и прочие события вашего бота. Транзакции оно не называет, поэтому правило тенанта транзакции к нему неприменимо: Veriqa ищет код по всей установке, на какой бы маршрут ни пришло событие, и берёт тенанта с найденной транзакции.
• Отвергайте конверт события на входе вызовов. Тело с event вместо operation, пришедшее на Http:BaseUrl, — ваше же событие, отражённое обратно; ответ на него — что угодно, кроме 200 с result.
• Обслуживайте вызовы, пока открыт свой запрос. На auth_start Veriqa шлёт адаптеру send-prompt до того, как ответит на ваш POST события. Адаптер, который не умеет принимать вызовы параллельно со своими запросами в Veriqa, получает таймаут вопроса, и транзакция ждёт истечения срока.

​

Подпись

• Ротация без простоя. Новый секрет — в Http:TransportSecret, старый — в Http:PreviousTransportSecret: отправитель ставит обе подписи, получатель принимает любую. Пока предыдущий секрет задан, Veriqa пишет при старте предупреждение.
• Ответы не подписываются: их подлинность держится на соединении, которое Veriqa открыла по настроенному адресу, — поэтому по умолчанию требуется https.
• Неверная подпись — 403, без конверта и без какого-либо эффекта, в обе стороны: так Veriqa отвечает на ваше событие без подписи или с неверной подписью, и так же обязан отвечать на такой вызов ваш адаптер.
• У каждой регистрации свой секрет. Общий секрет позволил бы одной регистрации выдать себя за другую, поэтому хост не стартует.

​

Идемпотентность

• webhook-id вызовов send-prompt, send-message и report-outcome — ключ идемпотентности. Повтор с ключом, который вы уже успешно обслужили, ничего нового не отправляет и возвращает результат первого вызова — ту же ссылку на сообщение. У deep-link и health webhook-id уникален, но ключом не является.
• webhook-id события выбираете вы: уникальный на событие и неизменный при повторной доставке того же события. Из него Veriqa строит ключи вызванных событием send-prompt и report-outcome, поэтому повторно доставленное событие не задаёт вопрос дважды.
• Неуспешная попытка ключ не связывает: следующая попытка с ним обслуживается заново.
• Срок хранения выбирает оператор адаптера, с двумя нижними границами: не меньше бюджета повторов Veriqa (Http:RetryBudget), а для ключа, рождённого событием, — ещё и не меньше окна, в котором сам адаптер может доставить это событие повторно.

​

Версия провода и статус preview

​

Conformance-набор

• вызовы через настоящую обёртку — каждую операцию, повтор с тем же ключом, неверный секрет и метку времени вне окна. Эти вызовы делает тот самый код HTTP-канала, что работает в Veriqa, поэтому набор не может разойтись с Veriqa;
• некорректные вызовы, которых Veriqa не делает, — без подписи, с незнакомыми полем, вариантом или операцией, чужой мажорной версии, конверт события, отражённый на вход вызовов, — их шлёт отдельный отправитель;
• приёмник событий — он играет Veriqa для ваших событий: проверяет подпись и схему каждого, вызывает send-prompt до ответа на auth_start и проверяет, что каждое событие пришло на маршрут тенанта своей транзакции.

docker build -f src/core/Veriqa.Core.ChannelAdapter.Http.Conformance/Dockerfile -t veriqa-http-channel-conformance .

​

Референсные адаптеры

• samples/python/custom-channel-telegram/ — Telegram на Python;
• samples/node/custom-channel-whatsapp-twilio/ — WhatsApp через Twilio на Node;
• samples/node/custom-channel-whatsapp-baileys/ — WhatsApp через Baileys на Node — рабочий адаптер для отладки, небольших команд и собственного использования; номер при этом могут заблокировать.

cp .env.example .env    # заполните секрет транспорта и креды платформы
docker compose up

​

InboundVerification внешнего адаптера