Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files

docs: improvement fs, http and https

  • Loading branch information...
koichik committed Oct 22, 2011
1 parent 216570b commit 00aa8935d7f0c2b95dc95d0e335cbffbf80d6aa1
Showing with 52 additions and 25 deletions.
  1. +3 −3 doc/api/fs.markdown
  2. +14 −13 doc/api/http.markdown
  3. +33 −7 doc/api/https.markdown
  4. +2 −2 doc/api/tls.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
@@ -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
@@ -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.
@@ -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

0 comments on commit 00aa893

Please sign in to comment.
You can’t perform that action at this time.