Node.js v0.11.11 マニュアル & ドキュメンテーション

Index | View on single page | View as JSON

HTTP

HTTP#

Stability: 3 - Stable

HTTP サーバおよびクライアントを使用するにはいずれも require('http') が必要です。

Node の HTTP インタフェースは、伝統的に扱いが難しかったプロトコルの多くの機能をサポートするように設計されています。とりわけ大きくて、場合によってはチャンク化されたメッセージです。インタフェースは決してリクエストまたはレスポンス全体をバッファリングしないように気をつけています－利用者はストリームデータを使うことができます。

HTTP メッセージヘッダはこのようなオブジェクトとして表現されます:

{ 'content-length': '123',
  'content-type': 'text/plain',
  'connection': 'keep-alive',
  'host': 'mysite.com',
  'accept': '*/*' }

キーは小文字化されます。値は変更されません。

考えられる HTTP アプリケーションを完全にサポートするために、 Node の HTTP API はとても低水準です。それはストリームのハンドリングとメッセージの解析だけに対処します。解析はメッセージをヘッダとボディに分けますが、実際のヘッダとボディは解析しません。

複数の値を取ることができると定義されたヘッダは、, 区切りで連結されます。ただし、set-cookie および cookie ヘッダは例外で、値の配列で表現されます。 content-length のように単一の値だけを持つヘッダはそれに応じて解析され、その結果は一つだけの値として表現されます。

受信した生のヘッダは rawHeaders プロパティに保持されます。それは [key, value, key2, value2, ...] の配列です。たとえば、前述のメッセージヘッダオブジェクトは、以下のような rawHeaders を持つかもしれません:

[ 'ConTent-Length', '123456',
  'content-LENGTH', '123',
  'content-type', 'text/plain',
  'CONNECTION', 'keep-alive',
  'Host', 'mysite.com',
  'accepT', '*/*' ]

http.METHODS#

Array

パーサによってサポートされているHTTPメソッドの配列です。

http.STATUS_CODES#

Object

全ての HTTP 標準ステータスコードと短い説明のコレクションです。たとえば、http.STATUS_CODES[404] === 'Not Found'。

http.createServer([requestListener])#

新しい Web サーバオブジェクトを返します。

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

http.createClient([port], [host])#

この関数は deprecated です; 代わりに http.request() を使用してください。新しい HTTP クライアントを構築します。 port と host は接続するサーバを示します。

Class: http.Server#

これは以下のイベントを持つ EventEmitter です:

Event: 'request'#

function (request, response) { }

リクエストの度に生成されます。コネクションごとに複数のリクエストがあるかもしれないことに注意してください (Keep Alive なコネクションの場合)。 request は http.IncomingMessage のインスタンス、 response は http.ServerResponse のインスタンスです。

Event: 'connection'#

function (socket) { }

新しい TCP ストリームが確立した時。 socket は net.Socket 型のオブジェクトです。通常の利用者がこのイベントにアクセスしたくなることはないでしょう。とりわけ、ソケットはプロトコルパーサにアタッチされるため、 readable イベントを生成しません。 socket は request.connection からアクセスすることもできます。

Event: 'close'#

function () { }

サーバがクローズした時に生成されます。

Event: 'checkContinue'#

function (request, response) { }

httpの Expect: 100-continue リクエストを受信する度に生成されます。このイベントが監視されない場合、サーバは自動的に 100 Continue を応答します。

このイベントを処理する場合、クライアントがリクエストボディを送信し続けるべきなら response.writeContinue() を呼び出す必要があります。あるいは、クライアントがリクエストボディを送信し続けるべきでないなら、適切な HTTP レスポンス (例えば 400 Bad Request) を生成します。

このイベントが生成されて処理された場合、requestイベントは生成されないことに注意してください。

Event: 'connect'#

function (request, socket, head) { }

クライアントが HTTP の CONNECT メソッドを要求する度に生成されます。このイベントが監視されない場合、CONNECT メソッドを要求したクライアントのコネクションはクローズされます。

request はリクエストイベントの引数と同様に HTTP リクエストです。
socket はサーバとクライアントの間のネットワークソケットです。
head はトンネリングストリームの最初のパケットを持つ Buffer のインスタンスです。空の場合もあります。

このイベントが生成された後、リクエスト元のソケットはもう data イベントリスナーを持ちません。このソケットでサーバへ送られたデータを扱うためにそれをバインドしなければならないことを意味します。

Event: 'upgrade'#

function (request, socket, head) { }

クライアントが HTTP のアップグレードを要求する度に生成されます。このイベントが監視されない場合、アップグレードを要求したクライアントのコネクションはクローズされます。

request はリクエストイベントの引数と同様に HTTP リクエストです。
socket はサーバとクライアントの間のネットワークソケットです。
head はアップグレードストリームの最初のパケットを持つ Buffer のインスタンスです。空の場合もあります。

Event: 'clientError'#

function (exception, socket) { }

クライアントコネクションが 'error' イベントを発した場合－ここに転送されます。

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

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

指定されたポートとホスト名でコネクションの受け入れを開始します。ホスト名が省略されると、サーバはどんな IPv4 アドレスへの接続も受け入れます (INADDR_ANY)。

UNIX ドメインソケットを待ち受ける場合、ポートとホスト名ではなくファイル名を提供します。

バックログは保留された接続のキューの最大長です。実際の長さは Linux では tcp_max_syn_backlog や somaxconn など、 sysctl の設定を通じて OS によって決定されます。このパラメータのデフォルト値は 511 (512 ではありません) です。

この関数は非同期です。最後の引数の callback は 'listening' イベントのリスナとして加えられます。詳細は net.Server.listen(port) を参照してください。

server.listen(path, [callback])#

path で与えられたコネクションを待ち受ける UNIX ドメインソケットのサーバを開始します。

この関数は非同期です。最後の引数の callback は 'listening' イベントのリスナとして加えられます。詳細は net.Server.listen(path) を参照してください。

server.listen(handle, [callback])#

handle Object
callback Function

handle オブジェクトには、サーバまたはソケット (下層の _handle メンバならなんでも) または、 {fd: <n>} オブジェクトを設定することができます。

これによりサーバは指定したハンドルへの接続を受け付けることになりますが、ファイル記述子またはハンドルは既にポートまたはドメインソケットにバインドされているものと見なされます。

ファイル記述子へのリスニングは Windows ではサポートされません。

この関数は非同期です。最後の引数の callback は 'listening' イベントのリスナとして加えられます。詳細は net.Server.listen() を参照してください。

server.close([callback])#

サーバが新しいコネクションを受け付けるのを終了します。 net.Server.close() を参照してください。

server.maxHeadersCount#

受け付けるヘッダ数の上限で、デフォルトは 1000 です。 0 に設定されると、制限しないことになります。

server.setTimeout(msecs, callback)#

msecs Number
callback Function

ソケットにタイムアウト値を設定し、サーバオブジェクト上で 'timeout' イベントを生成します。タイムアウトが発生すると、ソケットが引数として渡されます。

サーバオブジェクトに 'timeout' イベントのリスナが存在すると、それはタイムアウトしたソケットを引数として呼び出されます。

デフォルトでは、サーバのタイムアウト値は 2 分で、タイムアウトしたソケットは自動的に破棄されます。しかしながら、'timeout' イベントのコールバックをサーバに割り当てた場合、タイムアウトしたソケットのハンドリングはあなたの責務となります。

server.timeout#

{Number} デフォルト = 120000 (2 分)

不活性なソケットがタイムアウトしたと推定されるまでのミリ秒を表す数値。

ソケットのタイムアウト処理は接続のセットアップ時に行われるため、この値の変更は既存の接続ではなく、サーバへの 新しい 接続にだけ影響することに注意してください。

0 を設定すると、到着する接続に対する自動的なタイムアウトの振る舞いは無効になります。

Class: http.ServerResponse#

このオブジェクトは HTTP サーバ内部－ユーザではなく－で作成されます。 'request' リスナーの第 2 引数として渡されます。

レスポンスは Writable Stream インタフェースを実装します。これは以下のイベントを持つ EventEmitter です:

Event: 'close'#

function () { }

response.end() が呼び出されたりフラッシュされる前に、下層の接続が切断されたことを示します。

Event: 'finish'#

function () { }

レスポンスが送信されると生成されます。より詳しくいうと、このイベントはレスポンスヘッダおよびボディの最後のセグメントがネットワーク上へ転送するためにオペレーティングシステムに渡されると生成されます。それはクライアントが何かを受信したことを意味しません。

このイベントの後、レスポンスオブジェクトはどんなイベントも生成しません。

response.writeContinue()#

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

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

