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

クラス: http.Agent#

Agentは、HTTPクライアントの接続の持続性と再利用を管理する役割を担います。特定のホストとポートの保留中のリクエストのキューを維持し、キューが空になるまで、各リクエストに単一のソケット接続を再利用します。キューが空になると、ソケットは破棄されるか、プールに入れられて、同じホストとポートへのリクエストに再度使用するために保持されます。破棄されるかプールされるかは、keepAlive オプションによって異なります。

プールされた接続では、TCP Keep-Aliveが有効になっていますが、サーバーはアイドル状態の接続を閉じることがあります。その場合、プールから削除され、そのホストとポートに対して新しいHTTPリクエストが行われると、新しい接続が作成されます。サーバーは、同じ接続で複数のリクエストを許可しない場合もあります。その場合、リクエストごとに接続を再作成する必要があり、プールすることはできません。Agentは依然としてそのサーバーにリクエストを行いますが、各リクエストは新しい接続で行われます。

クライアントまたはサーバーによって接続が閉じられると、プールから削除されます。プール内の未使用のソケットは、未処理のリクエストがない場合にNode.jsプロセスが実行され続けないように、unrefされます。（socket.unref()を参照）。

未使用のソケットはOSリソースを消費するため、使用しなくなったAgentインスタンスはdestroy()することが推奨されます。

ソケットは、ソケットが'close'イベントまたは'agentRemove'イベントを発行すると、エージェントから削除されます。1つのHTTPリクエストをエージェントに保持せずに長時間開いたままにする場合は、次のような操作を行うことができます。

http.get(options, (res) => {
  // Do stuff
}).on('socket', (socket) => {
  socket.emit('agentRemove');
}); copy

エージェントは個々のリクエストにも使用できます。http.get()またはhttp.request()関数へのオプションとして{agent: false}を指定すると、デフォルトオプションの1回限りのAgentがクライアント接続に使用されます。

agent:false:

http.get({
  hostname: 'localhost',
  port: 80,
  path: '/',
  agent: false,  // Create a new agent just for this one request
}, (res) => {
  // Do stuff with response
}); copy

new Agent([options])#

• options <Object> エージェントに設定する構成可能なオプションのセット。次のフィールドを持つことができます。
  • keepAlive <boolean> 保留中のリクエストがない場合でもソケットを保持し、TCP接続を再確立することなく、将来のリクエストに使用できるようにします。Connectionヘッダーのkeep-alive値と混同しないでください。Connection: keep-aliveヘッダーは、Connectionヘッダーが明示的に指定されている場合、またはkeepAliveオプションとmaxSocketsオプションがそれぞれfalseとInfinityに設定されている場合を除き、エージェントを使用している場合は常に送信されます。この場合、Connection: closeが使用されます。デフォルト: false。
  • keepAliveMsecs <number> keepAliveオプションを使用する場合、TCP Keep-Aliveパケットの初期遅延を指定します。keepAliveオプションがfalseまたはundefinedの場合は無視されます。デフォルト: 1000。
  • maxSockets <number> ホストごとに許可される最大ソケット数。同じホストが複数の同時接続を開く場合、maxSockets の値に達するまで、各リクエストは新しいソケットを使用します。ホストが maxSockets より多くの接続を開こうとすると、追加のリクエストは保留リクエストキューに入り、既存の接続が終了するとアクティブな接続状態になります。これにより、特定のホストからのアクティブな接続は、常に最大で maxSockets になります。デフォルト: Infinity。
  • maxTotalSockets <number> すべてのホストに対して許可されるソケットの合計最大数。最大値に達するまで、各リクエストは新しいソケットを使用します。デフォルト: Infinity。
  • maxFreeSockets <number> ホストごとに空き状態にしておく最大ソケット数。keepAlive が true に設定されている場合にのみ関連します。デフォルト: 256。
  • scheduling <string> 次に使用する空きソケットを選択する際に適用するスケジューリング戦略。'fifo' または 'lifo' を指定できます。2 つのスケジューリング戦略の主な違いは、'lifo' が最後に使用されたソケットを選択するのに対し、'fifo' は最も古くに使用されたソケットを選択することです。1 秒あたりのリクエストレートが低い場合、'lifo' スケジューリングでは、非アクティブのためにサーバーによって閉じられた可能性のあるソケットを選択するリスクが低くなります。1 秒あたりのリクエストレートが高い場合、'fifo' スケジューリングはオープンソケットの数を最大化しますが、'lifo' スケジューリングは可能な限り低く抑えます。デフォルト: 'lifo'。
  • timeout <number> ソケットのタイムアウト（ミリ秒単位）。これは、ソケットが作成されるときにタイムアウトを設定します。

socket.connect() の options もサポートされています。

http.request() で使用されるデフォルトの http.globalAgent は、これらの値すべてがそれぞれのデフォルト値に設定されています。

これらを構成するには、カスタム http.Agent インスタンスを作成する必要があります。

import { Agent, request } from 'node:http';
const keepAliveAgent = new Agent({ keepAlive: true });
options.agent = keepAliveAgent;
request(options, onResponseCallback);const http = require('node:http');
const keepAliveAgent = new http.Agent({ keepAlive: true });
options.agent = keepAliveAgent;
http.request(options, onResponseCallback);copy

agent.createConnection(options[, callback])#

• options <Object> 接続の詳細を含むオプション。オプションの形式については、net.createConnection() を確認してください
• callback <Function> 作成されたソケットを受け取るコールバック関数
• 戻り値: <stream.Duplex>

HTTPリクエストに使用するソケット/ストリームを生成します。

デフォルトでは、この関数は net.createConnection() と同じです。ただし、カスタムエージェントは、より柔軟性が必要な場合に、このメソッドをオーバーライドできます。

ソケット/ストリームは、この関数からソケット/ストリームを返すか、ソケット/ストリームを callback に渡すことによって、2 つの方法のいずれかで提供できます。

ユーザーが <net.Socket> 以外のソケットタイプを指定しない限り、このメソッドは <net.Socket> クラスのインスタンス（<stream.Duplex> のサブクラス）を返すことが保証されています。

callback のシグネチャは (err, stream) です。

agent.keepSocketAlive(socket)#

• socket <stream.Duplex>

socket がリクエストから切り離され、Agent によって永続化される可能性がある場合に呼び出されます。デフォルトの動作は次のとおりです。

socket.setKeepAlive(true, this.keepAliveMsecs);
socket.unref();
return true; copy

このメソッドは、特定の Agent サブクラスによってオーバーライドできます。このメソッドが偽の値を返す場合、ソケットは次のリクエストで使用するために永続化されるのではなく破棄されます。

socket 引数は、<net.Socket>（<stream.Duplex> のサブクラス）のインスタンスにすることができます。

agent.reuseSocket(socket, request)#

• socket <stream.Duplex>
• request <http.ClientRequest>

keep-alive オプションのために永続化された後、socket が request にアタッチされるときに呼び出されます。デフォルトの動作は次のとおりです。

socket.ref(); copy

このメソッドは、特定の Agent サブクラスによってオーバーライドできます。

socket 引数は、<net.Socket>（<stream.Duplex> のサブクラス）のインスタンスにすることができます。

agent.destroy()#

エージェントが現在使用しているすべてのソケットを破棄します。

通常、これを行う必要はありません。ただし、keepAlive が有効になっているエージェントを使用している場合は、不要になったときにエージェントを明示的にシャットダウンするのが最適です。そうしないと、サーバーがそれらを終了するまでに、ソケットがかなり長い間開いたままになる可能性があります。

agent.freeSockets#

• <Object>

keepAlive が有効になっている場合に、エージェントによる使用を現在待機しているソケットの配列を含むオブジェクト。変更しないでください。

freeSockets リスト内のソケットは、'timeout' で自動的に破棄され、配列から削除されます。

agent.getName([options])#

• options <Object> 名前生成のための情報を提供するオプションのセット
  • host <string> リクエストを発行するサーバーのドメイン名または IP アドレス
  • port <number> リモートサーバーのポート
  • localAddress <string> リクエストを発行するときにネットワーク接続をバインドするためのローカルインターフェイス
  • family <integer> これが undefined と等しくない場合は、4 または 6 である必要があります。
• 戻り値: <string>

リクエストオプションのセットに対して一意の名前を取得して、接続を再利用できるかどうかを判断します。HTTP エージェントの場合、これは host:port:localAddress または host:port:localAddress:family を返します。HTTPS エージェントの場合、名前には、ソケットの再利用可能性を決定する CA、証明書、暗号、およびその他の HTTPS/TLS 固有のオプションが含まれます。

agent.maxFreeSockets#

• <number>

デフォルトでは 256 に設定されています。keepAlive が有効になっているエージェントの場合、これは空き状態で開いたままになるソケットの最大数を設定します。

agent.maxSockets#

• <number>

デフォルトでは Infinity に設定されています。エージェントがオリジンごとに開くことができる同時ソケットの数を決定します。オリジンは、agent.getName() の戻り値です。

agent.maxTotalSockets#

• <number>

デフォルトでは Infinity に設定されています。エージェントが開くことができる同時ソケットの数を決定します。maxSockets とは異なり、このパラメーターはすべてのオリジンに適用されます。

agent.requests#

• <Object>

まだソケットに割り当てられていないリクエストのキューを含むオブジェクト。変更しないでください。

agent.sockets#

• <Object>

現在エージェントで使用されているソケットの配列を含むオブジェクト。変更しないでください。

クラス: http.ClientRequest#

• 拡張: <http.OutgoingMessage>

このオブジェクトは内部的に作成され、http.request() から返されます。これは、ヘッダーがすでにキューに入れられている進行中のリクエストを表します。ヘッダーは、setHeader(name, value)、getHeader(name)、removeHeader(name) API を使用して変更可能です。実際のヘッダーは、最初のデータチャンクとともに、または request.end() を呼び出すときに送信されます。

応答を取得するには、リクエストオブジェクトに 'response' のリスナーを追加します。応答ヘッダーが受信されると、リクエストオブジェクトから 'response' が発行されます。'response' イベントは、http.IncomingMessage のインスタンスである 1 つの引数で実行されます。

'response' イベント中に、応答オブジェクトにリスナーを追加できます。特に、'data' イベントをリッスンします。

'response' ハンドラーが追加されていない場合、応答は完全に破棄されます。ただし、'response' イベントハンドラーが追加されている場合は、応答オブジェクトからのデータを、'readable' イベントが発生するたびに response.read() を呼び出すか、'data' ハンドラーを追加するか、または .resume() メソッドを呼び出すことによって消費する必要があります。データが消費されるまで、'end' イベントは発生しません。また、データが読み取られるまで、メモリを消費し、最終的に「プロセスがメモリ不足」エラーにつながる可能性があります。

後方互換性のため、res は 'error' リスナーが登録されている場合にのみ 'error' を発行します。

応答本体のサイズを制限するには、Content-Length ヘッダーを設定します。response.strictContentLength が true に設定されている場合、Content-Length ヘッダーの値が一致しないと、code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH' で識別される Error がスローされます。

