Commit 05c3ff5
doc: clarify that some modules don't work when compiled without ssl
PR-URL: #42198
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Richard Lau <rlau@redhat.com>
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Darshan Sen <raisinten@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>1 parent a6c1abf commit 05c3ff5
3 files changed
Lines changed: 109 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -30,6 +30,41 @@ can be accessed using: | |||
| 30 | 30 | const http2 = require('http2'); | |
| 31 | 31 | ``` | |
| 32 | 32 | ||
| 33 | + ## Determining if crypto support is unavailable | ||
| 34 | + | ||
| 35 | + It is possible for Node.js to be built without including support for the | ||
| 36 | + `crypto` module. In such cases, attempting to `import` from `http2` or | ||
| 37 | + calling `require('http2')` will result in an error being thrown. | ||
| 38 | + | ||
| 39 | + When using CommonJS, the error thrown can be caught using try/catch: | ||
| 40 | + | ||
| 41 | + ```cjs | ||
| 42 | + let http2; | ||
| 43 | + try { | ||
| 44 | + http2 = require('http2'); | ||
| 45 | + } catch (err) { | ||
| 46 | + console.log('http2 support is disabled!'); | ||
| 47 | + } | ||
| 48 | + ``` | ||
| 49 | + | ||
| 50 | + When using the lexical ESM `import` keyword, the error can only be | ||
| 51 | + caught if a handler for `process.on('uncaughtException')` is registered | ||
| 52 | + _before_ any attempt to load the module is made (using, for instance, | ||
| 53 | + a preload module). | ||
| 54 | + | ||
| 55 | + When using ESM, if there is a chance that the code may be run on a build | ||
| 56 | + of Node.js where crypto support is not enabled, consider using the | ||
| 57 | + `import()` function instead of the lexical `import` keyword: | ||
| 58 | + | ||
| 59 | + ```mjs | ||
| 60 | + let http2; | ||
| 61 | + try { | ||
| 62 | + http2 = await import('http2'); | ||
| 63 | + } catch (err) { | ||
| 64 | + console.log('http2 support is disabled!'); | ||
| 65 | + } | ||
| 66 | + ``` | ||
| 67 | + | ||
| 33 | 68 | ## Core API | |
| 34 | 69 | ||
| 35 | 70 | The Core API provides a low-level interface designed specifically around | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -9,6 +9,43 @@ | |||
| 9 | 9 | HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a | |
| 10 | 10 | separate module. | |
| 11 | 11 | ||
| 12 | + ## Determining if crypto support is unavailable | ||
| 13 | + | ||
| 14 | + It is possible for Node.js to be built without including support for the | ||
| 15 | + `crypto` module. In such cases, attempting to `import` from `https` or | ||
| 16 | + calling `require('https')` will result in an error being thrown. | ||
| 17 | + | ||
| 18 | + When using CommonJS, the error thrown can be caught using try/catch: | ||
| 19 | + | ||
| 20 | + <!-- eslint-skip --> | ||
| 21 | + | ||
| 22 | + ```cjs | ||
| 23 | + let https; | ||
| 24 | + try { | ||
| 25 | + https = require('https'); | ||
| 26 | + } catch (err) { | ||
| 27 | + console.log('https support is disabled!'); | ||
| 28 | + } | ||
| 29 | + ``` | ||
| 30 | + | ||
| 31 | + When using the lexical ESM `import` keyword, the error can only be | ||
| 32 | + caught if a handler for `process.on('uncaughtException')` is registered | ||
| 33 | + _before_ any attempt to load the module is made (using, for instance, | ||
| 34 | + a preload module). | ||
| 35 | + | ||
| 36 | + When using ESM, if there is a chance that the code may be run on a build | ||
| 37 | + of Node.js where crypto support is not enabled, consider using the | ||
| 38 | + `import()` function instead of the lexical `import` keyword: | ||
| 39 | + | ||
| 40 | + ```mjs | ||
| 41 | + let https; | ||
| 42 | + try { | ||
| 43 | + https = await import('https'); | ||
| 44 | + } catch (err) { | ||
| 45 | + console.log('https support is disabled!'); | ||
| 46 | + } | ||
| 47 | + ``` | ||
| 48 | + | ||
| 12 | 49 | ## Class: `https.Agent` | |
| 13 | 50 | ||
| 14 | 51 | <!-- YAML | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -14,6 +14,43 @@ The module can be accessed using: | |||
| 14 | 14 | const tls = require('tls'); | |
| 15 | 15 | ``` | |
| 16 | 16 | ||
| 17 | + ## Determining if crypto support is unavailable | ||
| 18 | + | ||
| 19 | + It is possible for Node.js to be built without including support for the | ||
| 20 | + `crypto` module. In such cases, attempting to `import` from `tls` or | ||
| 21 | + calling `require('tls')` will result in an error being thrown. | ||
| 22 | + | ||
| 23 | + When using CommonJS, the error thrown can be caught using try/catch: | ||
| 24 | + | ||
| 25 | + <!-- eslint-skip --> | ||
| 26 | + | ||
| 27 | + ```cjs | ||
| 28 | + let tls; | ||
| 29 | + try { | ||
| 30 | + tls = require('tls'); | ||
| 31 | + } catch (err) { | ||
| 32 | + console.log('tls support is disabled!'); | ||
| 33 | + } | ||
| 34 | + ``` | ||
| 35 | + | ||
| 36 | + When using the lexical ESM `import` keyword, the error can only be | ||
| 37 | + caught if a handler for `process.on('uncaughtException')` is registered | ||
| 38 | + _before_ any attempt to load the module is made (using, for instance, | ||
| 39 | + a preload module). | ||
| 40 | + | ||
| 41 | + When using ESM, if there is a chance that the code may be run on a build | ||
| 42 | + of Node.js where crypto support is not enabled, consider using the | ||
| 43 | + `import()` function instead of the lexical `import` keyword: | ||
| 44 | + | ||
| 45 | + ```mjs | ||
| 46 | + let tls; | ||
| 47 | + try { | ||
| 48 | + tls = await import('tls'); | ||
| 49 | + } catch (err) { | ||
| 50 | + console.log('tls support is disabled!'); | ||
| 51 | + } | ||
| 52 | + ``` | ||
| 53 | + | ||
| 17 | 54 | ## TLS/SSL concepts | |
| 18 | 55 | ||
| 19 | 56 | TLS/SSL is a set of protocols that rely on a public key infrastructure (PKI) to | |
0 commit comments