From 425ae2705d4a5589eb173eb349c56629fe4ecac1 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Thu, 3 Mar 2022 10:14:14 +0100 Subject: [PATCH 1/2] doc: clarify that some modules don't work when compiled without ssl --- doc/api/http2.md | 35 +++++++++++++++++++++++++++++++++++ doc/api/https.md | 37 +++++++++++++++++++++++++++++++++++++ doc/api/tls.md | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 109 insertions(+) diff --git a/doc/api/http2.md b/doc/api/http2.md index a2141e995f0a38..2d3a8a501173b6 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -30,6 +30,41 @@ can be accessed using: const http2 = require('http2'); ``` +## Determining if crypto support is unavailable + +It is possible for Node.js to be built without including support for the +`crypto` module. In such cases, attempting to `import` from `http2` or +calling `require('http2')` will result in an error being thrown. + +When using CommonJS, the error thrown can be caught using try/catch: + +```cjs +let http2; +try { + http2 = require('http2'); +} catch (err) { + console.log('http2 support is disabled!'); +} +``` + +When using the lexical ESM `import` keyword, the error can only be +caught if a handler for `process.on('uncaughtException')` is registered +_before_ any attempt to load the module is made -- using, for instance, +a preload module. + +When using ESM, if there is a chance that the code may be run on a build +of Node.js where crypto support is not enabled, consider using the +`import()` function instead of the lexical `import` keyword: + +```mjs +let http2; +try { + http2 = await import('http2'); +} catch (err) { + console.log('http2 support is disabled!'); +} +``` + ## Core API The Core API provides a low-level interface designed specifically around diff --git a/doc/api/https.md b/doc/api/https.md index a8155384077a5e..f3012557e8b860 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -9,6 +9,43 @@ HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a separate module. +## Determining if crypto support is unavailable + +It is possible for Node.js to be built without including support for the +`crypto` module. In such cases, attempting to `import` from `https` or +calling `require('https')` will result in an error being thrown. + +When using CommonJS, the error thrown can be caught using try/catch: + + + +```cjs +let https; +try { + https = require('https'); +} catch (err) { + console.log('https support is disabled!'); +} +``` + +When using the lexical ESM `import` keyword, the error can only be +caught if a handler for `process.on('uncaughtException')` is registered +_before_ any attempt to load the module is made -- using, for instance, +a preload module. + +When using ESM, if there is a chance that the code may be run on a build +of Node.js where crypto support is not enabled, consider using the +`import()` function instead of the lexical `import` keyword: + +```mjs +let https; +try { + https = await import('https'); +} catch (err) { + console.log('https support is disabled!'); +} +``` + ## Class: `https.Agent` + +```cjs +let tls; +try { + tls = require('tls'); +} catch (err) { + console.log('tls support is disabled!'); +} +``` + +When using the lexical ESM `import` keyword, the error can only be +caught if a handler for `process.on('uncaughtException')` is registered +_before_ any attempt to load the module is made -- using, for instance, +a preload module. + +When using ESM, if there is a chance that the code may be run on a build +of Node.js where crypto support is not enabled, consider using the +`import()` function instead of the lexical `import` keyword: + +```mjs +let tls; +try { + tls = await import('tls'); +} catch (err) { + console.log('tls support is disabled!'); +} +``` + ## TLS/SSL concepts TLS/SSL is a set of protocols that rely on a public key infrastructure (PKI) to From a15b64e3f6dcffc9fd2919d92db022af83ab99a0 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Thu, 3 Mar 2022 20:58:00 +0100 Subject: [PATCH 2/2] doc: use parenthesis instead of em dash Co-authored-by: Rich Trott --- doc/api/http2.md | 4 ++-- doc/api/https.md | 4 ++-- doc/api/tls.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 2d3a8a501173b6..48090bce3ddda3 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -49,8 +49,8 @@ try { When using the lexical ESM `import` keyword, the error can only be caught if a handler for `process.on('uncaughtException')` is registered -_before_ any attempt to load the module is made -- using, for instance, -a preload module. +_before_ any attempt to load the module is made (using, for instance, +a preload module). When using ESM, if there is a chance that the code may be run on a build of Node.js where crypto support is not enabled, consider using the diff --git a/doc/api/https.md b/doc/api/https.md index f3012557e8b860..3a28f3b0f00bfc 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -30,8 +30,8 @@ try { When using the lexical ESM `import` keyword, the error can only be caught if a handler for `process.on('uncaughtException')` is registered -_before_ any attempt to load the module is made -- using, for instance, -a preload module. +_before_ any attempt to load the module is made (using, for instance, +a preload module). When using ESM, if there is a chance that the code may be run on a build of Node.js where crypto support is not enabled, consider using the diff --git a/doc/api/tls.md b/doc/api/tls.md index 5c21dd620ef86a..8a8fdf9aefffeb 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -35,8 +35,8 @@ try { When using the lexical ESM `import` keyword, the error can only be caught if a handler for `process.on('uncaughtException')` is registered -_before_ any attempt to load the module is made -- using, for instance, -a preload module. +_before_ any attempt to load the module is made (using, for instance, +a preload module). When using ESM, if there is a chance that the code may be run on a build of Node.js where crypto support is not enabled, consider using the