TODO.patch

-### fs.watchFile(filename, [options], listener)
+## fs.watchFile(filename, [options], listener)
 
 Watch for changes on `filename`. The callback `listener` will be called each
 time the file is accessed.
 
 The second argument is optional. The `options` if provided should be an object
-containing two members a boolean, `persistent`, and `interval`, a polling
-value in milliseconds. The default is `{ persistent: true, interval: 0 }`.
+containing two members a boolean, `persistent`, and `interval`. `persistent`
+indicates whether the process should continue to run as long as files are
+being watched. `interval` indicates how often the target should be polled,
+in milliseconds. (On Linux systems with inotify, `interval` is ignored.) The
+default is `{ persistent: true, interval: 0 }`.
 
 The `listener` gets two arguments the current stat object and the previous
 stat object:
@@ -399,13 +413,44 @@ If you want to be notified when the file
 
-## fs.Stats
+## fs.watch(filename, [options], listener)
+
+Watch for changes on `filename`, where `filename` is either a file or a
+directory.  The returned object is [fs.FSWatcher](#fs.FSWatcher).
+
+The second argument is optional. The `options` if provided should be an object
+containing a boolean member `persistent`, which indicates whether the process
+should continue to run as long as files are being watched. The default is
+`{ persistent: true }`.
+
+The listener callback gets two arguments `(event, filename)`.  `event` is either
+'rename' or 'change', and `filename` is the name of the file which triggered
+the event.
+
+***Warning:***
+Providing `filename` argument in the callback is not supported
+on every platform (currently it's only supported on Linux and Windows).  Even
+on supported platforms `filename` is not always guaranteed to be provided.
+Therefore, don't assume that `filename` argument is always provided in the
+callback, and have some fallback logic if it is null.
+
+    fs.watch('somedir', function (event, filename) {
+      console.log('event is: ' + event);
+	  if (filename) {
+        console.log('filename provided: ' + filename);
+	  } else {
+	    console.log('filename not provided');
+	  }
+    });
+
+## Class: fs.Stats
 
-Objects returned from `fs.stat()` and `fs.lstat()` are of this type.
+Objects returned from `fs.stat()`, `fs.lstat()` and `fs.fstat()` and their
+synchronous counterparts are of this type.
 
  - `stats.isFile()`
  - `stats.isDirectory()`
@@ -415,18 +460,38 @@ Objects returned from `fs.stat()` and `f
  - `stats.isFIFO()`
  - `stats.isSocket()`
 
+For a regular file `util.inspect(stats)` would return a string very
+similar to this:
 
-## fs.ReadStream
-
-`ReadStream` is a `Readable Stream`.
-
-### Event: 'open'
+    { dev: 2114,
+      ino: 48064969,
+      mode: 33188,
+      nlink: 1,
+      uid: 85,
+      gid: 100,
+      rdev: 0,
+      size: 527,
+      blksize: 4096,
+      blocks: 8,
+      atime: Mon, 10 Oct 2011 23:24:11 GMT,
+      mtime: Mon, 10 Oct 2011 23:24:11 GMT,
+      ctime: Mon, 10 Oct 2011 23:24:11 GMT }
+
+Please note that `atime`, `mtime` and `ctime` are instances
+of [Date][MDN-Date] object and to compare the values of
+these objects you should use appropriate methods. For most
+general uses [getTime()][MDN-Date-getTime] will return
+the number of milliseconds elapsed since _1 January 1970
+00:00:00 UTC_ and this integer should be sufficient for
+any comparison, however there additional methods which can
+be used for displaying fuzzy information. More details can
+be found in the [MDN JavaScript Reference][MDN-Date] page.
 
-`function (fd) { }`
+[MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date
+[MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime
 
- `fd` is the file descriptor used by the ReadStream.
 
-### fs.createReadStream(path, [options])
+## fs.createReadStream(path, [options])
 
 Returns a new ReadStream object (See `Readable Stream`).
 
@@ -448,17 +513,18 @@ An example to read the last 10 bytes of
     fs.createReadStream('sample.txt', {start: 90, end: 99});
 
 
-## fs.WriteStream
+## Class: fs.ReadStream
 
-`WriteStream` is a `Writable Stream`.
+`ReadStream` is a [Readable Stream](stream.html#readable_stream).
 
 ### Event: 'open'
 
 `function (fd) { }`
 
- `fd` is the file descriptor used by the WriteStream.
+ `fd` is the file descriptor used by the ReadStream.
+
 
-### fs.createWriteStream(path, [options])
+## fs.createWriteStream(path, [options])
 
 Returns a new WriteStream object (See `Writable Stream`).
 
@@ -467,3 +533,45 @@ Returns a new WriteStream object (See `W
     { flags: 'w',
       encoding: null,
       mode: 0666 }
+
+`options` may also include a `start` option to allow writing data at
+some position past the beginning of the file.  Modifying a file rather
+than replacing it may require a `flags` mode of `r+` rather than the
+default mode `w`.
+
+## fs.WriteStream
+
+`WriteStream` is a [Writable Stream](stream.html#writable_stream).
+
+### Event: 'open'
+
+`function (fd) { }`
+
+ `fd` is the file descriptor used by the WriteStream.
+
+### file.bytesWritten
+
+The number of bytes written so far. Does not include data that is still queued
+for writing.
+
+## Class: fs.FSWatcher
+
+Objects returned from `fs.watch()` are of this type.
+
+### watcher.close()
+
+Stop watching for changes on the given `fs.FSWatcher`.
+
+### Event: 'change'
+
+* `event` {String} The type of fs change
+* `filename` {String} The filename that changed (if relevant/available)
+
+Emitted when something changes in a watched directory or file.
+See more details in [fs.watch](#fs.watch).
+
+### Event: 'error'
+
+`function (exception) {}`
+
+Emitted when an error occurs.


diff -upr ./api_v0.4.12/http.markdown ./api_v0.6.12/http.markdown
--- ./api_v0.4.12/http.markdown	2011-09-21 00:45:54.000000000 +0400
+++ ./api_v0.6.12/http.markdown	2012-03-08 01:22:12.000000000 +0400
@@ -1,4 +1,4 @@
-## HTTP
+# HTTP
 
 To use the HTTP server and client one must `require('http')`.
 
@@ -23,7 +23,14 @@ parsing only. It parses a message into h
 parse the actual headers or the body.
 
 
-## http.Server
+## http.createServer([requestListener])
+
+Returns a new web server object.
+
+The `requestListener` is a function which is automatically
+added to the `'request'` event.
+
+## Class: http.Server
 
 This is an `EventEmitter` with the following events:
 
@@ -31,7 +38,7 @@ This is an `EventEmitter` with the follo
 
 `function (request, response) { }`
 
-Emitted each time there is request. Note that there may be multiple requests
+Emitted each time there is a request. Note that there may be multiple requests
 per connection (in the case of keep-alive connections).
  `request` is an instance of `http.ServerRequest` and `response` is
  an instance of `http.ServerResponse`
@@ -46,7 +53,7 @@ per connection (in the case of keep-aliv
 
 ### Event: 'close'
 
-`function (errno) { }`
+`function () { }`
 
  Emitted when the server closes.
 
@@ -88,13 +95,6 @@ sent to the server on that socket.
 
 If a client connection emits an 'error' event - it will forwarded here.
 
-### http.createServer([requestListener])
-
-Returns a new web server object.
-
-The `requestListener` is a function which is automatically
-added to the `'request'` event.
-
 ### server.listen(port, [hostname], [callback])
 
 Begin accepting connections on the specified port and hostname.  If the
@@ -103,40 +103,44 @@ IPv4 address (`INADDR_ANY`).
 
 To listen to a unix socket, supply a filename instead of port and hostname.
 
-This function is asynchronous. The last parameter `callback` will be called
-when the server has been bound to the port.
+This function is asynchronous. The last parameter `callback` will be added as
+a listener for the ['listening'](net.html#event_listening_) event.
+See also [net.Server.listen()](net.html#server.listen).
 
 
 ### server.listen(path, [callback])
 
 Start a UNIX socket server listening for connections on the given `path`.
 
-This function is asynchronous. The last parameter `callback` will be called
-when the server has been bound.
+This function is asynchronous. The last parameter `callback` will be added as
+a listener for the ['listening'](net.html#event_listening_) event.
+See also [net.Server.listen()](net.html#server.listen).
 
 
 ### server.close()
 
 Stops the server from accepting new connections.
+See [net.Server.close()](net.html#server.close).
 
 
-## http.ServerRequest
+## Class: http.ServerRequest
 
 This object is created internally by a HTTP server -- not by
 the user -- and passed as the first argument to a `'request'` listener.
 
-This is an `EventEmitter` with the following events:
+The request implements the [Readable Stream](stream.html#readable_stream)
+interface. This is an `EventEmitter` with the following events:
 
 ### Event: 'data'
 
 `function (chunk) { }`
 
-Emitted when a piece of the message body is received.
+Emitted when a piece of the message body is received. The chunk is a string if
+an encoding has been set with `request.setEncoding()`, otherwise it's a
+[Buffer](buffer.html).
 
-Example: A chunk of the body is given as the single
-argument. The transfer-encoding has been decoded.  The
-body chunk is a string.  The body encoding is set with
-`request.setEncoding()`.
+Note that the __data will be lost__ if there is no listener when a
+`ServerRequest` emits a `'data'` event.
 
 ### Event: 'end'
 
@@ -147,20 +151,11 @@ will be emitted on the request.
 
 ### Event: 'close'
 
-`function (err) { }`
+`function () { }`
 
 Indicates that the underlaying connection was terminated before
 `response.end()` was called or able to flush.
 
-The `err` parameter is always present and indicates the reason for the timeout:
-
-`err.code === 'timeout'` indicates that the underlaying connection timed out.
-This may happen because all incoming connections have a default timeout of 2
-minutes.
-
-`err.code === 'aborted'` means that the client has closed the underlaying
-connection prematurely.
-
 Just like `'end'`, this event occurs only once per request, and no more `'data'`
 events will fire afterwards.
 
@@ -222,7 +217,7 @@ Also `request.httpVersionMajor` is the f
 `request.httpVersionMinor` is the second.
 
 
-### request.setEncoding(encoding=null)
+### request.setEncoding([encoding])
 
 Set the encoding for the request body. Either `'utf8'` or `'binary'`. Defaults
 to `null`, which means that the `'data'` event will emit a `Buffer` object..
@@ -248,10 +243,20 @@ authentication details.
 
 
 
-## http.ServerResponse
+## Class: http.ServerResponse
 
 This object is created internally by a HTTP server--not by the user. It is
-passed as the second parameter to the `'request'` event. It is a `Writable Stream`.
+passed as the second parameter to the `'request'` event.
+
+The response implements the [Writable  Stream](stream.html#writable_stream)
+interface. This is an `EventEmitter` with the following events:
+
+### Event: 'close'
+
+`function () { }`
+
+Indicates that the underlaying connection was terminated before
+`response.end()` was called or able to flush.
 
 ### response.writeContinue()
 
@@ -302,7 +307,7 @@ status code which was sent out.
 ### response.setHeader(name, value)
 
 Sets a single header value for implicit headers.  If this header already exists
-in the to-be-sent headers, it's value will be replaced.  Use an array of strings
+in the to-be-sent headers, its value will be replaced.  Use an array of strings
 here if you need to send multiple headers with the same name.
 
 Example:
@@ -333,7 +338,7 @@ Example:
     response.removeHeader("Content-Encoding");
 
 
-### response.write(chunk, encoding='utf8')
+### response.write(chunk, [encoding])
 
 If this method is called and `response.writeHead()` has not been called, it will
 switch to implicit header mode and flush the implicit headers.
@@ -367,7 +372,7 @@ Note that HTTP requires the `Trailer` he
 emit trailers, with a list of the header fields in its value. E.g.,
 
     response.writeHead(200, { 'Content-Type': 'text/plain',
-                              'Trailer': 'TraceInfo' });
+                              'Trailer': 'Content-MD5' });
     response.write(fileData);
     response.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});
     response.end();
@@ -387,21 +392,29 @@ followed by `response.end()`.
 ## http.request(options, callback)
 
 Node maintains several connections per server to make HTTP requests.
-This function allows one to transparently issue requests.
+This function allows one to transparently issue requests.  `options` align
+with [url.parse()](url.html#url.parse).
 
 Options:
 
 - `host`: A domain name or IP address of the server to issue the request to.
-- `port`: Port of remote server.
-- `method`: A string specifying the HTTP request method. Possible values:
-  `'GET'` (default), `'POST'`, `'PUT'`, and `'DELETE'`.
-- `path`: Request path. Should include query string and fragments if any.
-   E.G. `'/index.html?page=12'`
+  Defaults to `'localhost'`.
+- `hostname`: To support `url.parse()` `hostname` is preferred over `host`
+- `port`: Port of remote server. Defaults to 80.
+- `socketPath`: Unix Domain Socket (use one of host:port or socketPath)
+- `method`: A string specifying the HTTP request method. Defaults to `'GET'`.
+- `path`: Request path. Defaults to `'/'`. Should include query string if any.
+  E.G. `'/index.html?page=12'`
 - `headers`: An object containing request headers.
-- `agent`: Controls `Agent` behavior. Possible values:
- - `undefined` (default): use default `Agent` for this host and port.
+- `auth`: Basic authentication i.e. `'user:password'` to compute an
+  Authorization header.
+- `agent`: Controls [Agent](#http.Agent) behavior. When an Agent is used
+  request will default to `Connection: keep-alive`. Possible values:
+ - `undefined` (default): use [global Agent](#http.globalAgent) for this host
+   and port.
  - `Agent` object: explicitly use the passed in `Agent`.
- - `false`: explicitly generate a new `Agent` for this host and port. `Agent` will not be re-used.
+ - `false`: opts out of connection pooling with an Agent, defaults request to
+   `Connection: close`.
 
 `http.request()` returns an instance of the `http.ClientRequest`
 class. The `ClientRequest` instance is a writable stream. If one needs to
@@ -454,6 +467,9 @@ There are a few special headers that sho
   and listen for the `continue` event. See RFC2616 Section 8.2.3 for more
   information.
 
+* Sending an Authorization header will override using the `auth` option
+  to compute basic authentication.
+
 ## http.get(options, callback)
 
 Since most requests are GET requests without bodies, Node provides this
@@ -475,85 +491,59 @@ Example:
     });
 
 
-## http.Agent
-## http.getAgent(host, port)
-
-`http.request()` uses a special `Agent` for managing multiple connections to
-an HTTP server. Normally `Agent` instances should not be exposed to user
-code, however in certain situations it's useful to check the status of the
-agent. The `http.getAgent()` function allows you to access the agents.
+## Class: http.Agent
 
-### Event: 'upgrade'
-
-`function (response, socket, head) { }`
-
-Emitted each time a server responds to a request with an upgrade. If this
-event isn't being listened for, clients receiving an upgrade header will have
-their connections closed.
+In node 0.5.3+ there is a new implementation of the HTTP Agent which is used
+for pooling sockets used in HTTP client requests.
 
-A client server pair that show you how to listen for the `upgrade` event using `http.getAgent`:
+Previously, a single agent instance help the pool for single host+port. The
+current implementation now holds sockets for any number of hosts.
 
-    var http = require('http');
-    var net = require('net');
+The current HTTP Agent also defaults client requests to using
+Connection:keep-alive. If no pending HTTP requests are waiting on a socket
+to become free the socket is closed. This means that node's pool has the
+benefit of keep-alive when under load but still does not require developers
+to manually close the HTTP clients using keep-alive.
+
+Sockets are removed from the agent's pool when the socket emits either a
+"close" event or a special "agentRemove" event. This means that if you intend
+to keep one HTTP request open for a long time and don't want it to stay in the
+pool you can do something along the lines of:
 
-    // 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
-      };
+    http.get(options, function(res) {
+      // Do stuff
+    }).on("socket", function (socket) {
+      socket.emit("agentRemove");
     });
 
-    // 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);
-      });
-    });
+Alternatively, you could just opt out of pooling entirely using `agent:false`:
 
+    http.get({host:'localhost', port:80, path:'/', agent:false}, function (res) {
+      // Do stuff
+    })
 
 ### agent.maxSockets
 
-By default set to 5. Determines how many concurrent sockets the agent can have open.
+By default set to 5. Determines how many concurrent sockets the agent can have 
+open per host.
 
 ### agent.sockets
 
-An array of sockets currently in use by the Agent. Do not modify.
+An object which contains arrays of sockets currently in use by the Agent. Do not 
+modify.
+
+### agent.requests
 
-### agent.queue
+An object which contains queues of requests that have not yet been assigned to 
+sockets. Do not modify.
 
-A queue of requests waiting to be sent to sockets.
+## http.globalAgent
 
+Global instance of Agent which is used as the default for all http client
+requests.
 
 
-## http.ClientRequest
+## Class: http.ClientRequest
 
 This object is created internally and returned from `http.request()`.  It
 represents an _in-progress_ request whose header has already been queued.  The
@@ -590,19 +580,11 @@ event, the entire body will be caught.
       }, 10);
     });
 
