net.setDefaultAutoSelectFamilyAttemptTimeout() のエラーとトラブルシューティング (Node.js)

2025-05-27

net.setDefaultAutoSelectFamilyAttemptTimeout() メソッドとは

このメソッドは、Node.jsの net モジュールにおける機能である「自動アドレスファミリ選択 (AutoSelectFamily)」の試行タイムアウト時間をグローバルに設定するために使用されます。

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

Node.jsがネットワーク接続を確立する際、接続先のホスト名がIPv4とIPv6の両方のアドレスを持っている場合があります。AutoSelectFamily機能は、どちらのアドレスファミリ（IPv4またはIPv6）を優先的に試行するかを自動的に決定する仕組みです。

具体的には、まずIPv6での接続を試み、それが指定された時間内に成功しない場合、IPv4での接続を試みます。この挙動により、デュアルスタック環境（IPv4とIPv6の両方をサポートする環境）において、より適切なアドレスファミリでの接続を自動的に試みることができます。

setDefaultAutoSelectFamilyAttemptTimeout() メソッドの役割

net.setDefaultAutoSelectFamilyAttemptTimeout(timeout) メソッドは、このIPv6での接続試行のタイムアウト時間をミリ秒単位でグローバルに設定します。

timeout: ミリ秒単位の数値で、IPv6接続の試行を諦めてIPv4接続の試行を開始するまでの待ち時間を指定します。

設定の意味合い

長いタイムアウト
IPv6での接続が遅延している場合でも、しばらくの間IPv6での接続を試み続けます。IPv6が優先される環境では、より適切な接続が確立される可能性が高まりますが、IPv6に問題がある場合は接続確立までの時間が長くなる可能性があります。
短いタイムアウト
IPv6での接続がすぐに失敗する場合、比較的早くIPv4での接続を試みるようになります。IPv6に問題がある環境でも、比較的早く接続が確立される可能性があります。

グローバルな設定

setDefaultAutoSelectFamilyAttemptTimeout() で設定されたタイムアウト時間は、アプリケーション全体でデフォルトとして使用されます。個々の net.connect() や socket.connect() 呼び出しで、autoSelectFamilyAttemptTimeout オプションを指定することで、このグローバルな設定を上書きすることも可能です。

const net = require('net');

// デフォルトの自動選択ファミリ試行タイムアウトを 500 ミリ秒に設定
net.setDefaultAutoSelectFamilyAttemptTimeout(500);

// この設定は、特にオプションでタイムアウトを指定しない限り、
// 以降のすべての net.connect() 呼び出しに影響します。

net.connect({ host: 'example.com', port: 80 }, () => {
  console.log('接続成功');
});

一般的なエラーとトラブルシューティング

net.setDefaultAutoSelectFamilyAttemptTimeout() 自体が直接的なエラーを引き起こすことは少ないですが、その設定値や関連するネットワーク環境によって、予期せぬ動作や接続の問題が発生することがあります。以下に、よくあるケースとその対処法を説明します。

タイムアウト値の設定ミスによる問題

トラブルシューティング
- タイムアウト値が長すぎないか確認してください。
- IPv6接続が頻繁に失敗する環境であれば、タイムアウト値を短くするか、IPv4を優先する設定（例えば family: 4 を net.connect() のオプションで指定するなど）を検討してください。
問題
タイムアウト値を極端に長く設定した場合、IPv6での接続に問題がある場合に、接続確立までの時間が非常に長くなる可能性があります。
トラブルシューティング
- タイムアウト値が短すぎないか確認してください。通常、数十ミリ秒から数百ミリ秒程度の値が適切です。
- ネットワーク環境（IPv6の応答速度など）を考慮し、適切なタイムアウト値を設定してください。
- 特定の接続に対して異なるタイムアウト値を試したい場合は、net.connect() や socket.connect() のオプションで autoSelectFamilyAttemptTimeout を個別に設定することを検討してください。
問題
タイムアウト値を極端に短く設定した場合（例: 数ミリ秒）、IPv6での接続試行が完了する前にタイムアウトし、すぐにIPv4での接続が試みられます。IPv6環境が正常に動作しているにもかかわらず、常にIPv4での接続になってしまう可能性があります。

