GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — doc: improve agent.createConnection docs for http and https agents · nodejs/node@9632c39

File tree

Expand file treeCollapse file tree

Open diff view settings

Filter options

doc/api
- http.md
- https.md

Expand file treeCollapse file tree

Open diff view settings

Collapse file

`‎doc/api/http.md‎`

Copy file name to clipboardExpand all lines: doc/api/http.md

+25-11Lines changed: 25 additions & 11 deletions

Display the source diff
Display the rich diff

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`

Collapse file

`‎doc/api/https.md‎`

Copy file name to clipboardExpand all lines: doc/api/https.md

+6Lines changed: 6 additions & 0 deletions

Display the source diff
Display the rich diff

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

Comments

0 (0)

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.