Skip to content

Commit e99a2ca

Browse files
committed
doc: improve agent.createConnection docs for http and https agents
1 parent 9148e96 commit e99a2ca

File tree

2 files changed

+31
-11
lines changed

2 files changed

+31
-11
lines changed

doc/api/http.md

+25-11
Original file line numberDiff line numberDiff line change
@@ -204,23 +204,37 @@ added: v0.11.4
204204
-->
205205

206206
* `options` {Object} Options containing connection details. Check
207-
[`net.createConnection()`][] for the format of the options
208-
* `callback` {Function} Callback function that receives the created socket
209-
* Returns: {stream.Duplex}
207+
[`net.createConnection()`][] for the format of the options. For custom agents,
208+
this object is passed to the custom `createConnection` function.
209+
* `callback` {Function} (Optional, primarily for custom agents) A function to be
210+
called by a custom `createConnection` implementation when the socket is
211+
created, especially for asynchronous operations.
212+
* `err` {Error | null} An error object if socket creation failed.
213+
* `socket` {stream.Duplex} The created socket.
214+
* Returns: {stream.Duplex} The created socket. This is returned by the default
215+
implementation or by a custom synchronous `createConnection` implementation.
216+
If a custom `createConnection` uses the `callback` for asynchronous
217+
operation, this return value might not be the primary way to obtain the socket.
210218

211219
Produces a socket/stream to be used for HTTP requests.
212220

213-
By default, this function is the same as [`net.createConnection()`][]. However,
214-
custom agents may override this method in case greater flexibility is desired.
221+
By default, this function behaves identically to [`net.createConnection(options)`][],
222+
synchronously returning the created socket. The optional `callback` parameter in the
223+
signature is **not** used by this default implementation.
215224

216-
A socket/stream can be supplied in one of two ways: by returning the
217-
socket/stream from this function, or by passing the socket/stream to `callback`.
225+
However, custom agents may override this method to provide greater flexibility,
226+
for example, to create sockets asynchronously. When overriding `createConnection`:
218227

219-
This method is guaranteed to return an instance of the {net.Socket} class,
220-
a subclass of {stream.Duplex}, unless the user specifies a socket
221-
type other than {net.Socket}.
228+
1. **Synchronous socket creation**: The overriding method can return the
229+
socket/stream directly.
230+
2. **Asynchronous socket creation**: The overriding method can accept the `callback`
231+
and pass the created socket/stream to it (e.g., `callback(null, newSocket)`).
232+
If an error occurs during socket creation, it should be passed as the first
233+
argument to the `callback` (e.g., `callback(err)`).
222234

223-
`callback` has a signature of `(err, stream)`.
235+
The agent will call the provided `createConnection` function with `options` and
236+
this internal `callback`. The `callback` provided by the agent has a signature
237+
of `(err, stream)`.
224238

225239
### `agent.keepSocketAlive(socket)`
226240

doc/api/https.md

+6
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,12 @@ changes:
6161
An [`Agent`][] object for HTTPS similar to [`http.Agent`][]. See
6262
[`https.request()`][] for more information.
6363

64+
Like `http.Agent`, the `createConnection(options[, callback])` method can be overridden
65+
to customize how TLS connections are established.
66+
67+
> See [`http.Agent#createConnection()`][] for details on overriding this method,
68+
> including asynchronous socket creation with a callback.
69+
6470
### `new Agent([options])`
6571

6672
<!-- YAML

0 commit comments

Comments
 (0)