Looking Glass
Looking Glass предоставляет два независимых вида измерений:
- Ручные Ping, Traceroute и MTR: из выбранной локации к вашему публичному IP-адресу или домену.
- Задержка HTTPS: напрямую из браузера посетителя до локации. Это время обмена по HTTPS, а не ICMP ping.
Получение точек
Вызывайте GET /looking-glass/points с вашего backend, передавая X-Api-Key и api_key_id. Применяется белый список IP интеграции. Необязательный location_id фильтрует список; при отсутствии совпадений возвращается пустой список.
Точка содержит ID, локацию, страну, город, публичные тестовые IP, ipv4_enabled, ipv6_enabled, доступные checks и три nullable URL задержки. Используйте ответ реестра, не фиксированный список локаций или адресов.
Отключённые точки остаются в списке. Наличие IP не означает разрешение диагностики. Назначение URL:
| Поле | Назначение |
|---|---|
latency_url | Основной замер; при двух включённых семействах браузер выбирает семейство. При одном включённом возвращается его URL. |
latency_ipv4_url | Замер только по IPv4. |
latency_ipv6_url | Замер только по IPv6. |
Отключённое семейство или ненастроенный hostname дают null. Отсутствие IPv6 у посетителя не означает недоступность локации по IPv4.
Ручная проверка
Вызывайте POST /looking-glass/check только при запуске диагностики пользователем:
curl --request POST 'https://cloud-api.adaptgroup.pro/looking-glass/check' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--max-time 60 \
--data '{"api_key_id":1,"point_id":1,"type":"ping","family":4,"target":"1.1.1.1"}'
type — ping, traceroute или mtr; family — целое число 4 или 6. Цель — публичный числовой IP или домен без протокола, порта, пути и параметров. Числовой IP должен соответствовать выбранному семейству. DNS разрешается в выбранной локации. Внутренние и инфраструктурные адреса, включая домены, которые в них разрешаются, запрещены.
Вызов синхронный. Установите таймаут HTTP-клиента 60 секунд. Не повторяйте запрос автоматически после обрыва или HTTP 504: команда могла выполниться. Маршрут не использует Idempotency-Key.
Ответ содержит фактически проверенный IP в target, код команды return_code, timed_out, длительность выполнения duration_ms и output. Длительность выполнения — не задержка сети. Вывод Ping и Traceroute — текст, MTR — JSON-строка. Обрабатывайте ошибку разбора JSON и сохраняйте текстовый вариант отображения. Вывод вставляйте как текст, не HTML.
HTTP 200 может содержать ненулевой код команды или неполный результат: timed_out=true, return_code=null. Звёздочки в трассировке, неполученные ICMP-ответы и ненулевой код не доказывают недоступность всей локации.
Лимиты и ошибки
Квоты ручных проверок независимы для каждой интеграции. Лимиты частоты используют скользящее окно 60 секунд; все ограничения действуют одновременно:
| Область | Проверок в минуту | Одновременно |
|---|---|---|
| API-интеграция, все точки | 300 | 4 |
| Интеграция + IP источника | 30 | 2 |
| Интеграция + нормализованная цель | 60 | — |
| Интеграция + точка | 120 | 2 |
Каждая региональная точка дополнительно ограничивает интеграцию до 120 проверок в минуту, а интеграцию + фактически разрешённый IP цели — до 60 в минуту. Разные домены, разрешающиеся в один IP, делят эту квоту цели. IPv6 источника группируется по /64 внутри интеграции. При запросах через ваш backend посетители делят лимит его IP по всем локациям внутри вашей интеграции. Другая интеграция с тем же IP имеет собственную квоту. Произвольные поля client_ip и api_id не принимаются.
Точка выполняет до четырёх проверок одновременно, не более двух от одной интеграции. При занятых слотах запрос ожидает до пяти секунд в очереди, которая обслуживает интеграции по раундам. От одной интеграции допускается не более двух ожидающих запросов на точку. Ожидание и отказ не расходуют квоту частоты; она списывается при допуске к выполнению. Мощность общая, поэтому квота не гарантирует 300 завершённых проверок в минуту. Заполненная очередь или истёкшее ожидание возвращают HTTP 429 с Retry-After: 60. Запрос остаётся синхронным и не возвращает ID задания; после завершения ожидающего запроса проверка из очереди не запускается в фоне.
| HTTP | Код / значение |
|---|---|
| 401 | Неверная авторизация Cloud API. |
| 403 | ip_not_allowed: IP источника не входит в белый список интеграции. |
| 404 | lg_point_not_found: неизвестная точка. |
| 409 | lg_point_disabled: точка или семейство отключены. |
| 422 | Ошибка валидации запроса или lg_invalid_target: запрещённая цель либо ошибка DNS. |
| 429 | lg_rate_limited: исчерпана личная квота, недоступна мощность точки, очередь заполнена или время ожидания истекло. Учитывайте Retry-After, сейчас 60 секунд. |
| 502 | lg_agent_unavailable: точка недоступна или вернула некорректный результат. |
| 503 | lg_unavailable: сервис недоступен; lg_client_ip_unavailable: не удалось определить IP источника. |
| 504 | lg_timeout: результат диагностики не получен до истечения ожидания. |
После 429 не запускайте цикл автоматических повторов. Разрешите новую проверку по действию пользователя после Retry-After. API не кеширует результаты диагностики и не хранит их историю.
Задержка HTTPS из браузера
Ваш backend передаёт список точек на frontend. Браузер обращается к URL задержки напрямую, без API-ключа и cookies. Если проксировать запрос через backend, измерится его соединение вместо соединения посетителя.
- Один цикл при открытии страницы, не более трёх локаций одновременно. Пропускайте отключённые точки и
nullURL. - Для каждой локации выполните один прогрев, затем пять последовательных замеров. Прогрев исключите: он может включать DNS/TCP/TLS.
- Таймаут каждого запроса — три секунды. Показывайте медиану при минимум трёх успешных замерах, иначе — «Замер недоступен».
- При HTTP 429 остановите замер точки и покажите «Повторите позже». Не повторяйте автоматически.
- По умолчанию измеряйте только
latency_url. Отдельные IPv4/IPv6 URL используйте при выборе пользователя. - При уходе со страницы отменяйте запросы через
AbortController. Не запускайте цикл при каждом рендере или по фоновому интервалу. Результаты можно хранить в памяти вкладки 60 секунд; новый замер запускается отдельным действием.
У каждого запроса должен быть уникальный query-параметр и следующие настройки fetch:
const probeUrl = new URL(point.latency_url);
probeUrl.searchParams.set('probe', crypto.randomUUID());
const response = await fetch(probeUrl, {
credentials: 'omit',
cache: 'no-store',
mode: 'cors',
redirect: 'error',
signal: AbortSignal.any([pageAbortController.signal, AbortSignal.timeout(3000)]),
});
await response.arrayBuffer();
Endpoint возвращает пустой HTTP 200 с поддержкой CORS и Timing-Allow-Origin. Проверяйте статус; не используйте no-cors, скрывающий ошибки и ответы 429. При доступности Resource Timing используйте responseEnd - requestStart, иначе — разницу performance.now() вокруг fetch и чтения тела. Запасной вариант включает дополнительные накладные расходы браузера. Не очищайте общую таблицу Resource Timing страницы.
Добавьте https://*.lg.adaptgroup.pro в CSP connect-src вашего frontend. Подпишите результат «Задержка HTTPS». HTTP-таймауты не являются процентом потерь ICMP и не доказывают падение локации.
Эти запросы не расходуют квоту ручных проверок. Отдельные лимиты каждой точки: 20 запросов/с на IP с burst 40, 500/с на точку с burst 100, 8 одновременных запросов на IP и 128 на точку. Посетители за одним NAT делят его лимиты.