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

Merge 1b0d979 as of 2018-01-17
This commit was automatically generated. For any problems, please contact jackhorton

Reviewed-By: Jack Horton <jahorto@microsoft.com>

Author: jackhorton

CPP_STYLE_GUIDE.md

@@ -20,7 +20,8 @@
 * [Others](#others)
   * [Type casting](#type-casting)
   * [Do not include `*.h` if `*-inl.h` has already been included](#do-not-include-h-if--inlh-has-already-been-included)
-  * [Avoid throwing JavaScript errors in nested C++ methods](#avoid-throwing-javascript-errors-in-nested-c-methods)
+  * [Avoid throwing JavaScript errors in C++ methods](#avoid-throwing-javascript-errors-in-c)
+    * [Avoid throwing JavaScript errors in nested C++ methods](#avoid-throwing-javascript-errors-in-nested-c-methods)
 
 Unfortunately, the C++ linter (based on
 [Google’s `cpplint`](https://github.com/google/styleguide)), which can be run
@@ -213,12 +214,65 @@ instead of
 #include "util-inl.h"
 ```
 
-## Avoid throwing JavaScript errors in nested C++ methods
+## Avoid throwing JavaScript errors in C++
 
-If you need to throw JavaScript errors from a C++ binding method, try to do it
-at the top level and not inside of nested calls.
+When there is a need to throw errors from a C++ binding method, try to
+return the data necessary for constructing the errors to JavaScript,
+then construct and throw the errors [using `lib/internal/errors.js`][errors].
 
-A lot of code inside Node.js is written so that typechecking etc. is performed
-in JavaScript.
+Note that in general, type-checks on arguments should be done in JavaScript
+before the arguments are passed into C++. Then in the C++ binding, simply using
+`CHECK` assertions to guard against invalid arguments should be enough.
+
+If the return value of the binding cannot be used to signal failures or return
+the necessary data for constructing errors in JavaScript, pass a context object
+to the binding and put the necessary data inside in C++. For example:
+
+```cpp
+void Foo(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  // Let the JavaScript handle the actual type-checking,
+  // only assertions are placed in C++
+  CHECK_EQ(args.Length(), 2);
+  CHECK(args[0]->IsString());
+  CHECK(args[1]->IsObject());
+
+  int err = DoSomethingWith(args[0].As<String>());
+  if (err) {
+    // Put the data inside the error context
+    Local<Object> ctx = args[1].As<Object>();
+    Local<String> key = FIXED_ONE_BYTE_STRING(env->isolate(), "code");
+    ctx->Set(env->context(), key, err).FromJust();
+  } else {
+    args.GetReturnValue().Set(something_to_return);
+  }
+}
+
+// In the initialize function
+env->SetMethod(target, "foo", Foo);
+```
+
+```js
+exports.foo = function(str) {
+  // Prefer doing the type-checks in JavaScript
+  if (typeof str !== 'string') {
+    throw new errors.TypeError('ERR_INVALID_ARG_TYPE', 'str', 'string');
+  }
+
+  const ctx = {};
+  const result = binding.foo(str, ctx);
+  if (ctx.code !== undefined) {
+    throw new errors.Error('ERR_ERROR_NAME', ctx.code);
+  }
+  return result;
+};
+```
+
+### Avoid throwing JavaScript errors in nested C++ methods
+
+When you have to throw the errors from C++, try to do it at the top level and
+not inside of nested calls.
 
 Using C++ `throw` is not allowed.
+
+[errors]: https://github.com/nodejs/node/blob/master/doc/guides/using-internal-errors.md

Makefile

@@ -1020,57 +1020,13 @@ ifeq ($(XZ), 0)
 	ssh $(STAGINGSERVER) "touch nodejs/$(DISTTYPEDIR)/$(FULLVERSION)/$(TARNAME)-$(OSTYPE)-$(ARCH).tar.xz.done"
 endif
 
-.PHONY: bench-net
-bench-net: all
-	@$(NODE) benchmark/run.js net
-
-bench-crypto: all
-	@$(NODE) benchmark/run.js crypto
-
-.PHONY: bench-tls
-bench-tls: all
-	@$(NODE) benchmark/run.js tls
-
-.PHONY: bench-http
-bench-http: all
-	@$(NODE) benchmark/run.js http
-
-.PHONY: bench-fs
-bench-fs: all
-	@$(NODE) benchmark/run.js fs
-
-.PHONY: bench-misc
-bench-misc: benchmark/misc/function_call/build/Release/binding.node
-	@$(NODE) benchmark/run.js misc
-
-.PHONY: bench-array
-bench-array: all
-	@$(NODE) benchmark/run.js arrays
-
-.PHONY: bench-buffer
-bench-buffer: all
-	@$(NODE) benchmark/run.js buffers
-
-bench-url: all
-	@$(NODE) benchmark/run.js url
-
-bench-events: all
-	@$(NODE) benchmark/run.js events
-
-bench-util: all
-	@$(NODE) benchmark/run.js util
-
-bench-dgram: all
-	@$(NODE) benchmark/run.js dgram
-
 .PHONY: bench-all
-bench-all: bench bench-misc bench-array bench-buffer bench-url bench-events bench-dgram bench-util
+bench-all:
+	@echo "Please use benchmark/run.js or benchmark/compare.js to run the benchmarks."
 
 .PHONY: bench
-bench: bench-net bench-http bench-fs bench-tls
-
-.PHONY: bench-ci
-bench-ci: bench
+bench:
+	@echo "Please use benchmark/run.js or benchmark/compare.js to run the benchmarks."
 
 .PHONY: lint-md-clean
 lint-md-clean:

configure

@@ -908,7 +908,6 @@ def configure_node(o):
     configure_mips(o)
 
   if flavor == 'aix':
-    o['variables']['node_core_target_name'] = 'node_base'
     o['variables']['node_target_type'] = 'static_library'
 
   if target_arch in ('x86', 'x64', 'ia32', 'x32'):
@@ -1018,6 +1017,13 @@ def configure_node(o):
   else:
     o['variables']['coverage'] = 'false'
 
+  if options.shared:
+    o['variables']['node_target_type'] = 'shared_library'
+  elif options.enable_static:
+    o['variables']['node_target_type'] = 'static_library'
+  else:
+    o['variables']['node_target_type'] = 'executable'
+
 def configure_library(lib, output):
   shared_lib = 'shared_' + lib
   output['variables']['node_' + shared_lib] = b(getattr(options, shared_lib))
@@ -1539,6 +1545,7 @@ config = {
   'BUILDTYPE': 'Debug' if options.debug else 'Release',
   'USE_XCODE': str(int(options.use_xcode or 0)),
   'PYTHON': sys.executable,
+  'NODE_TARGET_TYPE': variables['node_target_type'],
 }
 
 if options.prefix:

doc/api/assert.md

@@ -645,6 +645,11 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
 ## assert.ok(value[, message])
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/17581
+    description: assert.ok() will throw a `ERR_MISSING_ARGS` error.
+                 Use assert.fail() instead.
 -->
 * `value` {any}
 * `message` {any}
@@ -658,19 +663,50 @@ parameter is `undefined`, a default error message is assigned. If the `message`
 parameter is an instance of an [`Error`][] then it will be thrown instead of the
 `AssertionError`.
 
+Be aware that in the `repl` the error message will be different to the one
+thrown in a file! See below for further details.
+
 ```js
 const assert = require('assert').strict;
 
 assert.ok(true);
 // OK
 assert.ok(1);
 // OK
-assert.ok(false);
-// throws "AssertionError: false == true"
-assert.ok(0);
-// throws "AssertionError: 0 == true"
+
 assert.ok(false, 'it\'s false');
 // throws "AssertionError: it's false"
+
+// In the repl:
+assert.ok(typeof 123 === 'string');
+// throws:
+// "AssertionError: false == true
+
+// In a file (e.g. test.js):
+assert.ok(typeof 123 === 'string');
+// throws:
+// "AssertionError: The expression evaluated to a falsy value:
+//
+//   assert.ok(typeof 123 === 'string')
+
+assert.ok(false);
+// throws:
+// "AssertionError: The expression evaluated to a falsy value:
+//
+//   assert.ok(false)
+
+assert.ok(0);
+// throws:
+// "AssertionError: The expression evaluated to a falsy value:
+//
+//   assert.ok(0)
+
+// Using `assert()` works the same:
+assert(0);
+// throws:
+// "AssertionError: The expression evaluated to a falsy value:
+//
+//   assert(0)
 ```
 
 ## assert.strictEqual(actual, expected[, message])

doc/api/buffer.md

@@ -511,14 +511,18 @@ console.log(buf2.toString());
 <!-- YAML
 added: v5.10.0
 changes:
-  - version: v8.9.3
-    pr-url: https://github.com/nodejs/node/pull/17428
-    description: Specifying an invalid string for `fill` now results in a
-                 zero-filled buffer.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/18129
+    description: Attempting to fill a non-zero length buffer with a zero length
+                 buffer triggers a thrown exception.
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/17427
     description: Specifying an invalid string for `fill` triggers a thrown
                  exception.
+  - version: v8.9.3
+    pr-url: https://github.com/nodejs/node/pull/17428
+    description: Specifying an invalid string for `fill` now results in a
+                 zero-filled buffer.
 -->
 
 * `size` {integer} The desired length of the new `Buffer`.
@@ -1224,13 +1228,17 @@ console.log(buf1.equals(buf3));
 <!-- YAML
 added: v0.5.0
 changes:
-  - version: v5.7.0
-    pr-url: https://github.com/nodejs/node/pull/4935
-    description: The `encoding` parameter is supported now.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/18129
+    description: Attempting to fill a non-zero length buffer with a zero length
+                 buffer triggers a thrown exception.
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/17427
     description: Specifying an invalid string for `value` triggers a thrown
                  exception.
+  - version: v5.7.0
+    pr-url: https://github.com/nodejs/node/pull/4935
+    description: The `encoding` parameter is supported now.
 -->
 
 * `value` {string|Buffer|integer} The value to fill `buf` with.

doc/api/deprecations.md

@@ -788,7 +788,6 @@ The AsyncHooks Sensitive API was never documented and had various of minor
 issues, see https://github.com/nodejs/node/issues/15572. Use the `AsyncResource`
 API instead.
 
-
 <a id="DEP0086"></a>
 ### DEP0086: Remove runInAsyncIdScope
 

doc/api/errors.md

@@ -1328,6 +1328,18 @@ While using `N-API`, `Constructor.prototype` was not an object.
 While calling `napi_create_dataview()`, a given `offset` was outside the bounds
 of the dataview or `offset + length` was larger than a length of given `buffer`.
 
+<a id="ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT"></a>
+### ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT
+
+While calling `napi_create_typedarray()`, the provided `offset` was not a
+multiple of the element size.
+
+<a id="ERR_NAPI_INVALID_TYPEDARRAY_LENGTH"></a>
+### ERR_NAPI_INVALID_TYPEDARRAY_LENGTH
+
+While calling `napi_create_typedarray()`, `(length * size_of_element) +
+byte_offset` was larger than the length of given `buffer`.
+
 <a id="ERR_NO_CRYPTO"></a>
 ### ERR_NO_CRYPTO
 
@@ -1530,6 +1542,12 @@ a hostname in the first parameter.
 An excessive amount of TLS renegotiations is detected, which is a potential
 vector for denial-of-service attacks.
 
+<a id="ERR_TLS_SNI_FROM_SERVER"></a>
+### ERR_TLS_SNI_FROM_SERVER
+
+An attempt was made to issue Server Name Indication from a TLS server-side
+socket, which is only valid from a client.
+
 <a id="ERR_TLS_RENEGOTIATION_DISABLED"></a>
 ### ERR_TLS_RENEGOTIATION_DISABLED
 

doc/api/http2.md

@@ -919,7 +919,7 @@ added: v8.4.0
 -->
 
 * code {number} Unsigned 32-bit integer identifying the error code. **Default:**
-  `http2.constant.NGHTTP2_NO_ERROR` (`0x00`)
+  `http2.constants.NGHTTP2_NO_ERROR` (`0x00`)
 * `callback` {Function} An optional function registered to listen for the
   `'close'` event.
 * Returns: {undefined}

doc/api/stream.md

@@ -1505,7 +1505,7 @@ added: v8.0.0
   argument.
 
 The `_destroy()` method is called by [`writable.destroy()`][writable-destroy].
-It can be overriden by child classes but it **must not** be called directly.
+It can be overridden by child classes but it **must not** be called directly.
 
 #### writable.\_final(callback)
 <!-- YAML
@@ -1727,7 +1727,7 @@ added: v8.0.0
   argument.
 
 The `_destroy()` method is called by [`readable.destroy()`][readable-destroy].
-It can be overriden by child classes but it **must not** be called directly.
+It can be overridden by child classes but it **must not** be called directly.
 
 #### readable.push(chunk[, encoding])
 <!-- YAML

doc/guides/maintaining-the-build-files.md

@@ -15,7 +15,7 @@ There are three main build files that may be directly run when building Node.js:
   Makefile mentioned below is maintained separately by humans). For a detailed
   guide on this script, see [configure](#configure).
 - `vcbuild.bat`: A Windows Batch Script that locates build tools, provides a
-  subset of the targets avilable in the [Makefile](#makefile), and a few targets
+  subset of the targets available in the [Makefile](#makefile), and a few targets
   of its own. For a detailed guide on this script, see
   [vcbuild.bat](#vcbuild.bat).
 - `Makefile`: A Makefile that can be run with GNU Make. It provides a set of