Current File : //proc/self/root/usr/src/node-v0.10.4/doc/api/http.json
{
"source": "doc/api/http.markdown",
"modules": [
{
"textRaw": "HTTP",
"name": "http",
"stability": 3,
"stabilityText": "Stable",
"desc": "<p>To use the HTTP server and client one must <code>require('http')</code>.\n\n</p>\n<p>The HTTP interfaces in Node are designed to support many features\nof the protocol which have been traditionally difficult to use.\nIn particular, large, possibly chunk-encoded, messages. The interface is\ncareful to never buffer entire requests or responses--the\nuser is able to stream data.\n\n</p>\n<p>HTTP message headers are represented by an object like this:\n\n</p>\n<pre><code>{ 'content-length': '123',\n 'content-type': 'text/plain',\n 'connection': 'keep-alive',\n 'accept': '*/*' }</code></pre>\n<p>Keys are lowercased. Values are not modified.\n\n</p>\n<p>In order to support the full spectrum of possible HTTP applications, Node's\nHTTP API is very low-level. It deals with stream handling and message\nparsing only. It parses a message into headers and body but it does not\nparse the actual headers or the body.\n\n\n</p>\n",
"properties": [
{
"textRaw": "`STATUS_CODES` {Object} ",
"name": "STATUS_CODES",
"desc": "<p>A collection of all the standard HTTP response status codes, and the\nshort description of each. For example, <code>http.STATUS_CODES[404] === 'Not\nFound'</code>.\n\n</p>\n"
},
{
"textRaw": "http.globalAgent",
"name": "globalAgent",
"desc": "<p>Global instance of Agent which is used as the default for all http client\nrequests.\n\n\n</p>\n"
},
{
"textRaw": "http.IncomingMessage",
"name": "IncomingMessage",
"desc": "<p>An <code>IncomingMessage</code> object is created by <code>http.Server</code> or <code>http.ClientRequest</code>\nand passed as the first argument to the <code>'request'</code> and <code>'response'</code> event\nrespectively. It may be used to access response status, headers and data.\n\n</p>\n<p>It implements the [Readable Stream][] interface, as well as the\nfollowing additional events, methods, and properties.\n\n</p>\n",
"events": [
{
"textRaw": "Event: 'close'",
"type": "event",
"name": "close",
"desc": "<p><code>function () { }</code>\n\n</p>\n<p>Indicates that the underlaying connection was terminated before\n<code>response.end()</code> was called or able to flush.\n\n</p>\n<p>Just like <code>'end'</code>, this event occurs only once per response. See\n[http.ServerResponse][]'s <code>'close'</code> event for more information.\n\n</p>\n",
"params": []
}
],
"properties": [
{
"textRaw": "message.httpVersion",
"name": "httpVersion",
"desc": "<p>In case of server request, the HTTP version sent by the client. In the case of\nclient response, the HTTP version of the connected-to server.\nProbably either <code>'1.1'</code> or <code>'1.0'</code>.\n\n</p>\n<p>Also <code>response.httpVersionMajor</code> is the first integer and\n<code>response.httpVersionMinor</code> is the second.\n\n</p>\n"
},
{
"textRaw": "message.headers",
"name": "headers",
"desc": "<p>The request/response headers object.\n\n</p>\n<p>Read only map of header names and values. Header names are lower-cased.\nExample:\n\n</p>\n<pre><code>// Prints something like:\n//\n// { 'user-agent': 'curl/7.22.0',\n// host: '127.0.0.1:8000',\n// accept: '*/*' }\nconsole.log(request.headers);</code></pre>\n"
},
{
"textRaw": "message.trailers",
"name": "trailers",
"desc": "<p>The request/response trailers object. Only populated after the 'end' event.\n\n</p>\n"
},
{
"textRaw": "message.method",
"name": "method",
"desc": "<p><strong>Only valid for request obtained from <code>http.Server</code>.</strong>\n\n</p>\n<p>The request method as a string. Read only. Example:\n<code>'GET'</code>, <code>'DELETE'</code>.\n\n</p>\n"
},
{
"textRaw": "message.url",
"name": "url",
"desc": "<p><strong>Only valid for request obtained from <code>http.Server</code>.</strong>\n\n</p>\n<p>Request URL string. This contains only the URL that is\npresent in the actual HTTP request. If the request is:\n\n</p>\n<pre><code>GET /status?name=ryan HTTP/1.1\\r\\n\nAccept: text/plain\\r\\n\n\\r\\n</code></pre>\n<p>Then <code>request.url</code> will be:\n\n</p>\n<pre><code>'/status?name=ryan'</code></pre>\n<p>If you would like to parse the URL into its parts, you can use\n<code>require('url').parse(request.url)</code>. Example:\n\n</p>\n<pre><code>node> require('url').parse('/status?name=ryan')\n{ href: '/status?name=ryan',\n search: '?name=ryan',\n query: 'name=ryan',\n pathname: '/status' }</code></pre>\n<p>If you would like to extract the params from the query string,\nyou can use the <code>require('querystring').parse</code> function, or pass\n<code>true</code> as the second argument to <code>require('url').parse</code>. Example:\n\n</p>\n<pre><code>node> require('url').parse('/status?name=ryan', true)\n{ href: '/status?name=ryan',\n search: '?name=ryan',\n query: { name: 'ryan' },\n pathname: '/status' }</code></pre>\n"
},
{
"textRaw": "message.statusCode",
"name": "statusCode",
"desc": "<p><strong>Only valid for response obtained from <code>http.ClientRequest</code>.</strong>\n\n</p>\n<p>The 3-digit HTTP response status code. E.G. <code>404</code>.\n\n</p>\n"
},
{
"textRaw": "message.socket",
"name": "socket",
"desc": "<p>The <code>net.Socket</code> object associated with the connection.\n\n</p>\n<p>With HTTPS support, use request.connection.verifyPeer() and\nrequest.connection.getPeerCertificate() to obtain the client's\nauthentication details.\n\n\n</p>\n"
}
],
"methods": [
{
"textRaw": "message.setTimeout(msecs, callback)",
"type": "method",
"name": "setTimeout",
"signatures": [
{
"params": [
{
"textRaw": "`msecs` {Number} ",
"name": "msecs",
"type": "Number"
},
{
"textRaw": "`callback` {Function} ",
"name": "callback",
"type": "Function"
}
]
},
{
"params": [
{
"name": "msecs"
},
{
"name": "callback"
}
]
}
],
"desc": "<p>Calls <code>message.connection.setTimeout(msecs, callback)</code>.\n\n</p>\n"
}
]
}
],
"methods": [
{
"textRaw": "http.createServer([requestListener])",
"type": "method",
"name": "createServer",
"desc": "<p>Returns a new web server object.\n\n</p>\n<p>The <code>requestListener</code> is a function which is automatically\nadded to the <code>'request'</code> event.\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "requestListener",
"optional": true
}
]
}
]
},
{
"textRaw": "http.createClient([port], [host])",
"type": "method",
"name": "createClient",
"desc": "<p>This function is <strong>deprecated</strong>; please use [http.request()][] instead.\nConstructs a new HTTP client. <code>port</code> and <code>host</code> refer to the server to be\nconnected to.\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "port",
"optional": true
},
{
"name": "host",
"optional": true
}
]
}
]
},
{
"textRaw": "http.request(options, callback)",
"type": "method",
"name": "request",
"desc": "<p>Node maintains several connections per server to make HTTP requests.\nThis function allows one to transparently issue requests.\n\n</p>\n<p><code>options</code> can be an object or a string. If <code>options</code> is a string, it is\nautomatically parsed with [url.parse()][].\n\n</p>\n<p>Options:\n\n</p>\n<ul>\n<li><code>host</code>: A domain name or IP address of the server to issue the request to.\nDefaults to <code>'localhost'</code>.</li>\n<li><code>hostname</code>: To support <code>url.parse()</code> <code>hostname</code> is preferred over <code>host</code></li>\n<li><code>port</code>: Port of remote server. Defaults to 80.</li>\n<li><code>localAddress</code>: Local interface to bind for network connections.</li>\n<li><code>socketPath</code>: Unix Domain Socket (use one of host:port or socketPath)</li>\n<li><code>method</code>: A string specifying the HTTP request method. Defaults to <code>'GET'</code>.</li>\n<li><code>path</code>: Request path. Defaults to <code>'/'</code>. Should include query string if any.\nE.G. <code>'/index.html?page=12'</code></li>\n<li><code>headers</code>: An object containing request headers.</li>\n<li><code>auth</code>: Basic authentication i.e. <code>'user:password'</code> to compute an\nAuthorization header.</li>\n<li><code>agent</code>: Controls [Agent][] behavior. When an Agent is used request will\ndefault to <code>Connection: keep-alive</code>. Possible values:<ul>\n<li><code>undefined</code> (default): use [global Agent][] for this host and port.</li>\n<li><code>Agent</code> object: explicitly use the passed in <code>Agent</code>.</li>\n<li><code>false</code>: opts out of connection pooling with an Agent, defaults request to\n<code>Connection: close</code>.</li>\n</ul>\n</li>\n</ul>\n<p><code>http.request()</code> returns an instance of the <code>http.ClientRequest</code>\nclass. The <code>ClientRequest</code> instance is a writable stream. If one needs to\nupload a file with a POST request, then write to the <code>ClientRequest</code> object.\n\n</p>\n<p>Example:\n\n</p>\n<pre><code>var options = {\n hostname: 'www.google.com',\n port: 80,\n path: '/upload',\n method: 'POST'\n};\n\nvar req = http.request(options, function(res) {\n console.log('STATUS: ' + res.statusCode);\n console.log('HEADERS: ' + JSON.stringify(res.headers));\n res.setEncoding('utf8');\n res.on('data', function (chunk) {\n console.log('BODY: ' + chunk);\n });\n});\n\nreq.on('error', function(e) {\n console.log('problem with request: ' + e.message);\n});\n\n// write data to request body\nreq.write('data\\n');\nreq.write('data\\n');\nreq.end();</code></pre>\n<p>Note that in the example <code>req.end()</code> was called. With <code>http.request()</code> one\nmust always call <code>req.end()</code> to signify that you're done with the request -\neven if there is no data being written to the request body.\n\n</p>\n<p>If any error is encountered during the request (be that with DNS resolution,\nTCP level errors, or actual HTTP parse errors) an <code>'error'</code> event is emitted\non the returned request object.\n\n</p>\n<p>There are a few special headers that should be noted.\n\n</p>\n<ul>\n<li><p>Sending a 'Connection: keep-alive' will notify Node that the connection to\nthe server should be persisted until the next request.</p>\n</li>\n<li><p>Sending a 'Content-length' header will disable the default chunked encoding.</p>\n</li>\n<li><p>Sending an 'Expect' header will immediately send the request headers.\nUsually, when sending 'Expect: 100-continue', you should both set a timeout\nand listen for the <code>continue</code> event. See RFC2616 Section 8.2.3 for more\ninformation.</p>\n</li>\n<li><p>Sending an Authorization header will override using the <code>auth</code> option\nto compute basic authentication.</p>\n</li>\n</ul>\n",
"signatures": [
{
"params": [
{
"name": "options"
},
{
"name": "callback"
}
]
}
]
},
{
"textRaw": "http.get(options, callback)",
"type": "method",
"name": "get",
"desc": "<p>Since most requests are GET requests without bodies, Node provides this\nconvenience method. The only difference between this method and <code>http.request()</code>\nis that it sets the method to GET and calls <code>req.end()</code> automatically.\n\n</p>\n<p>Example:\n\n</p>\n<pre><code>http.get("http://www.google.com/index.html", function(res) {\n console.log("Got response: " + res.statusCode);\n}).on('error', function(e) {\n console.log("Got error: " + e.message);\n});</code></pre>\n",
"signatures": [
{
"params": [
{
"name": "options"
},
{
"name": "callback"
}
]
}
]
}
],
"classes": [
{
"textRaw": "Class: http.Server",
"type": "class",
"name": "http.Server",
"desc": "<p>This is an [EventEmitter][] with the following events:\n\n</p>\n",
"events": [
{
"textRaw": "Event: 'request'",
"type": "event",
"name": "request",
"desc": "<p><code>function (request, response) { }</code>\n\n</p>\n<p>Emitted each time there is a request. Note that there may be multiple requests\nper connection (in the case of keep-alive connections).\n <code>request</code> is an instance of <code>http.IncomingMessage</code> and <code>response</code> is\n an instance of <code>http.ServerResponse</code>\n\n</p>\n",
"params": []
},
{
"textRaw": "Event: 'connection'",
"type": "event",
"name": "connection",
"desc": "<p><code>function (socket) { }</code>\n\n</p>\n<p> When a new TCP stream is established. <code>socket</code> is an object of type\n <code>net.Socket</code>. Usually users will not want to access this event. The\n <code>socket</code> can also be accessed at <code>request.connection</code>.\n\n</p>\n",
"params": []
},
{
"textRaw": "Event: 'close'",
"type": "event",
"name": "close",
"desc": "<p><code>function () { }</code>\n\n</p>\n<p> Emitted when the server closes.\n\n</p>\n",
"params": []
},
{
"textRaw": "Event: 'checkContinue'",
"type": "event",
"name": "checkContinue",
"desc": "<p><code>function (request, response) { }</code>\n\n</p>\n<p>Emitted each time a request with an http Expect: 100-continue is received.\nIf this event isn't listened for, the server will automatically respond\nwith a 100 Continue as appropriate.\n\n</p>\n<p>Handling this event involves calling <code>response.writeContinue</code> if the client\nshould continue to send the request body, or generating an appropriate HTTP\nresponse (e.g., 400 Bad Request) if the client should not continue to send the\nrequest body.\n\n</p>\n<p>Note that when this event is emitted and handled, the <code>request</code> event will\nnot be emitted.\n\n</p>\n",
"params": []
},
{
"textRaw": "Event: 'connect'",
"type": "event",
"name": "connect",
"desc": "<p><code>function (request, socket, head) { }</code>\n\n</p>\n<p>Emitted each time a client requests a http CONNECT method. If this event isn't\nlistened for, then clients requesting a CONNECT method will have their\nconnections closed.\n\n</p>\n<ul>\n<li><code>request</code> is the arguments for the http request, as it is in the request\nevent.</li>\n<li><code>socket</code> is the network socket between the server and client.</li>\n<li><code>head</code> is an instance of Buffer, the first packet of the tunneling stream,\nthis may be empty.</li>\n</ul>\n<p>After this event is emitted, the request's socket will not have a <code>data</code>\nevent listener, meaning you will need to bind to it in order to handle data\nsent to the server on that socket.\n\n</p>\n",
"params": []
},
{
"textRaw": "Event: 'upgrade'",
"type": "event",
"name": "upgrade",
"desc": "<p><code>function (request, socket, head) { }</code>\n\n</p>\n<p>Emitted each time a client requests a http upgrade. If this event isn't\nlistened for, then clients requesting an upgrade will have their connections\nclosed.\n\n</p>\n<ul>\n<li><code>request</code> is the arguments for the http request, as it is in the request\nevent.</li>\n<li><code>socket</code> is the network socket between the server and client.</li>\n<li><code>head</code> is an instance of Buffer, the first packet of the upgraded stream,\nthis may be empty.</li>\n</ul>\n<p>After this event is emitted, the request's socket will not have a <code>data</code>\nevent listener, meaning you will need to bind to it in order to handle data\nsent to the server on that socket.\n\n</p>\n",
"params": []
},
{
"textRaw": "Event: 'clientError'",
"type": "event",
"name": "clientError",
"desc": "<p><code>function (exception, socket) { }</code>\n\n</p>\n<p>If a client connection emits an 'error' event - it will forwarded here.\n\n</p>\n<p><code>socket</code> is the <code>net.Socket</code> object that the error originated from.\n\n\n</p>\n",
"params": []
}
],
"methods": [
{
"textRaw": "server.listen(port, [hostname], [backlog], [callback])",
"type": "method",
"name": "listen",
"desc": "<p>Begin accepting connections on the specified port and hostname. If the\nhostname is omitted, the server will accept connections directed to any\nIPv4 address (<code>INADDR_ANY</code>).\n\n</p>\n<p>To listen to a unix socket, supply a filename instead of port and hostname.\n\n</p>\n<p>Backlog is the maximum length of the queue of pending connections.\nThe actual length will be determined by your OS through sysctl settings such as\n<code>tcp_max_syn_backlog</code> and <code>somaxconn</code> on linux. The default value of this\nparameter is 511 (not 512).\n\n</p>\n<p>This function is asynchronous. The last parameter <code>callback</code> will be added as\na listener for the ['listening'][] event. See also [net.Server.listen(port)][].\n\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "port"
},
{
"name": "hostname",
"optional": true
},
{
"name": "backlog",
"optional": true
},
{
"name": "callback",
"optional": true
}
]
}
]
},
{
"textRaw": "server.listen(path, [callback])",
"type": "method",
"name": "listen",
"desc": "<p>Start a UNIX socket server listening for connections on the given <code>path</code>.\n\n</p>\n<p>This function is asynchronous. The last parameter <code>callback</code> will be added as\na listener for the ['listening'][] event. See also [net.Server.listen(path)][].\n\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "path"
},
{
"name": "callback",
"optional": true
}
]
}
]
},
{
"textRaw": "server.listen(handle, [callback])",
"type": "method",
"name": "listen",
"signatures": [
{
"params": [
{
"textRaw": "`handle` {Object} ",
"name": "handle",
"type": "Object"
},
{
"textRaw": "`callback` {Function} ",
"name": "callback",
"type": "Function",
"optional": true
}
]
},
{
"params": [
{
"name": "handle"
},
{
"name": "callback",
"optional": true
}
]
}
],
"desc": "<p>The <code>handle</code> object can be set to either a server or socket (anything\nwith an underlying <code>_handle</code> member), or a <code>{fd: <n>}</code> object.\n\n</p>\n<p>This will cause the server to accept connections on the specified\nhandle, but it is presumed that the file descriptor or handle has\nalready been bound to a port or domain socket.\n\n</p>\n<p>Listening on a file descriptor is not supported on Windows.\n\n</p>\n<p>This function is asynchronous. The last parameter <code>callback</code> will be added as\na listener for the <a href=\"net.html#event_listening_\">'listening'</a> event.\nSee also <a href=\"net.html#net_server_listen_handle_callback\">net.Server.listen()</a>.\n\n</p>\n"
},
{
"textRaw": "server.close([callback])",
"type": "method",
"name": "close",
"desc": "<p>Stops the server from accepting new connections. See [net.Server.close()][].\n\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "callback",
"optional": true
}
]
}
]
},
{
"textRaw": "server.setTimeout(msecs, callback)",
"type": "method",
"name": "setTimeout",
"signatures": [
{
"params": [
{
"textRaw": "`msecs` {Number} ",
"name": "msecs",
"type": "Number"
},
{
"textRaw": "`callback` {Function} ",
"name": "callback",
"type": "Function"
}
]
},
{
"params": [
{
"name": "msecs"
},
{
"name": "callback"
}
]
}
],
"desc": "<p>Sets the timeout value for sockets, and emits a <code>'timeout'</code> event on\nthe Server object, passing the socket as an argument, if a timeout\noccurs.\n\n</p>\n<p>If there is a <code>'timeout'</code> event listener on the Server object, then it\nwill be called with the timed-out socket as an argument.\n\n</p>\n<p>By default, the Server's timeout value is 2 minutes, and sockets are\ndestroyed automatically if they time out. However, if you assign a\ncallback to the Server's <code>'timeout'</code> event, then you are responsible\nfor handling socket timeouts.\n\n</p>\n"
}
],
"properties": [
{
"textRaw": "server.maxHeadersCount",
"name": "maxHeadersCount",
"desc": "<p>Limits maximum incoming headers count, equal to 1000 by default. If set to 0 -\nno limit will be applied.\n\n</p>\n"
},
{
"textRaw": "`timeout` {Number} Default = 120000 (2 minutes) ",
"name": "timeout",
"desc": "<p>The number of milliseconds of inactivity before a socket is presumed\nto have timed out.\n\n</p>\n<p>Note that the socket timeout logic is set up on connection, so\nchanging this value only affects <em>new</em> connections to the server, not\nany existing connections.\n\n</p>\n<p>Set to 0 to disable any kind of automatic timeout behavior on incoming\nconnections.\n\n</p>\n",
"shortDesc": "Default = 120000 (2 minutes)"
}
]
},
{
"textRaw": "Class: http.ServerResponse",
"type": "class",
"name": "http.ServerResponse",
"desc": "<p>This object is created internally by a HTTP server--not by the user. It is\npassed as the second parameter to the <code>'request'</code> event.\n\n</p>\n<p>The response implements the [Writable Stream][] interface. This is an\n[EventEmitter][] with the following events:\n\n</p>\n",
"events": [
{
"textRaw": "Event: 'close'",
"type": "event",
"name": "close",
"desc": "<p><code>function () { }</code>\n\n</p>\n<p>Indicates that the underlying connection was terminated before\n<code>response.end()</code> was called or able to flush.\n\n</p>\n",
"params": []
}
],
"methods": [
{
"textRaw": "response.writeContinue()",
"type": "method",
"name": "writeContinue",
"desc": "<p>Sends a HTTP/1.1 100 Continue message to the client, indicating that\nthe request body should be sent. See the ['checkContinue'][] event on <code>Server</code>.\n\n</p>\n",
"signatures": [
{
"params": []
}
]
},
{
"textRaw": "response.writeHead(statusCode, [reasonPhrase], [headers])",
"type": "method",
"name": "writeHead",
"desc": "<p>Sends a response header to the request. The status code is a 3-digit HTTP\nstatus code, like <code>404</code>. The last argument, <code>headers</code>, are the response headers.\nOptionally one can give a human-readable <code>reasonPhrase</code> as the second\nargument.\n\n</p>\n<p>Example:\n\n</p>\n<pre><code>var body = 'hello world';\nresponse.writeHead(200, {\n 'Content-Length': body.length,\n 'Content-Type': 'text/plain' });</code></pre>\n<p>This method must only be called once on a message and it must\nbe called before <code>response.end()</code> is called.\n\n</p>\n<p>If you call <code>response.write()</code> or <code>response.end()</code> before calling this, the\nimplicit/mutable headers will be calculated and call this function for you.\n\n</p>\n<p>Note: that Content-Length is given in bytes not characters. The above example\nworks because the string <code>'hello world'</code> contains only single byte characters.\nIf the body contains higher coded characters then <code>Buffer.byteLength()</code>\nshould be used to determine the number of bytes in a given encoding.\nAnd Node does not check whether Content-Length and the length of the body\nwhich has been transmitted are equal or not.\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "statusCode"
},
{
"name": "reasonPhrase",
"optional": true
},
{
"name": "headers",
"optional": true
}
]
}
]
},
{
"textRaw": "response.setTimeout(msecs, callback)",
"type": "method",
"name": "setTimeout",
"signatures": [
{
"params": [
{
"textRaw": "`msecs` {Number} ",
"name": "msecs",
"type": "Number"
},
{
"textRaw": "`callback` {Function} ",
"name": "callback",
"type": "Function"
}
]
},
{
"params": [
{
"name": "msecs"
},
{
"name": "callback"
}
]
}
],
"desc": "<p>Sets the Socket's timeout value to <code>msecs</code>. If a callback is\nprovided, then it is added as a listener on the <code>'timeout'</code> event on\nthe response object.\n\n</p>\n<p>If no <code>'timeout'</code> listener is added to the request, the response, or\nthe server, then sockets are destroyed when they time out. If you\nassign a handler on the request, the response, or the server's\n<code>'timeout'</code> events, then it is your responsibility to handle timed out\nsockets.\n\n</p>\n"
},
{
"textRaw": "response.setHeader(name, value)",
"type": "method",
"name": "setHeader",
"desc": "<p>Sets a single header value for implicit headers. If this header already exists\nin the to-be-sent headers, its value will be replaced. Use an array of strings\nhere if you need to send multiple headers with the same name.\n\n</p>\n<p>Example:\n\n</p>\n<pre><code>response.setHeader("Content-Type", "text/html");</code></pre>\n<p>or\n\n</p>\n<pre><code>response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]);</code></pre>\n",
"signatures": [
{
"params": [
{
"name": "name"
},
{
"name": "value"
}
]
}
]
},
{
"textRaw": "response.getHeader(name)",
"type": "method",
"name": "getHeader",
"desc": "<p>Reads out a header that's already been queued but not sent to the client. Note\nthat the name is case insensitive. This can only be called before headers get\nimplicitly flushed.\n\n</p>\n<p>Example:\n\n</p>\n<pre><code>var contentType = response.getHeader('content-type');</code></pre>\n",
"signatures": [
{
"params": [
{
"name": "name"
}
]
}
]
},
{
"textRaw": "response.removeHeader(name)",
"type": "method",
"name": "removeHeader",
"desc": "<p>Removes a header that's queued for implicit sending.\n\n</p>\n<p>Example:\n\n</p>\n<pre><code>response.removeHeader("Content-Encoding");</code></pre>\n",
"signatures": [
{
"params": [
{
"name": "name"
}
]
}
]
},
{
"textRaw": "response.write(chunk, [encoding])",
"type": "method",
"name": "write",
"desc": "<p>If this method is called and <code>response.writeHead()</code> has not been called, it will\nswitch to implicit header mode and flush the implicit headers.\n\n</p>\n<p>This sends a chunk of the response body. This method may\nbe called multiple times to provide successive parts of the body.\n\n</p>\n<p><code>chunk</code> can be a string or a buffer. If <code>chunk</code> is a string,\nthe second parameter specifies how to encode it into a byte stream.\nBy default the <code>encoding</code> is <code>'utf8'</code>.\n\n</p>\n<p><strong>Note</strong>: This is the raw HTTP body and has nothing to do with\nhigher-level multi-part body encodings that may be used.\n\n</p>\n<p>The first time <code>response.write()</code> is called, it will send the buffered\nheader information and the first body to the client. The second time\n<code>response.write()</code> is called, Node assumes you're going to be streaming\ndata, and sends that separately. That is, the response is buffered up to the\nfirst chunk of body.\n\n</p>\n<p>Returns <code>true</code> if the entire data was flushed successfully to the kernel\nbuffer. Returns <code>false</code> if all or part of the data was queued in user memory.\n<code>'drain'</code> will be emitted when the buffer is again free.\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "chunk"
},
{
"name": "encoding",
"optional": true
}
]
}
]
},
{
"textRaw": "response.addTrailers(headers)",
"type": "method",
"name": "addTrailers",
"desc": "<p>This method adds HTTP trailing headers (a header but at the end of the\nmessage) to the response.\n\n</p>\n<p>Trailers will <strong>only</strong> be emitted if chunked encoding is used for the\nresponse; if it is not (e.g., if the request was HTTP/1.0), they will\nbe silently discarded.\n\n</p>\n<p>Note that HTTP requires the <code>Trailer</code> header to be sent if you intend to\nemit trailers, with a list of the header fields in its value. E.g.,\n\n</p>\n<pre><code>response.writeHead(200, { 'Content-Type': 'text/plain',\n 'Trailer': 'Content-MD5' });\nresponse.write(fileData);\nresponse.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});\nresponse.end();</code></pre>\n",
"signatures": [
{
"params": [
{
"name": "headers"
}
]
}
]
},
{
"textRaw": "response.end([data], [encoding])",
"type": "method",
"name": "end",
"desc": "<p>This method signals to the server that all of the response headers and body\nhave been sent; that server should consider this message complete.\nThe method, <code>response.end()</code>, MUST be called on each\nresponse.\n\n</p>\n<p>If <code>data</code> is specified, it is equivalent to calling <code>response.write(data, encoding)</code>\nfollowed by <code>response.end()</code>.\n\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "data",
"optional": true
},
{
"name": "encoding",
"optional": true
}
]
}
]
}
],
"properties": [
{
"textRaw": "response.statusCode",
"name": "statusCode",
"desc": "<p>When using implicit headers (not calling <code>response.writeHead()</code> explicitly), this property\ncontrols the status code that will be sent to the client when the headers get\nflushed.\n\n</p>\n<p>Example:\n\n</p>\n<pre><code>response.statusCode = 404;</code></pre>\n<p>After response header was sent to the client, this property indicates the\nstatus code which was sent out.\n\n</p>\n"
},
{
"textRaw": "response.headersSent",
"name": "headersSent",
"desc": "<p>Boolean (read-only). True if headers were sent, false otherwise.\n\n</p>\n"
},
{
"textRaw": "response.sendDate",
"name": "sendDate",
"desc": "<p>When true, the Date header will be automatically generated and sent in \nthe response if it is not already present in the headers. Defaults to true.\n\n</p>\n<p>This should only be disabled for testing; HTTP requires the Date header\nin responses.\n\n</p>\n"
}
]
},
{
"textRaw": "Class: http.Agent",
"type": "class",
"name": "http.Agent",
"desc": "<p>In node 0.5.3+ there is a new implementation of the HTTP Agent which is used\nfor pooling sockets used in HTTP client requests.\n\n</p>\n<p>Previously, a single agent instance helped pool for a single host+port. The\ncurrent implementation now holds sockets for any number of hosts.\n\n</p>\n<p>The current HTTP Agent also defaults client requests to using\nConnection:keep-alive. If no pending HTTP requests are waiting on a socket\nto become free the socket is closed. This means that node's pool has the\nbenefit of keep-alive when under load but still does not require developers\nto manually close the HTTP clients using keep-alive.\n\n</p>\n<p>Sockets are removed from the agent's pool when the socket emits either a\n"close" event or a special "agentRemove" event. This means that if you intend\nto keep one HTTP request open for a long time and don't want it to stay in the\npool you can do something along the lines of:\n\n</p>\n<pre><code>http.get(options, function(res) {\n // Do stuff\n}).on("socket", function (socket) {\n socket.emit("agentRemove");\n});</code></pre>\n<p>Alternatively, you could just opt out of pooling entirely using <code>agent:false</code>:\n\n</p>\n<pre><code>http.get({hostname:'localhost', port:80, path:'/', agent:false}, function (res) {\n // Do stuff\n})</code></pre>\n",
"properties": [
{
"textRaw": "agent.maxSockets",
"name": "maxSockets",
"desc": "<p>By default set to 5. Determines how many concurrent sockets the agent can have \nopen per host.\n\n</p>\n"
},
{
"textRaw": "agent.sockets",
"name": "sockets",
"desc": "<p>An object which contains arrays of sockets currently in use by the Agent. Do not \nmodify.\n\n</p>\n"
},
{
"textRaw": "agent.requests",
"name": "requests",
"desc": "<p>An object which contains queues of requests that have not yet been assigned to \nsockets. Do not modify.\n\n</p>\n"
}
]
},
{
"textRaw": "Class: http.ClientRequest",
"type": "class",
"name": "http.ClientRequest",
"desc": "<p>This object is created internally and returned from <code>http.request()</code>. It\nrepresents an <em>in-progress</em> request whose header has already been queued. The\nheader is still mutable using the <code>setHeader(name, value)</code>, <code>getHeader(name)</code>,\n<code>removeHeader(name)</code> API. The actual header will be sent along with the first\ndata chunk or when closing the connection.\n\n</p>\n<p>To get the response, add a listener for <code>'response'</code> to the request object.\n<code>'response'</code> will be emitted from the request object when the response\nheaders have been received. The <code>'response'</code> event is executed with one\nargument which is an instance of <code>http.IncomingMessage</code>.\n\n</p>\n<p>During the <code>'response'</code> event, one can add listeners to the\nresponse object; particularly to listen for the <code>'data'</code> event.\n\n</p>\n<p>If no <code>'response'</code> handler is added, then the response will be\nentirely discarded. However, if you add a <code>'response'</code> event handler,\nthen you <strong>must</strong> consume the data from the response object, either by\ncalling <code>response.read()</code> whenever there is a <code>'readable'</code> event, or\nby adding a <code>'data'</code> handler, or by calling the <code>.resume()</code> method.\nUntil the data is consumed, the <code>'end'</code> event will not fire.\n\n</p>\n<p>Note: Node does not check whether Content-Length and the length of the body\nwhich has been transmitted are equal or not.\n\n</p>\n<p>The request implements the [Writable Stream][] interface. This is an\n[EventEmitter][] with the following events:\n\n</p>\n",
"events": [
{
"textRaw": "Event 'response'",
"type": "event",
"name": "response",
"desc": "<p><code>function (response) { }</code>\n\n</p>\n<p>Emitted when a response is received to this request. This event is emitted only\nonce. The <code>response</code> argument will be an instance of <code>http.IncomingMessage</code>.\n\n</p>\n<p>Options:\n\n</p>\n<ul>\n<li><code>host</code>: A domain name or IP address of the server to issue the request to.</li>\n<li><code>port</code>: Port of remote server.</li>\n<li><code>socketPath</code>: Unix Domain Socket (use one of host:port or socketPath)</li>\n</ul>\n",
"params": []
},
{
"textRaw": "Event: 'socket'",
"type": "event",
"name": "socket",
"desc": "<p><code>function (socket) { }</code>\n\n</p>\n<p>Emitted after a socket is assigned to this request.\n\n</p>\n",
"params": []
},
{
"textRaw": "Event: 'connect'",
"type": "event",
"name": "connect",
"desc": "<p><code>function (response, socket, head) { }</code>\n\n</p>\n<p>Emitted each time a server responds to a request with a CONNECT method. If this\nevent isn't being listened for, clients receiving a CONNECT method will have\ntheir connections closed.\n\n</p>\n<p>A client server pair that show you how to listen for the <code>connect</code> event.\n\n</p>\n<pre><code>var http = require('http');\nvar net = require('net');\nvar url = require('url');\n\n// Create an HTTP tunneling proxy\nvar proxy = http.createServer(function (req, res) {\n res.writeHead(200, {'Content-Type': 'text/plain'});\n res.end('okay');\n});\nproxy.on('connect', function(req, cltSocket, head) {\n // connect to an origin server\n var srvUrl = url.parse('http://' + req.url);\n var srvSocket = net.connect(srvUrl.port, srvUrl.hostname, function() {\n cltSocket.write('HTTP/1.1 200 Connection Established\\r\\n' +\n 'Proxy-agent: Node-Proxy\\r\\n' +\n '\\r\\n');\n srvSocket.write(head);\n srvSocket.pipe(cltSocket);\n cltSocket.pipe(srvSocket);\n });\n});\n\n// now that proxy is running\nproxy.listen(1337, '127.0.0.1', function() {\n\n // make a request to a tunneling proxy\n var options = {\n port: 1337,\n hostname: '127.0.0.1',\n method: 'CONNECT',\n path: 'www.google.com:80'\n };\n\n var req = http.request(options);\n req.end();\n\n req.on('connect', function(res, socket, head) {\n console.log('got connected!');\n\n // make a request over an HTTP tunnel\n socket.write('GET / HTTP/1.1\\r\\n' +\n 'Host: www.google.com:80\\r\\n' +\n 'Connection: close\\r\\n' +\n '\\r\\n');\n socket.on('data', function(chunk) {\n console.log(chunk.toString());\n });\n socket.on('end', function() {\n proxy.close();\n });\n });\n});</code></pre>\n",
"params": []
},
{
"textRaw": "Event: 'upgrade'",
"type": "event",
"name": "upgrade",
"desc": "<p><code>function (response, socket, head) { }</code>\n\n</p>\n<p>Emitted each time a server responds to a request with an upgrade. If this\nevent isn't being listened for, clients receiving an upgrade header will have\ntheir connections closed.\n\n</p>\n<p>A client server pair that show you how to listen for the <code>upgrade</code> event.\n\n</p>\n<pre><code>var http = require('http');\n\n// Create an HTTP server\nvar srv = http.createServer(function (req, res) {\n res.writeHead(200, {'Content-Type': 'text/plain'});\n res.end('okay');\n});\nsrv.on('upgrade', function(req, socket, head) {\n socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\\r\\n' +\n 'Upgrade: WebSocket\\r\\n' +\n 'Connection: Upgrade\\r\\n' +\n '\\r\\n');\n\n socket.pipe(socket); // echo back\n});\n\n// now that server is running\nsrv.listen(1337, '127.0.0.1', function() {\n\n // make a request\n var options = {\n port: 1337,\n hostname: '127.0.0.1',\n headers: {\n 'Connection': 'Upgrade',\n 'Upgrade': 'websocket'\n }\n };\n\n var req = http.request(options);\n req.end();\n\n req.on('upgrade', function(res, socket, upgradeHead) {\n console.log('got upgraded!');\n socket.end();\n process.exit(0);\n });\n});</code></pre>\n",
"params": []
},
{
"textRaw": "Event: 'continue'",
"type": "event",
"name": "continue",
"desc": "<p><code>function () { }</code>\n\n</p>\n<p>Emitted when the server sends a '100 Continue' HTTP response, usually because\nthe request contained 'Expect: 100-continue'. This is an instruction that\nthe client should send the request body.\n\n</p>\n",
"params": []
}
],
"methods": [
{
"textRaw": "request.write(chunk, [encoding])",
"type": "method",
"name": "write",
"desc": "<p>Sends a chunk of the body. By calling this method\nmany times, the user can stream a request body to a\nserver--in that case it is suggested to use the\n<code>['Transfer-Encoding', 'chunked']</code> header line when\ncreating the request.\n\n</p>\n<p>The <code>chunk</code> argument should be a [Buffer][] or a string.\n\n</p>\n<p>The <code>encoding</code> argument is optional and only applies when <code>chunk</code> is a string.\nDefaults to <code>'utf8'</code>.\n\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "chunk"
},
{
"name": "encoding",
"optional": true
}
]
}
]
},
{
"textRaw": "request.end([data], [encoding])",
"type": "method",
"name": "end",
"desc": "<p>Finishes sending the request. If any parts of the body are\nunsent, it will flush them to the stream. If the request is\nchunked, this will send the terminating <code>'0\\r\\n\\r\\n'</code>.\n\n</p>\n<p>If <code>data</code> is specified, it is equivalent to calling\n<code>request.write(data, encoding)</code> followed by <code>request.end()</code>.\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "data",
"optional": true
},
{
"name": "encoding",
"optional": true
}
]
}
]
},
{
"textRaw": "request.abort()",
"type": "method",
"name": "abort",
"desc": "<p>Aborts a request. (New since v0.3.8.)\n\n</p>\n",
"signatures": [
{
"params": []
}
]
},
{
"textRaw": "request.setTimeout(timeout, [callback])",
"type": "method",
"name": "setTimeout",
"desc": "<p>Once a socket is assigned to this request and is connected\n[socket.setTimeout()][] will be called.\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "timeout"
},
{
"name": "callback",
"optional": true
}
]
}
]
},
{
"textRaw": "request.setNoDelay([noDelay])",
"type": "method",
"name": "setNoDelay",
"desc": "<p>Once a socket is assigned to this request and is connected\n[socket.setNoDelay()][] will be called.\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "noDelay",
"optional": true
}
]
}
]
},
{
"textRaw": "request.setSocketKeepAlive([enable], [initialDelay])",
"type": "method",
"name": "setSocketKeepAlive",
"desc": "<p>Once a socket is assigned to this request and is connected\n[socket.setKeepAlive()][] will be called.\n\n\n</p>\n",
"signatures": [
{
"params": [
{
"name": "enable",
"optional": true
},
{
"name": "initialDelay",
"optional": true
}
]
}
]
}
]
}
],
"type": "module",
"displayName": "HTTP"
}
]
}
Mini Shell