[8.x Backport] backport multiple commits to 8.x

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,6 +14,3 @@ Contributors guide: https://github.com/nodejs/node/blob/master/CONTRIBUTING.md
 - [ ] tests and/or benchmarks are included
 - [ ] documentation is changed or added
 - [ ] commit message follows [commit guidelines](https://github.com/nodejs/node/blob/master/doc/guides/contributing/pull-requests.md#commit-message-guidelines)
-
-##### Affected core subsystem(s)
-<!-- Provide affected core subsystem(s) (like doc, cluster, crypto, etc). -->

doc/api/addons.md

@@ -34,8 +34,9 @@ involving knowledge of several components and APIs :
 
  - Node.js includes a number of other statically linked libraries including
    OpenSSL. These other libraries are located in the `deps/` directory in the
-   Node.js source tree. Only the V8 and OpenSSL symbols are purposefully
-   re-exported by Node.js and may be used to various extents by Addons.
+   Node.js source tree. Only the libuv, OpenSSL, V8 and zlib symbols are
+   purposefully re-exported by Node.js and may be used to various extents by
+   Addons.
    See [Linking to Node.js' own dependencies][] for additional information.
 
 All of the following examples are available for [download][] and may

doc/api/assert.md

@@ -191,6 +191,11 @@ changes:
 Asserts that the function `block` does not throw an error. See
 [`assert.throws()`][] for more details.
 
+Please note: Using `assert.doesNotThrow()` is actually not useful because there
+is no benefit by catching an error and then rethrowing it. Instead, consider
+adding a comment next to the specific code path that should not throw and keep
+error messages as expressive as possible.
+
 When `assert.doesNotThrow()` is called, it will immediately call the `block`
 function.
 

doc/api/fs.md

@@ -2238,8 +2238,19 @@ changes:
 * `callback` {Function}
   * `err` {Error}
 
-Asynchronous rename(2). No arguments other than a possible exception are given
-to the completion callback.
+Asynchronously rename file at `oldPath` to the pathname provided
+as `newPath`. In the case that `newPath` already exists, it will
+be overwritten. No arguments other than a possible exception are
+given to the completion callback.
+
+See also: rename(2).
+
+```js
+fs.rename('oldFile.txt', 'newFile.txt', (err) => {
+  if (err) throw err;
+  console.log('Rename complete!');
+});
+```
 
 ## fs.renameSync(oldPath, newPath)
 <!-- YAML

doc/api/inspector.md

@@ -136,8 +136,34 @@ with an error. [`session.connect()`] will need to be called to be able to send
 messages again. Reconnected session will lose all inspector state, such as
 enabled agents or configured breakpoints.
 
+## Example usage
+
+### CPU Profiler
+
+Apart from the debugger, various V8 Profilers are available through the DevTools
+protocol. Here's a simple example showing how to use the [CPU profiler][]:
+
+```js
+const inspector = require('inspector');
+
+const session = new inspector.Session();
+session.connect();
+
+session.post('Profiler.enable', () => {
+  session.post('Profiler.start', () => {
+    // invoke business logic under measurement here...
+
+    // some time later...
+    session.post('Profiler.stop', ({ profile }) => {
+      // write profile to disk, upload, etc.
+    });
+  });
+});
+```
+
 
 [`session.connect()`]: #inspector_session_connect
 [`Debugger.paused`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#event-paused
 [`EventEmitter`]: events.html#events_class_eventemitter
 [Chrome DevTools Protocol Viewer]: https://chromedevtools.github.io/devtools-protocol/v8/
+[CPU Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/Profiler

doc/api/intl.md

@@ -19,6 +19,7 @@ programs. Some of them are:
 - [`require('buffer').transcode()`][]
 - More accurate [REPL][] line editing
 - [`require('util').TextDecoder`][]
+- [RegExp Unicode Property Escapes][]
 
 Node.js (and its underlying V8 engine) uses [ICU][] to implement these features
 in native C/C++ code. However, some of them require a very large ICU data file
@@ -55,6 +56,7 @@ option:
 | [`require('buffer').transcode()`][]     | none (function does not exist)    | full                         | full                   | full       |
 | [REPL][]                                | partial (inaccurate line editing) | full                         | full                   | full       |
 | [`require('util').TextDecoder`][]       | partial (basic encodings support) | partial/full (depends on OS) | partial (Unicode-only) | full       |
+| [RegExp Unicode Property Escapes][]     | none (invalid RegExp error)       | full                         | full                   | full       |
 
 *Note*: The "(not locale-aware)" designation denotes that the function carries
 out its operation just like the non-`Locale` version of the function, if one
@@ -207,6 +209,7 @@ to be helpful:
 [ECMA-402]: https://tc39.github.io/ecma402/
 [ICU]: http://icu-project.org/
 [REPL]: repl.html#repl_repl
+[RegExp Unicode Property Escapes]: https://github.com/tc39/proposal-regexp-unicode-property-escapes
 [Test262]: https://github.com/tc39/test262/tree/master/test/intl402
 [WHATWG URL parser]: url.html#url_the_whatwg_url_api
 [btest402]: https://github.com/srl295/btest402

doc/api/perf_hooks.md

@@ -181,7 +181,8 @@ added: v8.5.0
 
 * Returns: {number}
 
-Returns the current high resolution millisecond timestamp.
+Returns the current high resolution millisecond timestamp, where 0 represents
+the start of the current `node` process.
 
 ### performance.timeOrigin
 <!-- YAML
@@ -190,8 +191,8 @@ added: v8.5.0
 
 * {number}
 
-The [`timeOrigin`][] specifies the high resolution millisecond timestamp from
-which all performance metric durations are measured.
+The [`timeOrigin`][] specifies the high resolution millisecond timestamp at
+which the current `node` process began, measured in Unix time.
 
 ### performance.timerify(fn)
 <!-- YAML
@@ -302,7 +303,8 @@ added: v8.5.0
 * {number}
 
 The high resolution millisecond timestamp at which the Node.js process
-completed bootstrap.
+completed bootstrapping. If bootstrapping has not yet finished, the property
+has the value of -1.
 
 ### performanceNodeTiming.clusterSetupEnd
 <!-- YAML
@@ -311,7 +313,8 @@ added: v8.5.0
 
 * {number}
 
-The high resolution millisecond timestamp at which cluster processing ended.
+The high resolution millisecond timestamp at which cluster processing ended. If
+cluster processing has not yet ended, the property has the value of -1.
 
 ### performanceNodeTiming.clusterSetupStart
 <!-- YAML
@@ -321,6 +324,7 @@ added: v8.5.0
 * {number}
 
 The high resolution millisecond timestamp at which cluster processing started.
+If cluster processing has not yet started, the property has the value of -1.
 
 ### performanceNodeTiming.loopExit
 <!-- YAML
@@ -330,7 +334,8 @@ added: v8.5.0
 * {number}
 
 The high resolution millisecond timestamp at which the Node.js event loop
-exited.
+exited. If the event loop has not yet exited, the property has the value of -1.
+It can only have a value of not -1 in a handler of the [`'exit'`][] event.
 
 ### performanceNodeTiming.loopStart
 <!-- YAML
@@ -340,7 +345,8 @@ added: v8.5.0
 * {number}
 
 The high resolution millisecond timestamp at which the Node.js event loop
-started.
+started. If the event loop has not yet started (e.g., in the first tick of the
+main script), the property has the value of -1.
 
 ### performanceNodeTiming.moduleLoadEnd
 <!-- YAML
@@ -395,8 +401,9 @@ added: v8.5.0
 
 * {number}
 
-The high resolution millisecond timestamp at which third_party_main processing
-ended.
+The high resolution millisecond timestamp at which third\_party\_main
+processing ended. If third\_party\_main processing has not yet ended, the
+property has the value of -1.
 
 ### performanceNodeTiming.thirdPartyMainStart
 <!-- YAML
@@ -405,8 +412,9 @@ added: v8.5.0
 
 * {number}
 
-The high resolution millisecond timestamp at which third_party_main processing
-started.
+The high resolution millisecond timestamp at which third\_party\_main
+processing started. If third\_party\_main processing has not yet started, the
+property has the value of -1.
 
 ### performanceNodeTiming.v8Start
 <!-- YAML
@@ -642,6 +650,7 @@ obs.observe({ entryTypes: ['function'], buffered: true });
 require('some-module');
 ```
 
+[`'exit'`]: process.html#process_event_exit
 [`timeOrigin`]: https://w3c.github.io/hr-time/#dom-performance-timeorigin
 [Async Hooks]: async_hooks.html
 [W3C Performance Timeline]: https://w3c.github.io/performance-timeline/

doc/api/process.md

@@ -349,6 +349,9 @@ Signal events will be emitted when the Node.js process receives a signal. Please
 refer to signal(7) for a listing of standard POSIX signal names such as
 `SIGINT`, `SIGHUP`, etc.
 
+The signal handler will receive the signal's name (`'SIGINT'`,
+ `'SIGTERM'`, etc.) as the first argument.
+
 The name of each event will be the uppercase common name for the signal (e.g.
 `'SIGINT'` for `SIGINT` signals).
 
@@ -361,6 +364,14 @@ process.stdin.resume();
 process.on('SIGINT', () => {
   console.log('Received SIGINT. Press Control-D to exit.');
 });
+
+// Using a single function to handle multiple signals
+function handle(signal) {
+  console.log(`Received ${signal}`);
+}
+
+process.on('SIGINT', handle);
+process.on('SIGTERM', handle);
 ```
 
 * `SIGUSR1` is reserved by Node.js to start the [debugger][]. It's possible to
@@ -620,7 +631,17 @@ process.
 ```js
 console.log(`Current directory: ${process.cwd()}`);
 ```
+## process.debugPort
+<!-- YAML
+added: v0.7.2
+-->
+* {number}
+
+The port used by Node.js's debugger when enabled.
 
+```js
+process.debugPort = 5858;
+```
 ## process.disconnect()
 <!-- YAML
 added: v0.7.2

doc/api/stream.md

@@ -323,6 +323,9 @@ The `'unpipe'` event is emitted when the [`stream.unpipe()`][] method is called
 on a [Readable][] stream, removing this [Writable][] from its set of
 destinations.
 
+This is also emitted in case this [Writable][] stream emits an error when a
+[Readable][] stream pipes into it.
+
 ```js
 const writer = getWritableStreamSomehow();
 const reader = getReadableStreamSomehow();
@@ -931,10 +934,6 @@ readable.on('readable', () => {
 });
 ```
 
-In general, it is recommended that developers avoid the use of the `'readable'`
-event and the `readable.read()` method in favor of using either
-`readable.pipe()` or the `'data'` event.
-
 A Readable stream in object mode will always return a single item from
 a call to [`readable.read(size)`][stream-read], regardless of the value of the
 `size` argument.
@@ -1485,6 +1484,9 @@ the callback and passing the error as the first argument. This will cause an
 on how the stream is being used. Using the callback ensures consistent and
 predictable handling of errors.
 
+If a Readable stream pipes into a Writable stream when Writable emits an
+error, the Readable stream will be unpiped.
+
 ```js
 const { Writable } = require('stream');
 
@@ -1740,6 +1742,10 @@ class SourceWrapper extends Readable {
 *Note*: The `readable.push()` method is intended be called only by Readable
 Implementers, and only from within the `readable._read()` method.
 
+For streams not operating in object mode, if the `chunk` parameter of
+`readable.push()` is `undefined`, it will be treated as empty string or
+buffer. See [`readable.push('')`][] for more information.
+
 #### Errors While Reading
 
 It is recommended that errors occurring during the processing of the
@@ -2259,6 +2265,7 @@ contain multi-byte characters.
 [`stream.uncork()`]: #stream_writable_uncork
 [`stream.unpipe()`]: #stream_readable_unpipe_destination
 [`stream.wrap()`]: #stream_readable_wrap_stream
+[`readable.push('')`]: #stream_readable_push
 [`writable.cork()`]: #stream_writable_cork
 [`writable.uncork()`]: #stream_writable_uncork
 [`zlib.createDeflate()`]: zlib.html#zlib_zlib_createdeflate_options

doc/api/url.md

@@ -971,6 +971,20 @@ changes:
 The `url.format()` method returns a formatted URL string derived from
 `urlObject`.
 
+```js
+url.format({
+  protocol: 'https',
+  hostname: 'example.com',
+  pathname: '/some/path',
+  query: {
+    page: 1,
+    format: 'json'
+  }
+});
+
+// => 'https://example.com/some/path?page=1&format=json'
+```
+
 If `urlObject` is not an object or a string, `url.format()` will throw a
 [`TypeError`][].
 

doc/guides/contributing/pull-requests.md

@@ -401,10 +401,10 @@ seem unfamiliar, refer to this
 All Pull Requests require "sign off" in order to land. Whenever a contributor
 reviews a Pull Request they may find specific details that they would like to
 see changed or fixed. These may be as simple as fixing a typo, or may involve
-substantive changes to the code you have written. In general, such requests
-are intended to be helpful, but at times may come across as abrupt or unhelpful,
-especially requests to change things that do not include concrete suggestions
-on *how* to change them.
+substantive changes to the code you have written. While such requests are
+intended to be helpful, they may come across as abrupt or unhelpful, especially
+requests to change things that do not include concrete suggestions on *how* to
+change them.
 
 Try not to be discouraged. If you feel that a particular review is unfair,
 say so, or contact one of the other contributors in the project and seek their
@@ -610,8 +610,8 @@ however, will stay intact on the Pull Request page.
 For the size of "one logical change",
 [0b5191f](https://github.com/nodejs/node/commit/0b5191f15d0f311c804d542b67e2e922d98834f8)
 can be a good example. It touches the implementation, the documentation,
-and the tests, but is still one logical change. In general, the tests should
-always pass when each individual commit lands on the master branch.
+and the tests, but is still one logical change. All tests should always pass
+when each individual commit lands on the master branch.
 
 ### Getting Approvals for Your Pull Request
 

doc/guides/maintaining-V8.md

@@ -3,15 +3,14 @@
 ## Background
 
 V8 follows the Chromium release schedule. The support horizon for Chromium is
-very different from the support horizon that Node.js needs to provide to its
-users. As a result Node.js needs to support a version of V8 for quite a bit
-longer than what upstream needs to support. Since V8 doesn't have an LTS
-supported branch, there is no official process around how the V8 branches in
-Node.js are maintained.
-
-This document attempts to document the current processes and proposes a workflow
-for maintaining the V8 branches in Node.js LTS and Current releases and how the
-Node.js and V8 teams at Google can help.
+different compared to the support horizon for Node.js. As a result, Node.js
+needs to support multiple versions of V8 longer than what upstream needs
+to support. V8 branches in Node.js lack of an official maintenance process due
+to a missing LTS supported branch.
+
+This document attempts to outline the current maintenance processes, proposes
+a workflow for maintaining the V8 branches in both Node.js LTS and current
+releases, and discusses how the Node.js and V8 teams at Google can help.
 
 ## V8 Release Schedule
 

lib/_http_client.js

@@ -350,7 +350,7 @@ function socketCloseListener() {
   req.emit('close');
   if (req.res && req.res.readable) {
     // Socket closed before we emitted 'end' below.
-    req.res.emit('aborted');
+    if (!req.res.complete) req.res.emit('aborted');
     var res = req.res;
     res.on('end', function() {
       res.emit('close');