Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: clarify that some modules don't work when compiled without ssl #42198

Merged
merged 2 commits into from Mar 5, 2022
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
35 changes: 35 additions & 0 deletions doc/api/http2.md
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.
aduh95 marked this conversation as resolved.
Show resolved Hide resolved

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:
Comment on lines +55 to +57
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FTR, other indicators of crypto being present/unavailable are

  • process.config.variables.node_use_openssl
  • process.features.tls

but it probably isn't a good idea to be encouraging use of those (particularly process.features which AFAIK remains undocumented).


```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
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.
aduh95 marked this conversation as resolved.
Show resolved Hide resolved

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
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.
aduh95 marked this conversation as resolved.
Show resolved Hide resolved

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