Node.js v21.7.2 ドキュメント

IPC サポート#

node:net モジュールは、Windows では名前付きパイプ、その他のオペレーティングシステムでは Unix ドメインソケットを使用して IPC をサポートしています。

IPC 接続のパスを特定する#

net.connect()、net.createConnection()、server.listen()、およびsocket.connect()は、IPC エンドポイントを識別するためにpathパラメーターを受け取ります。

Unix では、ローカルドメインは Unix ドメインとも呼ばれます。パスはファイルシステムのパス名です。これは、OS に依存する長さ `sizeof(sockaddr_un.sun_path) - 1` に切り捨てられます。一般的な値は、Linux では 107 バイト、macOS では 103 バイトです。Node.js API 抽象化が Unix ドメインソケットを作成する場合、Unix ドメインソケットもアンリンクします。たとえば、net.createServer() は Unix ドメインソケットを作成し、server.close() はそれをアンリンクします。しかし、ユーザーがこれらの抽象化の外で Unix ドメインソケットを作成した場合、ユーザーはそれを削除する必要があります。これは、Node.js API が Unix ドメインソケットを作成するが、プログラムがクラッシュした場合にも当てはまります。簡単に言うと、Unix ドメインソケットはファイルシステムに表示され、アンリンクされるまで保持されます。Linux では、パスの一番前に `\0` を追加して、`\0abstract` のように Unix 抽象ソケットを使用できます。Unix 抽象ソケットへのパスはファイルシステムには表示されず、ソケットへのすべてのオープン参照が閉じられたときに自動的に消えます。

Windows では、ローカルドメインは名前付きパイプを使用して実装されています。パスは、\\?\pipe\ または \\.\pipe\ のエントリを参照する必要があります。任意の文字が許可されていますが、後者はパイプ名の処理（`..` シーケンスの解決など）を行う場合があります。見た目とは異なり、パイプ名前空間はフラットです。パイプは保持されません。それらへの最後の参照が閉じられたときに削除されます。Unix ドメインソケットとは異なり、Windows は所有プロセスが終了したときにパイプを閉じ、削除します。

JavaScript の文字列エスケープでは、パスを次のように追加のバックスラッシュエスケープで指定する必要があります。

net.createServer().listen(
  path.join('\\\\?\\pipe', process.cwd(), 'myctl')); copy

クラス: `net.BlockList`#

BlockList オブジェクトは、一部のネットワーク API で使用して、特定の IP アドレス、IP 範囲、または IP サブネットへの着信または発信アクセスを無効にするためのルールを指定できます。

blockList.addAddress(address[, type])#

• address <string> | <net.SocketAddress> IPv4 または IPv6 アドレス。
• type <string> `'ipv4'` または `'ipv6'` のいずれか。デフォルト: `'ipv4'`。

指定された IP アドレスをブロックするルールを追加します。

blockList.addRange(start, end[, type])#

• start <string> | <net.SocketAddress> 範囲内の開始 IPv4 または IPv6 アドレス。
• end <string> | <net.SocketAddress> 範囲内の終了 IPv4 または IPv6 アドレス。
• type <string> `'ipv4'` または `'ipv6'` のいずれか。デフォルト: `'ipv4'`。

start（包含）からend（包含）までの IP アドレスの範囲をブロックするルールを追加します。

blockList.addSubnet(net, prefix[, type])#

• net <string> | <net.SocketAddress> ネットワーク IPv4 または IPv6 アドレス。
• prefix <number> CIDR プレフィックスビット数。IPv4 の場合、これは 0 から 32 の間の値でなければなりません。IPv6 の場合、これは 0 から 128 の間でなければなりません。
• type <string> `'ipv4'` または `'ipv6'` のいずれか。デフォルト: `'ipv4'`。

サブネットマスクとして指定された IP アドレスの範囲をブロックするルールを追加します。

blockList.check(address[, type])#

• address <string> | <net.SocketAddress> チェックする IP アドレス
• type <string> `'ipv4'` または `'ipv6'` のいずれか。デフォルト: `'ipv4'`。
• 戻り値: <boolean>

指定された IP アドレスが、BlockList に追加されたルールのいずれかに一致する場合は `true` を返します。

const blockList = new net.BlockList();
blockList.addAddress('123.123.123.123');
blockList.addRange('10.0.0.1', '10.0.0.10');
blockList.addSubnet('8592:757c:efae:4e45::', 64, 'ipv6');

console.log(blockList.check('123.123.123.123'));  // Prints: true
console.log(blockList.check('10.0.0.3'));  // Prints: true
console.log(blockList.check('222.111.111.222'));  // Prints: false

// IPv6 notation for IPv4 addresses works:
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true copy

blockList.rules#

• 型: <string[]>

ブロックリストに追加されたルールのリスト。

クラス: `net.SocketAddress`#

new net.SocketAddress([options])#

• options <Object>
  • address <string> ネットワークアドレス（IPv4またはIPv6文字列）。デフォルト: familyが'ipv4'の場合'127.0.0.1'、familyが'ipv6'の場合'::'。
  • family <string> 'ipv4'または'ipv6'のいずれか。デフォルト: 'ipv4'。
  • flowlabel <number> familyが'ipv6'の場合のみ使用されるIPv6フローラベル。
  • port <number> IPポート。

socketaddress.address#

• 型 <string>

socketaddress.family#

• 型 <string> 'ipv4'または'ipv6'。

socketaddress.flowlabel#

• 型 <number>

socketaddress.port#

• 型 <number>

クラス: net.Server#

• 拡張: <EventEmitter>

このクラスは、TCPまたはIPCサーバーを作成するために使用されます。

new net.Server([options][, connectionListener])#