-This is a `Writable Stream`.
 Note: Node does not check whether Content-Length and the length of the body
 which has been transmitted are equal or not.
 
-This is an `EventEmitter` with the following events:
-
-### Event: 'continue'
-
-`function () { }`
-
-Emitted when the server sends a '100 Continue' HTTP response, usually because
-the request contained 'Expect: 100-continue'. This is an instruction that
-the client should send the request body.
+The request implements the [Writable  Stream](stream.html#writable_stream)
+interface. This is an `EventEmitter` with the following events:
 
 ### Event 'response'
 
@@ -611,8 +593,79 @@ the client should send the request body.
 Emitted when a response is received to this request. This event is emitted only once. The
 `response` argument will be an instance of `http.ClientResponse`.
 
+Options:
+
+- `host`: A domain name or IP address of the server to issue the request to.
+- `port`: Port of remote server.
+- `socketPath`: Unix Domain Socket (use one of host:port or socketPath)
 
-### request.write(chunk, encoding='utf8')
+### Event: 'socket'
+
+`function (socket) { }`
+
+Emitted after a socket is assigned to this request.
+
+### Event: 'upgrade'
+
+`function (response, socket, head) { }`
+
+Emitted each time a server responds to a request with an upgrade. If this
+event isn't being listened for, clients receiving an upgrade header will have
+their connections closed.
+
+A client server pair that show you how to listen for the `upgrade` event using `http.getAgent`:
+
+    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 options = {
+        port: 1337,
+        host: '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 () { }`
+
+Emitted when the server sends a '100 Continue' HTTP response, usually because
+the request contained 'Expect: 100-continue'. This is an instruction that
+the client should send the request body.
+
+### request.write(chunk, [encoding])
 
 Sends a chunk of the body.  By calling this method
 many times, the user can stream a request body to a
@@ -620,11 +673,10 @@ server--in that case it is suggested to
 `['Transfer-Encoding', 'chunked']` header line when
 creating the request.
 
-The `chunk` argument should be an array of integers
-or a string.
+The `chunk` argument should be a [buffer](buffer.html) or a string.
 
-The `encoding` argument is optional and only
-applies when `chunk` is a string.
+The `encoding` argument is optional and only applies when `chunk` is a string.
+Defaults to `'utf8'`.
 
 
 ### request.end([data], [encoding])
@@ -633,20 +685,39 @@ Finishes sending the request. If any par
 unsent, it will flush them to the stream. If the request is
 chunked, this will send the terminating `'0\r\n\r\n'`.
 
-If `data` is specified, it is equivalent to calling `request.write(data, encoding)`
-followed by `request.end()`.
+If `data` is specified, it is equivalent to calling
+`request.write(data, encoding)` followed by `request.end()`.
 
 ### request.abort()
 
 Aborts a request.  (New since v0.3.8.)
 
+### request.setTimeout(timeout, [callback])
+
+Once a socket is assigned to this request and is connected 
+[socket.setTimeout(timeout, [callback])](net.html#socket.setTimeout)
+will be called.
+
+### request.setNoDelay([noDelay])
+
+Once a socket is assigned to this request and is connected 
+[socket.setNoDelay(noDelay)](net.html#socket.setNoDelay)
+will be called.
+
+### request.setSocketKeepAlive([enable], [initialDelay])
+
+Once a socket is assigned to this request and is connected 
+[socket.setKeepAlive(enable, [initialDelay])](net.html#socket.setKeepAlive)
+will be called.
 
 ## http.ClientResponse
 
 This object is created when making a request with `http.request()`. It is
 passed to the `'response'` event of the request object.
 
-The response implements the `Readable Stream` interface.
+The response implements the [Readable Stream](stream.html#readable_stream)
+interface. This is an `EventEmitter` with the following events:
+
 
 ### Event: 'data'
 
@@ -654,6 +725,9 @@ The response implements the `Readable St
 
 Emitted when a piece of the message body is received.
 
+Note that the __data will be lost__ if there is no listener when a
+`ClientResponse` emits a `'data'` event.
+
 
 ### Event: 'end'
 
@@ -690,10 +764,11 @@ The response headers object.
 
 The response trailers object. Only populated after the 'end' event.
 
-### response.setEncoding(encoding=null)
+### response.setEncoding([encoding])
 
-Set the encoding for the response body. Either `'utf8'`, `'ascii'`, or `'base64'`.
-Defaults to `null`, which means that the `'data'` event will emit a `Buffer` object..
+Set the encoding for the response body. Either `'utf8'`, `'ascii'`, or
+`'base64'`. Defaults to `null`, which means that the `'data'` event will emit
+a `Buffer` object.
 
 ### response.pause()
 
diff -upr ./api_v0.4.12/https.markdown ./api_v0.6.12/https.markdown
--- ./api_v0.4.12/https.markdown	2011-09-21 00:45:30.000000000 +0400
+++ ./api_v0.6.12/https.markdown	2012-03-08 01:22:12.000000000 +0400
@@ -1,16 +1,16 @@
-## HTTPS
+# HTTPS
 
 HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a
 separate module.
 
-## https.Server
+## Class: https.Server
 
 This class is a subclass of `tls.Server` and emits events same as
 `http.Server`. See `http.Server` for more information.
 
 ## https.createServer(options, [requestListener])
 
-Returns a new HTTPS web server object. The `options` is similer to
+Returns a new HTTPS web server object. The `options` is similar to
 `tls.createServer()`. The `requestListener` is a function which is
 automatically added to the `'request'` event.
 
@@ -34,7 +34,7 @@ Example:
 ## https.request(options, callback)
 
 Makes a request to a secure web server.
-Similar options to `http.request()`.
+All options from [http.request()](http.html#http.request) are valid.
 
 Example:
 
@@ -67,11 +67,69 @@ The options argument has the following o
 - port: port of host to request to. Defaults to 443.
 - path: Path to request. Default `'/'`.
 - method: HTTP request method. Default `'GET'`.
-- key: Private key to use for SSL. Default `null`.
-- cert: Public x509 certificate to use. Default `null`.
-- ca: An authority certificate or array of authority certificates to check
+
+- `host`: A domain name or IP address of the server to issue the request to.
+  Defaults to `'localhost'`.
+- `hostname`: To support `url.parse()` `hostname` is preferred over `host`
+- `port`: Port of remote server. Defaults to 443.
+- `method`: A string specifying the HTTP request method. Defaults to `'GET'`.
+- `path`: Request path. Defaults to `'/'`. Should include query string if any.
+  E.G. `'/index.html?page=12'`
+- `headers`: An object containing request headers.
+- `auth`: Basic authentication i.e. `'user:password'` to compute an
+  Authorization header.
+- `agent`: Controls [Agent](#https.Agent) behavior. When an Agent is
+  used request will default to `Connection: keep-alive`. Possible values:
+ - `undefined` (default): use [globalAgent](#https.globalAgent) for this
+   host and port.
+ - `Agent` object: explicitly use the passed in `Agent`.
+ - `false`: opts out of connection pooling with an Agent, defaults request to
+   `Connection: close`.
+
+The following options from [tls.connect()](tls.html#tls.connect) can also be
+specified. However, a [globalAgent](#https.globalAgent) silently ignores these.
+
+- `key`: Private key to use for SSL. Default `null`.
+- `passphrase`: A string of passphrase for the private key. Default `null`.
+- `cert`: Public x509 certificate to use. Default `null`.
+- `ca`: An authority certificate or array of authority certificates to check
   the remote host against.
 
+In order to specify these options, use a custom `Agent`.
+
+Example:
+
+    var options = {
+      host: 'encrypted.google.com',
+      port: 443,
+      path: '/',
+      method: 'GET',
+      key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
+      cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
+    };
+    options.agent = new https.Agent(options);
+
+    var req = https.request(options, function(res) {
+      ...
+    }
+
+Or does not use an `Agent`.
+
+Example:
+
+    var options = {
+      host: 'encrypted.google.com',
+      port: 443,
+      path: '/',
+      method: 'GET',
+      key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
+      cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
+      agent: false
+    };
+
+    var req = https.request(options, function(res) {
+      ...
+    }
 
 ## https.get(options, callback)
 
@@ -94,5 +152,13 @@ Example:
     });
 
 
+## Class: https.Agent
+
+An Agent object for HTTPS similar to [http.Agent](http.html#http.Agent).
+See [https.request()](#https.request) for more information.
+
 
+## https.globalAgent
 
+Global instance of [https.Agent](#https.Agent) which is used as the default
+for all HTTPS client requests.
diff -upr ./api_v0.4.12/modules.markdown ./api_v0.6.12/modules.markdown
--- ./api_v0.4.12/modules.markdown	2011-09-21 00:45:54.000000000 +0400
+++ ./api_v0.6.12/modules.markdown	2012-03-08 01:22:12.000000000 +0400
@@ -1,4 +1,6 @@
-## Modules
+# Modules
+
+<!--name=module-->
 
 Node has a simple module loading system.  In Node, files and modules are in
 one-to-one correspondence.  As an example, `foo.js` loads the module
@@ -30,7 +32,67 @@ Variables
 local to the module will be private. In this example the variable `PI` is
 private to `circle.js`.
 
-### Core Modules
+The module system is implemented in the `require("module")` module.
+
+## Cycles
+
+<!--type=misc-->
+
+When there are circular `require()` calls, a module might not be
+done being executed when it is returned.
+
+Consider this situation:
+
+`a.js`:
+
+    console.log('a starting');
+    exports.done = false;
+    var b = require('./b.js');
+    console.log('in a, b.done = %j', b.done);
+    exports.done = true;
+    console.log('a done');
+
+`b.js`:
+
+    console.log('b starting');
+    exports.done = false;
+    var a = require('./a.js');
+    console.log('in b, a.done = %j', a.done);
+    exports.done = true;
+    console.log('b done');
+
+`main.js`:
+
+    console.log('main starting');
+    var a = require('./a.js');
+    var b = require('./b.js');
+    console.log('in main, a.done=%j, b.done=%j', a.done, b.done);
+
+When `main.js` loads `a.js`, then `a.js` in turn loads `b.js`.  At that
+point, `b.js` tries to load `a.js`.  In order to prevent an infinite
+loop an **unfinished copy** of the `a.js` exports object is returned to the
+`b.js` module.  `b.js` then finishes loading, and its exports object is
+provided to the `a.js` module.
+
+By the time `main.js` has loaded both modules, they're both finished.
+The output of this program would thus be:
+
+    $ node main.js
+    main starting
+    a starting
+    b starting
+    in b, a.done = false
+    b done
+    in a, b.done = true
+    a done
+    in main, a.done=true, b.done=true
+
+If you have cyclic module dependencies in your program, make sure to
+plan accordingly.
+
+## Core Modules
+
+<!--type=misc-->
 
 Node has several modules compiled into the binary.  These modules are
 described in greater detail elsewhere in this documentation.
@@ -41,13 +103,16 @@ Core modules are always preferentially l
 passed to `require()`.  For instance, `require('http')` will always
 return the built in HTTP module, even if there is a file by that name.
 
-### File Modules
+## File Modules
+
+<!--type=misc-->
 
 If the exact filename is not found, then node will attempt to load the
-required filename with the added extension of `.js`, and then `.node`.
+required filename with the added extension of `.js`, `.json`, and then `.node`.
 
-`.js` files are interpreted as JavaScript text files, and `.node` files
-are interpreted as compiled addon modules loaded with `dlopen`.
+`.js` files are interpreted as JavaScript text files, and `.json` files are
+parsed as JSON text files. `.node` files are interpreted as compiled addon
+modules loaded with `dlopen`.
 
 A module prefixed with `'/'` is an absolute path to the file.  For
 example, `require('/home/marco/foo.js')` will load the file at
@@ -60,7 +125,9 @@ That is, `circle.js` must be in the same
 Without a leading '/' or './' to indicate a file, the module is either a
 "core module" or is loaded from a `node_modules` folder.
 
-### Loading from `node_modules` Folders
+## Loading from `node_modules` Folders
+
+<!--type=misc-->
 
 If the module identifier passed to `require()` is not a native module,
 and does not begin with `'/'`, `'../'`, or `'./'`, then node starts at the
@@ -82,7 +149,9 @@ this order:
 This allows programs to localize their dependencies, so that they do not
 clash.
 
-### Folders as Modules
+## Folders as Modules
+
+<!--type=misc-->
 
 It is convenient to organize programs and libraries into self-contained
 directories, and then provide a single entry point to that library.
@@ -110,7 +179,9 @@ example, then `require('./some-library')
 * `./some-library/index.js`
 * `./some-library/index.node`
 
-### Caching
+## Caching
+
+<!--type=misc-->
 
 Modules are cached after the first time they are loaded.  This means
 (among other things) that every call to `require('foo')` will get
@@ -124,7 +195,9 @@ dependencies to be loaded even when they
 If you want to have a module execute code multiple times, then export a
 function, and call that function.
 
-#### Module Caching Caveats
+### Module Caching Caveats
+
+<!--type=misc-->
 
 Modules are cached based on their resolved filename.  Since modules may
 resolve to a different filename based on the location of the calling
@@ -132,8 +205,22 @@ module (loading from `node_modules` fold
 that `require('foo')` will always return the exact same object, if it
 would resolve to different files.
 
+## The `module` Object
+
+<!-- type=var -->
+<!-- name=module -->
+
+* {Object}
+
+In each module, the `module` free variable is a reference to the object
+representing the current module.  In particular
+`module.exports` is the same as the `exports` object.
+`module` isn't actually a global but rather local to each module.
+
 ### module.exports
 
+* {Object}
+
 The `exports` object is created by the Module system. Sometimes this is not
 acceptable, many want their module to be an instance of some class. To do this
 assign the desired export object to `module.exports`. For example suppose we
@@ -172,7 +259,61 @@ y.js:
     console.log(x.a);
 
 
-### All Together...
+### module.require(id)
+
+* `id` {String}
+* Return: {Object} `exports` from the resolved module
+
+The `module.require` method provides a way to load a module as if
+`require()` was called from the original module.
+
+Note that in order to do this, you must get a reference to the `module`
+object.  Since `require()` returns the `exports`, and the `module` is
+typically *only* available within a specific module's code, it must be
+explicitly exported in order to be used.
+
+
+### module.id
+
+* {String}
+
+The identifier for the module.  Typically this is the fully resolved
+filename.
+
+
+### module.filename
+
+* {String}
+
+The fully resolved filename to the module.
+
+
+### module.loaded
+
+* {Boolean}
+
+Whether or not the module is done loading, or is in the process of
+loading.
+
+
+### module.parent
+
+* {Module Object}
+
+The module that required this one.
+
+
+### module.children
+
+* {Array}
+
+The module objects required by this one.
+
+
+
+## All Together...
+
+<!-- type=misc -->
 
 To get the exact filename that will be loaded when `require()` is called, use
 the `require.resolve()` function.
@@ -200,7 +341,8 @@ in pseudocode of what require.resolve do
        a. Parse X/package.json, and look for "main" field.
        b. let M = X + (json main field)
        c. LOAD_AS_FILE(M)
-    2. LOAD_AS_FILE(X/index)
+    2. If X/index.js is a file, load X/index.js as JavaScript text.  STOP
+    3. If X/index.node is a file, load X/index.node as binary addon.  STOP
 
     LOAD_NODE_MODULES(X, START)
     1. let DIRS=NODE_MODULES_PATHS(START)
@@ -220,80 +362,31 @@ in pseudocode of what require.resolve do
        c. let I = I - 1
     6. return DIRS
 
-### Loading from the `require.paths` Folders
+## Loading from the global folders
 
-In node, `require.paths` is an array of strings that represent paths to
-be searched for modules when they are not prefixed with `'/'`, `'./'`, or
-`'../'`.  For example, if require.paths were set to:
+<!-- type=misc -->
 
-    [ '/home/micheil/.node_modules',
-      '/usr/local/lib/node_modules' ]
+If the `NODE_PATH` environment variable is set to a colon-delimited list
+of absolute paths, then node will search those paths for modules if they
+are not found elsewhere.  (Note: On Windows, `NODE_PATH` is delimited by
+semicolons instead of colons.)
 
-Then calling `require('bar/baz.js')` would search the following
-locations:
+Additionally, node will search in the following locations:
 
-* 1: `'/home/micheil/.node_modules/bar/baz.js'`
-* 2: `'/usr/local/lib/node_modules/bar/baz.js'`
+* 1: `$HOME/.node_modules`
+* 2: `$HOME/.node_libraries`
+* 3: `$PREFIX/lib/node`
 
-The `require.paths` array can be mutated at run time to alter this
-behavior.
+Where `$HOME` is the user's home directory, and `$PREFIX` is node's
+configured `installPrefix`.
 
-It is set initially from the `NODE_PATH` environment variable, which is
-a colon-delimited list of absolute paths.  In the previous example,
-the `NODE_PATH` environment variable might have been set to:
+These are mostly for historic reasons.  You are highly encouraged to
+place your dependencies locally in `node_modules` folders.  They will be
+loaded faster, and more reliably.
 
-    /home/micheil/.node_modules:/usr/local/lib/node_modules
+## Accessing the main module
 
-Loading from the `require.paths` locations is only performed if the
-module could not be found using the `node_modules` algorithm above.
-Global modules are lower priority than bundled dependencies.
-
-#### **Note:** Please Avoid Using `require.paths`
-
-`require.paths` will only be supported through the end of the v0.4
-stable branch.  It is removed from node as of v0.5.
-
-While it seemed like a good idea at the time, and enabled a lot of
-useful experimentation, in practice a mutable `require.paths` list is
-often a troublesome source of confusion and headaches.
-
-##### Setting `require.paths` to some other value does nothing.
-
-This does not do what one might expect:
-
-    require.paths = [ '/usr/lib/node' ];
-
-All that does is lose the reference to the *actual* node module lookup
-paths, and create a new reference to some other thing that isn't used
-for anything.
-
-##### Putting relative paths in `require.paths` is... weird.
-
-If you do this:
-
-    require.paths.push('./lib');
-
-then it does *not* add the full resolved path to where `./lib`
-is on the filesystem.  Instead, it literally adds `'./lib'`,
-meaning that if you do `require('y.js')` in `/a/b/x.js`, then it'll look
-in `/a/b/lib/y.js`.  If you then did `require('y.js')` in
-`/l/m/n/o/p.js`, then it'd look in `/l/m/n/o/lib/y.js`.
-
-In practice, people have used this as an ad hoc way to bundle
-dependencies, but this technique is brittle.
-
-##### Zero Isolation
-
-There is (by regrettable design), only one `require.paths` array used by
-all modules.
-
-As a result, if one node program comes to rely on this behavior, it may
-permanently and subtly alter the behavior of all other node programs in
-the same process.  As the application stack grows, we tend to assemble
-functionality, and those parts interact in ways that are difficult to
-predict.
-
-### Accessing the main module
+<!-- type=misc -->
 
 When a file is run directly from Node, `require.main` is set to its
 `module`. That means that you can determine whether a file has been run
@@ -310,6 +403,8 @@ by checking `require.main.filename`.
 
 ## Addenda: Package Manager Tips
 
+<!-- type=misc -->
+
 The semantics of Node's `require()` function were designed to be general
 enough to support a number of sane directory structures. Package manager
 programs such as `dpkg`, `rpm`, and `npm` will hopefully find it possible to
diff -upr ./api_v0.4.12/net.markdown ./api_v0.6.12/net.markdown
--- ./api_v0.4.12/net.markdown	2011-09-21 00:45:30.000000000 +0400
+++ ./api_v0.6.12/net.markdown	2012-03-08 01:22:12.000000000 +0400
@@ -1,13 +1,14 @@
-## net
+# net
 
 The `net` module provides you with an asynchronous network wrapper. It contains
 methods for creating both servers and clients (called streams). You can include
-this module with `require("net");`
+this module with `require('net');`
 
-### net.createServer([options], [connectionListener])
+## net.createServer([options], [connectionListener])
 
 Creates a new TCP server. The `connectionListener` argument is
-automatically set as a listener for the `'connection'` event.
+automatically set as a listener for the ['connection'](#event_connection_)
+event.
 
 `options` is an object with the following defaults:
 
@@ -16,68 +17,100 @@ automatically set as a listener for the
 
 If `allowHalfOpen` is `true`, then the socket won't automatically send FIN
 packet when the other end of the socket sends a FIN packet. The socket becomes
-non-readable, but still writable. You should call the end() method explicitly.
-See `'end'` event for more information.
-
-### net.createConnection(arguments...)
-
-Construct a new socket object and opens a socket to the given location. When
-the socket is established the `'connect'` event will be emitted.
-
-The arguments for this method change the type of connection:
-
-* `net.createConnection(port, [host])`
-
-  Creates a TCP connection to `port` on `host`. If `host` is omitted, `localhost`
-  will be assumed.
-
-* `net.createConnection(path)`
-
-  Creates unix socket connection to `path`
-
----
-
-### net.Server
-
-This class is used to create a TCP or UNIX server.
+non-readable, but still writable. You should call the `end()` method explicitly.
+See ['end'](#event_end_) event for more information.
 
 Here is an example of a echo server which listens for connections
 on port 8124:
 
     var net = require('net');
-    var server = net.createServer(function (c) {
+    var server = net.createServer(function(c) { //'connection' listener
+      console.log('server connected');
+      c.on('end', function() {
+        console.log('server disconnected');
+      });
       c.write('hello\r\n');
       c.pipe(c);
     });
-    server.listen(8124, 'localhost');
+    server.listen(8124, function() { //'listening' listener
+      console.log('server bound');
+    });
 
 Test this by using `telnet`:
 
     telnet localhost 8124
 
-To listen on the socket `/tmp/echo.sock` the last line would just be
-changed to
+To listen on the socket `/tmp/echo.sock` the third line from the last would
+just be changed to
 
-    server.listen('/tmp/echo.sock');
+    server.listen('/tmp/echo.sock', function() { //'listening' listener
 
 Use `nc` to connect to a UNIX domain socket server:
 
     nc -U /tmp/echo.sock
 
-`net.Server` is an `EventEmitter` with the following events:
+## net.connect(arguments...)
+## net.createConnection(arguments...)
+
+Construct a new socket object and opens a socket to the given location. When
+the socket is established the ['connect'](#event_connect_) event will be
+emitted.
+
+The arguments for these methods change the type of connection:
+
+* `net.connect(port, [host], [connectListener])`
+* `net.createConnection(port, [host], [connectListener])`
+
+  Creates a TCP connection to `port` on `host`. If `host` is omitted,
+  `'localhost'` will be assumed.
+
+* `net.connect(path, [connectListener])`
+* `net.createConnection(path, [connectListener])`
+
+  Creates unix socket connection to `path`.
+
+The `connectListener` parameter will be added as an listener for the
+['connect'](#event_connect_) event.
+
+Here is an example of a client of echo server as described previously:
+
+    var net = require('net');
+    var client = net.connect(8124, function() { //'connect' listener
+      console.log('client connected');
+      client.write('world!\r\n');
+    });
+    client.on('data', function(data) {
+      console.log(data.toString());
+      client.end();
+    });
+    client.on('end', function() {
+      console.log('client disconnected');
+    });
+
+To connect on the socket `/tmp/echo.sock` the second line would just be
+changed to
+
+    var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
 
-#### server.listen(port, [host], [callback])
+## Class: net.Server
+
+This class is used to create a TCP or UNIX server.
+A server is a `net.Socket` that can listen for new incoming connections.
+
+### server.listen(port, [host], [listeningListener])
 
 Begin accepting connections on the specified `port` and `host`.  If the
 `host` is omitted, the server will accept connections directed to any
-IPv4 address (`INADDR_ANY`).
+IPv4 address (`INADDR_ANY`). A port value of zero will assign a random port.
 
-This function is asynchronous. The last parameter `callback` will be called
-when the server has been bound.
+This function is asynchronous.  When the server has been bound,
+['listening'](#event_listening_) event will be emitted.
+the last parameter `listeningListener` will be added as an listener for the
+['listening'](#event_listening_) event.
 
-One issue some users run into is getting `EADDRINUSE` errors. Meaning
+One issue some users run into is getting `EADDRINUSE` errors. This means that
 another server is already running on the requested port. One way of handling this
-would be to wait a second and the try again. This can be done with
+would be to wait a second and then try again. This can be done with
 
     server.on('error', function (e) {
       if (e.code == 'EADDRINUSE') {
@@ -89,38 +122,26 @@ would be to wait a second and the try ag
       }
     });
 
-(Note: All sockets in Node are set SO_REUSEADDR already)
+(Note: All sockets in Node set `SO_REUSEADDR` already)
 
 
-#### server.listen(path, [callback])
+### server.listen(path, [listeningListener])
 
 Start a UNIX socket server listening for connections on the given `path`.
 
-This function is asynchronous. The last parameter `callback` will be called
-when the server has been bound.
-
-#### server.listenFD(fd)
-
-Start a server listening for connections on the given file descriptor.
+This function is asynchronous.  When the server has been bound,
+['listening'](#event_listening_) event will be emitted.
+the last parameter `listeningListener` will be added as an listener for the
+['listening'](#event_listening_) event.
 
-This file descriptor must have already had the `bind(2)` and `listen(2)` system
-calls invoked on it.  Additionally, it must be set non-blocking; try
-`fcntl(fd, F_SETFL, O_NONBLOCK)`.
-
-#### server.pause(msecs)
-
-Stop accepting connections for the given number of milliseconds (default is
-one second).  This could be useful for throttling new connections against
-DoS attacks or other oversubscription.
-
-#### server.close()
+### server.close()
 
 Stops the server from accepting new connections. This function is
 asynchronous, the server is finally closed when the server emits a `'close'`
 event.
 
 
-#### server.address()
+### server.address()
 
 Returns the bound address and port of the server as reported by the operating system.
 Useful to find which port was assigned when giving getting an OS-assigned address.
@@ -138,40 +159,50 @@ Example:
       console.log("opened server on %j", address);
     });
 
+Don't call `server.address()` until the `'listening'` event has been emitted.
 
-#### server.maxConnections
+### server.maxConnections
 
-Set this property to reject connections when the server's connection count gets high.
+Set this property to reject connections when the server's connection count gets
+high.
 
-#### server.connections
+### server.connections
 
 The number of concurrent connections on the server.
 
-#### Event: 'connection'
 
-`function (socket) {}`
+`net.Server` is an `EventEmitter` with the following events:
+
+### Event: 'listening'
+
+Emitted when the server has been bound after calling `server.listen`.
+
+### Event: 'connection'
+
+* {Socket object} The connection object
 
 Emitted when a new connection is made. `socket` is an instance of
 `net.Socket`.
 
-#### Event: 'close'
-
-`function () {}`
+### Event: 'close'
 
 Emitted when the server closes.
 
----
+### Event: 'error'
+
+* {Error Object}
+
+Emitted when an error occurs.  The `'close'` event will be called directly
+following this event.  See example in discussion of `server.listen`.
 
-### net.Socket
+## Class: net.Socket
 
-This object is an abstraction of of a TCP or UNIX socket.  `net.Socket`
+This object is an abstraction of a TCP or UNIX socket.  `net.Socket`
 instances implement a duplex Stream interface.  They can be created by the
 user and used as a client (with `connect()`) or they can be created by Node
 and passed to the user through the `'connection'` event of a server.
 
-`net.Socket` instances are EventEmitters with the following events:
-
-#### new net.Socket([options])
+### new net.Socket([options])
 
 Construct a new socket object.
 
@@ -186,8 +217,8 @@ Construct a new socket object.
 specified underlying protocol. It can be `'tcp4'`, `'tcp6'`, or `'unix'`.
 About `allowHalfOpen`, refer to `createServer()` and `'end'` event.
 
-#### socket.connect(port, [host], [callback])
-#### socket.connect(path, [callback])
+### socket.connect(port, [host], [connectListener])
+### socket.connect(path, [connectListener])
 
 Opens the connection for a given socket. If `port` and `host` are given,
 then the socket will be opened as a TCP socket, if `host` is omitted,
@@ -198,23 +229,23 @@ Normally this method is not needed, as `
 socket. Use this only if you are implementing a custom Socket or if a
 Socket is closed and you want to reuse it to connect to another server.
 
-This function is asynchronous. When the `'connect'` event is emitted the
-socket is established. If there is a problem connecting, the `'connect'`
-event will not be emitted, the `'error'` event will be emitted with
+This function is asynchronous. When the ['connect'](#event_connect_) event is
+emitted the socket is established. If there is a problem connecting, the
+`'connect'` event will not be emitted, the `'error'` event will be emitted with
 the exception.
 
-The `callback` parameter will be added as an listener for the 'connect'
-event.
+The `connectListener` parameter will be added as an listener for the
+['connect'](#event_connect_) event.
 
 
-#### socket.bufferSize
+### socket.bufferSize
 
 `net.Socket` has the property that `socket.write()` always works. This is to
-help users get up an running quickly. The computer cannot necessarily keep up
-with the amount of data that is written to a socket - the network connection simply
-might be too slow. Node will internally queue up the data written to a socket and
-send it out over the wire when it is possible. (Internally it is polling on
-the socket's file descriptor for being writable).
+help users get up and running quickly. The computer cannot always keep up
+with the amount of data that is written to a socket - the network connection
+simply might be too slow. Node will internally queue up the data written to a
+socket and send it out over the wire when it is possible. (Internally it is
+polling on the socket's file descriptor for being writable).
 
 The consequence of this internal buffering is that memory may grow. This
 property shows the number of characters currently buffered to be written.
@@ -223,21 +254,21 @@ written, but the buffer may contain stri
 encoded, so the exact number of bytes is not known.)
 
 Users who experience large or growing `bufferSize` should attempt to
-"throttle" the data flows in their program with `pause()` and resume()`.
+"throttle" the data flows in their program with `pause()` and `resume()`.
 
 
-#### socket.setEncoding(encoding=null)
+### socket.setEncoding([encoding])
 
 Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is
-received.
+received. Defaults to `null`.
 
-#### socket.setSecure()
+### socket.setSecure()
 
 This function has been removed in v0.3. It used to upgrade the connection to
 SSL/TLS. See the [TLS section](tls.html#tLS_) for the new API.
 
 
-#### socket.write(data, [encoding], [callback])
+### socket.write(data, [encoding], [callback])
 
 Sends data on the socket. The second parameter specifies the encoding in the
 case of a string--it defaults to UTF8 encoding.
@@ -249,36 +280,34 @@ buffer. Returns `false` if all or part o
 The optional `callback` parameter will be executed when the data is finally
 written out - this may not be immediately.
 
-#### socket.write(data, [encoding], [fileDescriptor], [callback])
-
-For UNIX sockets, it is possible to send a file descriptor through the
-socket. Simply add the `fileDescriptor` argument and listen for the `'fd'`
-event on the other end.
+### socket.write(data, [encoding], [callback])
 
+Write data with the optional encoding. The callback will be made when the
+data is flushed to the kernel.
 
-#### socket.end([data], [encoding])
+### socket.end([data], [encoding])
 
-Half-closes the socket. I.E., it sends a FIN packet. It is possible the
+Half-closes the socket. i.e., it sends a FIN packet. It is possible the
 server will still send some data.
 
-If `data` is specified, it is equivalent to calling `socket.write(data, encoding)`
-followed by `socket.end()`.
+If `data` is specified, it is equivalent to calling
+`socket.write(data, encoding)` followed by `socket.end()`.
 
-#### socket.destroy()
+### socket.destroy()
 
 Ensures that no more I/O activity happens on this socket. Only necessary in
 case of errors (parse error or so).
 
-#### socket.pause()
+### socket.pause()
 
 Pauses the reading of data. That is, `'data'` events will not be emitted.
 Useful to throttle back an upload.
 
-#### socket.resume()
+### socket.resume()
 
 Resumes reading after a call to `pause()`.
 
-#### socket.setTimeout(timeout, [callback])
+### socket.setTimeout(timeout, [callback])
 
 Sets the socket to timeout after `timeout` milliseconds of inactivity on
 the socket. By default `net.Socket` do not have a timeout.
@@ -289,54 +318,72 @@ or `destroy()` the socket.
 
 If `timeout` is 0, then the existing idle timeout is disabled.
 
-The optional `callback` parameter will be added as a one time listener for the `'timeout'` event.
+The optional `callback` parameter will be added as a one time listener for the
+`'timeout'` event.
 
-#### socket.setNoDelay(noDelay=true)
+### socket.setNoDelay([noDelay])
 
 Disables the Nagle algorithm. By default TCP connections use the Nagle
-algorithm, they buffer data before sending it off. Setting `noDelay` will
-immediately fire off data each time `socket.write()` is called.
+algorithm, they buffer data before sending it off. Setting `true` for
+`noDelay` will immediately fire off data each time `socket.write()` is called.
+`noDelay` defaults to `true`.
 
-#### socket.setKeepAlive(enable=false, [initialDelay])
+### socket.setKeepAlive([enable], [initialDelay])
 
 Enable/disable keep-alive functionality, and optionally set the initial
 delay before the first keepalive probe is sent on an idle socket.
+`enable` defaults to `false`.
+
 Set `initialDelay` (in milliseconds) to set the delay between the last
 data packet received and the first keepalive probe. Setting 0 for
 initialDelay will leave the value unchanged from the default
-(or previous) setting.
+(or previous) setting. Defaults to `0`.
 
-#### socket.address()
+### socket.address()
 
-Returns the bound address and port of the socket as reported by the operating system.
-Returns an object with two properties, e.g. `{"address":"192.168.57.1", "port":62053}`
+Returns the bound address and port of the socket as reported by the operating
+system. Returns an object with two properties, e.g.
+`{"address":"192.168.57.1", "port":62053}`
 
-#### socket.remoteAddress
+### socket.remoteAddress
 
 The string representation of the remote IP address. For example,
 `'74.125.127.100'` or `'2001:4860:a005::68'`.
 
-This member is only present in server-side connections.
+### socket.remotePort
+
+The numeric representation of the remote port. For example,
+`80` or `21`.
+
+### socket.bytesRead
+
+The amount of received bytes.
 
+### socket.bytesWritten
 
-#### Event: 'connect'
+The amount of bytes sent.
 
-`function () { }`
 
-Emitted when a socket connection successfully is established.
+`net.Socket` instances are EventEmitters with the following events:
+
+### Event: 'connect'
+
+Emitted when a socket connection is successfully established.
 See `connect()`.
 
-#### Event: 'data'
+### Event: 'data'
 
-`function (data) { }`
+* {Buffer object}
 
 Emitted when data is received.  The argument `data` will be a `Buffer` or
 `String`.  Encoding of data is set by `socket.setEncoding()`.
-(See the [Readable Stream](streams.html#readable_Stream) section for more information.)
+(See the [Readable Stream](stream.html#readable_stream) section for more
+information.)
 
-#### Event: 'end'
+Note that the __data will be lost__ if there is no listener when a `Socket`
+emits a `'data'` event.
 
-`function () { }`
+### Event: 'end'
 
 Emitted when the other end of the socket sends a FIN packet.
 
@@ -347,9 +394,7 @@ its side allowing the user to write arbi
 caveat that the user is required to `end()` their side now.
 
 
-#### Event: 'timeout'
-
-`function () { }`
+### Event: 'timeout'
 
 Emitted if the socket times out from inactivity. This is only to notify that
 the socket has been idle. The user must manually close the connection.
@@ -357,42 +402,38 @@ the socket has been idle. The user must
 See also: `socket.setTimeout()`
 
 
-#### Event: 'drain'
-
-`function () { }`
+### Event: 'drain'
 
 Emitted when the write buffer becomes empty. Can be used to throttle uploads.
 
-#### Event: 'error'
+See also: the return values of `socket.write()`
+
+### Event: 'error'
 
-`function (exception) { }`
+* {Error object}
 
 Emitted when an error occurs.  The `'close'` event will be called directly
 following this event.
 
-#### Event: 'close'
+### Event: 'close'
 
-`function (had_error) { }`
+* `had_error` {Boolean} true if the socket had a transmission error
 
 Emitted once the socket is fully closed. The argument `had_error` is a boolean
 which says if the socket was closed due to a transmission error.
 
----
-
-### net.isIP
-
-#### net.isIP(input)
+## net.isIP(input)
 
 Tests if input is an IP address. Returns 0 for invalid strings,
 returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.
 
 
-#### net.isIPv4(input)
+## net.isIPv4(input)
 
 Returns true if input is a version 4 IP address, otherwise returns false.
 
 
-#### net.isIPv6(input)
+## net.isIPv6(input)
 
 Returns true if input is a version 6 IP address, otherwise returns false.

diff -upr ./api_v0.4.12/tls.markdown ./api_v0.6.12/tls.markdown
--- ./api_v0.4.12/tls.markdown	2011-09-21 00:45:54.000000000 +0400
+++ ./api_v0.6.12/tls.markdown	2012-03-08 01:22:12.000000000 +0400
@@ -1,4 +1,4 @@
-## TLS (SSL)
+# TLS (SSL)
 
 Use `require('tls')` to access this module.
 
@@ -26,43 +26,186 @@ Alternatively you can send the CSR to a
 (TODO: docs on creating a CA, for now interested users should just look at
 `test/fixtures/keys/Makefile` in the Node source code)
 
+## Client-initiated renegotiation attack mitigation
 
-### s = tls.connect(port, [host], [options], callback)
+<!-- type=misc -->
 
-Creates a new client connection to the given `port` and `host`. (If `host`
-defaults to `localhost`.) `options` should be an object which specifies
+The TLS protocol lets the client renegotiate certain aspects of the TLS session.
+Unfortunately, session renegotiation requires a disproportional amount of
+server-side resources, which makes it a potential vector for denial-of-service
+attacks.
+
+To mitigate this, renegotiations are limited to three times every 10 minutes. An
+error is emitted on the [CleartextStream](#tls.CleartextStream) instance when
+the threshold is exceeded. The limits are configurable:
+
+  - `tls.CLIENT_RENEG_LIMIT`: renegotiation limit, default is 3.
+
+  - `tls.CLIENT_RENEG_WINDOW`: renegotiation window in seconds, default is
+                               10 minutes.
+
+Don't change the defaults unless you know what you are doing.
+
+To test your server, connect to it with `openssl s_client -connect address:port`
+and tap `R<CR>` (that's the letter `R` followed by a carriage return) a few
+times.
+
+
+## NPN and SNI
+
+<!-- type=misc -->
+
+NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS
+handshake extensions allowing you:
+
+  * NPN - to use one TLS server for multiple protocols (HTTP, SPDY)
+  * SNI - to use one TLS server for multiple hostnames with different SSL
+    certificates.
+
+
+## tls.createServer(options, [secureConnectionListener])
+
+Creates a new [tls.Server](#tls.Server).
+The `connectionListener` argument is automatically set as a listener for the
+[secureConnection](#event_secureConnection_) event.
+The `options` object has these possibilities:
 
   - `key`: A string or `Buffer` containing the private key of the server in
     PEM format. (Required)
 
+  - `passphrase`: A string of passphrase for the private key.
+
   - `cert`: A string or `Buffer` containing the certificate key of the server in
+    PEM format. (Required)
+
+  - `ca`: An array of strings or `Buffer`s of trusted certificates. If this is
+    omitted several well known "root" CAs will be used, like VeriSign.
+    These are used to authorize connections.
+
+  - `ciphers`: A string describing the ciphers to use or exclude. Consult
+    <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT> for
+    details on the format.
+
+  - `requestCert`: If `true` the server will request a certificate from
+    clients that connect and attempt to verify that certificate. Default:
+    `false`.
+
+  - `rejectUnauthorized`: If `true` the server will reject any connection
+    which is not authorized with the list of supplied CAs. This option only
+    has an effect if `requestCert` is `true`. Default: `false`.
+
+  - `NPNProtocols`: An array or `Buffer` of possible NPN protocols. (Protocols
+    should be ordered by their priority).
+
+  - `SNICallback`: A function that will be called if client supports SNI TLS
+    extension. Only one argument will be passed to it: `servername`. And
+    `SNICallback` should return SecureContext instance.
+    (You can use `crypto.createCredentials(...).context` to get proper
+    SecureContext). If `SNICallback` wasn't provided - default callback with
+    high-level API will be used (see below).
+
+  - `sessionIdContext`: A string containing a opaque identifier for session
+    resumption. If `requestCert` is `true`, the default is MD5 hash value
+    generated from command-line. Otherwise, the default is not provided.
+
+Here is a simple example echo server:
+
+    var tls = require('tls');
+    var fs = require('fs');
+
+    var options = {
+      key: fs.readFileSync('server-key.pem'),
+      cert: fs.readFileSync('server-cert.pem'),
+
+      // This is necessary only if using the client certificate authentication.
+      requestCert: true,
+
+      // This is necessary only if the client uses the self-signed certificate.
+      ca: [ fs.readFileSync('client-cert.pem') ]
+    };
+
+    var server = tls.createServer(options, function(cleartextStream) {
+      console.log('server connected',
+                  cleartextStream.authorized ? 'authorized' : 'unauthorized');
+      cleartextStream.write("welcome!\n");
+      cleartextStream.setEncoding('utf8');
+      cleartextStream.pipe(cleartextStream);
+    });
+    server.listen(8000, function() {
+      console.log('server bound');
+    });
+
+
+You can test this server by connecting to it with `openssl s_client`:
+
+
+    openssl s_client -connect 127.0.0.1:8000
+
+
+## tls.connect(port, [host], [options], [secureConnectListener])
+
+Creates a new client connection to the given `port` and `host`. (If `host`
+defaults to `localhost`.) `options` should be an object which specifies
+
+  - `key`: A string or `Buffer` containing the private key of the client in
+    PEM format.
+
+  - `passphrase`: A string of passphrase for the private key.
+
+  - `cert`: A string or `Buffer` containing the certificate key of the client in
     PEM format.
 
   - `ca`: An array of strings or `Buffer`s of trusted certificates. If this is
     omitted several well known "root" CAs will be used, like VeriSign.
     These are used to authorize connections.
 
+  - `NPNProtocols`: An array of string or `Buffer` containing supported NPN
+    protocols. `Buffer` should have following format: `0x05hello0x05world`,
+    where first byte is next protocol name's length. (Passing array should
+    usually be much simpler: `['hello', 'world']`.)
+
+  - `servername`: Servername for SNI (Server Name Indication) TLS extension.
+
+  - `socket`: Establish secure connection on a given socket rather than
+    creating a new socket. If this option is specified, `host` and `port`
+    are ignored.  This is intended FOR INTERNAL USE ONLY.  As with all
+    undocumented APIs in Node, they should not be used.
+
+The `secureConnectListener` parameter will be added as a listener for the
+['secureConnect'](#event_secureConnect_) event.
+
 `tls.connect()` returns a [CleartextStream](#tls.CleartextStream) object.
 
-After the TLS/SSL handshake the `callback` is called. The `callback` will be
-called no matter if the server's certificate was authorized or not. It is up
-to the user to test `s.authorized` to see if the server certificate was signed
-by one of the specified CAs. If `s.authorized === false` then the error can be
-found in `s.authorizationError`.
+Here is an example of a client of echo server as described previously:
 
+    var tls = require('tls');
+    var fs = require('fs');
 
-### STARTTLS
+    var options = {
+      // These are necessary only if using the client certificate authentication
+      key: fs.readFileSync('client-key.pem'),
+      cert: fs.readFileSync('client-cert.pem'),
+    
+      // This is necessary only if the server uses the self-signed certificate
+      ca: [ fs.readFileSync('server-cert.pem') ]
+    };
 
-In the v0.4 branch no function exists for starting a TLS session on an
-already existing TCP connection.  This is possible it just requires a bit of
-work. The technique is to use `tls.createSecurePair()` which returns two
-streams: an encrypted stream and a cleartext stream. The encrypted stream is
-then piped to the socket, the cleartext stream is what the user interacts with
-thereafter.
+    var cleartextStream = tls.connect(8000, options, function() {
+      console.log('client connected',
+                  cleartextStream.authorized ? 'authorized' : 'unauthorized');
+      process.stdin.pipe(cleartextStream);
+      process.stdin.resume();
+    });
+    cleartextStream.setEncoding('utf8');
+    cleartextStream.on('data', function(data) {
+      console.log(data);
+    });
+    cleartextStream.on('end', function() {
+      server.close();
+    });
 
-[Here is some code that does it.](http://gist.github.com/848444)
 
-### pair = tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])
+## tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])
 
 Creates a new secure pair object with two streams, one of which reads/writes
 encrypted data, and one reads/writes cleartext data.
@@ -84,7 +227,11 @@ and the cleartext one is used as a repla
 `tls.createSecurePair()` returns a SecurePair object with
 [cleartext](#tls.CleartextStream) and `encrypted` stream properties.
 
-#### Event: 'secure'
+## Class: SecurePair
+
+Returned by tls.createSecurePair.
+
+### Event: 'secure'
 
 The event is emitted from the SecurePair once the pair has successfully
 established a secure connection.
@@ -93,59 +240,13 @@ Similarly to the checking for the server
 pair.cleartext.authorized should be checked to confirm whether the certificate
 used properly authorized.
 
-### tls.Server
+## Class: tls.Server
 
 This class is a subclass of `net.Server` and has the same methods on it.
 Instead of accepting just raw TCP connections, this accepts encrypted
 connections using TLS or SSL.
 
-Here is a simple example echo server:
-
-    var tls = require('tls');
-    var fs = require('fs');
-
-    var options = {
-      key: fs.readFileSync('server-key.pem'),
-      cert: fs.readFileSync('server-cert.pem')
-    };
-
-    tls.createServer(options, function (s) {
-      s.write("welcome!\n");
-      s.pipe(s);
-    }).listen(8000);
-
-
-You can test this server by connecting to it with `openssl s_client`:
-
-
-    openssl s_client -connect 127.0.0.1:8000
-
-
-#### tls.createServer(options, secureConnectionListener)
-
-This is a constructor for the `tls.Server` class. The options object
-has these possibilities:
-
-  - `key`: A string or `Buffer` containing the private key of the server in
-    PEM format. (Required)
-
-  - `cert`: A string or `Buffer` containing the certificate key of the server in
-    PEM format. (Required)
-
-  - `ca`: An array of strings or `Buffer`s of trusted certificates. If this is
-    omitted several well known "root" CAs will be used, like VeriSign.
-    These are used to authorize connections.
-
-  - `requestCert`: If `true` the server will request a certificate from
-    clients that connect and attempt to verify that certificate. Default:
-    `false`.
-
-  - `rejectUnauthorized`: If `true` the server will reject any connection
-    which is not authorized with the list of supplied CAs. This option only
-    has an effect if `requestCert` is `true`. Default: `false`.
-
-
-#### Event: 'secureConnection'
+### Event: 'secureConnection'
 
 `function (cleartextStream) {}`
 
@@ -160,9 +261,20 @@ server. If `cleartextStream.authorized`
 `cleartextStream.authorizationError` is set to describe how authorization
 failed. Implied but worth mentioning: depending on the settings of the TLS
 server, you unauthorized connections may be accepted.
+`cleartextStream.npnProtocol` is a string containing selected NPN protocol.
+`cleartextStream.servername` is a string containing servername requested with
+SNI.