レスポンスヘッダを送信します。ステータスコードは 404 のような 3 桁の数字による HTTP ステータスコードです。最後の引数 headers は、レスポンスヘッダです。オプションとして人に読める形式の statusMessage を第 2 引数で与えることができます。

例:

var body = 'hello world';
response.writeHead(200, {
  'Content-Length': body.length,
  'Content-Type': 'text/plain' });

このメソッドはメッセージごとに 1 回だけ呼び出されなくてはならず、 response.end() の前に呼び出されなければなりません。

もしこのメソッドが呼び出される前に response.write() または response.end() が呼ばれると、暗黙的で可変のヘッダが算出されてこの関数が呼び出されます。

注意: Content-Length は文字数ではなくバイト数で与えられます。上の例が動作するのは 'hello world' という文字列が単一バイト文字だけを含むためです。もしボディがより上位にコード化された文字を含む場合は、指定したエンコーディングによるバイト数を得るために Buffer.byteLength() を使うべきです。 Node は、Content-Length と実際に送信されたレスポンスボディの長さが等しいかどうかチェックしません。

response.setTimeout(msecs, callback)#

msecs Number
callback Function

ソケットのタイムアウト値を msec に設定します。コールバックが与えられると、それはレスポンスオブジェクトの 'timeout' イベントのリスナとして加えられます。

リクエスト、レスポンス、そしてサーバのいずれにも 'timeout' リスナが存在しない場合、タイムアウトしたソケットは破棄されます。もしリクエスト、レスポンス、サーバのいずれかに 'timeout' イベントを設定した場合、タイムアウトしたソケットのハンドリングはあなたの責務となります。

response.statusCode#

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

例:

response.statusCode = 404;

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

response.statusMessage#

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

例:

response.statusMessage = 'Not found';

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

response.setHeader(name, value)#

暗黙的ヘッダのヘッダ値を設定します。送信されようとしているレスポンスヘッダにこのヘッダが既に含まれている場合、その値は置き換えられます。同じ名前で複数のヘッダを送信したい場合は文字列の配列を使ってください。

例:

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

または

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

response.headersSent#

(読み込み専用の) Boolean。ヘッダが送信済みなら true、それ以外は false です。

response.sendDate#

true の場合、Date ヘッダが自動的に生成され、レスポンスとして送信されます (headers にすでに与えられていない場合)。デフォルトは true です。

これを無効にするのはテストでのみにすべきです。 HTTP はレスポンスに Date ヘッダを要求します。

response.getHeader(name)#

すでにキューに入れられているが未送信のヘッダを読み上げます．名前は大文字小文字を区別しないことに注意してください。これはヘッダが暗黙的にフラッシュされる前だけ呼び出すことができます。

例:

var contentType = response.getHeader('content-type');

response.removeHeader(name)#

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

例:

response.removeHeader("Content-Encoding");

response.write(chunk, [encoding])#

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

これはレスポンスボディのチャンクを送信します。このメソッドはボディの連続した部分を提供するために複数回呼び出されるかもしれません。

chunk は文字列またはバッファにすることができます。 chunk が文字列の場合、どのエンコードでバイトストリームにするかを第 2 引数で指定します。デフォルトの encoding は 'utf8' です。

注意: これは生の HTTP ボディで、高水準のマルチパートボディエンコーディングで使われるものとは無関係です。

初めて response.write() が呼び出されると、バッファリングされていたヘッダ情報と最初のボディがクライアントに送信されます。 2 回目に response.write() が呼ばれると、 Node はストリーミングデータを分割して送信しようとしていると仮定します。すなわち、レスポンスはボディの最初のチャンクまでバッファリングされます。

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

response.addTrailers(headers)#

このメソッドは 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();

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

このメソッドはレスポンスの全てのヘッダとボディを送信したことをサーバに伝えます; サーバはメッセージが終了したと考えるべきです。この response.end() メソッドは各レスポンスごとに呼び出さなければなりません。

data が指定された場合、 response.write(data, encoding) に続けて response.end() を呼び出すのと等価です。

http.request(options, [callback])#

Node は HTTP リクエストを行うために、サーバごとにいくつかのコネクションを保持します。この関数はその一つを使って透過的にリクエストを発行できるようにします。

options はオブジェクトまたは文字列です。もし options が文字列なら、それは url.parse() によって自動的に解析されます。

オプション:

