diff --git a/.eslintrc.yaml b/.eslintrc.yaml index 713e2f1c93d08d..7db9a842792212 100644 --- a/.eslintrc.yaml +++ b/.eslintrc.yaml @@ -62,17 +62,21 @@ rules: no-new-require: 2 no-path-concat: 2 no-restricted-modules: [2, sys, _linklist] - no-restricted-properties: [2, { - object: assert, - property: deepEqual, - message: Please use assert.deepStrictEqual(). - }, { - property: __defineGetter__, - message: __defineGetter__ is deprecated. - }, { - property: __defineSetter__, - message: __defineSetter__ is deprecated. - }] + no-restricted-properties: + - 2 + - object: assert + property: deepEqual + message: Use assert.deepStrictEqual(). + - object: assert + property: equal + message: Use assert.strictEqual() rather than assert.equal(). + - object: assert + property: notEqual + message: Use assert.notStrictEqual() rather than assert.notEqual(). + - property: __defineGetter__ + message: __defineGetter__ is deprecated. + - property: __defineSetter__, + message: __defineSetter__ is deprecated. # Stylistic Issues # http://eslint.org/docs/rules/#stylistic-issues diff --git a/BUILDING.md b/BUILDING.md index 75ef93f8c73a13..ec56e386595ae3 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -8,6 +8,71 @@ If you consistently can reproduce a test failure, search for it in the [Node.js issue tracker](https://github.com/nodejs/node/issues) or file a new issue. +## Supported platforms + +This list of supported platforms is current as of the branch / release to +which it is attached. + +### Input + +Node.js relies on V8 and libuv. Therefore, we adopt a subset of their +supported platforms. + +### Strategy + +Support is divided into three tiers: + +* **Tier 1**: Full test coverage and maintenance by the Node.js core team and + the broader community. +* **Tier 2**: Full test coverage but more limited maintenance, + often provided by the vendor of the platform. +* **Experimental**: Known to compile but not necessarily reliably or with + a full passing test suite. These are often working to be promoted to Tier + 2 but are not quite ready. There is at least one individual actively + providing maintenance and the team is striving to broaden quality and + reliability of support. + +### Supported platforms + +| System | Support type | Version | Architectures | Notes | +|--------------|--------------|----------------------------------|----------------------|------------------| +| GNU/Linux | Tier 1 | kernel >= 2.6.18, glibc >= 2.5 | x86, x64, arm, arm64 | | +| macOS | Tier 1 | >= 10.10 | x64 | | +| Windows | Tier 1 | >= Windows 7 or >= Windows2008R2 | x86, x64 | | +| SmartOS | Tier 2 | >= 14 < 16.4 | x86, x64 | see note1 | +| FreeBSD | Tier 2 | >= 10 | x64 | | +| GNU/Linux | Tier 2 | kernel >= 4.2.0, glibc >= 2.19 | ppc64be | | +| GNU/Linux | Tier 2 | kernel >= 3.13.0, glibc >= 2.19 | ppc64le | | +| AIX | Tier 2 | >= 6.1 TL09 | ppc64be | | +| GNU/Linux | Tier 2 | kernel >= 3.10, glibc >= 2.17 | s390x | | +| macOS | Experimental | >= 10.8 < 10.10 | x64 | no test coverage | +| Linux (musl) | Experimental | musl >= 1.0 | x64 | | + +note1 - The gcc4.8-libs package needs to be installed, because node + binaries have been built with GCC 4.8, for which runtime libraries are not + installed by default. For these node versions, the recommended binaries + are the ones available in pkgsrc, not the one available from nodejs.org. + Note that the binaries downloaded from the pkgsrc repositories are not + officially supported by the Node.js project, and instead are supported + by Joyent. SmartOS images >= 16.4 are not supported because + GCC 4.8 runtime libraries are not available in their pkgsrc repository + +### Supported toolchains + +Depending on host platform, the selection of toolchains may vary. + +#### Unix + +* GCC 4.8 or newer +* Clang 3.4 or newer + +#### Windows + +* Building Node: Visual Studio 2015 or Visual C++ Build Tools 2015 or newer +* Building native add-ons: Visual Studio 2013 or Visual C++ Build Tools 2015 + or newer + +## Building Node.js on supported platforms ### Unix / OS X @@ -20,9 +85,9 @@ Prerequisites: On OS X, you will also need: * [Xcode](https://developer.apple.com/xcode/download/) - * You also need to install the `Command Line Tools` via Xcode. You can find + - You also need to install the `Command Line Tools` via Xcode. You can find this under the menu `Xcode -> Preferences -> Downloads` - * This step will install `gcc` and the related toolchain containing `make` + - This step will install `gcc` and the related toolchain containing `make` * After building, you may want to setup [firewall rules](tools/macosx-firewall.sh) to avoid popups asking to accept incoming network connections when running tests: @@ -51,7 +116,8 @@ the `-j4` flag. See the [GNU Make Documentation](https://www.gnu.org/software/make/manual/html_node/Parallel.html) for more information. -Note that the above requires that `python` resolve to Python 2.6 or 2.7 and not a newer version. +Note that the above requires that `python` resolve to Python 2.6 or 2.7 +and not a newer version. To run the tests: @@ -252,9 +318,11 @@ It is possible to build Node.js with **Note**: building in this way does **not** allow you to claim that the runtime is FIPS 140-2 validated. Instead you can indicate that the runtime -uses a validated module. See the [security policy](http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf) +uses a validated module. See the +[security policy](http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf) page 60 for more details. In addition, the validation for the underlying module -is only valid if it is deployed in accordance with its [security policy](http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf). +is only valid if it is deployed in accordance with its +[security policy](http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf). If you need FIPS validated cryptography it is recommended that you read both the [security policy](http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf) and [user guide](https://openssl.org/docs/fips/UserGuide-2.0.pdf). diff --git a/README.md b/README.md index 7fe05e05e27ad0..77919134c3342c 100644 --- a/README.md +++ b/README.md @@ -132,7 +132,7 @@ the binary verification command above. ## Building Node.js See [BUILDING.md](BUILDING.md) for instructions on how to build -Node.js from source. +Node.js from source along with a list of officially supported platforms. ## Security diff --git a/benchmark/streams/writable-manywrites.js b/benchmark/streams/writable-manywrites.js new file mode 100644 index 00000000000000..fadafe86e4cf70 --- /dev/null +++ b/benchmark/streams/writable-manywrites.js @@ -0,0 +1,23 @@ +'use strict'; + +const common = require('../common'); +const Writable = require('stream').Writable; + +const bench = common.createBenchmark(main, { + n: [2e6] +}); + +function main(conf) { + const n = +conf.n; + const b = Buffer.allocUnsafe(1024); + const s = new Writable(); + s._write = function(chunk, encoding, cb) { + cb(); + }; + + bench.start(); + for (var k = 0; k < n; ++k) { + s.write(b); + } + bench.end(n); +} diff --git a/configure b/configure index 74229bf1120998..e7fa06fe87f6f6 100755 --- a/configure +++ b/configure @@ -894,7 +894,6 @@ def configure_node(o): o['variables']['library_files'] = options.linked_module o['variables']['asan'] = int(options.enable_asan or 0) - o['variables']['v8_inspector'] = b(not options.without_inspector) o['variables']['debug_devtools'] = 'node' if options.use_xcode and options.use_ninja: @@ -1268,6 +1267,12 @@ def configure_intl(o): pprint.pformat(icu_config, indent=2) + '\n') return # end of configure_intl +def configure_inspector(o): + disable_inspector = (options.without_inspector or + options.with_intl in (None, 'none') or + options.without_ssl) + o['variables']['v8_inspector'] = b(not disable_inspector) + output = { 'variables': {}, 'include_dirs': [], @@ -1298,6 +1303,7 @@ configure_v8(output) configure_openssl(output) configure_intl(output) configure_static(output) +configure_inspector(output) # variables should be a root level element, # move everything else to target_defaults diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 10f26421a4ceb5..f087718a6754fd 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -57,7 +57,7 @@ * When using underscores, asterisks and backticks please use proper escaping (**\\\_**, **\\\*** and **\\\`** instead of **\_**, **\*** and **\`**) * References to constructor functions should use PascalCase * References to constructor instances should be camelCased -* References to methods should be used with parenthesis: `socket.end()` instead of `socket.end` +* References to methods should be used with parentheses: `socket.end()` instead of `socket.end` [plugin]: http://editorconfig.org/#download [Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma diff --git a/doc/api/buffer.md b/doc/api/buffer.md index a33c214daeff29..44e274760d30cd 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -348,15 +348,16 @@ deprecated: v6.0.0 > [`Buffer.from(arrayBuffer[, byteOffset [, length]])`][`Buffer.from(arrayBuffer)`] > instead. -* `arrayBuffer` {ArrayBuffer} The `.buffer` property of a [`TypedArray`] or - [`ArrayBuffer`] -* `byteOffset` {Integer} Where to start copying from `arrayBuffer`. **Default:** `0` -* `length` {Integer} How many bytes to copy from `arrayBuffer`. +* `arrayBuffer` {ArrayBuffer} An [`ArrayBuffer`] or the `.buffer` property of a + [`TypedArray`]. +* `byteOffset` {Integer} Index of first byte to expose. **Default:** `0` +* `length` {Integer} Number of bytes to expose. **Default:** `arrayBuffer.length - byteOffset` -When passed a reference to the `.buffer` property of a [`TypedArray`] instance, -the newly created `Buffer` will share the same allocated memory as the -[`TypedArray`]. +This creates a view of the [`ArrayBuffer`] without copying the underlying +memory. For example, when passed a reference to the `.buffer` property of a +[`TypedArray`] instance, the newly created `Buffer` will share the same +allocated memory as the [`TypedArray`]. The optional `byteOffset` and `length` arguments specify a memory range within the `arrayBuffer` that will be shared by the `Buffer`. @@ -726,15 +727,16 @@ A `TypeError` will be thrown if `array` is not an `Array`. added: v5.10.0 --> -* `arrayBuffer` {ArrayBuffer} The `.buffer` property of a [`TypedArray`] or - [`ArrayBuffer`] -* `byteOffset` {Integer} Where to start copying from `arrayBuffer`. **Default:** `0` -* `length` {Integer} How many bytes to copy from `arrayBuffer`. +* `arrayBuffer` {ArrayBuffer} An [`ArrayBuffer`] or the `.buffer` property of a + [`TypedArray`]. +* `byteOffset` {Integer} Index of first byte to expose. **Default:** `0` +* `length` {Integer} Number of bytes to expose. **Default:** `arrayBuffer.length - byteOffset` -When passed a reference to the `.buffer` property of a [`TypedArray`] instance, -the newly created `Buffer` will share the same allocated memory as the -[`TypedArray`]. +This creates a view of the [`ArrayBuffer`] without copying the underlying +memory. For example, when passed a reference to the `.buffer` property of a +[`TypedArray`] instance, the newly created `Buffer` will share the same +allocated memory as the [`TypedArray`]. Example: diff --git a/doc/api/cli.md b/doc/api/cli.md index 34b2c7aff6adcc..9811a7ec7cc942 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -314,13 +314,26 @@ When set, the well known "root" CAs (like VeriSign) will be extended with the extra certificates in `file`. The file should consist of one or more trusted certificates in PEM format. A message will be emitted (once) with [`process.emitWarning()`][emit_warning] if the file is missing or -misformatted, but any errors are otherwise ignored. +malformed, but any errors are otherwise ignored. Note that neither the well known nor extra certificates are used when the `ca` options property is explicitly specified for a TLS or HTTPS client or server. +### `OPENSSL_CONF=file` + + +Load an OpenSSL configuration file on startup. Among other uses, this can be +used to enable FIPS-compliant crypto if Node.js is built with `./configure +\-\-openssl\-fips`. + +If the [`--openssl-config`][] command line option is used, the environment +variable is ignored. + [emit_warning]: process.html#process_process_emitwarning_warning_name_ctor [Buffer]: buffer.html#buffer_buffer [debugger]: debugger.html [REPL]: repl.html [SlowBuffer]: buffer.html#buffer_class_slowbuffer +[`--openssl-config`]: #cli_openssl_config_file diff --git a/doc/api/errors.md b/doc/api/errors.md index 640935da35e460..e0e0f06ac5900f 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -141,15 +141,15 @@ the first argument will be passed as `null`. const fs = require('fs'); function nodeStyleCallback(err, data) { - if (err) { - console.error('There was an error', err); - return; - } - console.log(data); + if (err) { + console.error('There was an error', err); + return; + } + console.log(data); } fs.readFile('/some/file/that/does-not-exist', nodeStyleCallback); -fs.readFile('/some/file/that/does-exist', nodeStyleCallback) +fs.readFile('/some/file/that/does-exist', nodeStyleCallback); ``` The JavaScript `try / catch` mechanism **cannot** be used to intercept errors @@ -167,15 +167,15 @@ try { throw err; } }); -} catch(err) { +} catch (err) { // This will not catch the throw! - console.log(err); + console.error(err); } ``` This will not work because the callback function passed to `fs.readFile()` is called asynchronously. By the time the callback has been called, the -surrounding code (including the `try { } catch(err) { }` block will have +surrounding code (including the `try { } catch (err) { }` block will have already exited. Throwing an error inside the callback **can crash the Node.js process** in most cases. If [domains][] are enabled, or a handler has been registered with `process.on('uncaughtException')`, such errors can be @@ -217,7 +217,7 @@ a string representing the location in the code at which ```js const myObject = {}; Error.captureStackTrace(myObject); -myObject.stack // similar to `new Error().stack` +myObject.stack; // similar to `new Error().stack` ``` The first line of the trace, instead of being prefixed with `ErrorType: @@ -238,7 +238,7 @@ function MyError() { // Without passing MyError to captureStackTrace, the MyError // frame would show up in the .stack property. By passing // the constructor, we omit that frame and all frames above it. -new MyError().stack +new MyError().stack; ``` ### Error.stackTraceLimit @@ -255,7 +255,7 @@ will affect any stack trace captured *after* the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. -#### error.message +### error.message * {String} @@ -267,11 +267,11 @@ the stack trace of the `Error`, however changing this property after the ```js const err = new Error('The message'); -console.log(err.message); +console.error(err.message); // Prints: The message ``` -#### error.stack +### error.stack * {String} @@ -359,7 +359,7 @@ For example: ```js require('net').connect(-1); - // throws RangeError, port should be > 0 && < 65536 + // throws "RangeError: "port" option should be >= 0 and < 65536: -1" ``` Node.js will generate and throw `RangeError` instances *immediately* as a form @@ -379,19 +379,6 @@ doesNotExist; // throws ReferenceError, doesNotExist is not a variable in this program. ``` -`ReferenceError` instances will have an `error.arguments` property whose value -is an array containing a single element: a string representing the variable -that was not defined. - -```js -const assert = require('assert'); -try { - doesNotExist; -} catch(err) { - assert(err.arguments[0], 'doesNotExist'); -} -``` - Unless an application is dynamically generating and running code, `ReferenceError` instances should always be considered a bug in the code or its dependencies. @@ -407,7 +394,7 @@ program. ```js try { require('vm').runInThisContext('binary ! isNotOk'); -} catch(err) { +} catch (err) { // err will be a SyntaxError } ``` diff --git a/doc/api/net.md b/doc/api/net.md index cd7532c409878b..1f161ebded63bf 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -66,7 +66,7 @@ Returns an object with `port`, `family`, and `address` properties: Example: ```js -var server = net.createServer((socket) => { +const server = net.createServer((socket) => { socket.end('goodbye\n'); }).on('error', (err) => { // handle errors here @@ -211,7 +211,7 @@ double-backslashes, such as: ```js net.createServer().listen( - path.join('\\\\?\\pipe', process.cwd(), 'myctl')) + path.join('\\\\?\\pipe', process.cwd(), 'myctl')); ``` The parameter `backlog` behaves the same as in @@ -334,7 +334,7 @@ Construct a new socket object. `fd` allows you to specify the existing file descriptor of socket. Set `readable` and/or `writable` to `true` to allow reads and/or writes on this socket (NOTE: Works only when `fd` is passed). -About `allowHalfOpen`, refer to `createServer()` and `'end'` event. +About `allowHalfOpen`, refer to [`net.createServer()`][] and [`'end'`][] event. `net.Socket` instances are [`EventEmitter`][] with the following events: @@ -874,8 +874,8 @@ server.listen(8124, () => { Test this by using `telnet`: -```sh -telnet localhost 8124 +```console +$ telnet localhost 8124 ``` To listen on the socket `/tmp/echo.sock` the third line from the last would @@ -889,8 +889,8 @@ server.listen('/tmp/echo.sock', () => { Use `nc` to connect to a UNIX domain socket server: -```js -nc -U /tmp/echo.sock +```console +$ nc -U /tmp/echo.sock ``` ## net.isIP(input) @@ -933,6 +933,7 @@ Returns true if input is a version 6 IP address, otherwise returns false. [`dns.lookup()` hints]: dns.html#dns_supported_getaddrinfo_flags [`end()`]: #net_socket_end_data_encoding [`EventEmitter`]: events.html#events_class_eventemitter +[`net.createServer()`]: #net_net_createserver_options_connectionlistener [`net.Socket`]: #net_class_net_socket [`pause()`]: #net_socket_pause [`resume()`]: #net_socket_resume diff --git a/doc/api/os.md b/doc/api/os.md index bfe20c1bef5c7f..15b84189c91272 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -26,6 +26,8 @@ A string constant defining the operating system-specific end-of-line marker: added: v0.5.0 --> +* Returns: {String} + The `os.arch()` method returns a string identifying the operating system CPU architecture *for which the Node.js binary was compiled*. @@ -36,6 +38,9 @@ The current possible values are: `'arm'`, `'arm64'`, `'ia32'`, `'mips'`, Equivalent to [`process.arch`][]. ## os.constants + * {Object} diff --git a/doc/api/timers.md b/doc/api/timers.md index 75d6a36737b7d9..aa99d619dbd284 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -163,7 +163,7 @@ added: v0.0.1 Cancels a `Timeout` object created by [`setTimeout()`][]. -[the Node.js Event Loop]: https://github.com/nodejs/node/blob/master/doc/topics/event-loop-timers-and-nexttick.md +[the Node.js Event Loop]: https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick [`TypeError`]: errors.html#errors_class_typeerror [`clearImmediate()`]: timers.html#timers_clearimmediate_immediate [`clearInterval()`]: timers.html#timers_clearinterval_timeout diff --git a/doc/api/tls.md b/doc/api/tls.md index 3c8c31a8f11e22..0e47ddac0391be 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -483,12 +483,8 @@ added: v0.11.4 will be emitted on the socket before establishing a secure communication * `secureContext`: Optional TLS context object created with [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one - will be created by passing the entire `options` object to - `tls.createSecureContext()`. *Note*: In effect, all - [`tls.createSecureContext()`][] options can be provided, but they will be - _completely ignored_ unless the `secureContext` option is missing. - * ...: Optional [`tls.createSecureContext()`][] options can be provided, see - the `secureContext` option for more information. + will be created by calling [`tls.createSecureContext()`][] with no options. + Construct a new `tls.TLSSocket` object from an existing TCP socket. ### Event: 'OCSPResponse' @@ -587,13 +583,16 @@ For Example: `{ type: 'ECDH', name: 'prime256v1', size: 256 }` added: v0.11.4 --> -* `detailed` {boolean} Specify `true` to request that the full certificate - chain with the `issuer` property be returned; `false` to return only the - top certificate without the `issuer` property. +* `detailed` {boolean} Include the full certificate chain if `true`, otherwise + include just the peer's certificate. Returns an object representing the peer's certificate. The returned object has some properties corresponding to the fields of the certificate. +If the full certificate chain was requested, each certificate will include a +`issuerCertificate` property containing an object representing its issuer's +certificate. + For example: ```text @@ -604,15 +603,15 @@ For example: O: 'node.js', OU: 'Test TLS Certificate', CN: 'localhost' }, - issuerInfo: + issuer: { C: 'UK', ST: 'Acknack Ltd', L: 'Rhys Jones', O: 'node.js', OU: 'Test TLS Certificate', CN: 'localhost' }, - issuer: - { ... another certificate ... }, + issuerCertificate: + { ... another certificate, possibly with a .issuerCertificate ... }, raw: < RAW DER buffer >, valid_from: 'Nov 11 09:52:22 2009 GMT', valid_to: 'Nov 6 09:52:22 2029 GMT', @@ -620,8 +619,7 @@ For example: serialNumber: 'B9B0D332A1AA5635' } ``` -If the peer does not provide a certificate, `null` or an empty object will be -returned. +If the peer does not provide a certificate, an empty object will be returned. ### tlsSocket.getProtocol()