• options <Object> net.createServer([options][, connectionListener])を参照してください。
• connectionListener <Function> 'connection'イベントのリスナーとして自動的に設定されます。
• 戻り値: <net.Server>

net.Serverは、以下のイベントを持つEventEmitterです。

イベント: 'close'#

サーバーが閉じられたときに発生します。接続が存在する場合は、すべての接続が終了するまでこのイベントは発生しません。

イベント: 'connection'#

• <net.Socket> 接続オブジェクト

新しい接続が確立されたときに発生します。socketはnet.Socketのインスタンスです。

イベント: 'error'#

• <Error>

エラーが発生したときに発生します。net.Socketとは異なり、server.close()を手動で呼び出さない限り、このイベントの直後に'close'イベントは発生しません。server.listen()の解説にある例を参照してください。

イベント: 'listening'#

server.listen()を呼び出した後にサーバーがバインドされたときに発生します。

イベント: 'drop'#

接続数がserver.maxConnectionsの閾値に達すると、サーバーは新しい接続をドロップし、代わりに'drop'イベントを発生させます。TCPサーバーの場合、引数は以下の通りです。それ以外の場合は、引数はundefinedです。

• data <Object> イベントリスナーに渡される引数。
  • localAddress <string> ローカルアドレス。
  • localPort <number> ローカルポート。
  • localFamily <string> ローカルファミリ。
  • remoteAddress <string> リモートアドレス。
  • remotePort <number> リモートポート。
  • remoteFamily <string> リモートIPファミリ。'IPv4'または'IPv6'。

server.address()#

• 戻り値: <Object> | <string> | <null>

IPソケットでリッスンしている場合、バインドされたaddress、アドレスfamily名、およびオペレーティングシステムによって報告されたサーバーのportを返します（OSによって割り当てられたアドレスを取得する場合に、どのポートが割り当てられたかを見つけるのに役立ちます）：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }。

パイプまたはUnixドメインソケットでリッスンしているサーバーの場合、名前は文字列として返されます。

const server = net.createServer((socket) => {
  socket.end('goodbye\n');
}).on('error', (err) => {
  // Handle errors here.
  throw err;
});

// Grab an arbitrary unused port.
server.listen(() => {
  console.log('opened server on', server.address());
}); copy

'listening'イベントが発生する前、またはserver.close()を呼び出した後、server.address()はnullを返します。

server.close([callback])#

• callback <Function> サーバーが閉じられたときに呼び出されます。
• 戻り値: <net.Server>

サーバーが新しい接続を受け入れるのを停止し、既存の接続を維持します。この関数は非同期であり、すべての接続が終了し、サーバーが'close'イベントを発生させると、サーバーは最終的に閉じられます。オプションのcallbackは、'close'イベントが発生するとすぐに呼び出されます。このイベントとは異なり、サーバーが閉じられたときに開いていなかった場合、唯一の引数としてErrorを使用して呼び出されます。

server[Symbol.asyncDispose]()#

server.close()を呼び出し、サーバーが閉じられたときに解決されるPromiseを返します。

server.getConnections(callback)#

• callback <Function>
• 戻り値: <net.Server>

サーバー上の同時接続数を非同期的に取得します。ソケットがフォークに送信された場合に機能します。

コールバックは、2つの引数errとcountを受け取る必要があります。

server.listen()#

接続をリッスンするサーバーを開始します。net.Serverは、リッスン対象に応じてTCPサーバーまたはIPCサーバーになります。

可能なシグネチャ

• server.listen(handle[, backlog][, callback])
• server.listen(options[, callback])
• server.listen(path[, backlog][, callback]) IPCサーバーの場合
• server.listen([port[, host[, backlog]]][, callback]) TCPサーバーの場合

この関数は非同期です。サーバーがリッスンを開始すると、'listening'イベントが発生します。最後のパラメーターcallbackは、'listening'イベントのリスナーとして追加されます。

すべてのlisten()メソッドは、保留中の接続のキューの最大長を指定するためにbacklogパラメーターを取ることができます。実際の長さは、Linux上のtcp_max_syn_backlogやsomaxconnなどのsysctl設定によってOSによって決定されます。このパラメーターのデフォルト値は511（512ではありません）。

すべてのnet.SocketはSO_REUSEADDRに設定されています（詳細はsocket(7)を参照してください）。

最初のserver.listen()呼び出し中にエラーが発生した場合、またはserver.close()が呼び出された場合にのみ、server.listen()メソッドを再度呼び出すことができます。それ以外の場合は、ERR_SERVER_ALREADY_LISTENエラーがスローされます。

リッスン時に発生する最も一般的なエラーの1つはEADDRINUSEです。これは、別のサーバーが既に要求されたport/path/handleでリッスンしている場合に発生します。これを処理する1つの方法は、一定時間後に再試行することです。

server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
}); copy

server.listen(handle[, backlog][, callback])#

• handle <Object>
• backlog <number> server.listen()関数の共通パラメーター
• callback <Function>
• 戻り値: <net.Server>

既にポート、Unixドメインソケット、またはWindows名前付きパイプにバインドされている特定のhandleで接続をリッスンするサーバーを開始します。

handleオブジェクトは、サーバー、ソケット（基になる_handleメンバーを持つもの）、または有効なファイル記述子であるfdメンバーを持つオブジェクトのいずれかになります。

ファイル記述子でのリッスンは、Windowsではサポートされていません。

server.listen(options[, callback])#