Content-Length の値は、文字数ではなくバイト数にする必要があります。Buffer.byteLength() を使用して、本体の長さをバイト単位で決定します。

イベント: 'abort'#

リクエストがクライアントによって中止されたときに発行されます。このイベントは、abort() の最初の呼び出しでのみ発行されます。

イベント: 'close'#

リクエストが完了したか、または基盤となる接続が（レスポンスが完了する前に）途中で終了したことを示します。

イベント: 'connect'#

• response <http.IncomingMessage>
• socket <stream.Duplex>
• head <Buffer>

サーバーがCONNECTメソッドでリクエストに応答するたびに発生します。このイベントがリッスンされていない場合、CONNECTメソッドを受信するクライアントは接続を閉じられます。

このイベントは、ユーザーが<net.Socket>以外のソケットタイプを指定しない限り、<net.Socket>クラス（<stream.Duplex>のサブクラス）のインスタンスを渡されることが保証されています。

'connect'イベントをリッスンする方法を示すクライアントとサーバーのペア

import { createServer, request } from 'node:http';
import { connect } from 'node:net';
import { URL } from 'node:url';

// Create an HTTP tunneling proxy
const proxy = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // Connect to an origin server
  const { port, hostname } = new URL(`http://${req.url}`);
  const serverSocket = connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node.js-Proxy\r\n' +
                    '\r\n');
    serverSocket.write(head);
    serverSocket.pipe(clientSocket);
    clientSocket.pipe(serverSocket);
  });
});

// Now that proxy is running
proxy.listen(1337, '127.0.0.1', () => {

  // Make a request to a tunneling proxy
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  };

  const req = request(options);
  req.end();

  req.on('connect', (res, socket, head) => {
    console.log('got connected!');

    // Make a request over an HTTP tunnel
    socket.write('GET / HTTP/1.1\r\n' +
                 'Host: www.google.com:80\r\n' +
                 'Connection: close\r\n' +
                 '\r\n');
    socket.on('data', (chunk) => {
      console.log(chunk.toString());
    });
    socket.on('end', () => {
      proxy.close();
    });
  });
});const http = require('node:http');
const net = require('node:net');
const { URL } = require('node:url');

// Create an HTTP tunneling proxy
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // Connect to an origin server
  const { port, hostname } = new URL(`http://${req.url}`);
  const serverSocket = net.connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node.js-Proxy\r\n' +
                    '\r\n');
    serverSocket.write(head);
    serverSocket.pipe(clientSocket);
    clientSocket.pipe(serverSocket);
  });
});

// Now that proxy is running
proxy.listen(1337, '127.0.0.1', () => {

  // Make a request to a tunneling proxy
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  };

  const req = http.request(options);
  req.end();

  req.on('connect', (res, socket, head) => {
    console.log('got connected!');

    // Make a request over an HTTP tunnel
    socket.write('GET / HTTP/1.1\r\n' +
                 'Host: www.google.com:80\r\n' +
                 'Connection: close\r\n' +
                 '\r\n');
    socket.on('data', (chunk) => {
      console.log(chunk.toString());
    });
    socket.on('end', () => {
      proxy.close();
    });
  });
});copy

イベント: 'continue'#

サーバーが「Expect: 100-continue」を含むリクエストに対して、通常は'100 Continue' HTTPレスポンスを送信したときに発生します。これは、クライアントがリクエストボディを送信する必要があるという指示です。

イベント: 'finish'#

リクエストが送信されたときに発生します。より具体的には、このイベントは、レスポンスヘッダーとボディの最後のセグメントがネットワークを介した送信のためにオペレーティングシステムに渡されたときに発生します。これは、サーバーが何かを受信したことを意味するものではありません。

イベント: 'information'#

• info <Object>
  • httpVersion <string>
  • httpVersionMajor <integer>
  • httpVersionMinor <integer>
  • statusCode <integer>
  • statusMessage <string>
  • headers <Object>
  • rawHeaders <string[]>

サーバーが1xxの中間レスポンス（101 Upgradeを除く）を送信したときに発生します。このイベントのリスナーは、HTTPバージョン、ステータスコード、ステータスメッセージ、キーと値のヘッダーオブジェクト、および生のヘッダー名とその値が続く配列を含むオブジェクトを受け取ります。

import { request } from 'node:http';

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request',
};

// Make a request
const req = request(options);
req.end();

req.on('information', (info) => {
  console.log(`Got information prior to main response: ${info.statusCode}`);
});const http = require('node:http');

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request',
};

// Make a request
const req = http.request(options);
req.end();

req.on('information', (info) => {
  console.log(`Got information prior to main response: ${info.statusCode}`);
});copy

101 Upgradeステータスは、Webソケット、インプレースTLSアップグレード、HTTP 2.0など、従来のHTTPリクエスト/レスポンスチェーンからの逸脱のため、このイベントを発生させません。101 Upgrade通知を受け取るには、代わりに'upgrade'イベントをリッスンしてください。

イベント: 'response'#

• response <http.IncomingMessage>

このリクエストに対するレスポンスが受信されたときに発生します。このイベントは一度だけ発生します。

イベント: 'socket'#

• socket <stream.Duplex>

このイベントは、ユーザーが<net.Socket>以外のソケットタイプを指定しない限り、<net.Socket>クラス（<stream.Duplex>のサブクラス）のインスタンスを渡されることが保証されています。

イベント: 'timeout'#

基盤となるソケットが非アクティブ状態からタイムアウトしたときに発生します。これは、ソケットがアイドル状態になったことを通知するだけです。リクエストは手動で破棄する必要があります。

参考: request.setTimeout()。

イベント: 'upgrade'#

• response <http.IncomingMessage>
• socket <stream.Duplex>
• head <Buffer>

サーバーがアップグレードでリクエストに応答するたびに発生します。このイベントがリッスンされておらず、レスポンスステータスコードが101 Switching Protocolsの場合、アップグレードヘッダーを受信するクライアントは接続を閉じられます。

このイベントは、ユーザーが<net.Socket>以外のソケットタイプを指定しない限り、<net.Socket>クラス（<stream.Duplex>のサブクラス）のインスタンスを渡されることが保証されています。

'upgrade'イベントをリッスンする方法を示すクライアントサーバーペア。

import http from 'node:http';
import process from 'node:process';

// Create an HTTP server
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
server.on('upgrade', (req, socket, head) => {
  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
               'Upgrade: WebSocket\r\n' +
               'Connection: Upgrade\r\n' +
               '\r\n');

  socket.pipe(socket); // echo back
});

// Now that server is running
server.listen(1337, '127.0.0.1', () => {

  // make a request
  const options = {
    port: 1337,
    host: '127.0.0.1',
    headers: {
      'Connection': 'Upgrade',
      'Upgrade': 'websocket',
    },
  };

  const req = http.request(options);
  req.end();

  req.on('upgrade', (res, socket, upgradeHead) => {
    console.log('got upgraded!');
    socket.end();
    process.exit(0);
  });
});const http = require('node:http');

// Create an HTTP server
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
server.on('upgrade', (req, socket, head) => {
  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
               'Upgrade: WebSocket\r\n' +
               'Connection: Upgrade\r\n' +
               '\r\n');

  socket.pipe(socket); // echo back
});

// Now that server is running
server.listen(1337, '127.0.0.1', () => {

  // make a request
  const options = {
    port: 1337,
    host: '127.0.0.1',
    headers: {
      'Connection': 'Upgrade',
      'Upgrade': 'websocket',
    },
  };

  const req = http.request(options);
  req.end();

  req.on('upgrade', (res, socket, upgradeHead) => {
    console.log('got upgraded!');
    socket.end();
    process.exit(0);
  });
});copy

request.abort()#

リクエストを中止としてマークします。これを呼び出すと、レスポンスに残っているデータが破棄され、ソケットが破棄されます。

request.aborted#

• <boolean>

リクエストが中止された場合、request.abortedプロパティはtrueになります。

request.connection#

• <stream.Duplex>

request.socketを参照してください。

request.cork()#

writable.cork()を参照してください。

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

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• 戻り値: <this>

リクエストの送信を完了します。ボディの未送信部分がある場合は、それらをストリームにフラッシュします。リクエストがチャンクされている場合は、ターミネートの'0\r\n\r\n'を送信します。

dataが指定されている場合は、request.write(data, encoding)を呼び出し、その後にrequest.end(callback)を呼び出すのと同じです。

callbackが指定されている場合は、リクエストストリームが終了したときに呼び出されます。

request.destroy([error])#

• error <Error> オプション、'error'イベントで発生させるエラー。
• 戻り値: <this>

リクエストを破棄します。オプションで'error'イベントを発生させ、'close'イベントを発生させます。これを呼び出すと、レスポンスに残っているデータが破棄され、ソケットが破棄されます。

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

request.destroyed#

• <boolean>

request.destroy()が呼び出された後、trueになります。

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

request.finished#

• <boolean>

request.end()が呼び出された場合、request.finishedプロパティはtrueになります。リクエストがhttp.get()を介して開始された場合、request.end()は自動的に呼び出されます。

request.flushHeaders()#

リクエストヘッダーをフラッシュします。

効率上の理由から、Node.jsは通常、request.end()が呼び出されるか、最初のリクエストデータのチャンクが書き込まれるまで、リクエストヘッダーをバッファリングします。その後、リクエストヘッダーとデータを単一のTCPパケットにパックしようとします。

これは通常望ましい（TCPラウンドトリップが節約される）のですが、最初がデータがかなり後まで送信されない場合はそうではありません。request.flushHeaders()は、最適化をバイパスしてリクエストを開始します。

request.getHeader(name)#

• name <string>
• 戻り値: <any>

リクエストのヘッダーを読み取ります。名前は大文字と小文字が区別されません。戻り値の型は、request.setHeader()に渡された引数によって異なります。

request.setHeader('content-type', 'text/html');
request.setHeader('Content-Length', Buffer.byteLength(body));
request.setHeader('Cookie', ['type=ninja', 'language=javascript']);
const contentType = request.getHeader('Content-Type');
// 'contentType' is 'text/html'
const contentLength = request.getHeader('Content-Length');
// 'contentLength' is of type number
const cookie = request.getHeader('Cookie');
// 'cookie' is of type string[] copy

request.getHeaderNames()#

• 戻り値: <string[]>

現在の送信ヘッダーの一意の名前を含む配列を返します。すべてのヘッダー名は小文字です。

request.setHeader('Foo', 'bar');
request.setHeader('Cookie', ['foo=bar', 'bar=baz']);

const headerNames = request.getHeaderNames();
// headerNames === ['foo', 'cookie'] copy

request.getHeaders()#

• 戻り値: <Object>

現在の送信ヘッダーの浅いコピーを返します。浅いコピーが使用されるため、さまざまなヘッダー関連のhttpモジュールメソッドをさらに呼び出すことなく、配列値を変更できます。返されるオブジェクトのキーはヘッダー名であり、値はそれぞれのヘッダー値です。すべてのヘッダー名は小文字です。

