Fork me on GitHub

Node.js — Документация

Содержание

TCP / Сеть

Модуль net предоставляет асинхронные методы для работы с сетью. Он включает методы для создания как серверов, так и клиентов (называемых потоками). Вы может использовать этот модуль вызвав require("net").

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

Создаёт новый TCP сервер. Аргумент connection_listener автоматически становится обработчиком события 'connection'.

Параметр options содержит свойства сервера со следующими значениями по умолчанию:

{ allowHalfOpen: false
}

Если allowHalfOpen равно true, то сокет не буждет автоматически посылать пакет FIN при получении его от адресата. Сокет будет становиться доступным только для записи. Необходимо вручную вызвать метод end() для закрытия сокета. См. описанеи события 'end' для более подробной информации.

net.createConnection(arguments...)

Создаёт новый сокет. Когда соединение установлено, будет сгенерировано событие 'connect'.

Аргументы для этого метода определяются типом соединения:

net.Server

Этот класс используется для создания TCP или UNIX сервера.

Вот простой пример сервера, который возвращает полученный запрос и слушает на порту 8124:

var net = require('net');
var server = net.createServer(function (c) {
  c.write('hello\r\n');
  c.pipe(c);
});
server.listen(8124, 'localhost');

Проверить работу сервера можно с помощью telnet:

telnet localhost 8124

Чтобы слушать сокет '/tmp/echo.sock', последнюю строку скрипта надо заменить на

server.listen('/tmp/echo.sock');

Для подключения к UNIX-сокеты используйте nc:

nc -U /tmp/echo.sock

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

Начинает принимать соединения на указанном порту port и имени хоста host. Если host пропущен, сервер будет принимать соединения на каждом IPv4-адресе (INADDR_ANY).

Эта функция асинхронна. Последний параметр callback будет вызван когда сервер начнёт принимать соединения.

server.listen(path, [callback])

Запускает сервер слушающий UNIX-сокет по указанному адресу path.

Эта функция асинхронна. Последний параметр callback будет вызван когда сервер начнёт принимать соединения.

Часто пользователи сообщают об ошибке EADDRINUSE. Она означает, что на этом порту уже запущен другой сервер. Одним из способов обработки ошибки EADDRINUSE является ожидание в течении, напрмиер, одной секунды и повторная попытка вызова server.listen. Это можно сделать с помощью следующего кода:

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 имеют установленную опцию SO_REUSEADDR.

server.listenFD(fd)

Запускает сервер, слушающий указанный файловый дескриптор.

Для указанного файлового дескриптора должны быть уже выполнены системные вызовы bind(2) и listen(2). Кроме того, он должен быть неблокирующим, это устанавливается с помощью fcntl(fd, F_SETFL, O_NONBLOCK).

server.pause([msecs])

Приостанавливает приём подключений на указанное количество миллисекунд (по умолчанию секунда). Это может быть использовано для регулирования количества новых подключений во время DoS атаки.

server.close()

Прекращает приём соединений сервером. Эта функция асинхронна, сервер полностью закрывается только после генерации события 'close'.

server.address()

Возвращает адрес, к которому привязан сервер. Удобно использовать, если выбор адреса предоставляется системе. Возвращает объект с двумя свойствами: {"address":"127.0.0.1", "port":2121}.

Пример:

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);
});

server.maxConnections

Установите это свойство, если хотите запретить серверу принимать больше определённого числа соединений единовременно.

server.connections

Текущее число соединений с сервером.

net.Server — экземпляр EventEmitter со следующими событиями:

Событие: 'connection'

function (socket) {}

Генерируется при новом соединении. socket — экземпляр net.Socket.

Событие: 'close'

function () {}

Генерируется при завершении работы сервера.

net.Socket

Этот объект — абстракция TCP порта или UNIX сокета. Экземпляр net.Socket имеет возможность как чтения, так и записи. Он может быть создан и использован как клиентом (с помощью connect()) либо создан внутри Node и передан пользователю через обработчик события 'connection'.

new net.Socket([options])

Создаёт новый объект сокета.

Объект options может содержать следующие поля со значениями по умолчанию:

{ fd: null
  type: null
  allowHalfOpen: false
}

Параметр fd позволяет вам указать существующий файловый дескриптор для создания сокета. Параметр type определяет протокол и может равняться 'tcp4', 'tcp6' или 'unix'. Параметр allowHalfOpen более подробно описан в функциях createServer() и событии 'end' сокета.

socket.connect(port, [host])

socket.connect(path)

Открывает TCP-соединение с указанным портом port и адресом host. Если второй параметр не задан, предполагается значение localhost. Если указан параметр path, то создаёт соединение с Unix-сокетом path.

Обычно этот метод не нужен. Используйте его только если поток закрыт и вы хотите повторно использовать тот же объект для соединения с другим сервером.

Эта функция асинхронна. Когда генерируется событие 'connect', соединение установлено. Если при соединении возникли проблемы, событие 'connect' не будет сгенерировано, вместо него будет сгенерировано событие 'error' с аргументом исключения.

Функция callback будет добавлена как обработчик события 'connect'.

socket.bufferSize

net.Socket имеет свойство, которое постоянно используется в socket.write(). Это нужно для быстрой работы Node. Компьютер не может самостоятельно определить, сколько данных реально записано в сокет, так как сетевые соединения могут быть очень медленными. Node содержит очередь записи для сокетов и производит её при первой же возможности. (Внутри это представялет из себя polling файлового дескриптора сокета на предмет возможности записи).