• options <Object> 必須。以下のプロパティをサポートします。
  • port <number>
  • host <string>
  • path <string> portが指定されている場合は無視されます。IPC接続のパス識別を参照してください。
  • backlog <number> server.listen()関数の一般的なパラメータです。
  • exclusive <boolean> デフォルト: false
  • readableAll <boolean> IPCサーバーの場合、パイプをすべてのユーザーが読み取り可能にします。デフォルト: false。
  • writableAll <boolean> IPCサーバーの場合、パイプをすべてのユーザーが書き込み可能にします。デフォルト: false。
  • ipv6Only <boolean> TCPサーバーの場合、ipv6Onlyをtrueに設定すると、デュアルスタックサポートが無効になります。つまり、ホスト::へのバインドは0.0.0.0のバインドを引き起こしません。デフォルト: false。
  • signal <AbortSignal> リッスンしているサーバーを閉じるために使用できるAbortSignalです。
• callback <Function> 関数。
• 戻り値: <net.Server>

portが指定されている場合、server.listen([port[, host[, backlog]]][, callback])と同じ動作をします。そうでない場合、pathが指定されている場合、server.listen(path[, backlog][, callback])と同じ動作をします。どちらも指定されていない場合、エラーがスローされます。

exclusiveがfalse（デフォルト）の場合、クラスタワーカーは同じ基盤となるハンドルを使用し、接続処理タスクを共有できます。exclusiveがtrueの場合、ハンドルは共有されず、ポート共有の試行はエラーになります。排他的ポートをリッスンする例を以下に示します。

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true,
}); copy

exclusiveがtrueで基盤となるハンドルが共有されている場合、複数のワーカーが異なるバックログを持つハンドルをクエリすることがあります。この場合、マスタープロセスに最初に渡されたbacklogが使用されます。

ルートとしてIPCサーバーを起動すると、サーバーパスが特権のないユーザーからアクセスできなくなる可能性があります。readableAllとwritableAllを使用すると、すべてのユーザーがサーバーにアクセスできるようになります。

signalオプションが有効になっている場合、対応するAbortControllerで.abort()を呼び出すことは、サーバーで.close()を呼び出すことと同様です。

const controller = new AbortController();
server.listen({
  host: 'localhost',
  port: 80,
  signal: controller.signal,
});
// Later, when you want to close the server.
controller.abort(); copy

server.listen(path[, backlog][, callback])#

• path <string> サーバーがリッスンするパス。IPC接続のパス識別を参照してください。
• backlog <number> server.listen()関数の一般的なパラメータです。
• callback <Function>。
• 戻り値: <net.Server>

指定されたpathで接続をリッスンするIPCサーバーを起動します。

server.listen([port[, host[, backlog]]][, callback])#

• port <number>
• host <string>
• backlog <number> server.listen()関数の一般的なパラメータです。
• callback <Function>。
• 戻り値: <net.Server>

指定されたportとhostで接続をリッスンするTCPサーバーを起動します。

portが省略されているか0の場合、オペレーティングシステムは任意の未使用ポートを割り当てます。これは、'listening'イベントが送信された後、server.address().portを使用して取得できます。

hostが省略されている場合、サーバーはIPv6が使用可能な場合は未指定のIPv6アドレス(::)で、そうでない場合は未指定のIPv4アドレス(0.0.0.0)で接続を受け入れます。

ほとんどのオペレーティングシステムでは、未指定のIPv6アドレス(::)をリッスンすると、net.Serverは未指定のIPv4アドレス(0.0.0.0)もリッスンする可能性があります。

server.listening#

• <boolean> サーバーが接続をリッスンしているかどうかを示します。

server.maxConnections#

• <integer>

サーバーの接続数が多くなった場合に接続を拒否するようにこのプロパティを設定します。

child_process.fork()でソケットが子プロセスに送信された後は、このオプションを使用しないことをお勧めします。

server.ref()#

• 戻り値: <net.Server>

unref()の反対です。以前にunrefされたサーバーでref()を呼び出すと、それが唯一残っているサーバーの場合でも（デフォルトの動作）、プログラムは終了しません。サーバーがrefされている場合、ref()を再度呼び出しても効果はありません。

server.unref()#

• 戻り値: <net.Server>

サーバーでunref()を呼び出すと、それがイベントシステム内の唯一のアクティブなサーバーである場合、プログラムを終了できます。サーバーがすでにunrefされている場合、unref()を再度呼び出しても効果はありません。

クラス: net.Socket#

• 拡張: <stream.Duplex>

このクラスは、TCPソケットまたはストリーミングIPCエンドポイント（Windowsでは名前付きパイプ、それ以外の場合はUnixドメインソケットを使用）の抽象化です。EventEmitterでもあります。

net.Socketはユーザーによって作成され、サーバーと直接やり取りするために使用できます。たとえば、net.createConnection()によって返されるため、ユーザーはそれをサーバーとの通信に使用できます。

また、Node.jsによって作成され、接続が受信されたときにユーザーに渡すこともできます。たとえば、net.Serverで送信された'connection'イベントのリスナーに渡されるため、ユーザーはそれをクライアントとのやり取りに使用できます。

new net.Socket([options])#

• options <Object> 使用可能なオプションは次のとおりです。
  • fd <number> 指定されている場合、指定されたファイルディスクリプターを持つ既存のソケットをラップします。そうでない場合は、新しいソケットが作成されます。
  • allowHalfOpen <boolean> falseに設定されている場合、ソケットは読み取り側が終了すると書き込み側を自動的に終了します。net.createServer()および'end'イベントの詳細については、を参照してください。デフォルト: false。
  • readable <boolean> fdが渡された場合、ソケットでの読み取りを許可します。そうでない場合は無視されます。デフォルト: false。
  • writable <boolean> fdが渡された場合、ソケットでの書き込みを許可します。そうでない場合は無視されます。デフォルト: false。
  • signal <AbortSignal> ソケットを破棄するために使用できるAbort信号です。
• 戻り値: <net.Socket>

新しいソケットオブジェクトを作成します。

新しく作成されたソケットは、connect()先の状況に応じて、TCPソケットまたはストリーミングIPCエンドポイントのどちらかになります。