AutoSelectFamily 機能が意図通りに動作しない

トラブルシューティング
- ネットワーク環境にIPv6接続の問題がないか確認してください。
- 接続先のサーバーがIPv6に応答しているか確認してください。
- タイムアウト値が非常に大きく設定されていないか確認してください。
問題
IPv6での接続試行がタイムアウトせず、IPv4での接続がいつまでも試みられない。
トラブルシューティング
- DNSサーバーがIPv6のアドレスを正しく返しているか確認してください (dig AAAA <ホスト名> などで確認できます)。
- 接続先のサーバーがIPv6を受け付けているか確認してください。
- 中間にあるネットワーク機器（ファイアウォールなど）がIPv6の通信をブロックしていないか確認してください。
- Node.jsのバージョンがAutoSelectFamily機能をサポートしているか確認してください（比較的新しいバージョンで導入されました）。
- net.setDefaultAutoSelectFamilyAttemptTimeout() の設定値が極端でないか確認してください。
問題
ホスト名がIPv4とIPv6の両方のアドレスを持っているにもかかわらず、常に特定のアドレスファミリ（例えばIPv4のみ）で接続される。

トラブルシューティング
- 特定の接続に対して異なるタイムアウトが必要な場合は、net.connect() や socket.connect() の autoSelectFamilyAttemptTimeout オプションを明示的に設定してください。
問題
グローバルなタイムアウト設定が、特定の接続に対して意図せず影響を与えている。
トラブルシューティング
- 引数として数値以外の値を渡していないか確認してください。
- Node.jsのバージョンが古く、このメソッドが利用できない可能性がないか確認してください。
問題
アプリケーションの起動時や設定変更時に、net.setDefaultAutoSelectFamilyAttemptTimeout() の呼び出しでエラーが発生する。

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

設定の確認
net.getDefaultAutoSelectFamilyAttemptTimeout() を呼び出して、現在のグローバルなタイムアウト設定値を確認します。
簡単なテスト
ping6 や telnet6 などのコマンドラインツールを使用して、接続先のIPv6アドレスへの接続性を個別にテストします。
ネットワーク監視
tcpdump や Wireshark などのツールを使用して、実際のネットワークトラフィックを監視し、DNSクエリや接続試行の状況を確認します。
ログ出力
ネットワーク接続に関する詳細なログを出力するようにアプリケーションを修正し、どのアドレスファミリでの接続が試みられているか、タイムアウトが発生しているかなどを確認します。

基本的な使用例: グローバルなタイムアウト値を設定する

この例では、アプリケーション全体のデフォルトの自動アドレスファミリ選択の試行タイムアウト値を設定します。

const net = require('net');

// デフォルトのタイムアウトを 500 ミリ秒に設定
net.setDefaultAutoSelectFamilyAttemptTimeout(500);

// 以降の net.connect() 呼び出しでは、特にオプションで指定しない限り、
// IPv6接続の試行が 500 ミリ秒でタイムアウトし、IPv4接続が試みられます。

net.connect({ host: 'example.com', port: 80 }, () => {
  console.log('example.com に接続成功 (デフォルトのタイムアウト)');
});

net.connect({ host: 'ipv6.google.com', port: 443 }, () => {
  console.log('ipv6.google.com に接続成功 (デフォルトのタイムアウト)');
});

個別の接続でタイムアウト値を上書きする

この例では、net.connect() のオプションで autoSelectFamilyAttemptTimeout を指定することで、グローバルな設定を特定の接続に対して上書きします。

const net = require('net');

// グローバルなデフォルトタイムアウトを 1000 ミリ秒に設定
net.setDefaultAutoSelectFamilyAttemptTimeout(1000);

// この接続では、タイムアウトを 200 ミリ秒に設定して試行
net.connect({ host: 'example.com', port: 80, autoSelectFamilyAttemptTimeout: 200 }, () => {
  console.log('example.com に接続成功 (カスタムタイムアウト)');
});

