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.

Sign up for GitHub

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: improve http.request and https.request options #1551

Closed
wants to merge 3 commits into from
Closed

doc: improve http.request and https.request options #1551

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3d25dd6
doc: improve http.connect option descriptions
silverwind Apr 28, 2015
7fc16cf
Copy options to https, unify globalAgent link
silverwind Apr 28, 2015
47bd725
Fix copy-paste error on default port
silverwind May 1, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions doc/api/http.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -460,10 +460,14 @@ Options:

- `host`: A domain name or IP address of the server to issue the request to.
Defaults to `'localhost'`.
- `hostname`: To support `url.parse()` `hostname` is preferred over `host`
- `hostname`: Alias for `host`. To support `url.parse()` `hostname` is
preferred over `host`.
- `family`: IP address family to use when resolving `host` and `hostname`.
Valid values are `4` or `6`. When unspecified, both IP v4 and v6 will be
used.
Copy link
Contributor

Choose a reason for hiding this comment

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

@cjihrig didn't your example in the original issue state that this was required for ipv6?

Copy link
Contributor

Choose a reason for hiding this comment

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

@Fishrock123 TL;DR, I believe @silverwind statement to be correct here.

In that particular example, IPv6 was required, as the server was only listening on '::1'. When dns.lookup() executes, it looks up localhost and returns the results [ '127.0.0.1', '::1', 'fe80::1' ] (on my local machine). The first result is used, and the family is inferred as 4.

Copy link
Contributor

Choose a reason for hiding this comment

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

So basically #708..

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I understood #708 as a request to attempt multiple IPs from the same family.

What exactly does a browser on dual stack do if it encounters both v4 and v6? Attempt both in succession? In parallel? Whatever it does, I think that's what we should do if no family is given.

- `port`: Port of remote server. Defaults to 80.
- `localAddress`: Local interface to bind for network connections.
- `socketPath`: Unix Domain Socket (use one of host:port or socketPath)
- `socketPath`: Unix Domain Socket (use one of host:port or socketPath).
- `method`: A string specifying the HTTP request method. Defaults to `'GET'`.
- `path`: Request path. Defaults to `'/'`. Should include query string if any.
E.G. `'/index.html?page=12'`. An exception is thrown when the request path
Expand All @@ -474,7 +478,7 @@ Options:
Authorization header.
- `agent`: Controls [Agent][] behavior. When an Agent is used request will
default to `Connection: keep-alive`. Possible values:
- `undefined` (default): use [global Agent][] for this host and port.
- `undefined` (default): use [globalAgent][] for this host and port.
- `Agent` object: explicitly use the passed in `Agent`.
- `false`: opts out of connection pooling with an Agent, defaults request to
`Connection: close`.
Expand Down Expand Up @@ -1069,7 +1073,7 @@ authentication details.
[EventEmitter]: events.html#events_class_events_eventemitter
[Readable Stream]: stream.html#stream_class_stream_readable
[Writable Stream]: stream.html#stream_class_stream_writable
[global Agent]: #http_http_globalagent
[globalAgent]: #http_http_globalagent
[http.ClientRequest]: #http_class_http_clientrequest
[http.IncomingMessage]: #http_http_incomingmessage
[http.ServerResponse]: #http_class_http_serverresponse
Expand Down
12 changes: 10 additions & 2 deletions doc/api/https.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,11 +103,19 @@ The options argument has the following options

- `host`: A domain name or IP address of the server to issue the request to.
Defaults to `'localhost'`.
- `hostname`: To support `url.parse()` `hostname` is preferred over `host`
- `hostname`: Alias for `host`. To support `url.parse()` `hostname` is
preferred over `host`.
- `family`: IP address family to use when resolving `host` and `hostname`.
Valid values are `4` or `6`. When unspecified, both IP v4 and v6 will be
used.
- `port`: Port of remote server. Defaults to 443.
- `localAddress`: Local interface to bind for network connections.
- `socketPath`: Unix Domain Socket (use one of host:port or socketPath).
- `method`: A string specifying the HTTP request method. Defaults to `'GET'`.
- `path`: Request path. Defaults to `'/'`. Should include query string if any.
E.G. `'/index.html?page=12'`
E.G. `'/index.html?page=12'`. An exception is thrown when the request path
contains illegal characters. Currently, only spaces are rejected but that
may change in the future.
- `headers`: An object containing request headers.
- `auth`: Basic authentication i.e. `'user:password'` to compute an
Authorization header.
Expand Down