Практический чек-лист для интеграции API IP-проверок

Добавить вызов IP intelligence API можно за десять минут. А потом полгода разбираться с пограничными случаями. Ниже — чек-лист, который мы сами хотели бы видеть у любой новой интеграции.

1. Правильно определите IP клиента

Прежде всего убедитесь, что проверяете именно тот адрес, который нужно. Если перед приложением стоит балансировщик или CDN, remoteAddr с большой вероятностью будет указывать на ваш собственный proxy. Вам нужна цепочка forwarded-заголовков — причём доверять стоит только тем узлам, которые вы контролируете, и брать самый правый недоверенный адрес, а не самый левый, который легко подделать. Проверка неверного IP хуже, чем отсутствие проверки: результат выглядит убедительно, но ведёт не туда.

Не забудьте корректно обработать IPv6, включая адреса в квадратных скобках и IPv4-mapped notation.

2. Задайте жёсткий таймаут

Выделите понятный бюджет — для сценария регистрации обычно достаточно 300–800 ms — и enforce it на стороне клиента. Risk check, который зависает, быстро превращает защитный механизм в причину инцидента.

3. Определите fail-open или fail-closed для каждого сценария

Зафиксируйте поведение явно для каждой точки вызова:

• Signup / login → fail open. Не стоит блокировать всю пользовательскую базу только потому, что внешняя зависимость отвечает медленно.
• Payout or withdrawal → fail closed или отправка в очередь на ручную проверку. Когда деньги уходят наружу, небольшая задержка оправдана.

Единая политика на всё приложение почти всегда заканчивается одним из двух: либо простоем, либо финансовыми потерями.

4. Cache

Один и тот же адрес может обращаться к вам много раз в течение нескольких минут. Кешируйте результат на разумный срок — один час обычно хороший старт — с ключом по IP-адресу. Это одновременно снижает задержку, стоимость и нагрузку на провайдера. TTL лучше сделать настраиваемым: во время инцидента его можно сократить, а при всплеске трафика — увеличить.

5. Выносите проверку из критического пути, когда это возможно

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

6. Обработайте все неудачные ответы

Перечислите их и покройте тестами: rate limited, invalid key, unknown address, private or reserved range, malformed input. В каждом случае код должен приходить к заранее определённому результату, а не падать с необработанным исключением внутри request handler.

Отдельного внимания заслуживают приватные диапазоны — 10.x, 192.168.x, 127.0.0.1 и другие подобные адреса будут встречаться в разработке и в неправильно настроенных proxy-цепочках. Отсекайте их до API-вызова, чтобы не тратить запрос впустую.

7. Защитите ключ

API key должен храниться в серверной конфигурации, а не в browser JavaScript и не внутри mobile bundle. Всё, что уехало на клиент, уже публично. Ротируйте ключи при изменениях в команде и используйте отдельные ключи для разных окружений, чтобы можно было отозвать один, не ломая всю систему.

8. Логируйте вердикт вместе с решением

Сохраняйте score и flags рядом с действием, которое вы предприняли. Когда через несколько месяцев возникнет вопрос «почему мы отклонили этот заказ в марте?», ответ должен быть в вашей базе данных, а не в попытке восстановить картину по dashboard провайдера.

9. Следите за собственными метриками

Отслеживайте percentiles задержки вызовов, error rate, cache hit rate и расход quota. Тихий дрейф любой из этих метрик часто начинается раньше, чем инцидент становится заметен пользователям.

10. Тестируйте на реальных адресах

Добавьте в тестовый набор известный datacenter address, известный TOR exit, residential address и mobile address. Проверяйте классификацию, а не точные scores: численные оценки со временем меняются, категории остаются стабильнее.

Пройдитесь по этому списку один раз — и интеграция проживёт дольше спринта, в котором её собрали.