// こちらはグローバルなデフォルトタイムアウト (1000 ミリ秒) が適用される
net.connect({ host: 'ipv6.google.com', port: 443 }, () => {
  console.log('ipv6.google.com に接続成功 (デフォルトのタイムアウト)');
});

タイムアウト値を変更するタイミング

setDefaultAutoSelectFamilyAttemptTimeout() は、通常アプリケーションの初期設定段階で一度だけ呼び出すことが多いです。実行中に頻繁に値を変更することは、予期せぬ動作を引き起こす可能性があるため、推奨されません。

const net = require('net');

// アプリケーション起動時にタイムアウトを設定
function initializeNetworkSettings() {
  const timeoutValue = process.env.AUTO_SELECT_TIMEOUT || 300; // 環境変数から取得したり、設定ファイルから読み込んだりする
  net.setDefaultAutoSelectFamilyAttemptTimeout(parseInt(timeoutValue, 10));
  console.log(`自動選択ファミリ試行タイムアウトを ${timeoutValue} ミリ秒に設定`);
}

initializeNetworkSettings();

net.connect({ host: 'example.com', port: 80 }, () => {
  console.log('接続成功');
});

タイムアウト値が接続時間に与える影響を確認する

この例では、異なるタイムアウト値を設定し、接続にかかる時間を計測することで、その影響を確認します。

const net = require('net');

async function testConnection(host, port, timeout) {
  net.setDefaultAutoSelectFamilyAttemptTimeout(timeout);
  const startTime = Date.now();
  return new Promise((resolve, reject) => {
    const socket = net.connect({ host, port }, () => {
      const endTime = Date.now();
      console.log(`${host}:${port} に接続成功 (タイムアウト: ${timeout}ms, 接続時間: ${endTime - startTime}ms)`);
      socket.end();
      resolve();
    });
    socket.on('error', (err) => {
      const endTime = Date.now();
      console.error(`${host}:${port} への接続エラー (タイムアウト: ${timeout}ms, 失敗時間: ${endTime - startTime}ms): ${err.message}`);
      reject(err);
    });
  });
}

async function main() {
  await testConnection('ipv6.google.com', 443, 100);
  await testConnection('ipv6.google.com', 443, 1000);
  await testConnection('example.com', 80, 100); // IPv4 のみの可能性
}

main();

タイムアウト値は、ネットワークの状況やサーバーの応答速度などを考慮して適切に設定する必要があります。
実際に動作させる際には、適切なホスト名とポート番号を指定してください。
上記の例では、接続先のホストがIPv6アドレスを持っているかどうか、またネットワーク環境によって結果が異なります。

net.connect() および socket.connect() の autoSelectFamilyAttemptTimeout オプションを使用する

最も直接的な代替方法は、個々の接続ごとにタイムアウト値を設定する方法です。net.connect() 関数やソケットの connect() メソッドのオプションオブジェクトに autoSelectFamilyAttemptTimeout プロパティを指定することで、その特定の接続のみに適用されるタイムアウト値を設定できます。

const net = require('net');

// グローバルなデフォルト設定はそのままにするか、または設定しない

// 特定の接続で異なるタイムアウト値を設定
net.connect({
  host: 'example.com',
  port: 80,
  autoSelectFamilyAttemptTimeout: 200 // この接続のみ 200 ミリ秒のタイムアウト
}, () => {
  console.log('example.com に接続成功 (カスタムタイムアウト)');
});

const socket = net.connect({ host: 'ipv6.google.com', port: 443 });
socket.connect({
  host: 'ipv6.google.com',
  port: 443,
  autoSelectFamilyAttemptTimeout: 1500 // このソケットの接続のみ 1500 ミリ秒のタイムアウト
}, () => {
  console.log('ipv6.google.com に接続成功 (ソケットごとのカスタムタイムアウト)');
});

// デフォルトの挙動を使用する接続
net.connect({ host: 'another-example.com', port: 80 }, () => {
  console.log('another-example.com に接続成功 (デフォルトのタイムアウト)');
});

この方法の利点は、アプリケーション全体の設定に影響を与えることなく、特定の接続の要件に合わせてタイムアウト値を調整できることです。例えば、一部の接続先はIPv6の応答が遅いことがわかっている場合に、タイムアウトを長く設定するといった使い方ができます。