request.getHeaders()メソッドによって返されるオブジェクトは、JavaScriptのObjectからプロトタイプ的に継承しません。これは、obj.toString()、obj.hasOwnProperty()などの典型的なObjectメソッドが定義されておらず、*動作しない*ことを意味します。

request.setHeader('Foo', 'bar');
request.setHeader('Cookie', ['foo=bar', 'bar=baz']);

const headers = request.getHeaders();
// headers === { foo: 'bar', 'cookie': ['foo=bar', 'bar=baz'] } copy

request.getRawHeaderNames()#

• 戻り値: <string[]>

現在の送信生のヘッダーの一意の名前を含む配列を返します。ヘッダー名は、設定されている正確な大文字と小文字で返されます。

request.setHeader('Foo', 'bar');
request.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headerNames = request.getRawHeaderNames();
// headerNames === ['Foo', 'Set-Cookie'] copy

request.hasHeader(name)#

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

nameで識別されるヘッダーが送信ヘッダーに現在設定されている場合、trueを返します。ヘッダー名の照合では、大文字と小文字が区別されません。

const hasContentType = request.hasHeader('content-type'); copy

request.maxHeadersCount#

• <number> デフォルト: 2000

最大レスポンスヘッダー数を制限します。0に設定すると、制限は適用されません。

request.path#

• <string> リクエストパス。

request.method#

• <string> リクエストメソッド。

request.host#

• <string> リクエストホスト。

request.protocol#

• <string> リクエストプロトコル。

request.removeHeader(name)#

• name <string>

ヘッダーオブジェクトにすでに定義されているヘッダーを削除します。

request.removeHeader('Content-Type'); copy

request.reusedSocket#

• <boolean> リクエストが再利用されたソケットを通じて送信されたかどうか。

keep-aliveが有効なエージェントを介してリクエストを送信する場合、基盤となるソケットが再利用される可能性があります。ただし、サーバーが不運なタイミングで接続を閉じると、クライアントは 'ECONNRESET' エラーに遭遇する可能性があります。

import http from 'node:http';

// Server has a 5 seconds keep-alive timeout by default
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // Adapting a keep-alive agent
  http.get('https://127.0.0.1:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Do nothing
    });
  });
}, 5000); // Sending request on 5s interval so it's easy to hit idle timeoutconst http = require('node:http');

// Server has a 5 seconds keep-alive timeout by default
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // Adapting a keep-alive agent
  http.get('https://127.0.0.1:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Do nothing
    });
  });
}, 5000); // Sending request on 5s interval so it's easy to hit idle timeoutcopy

リクエストがソケットを再利用したかどうかをマークすることで、それに基づいて自動エラー再試行を行うことができます。

import http from 'node:http';
const agent = new http.Agent({ keepAlive: true });

function retriableRequest() {
  const req = http
    .get('https://127.0.0.1:3000', { agent }, (res) => {
      // ...
    })
    .on('error', (err) => {
      // Check if retry is needed
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();const http = require('node:http');
const agent = new http.Agent({ keepAlive: true });

function retriableRequest() {
  const req = http
    .get('https://127.0.0.1:3000', { agent }, (res) => {
      // ...
    })
    .on('error', (err) => {
      // Check if retry is needed
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();copy

request.setHeader(name, value)#

• name <string>
• value <any>

ヘッダーオブジェクトに対して単一のヘッダー値を設定します。送信されるヘッダーにこのヘッダーが既に存在する場合、その値は置き換えられます。同じ名前の複数のヘッダーを送信するには、ここで文字列の配列を使用します。文字列以外の値は変更せずに保存されます。したがって、request.getHeader() は文字列以外の値を返す可能性があります。ただし、文字列以外の値は、ネットワーク送信のために文字列に変換されます。

request.setHeader('Content-Type', 'application/json'); copy

または

request.setHeader('Cookie', ['type=ninja', 'language=javascript']); copy

値が文字列の場合、latin1エンコーディングの範囲外の文字が含まれていると例外がスローされます。

値にUTF-8文字を渡す必要がある場合は、RFC 8187標準を使用して値をエンコードしてください。

const filename = 'Rock 🎵.txt';
request.setHeader('Content-Disposition', `attachment; filename*=utf-8''${encodeURIComponent(filename)}`); copy

request.setNoDelay([noDelay])#

• noDelay <boolean>

ソケットがこのリクエストに割り当てられ、接続されると、socket.setNoDelay() が呼び出されます。

request.setSocketKeepAlive([enable][, initialDelay])#

• enable <boolean>
• initialDelay <number>

ソケットがこのリクエストに割り当てられ、接続されると、socket.setKeepAlive() が呼び出されます。

request.setTimeout(timeout[, callback])#

• timeout <number> リクエストがタイムアウトするまでのミリ秒数。
• callback <Function> タイムアウトが発生したときに呼び出されるオプションの関数。'timeout'イベントにバインドするのと同じです。
• 戻り値: <http.ClientRequest>

ソケットがこのリクエストに割り当てられ、接続されると、socket.setTimeout() が呼び出されます。

request.socket#

• <stream.Duplex>

基盤となるソケットへの参照。通常、ユーザーはこのプロパティにアクセスしたくありません。特に、プロトコルパーサーがソケットにアタッチする方法のため、ソケットは 'readable' イベントを発生させません。

import http from 'node:http';
const options = {
  host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});const http = require('node:http');
const options = {
  host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});copy

このプロパティは、ユーザーが<net.Socket>以外のソケットタイプを指定した場合を除き、<net.Socket>クラスのインスタンス、<stream.Duplex>のサブクラスであることが保証されています。

request.uncork()#

writable.uncork() を参照してください。

request.writableEnded#

• <boolean>

request.end() が呼び出された後、true になります。このプロパティは、データがフラッシュされたかどうかを示すものではありません。このためには、代わりに request.writableFinished を使用してください。

request.writableFinished#

• <boolean>

すべてのデータが基盤となるシステムにフラッシュされた場合、'finish' イベントが発行される直前に true になります。

request.write(chunk[, encoding][, callback])#

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• 戻り値: <boolean>

本文のチャンクを送信します。このメソッドは複数回呼び出すことができます。Content-Length が設定されていない場合、データは自動的にHTTPチャンク転送エンコーディングでエンコードされるため、サーバーはデータがいつ終了するかを認識します。Transfer-Encoding: chunked ヘッダーが追加されます。リクエストの送信を完了するには、request.end() を呼び出す必要があります。

encoding 引数はオプションであり、chunk が文字列の場合にのみ適用されます。デフォルトは 'utf8' です。

callback 引数はオプションで、このデータのチャンクがフラッシュされたときに呼び出されます。ただし、チャンクが空でない場合に限ります。

データ全体がカーネルバッファに正常にフラッシュされた場合は true を返します。データの一部またはすべてがユーザーメモリにキューイングされた場合は false を返します。バッファが再び解放されると、'drain' が発行されます。

write 関数が空の文字列またはバッファで呼び出された場合、何もせず、さらに入力を待ちます。

クラス: http.Server#

• 拡張: <net.Server>

イベント: 'checkContinue'#

• request <http.IncomingMessage>
• response <http.ServerResponse>

HTTP Expect: 100-continue を含むリクエストが受信されるたびに発行されます。このイベントがリッスンされない場合、サーバーは必要に応じて 100 Continue で自動的に応答します。

このイベントの処理には、クライアントがリクエスト本文の送信を継続する必要がある場合は response.writeContinue() を呼び出すか、クライアントがリクエスト本文の送信を継続する必要がない場合は適切なHTTP応答（例：400 Bad Request）を生成することが含まれます。

このイベントが発行および処理されると、'request' イベントは発行されません。

イベント: 'checkExpectation'#

• request <http.IncomingMessage>
• response <http.ServerResponse>

HTTP Expect ヘッダーを含むリクエストが受信されるたびに発行されます。ここで、値が 100-continue ではない場合。このイベントがリッスンされない場合、サーバーは必要に応じて 417 Expectation Failed で自動的に応答します。

このイベントが発行および処理されると、'request' イベントは発行されません。

イベント: 'clientError'#

• exception <Error>
• socket <stream.Duplex>

クライアント接続が 'error' イベントを発行した場合、ここに転送されます。このイベントのリスナーは、基盤となるソケットを閉じる/破棄する責任があります。たとえば、接続を急に切断するのではなく、カスタムHTTP応答でソケットをより適切に閉じたい場合があります。リスナーが終了する前に、ソケットを**閉じるか破棄する**必要があります。

このイベントは、ユーザーが<net.Socket>以外のソケットタイプを指定しない限り、<net.Socket>クラス（<stream.Duplex>のサブクラス）のインスタンスを渡されることが保証されています。

デフォルトの動作は、HTTP '400 Bad Request'、または HPE_HEADER_OVERFLOW エラーの場合は HTTP '431 Request Header Fields Too Large' でソケットを閉じようとすることです。ソケットが書き込み可能でない場合、または現在のアタッチされた http.ServerResponse のヘッダーが送信されている場合、すぐに破棄されます。

socket は、エラーが発生した net.Socket オブジェクトです。

import http from 'node:http';

const server = http.createServer((req, res) => {
  res.end();
});
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});
server.listen(8000);const http = require('node:http');

const server = http.createServer((req, res) => {
  res.end();
});
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});
server.listen(8000);copy

'clientError' イベントが発生した場合、request または response オブジェクトはないため、応答ヘッダーやペイロードを含む送信されるHTTP応答は、必ず socket オブジェクトに直接書き込む必要があります。応答が適切にフォーマットされたHTTP応答メッセージであることを確認するために注意が必要です。

err は、2つの追加の列を持つ Error のインスタンスです。

• bytesParsed: Node.js が正しく解析した可能性のあるリクエストパケットのバイト数。
• rawPacket: 現在のリクエストの生のパケット。

ECONNRESET エラーの場合のように、クライアントがすでに応答を受信しているか、ソケットがすでに破棄されている場合があります。ソケットにデータを送信しようとする前に、ソケットがまだ書き込み可能であることを確認することをお勧めします。

server.on('clientError', (err, socket) => {
  if (err.code === 'ECONNRESET' || !socket.writable) {
    return;
  }

  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
}); copy

イベント: 'close'#

サーバーが閉じるときに発行されます。

イベント: 'connect'#

• request <http.IncomingMessage> 'request' イベントと同じように、HTTPリクエストの引数
• socket <stream.Duplex> サーバーとクライアント間のネットワークソケット
• head <Buffer> トンネリングストリームの最初のパケット（空の場合があります）

クライアントが HTTP CONNECT メソッドをリクエストするたびに発行されます。このイベントがリッスンされていない場合、CONNECT メソッドをリクエストするクライアントは接続を閉じられます。

このイベントは、ユーザーが<net.Socket>以外のソケットタイプを指定しない限り、<net.Socket>クラス（<stream.Duplex>のサブクラス）のインスタンスを渡されることが保証されています。