host: リクエストを発行するサーバのドメイン名または IP アドレス。
hostname: url.parse() サポート。hostname は host を上書きします。
port: リモートサーバのポート。デフォルトは 80 です。
localAddress: ネットワーク接続をバインドするローカルインタフェースです。
socketPath: Unix ドメインソケット (host:port または socketPath のどちらか)
method: HTTP リクエストのメソッドの文字列。デフォルトは 'GET' です。
path: リクエストのパス。デフォルトは '/' です。必要なら問い合わせ文字列を含めるべきです．例 '/index.html?page=12' 。リクエストパスが不正な文字を含んでいる場合は、例外がスローされます。現在はスペースだけが拒否されますが、それは将来変更されるかもしれません。
headers: リクエストヘッダを含むオブジェクト。
auth: ベーシック認証すなわち Authorization ヘッダのための 'user:password'。
agent: Agent の振る舞いを制御します。エージェントが使われる場合、Connection:keep-alive がデフォルトになります。可能な値は:
- undefined (デフォルト): ホストとポートで global Agent を使用します。
- Agent オブジェクト: 明示的に渡された Agent を使用します。
- false: Agent によるコネクションプーリングを使用しません。 Connection:close の場合のデフォルトです。
- keepAlive: {Boolean} 将来、他のリクエストで使用できるように、ソケットをプールに保持します。デフォルトは false です。
- keepAliveMsecs: {Integer} HTTP キープアライブが使用された場合、ソケットの接続を維持するために TCP キープアライブパケットを送信する間隔です。 keepAlive が true に設定された場合だけ関係があります。

オプションの callback 引数は、'response' イベントの一回限りのリスナとして加えられます。

http.request() は http.ClientRequest クラスのインスタンスを返します。 http.ClientRequest のインスタンスは書き込み可能なストリームです。もし POST リクエストでファイルのアップロードがしたければ、 http.ClientRequest オブジェクトに出力してください。

例:

var options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST'
};

var req = http.request(options, function(res) {
  console.log('STATUS: ' + res.statusCode);
  console.log('HEADERS: ' + JSON.stringify(res.headers));
  res.setEncoding('utf8');
  res.on('data', function (chunk) {
    console.log('BODY: ' + chunk);
  });
});

req.on('error', function(e) {
  console.log('problem with request: ' + e.message);
});

// write data to request body
req.write('data\n');
req.write('data\n');
req.end();

この例で req.end() が呼ばれていることに注意してください。 http.request() では、リクエストが終了したことを示すために、常に req.end() を呼び出さなければなりません - リクエストのボディに出力するデータがなかったとしても。

リクエスト中に何らかのエラー (DNS 解決、TCP レベルのエラー、HTTP パースエラーなど) が発生すると、戻り値のリクエストオブジェクトで 'error' イベントが生成されます。

いくつかの特別なヘッダに注意が必要です。

'Connection: keep-alive' の送信は、サーバへのコネクションを次のリクエストまで持続することを Node に通知します。
'Content-length' ヘッダの送信は、デフォルトのチャンクエンコーディングを無効にします。
'Expect' ヘッダの送信は、リクエストヘッダを即時に送信します。通常、'Expect: 100-continue' を送信すると、タイムアウトと continue イベントを待ち受けます。詳細は RFC2616 の 8.2.3 節を参照してください。
Authorization ヘッダの送信は、auth オプションによるベーシック認証を上書きします。

http.get(options, [callback])#

ほとんどのリクエストは本文のない GET リクエストであるため、 Node は便利なメソッドを提供します。このメソッドと http.request() の間の違いは、メソッドを GET に設定して req.end() を自動的に呼び出すことだけです。

例:

http.get("http://www.google.com/index.html", function(res) {
  console.log("Got response: " + res.statusCode);
}).on('error', function(e) {
  console.log("Got error: " + e.message);
});

Class: http.Agent#

HTTP エージェントは HTTP クライアントリクエストでソケットをプーリングするためのものです。

HTTP エージェントでは、クライアントリクエストはデフォルトで Connection:keep-alive を使います。ソケットを待ってペンディングになっている HTTP リクエストがなければ、ソケットはクローズされます。これは、node のプールは高負荷時に keep-alive のメリットを持ちながら、 keep-alive を使用する HTTP クライアントの開発者が手動でクローズする必要がないことを意味します。 -->

