From 00aa8935d7f0c2b95dc95d0e335cbffbf80d6aa1 Mon Sep 17 00:00:00 2001 From: koichik Date: Sat, 22 Oct 2011 23:40:15 +0900 Subject: [PATCH] docs: improvement fs, http and https --- doc/api/fs.markdown | 6 +++--- doc/api/http.markdown | 27 ++++++++++++++------------- doc/api/https.markdown | 40 +++++++++++++++++++++++++++++++++------- doc/api/tls.markdown | 4 ++-- 4 files changed, 52 insertions(+), 25 deletions(-) diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index f6e64dd0ef..82ca5a8098 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -133,7 +133,7 @@ Synchronous lchmod(2). ### fs.stat(path, [callback]) Asynchronous stat(2). The callback gets two arguments `(err, stats)` where -`stats` is a [`fs.Stats`](#fs.Stats) object. See the [fs.Stats](#fs.Stats) +`stats` is a [fs.Stats](#fs.Stats) object. See the [fs.Stats](#fs.Stats) section below for more information. ### fs.lstat(path, [callback]) @@ -471,9 +471,9 @@ similar to this: ctime: Mon, 10 Oct 2011 23:24:11 GMT } Please note that `atime`, `mtime` and `ctime` are instances -of [`Date`][MDN-Date] object and to compare the values of +of [Date][MDN-Date] object and to compare the values of these objects you should use appropriate methods. For most -general uses [`getTime()`][MDN-Date-getTime] will return +general uses [getTime()][MDN-Date-getTime] will return the number of milliseconds elapsed since _1 January 1970 00:00:00 UTC_ and this integer should be sufficient for any comparison, however there additional methods which can diff --git a/doc/api/http.markdown b/doc/api/http.markdown index 4cef0c847f..2c6fee759f 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -387,28 +387,29 @@ followed by `response.end()`. ## http.request(options, callback) Node maintains several connections per server to make HTTP requests. -This function allows one to transparently issue requests. Options align -with `url.parse`. +This function allows one to transparently issue requests. `options` align +with [url.parse()](url.html#url.parse). Options: - `host`: A domain name or IP address of the server to issue the request to. -- `hostname`: To support `url.parse` `hostname` is prefered over - `host` -- `port`: Port of remote server. + Defaults to `'localhost'`. +- `hostname`: To support `url.parse()` `hostname` is prefered over `host` +- `port`: Port of remote server. Defaults to 80. - `socketPath`: Unix Domain Socket (use one of host:port or socketPath) -- `method`: A string specifying the HTTP request method. Possible values: - `'GET'` (default), `'POST'`, `'PUT'`, and `'DELETE'`. -- `path`: Request path. Should include query string and fragments if any. - E.G. `'/index.html?page=12'` +- `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'` - `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 default `Agent` for this host and port. +- `agent`: Controls [Agent](#http.Agent) behavior. When an Agent is used + request will default to `Connection: keep-alive`. Possible values: + - `undefined` (default): use [global Agent](#http.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. + - `false`: opts out of connection pooling with an Agent, defaults request to + `Connection: close`. `http.request()` returns an instance of the `http.ClientRequest` class. The `ClientRequest` instance is a writable stream. If one needs to diff --git a/doc/api/https.markdown b/doc/api/https.markdown index 4113fe06e3..0aa6b19fc1 100644 --- a/doc/api/https.markdown +++ b/doc/api/https.markdown @@ -34,7 +34,7 @@ Example: ## https.request(options, callback) Makes a request to a secure web server. -All options from [`http.request()`](http.html#http.request) are valid. +All options from [http.request()](http.html#http.request) are valid. Example: @@ -68,12 +68,30 @@ The options argument has the following options - path: Path to request. Default `'/'`. - method: HTTP request method. Default `'GET'`. -The following options can also be specified. -However, a global [Agent](http.html#http.Agent) cannot be used. - -- key: Private key to use for SSL. Default `null`. -- cert: Public x509 certificate to use. Default `null`. -- ca: An authority certificate or array of authority certificates to check +- `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 prefered over `host` +- `port`: Port of remote server. Defaults to 443. +- `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'` +- `headers`: An object containing request headers. +- `auth`: Basic authentication i.e. `'user:password'` to compute an + Authorization header. +- `agent`: Controls [Agent](#https.Agent) behavior. When an Agent is + used request will default to `Connection: keep-alive`. Possible values: + - `undefined` (default): use [globalAgent](#https.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()](tls.html#tls.connect) can also be +specified. However, a [globalAgent](#https.globalAgent) silently ignores these. + +- `key`: Private key to use for SSL. Default `null`. +- `cert`: Public x509 certificate to use. Default `null`. +- `ca`: An authority certificate or array of authority certificates to check the remote host against. In order to specify these options, use a custom `Agent`. @@ -133,5 +151,13 @@ Example: }); +## https.Agent + +An Agent object for HTTPS similer to [http.Agent](http.html#http.Agent). +See [https.request()](#https.request) for more information. + +## https.globalAgent +Global instance of [https.Agent](#https.Agent) which is used as the default +for all HTTPS client requests. diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index 4a49fe6d7b..3ae7c61e6e 100644 --- a/doc/api/tls.markdown +++ b/doc/api/tls.markdown @@ -27,7 +27,7 @@ Alternatively you can send the CSR to a Certificate Authority for signing. `test/fixtures/keys/Makefile` in the Node source code) -#### tls.createServer(options, secureConnectionListener) +#### tls.createServer(options, [secureConnectionListener]) Creates a new [tls.Server](#tls.Server). The `connectionListener` argument is automatically set as a listener for the @@ -100,7 +100,7 @@ You can test this server by connecting to it with `openssl s_client`: openssl s_client -connect 127.0.0.1:8000 -#### tls.connect(port, [host], [options], secureConnectListener) +#### tls.connect(port, [host], [options], [secureConnectListener]) Creates a new client connection to the given `port` and `host`. (If `host` defaults to `localhost`.) `options` should be an object which specifies