このイベントが発行された後、リクエストのソケットは 'data' イベントリスナーを持たなくなるため、そのソケットでサーバーに送信されたデータを処理するには、バインドする必要があります。

イベント: 'connection'#

• socket <stream.Duplex>

新しい TCP ストリームが確立されたときに、このイベントが発行されます。socket は通常、net.Socket 型のオブジェクトです。通常、ユーザーはこのイベントにアクセスする必要はありません。特に、プロトコルパーサーがソケットにどのようにアタッチされるかにより、ソケットは 'readable' イベントを発行しません。socket は request.socket でもアクセスできます。

このイベントは、ユーザーが HTTP サーバーに接続を挿入するために明示的に発行することもできます。その場合、任意の Duplex ストリームを渡すことができます。

ここで socket.setTimeout() が呼び出された場合、ソケットがリクエストを処理したときに (server.keepAliveTimeout がゼロでない場合) 、タイムアウトは server.keepAliveTimeout に置き換えられます。

このイベントは、ユーザーが<net.Socket>以外のソケットタイプを指定しない限り、<net.Socket>クラス（<stream.Duplex>のサブクラス）のインスタンスを渡されることが保証されています。

イベント: 'dropRequest'#

• request <http.IncomingMessage> 'request' イベントと同じように、HTTPリクエストの引数
• socket <stream.Duplex> サーバーとクライアント間のネットワークソケット

ソケット上のリクエスト数が server.maxRequestsPerSocket の閾値に達すると、サーバーは新しいリクエストをドロップし、代わりに 'dropRequest' イベントを発行し、クライアントに 503 を送信します。

イベント: 'request'#

• request <http.IncomingMessage>
• response <http.ServerResponse>

リクエストがあるたびに発行されます。接続ごとに複数のリクエストが発生する場合があります (HTTP Keep-Alive 接続の場合)。

イベント: 'upgrade'#

• request <http.IncomingMessage> 'request' イベントと同じように、HTTPリクエストの引数
• socket <stream.Duplex> サーバーとクライアント間のネットワークソケット
• head <Buffer> アップグレードされたストリームの最初のパケット（空の場合もあります）

クライアントが HTTP アップグレードをリクエストするたびに発行されます。このイベントをリッスンすることはオプションであり、クライアントはプロトコル変更を要求することはできません。

このイベントが発行された後、リクエストのソケットは 'data' イベントリスナーを持たなくなるため、そのソケットでサーバーに送信されたデータを処理するには、バインドする必要があります。

このイベントは、ユーザーが<net.Socket>以外のソケットタイプを指定しない限り、<net.Socket>クラス（<stream.Duplex>のサブクラス）のインスタンスを渡されることが保証されています。

server.close([callback])#

• callback <Function>

サーバーが新しい接続を受け入れるのを停止し、リクエストを送信していないか、応答を待機していないこのサーバーに接続されているすべての接続を閉じます。net.Server.close() を参照してください。

server.closeAllConnections()#

このサーバーに接続されているすべての接続を閉じます。

server.closeIdleConnections()#

リクエストを送信していないか、応答を待機していないこのサーバーに接続されているすべての接続を閉じます。

server.headersTimeout#

• <number> デフォルト: server.requestTimeout または 60000 の小さい方。

パーサーが完全な HTTP ヘッダーを受信するまで待機する時間を制限します。

タイムアウトが期限切れになった場合、サーバーはステータス 408 で応答し、リクエストをリクエストリスナーに転送せずに接続を閉じます。

サーバーがリバースプロキシなしでデプロイされた場合に、潜在的なサービス拒否攻撃から保護するには、ゼロ以外の値 (例: 120 秒) に設定する必要があります。

server.listen()#

HTTP サーバーが接続をリッスンし始めます。このメソッドは、net.Server の server.listen() と同じです。

server.listening#

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

server.maxHeadersCount#

• <number> デフォルト: 2000

受信ヘッダーの最大数を制限します。0 に設定した場合、制限は適用されません。

server.requestTimeout#

• <number> デフォルト: 300000

クライアントからリクエスト全体を受信するまでのタイムアウト値をミリ秒単位で設定します。

タイムアウトが期限切れになった場合、サーバーはステータス 408 で応答し、リクエストをリクエストリスナーに転送せずに接続を閉じます。

サーバーがリバースプロキシなしでデプロイされた場合に、潜在的なサービス拒否攻撃から保護するには、ゼロ以外の値 (例: 120 秒) に設定する必要があります。

server.setTimeout([msecs][, callback])#

• msecs <number> デフォルト: 0 (タイムアウトなし)
• callback <Function>
• 戻り値: <http.Server>

ソケットのタイムアウト値を設定し、タイムアウトが発生した場合、ソケットを引数として渡して、Server オブジェクトで 'timeout' イベントを発行します。

Server オブジェクトに 'timeout' イベントリスナーがある場合、タイムアウトしたソケットを引数として呼び出されます。

デフォルトでは、Server はソケットをタイムアウトしません。ただし、コールバックが Server の 'timeout' イベントに割り当てられている場合、タイムアウトを明示的に処理する必要があります。

server.maxRequestsPerSocket#

• <number> ソケットごとのリクエスト数。デフォルト: 0 (制限なし)

キープアライブ接続を閉じる前に、ソケットが処理できる最大リクエスト数。

値が 0 の場合、制限は無効になります。

制限に達すると、Connection ヘッダーの値が close に設定されますが、実際には接続は閉じられません。制限に達した後に送信される後続のリクエストは、応答として 503 Service Unavailable を受け取ります。

server.timeout#

• <number> タイムアウト (ミリ秒単位)。デフォルト: 0 (タイムアウトなし)

ソケットがタイムアウトしたと推定されるまでの非アクティブ時間のミリ秒数。

値が 0 の場合、受信接続のタイムアウト動作は無効になります。

ソケットタイムアウトのロジックは接続時に設定されるため、この値を変更しても、既存の接続ではなく、サーバーへの新しい接続のみに影響します。

server.keepAliveTimeout#

• <number> タイムアウト (ミリ秒単位)。デフォルト: 5000 (5 秒)。

サーバーが最後の応答の書き込みを完了した後、ソケットが破棄されるまでに、追加の受信データを待機する必要がある非アクティブ時間のミリ秒数。キープアライブタイムアウトがトリガーされる前にサーバーが新しいデータを受信した場合、通常の非アクティブタイムアウト (つまり、server.timeout) がリセットされます。

値が 0 の場合、受信接続のキープアライブタイムアウト動作は無効になります。値が 0 の場合、http サーバーは、キープアライブタイムアウトがなかった 8.0.0 より前の Node.js バージョンと同様に動作します。

ソケットタイムアウトのロジックは接続時に設定されるため、この値を変更しても、既存の接続ではなく、サーバーへの新しい接続のみに影響します。

server[Symbol.asyncDispose]()#

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

クラス: http.ServerResponse#

• 拡張: <http.OutgoingMessage>

このオブジェクトは、ユーザーではなく HTTP サーバーによって内部的に作成されます。これは、'request' イベントの 2 番目のパラメーターとして渡されます。

イベント: 'close'#

レスポンスが完了したか、基になる接続が (レスポンス完了前に) 途中で終了したことを示します。

イベント: 'finish'#

レスポンスが送信されたときに発行されます。より具体的には、レスポンスヘッダーとボディの最後のセグメントがネットワーク経由で送信するためにオペレーティングシステムに渡されたときに、このイベントが発行されます。クライアントがまだ何かを受信したという意味ではありません。

response.addTrailers(headers)#

• headers <Object>

このメソッドは、HTTP トレーラーヘッダー（メッセージの最後にあるヘッダー）をレスポンスに追加します。

トレーラーは、レスポンスにチャンクエンコーディングが使用されている場合にのみ発行されます。そうでない場合 (例: リクエストが HTTP/1.0 の場合)、トレーラーは黙って破棄されます。

HTTP では、トレーラーを発行するために、その値にヘッダーフィールドのリストを含む Trailer ヘッダーを送信する必要があります。例:

response.writeHead(200, { 'Content-Type': 'text/plain',
                          'Trailer': 'Content-MD5' });
response.write(fileData);
response.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' });
response.end(); copy

無効な文字を含むヘッダーフィールド名または値を設定しようとすると、TypeError がスローされます。

response.connection#

• <stream.Duplex>

response.socket を参照してください。

response.cork()#

writable.cork()を参照してください。

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

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• 戻り値: <this>

このメソッドは、すべてのレスポンスヘッダーと本文が送信されたことをサーバーに通知します。サーバーはこのメッセージが完了したとみなすべきです。各レスポンスでは、response.end() メソッドを必ず呼び出す必要があります。

data が指定された場合、response.write(data, encoding) を呼び出した後、response.end(callback) を呼び出すのと同様の効果があります。

callback が指定された場合、レスポンスストリームが完了したときに呼び出されます。

response.finished#

• <boolean>

response.end() が呼び出された場合、response.finished プロパティは true になります。

response.flushHeaders()#

レスポンスヘッダーをフラッシュします。以下も参照してください：request.flushHeaders()。

response.getHeader(name)#

• name <string>
• 戻り値: <any>

クライアントに送信するためにキューに入れられたが、まだ送信されていないヘッダーを読み出します。名前は大文字と小文字を区別しません。戻り値の型は、response.setHeader() に渡された引数によって異なります。

response.setHeader('Content-Type', 'text/html');
response.setHeader('Content-Length', Buffer.byteLength(body));
response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);
const contentType = response.getHeader('content-type');
// contentType is 'text/html'
const contentLength = response.getHeader('Content-Length');
// contentLength is of type number
const setCookie = response.getHeader('set-cookie');
// setCookie is of type string[] copy

response.getHeaderNames()#

• 戻り値: <string[]>

現在の送信ヘッダーの一意の名前を含む配列を返します。すべてのヘッダー名は小文字です。

response.setHeader('Foo', 'bar');
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headerNames = response.getHeaderNames();
// headerNames === ['foo', 'set-cookie'] copy

response.getHeaders()#

• 戻り値: <Object>

現在の送信ヘッダーの浅いコピーを返します。浅いコピーが使用されるため、さまざまなヘッダー関連のhttpモジュールメソッドをさらに呼び出すことなく、配列値を変更できます。返されるオブジェクトのキーはヘッダー名であり、値はそれぞれのヘッダー値です。すべてのヘッダー名は小文字です。

response.getHeaders() メソッドによって返されるオブジェクトは、JavaScript の Object からプロトタイプ的に継承されていません。これは、obj.toString()、obj.hasOwnProperty() などの一般的な Object メソッドが定義されておらず、機能しないことを意味します。

response.setHeader('Foo', 'bar');
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headers = response.getHeaders();
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } copy

response.hasHeader(name)#

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

nameで識別されるヘッダーが送信ヘッダーに現在設定されている場合、trueを返します。ヘッダー名の照合では、大文字と小文字が区別されません。

const hasContentType = response.hasHeader('content-type'); copy

response.headersSent#