より積極的に HTTP キープアライブを使用したければ、keepAlive フラグを true に設定してエージェントを生成します (後述するコンストラクタオプション参照)。すると、エージェントは未使用のソケットを後で使うためにプールに維持します。それらは Node プロセスの実行を維持しないように明示的にマークされます。しかし、キープアライブなエージェントがもはや使われなくなった場合に明示的に destroy() を呼び出すのはいいことです。すると、ソケットはシャットダウンされます。

ソケットは 'close' イベントまたは特別な 'agentRemove' イベントが生成された時にエージェントのプールから削除されます。これは、一つの HTTP リクエストを長時間オープンしたままにするために、プールにソケットがとどまらないことを意図するなら、以下のようにすることができることを意味します:

http.get(options, function(res) {
  // Do stuff
}).on("socket", function (socket) {
  socket.emit("agentRemove");
});

別の方法として、 agent: false を指定することで、プーリングを使用しないこともできます:

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

new Agent([options])#

options {Object} エージェントに設定される構成可能なオプションの集合。以下のフィールドを持つことができます:
- keepAlive: {Boolean} 将来、他のリクエストで使用できるように、ソケットをプールに保持します。デフォルトは false です。
- keepAliveMsecs: {Integer} HTTP キープアライブが使用された場合、ソケットの接続を維持するために TCP キープアライブパケットを送信する間隔。 keepAlive が true に設定された場合だけ関係があります。
- maxSockets {Number} ホスト毎に許されるソケットの最大数。デフォルトは Infinity。
- maxFreeSockets {Number} フリーな状態でオープンしたままにするソケットの最大数。デフォルトは 256。

http.request によって使われるデフォルトの http.globalAgent は、これら全ての値をそれぞれのデフォルトに設定しています。

これらの値を構成するためには、独自の Agent オブジェクトを作成する必要があります。

var http = require('http');
var keepAliveAgent = new http.Agent({ keepAlive: true });
keepAliveAgent.request(options, onResponseCallback);

agent.maxSockets#

デフォルトでは無制限に設定されます。エージェントがいくつのソケットを並行にオープンするかを決定します。

agent.maxFreeSockets#

デフォルトでは 256 に設定されます。 HTTP キープアライブをサポートするエージェントでは、空いた状態でオープンしたままにされるソケットの最大数を設定します。

agent.sockets#

エージェントが現在使っているソケットの配列です。変更しないでください。

agent.freeSockets#

HTTP キープアライブが使われているエージェントの場合、使われるのを待っているソケットの配列です。変更しないでください。

agent.requests#

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

agent.destroy()#

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

通常、これは必要ありません。しかしながら、キープアライブが有効なエージェントを使用していて、それがもう必要ないとわかっているなら、エージェントを明示的にシャットダウンするのがベストです。そうでなければ、サーバがそれらを解放するまで、ソケットはとても長い時間オープンしたままになるかもしれません。

agent.getName(options)#

接続が再利用できるかどうかを決定するために、リクエストのオプションからユニークな名前を返します。 http のエージェントでは、これは host:port:localAddress です。 https のエージェントでは、名前は CA，証明書、暗号、その他 HTTPS/TLS に特有のオプションによってソケットの再利用性が決定されます。

http.globalAgent#

全ての HTTP クライアントリクエストで使用される、デフォルトの Agent のインスタンスです。

Class: http.ClientRequest#

このオブジェクトは HTTP サーバ内部で作成され、http.request() から返されます。それはヘッダがキューに入れられた 進行中 のリクエストを表現します。ヘッダは setHeader(name, value), getHeader(name), removeHeader(name) API によってまだ可変のままです。実際にヘッダが送信されるのは、最初のデータチャンクが送信される時またはコネクションがクローズされる時です。

レスポンスを取得するには、'response' 用のリスナーをリクエストオブジェクトに加えます。 'response' イベントはレスポンスヘッダを受信するとリクエストオブジェクトによって生成されます。 'response' イベントは http.IncomingMessage のインスタンスを唯一の引数として実行されます。

'response' イベントの間、レスポンスオブジェクトにリスナーを加えることができます; とりわけ 'data' イベントのリスナーです。

'response' ハンドラが加えられない場合、レスポンスは完全に捨てられます。しかし、'response' イベントハンドラを加えた場合は、 'readable' イベントが発生した時に response.read() を呼ぶか、 'data' ハンドラを加えるか、.resume() メソッドを呼び出すかのいずれかにより、レスポンスオブジェクトからのデータを消費しなければ なりません 。データが消費されるまで、'end' イベントは生成されません。また、データは読まれるまでメモリを消費し、'process out of memory' エラーにつながることになります。

