From 7ba172f56fcda3cfd7b055302ecb1398c8a469f3 Mon Sep 17 00:00:00 2001 From: Amelia Clarke Date: Fri, 3 Mar 2017 15:23:48 -0800 Subject: [PATCH] doc: argument types for https methods Ref: https://github.com/nodejs/node/issues/9399 PR-URL: https://github.com/nodejs/node/pull/11681 Reviewed-By: James M Snell Reviewed-By: Joyee Cheung --- doc/api/https.md | 100 ++++++++++++++++++----------------------------- 1 file changed, 37 insertions(+), 63 deletions(-) diff --git a/doc/api/https.md b/doc/api/https.md index 12ebef2bf8ce4b..ea99d8bcdb99b0 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -21,17 +21,20 @@ added: v0.3.4 This class is a subclass of `tls.Server` and emits events same as [`http.Server`][]. See [`http.Server`][] for more information. -### server.setTimeout(msecs, callback) +### server.setTimeout([msecs][, callback]) +- `msecs` {number} Defaults to 120000 (2 minutes). +- `callback` {Function} See [`http.Server#setTimeout()`][]. -### server.timeout +### server.timeout([msecs]) +- `msecs` {number} Defaults to 120000 (2 minutes). See [`http.Server#timeout`][]. @@ -39,10 +42,8 @@ See [`http.Server#timeout`][]. - -Returns a new HTTPS web server object. The `options` is similar to -[`tls.createServer()`][]. The `requestListener` is a function which is -automatically added to the `'request'` event. +- `options` {Object} Accepts `options` from [`tls.createServer()`][] and [`tls.createSecureContext()`][]. +- `requestListener` {Function} A listener to be added to the `request` event. Example: @@ -83,19 +84,33 @@ https.createServer(options, (req, res) => { +- `callback` {Function} See [`http.close()`][] for details. ### server.listen(handle[, callback]) +- `handle` {Object} +- `callback` {Function} + ### server.listen(path[, callback]) -### server.listen(port[, host][, backlog][, callback]) +- `path` {string} +- `callback` {Function} + +### server.listen([port][, host][, backlog][, callback]) +- `port` {number} +- `hostname` {string} +- `backlog` {number} +- `callback` {Function} See [`http.listen()`][] for details. -## https.get(options, callback) +## https.get(options[, callback]) +- `options` {Object | string} Accepts the same `options` as + [`https.request()`][], with the `method` always set to `GET`. +- `callback` {Function} Like [`http.get()`][] but for HTTPS. @@ -127,18 +142,27 @@ added: v0.5.9 Global instance of [`https.Agent`][] for all HTTPS client requests. -## https.request(options, callback) +## https.request(options[, callback]) +- `options` {Object | string} Accepts all `options` from [`http.request()`][], + with some differences in default values: + - `protocol` Defaults to `https:` + - `port` Defaults to `443`. + - `agent` Defaults to `https.globalAgent`. +- `callback` {Function} + Makes a request to a secure web server. +The following additional `options` from [`tls.connect()`][] are also accepted when using a + custom [`Agent`][]: + `pfx`, `key`, `passphrase`, `cert`, `ca`, `ciphers`, `rejectUnauthorized`, `secureProtocol`, `servername` + `options` can be an object or a string. If `options` is a string, it is automatically parsed with [`url.parse()`][]. -All options from [`http.request()`][] are valid. - Example: ```js @@ -165,58 +189,7 @@ req.on('error', (e) => { }); req.end(); ``` - -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`: 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'`. 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. -- `agent`: Controls [`Agent`][] behavior. When an Agent is used request will - default to `Connection: keep-alive`. Possible values: - - `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`. - -The following options from [`tls.connect()`][] can also be specified: - -- `pfx`: Certificate, Private key and CA certificates to use for SSL. Default `null`. -- `key`: Private key to use for SSL. Default `null`. -- `passphrase`: A string of passphrase for the private key or pfx. Default `null`. -- `cert`: Public x509 certificate to use. Default `null`. -- `ca`: A string, [`Buffer`][] or array of strings or [`Buffer`][]s of trusted - certificates in PEM format. If this is omitted several well known "root" - CAs will be used, like VeriSign. These are used to authorize connections. -- `ciphers`: A string describing the ciphers to use or exclude. Consult - for - details on the format. -- `rejectUnauthorized`: If `true`, the server certificate is verified against - the list of supplied CAs. An `'error'` event is emitted if verification - fails. Verification happens at the connection level, *before* the HTTP - request is sent. Default `true`. -- `secureProtocol`: The SSL method to use, e.g. `SSLv3_method` to force - SSL version 3. The possible values depend on your installation of - OpenSSL and are defined in the constant [`SSL_METHODS`][]. -- `servername`: Servername for SNI (Server Name Indication) TLS extension. - -In order to specify these options, use a custom [`Agent`][]. - -Example: +Example using options from [`tls.connect()`][]: ```js const options = { @@ -270,4 +243,5 @@ const req = https.request(options, (res) => { [`SSL_METHODS`]: https://www.openssl.org/docs/man1.0.2/ssl/ssl.html#DEALING-WITH-PROTOCOL-METHODS [`tls.connect()`]: tls.html#tls_tls_connect_options_callback [`tls.createServer()`]: tls.html#tls_tls_createserver_options_secureconnectionlistener +[`tls.createSecureContext()`]: tls.html#tls_tls_createsecurecontext_options [`url.parse()`]: url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost