Node.js ネットワーク接続のトラブルシューティング：getDefaultAutoSelectFamilyAttemptTimeout

2025-04-26

net.getDefaultAutoSelectFamilyAttemptTimeout() とは

net.getDefaultAutoSelectFamilyAttemptTimeout() は、Node.jsの net モジュールに存在する関数の一つで、自動アドレスファミリ選択 (AutoSelectFamily) の試行タイムアウトのデフォルト値（ミリ秒単位）を取得する ために使用されます。

自動アドレスファミリ選択 (AutoSelectFamily) とは

近年、インターネットプロトコルは IPv4 と IPv6 が共存しています。AutoSelectFamily 機能は、Node.js がネットワーク接続を確立する際に、利用可能なアドレスファミリ（IPv6 が利用可能であれば IPv6 を優先するなど）を自動的に選択しようとする機能です。

この自動選択の過程で、Node.js は複数のアドレスへの接続を試行することがあります。net.getDefaultAutoSelectFamilyAttemptTimeout() が返す値は、特定のアドレスファミリへの接続試行がタイムアウトするまでのデフォルトの時間 を示します。

この関数の役割

この関数を使用することで、Node.js アプリケーション全体の AutoSelectFamily 機能における個々の接続試行のデフォルトタイムアウト値を確認できます。

戻り値

この関数は、数値（ミリ秒単位）を返します。これは、自動アドレスファミリ選択が特定のアドレスへの接続を試行する際のデフォルトのタイムアウト時間です。

const net = require('net');

const defaultTimeout = net.getDefaultAutoSelectFamilyAttemptTimeout();
console.log(`デフォルトの AutoSelectFamily 試行タイムアウト: ${defaultTimeout} ミリ秒`);

AutoSelectFamily 機能は、ネットワーク環境に応じて最適なアドレスファミリを選択するのに役立ちますが、タイムアウト値が短すぎると、本来接続できるはずの環境でも接続に失敗する可能性があります。
デフォルトのタイムアウト値は、net.setDefaultAutoSelectFamilyAttemptTimeout(timeout) 関数を使用して変更することができます。ただし、通常はデフォルト値で十分な場合が多いです。
この関数は、デフォルトのタイムアウト値を取得するものであり、個々のソケットや接続に対して設定されたタイムアウト値には影響しません。

net.getDefaultAutoSelectFamilyAttemptTimeout() 自体で直接的なエラーが発生することは稀です。 この関数は単にデフォルトのタイムアウト値を取得するだけなので、呼び出し自体が失敗することは通常ありません。

しかし、net.getDefaultAutoSelectFamilyAttemptTimeout() が関連する AutoSelectFamily 機能や、そのデフォルト値を変更する net.setDefaultAutoSelectFamilyAttemptTimeout(timeout) の使用において、以下のような状況で問題が発生したり、誤解が生じたりすることがあります。

net.setDefaultAutoSelectFamilyAttemptTimeout() の誤用による問題

型が間違った値を設定した場合
- 症状
  net.setDefaultAutoSelectFamilyAttemptTimeout() に数値以外の値を渡すと、予期しない動作やエラーが発生する可能性があります。
- トラブルシューティング
  - net.setDefaultAutoSelectFamilyAttemptTimeout() には、ミリ秒単位の数値を渡すようにしてください。
タイムアウト値を長く設定しすぎた場合
- 症状
  接続できないホストへの接続試行に時間がかかり、全体的な処理が遅延する可能性があります。
- トラブルシューティング
  - 設定したタイムアウト値が長すぎないか見直してください。
  - より迅速に接続失敗を検知できるように、適切なタイムアウト値を設定してください。
- 症状
  IPv6 環境で、IPv4 アドレスへの接続試行が完了する前にタイムアウトが発生し、接続に失敗する可能性があります。特に、ネットワークの遅延が大きい場合や、DNS 解決に時間がかかる場合に起こりやすいです。
- トラブルシューティング
  - 設定したタイムアウト値が適切かどうか見直してください。ネットワーク環境や接続先の状況に合わせて、より長いタイムアウト値を設定する必要があるかもしれません。
  - ネットワークの遅延や DNS 解決時間を調査してください。
  - 一時的にタイムアウト値を大きくして、問題が解決するかどうか確認してみてください。

AutoSelectFamily 機能に関する誤解

タイムアウト値が接続全体のタイムアウトではない
- 症状
  net.getDefaultAutoSelectFamilyAttemptTimeout() で取得または設定した値は、あくまで個々の接続試行のタイムアウトであり、接続全体のタイムアウトではありません。接続全体のタイムアウトを設定したい場合は、ソケットオブジェクトに対して socket.setTimeout() を使用する必要があります。
- トラブルシューティング
  - 接続全体のタイムアウトを設定する必要がある場合は、socket.setTimeout() を適切に設定してください。
AutoSelectFamily が常に最適なアドレスファミリを選択するとは限らない
- 症状
  IPv6 が利用可能な環境でも、意図せず IPv4 で接続される、またはその逆のケースが発生する可能性があります。
- トラブルシューティング
  - AutoSelectFamily はあくまでデフォルトの動作であり、常に最適な選択をするとは限りません。特定のプロトコルでの接続を強制したい場合は、net.connect() や net.createServer() などのオプションで family を明示的に指定することを検討してください (family: 4 for IPv4, family: 6 for IPv6)。
  - 接続先のサーバーが IPv6 と IPv4 の両方に対応しているか確認してください。

環境による影響

オペレーティングシステムの設定
- 症状
  オペレーティングシステムの設定によっては、IPv6 が有効になっていない、または優先順位が低く設定されている場合があります。
- トラブルシューティング
  - オペレーティングシステムの設定を確認し、IPv6 が適切に設定されているか確認してください。
ネットワーク環境の問題
- 症状
  ファイアウォールやネットワーク設定によって、特定のアドレスファミリへの接続がブロックされている場合、タイムアウトが発生する可能性があります。
- トラブルシューティング
  - ネットワーク管理者やインフラ担当者に確認し、必要なポートやプロトコルが許可されているか確認してください。
  - 異なるネットワーク環境でテストし、問題が特定の環境に依存するかどうかを切り分けてください。

トラブルシューティングの一般的なアプローチ

ドキュメント確認
Node.js の公式ドキュメントを再度確認し、関連する API の仕様や注意点を確認します。
ネットワーク監視
Wireshark などのツールを使用してネットワークトラフィックを監視し、接続試行の状況やエラーを確認します。
単純化
問題を再現させるために、可能な限りシンプルなコードでテストします。
ログ出力
接続試行のログやエラーメッセージを詳細に出力するように設定し、何が起こっているかを確認します。

例1: デフォルトのタイムアウト値を取得して表示する

これは最も基本的な例で、現在のデフォルトの自動アドレスファミリ選択の試行タイムアウト値を取得し、コンソールに出力します。

const net = require('net');

const defaultTimeout = net.getDefaultAutoSelectFamilyAttemptTimeout();
console.log(`デフォルトの AutoSelectFamily 試行タイムアウト: ${defaultTimeout} ミリ秒`);

このコードを実行すると、Node.js のデフォルト設定に基づいたタイムアウト値（通常は 250 ミリ秒）がコンソールに表示されます。

例2: デフォルトのタイムアウト値を変更して確認する

この例では、net.setDefaultAutoSelectFamilyAttemptTimeout() を使用してデフォルト値を変更し、その変更が net.getDefaultAutoSelectFamilyAttemptTimeout() で正しく取得できることを確認します。

const net = require('net');

// デフォルトのタイムアウト値を取得して表示
let currentTimeout = net.getDefaultAutoSelectFamilyAttemptTimeout();
console.log(`現在のデフォルトのタイムアウト値 (変更前): ${currentTimeout} ミリ秒`);

// デフォルトのタイムアウト値を 500 ミリ秒に変更
net.setDefaultAutoSelectFamilyAttemptTimeout(500);
console.log('デフォルトのタイムアウト値を 500 ミリ秒に設定しました。');

// 変更後のデフォルトのタイムアウト値を取得して表示
currentTimeout = net.getDefaultAutoSelectFamilyAttemptTimeout();
console.log(`現在のデフォルトのタイムアウト値 (変更後): ${currentTimeout} ミリ秒`);

// 必要であれば、デフォルト値を元に戻すこともできます
// net.setDefaultAutoSelectFamilyAttemptTimeout(250);

このコードを実行すると、まず元のデフォルト値が表示され、次に変更後の 500 ミリ秒という値が表示されるはずです。

例3: サーバーとクライアントでタイムアウト値の影響を確認する (概念)

この例は、実際にタイムアウトが発生する状況を作るのは少し複雑なため、概念的な説明とコードの骨子を示します。

サーバー側 (server.js)

const net = require('net');

const server = net.createServer((socket) => {
  console.log('クライアントが接続しました。');
  socket.on('end', () => {
    console.log('クライアントが切断しました。');
  });
  socket.write('Hello from server!\r\n');
  socket.pipe(socket);
});

server.listen(3000, () => {
  console.log('サーバーがポート 3000 で起動しました。');
});

クライアント側 (client.js)

const net = require('net');

// デフォルトのタイムアウト値を取得して表示
const defaultTimeout = net.getDefaultAutoSelectFamilyAttemptTimeout();
console.log(`クライアントのデフォルト AutoSelectFamily 試行タイムアウト: ${defaultTimeout} ミリ秒`);

const client = net.connect({ port: 3000 }, () => {
  console.log('サーバーに接続しました。');
  client.on('data', (data) => {
    console.log(`サーバーからのデータ: ${data.toString()}`);
    client.end();
  });
});

client.on('end', () => {
  console.log('サーバーとの接続を閉じました。');
});

client.on('error', (err) => {
  console.error(`接続エラー: ${err}`);
});

// 意図的に存在しないアドレスに接続しようとする場合 (タイムアウトを確認する概念)
// setTimeout(() => {
//   const client2 = net.connect({ host: 'invalid-host-example', port: 3000 }, () => {
//     console.log('2番目のクライアントが接続しました (これは起こらないはず)');
//   });
//
//   client2.on('error', (err) => {
//     console.error(`2番目のクライアントの接続エラー: ${err}`);
//   });
// }, 1000);

この例では、クライアントがサーバーに接続する基本的な流れを示しています。net.getDefaultAutoSelectFamilyAttemptTimeout() は、クライアントが接続を試みる際のアドレス解決と接続確立の個々の試行に影響を与えます。

タイムアウトの影響を確認するシナリオ (概念)

IPv6 のみが利用可能な環境で、IPv4 のみに対応したサーバーに接続しようとする場合 (またはその逆)
AutoSelectFamily は両方のアドレスファミリを試行しますが、それぞれの試行が getDefaultAutoSelectFamilyAttemptTimeout() で設定された時間内に失敗すると、次の試行に移ります。デフォルト値が短すぎると、本来接続できるはずのプロトコルへの試行が完了する前にタイムアウトし、結果的に接続に失敗する可能性があります。
DNS 解決に時間がかかる場合
AutoSelectFamily は、ホスト名を IP アドレスに解決する際にもタイムアウトの影響を受けます。デフォルト値が短すぎると、DNS 解決が完了する前にタイムアウトし、接続エラーが発生する可能性があります。

注意点

net.setDefaultAutoSelectFamilyAttemptTimeout() はグローバルな設定であり、アプリケーション全体に影響を与えるため、慎重に使用する必要があります。
タイムアウトの挙動を詳細に確認するには、意図的に接続できない状況を作り出すなどの工夫が必要になる場合があります。
これらの例は基本的なものであり、実際のネットワーク環境やサーバーの構成によって動作が変わる可能性があります。

net.getDefaultAutoSelectFamilyAttemptTimeout() の直接的な操作は、アプリケーション全体のデフォルト設定を変更するため、状況によっては影響範囲が広すぎることがあります。より柔軟な制御や、特定の場合にのみ挙動を変えたい場合に役立つ代替方法を以下に示します。

net.connect() および net.createServer() の options.family プロパティを使用する

最も直接的な代替方法は、接続を確立する際 (net.connect()) やサーバーを作成する際 (net.createServer()) に、使用するアドレスファミリを明示的に指定することです。

net.createServer([options][, connectionListener]) の options.family
- サーバーがリッスンするアドレスファミリを制限できます。family: 4 なら IPv4 のみ、family: 6 なら IPv6 のみでリッスンします。
- family: 4 を指定すると、IPv4 アドレスのみを使用して接続を試みます。
- family: 6 を指定すると、IPv6 アドレスのみを使用して接続を試みます。
- family を省略するか 0 を指定すると、AutoSelectFamily が有効になり、デフォルトのタイムアウト設定に従います。

例
IPv4 のみを使用してサーバーに接続する