• <boolean>

ブール値（読み取り専用）。ヘッダーが送信された場合は true、そうでない場合は false。

response.removeHeader(name)#

• name <string>

暗黙的な送信のためにキューに入れられたヘッダーを削除します。

response.removeHeader('Content-Encoding'); copy

response.req#

• <http.IncomingMessage>

元の HTTP request オブジェクトへの参照。

response.sendDate#

• <boolean>

true の場合、ヘッダーに Date ヘッダーが存在しない場合、Date ヘッダーは自動的に生成され、レスポンスで送信されます。デフォルトは true です。

これはテストでのみ無効にする必要があります。HTTP ではレスポンスに Date ヘッダーが必要です。

response.setHeader(name, value)#

• name <string>
• value <any>
• 戻り値: <http.ServerResponse>

レスポンスオブジェクトを返します。

暗黙的なヘッダーの単一のヘッダー値を設定します。このヘッダーが送信されるヘッダーに既に存在する場合、その値は置き換えられます。同じ名前で複数のヘッダーを送信するには、文字列の配列を使用します。文字列以外の値は、変更せずに保存されます。したがって、response.getHeader() は文字列以外の値を返す場合があります。ただし、文字列以外の値はネットワーク送信のために文字列に変換されます。メソッドチェーンを有効にするために、同じレスポンスオブジェクトが呼び出し元に返されます。

response.setHeader('Content-Type', 'text/html'); copy

または

response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']); copy

無効な文字を含むヘッダーフィールド名または値を設定しようとすると、TypeError がスローされます。

response.setHeader() でヘッダーが設定されている場合、response.writeHead() に渡されたヘッダーとマージされます。その際、response.writeHead() に渡されたヘッダーが優先されます。

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
}); copy

response.writeHead() メソッドが呼び出され、このメソッドが呼び出されていない場合、内部でキャッシュせずに、指定されたヘッダー値を直接ネットワークチャネルに書き込みます。そのヘッダーに対する response.getHeader() は期待どおりの結果を返しません。ヘッダーの段階的な設定を、将来の取得と変更の可能性を考慮して行う場合は、response.writeHead() の代わりに response.setHeader() を使用してください。

response.setTimeout(msecs[, callback])#

• msecs <number>
• callback <Function>
• 戻り値: <http.ServerResponse>

ソケットのタイムアウト値を msecs に設定します。コールバックが指定されている場合、レスポンスオブジェクトの 'timeout' イベントのリスナーとして追加されます。

リクエスト、レスポンス、またはサーバーに 'timeout' リスナーが追加されていない場合、タイムアウトするとソケットが破棄されます。リクエスト、レスポンス、またはサーバーの 'timeout' イベントにハンドラーが割り当てられている場合、タイムアウトしたソケットを明示的に処理する必要があります。

response.socket#

• <stream.Duplex>

基になるソケットへの参照。通常、ユーザーはこのプロパティにアクセスする必要はありません。特に、ソケットはプロトコルパーサーがソケットにどのように接続するかによって、'readable' イベントを発生させません。response.end() の後、このプロパティは null に設定されます。

import http from 'node:http';
const server = http.createServer((req, res) => {
  const ip = res.socket.remoteAddress;
  const port = res.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);const http = require('node:http');
const server = http.createServer((req, res) => {
  const ip = res.socket.remoteAddress;
  const port = res.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);copy

このプロパティは、ユーザーが<net.Socket>以外のソケットタイプを指定した場合を除き、<net.Socket>クラスのインスタンス、<stream.Duplex>のサブクラスであることが保証されています。

response.statusCode#

• <number> デフォルト: 200

暗黙的なヘッダーを使用する場合（response.writeHead() を明示的に呼び出さない場合）、このプロパティは、ヘッダーがフラッシュされたときにクライアントに送信されるステータスコードを制御します。

response.statusCode = 404; copy

レスポンスヘッダーがクライアントに送信された後、このプロパティは送信されたステータスコードを示します。

response.statusMessage#

• <string>

暗黙的なヘッダーを使用する場合（response.writeHead() を明示的に呼び出さない場合）、このプロパティは、ヘッダーがフラッシュされたときにクライアントに送信されるステータスメッセージを制御します。これが undefined のままの場合、ステータスコードの標準メッセージが使用されます。

response.statusMessage = 'Not found'; copy

レスポンスヘッダーがクライアントに送信された後、このプロパティは送信されたステータスメッセージを示します。

response.strictContentLength#

• <boolean> デフォルト: false

true に設定されている場合、Node.js は Content-Length ヘッダーの値と本文のサイズ（バイト単位）が等しいかどうかを確認します。Content-Length ヘッダーの値が一致しない場合、code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH' で識別される Error がスローされます。

response.uncork()#

writable.uncork() を参照してください。

response.writableEnded#

• <boolean>

response.end() が呼び出された後、true になります。このプロパティは、データがフラッシュされたかどうかを示すものではありません。代わりに response.writableFinished を使用してください。

response.writableFinished#

• <boolean>

すべてのデータが基盤となるシステムにフラッシュされた場合、'finish' イベントが発行される直前に true になります。

response.write(chunk[, encoding][, callback])#

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> デフォルト: 'utf8'
• callback <Function>
• 戻り値: <boolean>

このメソッドが呼び出され、response.writeHead() が呼び出されていない場合、暗黙的なヘッダーモードに切り替わり、暗黙的なヘッダーをフラッシュします。

レスポンスボディのチャンクを送信します。このメソッドは、ボディの連続した部分を提供するために複数回呼び出すことができます。

リクエストメソッドまたはレスポンスステータスがコンテンツをサポートしていない場合、ボディへの書き込みは許可されません。HEAD リクエストや 204 または 304 レスポンスの一部としてボディへの書き込みを試みた場合、ERR_HTTP_BODY_NOT_ALLOWED というコードを持つ同期的な Error がスローされます。

chunk は文字列またはバッファーにすることができます。chunk が文字列の場合、2 番目のパラメーターはそれをバイトストリームにエンコードする方法を指定します。このデータのチャンクがフラッシュされると、callback が呼び出されます。

これは生の HTTP ボディであり、使用される可能性のある高レベルのマルチパートボディエンコーディングとは関係ありません。

response.write() が最初に呼び出されると、バッファリングされたヘッダー情報とボディの最初のチャンクがクライアントに送信されます。response.write() が 2 回目に呼び出されると、Node.js はデータがストリーミングされると想定し、新しいデータを個別に送信します。つまり、レスポンスはボディの最初のチャンクまでバッファリングされます。

データ全体がカーネルバッファに正常にフラッシュされた場合は true を返します。データの一部またはすべてがユーザーメモリにキューイングされた場合は false を返します。バッファが再び解放されると、'drain' が発行されます。

response.writeContinue()#

クライアントに HTTP/1.1 100 Continue メッセージを送信し、リクエストボディを送信する必要があることを示します。Server の 'checkContinue' イベントを参照してください。

response.writeEarlyHints(hints[, callback])#

• hints <Object>
• callback <Function>

HTTP/1.1 103 Early Hints メッセージを Link ヘッダーとともにクライアントに送信し、ユーザーエージェントがリンクされたリソースをプリロード/プリコネクトできることを示します。hints は、early hints メッセージとともに送信されるヘッダーの値を含むオブジェクトです。オプションの callback 引数は、レスポンスメッセージが書き込まれたときに呼び出されます。

例

const earlyHintsLink = '</styles.css>; rel=preload; as=style';
response.writeEarlyHints({
  'link': earlyHintsLink,
});

const earlyHintsLinks = [
  '</styles.css>; rel=preload; as=style',
  '</scripts.js>; rel=preload; as=script',
];
response.writeEarlyHints({
  'link': earlyHintsLinks,
  'x-trace-id': 'id for diagnostics',
});

const earlyHintsCallback = () => console.log('early hints message sent');
response.writeEarlyHints({
  'link': earlyHintsLinks,
}, earlyHintsCallback); copy

response.writeHead(statusCode[, statusMessage][, headers])#

• statusCode <number>
• statusMessage <string>
• headers <Object> | <Array>
• 戻り値: <http.ServerResponse>

リクエストに応答ヘッダーを送信します。ステータスコードは、404のような3桁のHTTPステータスコードです。最後の引数であるheadersは、応答ヘッダーです。オプションで、2番目の引数として人間が読めるstatusMessageを指定できます。

headersは、キーと値が同じリストにあるArrayの場合があります。これは、タプルのリストではありません。したがって、偶数番号のオフセットはキー値であり、奇数番号のオフセットは関連付けられた値です。配列は、request.rawHeadersと同じ形式です。

呼び出しをチェーンできるように、ServerResponseへの参照を返します。

const body = 'hello world';
response
  .writeHead(200, {
    'Content-Length': Buffer.byteLength(body),
    'Content-Type': 'text/plain',
  })
  .end(body); copy

このメソッドは、メッセージに対して一度だけ呼び出す必要があり、response.end()が呼び出される前に呼び出す必要があります。

response.write()またはresponse.end()がこれを呼び出す前に呼び出された場合、暗黙的/可変ヘッダーが計算され、この関数を呼び出します。

response.setHeader() でヘッダーが設定されている場合、response.writeHead() に渡されたヘッダーとマージされます。その際、response.writeHead() に渡されたヘッダーが優先されます。

このメソッドが呼び出され、response.setHeader()が呼び出されていない場合、内部的にキャッシュせずに、指定されたヘッダー値をネットワークチャネルに直接書き込み、ヘッダーに対するresponse.getHeader()は期待される結果を生成しません。将来の取得と変更の可能性を考慮して、ヘッダーを段階的に設定する場合は、代わりにresponse.setHeader()を使用してください。

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
}); copy

Content-Lengthは、文字数ではなくバイト数で読み取られます。バイト単位の本文の長さを決定するには、Buffer.byteLength()を使用します。Node.jsは、Content-Lengthと送信された本文の長さが等しいかどうかを確認します。

無効な文字を含むヘッダーフィールド名または値を設定しようとすると、[Error][]がスローされます。

response.writeProcessing()#

リクエスト本文を送信する必要があることを示すHTTP/1.1 102 Processingメッセージをクライアントに送信します。

クラス: http.IncomingMessage#

• 拡張: <stream.Readable>

IncomingMessageオブジェクトは、http.Serverまたはhttp.ClientRequestによって作成され、'request'イベントと'response'イベントの最初の引数としてそれぞれ渡されます。レスポンスのステータス、ヘッダー、データにアクセスするために使用できます。

<stream.Duplex>のサブクラスであるsocket値とは異なり、IncomingMessage自体は<stream.Readable>を拡張し、基礎となるソケットがキープアライブの場合に複数回再利用される可能性があるため、受信したHTTPヘッダーとペイロードを解析および送信するために個別に作成されます。

イベント: 'aborted'#

リクエストが中止されたときに発生します。

イベント: 'close'#

リクエストが完了したときに発生します。

message.aborted#

• <boolean>

リクエストが中止された場合、message.abortedプロパティはtrueになります。

message.complete#

• <boolean>

完全なHTTPメッセージが受信され、正常に解析された場合、message.completeプロパティはtrueになります。

このプロパティは、クライアントまたはサーバーが接続が終了する前にメッセージを完全に送信したかどうかを判断する手段として特に役立ちます。

const req = http.request({
  host: '127.0.0.1',
  port: 8080,
  method: 'POST',
}, (res) => {
  res.resume();
  res.on('end', () => {
    if (!res.complete)
      console.error(
        'The connection was terminated while the message was still being sent');
  });
}); copy

message.connection#

message.socketのエイリアス。

message.destroy([error])#

• error <Error>
• 戻り値: <this>

IncomingMessageを受信したソケットでdestroy()を呼び出します。errorが指定された場合、'error'イベントがソケットで発生し、errorがイベントのリスナーへの引数として渡されます。

message.headers#

• <Object>

リクエスト/レスポンスヘッダーオブジェクト。

ヘッダー名と値のキーと値のペア。ヘッダー名は小文字化されます。

// Prints something like:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers); copy

生のヘッダーの重複は、ヘッダー名に応じて次の方法で処理されます

• age、authorization、content-length、content-type、etag、expires、from、host、if-modified-since、if-unmodified-since、last-modified、location、max-forwards、proxy-authorization、referer、retry-after、server、またはuser-agentの重複は破棄されます。上記のヘッダーの重複した値の結合を許可するには、http.request()およびhttp.createServer()でオプションjoinDuplicateHeadersを使用します。詳細については、RFC 9110セクション5.3を参照してください。
• set-cookieは常に配列です。重複は配列に追加されます。
• 重複するcookieヘッダーの場合、値は; で結合されます。
• その他のすべてのヘッダーの場合、値は, で結合されます。

message.headersDistinct#

• <Object>

message.headersに似ていますが、結合ロジックがなく、値は1回しか受信していないヘッダーでも、常に文字列の配列です。

// Prints something like:
//
// { 'user-agent': ['curl/7.22.0'],
//   host: ['127.0.0.1:8000'],
//   accept: ['*/*'] }
console.log(request.headersDistinct); copy

message.httpVersion#

• <string>

サーバーリクエストの場合、クライアントによって送信されたHTTPバージョン。クライアントレスポンスの場合、接続先のサーバーのHTTPバージョン。おそらく'1.1'または'1.0'のいずれか。

また、message.httpVersionMajorは最初の整数であり、message.httpVersionMinorは2番目の整数です。

message.method#

• <string>

http.Serverから取得したリクエストに対してのみ有効です。

文字列としてのリクエストメソッド。読み取り専用。例：'GET'、'DELETE'。

message.rawHeaders#

• <string[]>

受信したとおりの生のリクエスト/レスポンスヘッダーリスト。

キーと値は同じリストにあります。これは、タプルのリストではありません。したがって、偶数番号のオフセットはキー値であり、奇数番号のオフセットは関連付けられた値です。

ヘッダー名は小文字化されず、重複はマージされません。

// Prints something like:
//
// [ 'user-agent',
//   'this is invalid because there can be only one',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders); copy

message.rawTrailers#

• <string[]>

受信したとおりの生のリクエスト/レスポンストレーラーのキーと値。'end'イベントでのみ設定されます。

message.setTimeout(msecs[, callback])#

• msecs <number>
• callback <Function>
• 戻り値: <http.IncomingMessage>

message.socket.setTimeout(msecs, callback)を呼び出します。

message.socket#

• <stream.Duplex>

接続に関連付けられたnet.Socketオブジェクト。

HTTPSサポートでは、クライアントの認証詳細を取得するためにrequest.socket.getPeerCertificate()を使用します。

このプロパティは、ユーザーがnet.Socket以外のソケットタイプを指定するか、内部的にnullにした場合を除き、<net.Socket>クラス、<stream.Duplex>のサブクラスのインスタンスであることが保証されています。

message.statusCode#

• <number>

http.ClientRequestから取得したレスポンスに対してのみ有効です。

3桁のHTTPレスポンスステータスコード。例：404。

message.statusMessage#

• <string>

http.ClientRequestから取得したレスポンスに対してのみ有効です。

HTTPレスポンスステータスメッセージ（理由句）。例：OKまたはInternal Server Error。

message.trailers#

• <Object>

リクエスト/レスポンストレーラーオブジェクト。'end'イベントでのみ設定されます。

message.trailersDistinct#

• <Object>

message.trailersに似ていますが、結合ロジックがなく、値は1回しか受信していないヘッダーでも、常に文字列の配列です。'end'イベントでのみ設定されます。

message.url#

• <string>

http.Serverから取得したリクエストに対してのみ有効です。

リクエストURL文字列。これには、実際のHTTPリクエストに存在するURLのみが含まれます。次のリクエストを受け取ります。

GET /status?name=ryan HTTP/1.1
Accept: text/plain copy

URLをその部分に解析するには

new URL(request.url, `http://${request.headers.host}`); copy

request.url が '/status?name=ryan' で、request.headers.host が 'localhost:3000' の場合

$ node
> new URL(request.url, `http://${request.headers.host}`)
URL {
  href: 'https://127.0.0.1:3000/status?name=ryan',
  origin: 'https://127.0.0.1:3000',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'localhost:3000',
  hostname: 'localhost',
  port: '3000',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
} copy

クラス: http.OutgoingMessage#

• 拡張: <Stream>

このクラスは http.ClientRequest と http.ServerResponse の親クラスとして機能します。これは、HTTPトランザクションの参加者の観点からの抽象的な送信メッセージです。

イベント: 'drain'#

メッセージのバッファが再び空になったときに発生します。

イベント: 'finish'#

送信が正常に終了したときに発生します。

イベント: 'prefinish'#

outgoingMessage.end() が呼び出された後に発生します。このイベントが発生したとき、すべてのデータは処理済みですが、完全にフラッシュされているとは限りません。

outgoingMessage.addTrailers(headers)#

• headers <Object>

HTTPトレーラー（メッセージの最後にあるヘッダー）をメッセージに追加します。

トレーラーは、メッセージがチャンクエンコードされている場合にのみ送信されます。そうでない場合、トレーラーはサイレントに破棄されます。

HTTPでは、トレーラーを送信するために、値にヘッダーフィールド名のリストを含む Trailer ヘッダーを送信する必要があります。例:

message.writeHead(200, { 'Content-Type': 'text/plain',
                         'Trailer': 'Content-MD5' });
message.write(fileData);
message.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' });
message.end(); copy

無効な文字を含むヘッダーフィールド名または値を設定しようとすると、TypeError がスローされます。

outgoingMessage.appendHeader(name, value)#

• name <string> ヘッダー名
• value <string> | <string[]> ヘッダー値
• 戻り値: <this>

ヘッダーオブジェクトに単一のヘッダー値を追加します。

値が配列の場合、これはこのメソッドを複数回呼び出すのと同じです。

ヘッダーに以前の値がない場合、これは outgoingMessage.setHeader(name, value) を呼び出すのと同じです。

クライアントリクエストまたはサーバーが作成されたときの options.uniqueHeaders の値によっては、ヘッダーが複数回送信されるか、; を使用して結合された値で1回送信されることになります。

outgoingMessage.connection#

outgoingMessage.socket のエイリアスです。

outgoingMessage.cork()#

writable.cork()を参照してください。

outgoingMessage.destroy([error])#

• error <Error> オプション。error イベントで発生させるエラー
• 戻り値: <this>

メッセージを破棄します。ソケットがメッセージに関連付けられていて接続されている場合、そのソケットも破棄されます。

outgoingMessage.end(chunk[, encoding][, callback])#

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> オプション、デフォルト: utf8
• callback <Function> オプション
• 戻り値: <this>

送信メッセージを終了します。本体の一部が送信されていない場合は、それらを基盤となるシステムにフラッシュします。メッセージがチャンクされている場合は、終端チャンク 0\r\n\r\n を送信し、トレーラー（存在する場合）を送信します。

chunk が指定されている場合、outgoingMessage.write(chunk, encoding) を呼び出し、次に outgoingMessage.end(callback) を呼び出すのと同じです。

callback が指定されている場合、メッセージが完了したときに呼び出されます ('finish' イベントのリスナーと同等です)。

outgoingMessage.flushHeaders()#

メッセージヘッダーをフラッシュします。

効率上の理由から、Node.js は通常、メッセージヘッダーを outgoingMessage.end() が呼び出されるか、メッセージデータの最初のチャンクが書き込まれるまでバッファリングします。その後、ヘッダーとデータを単一の TCP パケットにパックしようとします。

これは通常望ましい (TCP のラウンドトリップを節約できる) ですが、最初のデータがかなり後まで送信されない可能性がある場合は望ましくありません。outgoingMessage.flushHeaders() は最適化をバイパスし、メッセージを起動します。

outgoingMessage.getHeader(name)#

• name <string> ヘッダーの名前
• 戻り値: <string> | <undefined>

指定された名前の HTTP ヘッダーの値を取得します。そのヘッダーが設定されていない場合、返される値は undefined になります。

outgoingMessage.getHeaderNames()#

• 戻り値: <string[]>

現在の送信ヘッダーの一意の名前を含む配列を返します。すべての名前は小文字です。

outgoingMessage.getHeaders()#

• 戻り値: <Object>

現在の送信ヘッダーの浅いコピーを返します。浅いコピーが使用されるため、配列の値は、さまざまなヘッダー関連の HTTP モジュールメソッドをさらに呼び出すことなく変更できます。返されるオブジェクトのキーはヘッダー名であり、値はそれぞれのヘッダー値です。すべてのヘッダー名は小文字です。

outgoingMessage.getHeaders() メソッドによって返されるオブジェクトは、JavaScript の Object から原型的に継承されません。つまり、obj.toString()、obj.hasOwnProperty() などの一般的な Object メソッドは定義されておらず、機能しません。

outgoingMessage.setHeader('Foo', 'bar');
outgoingMessage.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headers = outgoingMessage.getHeaders();
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } copy

outgoingMessage.hasHeader(name)#

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

name で識別されるヘッダーが、現在送信ヘッダーに設定されている場合は true を返します。ヘッダー名は大文字と小文字を区別しません。

const hasContentType = outgoingMessage.hasHeader('content-type'); copy

outgoingMessage.headersSent#

• <boolean>

読み取り専用。ヘッダーが送信された場合は true、それ以外の場合は false。

outgoingMessage.pipe()#

http.OutgoingMessage の親クラスであるレガシー Stream クラスから継承された stream.pipe() メソッドをオーバーライドします。

このメソッドを呼び出すと、outgoingMessage は書き込み専用ストリームであるため、Error がスローされます。

outgoingMessage.removeHeader(name)#

• name <string> ヘッダー名

暗黙の送信のためにキューに入れられたヘッダーを削除します。

outgoingMessage.removeHeader('Content-Encoding'); copy

outgoingMessage.setHeader(name, value)#

• name <string> ヘッダー名
• value <any> ヘッダー値
• 戻り値: <this>

単一のヘッダー値を設定します。ヘッダーが送信されるヘッダーに既に存在する場合は、その値が置き換えられます。同じ名前で複数のヘッダーを送信するには、文字列の配列を使用します。

outgoingMessage.setHeaders(headers)#

• headers <Headers> | <Map>
• 戻り値: <http.ServerResponse>

レスポンスオブジェクトを返します。

暗黙的なヘッダーに複数のヘッダー値を設定します。headers は Headers または Map のインスタンスである必要があります。ヘッダーが送信されるヘッダーに既に存在する場合、その値は置き換えられます。

const headers = new Headers({ foo: 'bar' });
response.setHeaders(headers); copy

または

const headers = new Map([['foo', 'bar']]);
res.setHeaders(headers); copy

outgoingMessage.setHeaders() でヘッダーが設定されている場合、それらは response.writeHead() に渡されたヘッダーとマージされ、response.writeHead() に渡されたヘッダーが優先されます。

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  const headers = new Headers({ 'Content-Type': 'text/html' });
  res.setHeaders(headers);
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
}); copy

outgoingMessage.setTimeout(msesc[, callback])#

• msesc <number>
• callback <Function> オプション。タイムアウトが発生したときに呼び出される関数。timeout イベントへのバインドと同じです。
• 戻り値: <this>

ソケットがメッセージに関連付けられて接続されると、socket.setTimeout() が最初のパラメータとして msecs を指定して呼び出されます。

outgoingMessage.socket#

• <stream.Duplex>

基盤となるソケットへの参照。通常、ユーザーがこのプロパティにアクセスする必要はありません。

outgoingMessage.end() を呼び出した後、このプロパティは null に設定されます。

outgoingMessage.uncork()#

writable.uncork() を参照してください。

outgoingMessage.writableCorked#

• <number>

outgoingMessage.cork() が呼び出された回数。

outgoingMessage.writableEnded#

• <boolean>

outgoingMessage.end() が呼び出された場合は true。このプロパティはデータがフラッシュされたかどうかを示しません。その目的には、代わりに message.writableFinished を使用してください。

outgoingMessage.writableFinished#

• <boolean>

すべてのデータが基盤となるシステムにフラッシュされた場合は true。

outgoingMessage.writableHighWaterMark#

• <number>

割り当てられている場合は、基盤となるソケットの highWaterMark。それ以外の場合は、writable.write() が false を返し始める時のデフォルトのバッファーレベル (16384)。

outgoingMessage.writableLength#

• <number>

バッファリングされたバイト数。

outgoingMessage.writableObjectMode#

• <boolean>

常に false。

outgoingMessage.write(chunk[, encoding][, callback])#

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string> デフォルト: utf8
• callback <Function>
• 戻り値: <boolean>

本文のチャンクを送信します。このメソッドは複数回呼び出すことができます。

encoding 引数は chunk が文字列の場合にのみ関連します。デフォルトは 'utf8' です。

callback 引数はオプションで、このデータのチャンクがフラッシュされるときに呼び出されます。

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

http.METHODS#

• <string[]>

パーサーでサポートされている HTTP メソッドのリスト。

http.STATUS_CODES#

• <Object>

標準のすべての HTTP 応答ステータスコードと、それぞれの簡単な説明のコレクション。たとえば、http.STATUS_CODES[404] === 'Not Found'。

http.createServer([options][, requestListener])#

• options <Object>

  • connectionsCheckingInterval: 不完全なリクエストにおけるリクエストおよびヘッダーのタイムアウトをチェックする間隔値をミリ秒単位で設定します。デフォルト: 30000。
  • headersTimeout: クライアントから完全な HTTP ヘッダーを受信するまでのタイムアウト値をミリ秒単位で設定します。詳細については、server.headersTimeout を参照してください。デフォルト: 60000。
  • highWaterMark <number> 必要に応じて、すべての socket の readableHighWaterMark と writableHighWaterMark をオーバーライドします。これは IncomingMessage と ServerResponse の両方の highWaterMark プロパティに影響します。デフォルト: stream.getDefaultHighWaterMark() を参照してください。
  • insecureHTTPParser <boolean> true に設定すると、寛容フラグが有効な HTTP パーサーを使用します。安全でないパーサーの使用は避ける必要があります。詳細については、--insecure-http-parser を参照してください。デフォルト: false。
  • IncomingMessage <http.IncomingMessage> 使用する IncomingMessage クラスを指定します。元の IncomingMessage を拡張する場合に便利です。デフォルト: IncomingMessage。
  • joinDuplicateHeaders <boolean> true に設定すると、このオプションを使用すると、重複を破棄する代わりに、リクエスト内の複数のヘッダーのフィールド行の値をコンマ (, ) で結合できます。詳細については、message.headers を参照してください。デフォルト: false。
  • keepAlive <boolean> true に設定すると、新しい受信接続を受信した直後にソケットで Keep-Alive 機能が有効になります。[socket.setKeepAlive([enable][, initialDelay])][socket.setKeepAlive(enable, initialDelay)] と同様に行われます。デフォルト: false。
  • keepAliveInitialDelay <number> 正の数に設定すると、アイドル状態のソケットで最初の keepalive プローブが送信されるまでの初期遅延が設定されます。デフォルト: 0。
  • keepAliveTimeout: サーバーがソケットを破棄する前に、最後の応答を書き終えた後に追加の受信データを待機する必要がある非アクティブ時間 (ミリ秒単位)。詳細については、server.keepAliveTimeout を参照してください。デフォルト: 5000。
  • maxHeaderSize <number> 必要に応じて、このサーバーが受信したリクエストの --max-http-header-size の値をオーバーライドします。つまり、リクエストヘッダーの最大長 (バイト単位)。デフォルト: 16384 (16 KiB)。
  • noDelay <boolean> true に設定すると、新しい受信接続を受信した直後に Nagle アルゴリズムの使用を無効にします。デフォルト: true。
  • requestTimeout: クライアントからリクエスト全体を受信するまでのタイムアウト値をミリ秒単位で設定します。詳細については、server.requestTimeout を参照してください。デフォルト: 300000。
  • requireHostHeader <boolean> true に設定すると、(仕様で義務付けられているように) Host ヘッダーがない HTTP/1.1 リクエストメッセージに対して、サーバーが 400 (Bad Request) ステータスコードで応答するように強制します。デフォルト: true。
  • ServerResponse <http.ServerResponse> 使用する ServerResponse クラスを指定します。元の ServerResponse を拡張する場合に便利です。デフォルト: ServerResponse。
  • uniqueHeaders <Array> 1 回のみ送信する必要がある応答ヘッダーのリスト。ヘッダーの値が配列の場合、項目は ; を使用して結合されます。

• requestListener <Function>

• 戻り値: <http.Server>

http.Server の新しいインスタンスを返します。

requestListener は、'request' イベントに自動的に追加される関数です。

import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);const http = require('node:http');

// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);copy

import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);const http = require('node:http');

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);copy

http.get(options[, callback])#

http.get(url[, options][, callback])#

• url <string> | <URL>
• options <Object> デフォルトで method が GET に設定されていることを除いて、http.request() と同じ options を受け入れます。
• callback <Function>
• 戻り値: <http.ClientRequest>

ほとんどのリクエストが本体のない GET リクエストであるため、Node.js はこの便利なメソッドを提供します。このメソッドと http.request() の唯一の違いは、デフォルトでメソッドを GET に設定し、req.end() を自動的に呼び出すことです。コールバックは、http.ClientRequest セクションで述べられている理由により、応答データを消費するように注意する必要があります。

callback は、http.IncomingMessage のインスタンスである単一の引数で呼び出されます。

JSON フェッチの例

http.get('https://127.0.0.1:8000/', (res) => {
  const { statusCode } = res;
  const contentType = res.headers['content-type'];

  let error;
  // Any 2xx status code signals a successful response but
  // here we're only checking for 200.
  if (statusCode !== 200) {
    error = new Error('Request Failed.\n' +
                      `Status Code: ${statusCode}`);
  } else if (!/^application\/json/.test(contentType)) {
    error = new Error('Invalid content-type.\n' +
                      `Expected application/json but received ${contentType}`);
  }
  if (error) {
    console.error(error.message);
    // Consume response data to free up memory
    res.resume();
    return;
  }

  res.setEncoding('utf8');
  let rawData = '';
  res.on('data', (chunk) => { rawData += chunk; });
  res.on('end', () => {
    try {
      const parsedData = JSON.parse(rawData);
      console.log(parsedData);
    } catch (e) {
      console.error(e.message);
    }
  });
}).on('error', (e) => {
  console.error(`Got error: ${e.message}`);
});

// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000); copy

http.globalAgent#

• <http.Agent>

すべての HTTP クライアントリクエストのデフォルトとして使用される Agent のグローバルインスタンス。

http.maxHeaderSize#

• <number>

HTTP ヘッダーの最大許可サイズ (バイト単位) を指定する読み取り専用プロパティ。デフォルトは 16 KiB です。--max-http-header-size CLI オプションを使用して構成できます。

これは、maxHeaderSize オプションを渡すことで、サーバーおよびクライアントリクエストに対してオーバーライドできます。

http.request(options[, callback])#

http.request(url[, options][, callback])#