イベント: 'close'#

• hadError <boolean> ソケットに送信エラーがあった場合true。

ソケットが完全に閉じられたときに一度送信されます。引数hadErrorは、送信エラーのためにソケットが閉じられたかどうかを示すブール値です。

イベント: 'connect'#

ソケット接続が正常に確立されたときに送信されます。net.createConnection()を参照してください。

イベント: 'connectionAttempt'#

• ip <string> ソケットが接続しようとしているIPアドレス。
• port <number> ソケットが接続しようとしているポート。
• family <number> IPアドレスファミリ。IPv6の場合は6、IPv4の場合は4です。

新しい接続試行が開始されたときに送信されます。socket.connect(options)でファミリアウト選択アルゴリズムが有効になっている場合、複数回送信される可能性があります。

イベント: 'connectionAttemptFailed'#

• ip <string> ソケットが接続を試みたIPアドレス。
• port <number> ソケットが接続を試みたポート。
• family <number> IPの種類。IPv6の場合は6、IPv4の場合は4となります。* error <Error> 接続失敗に関連付けられたエラー。

接続試行が失敗したときに発生します。 socket.connect(options) でファミリー自動選択アルゴリズムが有効になっている場合、複数回発生する可能性があります。

イベント: 'connectionAttemptTimeout'#

• ip <string> ソケットが接続を試みたIPアドレス。
• port <number> ソケットが接続を試みたポート。
• family <number> IPアドレスファミリ。IPv6の場合は6、IPv4の場合は4です。

接続試行がタイムアウトしたときに発生します。これは、socket.connect(options) でファミリー自動選択アルゴリズムが有効になっている場合にのみ発生し（複数回発生する可能性があります）。

イベント: 'data'#

• <Buffer> | <string>

データを受信したときに発生します。引数dataはBufferまたはStringとなります。データのエンコーディングはsocket.setEncoding()で設定されます。

Socketが'data'イベントを発生させたときにリスナーがない場合、データは失われます。

イベント: 'drain'#

書き込みバッファが空になったときに発生します。アップロードのスロットリングに使用できます。

参照: socket.write()の戻り値。

イベント: 'end'#

ソケットの反対側が送信の終了をシグナルしたとき、つまりソケットの読み取り可能な側が終了したときに発生します。

デフォルト（allowHalfOpenがfalse）では、ソケットは送信終了パケットを返信し、保留中の書き込みキューを書き込んだ後にファイル記述子を破棄します。しかし、allowHalfOpenをtrueに設定すると、ソケットは書き込み可能な側を自動的にend()せず、ユーザーが任意の量のデータを書き込めるようになります。接続を閉じるには（つまり、FINパケットを返信するには）、ユーザーがend()を明示的に呼び出す必要があります。

イベント: 'error'#

• <Error>

エラーが発生したときに発生します。このイベントの直後に'close'イベントが呼び出されます。

イベント: 'lookup'#

ホスト名を解決した後、接続する前に発生します。Unixソケットには適用されません。

• err <Error> | <null> エラーオブジェクト。 dns.lookup()を参照してください。
• address <string> IPアドレス。
• family <number> | <null> アドレスの種類。dns.lookup()を参照してください。
• host <string> ホスト名。

イベント: 'ready'#

ソケットが使用可能になったときに発生します。

'connect'の直後にトリガーされます。

イベント: 'timeout'#

ソケットが非アクティブのためにタイムアウトした場合に発生します。これは、ソケットがアイドル状態であることを通知するためだけです。ユーザーは手動で接続を閉じる必要があります。

参照: socket.setTimeout().

socket.address()#

• 戻り値: <Object>

