Skip to content

Commit

Permalink
doc: clarify that some modules don't work when compiled without ssl
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
aduh95 authored and sxa committed Mar 7, 2022
1 parent a6c1abf commit 05c3ff5
Show file tree
Hide file tree
Showing 3 changed files with 109 additions and 0 deletions.
35 changes: 35 additions & 0 deletions doc/api/http2.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 37 additions & 0 deletions doc/api/https.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

<!-- eslint-skip -->

```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`

<!-- YAML
Expand Down
37 changes: 37 additions & 0 deletions doc/api/tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,43 @@ The module can be accessed using:
const tls = require('tls');
```

## 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 `tls` or
calling `require('tls')` will result in an error being thrown.

When using CommonJS, the error thrown can be caught using try/catch:

<!-- eslint-skip -->

```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
Expand Down

0 comments on commit 05c3ff5

Please sign in to comment.