meta: merge node/master into node-chakracore/master

Merge c589561 as of 2017-12-02
This commit was automatically generated. For any problems, please contact jackhorton

Reviewed-By: Taylor Woll <[email protected]>

Author: chakrabot

Diff for: COLLABORATOR_GUIDE.md

@@ -33,7 +33,7 @@
     - [How is an LTS release cut?](#how-is-an-lts-release-cut)
 
 This document contains information for Collaborators of the Node.js
-project regarding maintaining the code, documentation and issues.
+project regarding maintaining the code, documentation, and issues.
 
 Collaborators should be familiar with the guidelines for new
 contributors in [CONTRIBUTING.md](./CONTRIBUTING.md) and also

Diff for: CONTRIBUTING.md

@@ -74,7 +74,7 @@ for any individual to *act* in such a manner that is not in violation of the
 strict letter of the Code of Conduct guidelines while still going completely
 against the spirit of what that Code is intended to accomplish.
 
-Open, diverse and inclusive communities live and die on the basis of trust.
+Open, diverse, and inclusive communities live and die on the basis of trust.
 Contributors can disagree with one another so long as they trust that those
 disagreements are in good faith and everyone is working towards a common goal.
 
@@ -177,7 +177,7 @@ Node.js changed that broke the module.
 Once an issue has been opened, it is not uncommon for there to be discussion
 around it. Some contributors may have differing opinions about the issue,
 including whether the behavior being seen is a bug or a feature. This discussion
-is part of the process and should be kept focused, helpful and professional.
+is part of the process and should be kept focused, helpful, and professional.
 
 Short, clipped responses—that provide neither additional context nor supporting
 detail—are not helpful or professional. To many, such responses are simply

Diff for: CPP_STYLE_GUIDE.md

@@ -7,7 +7,7 @@
 * [4 spaces of indentation for statement continuations](#4-spaces-of-indentation-for-statement-continuations)
 * [Align function arguments vertically](#align-function-arguments-vertically)
 * [Initialization lists](#initialization-lists)
-* [CamelCase for methods, functions and classes](#camelcase-for-methods-functions-and-classes)
+* [CamelCase for methods, functions, and classes](#camelcase-for-methods-functions-and-classes)
 * [snake\_case for local variables and parameters](#snake_case-for-local-variables-and-parameters)
 * [snake\_case\_ for private class fields](#snake_case_-for-private-class-fields)
 * [Space after `template`](#space-after-template)
@@ -87,7 +87,7 @@ HandleWrap::HandleWrap(Environment* env,
       handle_(handle) {
 ```
 
-## CamelCase for methods, functions and classes
+## CamelCase for methods, functions, and classes
 
 Exceptions are simple getters/setters, which are named `property_name()` and
 `set_property_name()`, respectively.

Diff for: doc/STYLE_GUIDE.md

@@ -14,7 +14,7 @@
   human reviewers.
 * American English spelling is preferred. "Capitalize" vs. "Capitalise",
   "color" vs. "colour", etc.
-* Though controversial, the [Oxford comma][] is preferred for clarity's sake.
+* Use [serial commas][].
 * Generally avoid personal pronouns in reference documentation ("I", "you",
   "we").
   * Pronouns are acceptable in more colloquial documentation, like guides.
@@ -75,6 +75,6 @@
 
 [Em dashes]: https://en.wikipedia.org/wiki/Dash#Em_dash
 [Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
-[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma
+[serial commas]: https://en.wikipedia.org/wiki/Serial_comma
 [The New York Times Manual of Style and Usage]: https://en.wikipedia.org/wiki/The_New_York_Times_Manual_of_Style_and_Usage
 [plugin]: http://editorconfig.org/#download

Diff for: doc/api/addons.md

@@ -20,7 +20,7 @@ involving knowledge of several components and APIs :
    threads and all of the asynchronous behaviors of the platform. It also
    serves as a cross-platform abstraction library, giving easy, POSIX-like
    access across all major operating systems to many common system tasks, such
-   as interacting with the filesystem, sockets, timers and system events. libuv
+   as interacting with the filesystem, sockets, timers, and system events. libuv
    also provides a pthreads-like threading abstraction that may be used to
    power more sophisticated asynchronous Addons that need to move beyond the
    standard event loop. Addon authors are encouraged to think about how to

Diff for: doc/api/buffer.md

@@ -154,7 +154,7 @@ changes:
 -->
 
 `Buffer` instances are commonly used to represent sequences of encoded characters
-such as UTF-8, UCS2, Base64 or even Hex-encoded data. It is possible to
+such as UTF-8, UCS2, Base64, or even Hex-encoded data. It is possible to
 convert back and forth between `Buffer` instances and ordinary JavaScript strings
 by using an explicit character encoding.
 

Diff for: doc/api/child_process.md

@@ -628,7 +628,7 @@ pipes between the parent and child. The value is one of the following:
 5. Positive integer - The integer value is interpreted as a file descriptor
    that is is currently open in the parent process. It is shared with the child
    process, similar to how {Stream} objects can be shared.
-6. `null`, `undefined` - Use default value. For stdio fds 0, 1 and 2 (in other
+6. `null`, `undefined` - Use default value. For stdio fds 0, 1, and 2 (in other
    words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the
    default is `'ignore'`.
 

Diff for: doc/api/crypto.md

@@ -5,7 +5,7 @@
 > Stability: 2 - Stable
 
 The `crypto` module provides cryptographic functionality that includes a set of
-wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign and verify functions.
+wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify functions.
 
 Use `require('crypto')` to access this module.
 
@@ -651,7 +651,11 @@ added: v0.11.14
 changes:
   - version: v6.0.0
     pr-url: https://github.com/nodejs/node/pull/5522
-    description: The default `inputEncoding` changed from `binary` to `utf8`.
+    description: The default `inputEncoding` changed from `binary` to `utf8`
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/16849
+    description: Changed error format to better support invalid public key
+                 error
 -->
 - `otherPublicKey` {string | Buffer | TypedArray | DataView}
 - `inputEncoding` {string}
@@ -668,6 +672,12 @@ provided, `otherPublicKey` is expected to be a [`Buffer`][], `TypedArray`, or
 If `outputEncoding` is given a string will be returned; otherwise a
 [`Buffer`][] is returned.
 
+`ecdh.computeSecret` will throw an
+`ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY` error when `otherPublicKey`
+lies outside of the elliptic curve. Since `otherPublicKey` is
+usually supplied from a remote user over an insecure network,
+its recommended for developers to handle this exception accordingly.
+
 ### ecdh.generateKeys([encoding[, format]])
 <!-- YAML
 added: v0.11.14
@@ -1254,7 +1264,7 @@ In line with OpenSSL's recommendation to use pbkdf2 instead of
 [`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on
 their own using [`crypto.pbkdf2()`][] and to use [`crypto.createCipheriv()`][]
 to create the `Cipher` object. Users should not use ciphers with counter mode
-(e.g. CTR, GCM or CCM) in `crypto.createCipher()`. A warning is emitted when
+(e.g. CTR, GCM, or CCM) in `crypto.createCipher()`. A warning is emitted when
 they are used in order to avoid the risk of IV reuse that causes
 vulnerabilities. For the case when IV is reused in GCM, see [Nonce-Disrespecting
 Adversaries][] for details.
@@ -2034,7 +2044,7 @@ Based on the recommendations of [NIST SP 800-131A][]:
 
 - MD5 and SHA-1 are no longer acceptable where collision resistance is
   required such as digital signatures.
-- The key used with RSA, DSA and DH algorithms is recommended to have
+- The key used with RSA, DSA, and DH algorithms is recommended to have
   at least 2048 bits and that of the curve of ECDSA and ECDH at least
   224 bits, to be safe to use for several years.
 - The DH groups of `modp1`, `modp2` and `modp5` have a key size

Diff for: doc/api/errors.md

@@ -676,6 +676,13 @@ of OpenSSL being used.
 An invalid value for the `format` argument was passed to the `crypto.ECDH()`
 class `getPublicKey()` method.
 
+<a id="ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY"></a>
+### ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY
+
+An invalid value for the `key` argument has been passed to the
+`crypto.ECDH()` class `computeSecret()` method. It means that the public
+key lies outside of the elliptic curve.
+
 <a id="ERR_CRYPTO_ENGINE_UNKNOWN"></a>
 ### ERR_CRYPTO_ENGINE_UNKNOWN
 

Diff for: doc/api/fs.md

@@ -1881,7 +1881,7 @@ Linux, and Windows, an error will be returned. On FreeBSD, a representation
 of the directory's contents will be returned.
 
 ```js
-// macOS, Linux and Windows
+// macOS, Linux, and Windows
 fs.readFile('<directory>', (err, data) => {
   // => [Error: EISDIR: illegal operation on a directory, read <directory>]
 });
@@ -1929,7 +1929,7 @@ string. Otherwise it returns a buffer.
 behavior of `fs.readFileSync()` is platform-specific.
 
 ```js
-// macOS, Linux and Windows
+// macOS, Linux, and Windows
 fs.readFileSync('<directory>');
 // => [Error: EISDIR: illegal operation on a directory, read <directory>]
 
@@ -3043,7 +3043,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's
   </tr>
   <tr>
     <td><code>S_IRWXU</code></td>
-    <td>File mode indicating readable, writable and executable by owner.</td>
+    <td>File mode indicating readable, writable, and executable by owner.</td>
   </tr>
   <tr>
     <td><code>S_IRUSR</code></td>
@@ -3059,7 +3059,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's
   </tr>
   <tr>
     <td><code>S_IRWXG</code></td>
-    <td>File mode indicating readable, writable and executable by group.</td>
+    <td>File mode indicating readable, writable, and executable by group.</td>
   </tr>
   <tr>
     <td><code>S_IRGRP</code></td>
@@ -3075,7 +3075,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's
   </tr>
   <tr>
     <td><code>S_IRWXO</code></td>
-    <td>File mode indicating readable, writable and executable by others.</td>
+    <td>File mode indicating readable, writable, and executable by others.</td>
   </tr>
   <tr>
     <td><code>S_IROTH</code></td>

Diff for: doc/api/http2.md

@@ -1264,7 +1264,7 @@ added: v8.4.0
 
 In `Http2Server`, there is no `'clientError'` event as there is in
 HTTP1. However, there are `'socketError'`, `'sessionError'`,  and
-`'streamError'`, for error happened on the socket, session or stream
+`'streamError'`, for error happened on the socket, session, or stream
 respectively.
 
 #### Event: 'socketError'
@@ -1857,7 +1857,7 @@ performance.
 There are several types of error conditions that may arise when using the
 `http2` module:
 
-Validation Errors occur when an incorrect argument, option or setting value is
+Validation Errors occur when an incorrect argument, option, or setting value is
 passed in. These will always be reported by a synchronous `throw`.
 
 State Errors occur when an action is attempted at an incorrect time (for
@@ -2229,7 +2229,7 @@ added: v8.4.0
 * {net.Socket|tls.TLSSocket}
 
 Returns a Proxy object that acts as a `net.Socket` (or `tls.TLSSocket`) but
-applies getters, setters and methods based on HTTP/2 logic.
+applies getters, setters, and methods based on HTTP/2 logic.
 
 `destroyed`, `readable`, and `writable` properties will be retrieved from and
 set on `request.stream`.
@@ -2601,7 +2601,7 @@ added: v8.4.0
 * {net.Socket|tls.TLSSocket}
 
 Returns a Proxy object that acts as a `net.Socket` (or `tls.TLSSocket`) but
-applies getters, setters and methods based on HTTP/2 logic.
+applies getters, setters, and methods based on HTTP/2 logic.
 
 `destroyed`, `readable`, and `writable` properties will be retrieved from and
 set on `response.stream`.

Diff for: doc/api/n-api.md

@@ -2257,7 +2257,7 @@ following forms:
 - Named: a simple UTF8-encoded string
 - Integer-Indexed: an index value represented by `uint32_t`
 - JavaScript value: these are represented in N-API by `napi_value`. This can
-be a `napi_value` representing a String, Number or Symbol.
+be a `napi_value` representing a String, Number, or Symbol.
 
 N-API values are represented by the type `napi_value`.
 Any N-API call that requires a JavaScript value takes in a `napi_value`.
@@ -3471,8 +3471,8 @@ napi_status napi_get_node_version(napi_env env,
 
 Returns `napi_ok` if the API succeeded.
 
-This function fills the `version` struct with the major, minor and patch version
-of Node that is currently running, and the `release` field with the
+This function fills the `version` struct with the major, minor, and patch
+version of Node.js that is currently running, and the `release` field with the
 value of [`process.release.name`][`process.release`].
 
 The returned buffer is statically allocated and does not need to be freed.

Diff for: doc/api/os.md

@@ -453,7 +453,7 @@ The following signal constants are exported by `os.constants.signals`:
   <tr>
     <td><code>SIGILL</code></td>
     <td>Sent to a process to notify that it has attempted to perform an illegal,
-    malformed, unknown or privileged instruction.</td>
+    malformed, unknown, or privileged instruction.</td>
   </tr>
   <tr>
     <td><code>SIGTRAP</code></td>

Diff for: doc/api/process.md

@@ -275,7 +275,7 @@ A process warning is similar to an error in that it describes exceptional
 conditions that are being brought to the user's attention. However, warnings
 are not part of the normal Node.js and JavaScript error handling flow.
 Node.js can emit warnings whenever it detects bad coding practices that could
-lead to sub-optimal application performance, bugs or security vulnerabilities.
+lead to sub-optimal application performance, bugs, or security vulnerabilities.
 
 The listener function is called with a single `warning` argument whose value is
 an `Error` object. There are three key properties that describe the warning:
@@ -1307,7 +1307,7 @@ objects managed by V8. `rss`, Resident Set Size, is the amount of space
 occupied in the main memory device (that is a subset of the total allocated
 memory) for the process, which includes the _heap_, _code segment_ and _stack_.
 
-The _heap_ is where objects, strings and closures are stored. Variables are
+The _heap_ is where objects, strings, and closures are stored. Variables are
 stored in the _stack_ and the actual JavaScript code resides in the
 _code segment_.
 

Diff for: doc/api/tls.md

@@ -104,7 +104,7 @@ not required and a default ECDHE curve will be used. The `ecdhCurve` property
 can be used when creating a TLS Server to specify the list of names of supported
 curves to use, see [`tls.createServer()`] for more info.
 
-### ALPN, NPN and SNI
+### ALPN, NPN, and SNI
 
 <!-- type=misc -->
 
@@ -742,6 +742,55 @@ and their processing can be delayed due to packet loss or reordering. However,
 smaller fragments add extra TLS framing bytes and CPU overhead, which may
 decrease overall server throughput.
 
+## tls.checkServerIdentity(host, cert)
+<!-- YAML
+added: v0.8.4
+-->
+
+* `host` {string} The hostname to verify the certificate against
+* `cert` {Object} An object representing the peer's certificate. The returned
+  object has some properties corresponding to the fields of the certificate.
+
+Verifies the certificate `cert` is issued to host `host`.
+
+Returns {Error} object, populating it with the reason, host and cert on failure.
+On success, returns {undefined}.
+
+*Note*: This function can be overwritten by providing alternative function
+as part of the `options.checkServerIdentity` option passed to `tls.connect()`.
+The overwriting function can call `tls.checkServerIdentity()` of course, to augment
+the checks done with additional verification.
+
+*Note*: This function is only called if the certificate passed all other checks, such as
+being issued by trusted CA (`options.ca`).
+
+The cert object contains the parsed certificate and will have a structure similar to:
+
+```text
+{ subject:
+   { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
+     CN: '*.nodejs.org' },
+  issuer:
+   { C: 'GB',
+     ST: 'Greater Manchester',
+     L: 'Salford',
+     O: 'COMODO CA Limited',
+     CN: 'COMODO RSA Domain Validation Secure Server CA' },
+  subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
+  infoAccess:
+   { 'CA Issuers - URI':
+      [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
+     'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
+  modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
+  exponent: '0x10001',
+  valid_from: 'Aug 14 00:00:00 2017 GMT',
+  valid_to: 'Nov 20 23:59:59 2019 GMT',
+  fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
+  ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
+  serialNumber: '66593D57F20CBC573E433381B5FEC280',
+  raw: <Buffer ....> }
+```
+
 ## tls.connect(options[, callback])
 <!-- YAML
 added: v0.11.3
@@ -792,9 +841,11 @@ changes:
   * `servername`: {string} Server name for the SNI (Server Name Indication) TLS
     extension.
   * `checkServerIdentity(servername, cert)` {Function} A callback function
-    to be used when checking the server's hostname against the certificate.
-    This should throw an error if verification fails. The method should return
-    `undefined` if the `servername` and `cert` are verified.
+    to be used (instead of the builtin `tls.checkServerIdentity()` function)
+    when checking the server's hostname (or the provided `servername` when
+    explicitly set) against the certificate. This should return an {Error} if
+    verification fails. The method should return `undefined` if the `servername`
+    and `cert` are verified.
   * `session` {Buffer} A `Buffer` instance, containing TLS session.
   * `minDHSize` {number} Minimum size of the DH parameter in bits to accept a
     TLS connection. When a server offers a DH parameter with a size less

Diff for: doc/api/util.md

@@ -350,6 +350,24 @@ changes:
 The `util.inspect()` method returns a string representation of `object` that is
 primarily useful for debugging. Additional `options` may be passed that alter
 certain aspects of the formatted string.
+`util.inspect()` will use the constructor's name and/or `@@toStringTag` to make an
+identifiable tag for an inspected value.
+
+```js
+class Foo {
+  get [Symbol.toStringTag]() {
+    return 'bar';
+  }
+}
+
+class Bar {}
+
+const baz = Object.create(null, { [Symbol.toStringTag]: { value: 'foo' } });
+
+util.inspect(new Foo()); // 'Foo [bar] {}'
+util.inspect(new Bar()); // 'Bar {}'
+util.inspect(baz);       // '[foo] {}'
+```
 
 The following example inspects all properties of the `util` object: