IPルックアップAPIを本番導入するための実践チェックリスト

IPインテリジェンスのAPIを呼び出すだけなら、実装は10分で終わるかもしれません。けれど本番運用では、その後の半年間、さまざまなエッジケースと向き合うことになります。新しい連携を入れるなら、少なくともこのチェックリストは通しておきたいところです。

1. クライアントのIPアドレスを正しく取得する

まず何よりも、照会しているIPアドレスが本当にユーザーのものかを確認します。ロードバランサーやCDNの背後にいる場合、remoteAddr に入っているのは自社側の proxy であることが少なくありません。見るべきは転送ヘッダー上のチェーンです。ただし、信頼してよいのは自分たちが管理しているホップだけです。左端の、簡単に偽装できる値をそのまま使うのではなく、右側から見て最初の「信頼できない」エントリを採用する必要があります。間違ったIPアドレスを照会するくらいなら、照会しないほうがましです。誤った結果に、もっともらしい権威が付いてしまうからです。

IPv6にもきちんと対応しましょう。角括弧付きの表記や、IPv4-mapped IPv6アドレスも扱えるようにしておく必要があります。

2. ハードタイムアウトを設定する

あらかじめ許容する時間を決めておきます。サインアップ導線であれば、300〜800 ms程度が現実的な目安です。そして、その上限をクライアント側で必ず強制します。リスクチェックが応答待ちで固まってしまうと、セキュリティ機能のはずが障害の原因になります。

3. フェイルオープンかフェイルクローズかを、処理ごとに決める

呼び出し箇所ごとに、方針を明文化しておきます。

• Signup / login → fail open。依存先が遅いという理由で、全ユーザーを締め出してはいけません。
• Payout or withdrawal → fail closed、または手動レビューのキューに回します。資金が外に出る処理では、多少の遅延には意味があります。

アプリケーション全体で一律の方針にしてしまうと、障害につながるか、損失につながるかのどちらかになりがちです。

4. キャッシュする

同じIPアドレスから、数分以内に何度もアクセスが来ることはよくあります。IPアドレスをキーにして、妥当な時間だけ結果をキャッシュしましょう。まずは1時間程度を出発点にするとよいでしょう。レイテンシ、コスト、プロバイダー側の負荷を同時に下げられます。TTLは設定で変更できるようにしておくべきです。インシデント時には短くし、トラフィックが跳ねたときには長めにする、といった運用ができます。

5. 可能ならクリティカルパスから外す

すべてのチェックがレスポンスをブロックする必要はありません。分析データのクレンジング、ログの付加情報、事後レビューのためであれば、IPアドレスをキューに入れて非同期にエンリッチすれば十分です。同期呼び出しは、その場で意思決定が必要なケースに絞りましょう。

6. 望ましくないレスポンスを処理する

起こり得るケースを列挙し、テストします。レート制限、無効なAPIキー、不明なIPアドレス、プライベートまたは予約済みレンジ、不正な入力形式などです。それぞれについて、コード上で明確な結果に落ちるようにしておきます。リクエストハンドラー内で未処理例外になる状態は避けるべきです。

プライベートレンジは特に注意が必要です。10.x、192.168.x、127.0.0.1 などは、開発環境でも、設定ミスのある proxy チェーンでも出てきます。API呼び出しを消費する前に、アプリケーション側で短絡的に処理しましょう。

7. APIキーを保護する

APIキーはサーバーサイドの設定に置くものです。ブラウザのJavaScriptやモバイルアプリのバンドルに含めてはいけません。クライアントに配布されたものは、すべて公開情報だと考えるべきです。担当者が変わったらキーをローテーションし、環境ごとに別のキーを使いましょう。そうしておけば、ひとつのキーを失効させても全環境を巻き込まずに済みます。

8. 判定結果と実際の判断を一緒に記録する

スコアやフラグは、そのとき実行したアクションと合わせて保存します。後になって「なぜ3月にこの注文を拒否したのか」と確認したくなったとき、答えはプロバイダーのダッシュボードから復元するのではなく、自社のデータベースに残っているべきです。

9. 自社側のメトリクスを見る

呼び出しレイテンシのパーセンタイル、エラー率、キャッシュヒット率、クォータ消費量を追跡します。これらのどれかが静かにずれ始めたとき、多くの場合、その先に目に見えるインシデントがあります。

10. 実在するIPアドレスでテストする

テストスイートには、既知のデータセンターIP、既知のTOR出口ノード、住宅回線のIP、モバイル回線のIPを含めておきます。検証では厳密なスコアではなく、分類に対してアサーションするのが実務的です。スコアは変化しますが、カテゴリは比較的安定しています。

このリストを一度きちんと通しておけば、そのIPインテリジェンス連携は、実装したスプリントが終わった後も長く耐えてくれるはずです。