穩(wěn)定性: 3 - 穩(wěn)定

net 模塊提供了異步網(wǎng)絡(luò)封裝，它包含了創(chuàng)建服務器/客戶端的方法（調(diào)用 streams）。可以通過調(diào)用 require('net') 包含這個模塊。

net.createServer([options][, connectionListener])

創(chuàng)建一個 TCP 服務器。參數(shù) connectionListener 自動給 'connection' 事件創(chuàng)建監(jiān)聽器。

options 包含有以下默認值:

{
  allowHalfOpen: false,
  pauseOnConnect: false
}

如果 allowHalfOpen = true， 當另一端 socket 發(fā)送 FIN 包時 socket 不會自動發(fā)送 FIN 包。socket 變?yōu)椴豢勺x，但仍可寫。你需要顯式的調(diào)用 end() 方法。更多信息參見 'end' 事件。

如果 pauseOnConnect = true,當連接到來的時候相關(guān)聯(lián)的 socket 將會暫停。它允許在初始進程不讀取數(shù)據(jù)情況下，讓連接在進程間傳遞。調(diào)用 resume() 從暫停的 socket 里讀取數(shù)據(jù)。

下面是一個監(jiān)聽 8124 端口連接的應答服務器的例子：

var net = require('net');
var server = net.createServer(function(c) { //'connection' listener
  console.log('client connected');
  c.on('end', function() {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.listen(8124, function() { //'listening' listener
  console.log('server bound');
});

使用 telnet 來測試:

telnet localhost 8124

要監(jiān)聽 socket t /tmp/echo.sock，僅需要改倒數(shù)第三行代碼：

server.listen('/tmp/echo.sock', function() { //'listening' listener

使用 nc 連接到一個 UNIX domain socket 服務器:

nc -U /tmp/echo.sock必須

net.connect(options[, connectionListener])

net.createConnection(options[, connectionListener])

工廠方法，返回一個新的 'net.Socket'，并連接到指定的地址和端口。

當 socket 建立的時候，將會觸發(fā) 'connect' 事件。

和'net.Socket'有相同的方法。

對于 TCP sockets，參數(shù) options 因為下列參數(shù)的對象：

• port: 客戶端連接到 Port 的端口（必須）。

• host: 客戶端要連接到得主機。默認 'localhost'.

• localAddress: 網(wǎng)絡(luò)連接綁定的本地接口。

• localPort: 網(wǎng)絡(luò)連接綁定的本地端口。

• family : IP 棧版本。默認 4.

對于本地域socket，參數(shù) options因為下列參數(shù)的對象：

• path: 客戶端連接到得路徑(必須).

通用選項:

• 如果 allowHalfOpen = true， 當另一端 socket 發(fā)送 FIN 包時 socket 不會自動發(fā)送 FIN 包。socket 變?yōu)椴豢勺x，但仍可寫。你需要顯式的調(diào)用 end() 方法。更多信息參見 'end' 事件。

  connectListener 參數(shù)將會作為監(jiān)聽器添加到'connect'事件上。

下面是一個用上述方法應答服務器的客戶端例子：

var net = require('net');
var client = net.connect({port: 8124},
    function() { //'connect' listener
  console.log('connected to server!');
  client.write('world!\r\n');
});
client.on('data', function(data) {
  console.log(data.toString());
  client.end();
});
client.on('end', function() {
  console.log('disconnected from server');
});

要連接到 socket /tmp/echo.sock，僅需將第二行代碼改為：

var client = net.connect({path: '/tmp/echo.sock'});

net.connect(port[, host][, connectListener])

net.createConnection(port[, host][, connectListener])

創(chuàng)建一個到端口 port 和 主機 host的 TCP 連接。如果忽略主機 host，則假定為'localhost'。參數(shù) connectListener 將會作為監(jiān)聽器添加到 'connect' 事件。

這是工廠方法，返回一個新的 'net.Socket'。

net.connect(path[, connectListener])

net.createConnection(path[, connectListener])

創(chuàng)建到 path 的 unix socket 連接。 參數(shù) connectListener 將會作為監(jiān)聽器添加到 'connect' 事件上。

這是工廠方法，返回一個新的 'net.Socket'。

Class: net.Server

這個類用來創(chuàng)建一個 TCP 或本地服務器。

server.listen(port[, host][, backlog][, callback])

開始接受指定端口 port 和 主機 host 的連接。如果忽略主機 host， 服務器將會接受任何 IPv4 地址(INADDR_ANY)的直接連接。端口為 0，則會分配一個隨機端口。

積壓量（Backlog）為連接等待隊列的最大長度。實際長度由您的操作系統(tǒng)通過 sysctl 設(shè)定，比如 linux 上的tcp_max_syn_backlog 和 somaxconn。這個參數(shù)默認值是 511 (不是 512)。

這是異步函數(shù)。當服務器被綁定時會觸發(fā) 'listening' 事件。最后一個參數(shù) callback 將會作為'listening' 事件的監(jiān)聽器。

有些用戶會遇到 EADDRINUSE 錯誤，它表示另外一個服務器已經(jīng)運行在所請求的端口上。處理這個情況的辦法是等一段事件再重試：

server.on('error', function (e) {
  if (e.code == 'EADDRINUSE') {
    console.log('Address in use, retrying...');
    setTimeout(function () {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

(注意: Node 中的所有 socket 已設(shè)置了 SO_REUSEADDR )

server.listen(path[, callback])

• path {String}
• callback {Function}

啟動一個本地 socket 服務器，監(jiān)聽指定 path 的連接。

這是異步函數(shù)。綁定服務器后，會觸發(fā) 'listening' 事件。最后一個參數(shù) callback 將會作為'listening' 事件的監(jiān)聽器。

UNIX 上，本地域通常默認為 UNIX 域。參數(shù) path 是文件系統(tǒng)路徑，就和創(chuàng)建文件時一樣，它也遵從命名規(guī)則和權(quán)限檢查，并且在文件系統(tǒng)里可見，并持續(xù)到關(guān)閉關(guān)聯(lián)。

Windows上，本地域通過命名管道實現(xiàn)。路徑必須是以 \\?\pipe\ 或 \\.\pipe\ 入口。任意字符串都可以，不過之后進行相同的管道命名處理，比如解決 .. 序列。管道命名空間是平的。管道不會一直持久，當最后一個引用關(guān)閉的時候，管道將會移除。不要忘記 javascript 字符字符串轉(zhuǎn)義要求路徑使用雙反斜杠，比如：

net.createServer().listen(
    path.join('\\\\?\\pipe', process.cwd(), 'myctl'))

server.listen(handle[, callback])

• handle {Object}

• callback {Function}

  handle 對象可以設(shè)置成 server 或 socket（任意以下劃線 _handle 開頭的成員），或者是 {fd: <n>} 對象。

這將是服務器用指定的句柄接收連接，前提是文件描述符或句柄已經(jīng)綁定到端口或域 socket。

Windows 不支持監(jiān)聽文件句柄。

這是異步函數(shù)。當服務器已經(jīng)被綁定，將會觸發(fā)'listening' 事件。最后一個參數(shù) callback 將會作為 'listening' 事件的監(jiān)聽器。

server.listen(options[, callback])

• options {Object} - 必須. 支持以下屬性:
  • port {Number} - 可選.
  • host {String} - 可選.
  • backlog {Number} - 可選.
  • path {String} - 可選.
  • exclusive {Boolean} - 可選.
• callback {Function} - 可選.

options 的屬性：端口 port, 主機 host, 和 backlog, 以及可選參數(shù) callback 函數(shù), 他們在一起調(diào)用server.listen(port, [host], [backlog], [callback])。還有，參數(shù) path 可以用來指定 UNIX socket。

如果參數(shù) exclusive 是false（默認值），集群進程將會使用同一個句柄，允許連接共享。當參數(shù)exclusive 是 true 時，句柄不會共享，如果共享端口會返回錯誤。監(jiān)聽獨家端口例子如下：

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true
});

server.close([callback])

服務器停止接收新的連接，保持現(xiàn)有連接。這是異步函數(shù)，當所有連接結(jié)束的時候服務器會關(guān)閉，并會觸發(fā) 'close' 事件。你可以傳一個回調(diào)函數(shù)來監(jiān)聽 'close' 事件。如果存在，將會調(diào)用回調(diào)函數(shù)，錯誤（如果有）作為唯一參數(shù)。

server.address()

操作系統(tǒng)返回綁定的地址，協(xié)議族名和服務器端口。查找哪個端口已經(jīng)被系統(tǒng)綁定時，非常有用。返回的對象有3個屬性，比如： { port: 12346, family: 'IPv4', address: '127.0.0.1' }

例如:

var server = net.createServer(function (socket) {
  socket.end("goodbye\n");
});

// grab a random port.
server.listen(function() {
  address = server.address();
  console.log("opened server on %j", address);
});

在 'listening' 事件觸發(fā)前，不要調(diào)用 server.address()。

server.unref()

如果這是事件系統(tǒng)中唯一一個活動的服務器，調(diào)用 unref 將允許程序退出。如果服務器已被 unref，則再次調(diào)用 unref 并不會產(chǎn)生影響。

server.ref()

與 unref 相反，如果這是唯一的服務器，在之前被 unref 了的服務器上調(diào)用 ref 將不會讓程序退出（默認行為）。如果服務器已經(jīng)被 ref，則再次調(diào)用 ref 并不會產(chǎn)生影響。

server.maxConnections

設(shè)置這個選項后，當服務器連接數(shù)超過數(shù)量時拒絕新連接。

一旦已經(jīng)用 child_process.fork() 方法將 socket 發(fā)送給子進程， 就不推薦使用這個選項。

server.connections

已經(jīng)拋棄這個函數(shù)。請用 server.getConnections() 代替。服務器上當前連接的數(shù)量。

當調(diào)用 child_process.fork() 發(fā)送一個 socket 給子進程時，它將變?yōu)?null 。 要輪詢子進程來獲取當前活動連接的數(shù)量，請用 server.getConnections 代替.

server.getConnections(callback)

異步獲取服務器當前活躍連接的數(shù)量。當 socket 發(fā)送給子進程后才有效；

回調(diào)函數(shù)有 2 個參數(shù) err 和 count。

net.Server 是事件分發(fā)器 EventEmitter， 有以下事件:

事件： 'listening'

當服務器調(diào)用 server.listen 綁定后會觸發(fā)。

事件：'connection'

• {Socket object} 連接對象

當新連接創(chuàng)建后會被觸發(fā)。socket 是 net.Socket實例。

事件： 'close'

服務器關(guān)閉時會觸發(fā)。注意，如果存在連接，這個事件不會被觸發(fā)直到所有的連接關(guān)閉。

事件： 'error'

• {Error Object}

發(fā)生錯誤時觸發(fā)。'close' 事件將被下列事件直接調(diào)用。請查看 server.listen 例子。

Class: net.Socket

這個對象是 TCP 或 UNIX Socket 的抽象。net.Socket 實例實現(xiàn)了一個雙工流接口。 他們可以在用戶創(chuàng)建客戶端(使用 connect())時使用, 或者由 Node 創(chuàng)建它們，并通過 connection 服務器事件傳遞給用戶。

new net.Socket([options])

構(gòu)造一個新的 socket 對象。

options 對象有以下默認值:

{ fd: null
  allowHalfOpen: false,
  readable: false,
  writable: false
}

參數(shù) fd 允許你指定一個存在的文件描述符。將 readable 和（或） writable 設(shè)為 true ，允許在這個 socket 上讀和（或）寫（注意，僅在參數(shù) fd 有效時）。關(guān)于 allowHalfOpen，參見createServer() 和 'end' 事件。

socket.connect(port[, host][, connectListener])

socket.connect(path[, connectListener])

使用傳入的 socket 打開一個連接。如果指定了端口 port 和 主機 host，TCP socket 將打開 socket 。如果忽略參數(shù) host，則默認為 localhost。如果指定了 path ，socket 將會被指定路徑的 unix socket 打開。

通常情況不需要使用這個函數(shù)，比如使用 net.createConnection 打開 socket。只有你實現(xiàn)了自己的 socket 時才會用到。

這是異步函數(shù)。當 'connect' 事件被觸發(fā)時， socket 已經(jīng)建立。如果這是問題連接， 'connect' 事件不會被觸發(fā)， 將會拋出 'error'事件。

參數(shù) connectListener 將會作為監(jiān)聽器添加到 'connect' 事件。

socket.bufferSize

是 net.Socket 的一個屬性，用于 socket.write() 。幫助用戶獲取更快的運行速度。計算機不能一直處于寫入大量數(shù)據(jù)狀態(tài)--網(wǎng)絡(luò)連接可能太慢。Node 在內(nèi)部會將排隊數(shù)據(jù)寫入到socket，并在網(wǎng)絡(luò)可用時發(fā)送。（內(nèi)部實現(xiàn)：輪詢 socket 的文件描述符直到變?yōu)榭蓪懀?/p>

這種內(nèi)部緩沖的缺點是會增加內(nèi)存使用量。這個屬性表示當前準備寫的緩沖字符數(shù)。（字符的數(shù)量等于準備寫入的字節(jié)的數(shù)量，但是緩沖區(qū)可能包含字符串，這些字符串是惰性編碼的，所以準確的字節(jié)數(shù)還無法知道）。

遇到很大增長很快的 bufferSize 時，用戶可用嘗試用pause() 和 resume()來控制字符流。

socket.setEncoding([encoding])

設(shè)置 socket 的編碼為可讀流。更多信息參見stream.setEncoding()

socket.write(data[, encoding][, callback])

在 socket 上發(fā)送數(shù)據(jù)。第二個參數(shù)指定了字符串的編碼，默認是 UTF8 編碼。

如果所有數(shù)據(jù)成功刷新到內(nèi)核緩沖區(qū)，返回 true。如果數(shù)據(jù)全部或部分在用戶內(nèi)存里，返回 false 。當緩沖區(qū)為空的時候會觸發(fā) 'drain' 。

當數(shù)據(jù)最終被完整寫入的的時候，可選的 callback 參數(shù)會被執(zhí)行，但不一定會馬上執(zhí)行。

socket.end([data][, encoding])

半關(guān)閉 socket。例如，它發(fā)送一個 FIN 包?？赡芊掌魅栽诎l(fā)送數(shù)據(jù)。

如果參數(shù) data 不為空，等同于調(diào)用 socket.write(data, encoding) 后再調(diào)用 socket.end()。

socket.destroy()

確保沒有 I/O 活動在這個套接字上。只有在錯誤發(fā)生情況下才需要。（處理錯誤等等）。

socket.pause()

暫停讀取數(shù)據(jù)。就是說，不會再觸發(fā) data 事件。對于控制上傳非常有用。

socket.resume()

調(diào)用 pause() 后想恢復讀取數(shù)據(jù)。

socket.setTimeout(timeout[, callback])

socket 閑置時間超過 timeout 毫秒后 ，將 socket 設(shè)置為超時。

觸發(fā)空閑超時事件時，socket 將會收到 'timeout'事件，但是連接不會被斷開。用戶必須手動調(diào)用 end() 或 destroy() 這個socket。

如果 timeout = 0, 那么現(xiàn)有的閑置超時會被禁用

可選的 callback 參數(shù)將會被添加成為 'timeout' 事件的一次性監(jiān)聽器。

socket.setNoDelay([noDelay])

禁用納格（Nagle）算法。默認情況下 TCP 連接使用納格算法，在發(fā)送前他們會緩沖數(shù)據(jù)。將 noDelay 設(shè)置為 true 將會在調(diào)用 socket.write() 時立即發(fā)送數(shù)據(jù)。noDelay 默認值為 true。

socket.setKeepAlive([enable][, initialDelay])

禁用/啟用長連接功能，并在發(fā)送第一個在閑置 socket 上的長連接 probe 之前，可選地設(shè)定初始延時。默認為 false。

設(shè)定 initialDelay （毫秒），來設(shè)定收到的最后一個數(shù)據(jù)包和第一個長連接probe之間的延時。將 initialDelay 設(shè)為0，將會保留默認（或者之前）的值。默認值為0.

socket.address()

操作系統(tǒng)返回綁定的地址，協(xié)議族名和服務器端口。返回的對象有 3 個屬性，比如{ port: 12346, family: 'IPv4', address: '127.0.0.1' }。

socket.unref()

如果這是事件系統(tǒng)中唯一一個活動的服務器，調(diào)用 unref 將允許程序退出。如果服務器已被 unref，則再次調(diào)用 unref 并不會產(chǎn)生影響。

socket.ref()

與 unref 相反，如果這是唯一的服務器，在之前被 unref 了的服務器上調(diào)用 ref 將不會讓程序退出（默認行為）。如果服務器已經(jīng)被 ref，則再次調(diào)用 ref 并不會產(chǎn)生影響。

socket.remoteAddress

遠程的 IP 地址字符串，例如：'74.125.127.100' or '2001:4860:a005::68'.

socket.remoteFamily

遠程IP協(xié)議族字符串，比如 'IPv4' or 'IPv6'.

socket.remotePort

遠程端口，數(shù)字表示，例如：80 or 21.

socket.localAddress

網(wǎng)絡(luò)連接綁定的本地接口 遠程客戶端正在連接的本地 IP 地址，字符串表示。例如，如果你在監(jiān)聽'0.0.0.0'而客戶端連接在'192.168.1.1'，這個值就會是 '192.168.1.1'。

socket.localPort

本地端口地址，數(shù)字表示。例如：80 or 21.

socket.bytesRead

接收到得字節(jié)數(shù)。

socket.bytesWritten

發(fā)送的字節(jié)數(shù)。

net.Socket 是事件分發(fā)器 EventEmitter的實例， 有以下事件:

事件： 'lookup'

在解析域名后，但在連接前，觸發(fā)這個事件。對 UNIX sokcet 不適用。

• err {Error | Null} 錯誤對象。 參見 dns.lookup().
• address {String} IP 地址。
• family {String | Null} 地址類型。 參見 dns.lookup().

事件： 'connect'

當成功建立 socket 連接時觸發(fā)。 參見 connect().

事件： 'data'

• {Buffer object}

當接收到數(shù)據(jù)時觸發(fā)。參數(shù) data 可以是 Buffer 或 String。使用 socket.setEncoding()設(shè)定數(shù)據(jù)編碼。(更多信息參見 Readable Stream )。

當 Socket 觸發(fā)一個 'data' 事件時，如果沒有監(jiān)聽器，數(shù)據(jù)將會丟失。

事件： 'end'

當 socket 另一端發(fā)送 FIN 包時，觸發(fā)該事件。

默認情況下(allowHalfOpen == false)，一旦 socket 將隊列里的數(shù)據(jù)寫完畢，socket 將會銷毀它的文件描述符。如果 allowHalfOpen == true,socket 不會從它這邊自動調(diào)用 end()，使的用戶可以隨意寫入數(shù)據(jù)，而讓用戶端自己調(diào)用 end()。

事件： 'timeout'

當 socket 空閑超時時觸發(fā)，僅是表明 socket 已經(jīng)空閑。用戶必須手動關(guān)閉連接。

參見 : socket.setTimeout()

事件： 'drain'

當寫緩存為空得時候觸發(fā)?？捎脕砜刂粕蟼?。

參見 : socket.write() 的返回值。

事件： 'error'

• {Error object}

錯誤發(fā)生時觸發(fā)。以下事件將會直接觸發(fā) 'close' 事件。

事件： 'close'

• had_error {Boolean} 如果 socket 傳輸錯誤，為 true

當 socket 完全關(guān)閉時觸發(fā)。參數(shù) had_error 是 boolean，它表示是否因為傳輸錯誤導致 socket 關(guān)閉。

net.isIP(input)

測試是否輸入的為 IP 地址。字符串無效時返回 0。 IPV4 情況下返回 4， IPV6情況下返回 6.

net.isIPv4(input)

如果輸入的地址為 IPV4， 返回 true，否則返回 false。

net.isIPv6(input)

如果輸入的地址為 IPV6， 返回 true，否則返回 false。