Node v0.2.6

node(1)

1. node(1)
3. node(1)

NAME

node -- evented I/O for V8 JavaScript

Краткий обзор

Пример web сервера, написанного с помощью Node и отвечающего строкой 'Hello World':

var http = require('http');

http.createServer(function (request, response) {
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

Чтобы запустить сервер, поместите код в файл с названием example.js и выполните его программой node

> node example.js
Server running at http://127.0.0.1:8124/

Все примеры в этом руководстве можно запустить таким же образом.

Стандартные модули

Вместе с Node поставляется несколько стандартных встроенных модулей, большинство из которых описано ниже. Стандартный способ использования этих модулей — вызов require('name') и сохранение возвращаемого объекта в локальной переменной с именем, совпадающим с именем модуля.

Пример:

var sys = require('sys');

Также возможно расширение Node другими модулями. См. 'Modules'

Буферы (Buffers)

Чистый JavaScript поддерживает Unicode, но в нём нет средств для работы с двоичными данными. При работе с TCP или файловой системой часто необходимо работать именно с потоками двоичных данных. В Node предусмотрено несколько средств управления, создания и приёма двоичных потоков.

Бинарные данные хранятся в экземплярах класса Buffer. Buffer похож на массив целых чисел, но ему соответствует область памяти, выделенная вне стандартной кучи V8. Размер Buffer невозможно изменить после создания. Подключить класс можно с помощью require('buffer').Buffer.

При преобразовании между буферами и строками JavaScript требуется явно указывать метод кодирования символов. Node поддерживает 3 кодировки для строк: UTF-8 ('utf8'), ASCII ('ascii') и двоичную ('binary').

• 'ascii' — только для 7-битных ASCII-строк. Этот метод кодирования очень быстрый, и будет сбрасывать старший бит символа, если тот установлен.

• 'utf8' — Unicode-символы. Многие веб-страницы и документы используют UTF-8.

• 'binary' — устаревший способ. Хранит двоичные данные в строке используя младшие 8 бит каждого символа. Не используйте эту кодировку.

new Buffer(size)

Создаёт новый буфер размера size байт.

new Buffer(array)

Создаёт новый буфер, используя массив array байт.

new Buffer(str, encoding = 'utf8')

Создаёт новый буфер, содержащий строку str в кодировке encoding.

buffer.write(string, offset=0, encoding='utf8')

Записывает строку string в буфер по смещению offset от его начала с использованием указанной кодировки. Возвращает количество записанных байт. Если buffer не имеет достаточно места для сохранения всей строки метод запишет только её часть. В случае если кодировка строки — 'utf8', метод не будет записывать частичные символы.

Пример: записать utf8 строку в буфер, потом напечатать его.

Buffer = require('buffer').Buffer;
buf = new Buffer(256);
len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(len + " bytes: " + buf.toString('utf8', 0, len));

// 12 bytes: ½ + ¼ = ¾

buffer.toString(encoding, start, end)

Декодирует и возвращает строку из данных буфера, закодированных в кодировке encoding начиная с start и заканчивая позицией end.

См. пример buffer.write() выше.

buffer[index]

Получает или устанавливает байт на позиции index. Значения соответствуют индивидуальным байтам и могут лежать в пределах от 0x00 до 0xFF в шестнадцатиричной записи и от 0 до 255 в десятичной.

Пример: скопировать ASCII строку в буфер, байт за байтом.

var Buffer = require('buffer').Buffer,
  str = "node.js",
  buf = new Buffer(str.length),
  i;

for (i = 0; i < str.length ; i += 1) {
  buf[i] = str.charCodeAt(i);
}

console.log(buf);

// node.js

Buffer.byteLength(string, encoding)

Возвращает количество байт в строке. Это не то же самое что String.prototype.length так как этот метод возвращает число символов в строке.

Пример:

var Buffer = require('buffer').Buffer,
  str = '\u00bd + \u00bc = \u00be';

console.log(str + ": " + str.length + " characters, " +
  Buffer.byteLength(str, 'utf8') + " bytes");

// ½ + ¼ = ¾: 9 символов, 12 байт

buffer.length

Размер буфера в байтах. Заметьте, что это значение не всегда соответствует размеру содержимого. length возвращает объем памяти, зарезервированный для объекта буфера. Это значение не изменяется при изменении содержимого буфера.

var Buffer = require('buffer').Buffer,
  buf = new Buffer(1234);

console.log(buf.length);
buf.write("some string", "ascii", 0);
console.log(buf.length);

// 1234
// 1234

buffer.copy(targetBuffer, targetStart, sourceStart, sourceEnd)

Копирует данные между буферами с помощью memcpy().

Пример: создать два буфера, потом скопировать buf1 с байта 16 по байт 19 в buf2, начиная с 8-го байта в buf2.

var Buffer = require('buffer').Buffer,
  buf1 = new Buffer(26),
  buf2 = new Buffer(26),
  i;

for (i = 0 ; i < 26 ; i += 1) {
  buf1[i] = i + 97; // 97 is ASCII a
  buf2[i] = 33; // ASCII !
}

buf1.copy(buf2, 8, 16, 20);
console.log(buf2.toString('ascii', 0, 25));

// !!!!!!!!qrst!!!!!!!!!!!!!

buffer.slice(start, end)

Возвращает новый буфер, указывающий на ту же область памяти что предыдущий, но начиная с start и заканчивая end байтами.

Изменение содержимого нового буфера затронет содержимое старого!

Пример: построить буфер с ASCII-алфавитом, вырезать часть в новый буфер, затем изменить 1 часть в оригинальном буфере.

var Buffer = require('buffer').Buffer,
  buf1 = new Buffer(26), buf2,
  i;

for (i = 0 ; i < 26 ; i += 1) {
  buf1[i] = i + 97; // 97 is ASCII a
}

buf2 = buf1.slice(0, 3);
console.log(buf2.toString('ascii', 0, buf2.length));
buf1[0] = 33;
console.log(buf2.toString('ascii', 0, buf2.length));

// abc
// !bc

Источник событий (EventEmitter)

Множество объектов в Node генерируют события: TCP-сервер генерирует событие при каждом получении потока данных, дочерний процесс генерирует событие при выходе. Все объекты, генерирующие события, являются экземплярами events.EventEmitter.

События представлены строками в стиле camel-case. Вот несколько примеров: 'stream', 'data', 'messageBegin'.

К объектам могут быть присоединены функции, которые будут выполняться при генерации события. Эти функции называются обработчиками (listeners).

Класс EventEmitter находится в модуле 'events': require(events').EventEmitter.

Все источники событий генерируют событие 'newListener', когда к ним добавляются новые обработчики.

Когда источник событий сталкивается с ошибкой, типичное поведение — сгенерировать событие ошибки 'error'. События ошибки особенные — если им не назначен обработчик, то они выводят на экран стек вызовов (stack trace) и завершают программу.

Событие: 'newListener'

function (event, listener) { }

Это событие вызывается каждый раз при добавлении обработчика события.

Событие: 'error'

function (exception) { }

Если произошла ошибка, генерируется это событие. Оно отличается от других — если ему не назначено ни одного обработчика Node прекратит выполнение скрипта и напечатает текущий стек как для необработанного исключения.

emitter.addListener(event, listener)

Добавляет обработчик в конец массива обработчиков указанного события.

server.addListener('stream', function (stream) {
  console.log('someone connected!');
});

emitter.removeListener(event, listener)

Удаляет обработчик из массива обработчиков указанного события. Внимание: изменяет индексы в массиве обработчиков после указанного обработчика.

emitter.removeAllListeners(event)

Удаляет все обработчики из массива обработчиков для указанного события.

emitter.listeners(event)

Возвращает массив обработчиков для указанного события. Этот массив может быть использован, например, для удаления обработчиков.

emitter.emit(event, arg1, arg2, ...)

Выполнит все обработчики события по порядку с указанными аргументами.

Потоки

Поток — это абстрактный интерфейс, реализуемый многими объектами в Node. Например, запрос к HTTP-серверу является потоком, также как stdout. Потоки могут быть с возможностью чтения, записи или и того и другого. Все потоки являются экземплярами EventEmitter.

Поток с возможностью чтения

Поток с возможностью чтения имеет следующие методы, свойства и события.

Событие: 'data'

function (data) { }

Событие 'data' передаёт обработчику либо Buffer (по умолчанию), либо строку, если предварительно был вызван setEncoding().

Событие: 'end'

function () { }

Генерируется когда поток получает символ конца файла EOF (FIN в терминологии TCP). Означает что событий 'data' больше не предвидится. Если поток также имеет возможность записи, писать данные можно и дальше.

Событие: 'error'

function (exception) { }

Генерируется если при приёме данных произошла ошибка.

Событие: 'close'

function () { }

Генерируется когда соответствующий потоку файловый дескриптор закрывается. Не все потоки генерируют это событие. Например, входящий HTTP запрос не генерирует 'close'.

Событие: 'fd'

function (fd) { }

Генерируется когда поток получает файловый дескриптор. Только UNIX потоки поддерживают этот функционал; остальные никогда не генерируют это событие.

stream.setEncoding(encoding)

Заставляет событие 'data' передавать обработчику строку вместо буфера. encoding может быть 'utf8', 'ascii' или 'binary'.

stream.pause()

Прекращает поступление событий 'data'.

stream.resume()

Возобновляет поступление событий 'data' после pause().

stream.destroy()

Закрывает соответствующий потоку файловый дескриптор. Поток больше не будет генерировать событий.

Поток с возможностью записи

У потока с возможностью записи есть следующие методы, свойства и события.

Событие: 'drain'

function () { }

Генерируется после вызова метода write() вернувшего false — сигнал о том что можно писать дальше.

Событие: 'error'

function (exception) { }

Генерируется при ошибке с исключением exception.

Событие: 'close'

function () { }

Генерируется когда закрывается соответствующий потоку дескриптор.

stream.write(string, encoding, [fd])

Записывает строку string в указанной кодировке encoding в поток. Возвращает true если строка попала в буфер ядра. Возвращает false если буфер ядра полон и данные будут отправлены позже. Когда данные будут отправлены и буфер ядра опустеет, будет сгенерировано событие 'drain'. Кодировка по умолчанию принимает значение 'utf8'.

Если указан необязательный параметр fd, он интерпретируется как файловый дескриптор для отправки в поток. Это поддерживается только в UNIX потоках, и просто игнорируется в другом окружении. Когда дескриптор пересылается таким образом, если он будет закрыт до события 'drain' потока, может быть отправлен повреждённый (закрытый) дескриптор.

stream.write(buffer)

То же что и выше, но с использованием буфера.

stream.end()

Закрывает поток отправкой EOF или FIN.

stream.end(string, encoding)

Посылает строку string в указанной кодировке encoding и закрывает поток отправкой EOF или FIN. Так можно уменьшить общее число отправленных пакетов.

stream.end(buffer)

То же что выше но с использованием буфера.

stream.destroy()

Закрывает соответствующий потоку файловый дескриптор. Поток больше не будет генерировать событий.

Глобальные объекты

Эти объекты доступны в глобальной области видимости и могут быть использованы в любом месте кода.

global

Глобальный объект.

process

Объект процесса. Большая часть данных процесса находится именно здесь. См. секцию 'process' ниже.

require()

Подключение модулей. См. секцию 'Модули'.

require.paths

Массив путей поиска для require(). Этот массив может быть изменён для добавления пользовательских путей.

Пример: добавить новый путь в начало массива.

require.paths.unshift('/usr/local/node');
console.log(require.paths);
// /usr/local/node,/Users/mjr/.node_libraries

__filename

Имя исполняемого скрипта. Это абсолютный путь, и не всегда это будет то же имя, которое было передано в аргументе командной строки.

__dirname

Имя директории исполняемого скрипта.

Пример: запускаем node example.js из папки /Users/mjr.

console.log(__filename);
console.log(__dirname);
// /Users/mjr/example.js
// /Users/mjr

module

Ссылка на текущий модуль (типа process.Module). В частности, module.exports — то же самое, что и объект exports. См. src/process.js для подробной информации.

process

Объект process — глобальный и может быть использован в любом месте кода. Это экземпляр EventEmitter.

Событие: 'exit'

function () {}

Генерируется перед тем как процесс завершится. Это хорошее место для проверок состояния модуля (например, юнит-тестов). Event loop не будет действовать после завершения обработчика 'exit', так что таймеры использовать нельзя.

Пример обработки события exit:

process.addListener('exit', function () {
  process.nextTick(function () {
   console.log('This will not run');
  });
  console.log('About to exit.');
});

Событие: 'uncaughtException'

function (err) { }

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

Пример обработки события uncaughtException:

process.addListener('uncaughtException', function (err) {
  console.log('Caught exception: ' + err);
});

setTimeout(function () {
  console.log('This will still run.');
}, 500);

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
console.log('This will not run.');

Заметьте, что uncaughtException это очень грубый механизм для управления исключениями. Использование try / catch in your program даст вам больший контроль над выполнением вашего кода. В особенности для программ, предназначенных для постоянной работы, uncaughtException может быть очень полезным механизмом безопасности.

Сигнальные события

function () {}

Генерируются когда процесс получает сигнал. См. sigaction(2) для списка стандартных имён сигналов в POSIX таких как SIGINT, SIGUSR1, и т.д.

Пример обработки сигнала SIGINT:

var stdin = process.openStdin();

process.addListener('SIGINT', function () {
  console.log('Got SIGINT.  Press Control-D to exit.');
});

Простой способ отправки сигнала SIGINT: Control-C в большинстве терминальных программ.

process.stdout

Поток с возможностью записи, представляющий стандартный поток вывода stdout.

Пример: определение console.log

console.log = function (d) {
  process.stdout.write(d + '\n');
};

process.openStdin()

Открывает стандартный поток ввода, возвращает поток с возможностью чтения.

Пример открытия стандартного потока ввода и обработки обоих событий:

var stdin = process.openStdin();

stdin.setEncoding('utf8');

stdin.addListener('data', function (chunk) {
  process.stdout.write('data: ' + chunk);
});

stdin.addListener('end', function () {
  process.stdout.write('end');
});

process.argv

Массив, содержащий аргументы командной строки. Первым элементом будет 'node', вторым — имя JavaScript файла. Следующие элементы будут дополнительными аргументами скрипта.

// print process.argv
process.argv.forEach(function (val, index, array) {
  console.log(index + ': ' + val);
});

В результате получим:

$ node process-2.js one two=three four
0: node
1: /Users/mjr/work/node/process-2.js
2: one
3: two=three
4: four

process.execPath

Абсолютный путь к приложению, запустившему процесс.

process.chdir(directory)

Изменяет текущий рабочий каталог приложения либо генерирует исключение, если изменить каталог не удаётся.

console.log('Starting directory: ' + process.cwd());
try {
  process.chdir('/tmp');
  console.log('New directory: ' + process.cwd());
}
catch (err) {
  console.log('chdir: ' + err);
}

process.compile(code, filename)

Похоже на eval за исключением того что можно указать имя файла filename для более понятных сообщениях об ошибках; код code не имеет доступа к локальной области видимости. Значение filename будет использовано в качестве имени файла если скомпилированный код распечатает содержимое стека.

Пример использования process.compile и eval для выполнения одного и того же кода:

var localVar = 123,
    compiled, evaled;

compiled = process.compile('localVar = 1;', 'myfile.js');
console.log('localVar: ' + localVar + ', compiled: ' + compiled);
evaled = eval('localVar = 1;');
console.log('localVar: ' + localVar + ', evaled: ' + evaled);

// localVar: 123, compiled: 1
// localVar: 1, evaled: 1

process.compile не имеет доступа к локальной области видимости, поэтому localVar не меняется. eval имеет доступ к локальной области видимости, поэтому localVar изменяется.

При синтаксической ошибке в коде process.compile завершает работу node.

См. также: Script

process.cwd()

Возвращает текущую рабочую директорию процесса.

console.log('Current directory: ' + process.cwd());

process.env

Объект, хранящий окружение пользователя. См. environ(7).

process.exit(code)

Завершает процесс с указанным кодом code. Если код пропущен, выходит со стандартным успешным кодом 0.

Чтобы выйти с кодом "ошибка":

process.exit(1);

Оболочка, с помощью которой был запущен скрипт в node, должна получить код ошибки 1.

process.getgid(), process.setgid(id)

Получает/устанавливает групповой индикатор процесса. (См. setgid(2).) Это числовое значение id группы, а не её имя.

console.log('Current gid: ' + process.getgid());
try {
  process.setgid(501);
  console.log('New gid: ' + process.getgid());
}
catch (err) {
  console.log('Failed to set gid: ' + err);
}

process.getuid(), process.setuid(id)

Получает/устанавливает пользователя-владельца процесса. (См. setuid(2).) Это числовой идентификатор, а не имя пользователя.

console.log('Current uid: ' + process.getuid());
try {
  process.setuid(501);
  console.log('New uid: ' + process.getuid());
}
catch (err) {
  console.log('Failed to set uid: ' + err);
}

process.version

Заданное при компиляции свойство, возвращающее версию Node (NODE_VERSION).

console.log('Version: ' + process.version);

process.installPrefix

Заданное при компиляции свойство, хранящее директорию, в которую устанавливали node: NODE_PREFIX.

console.log('Prefix: ' + process.installPrefix);

process.kill(pid, signal)

Отправляет сигнал процессу. pid это идентификатор процесса, signal — строка, обозначающая отправляемый сигнал. Имена сигналов это строки вроде 'SIGINT' или 'SIGUSR1'. Если имя сигнала пропущено, отправлен будет сигнал 'SIGINT'. См. kill(2) для дальнейшей информации.

Заметьте, что хотя функция и называется process.kill, на самом деле она просто отправляет сигнал, как и системная команда kill. Отправляемый сигнал может не только завершать целевой процесс.

Пример процесса, отправляющего сигнал самому себе:

process.addListener('SIGHUP', function () {
  console.log('Got SIGHUP signal.');
});

setTimeout(function () {
  console.log('Exiting.');
  process.exit(0);
}, 100);

process.kill(process.pid, 'SIGHUP');

process.pid

Идентификатор процесса (PID).

console.log('This process is pid ' + process.pid);

process.platform

Платформа, на которой выполняется node. 'linux2', 'darwin', и т.д.

console.log('This platform is ' + process.platform);

process.memoryUsage()

Возвращает объект, описывающий потребление памяти процессом Node.

var sys = require('sys');

console.log(sys.inspect(process.memoryUsage()));

В результате получим:

{ rss: 4935680
, vsize: 41893888
, heapTotal: 1826816
, heapUsed: 650472
}

heapTotal и heapUsed относятся к потреблению памяти движком V8.

process.nextTick(callback)

На следующей итерации цикла обработки событий запустить указанный обработчик. Это не простой alias для setTimeout(fn, 0), это намного более эффективный метод.

process.nextTick(function () {
  console.log('nextTick callback');
});

process.umask(mask)

Задаёт и возвращает маску создания файлов процессом. Дочерние процессы наследуют эту маску от процесса-родителя. Если задан аргумент mask возвращает старую маску, иначе — возвращает текущую.

var oldmask, newmask = 0644;

oldmask = process.umask(newmask);
console.log('Changed umask from: ' + oldmask.toString(8) +
            ' to ' + newmask.toString(8));

sys

Эти функции — часть модуля 'sys'. Используйте require('sys') чтобы получить к ним доступ.

sys.print(string)

То же что console.log() но без перевода строки.

require('sys').print('String with no newline');

sys.debug(string)

Синхронный вывод. Заблокирует процесс и выведет строку string в поток stderr немедленно.

require('sys').debug('message on stderr');

sys.log(string)

Выводит строку с меткой времени в stdout.

require('sys').log('Timestmaped message.');

sys.inspect(object, showHidden, depth)

Возвращает объект object в виде строки, очень удобно для отладки.

Если showHidden имеет значение true, неперечисляемые свойства тоже будут показаны.

Параметр depth сообщает inspect на какую глубину просмотреть объект, прежде чем выдавать результат. Это полезно для больших сложных объектов.

По умолчанию принята глубина просмотра 2. Чтобы просмотреть объект на неограниченную глубину, передайте null в качестве значения depth.

Пример просмотра всех свойств объекта sys:

var sys = require('sys');

console.log(sys.inspect(sys, true, null));

sys.pump(readableStream, writeableStream, [callback])

Экспериментальный метод.

Читает данные из потока readableStream и посылает потоку writableStream. Когда writeableStream.write(data) возвращает false readableStream приостанавливается пока не произойдёт событие drain в writableStream. callback is вызывается после закрытия writableStream.

Таймеры

setTimeout(callback, delay, [arg, ...])

Позволяет выполнить переданный callback через delay миллисекунд. Возвращает ID таймаута — timeoutId для последующего использования с clearTimeout().

clearTimeout(timeoutId)

Отменяет установленный таймаут.

setInterval(callback, delay, [arg, ...])

Позволяет выполнять переданный callback каждые delay миллисекунд. Возвращает ID интервала — intervalId для использования с clearInterval().

Кроме того, можно передавать аргументы callback'у.

clearInterval(intervalId)

Прекращает действие интервального таймера.

Дочерние процессы

Node предоставляет tri-directional popen(3) в классе ChildProcess.

С дочерним потоком можно обмениваться данными через stdin, stdout и stderr в полностью неблокирующем стиле.

Для создания дочернего процесса используйте require('child_process').spawn().

С дочерним процессом всегда ассоциированы три потока: child.stdin, child.stdout и child.stderr.

Чтобы дочерний поток мог продолжать работу после остановки родительского, он должен обрабатывать сигнал SIGHUP.

ChildProcess — экземпляр EventEmitter.

Событие: 'exit'

function (code, signal) {}

Это событие генерируется при завершении дочернего процесса. Если процесс завершён нормально, в code передаётся код завершения процесса, иначе передаётся null. Если процесс завершился от принятия сигнала, signal — это строка, содержащая имя сигнала, либо null.

После генерации события 'exit' события 'output' и 'error' больше не будут генерироваться.

См. также: waitpid(2).

child_process.spawn(command, args, env)

Запускает новый процесс с указанной командой command, аргументами командной строки и переменными окружения. Если аргументы пропущены args будет пустым массивом, а env будет копией process.env.

Пример запуска ls -lh /usr, чтения stdout, stderr, и получения кода завершения:

var sys   = require('sys'),
    spawn = require('child_process').spawn,
    ls    = spawn('ls', ['-lh', '/usr']);

ls.stdout.addListener('data', function (data) {
  sys.print('stdout: ' + data);
});

ls.stderr.addListener('data', function (data) {
  sys.print('stderr: ' + data);
});

ls.addListener('exit', function (code) {
  console.log('child process exited with code ' + code);
});

Пример проверки запуска приложения:

var spawn = require('child_process').spawn,
    child = spawn('bad_command');

child.stderr.addListener('data', function (data) {
  if (/^execvp\(\)/.test(data.asciiSlice(0,data.length))) {
    console.log('Failed to start child process.');
  }
});

См. также: child_process.exec()

child.kill(signal)

Отправляет сигнал дочернему процессу. Если аргументы не переданы, то процессу будет отправлен сигнал 'SIGTERM'. См. signal(7) для списка возможных имён сигналов.

var spawn = require('child_process').spawn,
    grep  = spawn('grep', ['ssh']);

grep.addListener('exit', function (code, signal) {
  console.log('child process terminated due to receipt of signal '+signal);
});

// отправить процессу сигнал SIGHUP
grep.kill('SIGHUP');

Заметьте, что хотя функция называется kill, сигнал, отправляемый дочернему процессу, не обязательно его завершит. Метод kill просто отправляет сигналы.

См. также: kill(2)

child.pid

Идентификатор дочернего процесса.

Пример:

var spawn = require('child_process').spawn,
    grep  = spawn('grep', ['ssh']);

console.log('Spawned child pid: ' + grep.pid);
grep.stdin.end();

child.stdin.write(data, encoding)

Пишет данные в стандартный поток ввода (stdin) дочернего процесса. Второй аргумент необязательный и указывает кодировку: его возможные значения 'utf8', 'ascii', и 'binary'.

Пример: достаточно сложный способ выполнить 'ps ax | grep ssh'

var sys   = require('sys'),
    spawn = require('child_process').spawn,
    ps    = spawn('ps', ['ax']),
    grep  = spawn('grep', ['ssh']);

ps.stdout.addListener('data', function (data) {
  grep.stdin.write(data);
});

ps.stderr.addListener('data', function (data) {
  sys.print('ps stderr: ' + data);
});

ps.addListener('exit', function (code) {
  if (code !== 0) {
    console.log('ps process exited with code ' + code);
  }
  grep.stdin.end();
});

grep.stdout.addListener('data', function (data) {
  sys.print(data);
});

grep.stderr.addListener('data', function (data) {
  sys.print('grep stderr: ' + data);
});

grep.addListener('exit', function (code) {
  if (code !== 0) {
    console.log('grep process exited with code ' + code);
  }
});

child.stdin.end()

Закрывает поток stdin дочернего процесса. Это часто приводит к завершению дочернего процесса.

Пример:

var spawn = require('child_process').spawn,
    grep  = spawn('grep', ['ssh']);

grep.addListener('exit', function (code) {
  console.log('child process exited with code ' + code);
});

grep.stdin.end();

child_process.exec(command, [options, ] callback)

Высокоуровневый способ выполнить команду в качестве дочернего процесса, сохранить весь её вывод, и передать его в callback.

var sys   = require('sys'),
    exec  = require('child_process').exec,
    child;

child = exec('cat *.js bad_file | wc -l',
  function (error, stdout, stderr) {
    sys.print('stdout: ' + stdout);
    sys.print('stderr: ' + stderr);
    if (error !== null) {
      console.log('exec error: ' + error);
    }
  });

Функция-callback получает аргументы (error, stdout, stderr). При удачном выполнении в error будет null. При ошибке error будет экземпляром Error, err.code будет кодом завершения дочернего процесса, а в err.signal будет содержаться имя сигнала, завершившего процесс.

Вторым аргументом могут быть переданы параметры. По умолчанию они будут такими

{ encoding: 'utf8'
, timeout: 0
, maxBuffer: 200*1024
, killSignal: 'SIGKILL'
}

Если timeout больше 0, процесс будет завершён, если он выполняется дольше, чем timeout миллисекунд. Дочерний процесс завершается с помощью сигнала killSignal. В maxBuffer указывается максимальный объём данных, разрешённый на stdout или stderr — если этот объём будет превышен, то дочерний процесс будет завершён.

Script

Модуль Script отвечает за компиляцию и запуск JavaScript-кода. Вы можете получить доступ к модулю таким образом:

var Script = process.binding('evals').Script;

Новый JavaScript-код может быть скомпилирован и сразу запущен либо скомпилирован, сохранён, и запущен позже.

Script.runInThisContext(code, filename)

Действует почти как process.compile. Script.runInThisContext компилирует код code как если бы он был загружен из файла filename, запускает его и возвращает результат. Запускаемый код не получает доступа к локальной области видимости. Параметр filename — необязательный.

Пример использования Script.runInThisContext и eval для запуска одного и того же кода:

var localVar = 123,
    usingscript, evaled,
    Script = process.binding('evals').Script;

usingscript = Script.runInThisContext('localVar = 1;',
  'myfile.js');
console.log('localVar: ' + localVar + ', usingscript: ' +
  usingscript);
evaled = eval('localVar = 1;');
console.log('localVar: ' + localVar + ', evaled: ' +
  evaled);

// localVar: 123, usingscript: 1
// localVar: 1, evaled: 1

Script.runInThisContext не имеет доступа к локальной области видимости, поэтому переменная localVar остаётся неизменной. eval имеет доступ к локальной области видимости, поэтому localVar изменяется.

В случае обнаружения синтаксической ошибки в коде code, Script.runInThisContext выводит текст ошибки в stderr и генерирует исключение.

Script.runInNewContext(code, sandbox, filename)

Script.runInNewContext компилирует переданный код code для запуска в контексте sandbox как если бы код был загружен из файла filename, потом выполняет его и возвращает результат. Запущенный код не имеет доступа к локальной области видимости и объект sandbox будет использован в качестве глобального объекта для кода code. Параметры sandbox и filename необязательны.

Пример: скомпилировать и выполнить код, увеличивающий глобальную переменную и создающий новую. Эти переменные содержатся в sandbox-объекте.

var sys = require('sys'),
    Script = process.binding('evals').Script,
    sandbox = {
      animal: 'cat',
      count: 2
    };

Script.runInNewContext(
  'count += 1; name = "kitty"', sandbox, 'myfile.js');
console.log(sys.inspect(sandbox));

// { animal: 'cat', count: 3, name: 'kitty' }

Заметьте, что запуск стороннего кода — операция, требующая особого внимания. Script.runInNewContext очень полезен для предотвращения случайных утечек глобальных переменных, но по настоящему безопасное выполнение стороннего кода требует отдельного процесса.

При обнаружении синтаксической ошибки в code, Script.runInThisContext выводит текст ошибки в stderr и генерирует исключение.

new Script(code, filename)

new Script компилирует переданный код code как если бы он был загружен из файла filename, но не запускает его. Вместо этого он возвращает объект Script представляющий скомпилированный код. После этот скрипт может быть многократно выполнен следующими методами. Возвращаемый скрипт не привязан ни к какому глобальному объекту. Он привязывается перед каждым запуском, только для этого запуска. filename is optional.

В случае обнаружения синтаксической ошибки в коде code, new Script выводит текст ошибки в stderr и генерирует исключение.

script.runInThisContext()

Похоже на Script.runInThisContext (обратите внимание на заглавную 'S'), но теперь это метод предварительно скомпилированного объекта Script. script.runInThisContext запускает код в объекте script и возвращает результат. У запускаемого кода нет доступа к локальной области видимости, но есть доступ к глобальному объекту global (v8: in actual context).

Пример использования script.runInThisContext чтобы скомпилировать код однажды и запустить несколько раз:

var Script = process.binding('evals').Script,
    scriptObj, i;

globalVar = 0;

scriptObj = new Script('globalVar += 1', 'myfile.js');

for (i = 0; i < 1000 ; i += 1) {
  scriptObj.runInThisContext();
}

console.log(globalVar);

// 1000

script.runInNewContext(sandbox)

Как и в Script.runInNewContext (note capital 'S'), но теперь это метод заранее созданного объекта Script. script.runInNewContext запускает код, содержащийся в объекте script с объектом sandbox в качестве глобального и возвращает результат. Запускаемый код не имеет доступа к локальной области видимости. Переменная sandbox необязательна.

Пример: скомпилировать и выполнить код, увеличивающий глобальную переменную и создающий новую. Эти переменные содержатся в sandbox-объекте.

var sys = require('sys'),
    Script = process.binding('evals').Script,
    scriptObj, i,
    sandbox = {
      animal: 'cat',
      count: 2
    };

scriptObj = new Script(
    'count += 1; name = "kitty"', 'myfile.js');

for (i = 0; i < 10 ; i += 1) {
  scriptObj.runInNewContext(sandbox);
}

console.log(sys.inspect(sandbox));

// { animal: 'cat', count: 12, name: 'kitty' }

Заметьте, что запуск стороннего кода — операция, требующая особого внимания. Script.runInNewContext очень полезен для предотвращения случайных утечек глобальных переменных, но по настоящему безопасное выполнение стороннего кода требует отдельного процесса.

Файловая система

Файловый ввод/вывод обеспечивается с помощью простой обертки вокруг стандартных функций POSIX. Используйте require('fs') чтобы получить к ним доступ. Все эти методы имеют асинхронную и синхронную версии.

Асинхронные версии всегда принимают функцию обратного вызова в качестве последнего аргумента. Аргументы, передаваемые в функцию обратного вызова зависят от вызываемой функции, но первый из них всегда зарезервирован для исключения. Если операция завершается без ошибок, то в качется первого аргумента передаётся null или undefined.

Пример использования асинхронной версии:

var fs = require('fs');

fs.unlink('/tmp/hello', function (err) {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});

Пример использования синхронной версии:

var fs = require('fs');

fs.unlinkSync('/tmp/hello')
console.log('successfully deleted /tmp/hello');

Асинхронные методы не гарантируют порядок выполнения операций. Следующий код может сработать неправильно:

fs.rename('/tmp/hello', '/tmp/world', function (err) {
  if (err) throw err;
  console.log('renamed complete');
});
fs.stat('/tmp/world', function (err, stats) {
  if (err) throw err;
  console.log('stats: ' + JSON.stringify(stats));
});

Вполне возможно что fs.stat выполнится до fs.rename. Правильный способ сделать то же самое — выполнение этих методов по цепочке.

fs.rename('/tmp/hello', '/tmp/world', function (err) {
  if (err) throw err;
  fs.stat('/tmp/world', function (err, stats) {
    if (err) throw err;
    console.log('stats: ' + JSON.stringify(stats));
  });
});

В нагруженных процессах программисту строго рекомендуется использовать асинхронные версии вызовов. Синхронные версии будут блокировать весь процесс до своего завершения — предотвращая любые новые соединения.

fs.rename(path1, path2, callback)

Асинхронное переименование (rename(2)). Обработчику не передаётся аргументов кроме возможного исключения.

fs.renameSync(path1, path2)

Синхронный rename(2).

fs.truncate(fd, len, callback)

Асинхронный ftruncate(2). Обработчику не передаётся аргументов кроме возможного исключения.

fs.truncateSync(fd, len)

Синхронный ftruncate(2).

fs.chmod(path, mode, callback)

Асинхронное изменение прав доступа (chmod(2)). Обработчику не передаётся аргументов кроме возможного исключения.

fs.chmodSync(path, mode)

Синхронный chmod(2).

fs.stat(path, callback), fs.lstat(path, callback), fs.fstat(fd, callback)

Асинхронные stat(2), lstat(2) или fstat(2). Обработчик получает два аргумента (err, stats), где stats это объект fs.Stats. Он выглядит примерно так:

{ dev: 2049
, ino: 305352
, mode: 16877
, nlink: 12
, uid: 1000
, gid: 1000
, rdev: 0
, size: 4096
, blksize: 4096
, blocks: 8
, atime: '2009-06-29T11:11:55Z'
, mtime: '2009-06-29T11:11:40Z'
, ctime: '2009-06-29T11:11:40Z'
}

См. секцию fs.Stats для дальнейшей информации.

fs.statSync(path), fs.lstatSync(path), fs.fstatSync(fd)

Синхронные stat(2), lstat(2) и fstat(2). Возвращают экземпляр fs.Stats.

fs.link(srcpath, dstpath, callback)

Асинхронное создание ссылки (link(2)). Передаваемой функции не передаётся ничего кроме возможного исключения.

fs.linkSync(dstpath, srcpath)

Синхронный link(2).

fs.symlink(linkdata, path, callback)

Асинхронное создание символической ссылки (symlink(2)). Передаваемой функции не передаётся ничего кроме возможного исключения.

fs.symlinkSync(linkdata, path)

Синхронный symlink(2).

fs.readlink(path, callback)

Асинхронное разрешение ссылки (readlink(2)). Обработчик принимает два аргумента (err, resolvedPath).

fs.readlinkSync(path)

Синхронный readlink(2). Возвращает полученный путь.

fs.realpath(path, callback)

Асинхронный realpath(2). Обработчик принимает два аргумента (err, resolvedPath).

fs.realpathSync(path)

Синхронный realpath(2). Возвращает полученный путь.

fs.unlink(path, callback)

Асинхронный unlink(2). Передаваемой функции не передаётся ничего кроме возможного исключения.

fs.unlinkSync(path)

Синхронный unlink(2).

fs.rmdir(path, callback)

Асинхронный rmdir(2). Передаваемой функции не передаётся ничего кроме возможного исключения.

fs.rmdirSync(path)

Синхронный rmdir(2).

fs.mkdir(path, mode, callback)

Асинхронное создание директории (mkdir(2)). Передаваемой функции не передаётся ничего кроме возможного исключения.

fs.mkdirSync(path, mode)

Синхронный mkdir(2).

fs.readdir(path, callback)

Асинхронное чтение содержимого директории (readdir(3)). Обработчик принимает два аргумента (err, files), где files это массив имён файлов в директории исключая '.' и '..'.

fs.readdirSync(path)

Синхронный readdir(3). Возвращает массив имён файлов исключая '.' и '..'.

fs.close(fd, callback)

Асинхронный close(2). Передаваемой функции не передаётся ничего кроме возможного исключения.

fs.closeSync(fd)

Синхронный close(2).

fs.open(path, flags, mode, callback)

Асинхронное открытие файла. См. open(2). Флаги могут быть 'r', 'r+', 'w', 'w+', 'a', или 'a+'. Обработчик принимает два аргумента (err, fd).

fs.openSync(path, flags, mode)

Синхронное открытие файла (open(2)).

fs.write(fd, buffer, offset, length, position, callback)

Записывает буфер buffer в файл указанный дескриптором fd.

Сдвиг offset и длина length определяют часть буфера, которая будет записана.

Позиция position задаёт смещение от начала файла куда должны быть записаны данные. Если position равна null, данные записываются с текущей позиции. См. pwrite(2).

Обработчик принимает два аргумента (err, written), где written указывает сколько байт было записано в файл.

fs.writeSync(fd, data, position, encoding)

Синхронная версия fs.write(). Возвращает число записанных байт.

fs.read(fd, buffer, offset, length, position, callback)

Читает данные из файла, указанного дескриптором fd.

buffer — буфер, в который будут помещены прочитанные данные.

offset — смещение внутри буфера с которого начнётся запись.

length — число байт для чтения.

position — число означающее позицию, с которой начнётся чтение файла. Если position принимает значение null, данные будут прочитаны с текущей позиции.

Функция-обработчик принимает два аргумента, (err, bytesRead).

fs.readSync(fd, buffer, offset, length, position)

Синхронная версия fs.read. Возвращает количество прочитанных байт.

fs.readFile(filename, [encoding,] callback)

Асинхронно загружает в память содержимое файла. Пример:

fs.readFile('/etc/passwd', function (err, data) {
  if (err) throw err;
  console.log(data);
});

Обработчику передаются два аргумента: (err, data), где data — содержимое файла.

Если кодировка не указана, возвращается буфер.

fs.readFileSync(filename [, encoding])

Синхронная версия fs.readFile. Возвращает содержимое файла filename.

Если указана кодировка encoding, то функция возвращает строку. Иначе — возвращает буфер.

fs.writeFile(filename, data, encoding='utf8', callback)

Асинхронно записывает данные в файл. Пример:

fs.writeFile('message.txt', 'Hello Node', function (err) {
  if (err) throw err;
  console.log('It\'s saved!');
});

fs.writeFileSync(filename, data, encoding='utf8')

Синхронная версия fs.writeFile.

fs.watchFile(filename, [options,] listener)

Наблюдает за изменениями файла filename. Обработчик listener вызывается каждый раз при изменении файла.

Второй аргумент необязателен. Объект options, если он передан, должен содержать два свойства: двоичное persistent, и interval, задержку между проверками файла в миллисекундах. Значение по умолчанию: {persistent: true, interval: 0}.

Обработчик listener принимает два аргумента: текущий объект stat и предыдущий объект stat:

fs.watchFile(f, function (curr, prev) {
  console.log('the current mtime is: ' + curr.mtime);
  console.log('the previous mtime was: ' + prev.mtime);
});

Эти объекты — экземпляры fs.Stat.

fs.unwatchFile(filename)

Прекращает обрабатывать изменения файла filename.

fs.Stats

Объекты, возвращаемые fs.stat(), fs.lstat() и fs.fstat() являются экземплярами этого класса.

• stats.isFile()
• stats.isDirectory()
• stats.isBlockDevice()
• stats.isCharacterDevice()
• stats.isSymbolicLink() (доступно только после fs.lstat())
• stats.isFIFO()
• stats.isSocket()

fs.ReadStream

ReadStream это поток с возможностью чтения.

fs.createReadStream(path, [options])

Возвращает новый объект ReadStream.

options это объект со следующими полями по умолчанию:

{ 'flags': 'r'
, 'encoding': 'binary'
, 'mode': 0666
, 'bufferSize': 4 * 1024
}

readStream.readable

Двоичное свойство, принимающее значение true по умолчанию, но переключаемое в false после события ошибки 'error' , закрытия потока (событие 'end'), или вызова destroy().

readStream.pause()

Прекращает чтение данных потоком. События 'data' не будут происходить пока поток не будет разблокирован.

readStream.resume()

Разблокирует поток. Вместе с pause() может использоваться для контроля чтения.

readStream.destroy()

Позволяет закрыть поток не дожидаясь события 'end'. Никакие события кроме 'close' не будут происходить после вызова этого метода.

fs.WriteStream

WriteStream это поток с возможностью записи.

fs.createWriteStream(path, [options])

Возвращает новый объект WriteStream. options это объект со следующими свойствами по умолчанию:

{ 'flags': 'w'
, 'encoding': 'binary'
, 'mode': 0666
}

writeStream.writeable

Двоичное свойство, по умолчанию установленное в true , но принимающее значение false после события 'error' или вызова end() / destroy().

writeStream.write(data, encoding='utf8')

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

Второй необязательный параметр указывает кодировку строки.

writeStream.end()

Закрывает поток после того как все отложенные вызовы write() завершатся.

writeStream.destroy()

Позволяет закрыть поток независимо от его текущего состояния.

HTTP

Для использования клиента и сервера HTTP необходимо подключить соответствующий модуль с помощью require('http').

Интерфейс HTTP спроектирован в Node таким образом, чтобы поддерживать многие возможности протокола, которые традиционно было довольно сложно использовать. В частности, большие сообщения с возможным chunk-encoding. Интерфейс никогда не сохраняет в буфере целиком запрос или ответ, давая пользователю возможность принимать и отправлять данные в потоковом режиме.

Заголовки сообщения HTTP представлены примерно таким объектом:

{ 'content-length': '123'
, 'content-type': 'text/plain'
, 'stream': 'keep-alive'
, 'accept': '*/*'
}

Ключи приводятся к нижнему регистру. Значения не изменяются.

Для поддержки всего спектра возможных применений HTTP, соответствующее API в Node довольно низкоуровневое. Оно основано на потоках и передаче сообщений. Node разбирает HTTP-сообщение на заголовки и тело, остальное должен сделать программист.

HTTPS поддерживается если на целевой платформе доступен OpenSSL.

http.Server

Это EventEmitter со следующими событиями:

Событие: 'request'

function (request, response) { }

Объект request — экземпляр http.ServerRequest, объект response — экземпляр http.ServerResponse.

Событие: 'connection'

function (stream) { }

Генерируется при установке нового HTTP-соединения. stream — объект типа net.Stream. Обычно пользователи не используют это событие. Объект потока stream также можно найти в свойстве объекта запроса request.connection.

Событие: 'close'

function (errno) { }

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

http.createServer(requestListener, [options])

Возвращает новый объект web-сервера.

Аргумент options необязателен. Аргумент options принимает те же значения, что объект параметров для сервера net.Server.

Функция requestListener автоматически добавляется к событию 'request' сервера.

Событие: 'request'

function (request, response) {}

Генерируется каждый раз при получении запроса. Заметьте, что в течении одного соединения может происходить несколько запросов (в случае keep-alive соединения).

Событие: 'upgrade'

function (request, socket, head)

Генерируется каждый раз когда клиент запрашивает апгрейд соединения до защищённого (см. RFC 2817). Если это событие никак не обрабатывается соединение для которого запрошен апгрейд будет закрыто.

• request — аргументы для HTTP запроса, как в событии 'request'.
• socket — сетевой сокет между сервером и клиентом.
• head — экземпляр Buffer, первый пакет защищенного потока, может быть пустым.

После генерации этого события, у объекта server не будет обработчика события data, и программисту нужно назначить его заново чтобы обрабатывать данные, получаемые этим соединением.

Событие: 'clientError'

function (exception) {}

Если соединение с клиентом генерирует событие 'error' — оно поднимается сюда.

server.listen(port, hostname=null, callback=null)

Начинает приём соединений на указанном порту и имени хоста. Если имя хоста не указано, сервер будет принимать соединения на любой IPv4-адрес машины (INADDR_ANY).

Чтобы слушать unix-сокет, передайте имя файла вместо порта и имени хоста.

Эта функция асинхронна. Функция, переданная последним параметром callback будет вызвана когда сервер будет повешен на порт.

server.listen(path, callback=null)

Начинает слушать unix-сокет с заданным путём path.

Эта функция асинхронна. Функция, переданная последним параметром callback будет вызвана когда сервер будет повешен на порт.

server.setSecure(credentials)

Включает поддержку HTTPS для сервера, с параметрами для криптографического модуля: private-ключом и сертификатом сервера; также можно передать CA-сертификат для аутентификации клиентов.

Если в параметрах указан один или несколько CA-сертификатов, сервер запросит у клиента его сертификат при установке HTTPS-соединения. Достоверность и содержимое сертификата могут быть проверены с помощью методов verifyPeer() и getPeerCertificate() объекта request.connection сервера.

server.close()

Прекращает приём новых соединений сервером.

http.ServerRequest

Этот объект создаётся автоматически HTTP-сервером (не пользователем) и передаётся первым аргументом обработчику события 'request'.

Это EventEmitter со следующими событиями:

Событие: 'data'

function (chunk) { }

Генерируется при получении части тела сообщения.

Пример: Часть тела сообщения передаётся как единственный аргумент. Сообщение уже раскодировано из transfer-encoding. Часть тела представлена в виде строки. Кодировка тела сообщения задаётся request.setBodyEncoding().

Событие: 'end'

function () { }

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

request.method

Метод запроса в виде строки. Только для чтения. Пример: 'GET', 'DELETE'.

request.url

Строка с URL запроса. Здесь содержится URL в том виде, в котором он задан в самом HTTP-запросе. Если запрос выглядит так:

GET /status?name=ryan HTTP/1.1\r\n
Accept: text/plain\r\n
\r\n

Тогда значением request.url будет:

'/status?name=ryan'

Если вы хотите разделить URL на составные части, вы можете использовать require('url').parse(request.url). Пример:

node> require('url').parse('/status?name=ryan')
{ href: '/status?name=ryan'
, search: '?name=ryan'
, query: 'name=ryan'
, pathname: '/status'
}

Если вам нужно извлечь параметры из строки запроса, можно использовать функцию require('querystring').parse , или передать true в качестве второго аргумента require('url').parse. Пример:

node> require('url').parse('/status?name=ryan', true)
{ href: '/status?name=ryan'
, search: '?name=ryan'
, query: { name: 'ryan' }
, pathname: '/status'
}

request.headers

Заголовки запроса. Только для чтения.

request.httpVersion

Версия протокола HTTP в виде строки. Только чтение. Пример: '1.1', '1.0'. Также request.httpVersionMajor содержит первое число и request.httpVersionMinor — второе.

request.setEncoding(encoding='binary')

Задаёт кодировку тела запроса. Либо 'utf8', либо 'binary'. По умолчанию принимает значение 'binary'.

request.pause()

Прекращает генерирование событий запросом. Можно использовать для ускорения закачки файла.

request.resume()

Возобновляет генерирование событий запросом

request.connection

Объект соединения, экземпляр net.Stream.

Если включена поддержка HTTPS, используйте request.connection.verifyPeer() и request.connection.getPeerCertificate() чтобы получить сведения об аутентификации клиента.

http.ServerResponse

Этот объект создаётся внутри HTTP-сервера — не пользователем. Он передаётся вторым параметром в обработчик события 'request' и является потоком с возможностью записи.

response.writeHead(statusCode[, reasonPhrase] , headers)

Отправляет заголовки ответа клиенту. statusCode это три цифры кода статуса HTTP, например 404. Последний аргумент, headers, это заголовки ответа. Также вторым аргументом можно передать фразу reasonPhrase.

Пример:

var body = 'hello world';
response.writeHead(200, {
  'Content-Length': body.length,
  'Content-Type': 'text/plain'
});

Этот метод должен быть вызван только однажды для каждого сообщения и должен быть вызван до response.end().

response.write(chunk, encoding)

Этот метод должен вызываться после writeHead. Он отправляет часть тела ответа. Метод может быть вызван несколько раз для отправки последующих частей тела ответа.

Если chunk это строка, второй параметр указывает в какой кодировке отправлять её в поток. По умолчанию encoding принимает значение 'ascii'.

Замечание: Это необработанное тело HTTP-ответа и не имеет отношения к более высокоуровневым вещам вроде multi-part encoding, которые тоже могут использоваться.

После первого вызова response.write() клиенту будет отправлены заголовки и первая часть тела сообщения. После второго вызова response.write() Node предполагает что вы начинаете потоковую передачу данных и отправляет часть тела отдельно. Таким образом, данные буферизуются только до первой части тела ответа.

response.end()

Этот метод отправляет серверу сигнал что все заголовки и тело ответа отправлены; сервер должен считать это сообщение законченным. Метод response.end() ДОЛЖЕН быть вызван при каждом ответе.

http.Client

HTTP-клиент создаётся принимая адрес сервера в качестве аргумента, возвращаемый идентификатор используется для отправки одного или нескольких запросов. В зависимости от того, к какому серверу совершено подключение клиент может использовать pipeline (несколько запросов за соединение) либо пересоздавать поток после каждого запроса. Текущая версия не использует pipeline.

Пример подключения к google.com:

var http = require('http');
var google = http.createClient(80, 'www.google.com');
var request = google.request('GET', '/',
  {'host': 'www.google.com'});
request.end();
request.addListener('response', function (response) {
  console.log('STATUS: ' + response.statusCode);
  console.log('HEADERS: ' + JSON.stringify(response.headers));
  response.setEncoding('utf8');
  response.addListener('data', function (chunk) {
    console.log('BODY: ' + chunk);
  });
});

Событие: 'upgrade'

function (request, socket, head)

Генерируется каждый раз когда сервер отвечает на запрос предложением улучшить соединение до безопасного. Если это событие не обрабатывается, клиент при получении заголовка upgrade будет закрывать соединение.

См. описание события upgrade для http.Server.

http.createClient(port, host, secure, credentials)

Создаёт новый HTTP клиент. port и host относятся к серверу, к которому производится подключение. Поток не создаётся до отправки запроса.

secure — дополнительный двоичный флаг для включения поддержки HTTPS, а credentials — необязательный объект параметров для crypto-модуля, хранящий private-ключ клиента, сертификат и список доверенных CA сертификатов.

Если соединение зашифровано, но в объекте параметров не переданы сертификаты CA, то Node будет использовать публично доступный список CA, который представлен в http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt.

client.request([method], path, [request_headers])

Отправляет запрос; при необходимости инициирует соединение. Возвращает экземпляр http.ClientRequest.

method — необязательный параметр, по умолчанию принимает значение 'GET'.

request_headers необязательный параметр. Дополнительные заголовки запроса могут быть добавлены внутри Node. Возвращает объект ClientRequest.

Не забудьте включить заголовок Content-Length если планируете отправить тело запроса. Если вы хотите отправить тело запроса потоком, поставьте Transfer-Encoding: chunked.

ВНИМАНИЕ: запрос ещё не закончен. Этот метод только отсылает заголовки серверу. Необходимо вызвать request.end() чтобы отправить запрос целиком и получить ответ. (Это звучит сложно, но позволяет пользователю передавать тело запроса в потоковом режиме с помощью request.write().)

client.verifyPeer()

Возвращает true или false в зависимости от подлинности сертификата сервера соответственно списку доверенных сертификатов CA (переданному явно или используемому по умолчанию).

client.getPeerCertificate()

Возвращает JSON с деталями сертификата сервера, содержит поля 'subject', 'issuer', 'valid_from' и 'valid_to'

http.ClientRequest

Объект создаётся внутри Node и возвращается методом request() объекта http.Client. Он представляет собой незаконченный запрос, заголовки которого уже отправлены.

Чтобы получить ответ, добавьте обработчик событию 'response' объекта запроса. Событие 'response' будет сгенерировано объектом запроса при получении заголовков ответа. Обработчик события 'response' выполняется с одним аргументом — экземпляром http.ClientResponse.

Во время события 'response' можно добавлять обработчики к объекту ответа; в частности, чтобы получать части тела ответа надо добавить обработчик событию 'data'. Заметьте что обработчик события 'response' вызывается до того, как будут получены части тела ответа, поэтому не надо беспокоиться, что первая часть тела будет пропущена. Если обработчик 'data' добавляется во время события 'response', то всё тело ответа будет получено наверняка.

// Good
request.addListener('response', function (response) {
  response.addListener('data', function (chunk) {
    console.log('BODY: ' + chunk);
  });
});

// Bad - misses all or part of the body
request.addListener('response', function (response) {
  setTimeout(function () {
    response.addListener('data', function (chunk) {
      console.log('BODY: ' + chunk);
    });
  }, 10);
});

Это поток с возможностью записи.

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

Событие: 'response'

function (response) { }

Генерируется когда на запрос приходит ответ. Это событие генерируется только один раз. Аргументом обработчика response будет экземпляр http.ClientResponse.

request.write(chunk, encoding='ascii')

Отправляет часть тела запроса. Вызывая этот метод несколько раз, пользователь может отправлять тело ответа серверу в потоковом режиме — в таком случае предпочтительно добавлять в заголовки ['Transfer-Encoding', 'chunked'] при создании запроса.

Аргумент chunk должен быть массивом чисел или строкой.

Аргумент encoding необязателен и имеет значение только если chunk это строка. Аргумент encoding должен принимать значение 'utf8' или 'ascii'. По умолчанию используется кодировка ASCII как более быстрая для обработки.

request.end()

Завершает отправку запроса. Если какие то части тела запроса ещё не были отправлены, они отправляются. Если запрос разбит на части, будет послана завершающая последовательность '0\r\n\r\n'.

http.ClientResponse

Этот объект создаётся при создании запроса с помощью http.Client. Он передаётся обработчику события 'response' объекта запроса.

Объект ответа — поток с возможностью чтения.

Событие: 'data'

function (chunk) {}

Генерирется при получении части тела сообщения.

Часть тела сообщения передаётся обработчику в качестве единственного аргумента. Строка уже преобразована из кодировки с помощью которой осуществлялась передача. Часть тела сообщения передаётся обработчику в виде строки. Кодировка тела сообщения задаётся response.setBodyEncoding().

Событие: 'end'

function () {}

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

response.statusCode

Код статуса HTTP из трёх цифр, например 404.

response.httpVersion

Версия HTTP для текущего соединения. Скорее всего либо '1.1', либо '1.0'. Также response.httpVersionMajor — первая цифра версии, response.httpVersionMinor — вторая.

response.headers

Заголовки ответа.

response.setEncoding(encoding)

Задаёт кодировку тела ответа. Может принимать значения 'utf8' либо 'binary'. По умолчанию используется 'binary'.

response.pause()

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

response.resume()

Возобновляет генерацию событий ответом.

response.client

Ссылка на http.Client которому принадлежит ответ.

net.Server

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

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

var net = require('net');
var server = net.createServer(function (stream) {
  stream.setEncoding('utf8');
  stream.addListener('connect', function () {
    stream.write('hello\r\n');
  });
  stream.addListener('data', function (data) {
    stream.write(data);
  });
  stream.addListener('end', function () {
    stream.write('goodbye\r\n');
    stream.end();
  });
});
server.listen(8124, 'localhost');

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

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

Это EventEmitter со следующими событиями:

Событие: 'connection'

function (stream) {}

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

Событие: 'close'

function () {}

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

net.createServer(connectionListener)

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

server.listen(port, host=null, callback=null)

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

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

server.listen(path, callback=null)

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

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

server.listenFD(fd)

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

Для указанного файлового дескриптора должны быть уже выполнены системные вызовы bind(2) и listen(2).

server.close()

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

net.Stream

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

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

Событие: 'connect'

function () { }

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

Событие: 'secure'

function () { }

Генерируется когда соединение успешно проходит HTTPS-аутентификацию клиента.

Событие: 'data'

function (data) { }

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

Событие: 'end'

function () { }

Генерируется когда другой участник соединения посылает пакет FIN. После генерации этого события свойство readyState будет установлено в значение 'writeOnly'. Часто в обработчике этого события следует просто вызвать stream.end() (послав ответный FIN).

Событие: 'timeout'

function () { }

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

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

Событие: 'drain'

function () { }

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

Событие: 'error'

function (exception) { }

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

Событие: 'close'

function () { }

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

net.createConnection(port, host='127.0.0.1')

Создаёт новый объект потока и открывает соединение с указанным портом port и адресом host. Если второй параметр не задан, предполагается значение localhost.

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

stream.connect(port, host='127.0.0.1')

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

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

stream.remoteAddress

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

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

stream.readyState

Состояние потока: 'closed', 'open', 'opening', 'readOnly', или 'writeOnly'.

stream.setEncoding(encoding)

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

stream.setSecure(credentials)

Включает поддержку HTTPS для потока, параметры передаются криптографическому модулю и включают private key и сертификат потока, дополнительно могут включать сертификаты CA для аутентификации участника соединения.

Если объект параметров содержит один или несколько сертификатов CA, поток запросит у участника соединения сертификат в ходе установки HTTPS-соединения. Правильность и содержимое сертификата могут быть проверены функциями verifyPeer() и getPeerCertificate().

stream.verifyPeer()

Возвращает true или false в зависимости от правильности сертификата участника соединения в контексте заданных CA-сертификатов (или списка CA по умолчанию).

stream.getPeerCertificate()

Возвращает JSON с деталями сертификата участника соединения, содержащий свойства 'subject', 'issuer', 'valid_from' и 'valid_to'

stream.write(data, encoding='ascii')

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

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

stream.end()

Наполовину закрывает соединение, т.е. отправляет пакет FIN. Возможно сервер ещё получит какие-то данные. После вызова этого метода свойство readyState будет установлено в значение 'readOnly'.

stream.destroy()

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

stream.pause()

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

stream.resume()

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

stream.setTimeout(timeout)

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

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

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

stream.setNoDelay(noDelay=true)

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

stream.setKeepAlive(enable=false, initialDelay)

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

Модуль криптографии

Используйте require('crypto') чтобы получить доступ к функциям модуля.

Криптографический модуль требует для своей работы наличия OpenSSL. Он предоставляет возможность использовать аутентификацию в HTTPS и HTTP-соединениях.

Модуль также предоставляет набор обёрток для некоторых методов OpenSSL: hash, hmac, cipher, decipher, sign и verify.

crypto.createCredentials(details)

Создаёт объект данных аутентификации, может принимать параметром объект со следующими свойствами:

key : строка с PEM-закодированным приватным ключом,

cert : строка с PEM-закодированным сертификатом,

ca : строка или список строк PEM-закодированных доверенных корневых сертификатов.

Если корневые сертификаты не указаны, node.js будет использовать список доверенных сертификатов, расположенный по адресу http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt.

crypto.createHash(algorithm)

Создает и возвращает объект hash, который может быть использован для создания криптографических хэшей по заданному алгоритму.

Возможные значения для algorithm зависят от доступных алгоритмах в той версии OpenSSL, которая у вас установлена. Например, это может быть 'sha1', 'md5' и т.д. В последней версии OpenSSL список поддерживаемых алгоритмов можно было узнать с помощью команды openssl list-message-digest-algorithms.

hash.update(data)

Обновляет содержимое на data. Этот метод может быть вызван несколько раз.

hash.digest(encoding)

Вычисляет хеш от всех поступивших данных. Параметр encoding может равняться 'hex', 'binary' или 'base64'.

crypto.createHmac(algorithm, key)

Создает и возвращает объект hmac, который может быть использован для создания хеш-кода идентификации сообщений (HMAC) по заданному алгоритму и ключу.

Возможные значения для algorithm зависят от доступных алгоритмах в OpenSSL, см. описание для crypto.createHash() выше. key определяет используемый ключ.

hmac.update(data)

Обновляет содержимое на data. Этот метод может быть вызван несколько раз.

hmac.digest(encoding)

Вычисляет хеш от всех поступивших данных. Параметр encoding может равняться 'hex', 'binary' или 'base64'.

crypto.createCipher(algorithm, key)

Создает и возвращает объект cipher, который может быть использован для шифрования по заданному алгоритму и ключу.

Возможные значения для algorithm зависят от доступных алгоритмах в той версии OpenSSL, которая у вас установлена. Например, это может быть 'aes192', 'blowfish' и т.д. В последней версии OpenSSL список поддерживаемых алгоритмов можно было узнать openssl list-cipher-algorithms.

cipher.update(data, input_encoding, output_encoding)

Обновляет содержимое на data, кодировку которых задаёт аргумент input_encoding (может равняться 'utf8', 'ascii' или 'binary'). Аргумент output_encoding определяет выходной формат и может равняться 'binary', 'base64' или 'hex'.

Возвращает зашифрованного содержимого и может быть названо много раз с новыми данными.

cipher.final(output_encoding)

Возвращает все оставшиеся зашифрованного содержимого. Значение аргументо output_encoding объяснено выше.

crypto.createDecipher(algorithm, key)

Создает и возвращает объект decipher, который может быть использован для дешифрования по заданному алгоритму и ключу. Это объект-близнец для объекта cipher.

decipher.update(data, input_encoding, output_encoding)

Обновляет содержимое на data, формат которых задаёт аргумент input_encoding (может равняться 'binary', 'base64' или 'hex'). Аргумент output_encoding определяет выходную кодировку и может равняться 'utf8', 'ascii' или 'binary'.

decipher.final(output_encoding)

Возвращает все оставшиеся разшифрованного содержимого в виде простого текста. Значение аргументо output_encoding объяснено выше.

crypto.createSign(algorithm)

Создает и возвращает объект signer, который может быть использован для создания электронной подписи по заданному алгоритму.

Возможные значения для algorithm зависят от доступных алгоритмах в той версии OpenSSL, которая у вас установлена. Например, это может быть 'rsa', 'RSA-SHA256' и т.д. В последней версии можно было узнать список поддерживаемых алгоритмов с помощью команды openssl list-public-key-algorithms.

signer.update(data)

Обновляет содержимое на data. Этот метод может быть вызван несколько раз.

signer.sign(private_key, output_format)

Вычисляет подпись для всех данных. private_key задаёт закрытый ключ в формате PEM.

Возвращает подпись в формате output_format, который может равняться 'binary', 'hex' или 'base64'.

crypto.createVerify(algorithm)

Создает и возвращает объект verifier, который может быть использован для проверки электронной подписи. Это объект-близнец для объекта signer.

verifier.update(data)

Обновляет содержимое на data. Этот метод может быть вызван несколько раз.

verifier.verify(public_key, signature, signature_format)

Проверяет данные с помощью открытого ключа public_key в формате PEM и подписи signature формата signature_format (может равняться 'binary', 'hex' или 'base64'.

Возвращает true или false в зависимости от действительности подписи и публичного ключа.

DNS

Используйте require('dns') чтобы получить доступ к модулю.

Пример, преобразующий в IP-адрес хост 'www.google.com' и преобразовывающий обратно полученные адреса.

var dns = require('dns');

dns.resolve4('www.google.com', function (err, addresses) {
  if (err) throw err;

  console.log('addresses: ' + JSON.stringify(addresses));

  for (var i = 0; i < addresses.length; i++) {
    var a = addresses[i];
    dns.reverse(a, function (err, domains) {
      if (err) {
        console.log('reverse for ' + a + ' failed: ' +
          err.message);
      } else {
        console.log('reverse for ' + a + ': ' +
          JSON.stringify(domains));
      }
    });
  }
});

dns.resolve(domain, rrtype = 'A', callback)

Разрешает домен (например 'google.com') в массив записей типа, указанного в rrtype. Допустимые значения rrtypes: A (адреса IPV4), AAAA (адреса IPV6), MX (записи mail exchange), TXT (текстовые записи), SRV (записи SRV), и PTR (используются для запросов домена по IP).

Обработчик принимает аргументы (err, addresses). Тип каждого элемента addresses определяется типом записи, и описан в документации по соответствующим методам запроса ниже.

При ошибке err будет экземпляром объекта Error, где err.errno — один из кодов ошибки, перечисленных ниже, а err.message — строка, содержащая описание ошибки на английском.

dns.resolve4(domain, callback)

То же что dns.resolve(), но только для IPv4 адресов (записи типа A). addresses это массив IPv4 адресов (например
['74.125.79.104', '74.125.79.105', '74.125.79.106']).

dns.resolve6(domain, callback)

То же что dns.resolve4() но только для IPv6 адресов (записи типа AAAA).

dns.resolveMx(domain, callback)

То же что dns.resolve(), но только для MX-записей.

addresses это массив MX записей, каждая с атрибутами priority и exchange (например [{'priority': 10, 'exchange': 'mx.example.com'},...]).

dns.resolveTxt(domain, callback)

То же что dns.resolve(), но только для текстовых записей (тип записи TXT). addresses это массив текстовых записей, доступных для домена domain (например ['v=spf1 ip4:0.0.0.0 ~all']).

dns.resolveSrv(domain, callback)

То же, что dns.resolve(), но только для service records (записей SRV). addresses это массив SRV записей, доступных для домена domain. Свойства SRV записей: 'priority', 'weight', 'port', и 'name' (например, [{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]).

dns.reverse(ip, callback)

Обратно разрешает IP-адрес в массив доменных имён.

Аргументы обработчика: (err, domains).

Если произошла ошибка, err будет ненулевым экземпляром объекта Error.

Каждый запрос к DNS может вернуть код ошибки.

• dns.TEMPFAIL: таймаут, SERVFAIL или что-то подобное.
• dns.PROTOCOL: получен повреждённый ответ.
• dns.NXDOMAIN: домен не существует.
• dns.NODATA: домен существует, но нет данных требуемого типа.
• dns.NOMEM: при обработке закончилась память.
• dns.BADQUERY: запрос неверно сформирован.

dgram

Сокеты для датаграмм доступны при включении require('dgram'). Датаграммы чаще всего обрабатываются как сообщения IP/UDP, но они могут быть использованы и с доменными сокетами Unix.

Событие: 'message'

function (msg, rinfo) { }

Генерируется когда новая датаграмма доступна на сокете. msg это Buffer, а rinfo это объект с информацией об адресе отправителя и количестве байт в датаграмме.

Событие: 'listening'

function () { }

Генеритуется когда сокет начинает приём датаграмм. Для UDP-сокета это происходит при создании. Сокеты Unix не начинают приём до вызова для них bind().

Событие: 'close'

function () { }

Генерируется когда сокет закрывается с помощью close(). События message на этом сокете больше не будут генерироваться.

dgram.createSocket(type, [callback])

Создаёт сокет для датаграмм заданного типа. Доступные типы: udp4, udp6 и unix_dgram.

Принимает необязательную функцию, которая добавляется обработчиком событий message.

dgram.send(buf, offset, length, path, [callback])

Для датаграмм на Unix-сокетах адрес назначения это путь в файловой системе. Принимает необязательную функцию, которая будет вызвана после завершения вызова sendto операционной системой. Пока идёт вызов, повторное использование буфера buf небезопасно. Заметьте, что если сокет не привязан к пути в файловой системе с помощью bind(), на нём невозможно получать сообщения.

Пример отправки сообщения демону syslogd в OSX через Unix-сокет /var/run/syslog:

var dgram = require('dgram');
var message = new Buffer("A message to log.");
var client = dgram.createSocket("unix_dgram");
client.send(message, 0, message.length, "/var/run/syslog",
  function (err, bytes) {
    if (err) {
      throw err;
    }
    console.log("Wrote " + bytes + " bytes to socket.");
});

dgram.send(buf, offset, length, port, address, [callback])

Для UDP сокетов должен быть указан IP-адрес и порт назначения. В качестве адреса address может быть передана строка, она будет преобразована в адрес через DNS. Принимает необязательную функцию, которая определит произошли ли ошибки при использовании DNS и можно ли повторно использовать buf. Заметьте, что обращение к DNS для разрешения адреса отложит отправку пакета как минимум до следующей итерации event loop. Единственный способ убедиться что пакет действительно отправлен — использование фунции-обработчика.

Пример отправки UDP пакета на случайный порт локальной машины:

var dgram = require('dgram');
var message = new Buffer("Some bytes");
var client = dgram.createSocket("udp4");
client.send(message, 0, message.length, 41234, "localhost");
client.close();

dgram.bind(path)

Для Unix-сокетов датаграмм, начинает приём сообшений на сокете, путь к которому передаётся в аргументе path. Заметьте что клиенты могут использовать send() без вызова bind(), но никакие сообщения не будут приняты пока bind() не будет вызван.

Пример Unix-сервера пакетов, отправляющего обратно все принятые сообщения:

var dgram = require("dgram");
var serverPath = "/tmp/dgram_server_sock";
var server = dgram.createSocket("unix_dgram");
 
server.on("message", function (msg, rinfo) {
  console.log("got: " + msg + " from " + rinfo.address);
  server.send(msg, 0, msg.length, rinfo.address);
});
 
server.on("listening", function () {
  console.log("server listening " + server.address().address);
})
 
server.bind(serverPath);

Пример Unix-клиента для приема пакетов, работающего с этим сервером:

var dgram = require("dgram");
var serverPath = "/tmp/dgram_server_sock";
var clientPath = "/tmp/dgram_client_sock";
 
var message = new Buffer("A message at " + (new Date()));
 
var client = dgram.createSocket("unix_dgram");
 
client.on("message", function (msg, rinfo) {
  console.log("got: " + msg + " from " + rinfo.address);
});
 
client.on("listening", function () {
  console.log("client listening " + client.address().address);
  client.send(message, 0, message.length, serverPath);
});
 
client.bind(clientPath);

dgram.bind(port, [address])

Для UDP-сокетов, начинает приём сообщений на заданном порту port и опционально на адресе address. Если address не указан, ОС будет слушать все доступные адреса.

Пример UDP сервера слушающего порт 41234:

var dgram = require("dgram");
 
var server = dgram.createSocket("udp4");
var messageToSend = new Buffer("A message to send");
 
server.on("message", function (msg, rinfo) {
  console.log("server got: " + msg + " from " +
    rinfo.address + ":" + rinfo.port);
});
 
server.on("listening", function () {
  var address = server.address();
  console.log("server listening " +
      address.address + ":" + address.port);
});
 
server.bind(41234);
// server listening 0.0.0.0:41234

dgram.close()

Закрывает соответствующий сокет и прекращает приём данных на нём. UDP сокеты автоматически начинают принимать сообщения, даже без вызова bind().

dgram.address()

Возвращает объект в котором содержится информация об адресе сокета. Для UDP сокетов этот объект будет содержать поля address и port. Для сокетов Unix он будет содержать только address.

dgram.setBroadcast(flag)

Устанавливает или снимает флаг SO_BROADCAST в настройках сокета. Когда этот флаг установлен, пакеты UDP могут быть отправлены на широковещательный адрес локального интерфейса.

dgram.setTTL(ttl)

Задаёт значение параметра IP_TTL. TTL это "время жизни" пакета ("Time to Live"), но в этом контексте оно означает количество IP узлов которое может пройти пакет. Каждый роутер или шлюз, перенаправляющие пакет дальше, снижают это значение на единицу. Если TTL снижается до 0 на одном из узлов, пакет не будет передан дальше. TTL обычно изменяют для диагностики сети или ограничения действия широковещательных пакетов.

Аргумент к setTTL() это число узлов от 1 до 255. На большинстве систем значение по умолчанию 64.

Assert

Этот модуль используется для написания юнит-тестов для Ваших приложений, вы можете использовать его вызвав require('assert').

assert.fail(actual, expected, message, operator)

Проверяет что actual соответствует expected используя указанный оператор.

assert.ok(value, message)

Проверяет что значение value равно true, то же самое что assert.equal(true, value, message);

assert.equal(actual, expected, message)

Неглубокая проверка на равенство с использованием соответствующего оператора ( == ).

assert.notEqual(actual, expected, message)

Неглубокая проверка на неравенство с использованием соответствующего оператора (!= ).

assert.deepEqual(actual, expected, message)

Глубокая проверка на равенство.

assert.notDeepEqual(actual, expected, message)

Глубокая проверка на неравенство.

assert.strictEqual(actual, expected, message)

Проверка на строгое равенство, с использованием соответствующего оператора ( === )

assert.notStrictEqual(actual, expected, message)

Проверка на строгое неравенство, с использованием соответствующего оператора ( !== )

assert.throws(block, error, message)

Ожидает что блок кода block вызовет ошибку.

assert.doesNotThrow(block, error, message)

Ожидает что блок кода block не вызовет ошибки.

assert.ifError(value)

Проверяет что value имеет значение false, бросает исключение встретив true. Удобно для проверки первого аргумента функций-обработчиков, error.

Path

Этот модуль содержит средства для работы с путями. Используйте require('path') чтобы получить к нему доступ. Модуль предоставляет следующие методы:

path.join(/ path1, path2, ... /)

Соединяет все аргументы и обрабатывает получившийся путь. Например:

node> require('path').join(
...   '/foo', 'bar', 'baz/asdf', 'quux', '..')
'/foo/bar/baz/asdf'

path.normalizeArray(arr)

Нормализует массив частей пути, обрабатывая '..' и '.'. Пример:

path.normalizeArray(['',
  'foo', 'bar', 'baz', 'asdf', 'quux', '..'])
// возвращает
[ '', 'foo', 'bar', 'baz', 'asdf' ]

path.normalize(p)

Нормализует строку пути, обрабатывая '..' и '.'. Пример:

path.normalize('/foo/bar/baz/asdf/quux/..')
// возвращает
'/foo/bar/baz/asdf'

path.dirname(p)

Возвращает имя директории для пути. Действует как Unix-команда dirname. Пример:

path.dirname('/foo/bar/baz/asdf/quux')
// возвращает
'/foo/bar/baz/asdf'

path.basename(p, ext)

Возвращает последнюю часть пути. Действует как Unix-команда basename. Пример:

path.basename('/foo/bar/baz/asdf/quux.html')
// возвращает
'quux.html'

path.basename('/foo/bar/baz/asdf/quux.html', '.html')
// возвращает
'quux'

path.extname(p)

Возвращает расширение пути. Учитывается всё после последней '.' в последней части пути. Если в последней части нет '.' или '.' единственный символ, возвращает пустую строку. Примеры:

path.extname('index.html')
// returns 
'.html'

path.extname('index')
// returns
''

path.exists(p, callback)

Проверяет, существует ли данный путь. Вызывает переданный обработчик с аргументом true или false. Пример:

path.exists('/etc/passwd', function (exists) {
  sys.debug(exists ? "it's there" : "no passwd!");
});

URL

В это модуле собраны инструменты для разрешения и разбора URL. Вызовите require('url') чтобы его использовать.

Объекты разобранного URL имеют либо все либо некоторые из перечисленных полей, в зависимости от их присутствия в строке URL. Части которых не было в URL не будут присутствовать в объекте. Примеры показаны для URL

'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

• href

  Полный URL который был разобран. Пример: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

• protocol

  Протокол запроса. Пример: 'http:'

• host

  Полный host, включая порт и информацию аутентификации. Пример: 'user:pass@host.com:8080'

• auth

  Информация для аутентификации. Пример: 'user:pass'

• hostname

  Имя хоста. Пример: 'host.com'

• port

  Номер порта. Пример: '8080'

• pathname

  Секция пути, которая идёт после хоста и перед строкой параметров, включая начальный слеш если он есть. Пример: '/p/a/t/h'

• search

  Строка запроса, включая ведущий знак вопроса. Пример: '?query=string'

• query

  Параметры из строки запроса, либо уже разобранный объект с параметрами. пример: 'query=string' или {'query':'string'}

• hash

  "Якорь" URL, включая знак решётки. Пример: '#hash'

Модуль URL предоставляет следующие методы:

url.parse(urlStr, parseQueryString=false)

Получает строку URL и возвращает объект. Передайте true вторым аргументом чтобы одновременно разобрать строку запроса модулем querystring.

url.format(urlObj)

Получает объект URL и возвращает отформатированный URL в виде строки.

url.resolve(from, to)

Получает базовый URL и относительный URL, и разрешает их как это сделал бы браузер для гиперссылки.

Строка запроса

Этот модуль предоставляет инструменты для работы со строкой запроса. Он предоставляет следующие методы:

querystring.stringify(obj, sep='&', eq='=', munge=true)

Сериализует объект в строку запроса. Можно менять символы разделителя и присваивания. Пример:

querystring.stringify({foo: 'bar'})
// вернёт
'foo=bar'

querystring.stringify({foo: 'bar', baz: 'bob'}, ';', ':')
// вернёт
'foo:bar;baz:bob'

По умолчанию, эта функция будет преобразовывать параметры для массивов и объектов в стиле PHP/Rails. Пример:

querystring.stringify({foo: 'bar', foo: 'baz', foo: 'boz'})
// вернёт
'foo=boz'

querystring.stringify({foo: {bar: 'baz'}})
// вернёт
'foo[bar]=baz'

Если Вы хотите избежать такого преобразования параметров (например, генерируя параметры для Java сервлета), вы можете передать в аргументе munge значение false. Пример:

querystring.stringify({foo: 'bar', foo: 'baz', foo: 'boz'}, '&', '=', false)
// возвращает
'foo=bar&foo=baz&foo=boz'

Заметьте что когда munge выставлено в false, имена параметров для объектов всё равно будут преобразованы.

querystring.parse(str, sep='&', eq='=')

Десериализует строку запроса в объект. Можно задавать собственные символы разделителя и присваивания.

querystring.parse('a=b&b=c')
// возвращает
{ 'a': 'b'
, 'b': 'c'
}

Эта функция может разбирать также преобразованные строки запроса (см. stringify)

querystring.escape

Функция экранирования, используемая в querystring.stringify, предоставляется для того чтобы проще было заменить её собственной.

querystring.unescape

Функция декодирования, используемая querystring.parse, предоставляется для того чтобы проще было заменить её собственной.

REPL

Интерактивная консоль (Read-Eval-Print-Loop, REPL) доступна как самостоятельная программа и может включаться в другие скрипты. REPL предоставляет возможность интерактивно выполнять JavaScript и сразу видеть результат. Он может использоваться для отладки, тестирования, и просто знакомства с системой.

Выполняя node без аргументов из командной строки вы попадёте прямо в REPL. В нём есть простое редактирование строк по образцу emacs.

mjr:~$ node
Type '.help' for options.
node> a = [ 1, 2, 3];
[ 1, 2, 3 ]
node> a.forEach(function (v) {
...   console.log(v);
...   });
1
2
3

Чтобы использовать продвинутые редакторы, запустите Node с переменной окружения NODE_NO_READLINE=1. Это запустит REPL с обычными терминальными настройками, позволяющими использовать rlwrap.

К примеру, можно добавить следующее к Вашему файлу bashrc:

alias node="env NODE_NO_READLINE=1 rlwrap node"

repl.start(prompt, stream)

Запускает REPL с prompt в качестве приглашения и потоком stream для ввода/вывода. Параметр prompt необязателен и по умолчанию принимает значение node>. Параметр stream также необязателен и по умолчанию принимает значение process.openStdin().

В одном экземпляре node могут быть запущены несколько консолей REPL. Все будут использовать один глобальный объект но разный ввод-вывод.

Вот пример, запускающий консоль REPL на стандартном потоке ввода-вывода, сокете Unix, и TCP-сокете:

var net = require("net"),
    repl = require("repl");

connections = 0;

repl.start("node via stdin> ");

net.createServer(function (socket) {
  connections += 1;
  repl.start("node via Unix socket> ", socket);
}).listen("/tmp/node-repl-sock");

net.createServer(function (socket) {
  connections += 1;
  repl.start("node via TCP socket> ", socket);
}).listen(5001);

Запуск этой программы из командной строки запустит консоль на stdin. Другие клиенты могут подключаться через Unix-сокет или TCP-сокет. telnet можно использовать для подключения к TCP сокетам, и socat можно использовать для обоих типов сокетов.

Запуская REPL на сокете вместо стандартного ввода-вывода Вы можете подключаться к работающему процессу node не перезапуская его.

Возможности REPL

Внутри REPL Control+D завершает его работу. Можно вводить многострочные выражения.

Специальная переменная _ (знак подчёркивания) содержит результат последнего выражения.

node> [ "a", "b", "c" ]
[ 'a', 'b', 'c' ]
node> _.length
3
node> _ += 1
4

REPL предоставляет доступ к любым переменным глобальной области видимости. Вы можете явно передать переменную в REPL, присвоив её объекту scope ассоциированному, с каждым экземпляром REPLServer. Например:

// repl_test.js
var repl = require("repl"),
    msg = "message";

repl.start().scope.m = msg;

Свойства объекта scope выглядят внутри REPL как локальные:

mjr:~$ node repl_test.js
node> m
'message'

В REPL есть несколько специальных команд:

• .break - При вводе многострочного выражения иногда можно ошибиться, либо совсем отказаться от его ввода. .break начнёт ввод заново.

• .clear - Сбрасывает объект scope в пустой и очищает введённое многострочное выражение.

• .exit - Закрывает потоки ввода-вывода, принуждая REPL завершиться.

• .help - Показывает список специальных команд.

Дополнения

Дополнения — это динамически подключаемые объекты. Они могут предоставлять связь с библиотеками на языках C/C++. На данный момент API для дополнения довольно сложное и использует следующие библиотеки:

• Движок V8 JavaScript, написан на C++. Используется для обращения к JavaScript из дополнения: создания объектов, вызова функций и т.д. Документация по нему крайне скудна, в основнос тоит полагаться на заголовочный файл v8.h (deps/v8/include/v8.h в дистрибутиве Node).

• libev, библиотеку обработки цикла событий на C. Каждый раз, когда вам потребуется подождать пока файловый дескриптор станет доступен для чтения, подождать вызова таймера или поступления сигнала, вы будете испльзовать вызовы из libev. Соответственно, вам придётся использовать libev для любых операций ввода/вывода. Node использует цикл событий EV_DEFAULT. Документация доступна на сайте автора.

• libeio, библиотеку пула потоков на C. Она используется для выполнения блокирующих вызовов POSIX асинхронно, в отдельных потоках. Для большинства вызовов существуют стандартные обёртки, которые вы можете найти в заголовочном файле src/file.cc , так что скорее всего вам не понадобится использовать эту библиотеку. Внутренние функции libeio можно посмотреть в файле deps/libeio/eio.h дистрибутива Node.

• Внутренние библиотеки Node. Наиболее важная из них — класс node::ObjectWrap, от которого будут наследоваться большинство ваших классов.

• Остальные доступные библиотеки вы можете найти впапке deps/ дистрибутива Node.

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

В качестве простого примера сделаем дополнение для Node на C++, которое будет делать тоже самое, что и JavaScript код:

exports.hello = 'world';

Создадим файл hello.cc:

#include <v8.h>

using namespace v8;

extern 'C' void
init (Handle<Object> target)
{
  HandleScope scope;
  target->Set(String::New("hello"), String::New("World"));
}

Этот код нужно собрать в файл hello.node, файл бинарного дополнения. Для этого создадим файл wscript, содержащий код на Python (аналог Makefile):

srcdir = '.'
blddir = 'build'
VERSION = '0.0.1'

def set_options(opt):
  opt.tool_options('compiler_cxx')

def configure(conf):
  conf.check_tool('compiler_cxx')
  conf.check_tool('node_addon')

def build(bld):
  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
  obj.target = 'hello'
  obj.source = 'hello.cc'

Теперь можно запустить команду node-waf configure build, которая создаст файл build/default/hello.node, содержащий бинарную версию дополнения.

node-waf — расширение WAF, системы сборки на языке Python. node-waf включён в состав Node для упрощения процесса сборки дополнений.

Каждое дополнение должно содержать функцию init со следующим интерфейсом:

extern 'C' void init (Handle<Object> target)

На данный момент это вся документация по созданию дополнений. В качестве примера вы можете просмотреть код http://github.com/ry/node_postgres.

Оригинальная документация: nodejs.org. Перевод: Сергей Широков и Nodejs.ru.

Поучаствовать в переводе можно на Github