バインドされたaddress、アドレスfamily名、およびオペレーティングシステムによって報告されたソケットのportを返します: { port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.autoSelectFamilyAttemptedAddresses#

• <string[]>

このプロパティは、socket.connect(options)でファミリー自動選択アルゴリズムが有効になっている場合にのみ存在し、試行されたアドレスの配列です。

各アドレスは$IP:$PORT形式の文字列です。接続が成功した場合、最後のアドレスはソケットが現在接続されているアドレスです。

socket.bufferSize#

• <integer>

このプロパティは、書き込みのためにバッファリングされた文字数を示します。バッファには、エンコード後の長さがまだ不明な文字列が含まれる場合があります。そのため、この数値はバッファ内のバイト数の近似値にすぎません。

net.Socketには、socket.write()が常に動作するという特性があります。これは、ユーザーが迅速に使い始めるのを助けるためです。コンピューターは常に、ソケットに書き込まれるデータの量に対応できるわけではありません。ネットワーク接続が遅すぎる可能性があります。Node.jsは、ソケットに書き込まれたデータを内部的にキューイングし、可能になったときにワイヤ経由で送信します。

この内部バッファリングの結果、メモリが増加する可能性があります。大きくまたは増大するbufferSizeを経験するユーザーは、socket.pause()とsocket.resume()を使用してプログラム内のデータフローを「スロットル」する必要があります。

socket.bytesRead#

• <integer>

受信したバイト数。

socket.bytesWritten#

• <integer>

送信されたバイト数。

socket.connect()#

指定されたソケットで接続を開始します。

可能なシグネチャ

• socket.connect(options[, connectListener])
• socket.connect(path[, connectListener]) (IPC接続の場合)。
• socket.connect(port[, host][, connectListener]) (TCP接続の場合)。
• 戻り値: <net.Socket> ソケット自体。

この関数は非同期です。接続が確立されると、'connect'イベントが発生します。接続に問題がある場合、'connect'イベントの代わりに、'error'イベントがエラーと共に発生します。'error'リスナーに渡されます。最後のパラメーターconnectListenerが指定されている場合、'connect'イベントのリスナーとして一度だけ追加されます。

この関数は、'close'が発生した後にソケットを再接続する場合にのみ使用してください。それ以外の場合、未定義の動作につながる可能性があります。

socket.connect(options[, connectListener])#

• options <Object>
• connectListener <Function> socket.connect()メソッドの共通パラメーター。'connect'イベントのリスナーとして一度だけ追加されます。
• 戻り値: <net.Socket> ソケット自体。

指定されたソケットで接続を開始します。通常、このメソッドは必要ありません。ソケットはnet.createConnection()で作成および開く必要があります。カスタムソケットを実装する場合にのみ使用してください。

TCP接続の場合、使用可能なoptionsは次のとおりです。

• port <number> 必須。ソケットが接続するポート。
• host <string> ソケットが接続するホスト。デフォルト: 'localhost'。
• localAddress <string> ソケットが接続元とするローカルアドレス。
• localPort <number> ソケットが接続元とするローカルポート。
• family <number>: IPスタックのバージョン。4、6、または0である必要があります。値0は、IPv4アドレスとIPv6アドレスの両方が許可されることを示します。デフォルト: 0。
• hints <number> オプションのdns.lookup()ヒント。
• lookup <Function> カスタムルックアップ関数。デフォルト: dns.lookup().
• noDelay <boolean> trueに設定すると、ソケットが確立された直後にNagleアルゴリズムの使用が無効になります。デフォルト: false。
• keepAlive <boolean> trueに設定すると、接続が確立された直後にソケットでキープアライブ機能が有効になり、socket.setKeepAlive([enable][, initialDelay])で行われるものと同様になります。デフォルト: false。
• keepAliveInitialDelay <number> 正の値に設定すると、アイドル状態のソケットで最初のキープアライブプローブが送信されるまでの初期遅延が設定されます。デフォルト: 0。
• autoSelectFamily <boolean>: trueに設定すると、RFC 8305のセクション5を緩やかに実装したファミリー自動検出アルゴリズムが有効になります。lookupに渡されるallオプションはtrueに設定され、ソケットは取得したIPv6およびIPv4アドレスすべてに順次接続を試み、接続が確立されるまで続行します。最初に返されたAAAAアドレスが最初に試され、次に最初のAアドレス、次に2番目に返されたAAAAアドレスなどが試されます。各接続試行（最後を除く）には、autoSelectFamilyAttemptTimeoutオプションで指定された時間制限が適用され、タイムアウトすると次のアドレスが試されます。familyオプションが0でない場合、またはlocalAddressが設定されている場合は無視されます。少なくとも1つの接続が成功すれば、接続エラーは発生しません。すべての接続試行が失敗した場合、失敗したすべての試行を含む単一のAggregateErrorが発生します。デフォルト: net.getDefaultAutoSelectFamily()
• autoSelectFamilyAttemptTimeout <number>: autoSelectFamilyオプションを使用する場合、次のアドレスを試行する前に接続試行が完了するまで待機するミリ秒単位の時間です。10未満の正の整数に設定されている場合、代わりに値10が使用されます。デフォルト: net.getDefaultAutoSelectFamilyAttemptTimeout()

IPC接続の場合、使用可能なoptionsは次のとおりです。

• path <string> 必須。クライアントが接続するパス。 IPC接続のパス識別を参照してください。指定されている場合、上記のTCP固有のオプションは無視されます。

両方のタイプで使用可能なoptionsは次のとおりです。

• onread <Object> 指定されている場合、受信データは単一のbufferに格納され、データがソケットに到着すると、指定されたcallbackに渡されます。これにより、ストリーミング機能はデータを提供しなくなります。ソケットは通常どおり'error'、'end'、'close'などのイベントを発生させます。pause()やresume()などのメソッドも期待どおりに動作します。
  • buffer <Buffer> | <Uint8Array> | <Function> 受信データを格納するために使用する再利用可能なメモリのチャンク、またはそのようなチャンクを返す関数。
  • callback <Function> この関数は、受信データの各チャンクに対して呼び出されます。この関数には、bufferに書き込まれたバイト数とbufferへの参照という2つの引数が渡されます。この関数からfalseを返すことで、ソケットを暗黙的にpause()します。この関数はグローバルコンテキストで実行されます。

以下は、onreadオプションを使用するクライアントの例です。

const net = require('node:net');
net.connect({
  port: 80,
  onread: {
    // Reuses a 4KiB Buffer for every read from the socket.
    buffer: Buffer.alloc(4 * 1024),
    callback: function(nread, buf) {
      // Received data is available in `buf` from 0 to `nread`.
      console.log(buf.toString('utf8', 0, nread));
    },
  },
}); copy

socket.connect(path[, connectListener])#

• path <string> クライアントが接続するパス。 IPC接続のパス識別を参照してください。
• connectListener <Function> socket.connect()メソッドの共通パラメーター。'connect'イベントのリスナーとして一度だけ追加されます。
• 戻り値: <net.Socket> ソケット自体。

指定されたソケット上でIPC接続を開始します。

optionsとして{ path: path }を使用して呼び出されたsocket.connect(options[, connectListener])へのエイリアスです。

socket.connect(port[, host][, connectListener])#

• port <number> クライアントが接続するポート。
• host <string> クライアントが接続するホスト。
• connectListener <Function> socket.connect()メソッドの共通パラメーター。'connect'イベントのリスナーとして一度だけ追加されます。
• 戻り値: <net.Socket> ソケット自体。

指定されたソケット上でTCP接続を開始します。

optionsとして{port: port, host: host}を使用して呼び出されたsocket.connect(options[, connectListener])へのエイリアスです。

socket.connecting#

• <boolean>

trueの場合、socket.connect(options[, connectListener])が呼び出され、まだ完了していません。ソケットが接続されるまでtrueのままになり、接続されるとfalseに設定され、'connect'イベントが発生します。socket.connect(options[, connectListener])コールバックは'connect'イベントのリスナーであることに注意してください。

socket.destroy([error])#

• error <Object>
• 戻り値: <net.Socket>

このソケットでそれ以上のI/Oアクティビティが行われないようにします。ストリームを破棄し、接続を閉じます。

writable.destroy()の詳細については、こちらを参照してください。

socket.destroyed#

• <boolean> 接続が破棄されているかどうかを示します。接続が破棄されると、それ以上データの転送はできません。

writable.destroyedの詳細については、こちらを参照してください。

socket.destroySoon()#

すべてのデータの書き込み後にソケットを破棄します。'finish'イベントがすでに発生している場合、ソケットはすぐに破棄されます。ソケットがまだ書き込み可能な場合、暗黙的にsocket.end()を呼び出します。

socket.end([data[, encoding]][, callback])#

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> dataがstringの場合にのみ使用されます。デフォルト: 'utf8'。
• callback <Function> ソケットが終了したときのオプションのコールバック。
• 戻り値: <net.Socket> ソケット自体。

ソケットをハーフクローズします。つまり、FINパケットを送信します。サーバーはまだデータを送信する可能性があります。

writable.end()の詳細については、こちらを参照してください。

socket.localAddress#

• <string>

リモートクライアントが接続しているローカルIPアドレスの文字列表現です。たとえば、'0.0.0.0'でリッスンしているサーバーの場合、クライアントが'192.168.1.1'に接続すると、socket.localAddressの値は'192.168.1.1'になります。

socket.localPort#

• <integer>

ローカルポートの数値表現です。たとえば、80または21。

socket.localFamily#

• <string>

ローカルIPファミリーの文字列表現です。'IPv4'または'IPv6'。

socket.pause()#

• 戻り値: <net.Socket> ソケット自体。

データの読み取りを一時停止します。つまり、'data'イベントは発生しません。アップロードを抑制するのに役立ちます。

socket.pending#

• <boolean>

ソケットがまだ接続されていない場合（.connect()がまだ呼び出されていないか、接続処理中である場合（socket.connectingを参照））、これはtrueです。

socket.ref()#

• 戻り値: <net.Socket> ソケット自体。

unref()の反対です。以前にunrefされたソケットでref()を呼び出すと、それが残っている唯一のソケットの場合でも、プログラムは終了しません（デフォルトの動作）。ソケットがrefされている場合、refを再度呼び出しても効果はありません。

socket.remoteAddress#

• <string>

リモートIPアドレスの文字列表現です。たとえば、'74.125.127.100'または'2001:4860:a005::68'。ソケットが破棄されている場合（たとえば、クライアントが切断された場合）、値はundefinedになる可能性があります。

socket.remoteFamily#

• <string>

リモートIPファミリーの文字列表現です。'IPv4'または'IPv6'。ソケットが破棄されている場合（たとえば、クライアントが切断された場合）、値はundefinedになる可能性があります。

socket.remotePort#

• <integer>

リモートポートの数値表現です。たとえば、80または21。ソケットが破棄されている場合（たとえば、クライアントが切断された場合）、値はundefinedになる可能性があります。

socket.resetAndDestroy()#

• 戻り値: <net.Socket>

RSTパケットを送信してTCP接続を閉じ、ストリームを破棄します。このTCPソケットが接続中の場合、接続されるとRSTパケットを送信してTCPソケットを破棄します。そうでない場合、ERR_SOCKET_CLOSEDエラーでsocket.destroyを呼び出します。これがTCPソケットではない場合（パイプなど）、このメソッドを呼び出すと、すぐにERR_INVALID_HANDLE_TYPEエラーが発生します。

socket.resume()#

• 戻り値: <net.Socket> ソケット自体。

socket.pause()を呼び出した後に読み取りを再開します。

socket.setEncoding([encoding])#

• encoding <string>
• 戻り値: <net.Socket> ソケット自体。

読み取り可能なストリームとしてソケットのエンコーディングを設定します。readable.setEncoding()の詳細については、こちらを参照してください。

socket.setKeepAlive([enable][, initialDelay])#

• enable <boolean> デフォルト: false
• initialDelay <number> デフォルト: 0
• 戻り値: <net.Socket> ソケット自体。

キープアライブ機能を有効/無効にし、アイドルソケットで最初のキープアライブプローブが送信される前の初期遅延をオプションで設定します。

initialDelay（ミリ秒単位）を設定して、最後に受信したデータパケットと最初のキープアライブプローブの間の遅延時間を設定します。initialDelayに0を設定すると、値はデフォルト（または以前の）設定から変更されません。

キープアライブ機能を有効にすると、次のソケットオプションが設定されます。

• SO_KEEPALIVE=1
• TCP_KEEPIDLE=initialDelay
• TCP_KEEPCNT=10
• TCP_KEEPINTVL=1

socket.setNoDelay([noDelay])#

• noDelay <boolean> デフォルト：true
• 戻り値: <net.Socket> ソケット自体。

Nagleアルゴリズムの使用を有効/無効にします。

TCP接続が作成されると、Nagleアルゴリズムが有効になります。

Nagleアルゴリズムは、データがネットワーク経由で送信される前に遅延させます。レイテンシを犠牲にしてスループットを最適化しようとします。

noDelayにtrueを渡すか、引数を渡さない場合、ソケットのNagleアルゴリズムが無効になります。noDelayにfalseを渡すと、Nagleアルゴリズムが有効になります。

socket.setTimeout(timeout[, callback])#

• timeout <number>
• callback <Function>
• 戻り値: <net.Socket> ソケット自体。

ソケットの非アクティブ状態がtimeoutミリ秒後にタイムアウトするようにソケットを設定します。デフォルトでは、net.Socketにはタイムアウトがありません。

アイドルタイムアウトがトリガーされると、ソケットは'timeout'イベントを受け取りますが、接続は切断されません。接続を終了するには、ユーザーが手動でsocket.end()またはsocket.destroy()を呼び出す必要があります。

socket.setTimeout(3000);
socket.on('timeout', () => {
  console.log('socket timeout');
  socket.end();
}); copy

timeoutが0の場合、既存のアイドルタイムアウトは無効になります。

オプションのcallbackパラメータは、'timeout'イベントのワンタイムリスナーとして追加されます。

socket.timeout#

• <number> | <undefined>

socket.setTimeout()で設定された、ミリ秒単位のソケットタイムアウトです。タイムアウトが設定されていない場合はundefinedです。

socket.unref()#

• 戻り値: <net.Socket> ソケット自体。

ソケットでunref()を呼び出すと、これがイベントシステムでアクティブな唯一のソケットの場合、プログラムを終了できます。ソケットが既にunrefされている場合、unref()を再度呼び出しても効果はありません。

socket.write(data[, encoding][, callback])#

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> dataがstringの場合のみ使用されます。デフォルト：utf8。
• callback <Function>
• 戻り値: <boolean>

ソケットでデータを送信します。2番目のパラメータは、文字列の場合のエンコーディングを指定します。デフォルトはUTF8エンコーディングです。

データ全体がカーネルバッファに正常にフラッシュされた場合はtrueを返し、データの一部または全部がユーザーメモリにキューに入れられた場合はfalseを返します。'drain'は、バッファが再びフリーになったときに発生します。

オプションのcallbackパラメータは、データが最終的に書き込まれたときに実行されますが、すぐに実行されるとは限りません。

詳細については、Writableストリームwrite()メソッドを参照してください。

socket.readyState#

• <string>

このプロパティは、接続の状態を文字列で表します。

• ストリームが接続中の場合、socket.readyStateはopeningです。
• ストリームが読み取り可能で書き込み可能な場合、openです。
• ストリームが読み取り可能で書き込み不可能な場合、readOnlyです。
• ストリームが読み取り不可能で書き込み不可能な場合、writeOnlyです。

net.connect()#

net.createConnection()へのエイリアスです。

可能なシグネチャ

• net.connect(options[, connectListener])
• IPC接続用のnet.connect(path[, connectListener])。
• TCP接続用のnet.connect(port[, host][, connectListener])。

net.connect(options[, connectListener])#

• options <Object>
• connectListener <Function>
• 戻り値: <net.Socket>

net.createConnection(options[, connectListener])へのエイリアスです。

net.connect(path[, connectListener])#

• path <string>
• connectListener <Function>
• 戻り値: <net.Socket>

net.createConnection(path[, connectListener])へのエイリアスです。

net.connect(port[, host][, connectListener])#

• port <number>
• host <string>
• connectListener <Function>
• 戻り値: <net.Socket>

net.createConnection(port[, host][, connectListener])へのエイリアスです。

net.createConnection()#

新しいnet.Socketを作成し、socket.connect()で接続をすぐに開始してから、接続を開始するnet.Socketを返すファクトリ関数です。

接続が確立されると、返されたソケットで'connect'イベントが発生します。最後のパラメータconnectListenerが指定されている場合、'connect'イベントのリスナーとして一度だけ追加されます。

可能なシグネチャ

• net.createConnection(options[, connectListener])
• IPC接続用のnet.createConnection(path[, connectListener])。
• TCP接続用のnet.createConnection(port[, host][, connectListener])。

net.connect()関数は、この関数のエイリアスです。

net.createConnection(options[, connectListener])#

• options <Object> 必須。 new net.Socket([options])呼び出しとsocket.connect(options[, connectListener])メソッドの両方に渡されます。
• connectListener <Function> net.createConnection()関数の共通パラメータです。指定されている場合、返されたソケットの'connect'イベントのリスナーとして一度だけ追加されます。
• 戻り値: <net.Socket> 接続を開始するために使用される新しく作成されたソケット。

使用可能なオプションについては、new net.Socket([options])とsocket.connect(options[, connectListener])を参照してください。

追加オプション

• timeout <number> 設定されている場合、ソケットが作成された後、接続を開始する前に、socket.setTimeout(timeout)を呼び出すために使用されます。

net.createServer()セクションで説明されているエコーサーバーのクライアントの例を次に示します。

const net = require('node:net');
const client = net.createConnection({ port: 8124 }, () => {
  // 'connect' listener.
  console.log('connected to server!');
  client.write('world!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('disconnected from server');
}); copy

ソケット/tmp/echo.sockに接続するには

const client = net.createConnection({ path: '/tmp/echo.sock' }); copy

net.createConnection(path[, connectListener])#

• path <string> ソケットが接続するパス。 socket.connect(path[, connectListener])に渡されます。IPC接続のパスを特定するを参照してください。
• connectListener <Function> net.createConnection()関数の共通パラメータであり、開始ソケットの'connect'イベントの「一度だけ」リスナーです。socket.connect(path[, connectListener])に渡されます。
• 戻り値: <net.Socket> 接続を開始するために使用される新しく作成されたソケット。

IPC接続を開始します。

この関数は、すべてのオプションをデフォルトに設定した新しいnet.Socketを作成し、socket.connect(path[, connectListener])で接続をすぐに開始してから、接続を開始するnet.Socketを返します。

net.createConnection(port[, host][, connectListener])#

• port <number> ソケットが接続するポート。 socket.connect(port[, host][, connectListener])に渡されます。
• host <string> ソケットが接続するホスト。 socket.connect(port[, host][, connectListener])に渡されます。デフォルト：'localhost'。
• connectListener <Function> net.createConnection()関数の共通パラメータであり、開始ソケットの'connect'イベントの「一度だけ」リスナーです。socket.connect(port[, host][, connectListener])に渡されます。
• 戻り値: <net.Socket> 接続を開始するために使用される新しく作成されたソケット。

TCP接続を開始します。

この関数は、すべてのオプションをデフォルトに設定した新しいnet.Socketを作成し、socket.connect(port[, host][, connectListener])で接続をすぐに開始してから、接続を開始するnet.Socketを返します。

net.createServer([options][, connectionListener])#

• options <Object>

  • allowHalfOpen <boolean> falseに設定されている場合、読み取り側が終了すると、ソケットは書き込み側を自動的に終了します。デフォルト：false。
  • highWaterMark <number> すべてのnet.SocketのreadableHighWaterMarkとwritableHighWaterMarkをオプションでオーバーライドします。デフォルト：stream.getDefaultHighWaterMark()を参照してください。
  • pauseOnConnect <boolean> 受信接続時にソケットを一時停止するかどうかを示します。デフォルト：false。
  • noDelay <boolean> trueに設定されている場合、新しい受信接続が受信された直後にNagleアルゴリズムの使用が無効になります。デフォルト：false。
  • keepAlive <boolean> 新しい着信接続が受信された直後に、ソケットでキープアライブ機能を有効にします。 socket.setKeepAlive([enable][, initialDelay])で行われる処理と同様です。 **デフォルト値:** false。
  • keepAliveInitialDelay <number> 正の値に設定すると、アイドル状態のソケットで最初のキープアライブプローブが送信されるまでの初期遅延が設定されます。デフォルト: 0。

• connectionListener <Function> 'connection'イベントのリスナーとして自動的に設定されます。

• 戻り値: <net.Server>

新しいTCPまたはIPCサーバーを作成します。

allowHalfOpenがtrueに設定されている場合、ソケットの反対側が伝送の終了をシグナルで通知すると、socket.end()が明示的に呼び出されるまで、サーバーは伝送終了の応答を送信しません。たとえば、TCPのコンテキストでは、FINパケットを受信しても、socket.end()が明示的に呼び出されるまでFINパケットは送信されません。それまでは、接続はハーフクローズド状態（読み取り不可だが書き込み可能）になります。'end'イベントとRFC 1122（4.2.2.13項）を参照してください。

pauseOnConnectがtrueに設定されている場合、着信接続ごとに関連付けられたソケットは一時停止され、そのハンドルからデータは読み取られません。これにより、元のプロセスがデータを読み取る前に、プロセス間で接続を渡すことができます。一時停止されたソケットからのデータの読み取りを開始するには、socket.resume()を呼び出します。

サーバーは、listen()の対象に応じて、TCPサーバーまたはIPCサーバーになります。

ポート8124で接続をリッスンするTCPエコーサーバーの例を示します。

const net = require('node:net');
const server = net.createServer((c) => {
  // 'connection' listener.
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
}); copy

telnetを使用してテストします。

telnet localhost 8124 copy

/tmp/echo.sockソケットでリッスンするには

server.listen('/tmp/echo.sock', () => {
  console.log('server bound');
}); copy

ncを使用してUnixドメインソケットサーバーに接続します。

nc -U /tmp/echo.sock copy

net.getDefaultAutoSelectFamily()#

socket.connect(options)のautoSelectFamilyオプションの現在のデフォルト値を取得します。コマンドラインオプション--no-network-family-autoselectionが指定されていない限り、初期デフォルト値はtrueです。

• 戻り値: <boolean> autoSelectFamilyオプションの現在のデフォルト値。

net.setDefaultAutoSelectFamily(value)#

socket.connect(options)のautoSelectFamilyオプションのデフォルト値を設定します。

• value <boolean> 新しいデフォルト値。初期デフォルト値はfalseです。

net.getDefaultAutoSelectFamilyAttemptTimeout()#

socket.connect(options)のautoSelectFamilyAttemptTimeoutオプションの現在のデフォルト値を取得します。初期デフォルト値は250です。

• 戻り値: <number> autoSelectFamilyAttemptTimeoutオプションの現在のデフォルト値。

net.setDefaultAutoSelectFamilyAttemptTimeout(value)#

socket.connect(options)のautoSelectFamilyAttemptTimeoutオプションのデフォルト値を設定します。

• value <number> 新しいデフォルト値。正の数でなければなりません。10未満の場合、代わりに10が使用されます。初期デフォルト値は250です。

net.isIP(input)#

• input <string>
• 戻り値: <integer>

inputがIPv6アドレスの場合、6を返します。inputが先頭にゼロのないドット10進表記のIPv4アドレスの場合、4を返します。それ以外の場合は、0を返します。

net.isIP('::1'); // returns 6
net.isIP('127.0.0.1'); // returns 4
net.isIP('127.000.000.001'); // returns 0
net.isIP('127.0.0.1/24'); // returns 0
net.isIP('fhqwhgads'); // returns 0 copy

net.isIPv4(input)#

• input <string>
• 戻り値: <boolean>

inputが先頭にゼロのないドット10進表記のIPv4アドレスの場合、trueを返します。それ以外の場合は、falseを返します。

net.isIPv4('127.0.0.1'); // returns true
net.isIPv4('127.000.000.001'); // returns false
net.isIPv4('127.0.0.1/24'); // returns false
net.isIPv4('fhqwhgads'); // returns false copy

net.isIPv6(input)#

• input <string>
• 戻り値: <boolean>

inputがIPv6アドレスの場合、trueを返します。それ以外の場合は、falseを返します。

net.isIPv6('::1'); // returns true
net.isIPv6('fhqwhgads'); // returns false copy