Merge branch 'v0.4'

Conflicts:
	src/node_crypto.cc

6 files changed, 92 insertions, 18 deletions

diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown
index 56021f305d..9212cc051d 100644
--- a/doc/api/dns.markdown
+++ b/doc/api/dns.markdown
@@ -41,7 +41,8 @@ necessarily the value initially passed to `lookup`).
 Resolves a domain (e.g. `'google.com'`) into an array of the record types
 specified by rrtype. Valid rrtypes are `A` (IPV4 addresses), `AAAA` (IPV6
 addresses), `MX` (mail exchange records), `TXT` (text records), `SRV` (SRV
-records), and `PTR` (used for reverse IP lookups).
+records), `PTR` (used for reverse IP lookups), `NS` (name server records)
+and `CNAME` (canonical name records).
 
 The callback has arguments `(err, addresses)`.  The type of each item
 in `addresses` is determined by the record type, and described in the
@@ -89,6 +90,18 @@ Reverse resolves an ip address to an array of domain names.
 
 The callback has arguments `(err, domains)`.
 
+### dns.resolveNs(domain, callback)
+
+The same as `dns.resolve()`, but only for name server records (`NS` records).
+`addresses` is an array of the name server records available for `domain`
+(e.g., `['ns1.example.com', 'ns2.example.com']`).
+
+### dns.resolveCname(domain, callback)
+
+The same as `dns.resolve()`, but only for canonical name records (`CNAME`
+records). `addresses` is an array of the canonical name records available for
+`domain` (e.g., `['bar.example.com']`).
+
 If there an an error, `err` will be non-null and an instanceof the Error
 object.
 
diff --git a/doc/api/http.markdown b/doc/api/http.markdown
index 402a7acfd0..e270238fdb 100644
--- a/doc/api/http.markdown
+++ b/doc/api/http.markdown
@@ -142,9 +142,29 @@ body chunk is a string.  The body encoding is set with
 
 `function () { }`
 
-Emitted exactly once for each message. No arguments.  After
-emitted no other events will be emitted on the request.
+Emitted exactly once for each request. After that, no more `'data'` events
+will be emitted on the request.
 
+### Event: 'close'
+
+`function (err) { }`
+
+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.
+
+Note: `'close'` can fire after `'end'`, but not vice versa.
 
 ### request.method
 
diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown
index 07ff31fe54..eec27b2d83 100644
--- a/doc/api/modules.markdown
+++ b/doc/api/modules.markdown
@@ -139,6 +139,22 @@ Modules are cached after the first time they are loaded.  This means
 (among other things) that every call to `require('foo')` will get
 exactly the same object returned, if it would resolve to the same file.
 
+Multiple calls to `require('foo')` may not cause the module code to be
+executed multiple times.  This is an important feature.  With it,
+"partially done" objects can be returned, thus allowing transitive
+dependencies to be loaded even when they would cause cycles.
+
+If you want to have a module execute code multiple times, then export a
+function, and call that function.
+
+#### Module Caching Caveats
+
+Modules are cached based on their resolved filename.  Since modules may
+resolve to a different filename based on the location of the calling
+module (loading from `node_modules` folders), it is not a *guarantee*
+that `require('foo')` will always return the exact same object, if it
+would resolve to different files.
+
 ### module.exports
 
 The `exports` object is created by the Module system. Sometimes this is not
@@ -173,17 +189,12 @@ x.js:
       module.exports = { a: "hello" };
     }, 0);
 
-y.js
+y.js:
 
     var x = require('./x');
     console.log(x.a);
 
 
-
-
-
-
-
 ### All Together...
 
 To get the exact filename that will be loaded when `require()` is called, use
@@ -192,11 +203,11 @@ the `require.resolve()` function.
 Putting together all of the above, here is the high-level algorithm
 in pseudocode of what require.resolve does:
 
-    require(X)
+    require(X) from module at path Y
     1. If X is a core module,
        a. return the core module
        b. STOP
-    2. If X begins with `./` or `/`,
+    2. If X begins with './' or '/' or '../'
        a. LOAD_AS_FILE(Y + X)
        b. LOAD_AS_DIRECTORY(Y + X)
     3. LOAD_NODE_MODULES(X, dirname(Y))
@@ -229,6 +240,7 @@ in pseudocode of what require.resolve does:
        a. if PARTS[I] = "node_modules" CONTINUE
        c. DIR = path join(PARTS[0 .. I] + "node_modules")
        b. DIRS = DIRS + DIR
+       c. let I = I - 1
     6. return DIRS
 
 ### Loading from the `require.paths` Folders
@@ -261,9 +273,7 @@ Global modules are lower priority than bundled dependencies.
 
 #### **Note:** Please Avoid Modifying `require.paths`
 
-For compatibility reasons, `require.paths` is still given first priority
-in the module lookup process.  However, it may disappear in a future
-release.
+`require.paths` may disappear in a future release.
 
 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
@@ -302,8 +312,23 @@ 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 it is a problem with those parts interact in ways
-that are difficult to predict.
+functionality, and those parts interact in ways that are difficult to
+predict.
+
+### Accessing the main module
+
+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
+directly by testing
+
+    require.main === module
+
+For a file `foo.js`, this will be `true` if run via `node foo.js`, but
+`false` if run by `require('./foo')`.
+
+Because `module` provides a `filename` property (normally equivalent to
+`__filename`), the entry point of the current application can be obtained
+by checking `require.main.filename`.
 
 ## Addenda: Package Manager Tips
 
diff --git a/doc/api/net.markdown b/doc/api/net.markdown
index 15cf8f452b..b25e2e684f 100644
--- a/doc/api/net.markdown
+++ b/doc/api/net.markdown
@@ -106,6 +106,12 @@ Start a server listening for connections on the given file descriptor.
 This file descriptor must have already had the `bind(2)` and `listen(2)` system
 calls invoked on it.
 
+#### 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()
 
 Stops the server from accepting new connections. This function is
@@ -115,8 +121,9 @@ event.
 
 #### server.address()
 
-Returns the bound address of the server as seen by the operating system.
-Useful to find which port was assigned when giving getting an OS-assigned 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.
+Returns an object with two properties, e.g. `{"address":"127.0.0.1", "port":2121}`
 
 Example:
 
@@ -298,6 +305,11 @@ data packet received and the first keepalive probe. Setting 0 for
 initialDelay will leave the value unchanged from the default
 (or previous) setting.
 
+#### 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}`
+
 #### socket.remoteAddress
 
 The string representation of the remote IP address. For example,
diff --git a/doc/index.html b/doc/index.html
index 42dcc5c172..ae2c76e4cc 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -215,6 +215,10 @@ server.listen(1337, "127.0.0.1");
 
     <div style="clear: both; font-size: 8pt">
       Copyright 2010 Joyent, Inc
+      <br/>
+      Node.js is a trademark of Joyent, Inc.
+      See the <a href="trademark-policy.pdf">trademark policy</a>
+      for more information.
     </div>
 
     <script type="text/javascript">
diff --git a/doc/trademark-policy.pdf b/doc/trademark-policy.pdf
new file mode 100644
index 0000000000..59a04b2915
--- /dev/null
+++ b/doc/trademark-policy.pdf