注意: Node は Content-Length と実際に送信されたリクエストボディの長さが等しいかどうかチェックしません。

リクエストは Writable Stream インタフェースを実装します。これは以下のイベントを持つ EventEmitter です。

Event: 'response'#

function (response) { }

このリクエストに対するレスポンスを受信した時に生成されます。このイベントは一回だけ生成されます。 response 引数は http.IncomingMessage のインスタンスです。

オプション:

host: リクエストを発行するサーバのドメイン名または IP アドレス。
port: リモートサーバのポート。
soocketPath: Unix ドメインソケット (host:port または socketPath のどちらか)

Event: 'socket'#

function (socket) { }

このリクエストにソケットが割り当てられた後に生成されます。

Event: 'connect'#

function (response, socket, head) { }

サーバが CONNECT メソッドの要求に応答する度に生成されます。このイベントが監視されていない場合、クライアントが CONNECT メソッドへのレスポンスを受信すると、そのコネクションはクローズされます。

どのように connect イベントを監視するかを示すクライアントとサーバのペア:

var http = require('http');
var net = require('net');
var url = require('url');

// Create an HTTP tunneling proxy
var proxy = http.createServer(function (req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end('okay');
});
proxy.on('connect', function(req, cltSocket, head) {
  // connect to an origin server
  var srvUrl = url.parse('http://' + req.url);
  var srvSocket = net.connect(srvUrl.port, srvUrl.hostname, function() {
    cltSocket.write('HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node-Proxy\r\n' +
                    '\r\n');
    srvSocket.write(head);
    srvSocket.pipe(cltSocket);
    cltSocket.pipe(srvSocket);
  });
});

// now that proxy is running
proxy.listen(1337, '127.0.0.1', function() {

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

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

  req.on('connect', function(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', function(chunk) {
      console.log(chunk.toString());
    });
    socket.on('end', function() {
      proxy.close();
    });
  });
});

Event: 'upgrade'#

function (response, socket, head) { }

サーバがアップグレード要求に応答する度に生成されます。このイベントが監視されていない場合、クライアントがアップグレードヘッダを受信するとそのコネクションはクローズされます。

どのように upgrade イベントを監視するかを示すクライアントとサーバのペア:

var http = require('http');

