From b62152bc8453011ff447a71182ff90dc351ff3e6 Mon Sep 17 00:00:00 2001 From: Ryan Dahl Date: Wed, 5 Jan 2011 11:53:56 -0800 Subject: [PATCH] Rename net.Stream to net.Socket --- doc/api/net.markdown | 114 +++++++++++++++++++++---------------------- lib/net.js | 88 +++++++++++++++++---------------- 2 files changed, 102 insertions(+), 100 deletions(-) diff --git a/doc/api/net.markdown b/doc/api/net.markdown index 4e905686f6..28a771ea51 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -11,8 +11,8 @@ automatically set as a listener for the `'connection'` event. ### net.createConnection(arguments...) -Construct a new stream object and opens a stream to the given location. When -the stream is established the `'connect'` event will be emitted. +Construct a new socket object and opens a socket to the given location. When +the socket is established the `'connect'` event will be emitted. The arguments for this method change the type of connection: @@ -131,10 +131,10 @@ The number of concurrent connections on the server. #### Event: 'connection' -`function (stream) {}` +`function (socket) {}` -Emitted when a new connection is made. `stream` is an instance of -`net.Stream`. +Emitted when a new connection is made. `socket` is an instance of +`net.Socket`. #### Event: 'close' @@ -144,29 +144,29 @@ Emitted when the server closes. --- -### net.Stream +### net.Socket -This object is an abstraction of of a TCP or UNIX socket. `net.Stream` -instance implement a duplex stream interface. They can be created by the +This object is an abstraction of of a TCP or UNIX socket. `net.Socket` +instances implement a duplex Stream interface. They can be created by the user and used as a client (with `connect()`) or they can be created by Node and passed to the user through the `'connection'` event of a server. -`net.Stream` instances are EventEmitters with the following events: +`net.Socket` instances are EventEmitters with the following events: -#### stream.connect(port, [host], [callback]) -#### stream.connect(path, [callback]) +#### socket.connect(port, [host], [callback]) +#### socket.connect(path, [callback]) -Opens the connection for a given stream. If `port` and `host` are given, -then the stream will be opened as a TCP stream, if `host` is omitted, -`localhost` will be assumed. If a `path` is given, the stream will be +Opens the connection for a given socket. If `port` and `host` are given, +then the socket will be opened as a TCP socket, if `host` is omitted, +`localhost` will be assumed. If a `path` is given, the socket will be opened as a unix socket to that path. Normally this method is not needed, as `net.createConnection` opens the -stream. Use this only if you are implementing a custom Stream or if a -Stream is closed and you want to reuse it to connect to another server. +socket. Use this only if you are implementing a custom Socket or if a +Socket is closed and you want to reuse it to connect to another server. This function is asynchronous. When the `'connect'` event is emitted the -stream is established. If there is a problem connecting, the `'connect'` +socket is established. If there is a problem connecting, the `'connect'` event will not be emitted, the `'error'` event will be emitted with the exception. @@ -174,34 +174,34 @@ The `callback` paramenter will be added as an listener for the 'connect' event. -#### stream.setEncoding(encoding=null) +#### socket.setEncoding(encoding=null) Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is received. -#### stream.setSecure([credentials]) +#### socket.setSecure([credentials]) -Enables SSL support for the stream, with the crypto module credentials specifying -the private key and certificate of the stream, and optionally the CA certificates +Enables SSL support for the socket, with the crypto module credentials specifying +the private key and certificate of the socket, and optionally the CA certificates for use in peer authentication. -If the credentials hold one ore more CA certificates, then the stream will request +If the credentials hold one ore more CA certificates, then the socket will request for the peer to submit a client certificate as part of the SSL connection handshake. The validity and content of this can be accessed via `verifyPeer()` and `getPeerCertificate()`. -#### stream.verifyPeer() +#### socket.verifyPeer() Returns true or false depending on the validity of the peers's certificate in the context of the defined or default list of trusted CA certificates. -#### stream.getPeerCertificate() +#### socket.getPeerCertificate() Returns a JSON structure detailing the peer's certificate, containing a dictionary with keys for the certificate `'subject'`, `'issuer'`, `'valid_from'` and `'valid_to'`. -#### stream.write(data, [encoding], [callback]) +#### socket.write(data, [encoding], [callback]) -Sends data on the stream. The second parameter specifies the encoding in the +Sends data on the socket. The second parameter specifies the encoding in the case of a string--it defaults to UTF8 encoding. Returns `true` if the entire data was flushed successfully to the kernel @@ -211,62 +211,62 @@ buffer. Returns `false` if all or part of the data was queued in user memory. The optional `callback` parameter will be executed when the data is finally written out - this may not be immediately. -#### stream.write(data, [encoding], [fileDescriptor], [callback]) +#### socket.write(data, [encoding], [fileDescriptor], [callback]) For UNIX sockets, it is possible to send a file descriptor through the -stream. Simply add the `fileDescriptor` argument and listen for the `'fd'` +socket. Simply add the `fileDescriptor` argument and listen for the `'fd'` event on the other end. -#### stream.end([data], [encoding]) +#### socket.end([data], [encoding]) -Half-closes the stream. I.E., it sends a FIN packet. It is possible the +Half-closes the socket. I.E., it sends a FIN packet. It is possible the server will still send some data. -If `data` is specified, it is equivalent to calling `stream.write(data, encoding)` -followed by `stream.end()`. +If `data` is specified, it is equivalent to calling `socket.write(data, encoding)` +followed by `socket.end()`. -#### stream.destroy() +#### socket.destroy() -Ensures that no more I/O activity happens on this stream. Only necessary in +Ensures that no more I/O activity happens on this socket. Only necessary in case of errors (parse error or so). -#### stream.pause() +#### socket.pause() Pauses the reading of data. That is, `'data'` events will not be emitted. Useful to throttle back an upload. -#### stream.resume() +#### socket.resume() Resumes reading after a call to `pause()`. -#### stream.setTimeout(timeout) +#### socket.setTimeout(timeout) -Sets the stream to timeout after `timeout` milliseconds of inactivity on -the stream. By default `net.Stream` do not have a timeout. +Sets the socket to timeout after `timeout` milliseconds of inactivity on +the socket. By default `net.Socket` do not have a timeout. -When an idle timeout is triggered the stream will receive a `'timeout'` +When an idle timeout is triggered the socket will receive a `'timeout'` event but the connection will not be severed. The user must manually `end()` -or `destroy()` the stream. +or `destroy()` the socket. If `timeout` is 0, then the existing idle timeout is disabled. -#### stream.setNoDelay(noDelay=true) +#### socket.setNoDelay(noDelay=true) Disables the Nagle algorithm. By default TCP connections use the Nagle algorithm, they buffer data before sending it off. Setting `noDelay` will -immediately fire off data each time `stream.write()` is called. +immediately fire off data each time `socket.write()` is called. -#### stream.setKeepAlive(enable=false, [initialDelay]) +#### socket.setKeepAlive(enable=false, [initialDelay]) Enable/disable keep-alive functionality, and optionally set the initial -delay before the first keepalive probe is sent on an idle stream. +delay before the first keepalive probe is sent on an idle socket. Set `initialDelay` (in milliseconds) to set the delay between the last data packet received and the first keepalive probe. Setting 0 for initialDelay will leave the value unchanged from the default (or previous) setting. -#### stream.remoteAddress +#### socket.remoteAddress The string representation of the remote IP address. For example, `'74.125.127.100'` or `'2001:4860:a005::68'`. @@ -278,7 +278,7 @@ This member is only present in server-side connections. `function () { }` -Emitted when a stream connection successfully is established. +Emitted when a socket connection successfully is established. See `connect()`. #### Event: 'data' @@ -286,18 +286,18 @@ See `connect()`. `function (data) { }` Emitted when data is received. The argument `data` will be a `Buffer` or -`String`. Encoding of data is set by `stream.setEncoding()`. -(See the section on `Readable Stream` for more information.) +`String`. Encoding of data is set by `socket.setEncoding()`. +(See the section on `Readable Socket` for more information.) #### Event: 'end' `function () { }` -Emitted when the other end of the stream sends a FIN packet. +Emitted when the other end of the socket sends a FIN packet. -By default (`allowHalfOpen == false`) the stream will destroy its file +By default (`allowHalfOpen == false`) the socket will destroy its file descriptor once it has written out its pending write queue. However, by -setting `allowHalfOpen == true` the stream will not automatically `end()` +setting `allowHalfOpen == true` the socket will not automatically `end()` its side allowing the user to write arbitrary amounts of data, with the caveat that the user is required to `end()` their side now. @@ -306,10 +306,10 @@ caveat that the user is required to `end()` their side now. `function () { }` -Emitted if the stream times out from inactivity. This is only to notify that -the stream has been idle. The user must manually close the connection. +Emitted if the socket times out from inactivity. This is only to notify that +the socket has been idle. The user must manually close the connection. -See also: `stream.setTimeout()` +See also: `socket.setTimeout()` #### Event: 'drain' @@ -329,8 +329,8 @@ following this event. `function (had_error) { }` -Emitted once the stream is fully closed. The argument `had_error` is a boolean -which says if the stream was closed due to a transmission error. +Emitted once the socket is fully closed. The argument `had_error` is a boolean +which says if the socket was closed due to a transmission error. --- diff --git a/lib/net.js b/lib/net.js index 832954aa3e..efd5dd1386 100644 --- a/lib/net.js +++ b/lib/net.js @@ -167,7 +167,7 @@ function onWritable(readable, writable) { } } -function initStream(self) { +function initSocket(self) { self._readWatcher = ioWatchers.alloc(); self._readWatcher.socket = self; self._readWatcher.callback = onReadable; @@ -185,10 +185,10 @@ function initStream(self) { self.writable = false; } -// Deprecated API: Stream(fd, type) -// New API: Stream({ fd: 10, type: 'unix', allowHalfOpen: true }) -function Stream(options) { - if (!(this instanceof Stream)) return new Stream(arguments[0], arguments[1]); +// Deprecated API: Socket(fd, type) +// New API: Socket({ fd: 10, type: 'unix', allowHalfOpen: true }) +function Socket(options) { + if (!(this instanceof Socket)) return new Socket(arguments[0], arguments[1]); stream.Stream.call(this); this.fd = null; @@ -210,17 +210,19 @@ function Stream(options) { setImplmentationMethods(this); } } -util.inherits(Stream, stream.Stream); -exports.Stream = Stream; +util.inherits(Socket, stream.Stream); +exports.Socket = Socket; +// Legacy naming. +exports.Stream = Socket; -Stream.prototype._onTimeout = function() { +Socket.prototype._onTimeout = function() { this.emit('timeout'); }; -Stream.prototype.open = function(fd, type) { - initStream(this); +Socket.prototype.open = function(fd, type) { + initSocket(this); this.fd = fd; this.type = type || null; @@ -234,13 +236,13 @@ Stream.prototype.open = function(fd, type) { exports.createConnection = function(port, host) { - var s = new Stream(); + var s = new Socket(); s.connect(port, host); return s; }; -Object.defineProperty(Stream.prototype, 'readyState', { +Object.defineProperty(Socket.prototype, 'readyState', { get: function() { if (this._connecting) { return 'opening'; @@ -264,7 +266,7 @@ Object.defineProperty(Stream.prototype, 'readyState', { // Returns true if all the data was flushed to socket. Returns false if // something was queued. If data was queued, then the 'drain' event will // signal when it has been finally flushed to socket. -Stream.prototype.write = function(data /* [encoding], [fd], [cb] */) { +Socket.prototype.write = function(data /* [encoding], [fd], [cb] */) { var encoding, fd, cb; // parse arguments @@ -301,7 +303,7 @@ Stream.prototype.write = function(data /* [encoding], [fd], [cb] */) { // Slow. There is already a write queue, so let's append to it. if (this._writeQueueLast() === END_OF_FILE) { - throw new Error('Stream.end() called already; cannot write.'); + throw new Error('Socket.end() called already; cannot write.'); } var last = this._writeQueue.length - 1; @@ -351,9 +353,9 @@ Stream.prototype.write = function(data /* [encoding], [fd], [cb] */) { // 2. Write data to socket. Return true if flushed. // 3. Slice out remaining // 4. Unshift remaining onto _writeQueue. Return false. -Stream.prototype._writeOut = function(data, encoding, fd, cb) { +Socket.prototype._writeOut = function(data, encoding, fd, cb) { if (!this.writable) { - throw new Error('Stream is not writable'); + throw new Error('Socket is not writable'); } var buffer, off, len; @@ -445,7 +447,7 @@ Stream.prototype._writeOut = function(data, encoding, fd, cb) { leftOver.used = leftOver.length; // used the whole thing... // util.error('data.used = ' + data.used); - //if (!this._writeQueue) initWriteStream(this); + //if (!this._writeQueue) initWriteSocket(this); // data should be the next thing to write. this._writeQueue.unshift(leftOver); @@ -463,7 +465,7 @@ Stream.prototype._writeOut = function(data, encoding, fd, cb) { // Flushes the write buffer out. // Returns true if the entire buffer was flushed. -Stream.prototype.flush = function() { +Socket.prototype.flush = function() { while (this._writeQueue && this._writeQueue.length) { var data = this._writeQueue.shift(); var encoding = this._writeQueueEncoding.shift(); @@ -483,13 +485,13 @@ Stream.prototype.flush = function() { }; -Stream.prototype._writeQueueLast = function() { +Socket.prototype._writeQueueLast = function() { return this._writeQueue.length > 0 ? this._writeQueue[this._writeQueue.length - 1] : null; }; -Stream.prototype.setEncoding = function(encoding) { +Socket.prototype.setEncoding = function(encoding) { var StringDecoder = require('string_decoder').StringDecoder; // lazy load this._decoder = new StringDecoder(encoding); }; @@ -521,7 +523,7 @@ function doConnect(socket, port, host) { function toPort(x) { return (x = Number(x)) >= 0 ? x : false; } -Stream.prototype._onConnect = function() { +Socket.prototype._onConnect = function() { var errno = socketError(this.fd); if (errno == 0) { // connection established @@ -548,8 +550,8 @@ Stream.prototype._onConnect = function() { }; -Stream.prototype._onWritable = function() { - // Stream becomes writable on connect() but don't flush if there's +Socket.prototype._onWritable = function() { + // Socket becomes writable on connect() but don't flush if there's // nothing actually to write if (this.flush()) { if (this._events && this._events['drain']) this.emit('drain'); @@ -559,7 +561,7 @@ Stream.prototype._onWritable = function() { }; -Stream.prototype._onReadable = function() { +Socket.prototype._onReadable = function() { var self = this; // If this is the first recv (pool doesn't exist) or we've used up @@ -623,14 +625,14 @@ Stream.prototype._onReadable = function() { }; -// var stream = new Stream(); -// stream.connect(80) - TCP connect to port 80 on the localhost -// stream.connect(80, 'nodejs.org') - TCP connect to port 80 on nodejs.org -// stream.connect('/tmp/socket') - UNIX connect to socket specified by path -Stream.prototype.connect = function() { +// var socket = new Socket(); +// socket.connect(80) - TCP connect to port 80 on the localhost +// socket.connect(80, 'nodejs.org') - TCP connect to port 80 on nodejs.org +// socket.connect('/tmp/socket') - UNIX connect to socket specified by path +Socket.prototype.connect = function() { var self = this; - initStream(self); - if (self.fd) throw new Error('Stream already opened'); + initSocket(self); + if (self.fd) throw new Error('Socket already opened'); if (!self._readWatcher) throw new Error('No readWatcher'); require('timers').active(socket); @@ -666,25 +668,25 @@ Stream.prototype.connect = function() { }; -Stream.prototype.address = function() { +Socket.prototype.address = function() { return getsockname(this.fd); }; -Stream.prototype.setNoDelay = function(v) { +Socket.prototype.setNoDelay = function(v) { if ((this.type == 'tcp4') || (this.type == 'tcp6')) { setNoDelay(this.fd, v); } }; -Stream.prototype.setKeepAlive = function(enable, time) { +Socket.prototype.setKeepAlive = function(enable, time) { if ((this.type == 'tcp4') || (this.type == 'tcp6')) { var secondDelay = Math.ceil(time / 1000); setKeepAlive(this.fd, enable, secondDelay); } }; -Stream.prototype.setTimeout = function(msecs) { +Socket.prototype.setTimeout = function(msecs) { if (msecs > 0) { require('timers').enroll(this, msecs); if (this.fd) { require('timers').active(this); } @@ -694,13 +696,13 @@ Stream.prototype.setTimeout = function(msecs) { }; -Stream.prototype.pause = function() { +Socket.prototype.pause = function() { if (this._readWatcher) this._readWatcher.stop(); }; -Stream.prototype.resume = function() { - if (this.fd === null) throw new Error('Cannot resume() closed Stream.'); +Socket.prototype.resume = function() { + if (this.fd === null) throw new Error('Cannot resume() closed Socket.'); if (this._readWatcher) { this._readWatcher.stop(); this._readWatcher.set(this.fd, true, false); @@ -708,7 +710,7 @@ Stream.prototype.resume = function() { } }; -Stream.prototype.destroySoon = function() { +Socket.prototype.destroySoon = function() { if (this.flush()) { this.destroy(); } else { @@ -716,7 +718,7 @@ Stream.prototype.destroySoon = function() { } }; -Stream.prototype.destroy = function(exception) { +Socket.prototype.destroy = function(exception) { // pool is shared between sockets, so don't need to free it here. var self = this; @@ -758,7 +760,7 @@ Stream.prototype.destroy = function(exception) { }; -Stream.prototype._shutdown = function() { +Socket.prototype._shutdown = function() { if (!this.writable) { throw new Error('The connection is not writable'); } else { @@ -780,7 +782,7 @@ Stream.prototype._shutdown = function() { }; -Stream.prototype.end = function(data, encoding) { +Socket.prototype.end = function(data, encoding) { if (this.writable) { if (this._writeQueueLast() !== END_OF_FILE) { if (data) this.write(data, encoding); @@ -855,7 +857,7 @@ function Server(/* [ options, ] listener */) { var options = { fd: peerInfo.fd, type: self.type, allowHalfOpen: self.allowHalfOpen }; - var s = new Stream(options); + var s = new Socket(options); s.remoteAddress = peerInfo.address; s.remotePort = peerInfo.port; s.type = self.type;