const net = require('net');

const client = net.connect({ port: 3000, host: '127.0.0.1', family: 4 }, () => {
  console.log('IPv4 でサーバーに接続しました。');
  // ...
});

client.on('error', (err) => {
  console.error('接続エラー:', err);
});

利点

意図するプロトコルを明確に指定できるため、AutoSelectFamily の挙動に依存しません。
特定の接続に対してのみアドレスファミリを制御できるため、グローバルなデフォルト設定を変更する必要がありません。

欠点

アプリケーションの要件に応じて、IPv4 と IPv6 のどちらを使用するかを事前に判断する必要があります。
接続ごとに明示的に指定する必要があるため、多くの接続を行う場合はコードが冗長になる可能性があります。

接続試行のタイムアウトを個別に設定する (socket.setTimeout())

net.getDefaultAutoSelectFamilyAttemptTimeout() は、AutoSelectFamily における個々の接続試行のタイムアウトを制御しますが、接続全体のタイムアウトを制御するわけではありません。接続全体のタイムアウトを設定したい場合は、ソケットオブジェクトの socket.setTimeout(timeout[, callback]) メソッドを使用します。

例
接続全体のタイムアウトを 3 秒に設定する

const net = require('net');

const client = net.connect({ port: 3000, host: 'example.com' }, () => {
  console.log('サーバーに接続しました。');
  client.setTimeout(3000, () => {
    console.log('接続がタイムアウトしました。');
    client.destroy(); // ソケットを破棄
  });
  // ...
});

client.on('data', (data) => {
  console.log('受信データ:', data.toString());
});

client.on('error', (err) => {
  console.error('接続エラー:', err);
});

利点

AutoSelectFamily の個々の試行タイムアウトとは独立して設定できます。
接続全体のタイムアウトを制御できるため、無応答の接続を長時間放置することを防ぎます。

欠点

個々のソケットに対してタイムアウトを設定する必要があります。

より高レベルな HTTP/HTTPS モジュールを使用する際のオプション

http や https モジュールを使用して HTTP/HTTPS リクエストを行う場合、内部的には net モジュールが使用されますが、これらの高レベルモジュールは、接続に関するより多くのオプションを提供している場合があります。例えば、リクエスト全体のタイムアウトや、DNS 解決に関する設定などです。これらのオプションを通じて、間接的に接続の挙動を制御できる場合があります。

例 (http モジュールでのタイムアウト設定)

const http = require('http');

const options = {
  hostname: 'example.com',
  port: 80,
  path: '/',
  method: 'GET',
  timeout: 5000 // リクエスト全体のタイムアウト (ミリ秒)
};

const req = http.request(options, (res) => {
  console.log(`ステータスコード: ${res.statusCode}`);
  res.on('data', (chunk) => {
    console.log(`ボディ: ${chunk}`);
  });
});

req.on('error', (err) => {
  console.error(`リクエストエラー: ${err.message}`);
});

req.on('timeout', () => {
  console.log('リクエストがタイムアウトしました。');
  req.destroy();
});

req.end();

利点

より高レベルな抽象化により、低レベルなソケット操作を意識せずに済みます。
HTTP/HTTPS プロトコルに特化した便利なオプションが利用できます。

欠点

net モジュールほど低レベルな制御はできません。

カスタムの接続ロジックを実装する (複雑)

より高度なシナリオでは、AutoSelectFamily の挙動に完全に依存せず、自身で接続を試行するロジックを実装することも考えられます。これには、利用可能なアドレスファミリを判断し、順番に接続を試みるなどの処理が含まれます。ただし、これはかなり複雑な実装になるため、特別な要件がある場合にのみ検討すべきです。

net.getDefaultAutoSelectFamilyAttemptTimeout() はデフォルトの挙動を制御するグローバルな設定ですが、より柔軟かつ特定の場合にのみ挙動を変えたい場合は、以下の代替方法を検討してください。

カスタムの接続ロジック
より複雑な要件に対応するために、自身で接続処理を実装する (高度なケース)。
高レベルモジュール (http, https)
プロトコル固有のタイムアウトや接続オプションを利用する。
socket.setTimeout()
個々のソケット接続に対してタイムアウトを設定する。
net.connect()/net.createServer() の family オプション
特定の接続やサーバーでアドレスファミリを明示的に指定する。