// Create an HTTP server
var srv = http.createServer(function (req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end('okay');
});
srv.on('upgrade', function(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
srv.listen(1337, '127.0.0.1', function() {

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

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

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

Event: 'continue'#

function () { }

通常、リクエストが 'Expect: 100-continue' を含んでいたことにより、サーバが '100 Continue' HTTP レスポンスを送信することで生成されます。これはクライアントがリクエストボディを送信すべき事を示します。

request.write(chunk, [encoding])#

ボディのチャンクを送信します。このメソッドを何回も呼び出すと、サーバへのリクエストボディをストリーム化できます－このケースは ['Transfer-Encoding', 'chunked'] ヘッダでリクエストを生成したことを意味します。

chunk 引数は Buffer または文字列です。

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

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

リクエストの送信を終了します。ボディのいくつかの部分がまだ送信されていない場合、それはストリームにフラッシュされます。リクエストがチャンク化されている場合、これは終端の '0\r\n\r\n' を送信します。

data が指定された場合は、 request.write(data, encoding) に続けて request.end() を呼び出すのと等価です。

request.abort()#

リクエストをアボートします (v0.3.8 からの新機能)

request.setTimeout(timeout, [callback])#

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

request.setNoDelay([noDelay])#

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

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

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

http.IncomingMessage#

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

これは Readable Stream インタフェースの実装で、以下のイベント、メソッド、およびプロパティを追加で持ちます。

Event: 'close'#

function () { }

下層の接続が切断されたことを示します。 'end' と同様、このイベントはレスポンス毎に一度だけ生成されます。

'end' のように、このイベントはレスポンス毎に一回生成され、 'data' イベントはそれ以上生成されません。 http.ServerResponse の 'close' イベントにより多くの情報があります。

message.httpVersion#

サーバリクエストの場合、クライアントが送信した HTTP バージョンです。クライアントレスポンスの場合、接続したサーバの HTTP バージョンです。いずれの場合も '1.1' または '1.0' です。

同様に response.httpVersionMajor は最初の整数、 response.httpVersionMinor は 2 番目の整数です。

message.headers#

リクエスト／レスポンスヘッダオブジェクトです。

ヘッダ名と値のリードオンリーなマップです。ヘッダ名は小文字です。例:

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

message.rawHeaders#

受信したものと正確に等しい生のリクエスト／レスポンスヘッダのリストです。

キーと値は同じリストに含まれることに注意してください。これはタプルのリストでは ありません 。すなわち、偶数番目はキーで、奇数番目は関連づけられた値です。

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

// 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);

message.trailers#

リクエスト／レスポンスのトレーラオブジェクトです。 'end' イベントが生成されて以降のみ存在します。

message.rawTrailers#

受信したものと正確に等しい生のリクエスト／レスポンストレーラのリストです。 'end' イベントが生成されて以降のみ存在します。

message.setTimeout(msecs, callback)#

msecs Number
callback Function

message.connection.setTimeout(msecs, callback) を呼びます。

message.method#

http.Server から得たリクエストでのみ有効です

リクエストメソッドを表す文字列です。参照のみ可能です。例: 'GET'、'DELETE'

message.url#

http.Server から得たリクエストでのみ有効です

リクエスト URL を表す文字列です。これは実際の HTTP リクエストに存在する URL だけを含みます。もしリクエストが:

GET /status?name=ryan HTTP/1.1\r\n
Accept: text/plain\r\n
\r\n

この場合の request.url はこうなります:

'/status?name=ryan'

URL の要素を解析したい場合は、 require('url').parse(request.url) を参照してください。例:

node> require('url').parse('/status?name=ryan')
{ href: '/status?name=ryan',
  search: '?name=ryan',
  query: 'name=ryan',
  pathname: '/status' }

問い合わせ文字列からパラメータを取り出したい場合は、 require('querystring').parse 関数を参照するか、 require('url').parse の第 2 引数に true を渡してください。例:

node> require('url').parse('/status?name=ryan', true)
{ href: '/status?name=ryan',
  search: '?name=ryan',
  query: { name: 'ryan' },
  pathname: '/status' }

message.statusCode#

http.ClientRequest から得たレスポンスでのみ有効です

3 桁の数字によるレスポンスのステータスコードです。例えば 404。

message.statusMessage#

http.ClientRequest から得たレスポンスでのみ有効です

HTTP レスポンスのステータスメッセージ (reason phrase)。例: OK や Internal Server Error。

message.socket#

コネクションに関連づけられた net.Socket オブジェクトです。

HTTPS では request.connection.verifyPeer() と request.connection.getPeerCertificate() でクライアントの認証の詳細を取得できます。

Table of Contents

HTTP#

http.METHODS#

http.STATUS_CODES#

http.createServer([requestListener])#

http.createClient([port], [host])#

Class: http.Server#

Event: 'request'#

Event: 'connection'#

Event: 'close'#

Event: 'checkContinue'#

Event: 'connect'#

Event: 'upgrade'#

Event: 'clientError'#

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

server.listen(path, [callback])#

server.listen(handle, [callback])#

server.close([callback])#

server.maxHeadersCount#

server.setTimeout(msecs, callback)#

server.timeout#

Class: http.ServerResponse#

Event: 'close'#

Event: 'finish'#

response.writeContinue()#

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

response.setTimeout(msecs, callback)#

response.statusCode#

response.statusMessage#

response.setHeader(name, value)#

response.headersSent#

response.sendDate#

response.getHeader(name)#

response.removeHeader(name)#

response.write(chunk, [encoding])#

response.addTrailers(headers)#

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

http.request(options, [callback])#

http.get(options, [callback])#

Class: http.Agent#

new Agent([options])#

agent.maxSockets#

agent.maxFreeSockets#

agent.sockets#

agent.freeSockets#

agent.requests#

agent.destroy()#

agent.getName(options)#

http.globalAgent#

Class: http.ClientRequest#

Event: 'response'#

Event: 'socket'#

Event: 'connect'#

Event: 'upgrade'#

Event: 'continue'#

request.write(chunk, [encoding])#

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

request.abort()#

request.setTimeout(timeout, [callback])#

request.setNoDelay([noDelay])#

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

http.IncomingMessage#

Event: 'close'#

message.httpVersion#

message.headers#

message.rawHeaders#

message.trailers#

message.rawTrailers#

message.setTimeout(msecs, callback)#

message.method#

message.url#

message.statusCode#

message.statusMessage#

message.socket#