ЕСледствием этой внутренней буферизации является возможное увеличение затрат памяти. Это совйство (bufferSize) показывает количество символов, которые содержатся на данный момент в очереди на запись. (Количество символов примерно равно количеству байтов, однако в буфере могут находиться строки и тогда это не совсем верно).

Если вы наблюдаете большую величину bufferSize или её быстрое увеличение, то вы можете попробовать посылать данные порциями ("throttle"), используя методы pause() и resume()`.

socket.setEncoding(encoding=null)

Задаёт кодировку ('ascii', 'utf8' или 'base64') для принимаемых данных.

socket.setSecure([credentials])

Эта функция удалена в v0.3. Она использовалась для установки защищённого соединения. См. модуль TLS с описанием нового API.

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

Отправляет данные в поток. Второй параметр означает кодировку, если первым параметром передана строка. По умолчанию используется UTF-8.

Возвращает true если все данные были успешно переданы в буфер ядра. Возвращает false если все данные или их часть были помещены в очередь в памяти. Событие 'drain' будет сгенерировано когда буфер ядра снова будет пуст.

Необязательый параметр-функци callback будет вызвана после завершения записи данных.

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

UNIX-сокеты позволяют передавать через них файловые дескрипторы между приложениями. Для этого достаточно передать параметр fileDescriptor и ожидать события 'fd' во втором приложении.

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

Наполовину закрывает соединение, т.е. отправляет пакет FIN. Возможно сервер ещё получит какие-то данные.

Если определён аргумент data, то этот вызов эквивалентен последовательному вызову socket.write(data, encoding) и socket.end().

socket.destroy()

Закрывает сокет таким образом чтобы в нём больше не происходило ввода-вывода. Необходимо только для закрытия соединения в случае серьёзных ошибок.

socket.pause()

Приостанавливает чтение данных. Т.е. события 'data' не будут генерироваться. Используется при приёме файлов.

socket.resume()

Возобновляет чтение данных после вызова pause().

socket.setTimeout(timeout, [callback])

Устанавливает таймаут в timeout миллисекунд бездействия сокета. По умолчанию net.Stream не имеет таймаута.

Если сокет не будет проявлять активности указанное количество миллисекунд будет сгенерировано событие 'timeout', но само соединение не будет затронуто. Пользователь должен самостоятельно вызвать end() или destroy() для закрытия сокета.

Если в качестве timeout передан 0, существующий таймаут перестаёт действовать.

Необязательный аргумент callback будет добавлен в качестве обработчика события 'timeout'.

socket.setNoDelay(noDelay=true)

Выключает алгоритм Нагла. По умолчанию TCP-соединения используют алгоритм Нагла, собирая данные в буфер перед отправкой. Установка noDelay приведёт к немедленной отправке всех данных, передаваемых в stream.write().

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

Включает/выключает функционал keep-alive, и дополнительно позволяет установить начальную задержку после которой будет отправлен первый пакет проверки соединения при неактивности. Значение initialDelay (в миллисекундах) означает интервал между последним отправленным пакетом и первой проверкой соединения. Установка initialDelay в 0 оставит в силе предыдущее значение.

socket.address()

Возвращает адрес, к которому привязан сокет. Удобно использовать, если выбор адреса предоставляется системе. Возвращает объект с двумя свойствами: {"address":"127.0.0.1", "port":2121}.

socket.remoteAddress

Строковое представление удалённого IP адреса. Например, '74.125.127.100' или '2001:4860:a005::68'.

Это свойство доступно только для соединений сервер-сервер.

Экземпляры net.Stream — экземпляры EventEmitter со следующими событиями:

Событие: 'connect'

function () { }

Генерируется после успешной установки соединения. См. connect().

Событие: 'data'

function (data) { }

Генерируется при приёме данных. Аргумент data будет экземпляром Buffer или String. Кодировка передаваемых данных устанавливается методом socket.setEncoding(). (См. секцию о потоках с возможностью чтения для более подробной информации.)

Событие: 'end'

function () { }

Генерируется когда другой участник соединения посылает пакет FIN.

По умолчанию (allowHalfOpen == false) сокет уничтожает свой файловый дескриптор после завершения обработки очереди записи. Но если установить allowHalfOpen == true, то поток не будет автоматически завершаться (end()), т.е. пользоввателю требуется вручную вызвать end().

Событие: 'timeout'

function () { }

Генерируется если сокет долгое время не используется. Это просто уведомление о длительной неактивности сокета. Пользователь должен сам закрыть соединение.

См. также: socket.setTimeout().

Событие: 'drain'

function () { }

Генерируется когда буфер записи становится пустым (все данные, переданные в поток, были отправлены получателю). Может быть использоваться для отправки файлов.

Событие: 'error'

function (exception) { }

Генерируется при возникновении ошибки. Сразу после этого будет сгенерировано событие 'close'.

Событие: 'close'

function (had_error) { }

Генерируется один раз когда поток полностью закрывается. Аргумент had_error — двоичное значение, устанавливаемое в true если поток был закрыт из за ошибки передачи.

net.isIP

net.isIP(input)

Проверяет. является ли input валидным IP адресом. Возвращает 0 для неверных строк, 4 для IPv4 адресов и 6 для IPv6 адресов.

net.isIPv4(input)

Возвращает true если input является IPv4 адресов, в осатльных случаях false.

net.isIPv6(input)

Возвращает true если input является IPv6 адресов, в осатльных случаях false.