Commit 9632c39
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -237,23 +237,37 @@ added: v0.11.4 | |||
| 237 | 237 | --> | |
| 238 | 238 | ||
| 239 | 239 | * `options` {Object} Options containing connection details. Check | |
| 240 | - [`net.createConnection()`][] for the format of the options | ||
| 241 | - * `callback` {Function} Callback function that receives the created socket | ||
| 242 | - * Returns: {stream.Duplex} | ||
| 240 | + [`net.createConnection()`][] for the format of the options. For custom agents, | ||
| 241 | + this object is passed to the custom `createConnection` function. | ||
| 242 | + * `callback` {Function} (Optional, primarily for custom agents) A function to be | ||
| 243 | + called by a custom `createConnection` implementation when the socket is | ||
| 244 | + created, especially for asynchronous operations. | ||
| 245 | + * `err` {Error | null} An error object if socket creation failed. | ||
| 246 | + * `socket` {stream.Duplex} The created socket. | ||
| 247 | + * Returns: {stream.Duplex} The created socket. This is returned by the default | ||
| 248 | + implementation or by a custom synchronous `createConnection` implementation. | ||
| 249 | + If a custom `createConnection` uses the `callback` for asynchronous | ||
| 250 | + operation, this return value might not be the primary way to obtain the socket. | ||
| 243 | 251 | ||
| 244 | 252 | Produces a socket/stream to be used for HTTP requests. | |
| 245 | 253 | ||
| 246 | - By default, this function is the same as [`net.createConnection()`][]. However, | ||
| 247 | - custom agents may override this method in case greater flexibility is desired. | ||
| 254 | + By default, this function behaves identically to [`net.createConnection(options)`][], | ||
| 255 | + synchronously returning the created socket. The optional `callback` parameter in the | ||
| 256 | + signature is **not** used by this default implementation. | ||
| 248 | 257 | ||
| 249 | - A socket/stream can be supplied in one of two ways: by returning the | ||
| 250 | - socket/stream from this function, or by passing the socket/stream to `callback`. | ||
| 258 | + However, custom agents may override this method to provide greater flexibility, | ||
| 259 | + for example, to create sockets asynchronously. When overriding `createConnection`: | ||
| 251 | 260 | ||
| 252 | - This method is guaranteed to return an instance of the {net.Socket} class, | ||
| 253 | - a subclass of {stream.Duplex}, unless the user specifies a socket | ||
| 254 | - type other than {net.Socket}. | ||
| 261 | + 1. **Synchronous socket creation**: The overriding method can return the | ||
| 262 | + socket/stream directly. | ||
| 263 | + 2. **Asynchronous socket creation**: The overriding method can accept the `callback` | ||
| 264 | + and pass the created socket/stream to it (e.g., `callback(null, newSocket)`). | ||
| 265 | + If an error occurs during socket creation, it should be passed as the first | ||
| 266 | + argument to the `callback` (e.g., `callback(err)`). | ||
| 255 | 267 | ||
| 256 | - `callback` has a signature of `(err, stream)`. | ||
| 268 | + The agent will call the provided `createConnection` function with `options` and | ||
| 269 | + this internal `callback`. The `callback` provided by the agent has a signature | ||
| 270 | + of `(err, stream)`. | ||
| 257 | 271 | ||
| 258 | 272 | ### `agent.keepSocketAlive(socket)` | |
| 259 | 273 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -61,6 +61,12 @@ changes: | |||
| 61 | 61 | An [`Agent`][] object for HTTPS similar to [`http.Agent`][]. See | |
| 62 | 62 | [`https.request()`][] for more information. | |
| 63 | 63 | ||
| 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 | + | ||
| 64 | 70 | ### `new Agent([options])` | |
| 65 | 71 | ||
| 66 | 72 | <!-- YAML | |
0 commit comments