Node.js v0.4.12 Manual & Documentation


Table Of Contents


HTTP

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

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

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

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

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

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

http.Server

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

Event: 'request'

function (request, response) { }

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

requesthttp.ServerRequest のインスタンス、 responsehttp.ServerResponse のインスタンスです。

Event: 'connection'

function (socket) { }

新しい TCP ストリームが確立した時。 socketnet.Socket 型のオブジェクトです。 通常の利用者がこのイベントにアクセスしたくなることはないでしょう。 socketrequest.connection からアクセスすることもできます。

Event: 'close'

function (errno) { }

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

Event: 'checkContinue'

function (request, response) { }

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

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

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

Event: 'upgrade'

function (request, socket, head) { }

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

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

Event: 'clientError'

function (exception) { }

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

http.createServer([requestListener])

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

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

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

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

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

この関数は非同期です。最後の引数の callback はサーバがポートをバインドすると呼び出されます。

server.listen(path, [callback])

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

この関数は非同期です。最後の引数の callback はサーバがバインドすると呼び出されます。

server.close()

サーバが新しいコネクションを受け付けるのを終了します。

http.ServerRequest

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

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

Event: 'data'

function (chunk) { }

メッセージボディの断片を受信した場合に生成されます。

例: 一つの引数としてボディのチャンクが与えられます。 転送エンコーディングでデコードされます。 ボディのチャンクは文字列です。 ボディのエンコーディングは request.setBodyEncoding() で設定されます。

Event: 'end'

function () { }

リクエストごとに厳密に一回生成されます。 その後、このリクエストで 'data' イベントが生成されることはありません。

Event: 'close'

function (err) { }

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

err パラメータは常に与えられ、クローズの理由を示します。

err.code === 'timeout' は下層のコネクションがタイムアウトしたことを示します。 これは、全ての着信側の接続はデフォルト 2 分でタイムアウトするために発生します。

err.code === 'aborted' はクライアントが仮想の接続をいち早く切断したことを 意味します。

'end' と同様、このイベントはリクエスト上で一度だけ発生し、その後ではもう 'data' イベントが発生することはありません。

注意: 'close''end' の後で発生することがあります。 その逆もあります。

request.method

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

request.url

リクエスト 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' }

request.headers

参照のみ可能です。

request.trailers

参照のみ可能です; HTTP のトレーラです (もしあれば)。'end' イベントの後にだけ発生します。

request.httpVersion

HTTP プロトコルのバージョンを表す文字列です。参照のみ可能です。例: '1.1''1.0'。 同様に request.httpVersionMajor は最初の整数、 request.httpVersionMinor は 2 番目の整数です。

request.setEncoding(encoding=null)

リクエストボディのエンコーディングを設定します。 'utf8' または 'binary' のいずれかです。 デフォルトは null で、'data' イベントが Buffer を生成することを意味します。

request.pause()

リクエストによるイベントの生成を中断します。アップロード速度を落とすのに便利です。

request.resume()

中断されたリクエストを再開します。

request.connection

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

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

http.ServerResponse

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

response.writeContinue()

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

response.writeHead(statusCode, [reasonPhrase], [headers])

レスポンスヘッダを送信します。 ステータスコードは 404 のような 3 桁の数字による HTTP ステータスコードです。 最後の引数 headers は、レスポンスヘッダです。 オプションとして人に読める形式の reasonPhrase を第 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.statusCode

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

例:

response.statusCode = 404;

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

response.setHeader(name, value)

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

例:

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

or

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

response.getHeader(name)

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

例:

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

response.removeHeader(name)

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

例:

response.removeHeader("Content-Encoding");

response.write(chunk, encoding='utf8')

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

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

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

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

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

response.addTrailers(headers)

このメソッドは HTTP トレーラヘッダ (メッセージの最後に置かれるヘッダ) をレスポンスに追加します。

トレーラはレスポンスがチャンク化されたエンコーディングでのみ生成されます; そうでなければ (例えばリクエストが HTTP/1.0)、黙って破棄されます。

HTTP は、トレーラを生成するならそのヘッダフィールドのリストを値として Trailer ヘッダを送信することを要求していることに注意してください。

response.writeHead(200, { 'Content-Type': 'text/plain',
                          'Trailer': 'TraceInfo' });
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 リクエストを行うために、サーバごとにいくつかのコネクションを保持します。 この関数はその一つを使って透過的にリクエストを発行できるようにします。