• url <string> | <URL>
• options <Object>
  • agent <http.Agent> | <boolean> Agent の動作を制御します。可能な値:
    • undefined (デフォルト): このホストとポートに対して http.globalAgent を使用します。
    • Agent オブジェクト: 渡された Agent を明示的に使用します。
    • false: デフォルト値で新しい Agent を使用します。
  • auth <string> Authorization ヘッダーを計算するための基本的な認証 ('user:password')。
  • createConnection <Function> agent オプションが使用されていない場合に、リクエストに使用するソケット/ストリームを生成する関数。これは、デフォルトの createConnection 関数をオーバーライドするためだけにカスタム Agent クラスを作成するのを避けるために使用できます。詳細については、agent.createConnection() を参照してください。任意の Duplex ストリームが有効な戻り値です。
  • defaultPort <number> プロトコルのデフォルトポート。デフォルト: Agent が使用されている場合は agent.defaultPort、それ以外の場合は undefined。
  • family <number> host または hostname を解決する際に使用する IP アドレスファミリ。有効な値は 4 または 6 です。指定しない場合は、IPv4 と IPv6 の両方が使用されます。
  • headers <Object> リクエストヘッダーを含むオブジェクト。
  • hints <number> オプションの dns.lookup() ヒント。
  • host <string> リクエストを送信するサーバーのドメイン名または IP アドレス。デフォルト: 'localhost'。
  • hostname <string> host のエイリアス。 url.parse() をサポートするために、host と hostname の両方が指定されている場合は hostname が使用されます。
  • insecureHTTPParser <boolean> true に設定すると、寛容フラグが有効になった HTTP パーサーを使用します。安全でないパーサーの使用は避ける必要があります。詳細については、--insecure-http-parser を参照してください。デフォルト: false
  • joinDuplicateHeaders <boolean> リクエスト内の複数のヘッダーのフィールド行の値を、重複を破棄する代わりに , で結合します。詳細については、message.headers を参照してください。デフォルト: false。
  • localAddress <string> ネットワーク接続のためにバインドするローカルインターフェイス。
  • localPort <number> 接続元のローカルポート。
  • lookup <Function> カスタムルックアップ関数。デフォルト: dns.lookup()。
  • maxHeaderSize <number> サーバーから受信したレスポンスのヘッダーの最大長（バイト単位）である --max-http-header-size の値をオプションでオーバーライドします。デフォルト: 16384 (16 KiB)。
  • method <string> HTTP リクエストメソッドを指定する文字列。デフォルト: 'GET'。
  • path <string> リクエストパス。クエリ文字列がある場合は含める必要があります。例: '/index.html?page=12'。リクエストパスに不正な文字が含まれている場合は例外がスローされます。現在、スペースのみが拒否されていますが、将来変更される可能性があります。デフォルト: '/'。
  • port <number> リモートサーバーのポート。デフォルト: 設定されている場合は defaultPort、それ以外の場合は 80。
  • protocol <string> 使用するプロトコル。デフォルト: 'http:'。
  • setHost <boolean>: Host ヘッダーを自動的に追加するかどうかを指定します。デフォルトは true です。
  • signal <AbortSignal>: 進行中のリクエストを中止するために使用できる AbortSignal。
  • socketPath <string> Unix ドメインソケット。host または port のいずれかが指定されている場合は、TCP ソケットを指定するため、使用できません。
  • timeout <number>: ソケットタイムアウトをミリ秒単位で指定する数値。これにより、ソケットが接続される前にタイムアウトが設定されます。
  • uniqueHeaders <Array> 1回だけ送信する必要があるリクエストヘッダーのリスト。ヘッダーの値が配列の場合、項目は ; を使用して結合されます。
• callback <Function>
• 戻り値: <http.ClientRequest>

socket.connect() の options もサポートされています。

Node.js は HTTP リクエストを行うために、サーバーごとに複数の接続を維持します。この関数を使用すると、リクエストを透過的に発行できます。

url は文字列または URL オブジェクトにすることができます。url が文字列の場合、new URL() で自動的に解析されます。 URL オブジェクトの場合、通常の options オブジェクトに自動的に変換されます。

url と options の両方が指定されている場合、オブジェクトはマージされ、options プロパティが優先されます。

オプションの callback パラメーターは、'response' イベントの 1 回限りのリスナーとして追加されます。

http.request() は、http.ClientRequest クラスのインスタンスを返します。ClientRequest インスタンスは書き込み可能なストリームです。POST リクエストでファイルをアップロードする必要がある場合は、ClientRequest オブジェクトに書き込みます。

import http from 'node:http';
import { Buffer } from 'node:buffer';

const postData = JSON.stringify({
  'msg': 'Hello World!',
});

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
  },
};

const req = http.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  });
  res.on('end', () => {
    console.log('No more data in response.');
  });
});

req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
});

// Write data to request body
req.write(postData);
req.end();const http = require('node:http');

const postData = JSON.stringify({
  'msg': 'Hello World!',
});

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
  },
};

const req = http.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  });
  res.on('end', () => {
    console.log('No more data in response.');
  });
});

req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
});

// Write data to request body
req.write(postData);
req.end();copy

例では req.end() が呼び出されています。http.request() では、リクエストボディにデータが書き込まれていない場合でも、リクエストの終了を示すために、常に req.end() を呼び出す必要があります。

リクエスト中にエラーが発生した場合（DNS の解決、TCP レベルのエラー、または実際の HTTP 解析エラーなど）、返されたリクエストオブジェクトで 'error' イベントが発生します。すべての 'error' イベントと同様に、リスナーが登録されていない場合、エラーはスローされます。

注意すべき特別なヘッダーがいくつかあります。

• 'Connection: keep-alive' を送信すると、Node.js にサーバーへの接続を次のリクエストまで維持する必要があることが通知されます。

• 'Content-Length' ヘッダーを送信すると、デフォルトのチャンクエンコーディングが無効になります。

• 'Expect' ヘッダーを送信すると、リクエストヘッダーがすぐに送信されます。通常、'Expect: 100-continue' を送信する場合、タイムアウトと 'continue' イベントのリスナーの両方を設定する必要があります。詳細については、RFC 2616 セクション 8.2.3 を参照してください。

• Authorization ヘッダーを送信すると、auth オプションを使用した基本認証の計算がオーバーライドされます。

options として URL を使用した例

const options = new URL('http://abc:[email protected]');

const req = http.request(options, (res) => {
  // ...
}); copy

リクエストが成功した場合、次のイベントが次の順序で発生します。

• 'socket'
• 'response'
  • res オブジェクトで 'data' が任意の回数発生します (レスポンスボディが空の場合、たとえばほとんどのリダイレクトでは 'data' はまったく発生しません)。
  • res オブジェクトで 'end' が発生します。
• 'close'

接続エラーが発生した場合、次のイベントが発生します。

• 'socket'
• 'error'
• 'close'

レスポンスが受信される前に接続が早期に切断された場合、次のイベントが次の順序で発生します。

• 'socket'
• メッセージ 'Error: socket hang up' とコード 'ECONNRESET' のエラーを伴う 'error'。
• 'close'

レスポンスが受信された後に接続が早期に切断された場合、次のイベントが次の順序で発生します。

• 'socket'
• 'response'
  • res オブジェクトで 'data' が任意の回数発生します。
• （ここで接続が切断されます）
• res オブジェクトで 'aborted' が発生します。
• メッセージ 'Error: aborted' とコード 'ECONNRESET' のエラーを伴う res オブジェクトで 'error' が発生します。
• 'close'
• res オブジェクトで 'close' が発生します。

ソケットが割り当てられる前に req.destroy() が呼び出された場合、次のイベントが次の順序で発生します。

• （ここで req.destroy() が呼び出されました）
• メッセージ 'Error: socket hang up' とコード 'ECONNRESET' のエラー、または req.destroy() が呼び出された際のエラーを伴う 'error'。
• 'close'

接続が成功する前に req.destroy() が呼び出された場合、次のイベントが次の順序で発生します。

• 'socket'
• （ここで req.destroy() が呼び出されました）
• メッセージ 'Error: socket hang up' とコード 'ECONNRESET' のエラー、または req.destroy() が呼び出された際のエラーを伴う 'error'。
• 'close'

レスポンスが受信された後に req.destroy() が呼び出された場合、次のイベントが次の順序で発生します。

• 'socket'
• 'response'
  • res オブジェクトで 'data' が任意の回数発生します。
• （ここで req.destroy() が呼び出されました）
• res オブジェクトで 'aborted' が発生します。
• メッセージ 'Error: aborted' とコード 'ECONNRESET' のエラー、または req.destroy() が呼び出された際のエラーを伴う res オブジェクトで 'error' が発生します。
• 'close'
• res オブジェクトで 'close' が発生します。

ソケットが割り当てられる前に req.abort() が呼び出された場合、次のイベントが次の順序で発生します。

• （ここで req.abort() が呼び出されました）
• 'abort'
• 'close'

接続が成功する前に req.abort() が呼び出された場合、次のイベントが次の順序で発生します。

• 'socket'
• （ここで req.abort() が呼び出されました）
• 'abort'
• メッセージ 'Error: socket hang up' とコード 'ECONNRESET' のエラーを伴う 'error'。
• 'close'

レスポンスが受信された後に req.abort() が呼び出された場合、次のイベントが次の順序で発生します。

• 'socket'
• 'response'
  • res オブジェクトで 'data' が任意の回数発生します。
• （ここで req.abort() が呼び出されました）
• 'abort'
• res オブジェクトで 'aborted' が発生します。
• メッセージ 'Error: aborted' とコード 'ECONNRESET' のエラーを伴う res オブジェクトで 'error' が発生します。
• 'close'
• res オブジェクトで 'close' が発生します。

timeout オプションの設定または setTimeout() 関数の使用は、リクエストを中止したり、'timeout' イベントを追加する以外は何もしません。

AbortSignal を渡し、対応する AbortController で abort() を呼び出すと、リクエストで .destroy() を呼び出すのと同じように動作します。具体的には、メッセージ 'AbortError: The operation was aborted'、コード 'ABORT_ERR'、および（提供されている場合は）cause を伴うエラーで 'error' イベントが発生します。

http.validateHeaderName(name[, label])#

• name <string>
• label <string> エラーメッセージのラベル。デフォルト: 'Header name'。

res.setHeader(name, value) が呼び出されたときに実行される、提供された name に対する低レベルの検証を実行します。

不正な値を name として渡すと、code: 'ERR_INVALID_HTTP_TOKEN' で識別される TypeError がスローされます。

HTTP リクエストまたはレスポンスにヘッダーを渡す前にこのメソッドを使用する必要はありません。HTTP モジュールは、このようなヘッダーを自動的に検証します。

例

import { validateHeaderName } from 'node:http';

try {
  validateHeaderName('');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code); // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message); // --> 'Header name must be a valid HTTP token [""]'
}const { validateHeaderName } = require('node:http');

try {
  validateHeaderName('');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code); // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message); // --> 'Header name must be a valid HTTP token [""]'
}copy

http.validateHeaderValue(name, value)#

• name <string>
• value <any>

res.setHeader(name, value) が呼び出されたときに実行される、提供された value に対する低レベルの検証を実行します。

不正な値を value として渡すと、TypeError がスローされます。

• 未定義の値エラーは code: 'ERR_HTTP_INVALID_HEADER_VALUE' で識別されます。
• 無効な文字の値エラーは code: 'ERR_INVALID_CHAR' で識別されます。

HTTP リクエストまたはレスポンスにヘッダーを渡す前にこのメソッドを使用する必要はありません。HTTP モジュールは、このようなヘッダーを自動的に検証します。

例

import { validateHeaderValue } from 'node:http';

try {
  validateHeaderValue('x-my-header', undefined);
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE'); // --> true
  console.error(err.message); // --> 'Invalid value "undefined" for header "x-my-header"'
}

try {
  validateHeaderValue('x-my-header', 'oʊmɪɡə');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code === 'ERR_INVALID_CHAR'); // --> true
  console.error(err.message); // --> 'Invalid character in header content ["x-my-header"]'
}const { validateHeaderValue } = require('node:http');

try {
  validateHeaderValue('x-my-header', undefined);
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE'); // --> true
  console.error(err.message); // --> 'Invalid value "undefined" for header "x-my-header"'
}

try {
  validateHeaderValue('x-my-header', 'oʊmɪɡə');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code === 'ERR_INVALID_CHAR'); // --> true
  console.error(err.message); // --> 'Invalid character in header content ["x-my-header"]'
}copy

http.setMaxIdleHTTPParsers(max)#

• max <number> デフォルト: 1000。

アイドル状態の HTTP パーサーの最大数を設定します。