family オプションを使用してアドレスファミリを明示的に指定する

自動アドレスファミリ選択自体をスキップし、接続に使用するアドレスファミリ（IPv4またはIPv6）を明示的に指定することもできます。net.connect() や socket.connect() のオプションで family プロパティに 4 (IPv4) または 6 (IPv6) を設定します。

const net = require('net');

// IPv4 のみを使用して接続
net.connect({ host: 'example.com', port: 80, family: 4 }, () => {
  console.log('example.com に IPv4 で接続成功');
});

// IPv6 のみを使用して接続
net.connect({ host: 'ipv6.google.com', port: 443, family: 6 }, () => {
  console.log('ipv6.google.com に IPv6 で接続成功');
});

// アドレスファミリを指定した場合、タイムアウトの設定は直接的には影響しません
// (指定されたファミリでの接続試行のタイムアウトは通常通り行われます)。

この方法の利点は、どちらのアドレスファミリを使用するかを完全に制御できるため、AutoSelectFamily の挙動に依存しないことです。特定の環境で特定のアドレスファミリを優先したい場合や、AutoSelectFamily が期待通りに動作しない場合に有効です。

カスタムのロジックでアドレスファミリを試行する

より高度な方法として、DNSルックアップの結果に基づいて、自分で接続を試行する順序やタイムアウトを制御するロジックを実装することも可能です。dns モジュールを使用してホスト名のIPアドレスを取得し、取得したアドレスのファミリに基づいて接続を試みます。

const net = require('net');
const dns = require('dns').promises;

async function connectWithCustomTimeout(host, port, timeout) {
  try {
    const addresses = await dns.lookup(host, { all: true });
    let connected = false;

    for (const addrInfo of addresses) {
      const family = addrInfo.family;
      const address = addrInfo.address;
      console.log(`${host} の ${family === 4 ? 'IPv4' : 'IPv6'} アドレス: ${address}`);

      const startTime = Date.now();
      await new Promise((resolve, reject) => {
        const socket = net.connect({ host: address, port });
        let timeoutId;

        socket.on('connect', () => {
          clearTimeout(timeoutId);
          const endTime = Date.now();
          console.log(`${host}:${port} に ${family === 4 ? 'IPv4' : 'IPv6'} で接続成功 (接続時間: ${endTime - startTime}ms)`);
          socket.end();
          connected = true;
          resolve();
        });

        socket.on('error', (err) => {
          clearTimeout(timeoutId);
          console.error(`${host}:${port} への ${family === 4 ? 'IPv4' : 'IPv6'} での接続エラー: ${err.message}`);
          resolve(); // エラーが発生しても次のアドレスを試行
        });

        timeoutId = setTimeout(() => {
          socket.destroy(new Error(`接続タイムアウト (${timeout}ms)`));
          resolve();
        }, timeout);
      });

      if (connected) {
        break; // 接続に成功したらループを抜ける
      }
    }

    if (!connected) {
      console.error(`${host}:${port} への接続に失敗`);
    }

  } catch (err) {
    console.error(`${host} の DNS ルックアップエラー: ${err.message}`);
  }
}

async function main() {
  await connectWithCustomTimeout('example.com', 80, 300);
  await connectWithCustomTimeout('ipv6.google.com', 443, 500);
}

main();

この方法は最も柔軟性がありますが、実装が複雑になる可能性があります。特定のアドレスファミリを優先的に試行したり、接続失敗時のフォールバックロジックを細かく制御したい場合に有効です。

net.setDefaultAutoSelectFamilyAttemptTimeout() はグローバルなデフォルト設定を変更する便利な方法ですが、より細やかな制御が必要な場合は、以下の代替方法を検討してください。

カスタムのロジック
dns モジュールと net モジュールを組み合わせて、アドレスファミリの試行順序やタイムアウトを自分で制御できます。
family オプション
使用するアドレスファミリを明示的に指定することで、AutoSelectFamily をスキップできます。
net.connect() および socket.connect() の autoSelectFamilyAttemptTimeout オプション
個々の接続ごとにタイムアウト値を設定できます。