オプション:

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

例:

var options = {
  host: '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' イベントが生成されます。

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

http.get(options, callback)

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

例:

var options = {
  host: 'www.google.com',
  port: 80,
  path: '/index.html'
};

http.get(options, function(res) {
  console.log("Got response: " + res.statusCode);
}).on('error', function(e) {
  console.log("Got error: " + e.message);
});

http.Agent

http.getAgent(host, port)

http.request() は HTTP サーバへの複数のコネクションを管理する特別な Agent を使用します。 通常 Agent インスタンスはユーザコードに出てきませんが、特定の状況ではエージェントの状態をチェックすることが役に立ちます。 http.getAgent() 関数はエージェントへのアクセスを可能にします。

Event: 'upgrade'

function (response, socket, head) { }

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

http.getAget を使ってどのように upgrade イベントを監視するかを示す、 クライアントとサーバのペア:

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

// 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, upgradeHead) {
  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
               'Upgrade: WebSocket\r\n' +
               'Connection: Upgrade\r\n' +
               '\r\n\r\n');

  socket.ondata = function(data, start, end) {
    socket.write(data.toString('utf8', start, end), 'utf8'); // echo back
  };
});

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

  // make a request
  var agent = http.getAgent('127.0.0.1', 1337);

  var options = {
    agent: agent,
    port: 1337,
    host: '127.0.0.1',
    headers: {
      'Connection': 'Upgrade',
      'Upgrade': 'websocket'
    }
  };

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

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

agent.maxSockets

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

agent.sockets

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

agent.queue

ソケットへの送信を待機しているリクエストのキューです。

http.ClientRequest

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

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

'response' イベントの間、レスポンスオブジェクトにリスナーを加えることができます; とりわけ 'data' イベントのリスナーです。 'response' イベントはレスポンスボディのどの部分を受信するよりも前に呼び出されることに注意してください。 そのため、ボディの最初の部分の受信と競合することを心配する必要はありません。 'response' イベントの間に 'data' イベントのリスナーが加えられる限り、 ボディ全体を受信することができます。

// Good
request.on('response', function (response) {
  response.on('data', function (chunk) {
    console.log('BODY: ' + chunk);
  });
});

// Bad - misses all or part of the body
request.on('response', function (response) {
  setTimeout(function () {
    response.on('data', function (chunk) {
      console.log('BODY: ' + chunk);
    });
  }, 10);
});

これは Writable Stream です。 注意: Node は Content-Length ヘッダの値と、 実際に送信されたボディの長さが等しいかをチェックしません。

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

Event: 'continue'

function () { }

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

Event 'response'

function (response) { }

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

request.write(chunk, encoding='utf8')

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

chunk 引数は整数の配列か文字列になります。

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

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

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

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

request.abort()

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

http.ClientResponse

このオブジェクトは http.request() によってリクエストと一緒に作成されます。 これはリクエストオブジェクトの 'response' イベントに渡されます。

レスポンスは Readable Stream インタフェースを実装します。

Event: 'data'

function (chunk) { }

メッセージボディの断片を受信した場合に生成されます。

Event: 'end'

function () { }

メッセージごとに厳密に一回だけ生成されます。 このイベントが生成された後、このレスポンスはどんなイベントも生成しません。

Event: 'close'

function (err) { }

'end' イベントが生成される前に下層の接続が切断されたことを示します。 http.ServerRequest'close' イベントにより多くの情報があります。

response.statusCode

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

response.httpVersion

接続しているサーバとの HTTP のバージョンです。 おそらく '1.1' または '1.0' のどちらかです。 同様に response.httpVersionMajor は最初の整数、 response.httpVersionMinor は 2 番目の整数です。

response.headers

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

response.trailers

レスポンスのトレーラオブジェクトです。 'end' イベントの後にだけ発生します。

response.setEncoding(encoding=null)

レスポンスボディのエンコーディングを設定します。 'utf8''ascii'、あるいは 'base64' のいずれかです。 デフォルトは null で、 'data' イベントが Buffer を生成することを意味します。

response.pause()

イベントの生成によるレスポンスを中断します。ダウンロード速度を落とすのに便利です。

response.resume()

中断されていたレスポンスを再開します。