diff options
Diffstat (limited to 'doc/api')
| -rw-r--r-- | doc/api/crypto.markdown | 34 | ||||
| -rw-r--r-- | doc/api/domain.markdown | 12 | ||||
| -rw-r--r-- | doc/api/http.markdown | 31 | ||||
| -rw-r--r-- | doc/api/https.markdown | 13 | ||||
| -rw-r--r-- | doc/api/net.markdown | 16 | ||||
| -rw-r--r-- | doc/api/process.markdown | 7 | ||||
| -rw-r--r-- | doc/api/stream.markdown | 16 | ||||
| -rw-r--r-- | doc/api/tls.markdown | 6 | ||||
| -rw-r--r-- | doc/api/util.markdown | 13 |
9 files changed, 106 insertions, 42 deletions
diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index e4d43467b..53e5b5e41 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -1,6 +1,7 @@ # Crypto - Stability: 3 - Stable + Stability: 2 - Unstable; API changes are being discussed for + future versions. Breaking changes will be minimized. See below. Use `require('crypto')` to access this module. @@ -390,6 +391,37 @@ Generates cryptographically strong pseudo-random data. Usage: // handle error } +## Proposed API Changes in Future Versions of Node + +The Crypto module was added to Node before there was the concept of a +unified Stream API, and before there were Buffer objects for handling +binary data. + +As such, the streaming classes don't have the typical methods found on +other Node classes, and many methods accept and return Binary-encoded +strings by default rather than Buffers. + +A future version of node will make Buffers the default data type. +This will be a breaking change for some use cases, but not all. + +For example, if you currently use the default arguments to the Sign +class, and then pass the results to the Verify class, without ever +inspecting the data, then it will continue to work as before. Where +you now get a binary string and then present the binary string to the +Verify object, you'll get a Buffer, and present the Buffer to the +Verify object. + +However, if you are doing things with the string data that will not +work properly on Buffers (such as, concatenating them, storing in +databases, etc.), or you are passing binary strings to the crypto +functions without an encoding arguemnt, then you will need to start +providing encoding arguments to specify which encoding you'd like to +use. + +Also, a Streaming API will be provided, but this will be done in such +a way as to preserve the legacy API surface. + + [createCipher()]: #crypto_crypto_createcipher_algorithm_password [createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv [crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_encoding diff --git a/doc/api/domain.markdown b/doc/api/domain.markdown index 5e3b34c4f..24acd295b 100644 --- a/doc/api/domain.markdown +++ b/doc/api/domain.markdown @@ -184,9 +184,9 @@ from that one, and bound to this one instead. The opposite of `domain.add(emitter)`. Removes domain handling from the specified emitter. -### domain.bind(cb) +### domain.bind(callback) -* `cb` {Function} The callback function +* `callback` {Function} The callback function * return: {Function} The bound function The returned function will be a wrapper around the supplied callback @@ -210,16 +210,16 @@ thrown will be routed to the domain's `error` event. // with the normal line number and stack message. }); -### domain.intercept(cb) +### domain.intercept(callback) -* `cb` {Function} The callback function +* `callback` {Function} The callback function * return: {Function} The intercepted function -This method is almost identical to `domain.bind(cb)`. However, in +This method is almost identical to `domain.bind(callback)`. However, in addition to catching thrown errors, it will also intercept `Error` objects sent as the first argument to the function. -In this way, the common `if (er) return cb(er);` pattern can be replaced +In this way, the common `if (er) return callback(er);` pattern can be replaced with a single error handler in a single place. #### Example diff --git a/doc/api/http.markdown b/doc/api/http.markdown index 61121166e..92918faa5 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -159,10 +159,10 @@ This function is asynchronous. The last parameter `callback` will be added as a listener for the ['listening'][] event. See also [net.Server.listen(path)][]. -### server.listen(handle, [listeningListener]) +### server.listen(handle, [callback]) * `handle` {Object} -* `listeningListener` {Function} +* `callback` {Function} The `handle` object can be set to either a server or socket (anything with an underlying `_handle` member), or a `{fd: <n>}` object. @@ -175,9 +175,9 @@ Listening on a file descriptor is not supported on Windows. This function is asynchronous. The last parameter `callback` will be added as a listener for the ['listening'](net.html#event_listening_) event. -See also [net.Server.listen()](net.html#server.listen). +See also [net.Server.listen()](net.html#net_server_listen_handle_callback). -### server.close([cb]) +### server.close([callback]) Stops the server from accepting new connections. See [net.Server.close()][]. @@ -873,16 +873,23 @@ Note that the __data will be lost__ if there is no listener when a `function () { }` -Emitted exactly once for each message. No arguments. After -emitted no other events will be emitted on the response. +Emitted exactly once for each response. After that, no more `'data'` events +will be emitted on the response. + ### Event: 'close' -`function (err) { }` +`function () { }` Indicates that the underlaying connection was terminated before -`end` event was emitted. -See [http.ServerRequest][]'s `'close'` event for more information. +`response.end()` was called or able to flush. + +Just like `'end'`, this event occurs only once per response, and no more +`'data'` events will fire afterwards. See [http.ServerResponse][]'s `'close'` +event for more information. + +Note: `'close'` can fire after `'end'`, but not vice versa. + ### response.statusCode @@ -924,9 +931,9 @@ Resumes a paused response. [http.request()]: #http_http_request_options_callback [http.ServerRequest]: #http_class_http_serverrequest ['listening']: net.html#net_event_listening -[net.Server.close()]: net.html#net_server_close_cb -[net.Server.listen(path)]: net.html#net_server_listen_path_listeninglistener -[net.Server.listen(port)]: net.html#net_server_listen_port_host_backlog_listeninglistener +[net.Server.close()]: net.html#net_server_close_callback +[net.Server.listen(path)]: net.html#net_server_listen_path_callback +[net.Server.listen(port)]: net.html#net_server_listen_port_host_backlog_callback [Readable Stream]: stream.html#stream_readable_stream [socket.setKeepAlive()]: net.html#net_socket_setkeepalive_enable_initialdelay [socket.setNoDelay()]: net.html#net_socket_setnodelay_nodelay diff --git a/doc/api/https.markdown b/doc/api/https.markdown index 943395a55..0d22b2f8f 100644 --- a/doc/api/https.markdown +++ b/doc/api/https.markdown @@ -46,6 +46,17 @@ Or res.end("hello world\n"); }).listen(8000); + +### server.listen(port, [host], [backlog], [callback]) +### server.listen(path, [callback]) +### server.listen(handle, [callback]) + +See [http.listen()][] for details. + +### server.close([callback]) + +See [http.close()][] for details. + ## https.request(options, callback) Makes a request to a secure web server. @@ -193,6 +204,8 @@ Global instance of [https.Agent][] for all HTTPS client requests. [Agent]: #https_class_https_agent [globalAgent]: #https_https_globalagent +[http.listen()]: http.html#http_server_listen_port_hostname_backlog_callback +[http.close()]: http.html#http_server_close_callback [http.Agent]: http.html#http_class_http_agent [http.request()]: http.html#http_http_request_options_callback [https.Agent]: #https_class_https_agent diff --git a/doc/api/net.markdown b/doc/api/net.markdown index 3f39cda32..b829a47e7 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -118,7 +118,7 @@ The `connectListener` parameter will be added as an listener for the This class is used to create a TCP or UNIX server. A server is a `net.Socket` that can listen for new incoming connections. -### server.listen(port, [host], [backlog], [listeningListener]) +### server.listen(port, [host], [backlog], [callback]) Begin accepting connections on the specified `port` and `host`. If the `host` is omitted, the server will accept connections directed to any @@ -130,7 +130,7 @@ The actual length will be determined by your OS through sysctl settings such as parameter is 511 (not 512). This function is asynchronous. When the server has been bound, -['listening'][] event will be emitted. The last parameter `listeningListener` +['listening'][] event will be emitted. The last parameter `callback` will be added as an listener for the ['listening'][] event. One issue some users run into is getting `EADDRINUSE` errors. This means that @@ -150,18 +150,18 @@ would be to wait a second and then try again. This can be done with (Note: All sockets in Node set `SO_REUSEADDR` already) -### server.listen(path, [listeningListener]) +### server.listen(path, [callback]) Start a UNIX socket server listening for connections on the given `path`. This function is asynchronous. When the server has been bound, -['listening'][] event will be emitted. The last parameter `listeningListener` +['listening'][] event will be emitted. The last parameter `callback` will be added as an listener for the ['listening'][] event. -### server.listen(handle, [listeningListener]) +### server.listen(handle, [callback]) * `handle` {Object} -* `listeningListener` {Function} +* `callback` {Function} The `handle` object can be set to either a server or socket (anything with an underlying `_handle` member), or a `{fd: <n>}` object. @@ -174,10 +174,10 @@ Listening on a file descriptor is not supported on Windows. This function is asynchronous. When the server has been bound, ['listening'](#event_listening_) event will be emitted. -the last parameter `listeningListener` will be added as an listener for the +the last parameter `callback` will be added as an listener for the ['listening'](#event_listening_) event. -### server.close([cb]) +### server.close([callback]) Stops the server from accepting new connections and keeps existing connections. This function is asynchronous, the server is finally diff --git a/doc/api/process.markdown b/doc/api/process.markdown index b407883b2..d8612600c 100644 --- a/doc/api/process.markdown +++ b/doc/api/process.markdown @@ -489,14 +489,15 @@ primary use is for measuring performance between intervals. You may pass in the result of a previous call to `process.hrtime()` to get a diff reading, useful for benchmarks and measuring intervals: - var t = process.hrtime(); + var time = process.hrtime(); // [ 1800216, 927643717 ] setTimeout(function() { - t = process.hrtime(t); + var diff = process.hrtime(time); // [ 1, 6962306 ] - console.log('benchmark took %d seconds and %d nanoseconds', t[0], t[1]); + console.log('benchmark took %d seconds and %d nanoseconds', + diff[0], diff[1]); // benchmark took 1 seconds and 6962306 nanoseconds }, 1000); diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index a894591dd..5e0c6f642 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -120,8 +120,12 @@ A `Writable Stream` has the following methods, members, and events. `function () { }` -After a `write()` method returned `false`, this event is emitted to -indicate that it is safe to write again. +Emitted when the stream's write queue empties and it's safe to write without +buffering again. Listen for it when `stream.write()` returns `false`. + +The `'drain'` event can happen at *any* time, regardless of whether or not +`stream.write()` has previously returned `false`. To avoid receiving unwanted +`'drain'` events, listen using `stream.once()`. ### Event: 'error' @@ -146,7 +150,7 @@ Emitted when the stream is passed to a readable stream's pipe method. A boolean that is `true` by default, but turns `false` after an `'error'` occurred or `end()` / `destroy()` was called. -### stream.write(string, [encoding], [fd]) +### stream.write(string, [encoding]) Writes `string` with the given `encoding` to the stream. Returns `true` if the string has been flushed to the kernel buffer. Returns `false` to @@ -154,12 +158,6 @@ indicate that the kernel buffer is full, and the data will be sent out in the future. The `'drain'` event will indicate when the kernel buffer is empty again. The `encoding` defaults to `'utf8'`. -If the optional `fd` parameter is specified, it is interpreted as an -integral file descriptor to be sent over the stream. This is only -supported for UNIX streams, and is silently ignored otherwise. When -writing a file descriptor in this manner, closing the descriptor before -the stream drains risks sending an invalid (closed) FD. - ### stream.write(buffer) Same as the above except with a raw buffer. diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index d8392ed24..dac7a247b 100644 --- a/doc/api/tls.markdown +++ b/doc/api/tls.markdown @@ -208,8 +208,8 @@ You can test this server by connecting to it with `openssl s_client`: openssl s_client -connect 127.0.0.1:8000 -## tls.connect(options, [secureConnectListener]) -## tls.connect(port, [host], [options], [secureConnectListener]) +## tls.connect(options, [callback]) +## tls.connect(port, [host], [options], [callback]) Creates a new client connection to the given `port` and `host` (old API) or `options.port` and `options.host`. (If `host` is omitted, it defaults to @@ -249,7 +249,7 @@ Creates a new client connection to the given `port` and `host` (old API) or - `servername`: Servername for SNI (Server Name Indication) TLS extension. -The `secureConnectListener` parameter will be added as a listener for the +The `callback` parameter will be added as a listener for the ['secureConnect'][] event. `tls.connect()` returns a [CleartextStream][] object. diff --git a/doc/api/util.markdown b/doc/api/util.markdown index 96ae90f43..f9fa728d6 100644 --- a/doc/api/util.markdown +++ b/doc/api/util.markdown @@ -114,6 +114,19 @@ Predefined color codes are: `white`, `grey`, `black`, `blue`, `cyan`, `green`, `magenta`, `red` and `yellow`. There are also `bold`, `italic`, `underline` and `inverse` codes. +Objects also may define their own `inspect(depth)` function which `util.inspect()` +will invoke and use the result of when inspecting the object: + + var util = require('util'); + + var obj = { name: 'nate' }; + obj.inspect = function(depth) { + return '{' + this.name + '}'; + }; + + util.inspect(obj); + // "{nate}" + ## util.isArray(object) |