Пример 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/Все примеры в этом руководстве можно запустить таким же образом.
Эти объекты доступны в глобальной области видимости и могут быть использованы в любом месте кода.
Глобальный объект.
Объект процесса. Большая часть данных процесса находится именно здесь.
См. секцию 'Процесс' ниже.
Подключает модули. См. секцию 'Модули'.
Использует внутреннюю логику require() для определение местоположения модуля,
но не загружает его, а возвращает имя файла, содержащего модуль.
Массив путей поиска для require(). Этот массив может быть изменён
для добавления пользовательских путей.
Пример: добавить новый путь в начало массива.
require.paths.unshift('/usr/local/node');Имя исполняемого скрипта. Это абсолютный путь, и не всегда это будет то же имя, которое было передано в аргументе командной строки.
Пример: запускаем node example.js из папки /Users/mjr.
console.log(__filename);
// /Users/mjr/example.jsИмя директории исполняемого скрипта.
Пример: запускаем node example.js из папки /Users/mjr.
console.log(__dirname);
// /Users/mjrСсылка на текущий модуль (типа process.Module). В частности, module.exports —
то же самое, что и объект exports. См. src/node.js для подробной информации.
Позволяет выполнить переданный callback через delay миллисекунд.
Возвращает ID таймаута — timeoutId для последующего использования с clearTimeout().
Отменяет установленный таймаут.
Позволяет выполнять переданный callback каждые delay миллисекунд.
Возвращает ID интервала — intervalId для использования с clearInterval().
Кроме того, можно передавать аргументы callback'у.
Прекращает действие интервального таймера.
Вместе с Node поставляется несколько стандартных встроенных модулей,
большинство из которых описано ниже. Стандартный способ использования этих
модулей — вызов require('name') и сохранение возвращаемого объекта в локальной
переменной с именем, совпадающим с именем модуля.
Пример:
var util = require('util');Также возможно расширение Node другими модулями. См. 'Модули'.
Node использует систему модулей CommonJS.
Node имеет простую систему загрузки модулей, файлы и модули в которой являются,
в каком-то смысле, синонимами. В примере foo.js загружает модуль circle.js,
находящийся в той же директории.
Содержимое foo.js:
var circle = require('./circle');
console.log( 'The area of a circle of radius 4 is '
+ circle.area(4));Содержимое circle.js:
var PI = 3.14;
exports.area = function (r) {
return PI * r * r;
};
exports.circumference = function (r) {
return 2 * PI * r;
};Модуль circle.js экспортирует функции area() и circumference(). Для этого
достаточно добавить экспортируемые функции/объекты к специальному объекты exports.
(В качетве альтернативы можно использовать this вместо exports.) Переменные,
локальные для модуля, не будут видны извне. В этом примере переменная PI видна
только внутри модуля circle.js. Модули, имена которых не начинаются с './'
являются стандартными модулями Node, о них будет рассказано позже.
модули, имена которых начинаются на './' считаются относительными для
вызывающего require() модуля. Это означает, что в примере выше circle.js
должен находиться в той же папке, что и foo.js, тогда require('./circle')
будет работать.
В случае отсутствия './' (например require('assert')), модуль будет искаться
в папках, указаных в массиве require.paths. require.paths обычно выглядит
примерно так:
[ '/home/ryan/.node_modules' ]
Соответственно, при вызове require('foo') Node будет пробовать найти файлы
в следующем порядке:
/home/ryan/.node_modules/foo/home/ryan/.node_modules/foo.js/home/ryan/.node_modules/foo.node/home/ryan/.node_modules/foo/index.js/home/ryan/.node_modules/foo/index.nodeИ остановится как только файл будет найден. Файлы с расширением 'node'
являются C/C++ дополнениями, см. 'C/C++ дополнения' ниже. 'index.js' позволяет
вам собирать модуль в отдельной папке, дающей имя модулю.
Список require.paths можно изменять во время выполнения программы, или задать
с помощью переменной окружения NODE_PATH (содержащей пути, разделённые двоеточием).
Также Node будет производить поиск в папке node_modules в текущей папке,
и выше по дереву проекта. Это позволяет вам иметь различыне версии пакета
для различного окружения. Например, если у вас есть devopment версия и production
версия проекта с различным модулем foo, располагающемся в projects/x/development/node_modules/foo и
projects/x/production/node_modules/foo соответственно.
При последующих вызовах require('foo') поиск не будет происходить второй раз,
а модуль будет загружен из объекта require.cache.
Для того, чтобы определить, какой модуль был загружен при вызове require(),
можно воспользоваться функцией require.resolve().
Дополнения — это динамически подключаемые объекты. Они могут предоставлять связь с библиотеками на языках 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)На данный момент это вся документация по созданию дополнений. В качестве примера вы можете просмотреть код node_postgres.
Объект process — глобальный и может быть использован в любом месте кода.
Является экземпляром EventEmitter.
function () {}
Генерируется перед тем как процесс завершится. Это хорошее место для проверок
состояния модуля (например, юнит-тестов). Event loop не будет действовать
после завершения обработчика 'exit', так что таймеры использовать нельзя.
Пример обработки события 'exit':
process.on('exit', function () {
process.nextTick(function () {
console.log('This will not run');
});
console.log('About to exit.');
});function (err) { }
Генерируется, когда неперехваченное исключение достигает цикла обработки событий. Если этому событию назначен обработчик, стандартное действие (печать стека и выход) производиться не будет.
Пример обработки события 'uncaughtException':
process.on('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 даст вам больший контроль над выполнением вашего кода.
Но для программ, предназначенных для постоянной работы,
'uncaughtException' может быть очень полезным механизмом безопасности.
function () {}
Генерируются когда процесс получает сигнал.
См. sigaction(2) для списка стандартных имён сигналов в POSIX,
таких как SIGINT, SIGUSR1 и т.д.
Пример обработки сигнала SIGINT:
// Start reading from stdin so we don't exit.
process.stdin.resume();
process.on('SIGINT', function () {
console.log('Got SIGINT. Press Control-D to exit.');
});Простой способ отправки сигнала SIGINT: Control-C в большинстве терминальных программ.
Поток с возможностью записи, представляющий стандартный поток вывода stdout.
Пример (определение console.log):
console.log = function (d) {
process.stdout.write(d + '\n');
};Стандартный поток ввода stdin. Этот поток по умолчанию не реагирует на события,
для чтения из него нужно предварительно вызвать process.stdin.resume().
Пример открытия стандартного потока ввода и обработки обоих событий:
process.stdin.resume();
process.stdin.setEncoding('utf8');
process.stdin.on('data', function (chunk) {
process.stdout.write('data: ' + chunk);
});
process.stdin.on('end', function () {
process.stdout.write('end');
});Массив, содержащий аргументы командной строки. Первым элементом будет '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Абсолютный путь к приложению, запустившему процесс.
Пример:
/usr/local/bin/nodeИзменяет текущий рабочий каталог приложения либо генерирует исключение, если изменить каталог не удаётся.
console.log('Starting directory: ' + process.cwd());
try {
process.chdir('/tmp');
console.log('New directory: ' + process.cwd());
}
catch (err) {
console.log('chdir: ' + err);
}Возвращает текущую рабочую директорию процесса.
console.log('Current directory: ' + process.cwd());Объект, хранящий окружение пользователя. См. environ(7).
Завершает процесс с указанным кодом code.
Если код пропущен, завершает процесс со стандартным успешным кодом 0.
Чтобы выйти с ощибочным кодом, нужно вызвать:
process.exit(1);Оболочка, с помощью которой был запущен скрипт в node, должна получить код 1.
Возвращает групповой индикатор процесса (см. setgid(2)). Это числовое значение id группы, а не её имя.
console.log('Current gid: ' + process.getgid());Устанавливает групповой индикатор процесса (см. setgid(2)). Функция принимает как числовое значение, так и его текстовый эквивалент. Если функции передано имя группы, то функция блокирует выполнение кода пока не разрешит имя в числовой идентификатор.
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);
}Возвращает индикатор пользователя-владельца процесса (см. setuid(2)). Это числовой идентификатор, а не имя пользователя.
console.log('Current uid: ' + process.getuid());Устанавливает индикатор пользователя-владельца процесса (см. 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);
}Заданное при компиляции свойство, возвращающее версию Node (NODE_VERSION).
console.log('Version: ' + process.version);Заданное при компиляции свойство, хранящее директорию,
в которую устанавливали Node (NODE_PREFIX).
console.log('Prefix: ' + process.installPrefix);Отправляет сигнал процессу. pid это идентификатор процесса, signal — строка,
обозначающая отправляемый сигнал. Имена сигналов это строки вроде 'SIGINT' или 'SIGUSR1'.
Если имя сигнала пропущено, отправлен будет сигнал 'SIGINT'.
См. kill(2) для более подробной информации.
Заметьте, что хотя функция и называется process.kill,
на самом деле она просто отправляет сигнал, как и системная команда kill.
Отправляемый сигнал может не только завершать целевой процесс.
Пример процесса, отправляющего сигнал самому себе:
process.on('SIGHUP', function () {
console.log('Got SIGHUP signal.');
});
setTimeout(function () {
console.log('Exiting.');
process.exit(0);
}, 100);
process.kill(process.pid, 'SIGHUP');Идентификатор процесса (PID).
console.log('This process is pid ' + process.pid);свойство для определение/задания заголовка, отобращаемого в списке процессов.
Платформа, на которой выполняется node. 'linux2', 'darwin' и т.д.
console.log('This platform is ' + process.platform);Возвращает объект, описывающий потребление памяти процессом Node.
var util = require('util');
console.log(util.inspect(process.memoryUsage()));В результате получим:
{ rss: 4935680,
vsize: 41893888,
heapTotal: 1826816,
heapUsed: 650472 }heapTotal и heapUsed относятся к потреблению памяти движком V8.
На следующей итерации цикла обработки событий запустить указанный обработчик.
Это не простой alias для setTimeout(fn, 0), это намного более эффективный метод.
process.nextTick(function () {
console.log('nextTick callback');
});Задаёт и возвращает маску создания файлов процессом. Дочерние процессы наследуют эту маску от процесса-родителя. Если задан аргумент mask возвращает старую маску, иначе — возвращает текущую.
var oldmask, newmask = 0644;
oldmask = process.umask(newmask);
console.log('Changed umask from: ' + oldmask.toString(8) +
' to ' + newmask.toString(8));Используйте require('util') для доступа к этим функциям.
Синхронный вывод. Заблокирует процесс и выведет строку string
в поток stderr немедленно.
require('util').debug('message on stderr');Выводит строку с меткой времени в stdout.
require('util').log('Timestmaped message.');Возвращает объект object в виде строки, очень удобно для отладки.
Если showHidden имеет значение true, неперечисляемые свойства тоже будут показаны.
Параметр depth он сообщает inspect на какую глубину просмотреть объект,
прежде чем выдавать результат. Это полезно для больших сложных объектов.
По умолчанию принята глубина просмотра 2. Чтобы просмотреть объект
на неограниченную глубину, передайте null в качестве значения depth.
Пример просмотра всех свойств объекта util:
var util = require('util');
console.log(util.inspect(util, true, null));Экспериментальный метод.
Читает данные из потока readableStream и посылает потоку writableStream.
Когда writableStream.write(data) возвращает false readableStream
приостанавливается пока не произойдёт событие drain во writableStream.
callback вызывается после закрытия writableStream. callback принимает
ошибку в случае если writableStream был закрыт или возникла ошибка.
Расширяет конструктор
прототипа методами из другого прототипа. Прототип constructor будет новым объектом, созданным с помощью superConstructor.
Также superConstructor будет доступен через свойство constructor.super_.
var util = require("util");
var events = require("events");
function MyStream() {
events.EventEmitter.call(this);
}
util.inherits(MyStream, events.EventEmitter);
MyStream.prototype.write = function(data) {
this.emit("data", data);
}
var stream = new MyStream();
console.log(stream instanceof events.EventEmitter); // true
console.log(MyStream.super_ === events.EventEmitter); // true
stream.on("data", function(data) {
console.log('Received data: "' + data + '"');
})
stream.write("It works!"); // Received data: "It works!"Множество объектов в Node генерируют события: net.Server вызывает событие
при каждом поступающем запросе, fs.readStream вызывает событие при открытии файла.
Все объекты, генерирующие события, являются экземплярами events.EventEmitter.
Используйте require('events') чтобы получить доступ к модулю.
Обычно события представлены строками в стиле camelCase. Вот несколько примеров:
'stream', 'data', 'messageBegin'. Однако, это только пожелание и никаких
жёстких ограничений на имена событий не накладывается.
К объектам могут быть присоединены функции, которые будут выполняться при генерации события. Эти функции называются обработчиками (listeners).
Класс EventEmitter находится в модуле 'events': require(events').EventEmitter.
Когда источник событий сталкивается с ошибкой, типичное поведение — сгенерировать
событие ошибки 'error'. События ошибки особенные — если им не назначен
обработчик, то они выводят на экран стек вызовов (stack trace) и завершают программу.
Все источники событий генерируют событие 'newListener',
когда к ним добавляются новые обработчики.
Добавляет обработчик в конец массива обработчиков указанного события.
server.on('connection', function (stream) {
console.log('someone connected!');
});Добавляет однократный обработчик указанного события. Обработчик вызываетя один раз при первом наступлении события, после чего удаляется.
server.once('connection', function (stream) {
console.log('Ah, we have our first user!');
});Удаляет обработчик из массива обработчиков указанного события. Внимание: изменяет индексы в массиве обработчиков после указанного обработчика.
var callback = function(stream) {
console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);Удаляет все обработчики из массива обработчиков для указанного события.
По умолчаню EventEmitter выводит предупреждение, если к нему подключено
больше 10-ти обработчиков. Это полезно для поиска утечек памяти.
Но не всегда такое ограничение полезно и возможно. Эта функция позволяет изменить
пороговое значение. Если функции передать значение 0,
то предупреждение не будет выводиться при любом числе обработчиков.
Возвращает массив обработчиков для указанного события. Этот массив может быть использован, например, для удаления обработчиков.
server.on('connection', function (stream) {
console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')); // [ [Function] ]Выполнит все обработчики события по порядку с указанными аргументами.
function (event, listener) { }
Это событие вызывается каждый раз при добавлении обработчика события.
Чистый JavaScript поддерживает Unicode, но в нём нет средств для работы с двоичными данными. При работе с TCP или файловой системой часто необходимо работать именно с потоками двоичных данных. В Node предусмотрено несколько средств управления, создания и приёма двоичных потоков.
Бинарные данные хранятся в экземплярах класса Buffer. Buffer похож на массив целых чисел, но ему соответствует область памяти, выделенная вне стандартной кучи V8. Размер Buffer невозможно изменить после создания.
Объект Buffer существует в глобальном пространстве имён.
При преобразовании между буферами и строками JavaScript требуется явно указывать метод кодирования символов. Node поддерживает 3 кодировки для строк:
'ascii' — только для 7-битных ASCII-строк. Этот метод кодирования очень
быстрый, и будет сбрасывать старший бит символа, если тот установлен.
'utf8' — Unicode-символы. Многие веб-страницы и документы используют UTF-8.
'binary' — устаревший способ. Хранит двоичные данные в строке используя
младшие 8 бит каждого символа. Не используйте эту кодировку.
Создаёт новый буфер размера size байт.
Создаёт новый буфер из массива array 8-битных символов.
Создаёт новый буфер, содержащий строку str в кодировке encoding.
Записывает строку string в буфер по смещению offset от его начала
с использованием указанной кодировки. Возвращает количество записанных байт.
Если buffer не имеет достаточно места для сохранения всей строки,
то метод запишет только её часть. В случае если кодировка строки — 'utf8',
то метод не будет записывать частичные символы.
Пример: записать UTF-8 строку в буфер, потом напечатать его.
buf = new Buffer(256);
len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(len + " bytes: " + buf.toString('utf8', 0, len));
// 12 bytes: ½ + ¼ = ¾Декодирует и возвращает строку из данных буфера, закодированных в кодировке
encoding начиная с позиции start и заканчивая позицией end.
См. пример buffer.write() выше.
Получает или устанавливает байт на позиции index. Значения соответствуют индивидуальным
байтам и могут лежать в пределах от 0x00 до 0xFF в шестнадцатиричной записи
и от 0 до 255 в десятичной.
Пример: скопировать ASCII строку в буфер, байт за байтом.
str = "node.js";
buf = new Buffer(str.length);
for (var i = 0; i < str.length ; i++) {
buf[i] = str.charCodeAt(i);
}
console.log(buf);
// node.jsПроверяет, является ли obj буфером.
Возвращает количество байт в строке. Это не то же самое что String.prototype.length,
так как этот метод возвращает число символов в строке.
Пример:
str = '\u00bd + \u00bc = \u00be';
console.log(str + ": " + str.length + " characters, " +
Buffer.byteLength(str, 'utf8') + " bytes");
// ½ + ¼ = ¾: 9 characters, 12 bytesРазмер буфера в байтах. Заметьте, что это значение не всегда соответствует размеру
содержимого. length возвращает объем памяти, зарезервированный для объекта буфера.
Это значение не изменяется при изменении содержимого буфера.
buf = new Buffer(1234);
console.log(buf.length);
buf.write("some string", "ascii", 0);
console.log(buf.length);
// 1234
// 1234Копирует данные между буферами с помощью memcpy().
Пример: создадим два буфера, потом скопировать buf1
с байта 16 по байт 19 в buf2, начиная с 8-го байта в buf2.
buf1 = new Buffer(26);
buf2 = new Buffer(26);
for (var i = 0 ; i < 26 ; i++) {
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!!!!!!!!!!!!!Возвращает новый буфер, указывающий на ту же область памяти что предыдущий,
но начиная со start и заканчивая end байтами.
Изменение содержимого нового буфера затронет содержимое старого!
Пример: построить буфер с ASCII-алфавитом, вырезать часть в новый буфер, затем изменить 1 часть в оригинальном буфере.
var buf1 = new Buffer(26);
for (var i = 0 ; i < 26 ; i++) {
buf1[i] = i + 97; // 97 is ASCII a
}
var 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Поток — это абстрактный интерфейс, реализуемый многими объектами в Node.
Например, запрос к HTTP-серверу является потоком, также как stdout. Потоки
могут быть с возможностью чтения, записи или и того и другого. Все потоки
являются экземплярами EventEmitter.
Поток с возможностью чтения имеет следующие методы, свойства и события.
function (data) { }
Событие 'data' передаёт обработчику либо Buffer (по умолчанию),
либо строку, если предварительно был вызван setEncoding().
function () { }
Генерируется когда поток получает символ конца файла EOF (FIN в терминологии TCP).
Означает что событий 'data' больше не предвидится. Если поток также имеет
возможность записи, писать данные можно и дальше.
function (exception) { }
Генерируется если при приёме данных произошла ошибка.
function () { }
Генерируется когда соответствующий потоку файловый дескриптор закрывается.
Не все потоки генерируют это событие. Например, входящий HTTP запрос
не генерирует 'close'.
function (fd) { }
Генерируется когда поток получает файловый дескриптор. Только UNIX потоки поддерживают этот функционал; остальные никогда не генерируют это событие.
A boolean that is true by default, but turns false after an 'error'
occured, the stream came to an 'end', or destroy() was called.
Заставляет событие 'data' передавать обработчику строку вместо буфера.
encoding может быть 'utf8', 'ascii' или 'base64'.
Прекращает поступление событий 'data'.
Возобновляет поступление событий 'data' после pause().
Закрывает соответствующий потоку файловый дескриптор. Поток больше не будет генерировать событий.
Соединяет поток с возможностью чтения с потоком destination, доступным для записи.
Все читаемые этим поток данные будут записаны в destination. Для синхронизации
вшуюсяпотоков можно использовать stream.pause() и stream.resume().
Пример эмуляции UNIX-команды cat:
process.stdin.resume();
process.stdin.pipe(process.stdout);По умолчанию при поступлдении события end у источника будет вызван метод end()
у приёмника destination is no longer writable. Если в качестве options
передать { end: false }, то поток-приёмник останется открытым после закрытия потока-источника:
process.stdin.resume();
process.stdin.pipe(process.stdout, { end: false });
process.stdin.on("end", function() {
process.stdout.write("Goodbye\n");
});ПРИМЕЧАНИЕ: Если поток-источник не поддерживает pause() и resume(), эта функция
одобалвяет в объект простую реализацию этих функцйи, вызывающую события
'pause' и 'resume', соответственно.
У потока с возможностью записи есть следующие методы, свойства и события.
function () { }
Генерируется после вызова метода write() вернувшего false — сигнал о том,
что можно писать дальше.
function (exception) { }
Генерируется при ошибке с исключением exception.
function () { }
Генерируется когда закрывается соответствующий потоку дескриптор.
Булево свойство, по умолчанию true, но становящиеся false после наступления
события 'error' или вызова end() / destroy().
Записывает строку string в указанной кодировке encoding в поток. Возвращает
true если строка попала в буфер ядра. Возвращает false если буфер ядра полон
и данные будут отправлены позже. Когда данные будут отправлены и буфер ядра опустеет,
будет сгенерировано событие 'drain'. Кодировка по умолчанию — 'utf8'.
Если указан необязательный параметр fd, он интерпретируется как файловый
дескриптор для отправки в поток. Это поддерживается только в UNIX потоках,
и просто игнорируется в другом окружении. Когда дескриптор пересылается таким
образом, если он будет закрыт до события 'drain' потока, может быть отправлен
повреждённый (закрытый) дескриптор.
То же что и выше, но с использованием буфера.
Закрывает поток отправкой EOF или FIN.
Посылает строку string в указанной кодировке encoding и закрывает поток
отправкой EOF или FIN. Так можно уменьшить общее число отправленных пакетов.
То же что выше но с использованием буфера.
Закрывает соответствующий потоку файловый дескриптор. Поток больше не будет генерировать событий.
Закрывает соответствующий потоку файловый дескриптор после того, как очередь записи окажется пустой.
Используйте require('crypto') чтобы получить доступ к функциям модуля.
Криптографический модуль требует для своей работы наличия OpenSSL. Он предоставляет возможность использовать аутентификацию в HTTPS и HTTP-соединениях.
Модуль также предоставляет набор обёрток для некоторых методов OpenSSL: hash, hmac, cipher, decipher, sign и verify.
Создаёт объект данных аутентификации, может принимать параметром объект со следующими свойствами:
key : строка с PEM-закодированным приватным ключом,cert : строка с PEM-закодированным сертификатом,ca : строка или список строк PEM-закодированных доверенных корневых сертификатов.Если корневые сертификаты не указаны, node.js будет использовать список доверенных сертификатов, расположенный по адресу http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt.
Создает и возвращает объект hash, который может быть использован
для создания криптографических хэшей по заданному алгоритму.
Возможные значения для algorithm зависят от доступных алгоритмах в той версии OpenSSL,
которая у вас установлена. Например, это может быть 'sha1', 'md5' и т.д.
В последней версии OpenSSL список поддерживаемых алгоритмов можно было узнать
с помощью команды openssl list-message-digest-algorithms.
Обновляет содержимое на data. Этот метод может быть вызван несколько раз.
Вычисляет хеш от всех поступивших данных.
Параметр encoding может равняться 'hex', 'binary' или 'base64'.
Создает и возвращает объект hmac, который может быть использован
для создания хеш-кода идентификации сообщений (HMAC) по заданному алгоритму и ключу.
Возможные значения для algorithm зависят от доступных алгоритмах в OpenSSL,
см. описание для crypto.createHash() выше. key определяет используемый ключ.
Обновляет содержимое на data. Этот метод может быть вызван несколько раз.
Вычисляет хеш от всех поступивших данных.
Параметр encoding может равняться 'hex', 'binary' или 'base64'.
Создает и возвращает объект cipher, который может быть использован
для шифрования по заданному алгоритму и ключу.
Возможные значения для algorithm зависят от доступных алгоритмах в той версии OpenSSL,
которая у вас установлена. Например, это может быть 'aes192', 'blowfish' и т.д.
В последней версии OpenSSL список поддерживаемых алгоритмов можно было узнать
с помощью команды openssl list-cipher-algorithms.
Обновляет содержимое на data, кодировку которых задаёт аргумент input_encoding
(может равняться 'utf8', 'ascii' или 'binary'). Аргумент output_encoding
определяет выходной формат и может равняться 'binary', 'base64' или 'hex'.
Возвращает зашифрованного содержимого и может быть названо много раз с новыми данными.
Возвращает все оставшиеся зашифрованного содержимого в кодировке output_encoding,
которая может равняться 'binary', 'ascii' или 'utf8'.
Создает и возвращает объект decipher, который может быть использован
для дешифрования по заданному алгоритму и ключу. Это объект-близнец для объекта cipher.
Обновляет содержимое на data, формат которых задаёт аргумент input_encoding
(может равняться 'binary', 'base64' или 'hex'). Аргумент output_encoding
определяет выходную кодировку и может равняться 'utf8', 'ascii' или 'binary'.
Возвращает все оставшиеся разшифрованного содержимого в виде простого текста. Значение аргументо output_encoding объяснено выше.
Создает и возвращает объект signer, который может быть использован
для создания электронной подписи по заданному алгоритму.
Обновляет содержимое на data. Этот метод может быть вызван несколько раз.
Вычисляет подпись для всех данных. private_key задаёт закрытый ключ в формате PEM.
Возвращает подпись в формате output_format, который может равняться 'binary', 'hex' или 'base64'.
Создает и возвращает объект verifier, который может быть использован
для проверки электронной подписи. Это объект-близнец для объекта signer.
Обновляет содержимое на data. Этот метод может быть вызван несколько раз.
Проверяет данные с помощью открытого ключа public_key в формате PEM и подписи
signature формата signature_format (может равняться 'binary', 'hex' или 'base64'.
Возвращает true или false в зависимости от действительности подписи и публичного ключа.
Используйте require('tls') чтобы получить доступ к функциям этого модуля.
Модуль tls использует OpenSSL чтобы предоставить Transport Layer Security и/или
Secure Socket Layer (SSL): зашифрованные соединения.
TLS/SSL это инфраструктура с публичными ключами. Каждый клиент и каждый сервер должны иметь собственный приватный ключ. Приватный ключ создаётся таким образом:
openssl genrsa -out ryans-key.pem 1024Все серверы и некоторые клиенты должны иметь сертификат. Сертификаты это публичные ключи подписанные Центром Сертификации или самим создателем сертификата. Первый шаг в получени сертификата: создание файла запроса на подпись сертификата (CSR, Certificate Signing Request). Это делается следующим образом:
openssl req -new -key ryans-key.pem -out ryans-csr.pemЧтобы создать самостоятельно подписанный сертификат CSR, сделайте:
openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pemЛибо Вы можете отправить CSR в Центр Сертификации для подписи.
(TODO: docs on creating a CA, for now interested users should just look at
test/fixtures/keys/Makefile in the Node source code)
Создаёт новое соединение на выбранный порт и хост (хост по умолчанию - localhost). Опции options должны быть объектом, содержащим
key: Строка или буфер содержащие приватный ключ сервера в формате PEM (обязательно)
cert: Строка или буфер содержащие ключ сертификата сервера в формате PEM.
ca: Массив строк или буферов с доверенными сертификатами. Если этот массив пропущен, будут использованы "корневые" Центры Сертификации, например VeriSign. Они будут использованы для авторизации соединения.
tls.connect() возвращает текстовый объект CryptoStream.
После рукопожатия TLS/SSL вызывается переданная функция. Вызов произойдёт независимо от того был ли авторизрван сертификат. Пользователь сам должен проверить значение s.authorized чтобы увидеть был ли сертификат подписан одним из указанных центров. Если s.authorized === false то в переменной s.authorizationError будет содержаться объект соответствующей ошибки.
Этот класс - подкласс net.Server и имеет те же методы. Вместо приёма простых TCP соединений он принимает защищённые соединения с использованием TLS или SSL.
Простой пример эхо-сервера (возвращает полученные данные):
var tls = require('tls');
var fs = require('fs');
var options = {
key: fs.readFileSync('server-key.pem'),
cert: fs.readFileSync('server-cert.pem')
};
tls.createServer(options, function (s) {
s.write("welcome!\n");
s.pipe(s);
}).listen(8000);Вы можете проверить сервер, присоединившись к нему с помощью openssl s_client:
openssl s_client -connect 127.0.0.1:8000Это конструктор для класса tls.Server. Объект опций может содержать следующие значения:
key: Строка или буфер содержащие приватный ключ сервера в формате PEM (обязательно)
cert: Строка или буфер содержащие ключ сертификата сервера в формате PEM.
ca: Массив строк или буферов с доверенными сертификатами. Если этот массив пропущен, будут использованы "корневые" Центры Сертификации, например VeriSign. Они будут использованы для авторизации соединения.
requestCert: Если принимает значение true сервер будет запрашивать у клиентов сертификаты и пытаться проверять их подлинность. По умолчанию принимает значение false.
rejectUnauthorized: Если равно true сервер будет сбрасывать соединения сертификаты которых не подтверждены списком доверенных Центров Сертификации. Эта опция действует только если requestCert равен true. Значение по умолчанию: false.
function (cleartextStream) {}
Это событие генерируется при приёме нового соединения после успешного прохождения рукопожатия. Аргумент - экземпляр stream.Stream открытый на чтение и запись. Он имеет все методы и события обычного потока.
cleartextStream.authorized - двоичное значение, сообщающее что клиент был проверен одним из заданных для сервера доверенных Центров Сертификации. Если это свойство принимает значение false, в cleartextStream.authorizationError будет храниться ошибка авторизации. Стоит заметить что в зависимости от настроек TLS-сервера неавторизованные соединения могут приниматься либо сбрасываться.
Начинает приём соединений на указанном порту и адресе. Если адрес не указан, сервер принимает соединения на любой адрес IPv4 (INADDR_ANY).
Эта функция асинхронна. Коллбек, переданный последним параметром, будет вызван когда сервер будет готов к приёму соединений.
См. net.Server для дальнейшей информации.
Прекращает приём новых соединений сервером. Эта функция асинхронна, сервер окончательно закрывается когда генерируется событие 'close'.
Задайте это свойство чтобы сбрасывать новые соединения как только количество одновременных соединений достигнет указанного значения.
Число одновременных соединений с сервером.
Файловый ввод/вывод обеспечивается с помощью простой обертки вокруг стандартных
функций 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));
});
});В нагруженных процессах программисту строго рекомендуется использовать асинхронные версии вызовов. Синхронные версии будут блокировать весь процесс до своего завершения — предотвращая любые новые соединения.
Асинхронное переименование (rename(2)). Обработчику не передаётся аргументов кроме возможного исключения.
Синхронный rename(2).
Асинхронный ftruncate(2). Обработчику не передаётся аргументов кроме возможного исключения.
Синхронный ftruncate(2).
Асинхронное изменение прав доступа (chmod(2)). Обработчику не передаётся аргументов кроме возможного исключения.
Синхронный chmod(2).
Асинхронный stat(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 ниже для дополнительной информации.
Асинхронный lstat(2). Обработчик получает два аргумента (err, stats),
где stats это экземпляр fs.Stats.
Асинхронный fstat(2). Обработчик получает два аргумента (err, stats),
где stats это экземпляр fs.Stats.
Синхронный stat(2). Возвращает экземпляр fs.Stats.
Синхронный lstat(2). Возвращает экземпляр fs.Stats.
Синхронный fstat(2). Возвращает экземпляр fs.Stats.
Асинхронное создание ссылки (link(2)). Передаваемой функции не передаётся ничего кроме возможного исключения.
Синхронный link(2).
Асинхронное создание символической ссылки (symlink(2)). Передаваемой функции не передаётся ничего кроме возможного исключения.
Синхронный symlink(2).
Асинхронное разрешение ссылки (readlink(2)).
Обработчик принимает два аргумента (err, resolvedPath).
Синхронный readlink(2). Возвращает полученный путь.
Асинхронный realpath(2).
Обработчик принимает два аргумента (err, resolvedPath).
Синхронный realpath(2). Возвращает полученный путь.
Асинхронный unlink(2). Передаваемой функции не передаётся ничего кроме возможного исключения.
Синхронный unlink(2).
Асинхронный rmdir(2). Передаваемой функции не передаётся ничего кроме возможного исключения.
Синхронный rmdir(2).
Асинхронный mkdir(2). Передаваемой функции не передаётся ничего кроме возможного исключения.
Синхронный mkdir(2).
Асинхронное чтение содержимого директории (readdir(3)).
Обработчик принимает два аргумента (err, files),
где files это массив имён файлов в директории исключая '.' и '..'.
Синхронный readdir(3). Возвращает массив имён файлов исключая '.' и '..'.
Асинхронный close(2). Передаваемой функции не передаётся ничего кроме возможного исключения.
Синхронный close(2).
Асинхронное открытие файла. См. open(2).
Флаги могут быть 'r', 'r+', 'w', 'w+', 'a' или 'a+'.
Обработчик принимает два аргумента (err, fd).
Синхронный open(2).
Записывает буфер buffer в файл указанный дескриптором fd.
Сдвиг offset и длина length определяют часть буфера, которая будет записана.
Позиция position задаёт смещение от начала файла куда должны быть записаны данные.
Если position равна null, данные записываются с текущей позиции. См. pwrite(2).
Обработчик принимает два аргумента (err, written),
где written указывает сколько байт было записано в файлn.
Синхронная версия fs.write(). Возвращает число записанных байт.
Синхронная версия fs.write(), записывающая в файл строку, а не буфер.
Возвращает число записанных байт.
Читает данные из файла, указанного дескриптором fd.
buffer — буфер, в который будут помещены прочитанные данные.
offset — смещение внутри буфера с которого начнётся запись.
length — число байт для чтения.
position — число означающее позицию, с которой начнётся чтение файла.
Если position принимает значение null, данные будут прочитаны с текущей позиции.
Функция-обработчик принимает два аргумента, (err, bytesRead).
Синхронная версия fs.read. Возвращает количество прочитанных байт.
Синхронная версия fs.read, читающая из файл строку, а не буфер.
Возвращает количество прочитанных байт.
Асинхронно загружает в память содержимое файла. Пример:
fs.readFile('/etc/passwd', function (err, data) {
if (err) throw err;
console.log(data);
});Обработчику передаются два аргумента: (err, data), где data — содержимое файла.
Если кодировка не указана, возвращается буфер.
Синхронная версия fs.readFile. Возвращает содержимое файла filename.
Если указана кодировка encoding, то функция возвращает строку. Иначе — возвращает буфер.
Асинхронно записывает данные в файл. data может быть строкой или буфером.
Пример:
fs.writeFile('message.txt', 'Hello Node', function (err) {
if (err) throw err;
console.log('It\'s saved!');
});Синхронная версия fs.writeFile.
Наблюдает за изменениями файла 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.
Прекращает обрабатывать изменения файла filename.
Объекты, возвращаемые fs.stat(), fs.lstat() и fs.fstat() являются
экземплярами этого класса.
stats.isFile()stats.isDirectory()stats.isBlockDevice()stats.isCharacterDevice()stats.isSymbolicLink() (доступно только после fs.lstat())stats.isFIFO()stats.isSocket()ReadStream является потоком с возможностью чтения.
Возвращает новый объект ReadStream.
options это объект со следующими полями по умолчанию:
{ flags: 'r',
encoding: null,
mode: 0666,
bufferSize: 4096 }Объект options может содержать поля start и end для чтения фрагмента файла
вместо всего файла. И start, и end являются границами с включением
и начинаюся с 0. При использовании необходимо задавать обе границы
Пример чтения последних 10 байт файла размером 100 байт:
fs.createReadStream('sample.txt', {start: 90, end: 99});WriteStream является потоком с возможностью записи.
function (fd) { }
fd содержит файловый дескриптов, используемый WriteStream.
Возвращает новый объект WriteStream.
options это объект со следующими свойствами по умолчанию:
{ flags: 'w',
encoding: null,
mode: 0666 }Этот модуль содержит средства для работы с путями.
Используйте require('path') чтобы получить к нему доступ.
Нормализует строку пути, обрабатывая '..' и '.'.
Пример:
path.normalize('/foo/bar/baz/asdf/quux/..')
// returns
'/foo/bar/baz/asdf'Соединяет все аргументы и нормализует получившийся путь.
Пример:
node> require('path').join(
... '/foo', 'bar', 'baz/asdf', 'quux', '..')
'/foo/bar/baz/asdf'Разрешает путь to в абсолютный.
Если to не является абсолютным, то к нему добавляют пути, справа налево,
из аргументов from до тех пор, пока полученный путь не будет абсолютным.
Если в итоге путь останется относительным, он будет разрешён относительно
рабочей директории. полученный путь нормализуется и у него удаляется
завершающий слеш, если конечно это не корневая директория.
Возможно, вам будет проще понять механизм работы этого метода,
если считать что он последовательно выполняет команду cd и возвращает конечный путь, т.е.
path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')возвращает тоже самое, что и:
cd foo/bar
cd /tmp/file/
cd ..
cd a/../subfile
pwdРазница в том, что промежуточные пути могут не существовать или быть файлами.
Примеры:
path.resolve('/foo/bar', './baz')
// returns
'/foo/bar/baz'
path.resolve('/foo/bar', '/tmp/file/')
// returns
'/tmp/file'
path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
// if currently in /home/myself/node, it returns
'/home/myself/node/wwwroot/static_files/gif/image.gif'Возвращает имя директории для пути. Действует как Unix-команда dirname.
Пример:
path.dirname('/foo/bar/baz/asdf/quux')
// returns
'/foo/bar/baz/asdf'Возвращает последнюю часть пути. Действует как Unix-команда basename.
Пример:
path.basename('/foo/bar/baz/asdf/quux.html')
// returns
'quux.html'
path.basename('/foo/bar/baz/asdf/quux.html', '.html')
// returns
'quux'Возвращает расширение пути. Учитывается всё после последней '.' в последней части пути. Если в последней части нет '.' или '.' единственный символ, возвращает пустую строку.
Пример:
path.extname('index.html')
// returns
'.html'
path.extname('index')
// returns
''Проверяет, существует ли данный путь. Вызывает переданный обработчик
с аргументом true или false.
Пример:
path.exists('/etc/passwd', function (exists) {
util.debug(exists ? "it's there" : "no passwd!");
});Модуль net предоставляет асинхронные методы для работы с сетью. Он включает
методы для создания как серверов, так и клиентов (называемых потоками).
Вы может использовать этот модуль вызвав require("net").
Создаёт новый TCP сервер. Аргумент connection_listener автоматически
становится обработчиком события 'connection'.
Создаёт новый сокет. Когда соединение установлено, будет сгенерировано
событие 'connect'.
Аргументы для этого метода определяются тепим соединения:
net.createConnection(port, [host])
Открывает TCP-соединение с указанным портом port и адресом host.
Если второй параметр не задан, предполагается значение localhost.
net.createConnection(path)
Создаёт соединение с Unix-сокетом path.
Этот класс используется для создания TCP или UNIX сервера.
Вот простой пример сервера, который возвращает полученный запрос и слушает на порту 8124:
var net = require('net');
var server = net.createServer(function (stream) {
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');Начинает принимать соединения на указанном порту port и имени хоста host.
Если host пропущен, сервер будет принимать соединения
на каждом IPv4-адресе (INADDR_ANY).
Эта функция асинхронна. Последний параметр callback будет вызван когда сервер
начнёт принимать соединения.
Запускает сервер слушающий UNIX-сокет по указанному адресу path.
Эта функция асинхронна. Последний параметр callback будет вызван когда сервер
начнёт принимать соединения.
Используйте nc для подключения к серверу с помощью UNIX-сокета:
nc -U /tmp/echo.sockЗапускает сервер, слушающий указанный файловый дескриптор.
Для указанного файлового дескриптора должны быть уже выполнены
системные вызовы bind(2) и listen(2).
Прекращает приём соединений сервером. Эта функция асинхронна,
сервер полностью закрывается только после генерации события 'close'.
Возвращает адрес, к которому привязан сервер. Удобно использовать, если выбор адреса предоставляется системе.
Пример:
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);
});Установите это свойство, если хотите запретить серверу принимать больше определённого числа соединений единовременно.
Текущее число соединений с сервером.
net.Server — экземпляр EventEmitter со следующими событиями:
function (socket) {}
Генерируется при новом соединении. socket — экземпляр net.Socket.
function () {}
Генерируется при завершении работы сервера.
Этот объект — абстракция TCP порта или UNIX сокета. Экземпляр net.Socket
имеет возможность как чтения, так и записи. Он может быть создан и использован
как клиентом (с помощью connect()) либо создан внутри Node и передан
пользователю через обработчик события 'connection'.
Открывает TCP-соединение с указанным портом port и адресом host. Если второй
параметр не задан, предполагается значение localhost. Если указан параметр
path, то создаёт соединение с Unix-сокетом path.
Обычно этот метод не нужен. Используйте его только если поток закрыт и вы хотите повторно использовать тот же объект для соединения с другим сервером.
Эта функция асинхронна. Когда генерируется событие 'connect', соединение
установлено. Если при соединении возникли проблемы, событие 'connect'
не будет сгенерировано, вместо него будет сгенерировано событие 'error'
с аргументом исключения.
Функция callback будет добавлена как обработчик события 'connect'.
Задаёт кодировку ('ascii', 'utf8' или 'base64') для принимаемых данных.
Эта функция удалена в v0.3. Она использовалась для установки защищённого соединения. См. модуль TLS с описанием нового API.
Отправляет данные в поток. Второй параметр означает кодировку, если первым параметром передана строка. По умолчанию используется UTF-8.
Возвращает true если все данные были успешно переданы в буфер ядра. Возвращает
false если все данные или их часть были помещены в очередь в памяти. Событие
'drain' будет сгенерировано когда буфер ядра снова будет пуст.
Необязательый параметр-функци callback будет вызвана после завершения записи данных.
UNIX-сокеты позволяют передавать через них файловые дескрипторы между приложениями.
Для этого достаточно передать параметр fileDescriptor и ожидать события 'fd'
во втором приложении.
Наполовину закрывает соединение, т.е. отправляет пакет FIN. Возможно сервер ещё получит какие-то данные.
Если определён аргумент data, то этот вызов эквивалентен последовательному вызову
socket.write(data, encoding) и socket.end().
Закрывает сокет таким образом чтобы в нём больше не происходило ввода-вывода. Необходимо только для закрытия соединения в случае серьёзных ошибок.
Приостанавливает чтение данных. Т.е. события 'data' не будут генерироваться. Используется при приёме файлов.
Возобновляет чтение данных после вызова pause().
Устанавливает таймаут в timeout миллисекунд бездействия сокета. По умолчанию
net.Stream не имеет таймаута.
Если сокет не будет проявлять активности указанное количество миллисекунд будет
сгенерировано событие 'timeout', но само соединение не будет затронуто.
Пользователь должен самостоятельно вызвать end() или destroy() для закрытия сокета.
Если в качестве timeout передан 0, существующий таймаут перестаёт действовать.
Выключает алгоритм Нагла. По умолчанию TCP-соединения используют алгоритм Нагла,
собирая данные в буфер перед отправкой. Установка noDelay приведёт к немедленной
отправке всех данных, передаваемых в stream.write().
Включает/выключает функционал keep-alive, и дополнительно позволяет установить
начальную задержку после которой будет отправлен первый пакет проверки соединения
при неактивности. Значение initialDelay (в миллисекундах) означает интервал
между последним отправленным пакетом и первой проверкой соединения. Установка
initialDelay в 0 оставит в силе предыдущее значение.
Строковое представление удалённого IP адреса. Например, '74.125.127.100' или
'2001:4860:a005::68'.
Это свойство доступно только для соединений сервер-сервер.
Экземпляры net.Stream — экземпляры EventEmitter со следующими событиями:
function () { }
Генерируется после успешной установки соединения. См. connect().
function (data) { }
Генерируется при приёме данных. Аргумент data будет экземпляром Buffer
или String. Кодировка передаваемых данных устанавливается методом
socket.setEncoding(). (См. секцию о потоках с возможностью чтения для
более подробной информации.)
function () { }
Генерируется когда другой участник соединения посылает пакет FIN.
По умолчанию (allowHalfOpen == false) сокет уничтожает свой файловый дескриптор
после завершения обработки очереди записи. Но если установить allowHalfOpen == true,
то поток не будет автоматически завершаться (end()), т.е. пользоввателю
требуется вручную вызвать end().
function () { }
Генерируется если сокет долгое время не используется. Это просто уведомление о длительной неактивности сокета. Пользователь должен сам закрыть соединение.
См. также: socket.setTimeout().
function () { }
Генерируется когда буфер записи становится пустым (все данные, переданные в поток, были отправлены получателю). Может быть использоваться для отправки файлов.
function (exception) { }
Генерируется при возникновении ошибки. Сразу после этого будет сгенерировано
событие 'close'.
function (had_error) { }
Генерируется один раз когда поток полностью закрывается. Аргумент had_error — двоичное значение, устанавливаемое в true если поток был закрыт из за ошибки передачи.
Проверяет. является ли input валидным IP адресом. Возвращает 0 для неверных строк,
4 для IPv4 адресов и 6 для IPv6 адресов.
Возвращает true если input является IPv4 адресов, в осатльных случаях false.
Возвращает true если input является IPv6 адресов, в осатльных случаях false.
Используйте 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));
addresses.forEach(function (a) {
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));
}
});
});
});Resolves a domain (e.g. 'google.com') into the first found A (IPv4) or
AAAA (IPv6) record.
The callback has arguments (err, address, family). The address argument
is a string representation of a IP v4 or v6 address. The family argument
is either the integer 4 or 6 and denotes the family of address (not
neccessarily the value initially passed to lookup).
Разрешает домен (например '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.resolve(), но только для IPv4 адресов (записи типа A).
addresses это массив IPv4 адресов (например['74.125.79.104', '74.125.79.105', '74.125.79.106']).
То же что dns.resolve4() но только для IPv6 адресов (записи типа AAAA).
То же что dns.resolve(), но только для MX-записей.
addresses это массив MX записей, каждая с атрибутами priority и exchange
(например [{'priority': 10, 'exchange': 'mx.example.com'},...]).
То же что dns.resolve(), но только для текстовых записей (тип записи TXT).
addresses это массив текстовых записей, доступных для домена domain
(например ['v=spf1 ip4:0.0.0.0 ~all']).
То же, что dns.resolve(), но только для service records (записей SRV).
addresses это массив SRV записей, доступных для домена domain.
Свойства SRV записей: priority, weight, port, и name
(например, [{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]).
Обратно разрешает IP-адрес в массив доменных имён.
Аргументы обработчика: (err, domains).
Если произошла ошибка, err будет ненулевым экземпляром объекта Error.
Каждый запрос к DNS может вернуть код ошибки.
dns.TEMPFAIL: таймаут, SERVFAIL или что-то подобное.dns.PROTOCOL: получен повреждённый ответ.dns.NXDOMAIN: домен не существует.dns.NODATA: домен существует, но нет данных требуемого типа.dns.NOMEM: при обработке закончилась память.dns.BADQUERY: запрос неверно сформирован.Сокеты для датаграмм доступны при включении require('dgram'). Датаграммы
чаще всего обрабатываются как сообщения IP/UDP, но они могут быть использованы
и с доменными сокетами Unix.
function (msg, rinfo) { }
Генерируется когда новая датаграмма доступна на сокете. msg это Buffer,
а rinfo это объект с информацией об адресе отправителя и количестве байт в датаграмме.
function () { }
Генеритуется когда сокет начинает приём датаграмм. Для UDP-сокета это происходит
при создании. Сокеты Unix не начинают приём до вызова для них bind().
function () { }
Генерируется когда сокет закрывается с помощью close().
События message на этом сокете больше не будут генерироваться.
Создаёт сокет для датаграмм заданного типа. Доступные типы: udp4, udp6 и unix_dgram.
Принимает необязательную функцию, которая добавляется обработчиком событий message.
Для датаграмм на 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.");
});Для UDP сокета, адрес назначения представляет port and IP-адрес. В качетве
аргумента address может быть передана строка, которая может быть разрешена
с помощью DNS. Принимает необязательную функцию, которая будет вызвана после
завершения разрешения DNS имени и когда буфер можно будет использовать заново.
Следует иметь в виду, что DNS запросы требуют времени, по крайне мере
до следующего витка цикола событий. Единственный способ узнать, что отправка
состоялась — использовать callback.
Пример отправки UDP-пакета на произвольный порт localhost:
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();Для 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);Для 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Закрывает сокет и прекращает приём данных.
Возвращает объект с информацией об адресе, на который настроен сокет. Для UDP
сокетов этот объект содержит свойства address и port, а для Unix-сокетов
только свойство address.
Устанавливает или сбрасывает опцию SO_BROADCAST сокета. если эта опция установлена,
то UDP пакеты могут оправляться по широковещательному адресу локального интерфейса.
Устанавливает опуцию IP_TTL сокета. TTL означает "время жизни", и его значение
определяет количество IP, сквозь которые может быть передан пакет. Каждый роутер
или шлюз на пути пакета уменьшают TTL. Как только он станет равным нуля, пакет уничтожится.
Изменение TTL может быть полезно для тестирования сети или широковещательной рассылки.
Аргументом setTTL() является число от 1 до 255. По умолчанию на большинстве
систем ипользуется 64.
Для использования клиента и сервера HTTP необходимо подключить
соответствующий модуль с помощью require('http').
Интерфейс HTTP спроектирован в Node таким образом, чтобы поддерживать многие возможности протокола, которые традиционно было довольно сложно использовать. В частности, большие сообщения с возможным chunk-encoding. Интерфейс никогда не сохраняет в буфере целиком запрос или ответ, давая пользователю возможность принимать и отправлять данные в потоковом режиме.
Заголовки сообщения HTTP представлены примерно таким объектом:
{ 'content-length': '123',
'content-type': 'text/plain',
'connection': 'keep-alive',
'accept': '*/*' }Ключи приводятся к нижнему регистру. Значения не изменяются.
Для поддержки всего спектра возможных применений HTTP, соответствующее API в Node довольно низкоуровневое. Оно основано на потоках и передаче сообщений. Node разбирает HTTP-сообщение на заголовки и тело, остальное должен сделать программист.
HTTPS поддерживается если на целевой платформе доступен OpenSSL.
Это EventEmitter со следующими событиями:
function (request, response) { }
Генерируется каждый раз при получении запроса. Заметьте, что в течении одного
соединения может происходить несколько запросов (в случае keep-alive соединения).
Объект request — экземпляр http.ServerRequest,
объект response — экземпляр http.ServerResponse.
function (stream) { }
Генерируется при установке нового HTTP-соединения. stream — объект типа net.Stream.
Обычно пользователи не используют это событие. Объект потока stream также можно
найти в свойстве объекта запроса request.connection.
function (errno) { }
Генерируется при завершении работы сервера.
function (request, response) {}
Событие наступает кажды раз при получении заголовка 'Expect: 100'.
Если для этого события не назначен ни один обработчик, то сервер автоматически
отвечает '100 Continue'.
Обработка этого события подразумевает вызов response.writeContinue если клиент
должен продолжить отправку тела запроса, или генерацию другого HTTP запроса
(например '400 Bad Request') если клиент не должен этого делать.
Имейте в виду, что если это событие наступило и было обработано, то событие
request не наступает.
function (request, socket, head)
Генерируется каждый раз когда клиент запрашивает апгрейд соединения до защищённого (см. RFC 2817). Если это событие никак не обрабатывается соединение для которого запрошен апгрейд будет закрыто.
request — аргументы для HTTP запроса, как в событии 'request'.socket — сетевой сокет между сервером и клиентом.head — экземпляр Buffer, первый пакет защищенного потока, может быть пустым.После генерации этого события, у объекта server не будет обработчика события
data, и программисту нужно назначить его заново чтобы обрабатывать данные,
получаемые этим соединением.
function (exception) {}
Если соединение с клиентом генерирует событие 'error' — оно поднимается сюда.
Возвращает новый объект web-сервера.
Функция requestListener автоматически добавляется к событию 'request' сервера.
Начинает приём соединений на указанном порту и имени хоста. Если имя хоста не указано,
сервер будет принимать соединения на любой IPv4-адрес машины (INADDR_ANY).
Чтобы слушать unix-сокет, передайте имя файла вместо порта и имени хоста.
Эта функция асинхронна. Функция, переданная последним параметром callback
будет вызвана когда сервер будет связан с портом.
Начинает слушать unix-сокет с заданным путём path.
Эта функция асинхронна. Функция, переданная последним параметром callback
будет вызвана когда сервер будет связан с сокетом.
Прекращает приём новых соединений сервером.
Этот объект создаётся автоматически HTTP-сервером (не пользователем)
и передаётся первым аргументом обработчику события 'request'.
Это EventEmitter со следующими событиями:
function (chunk) { }
Генерируется при получении части тела сообщения.
Пример: Часть тела сообщения передаётся как единственный аргумент. Сообщение
уже раскодировано из transfer-encoding. Часть тела представлена в виде строки.
Кодировка тела сообщения задаётся request.setBodyEncoding().
function () { }
Генерируется строго один раз для каждого сообщения. Нет аргументов. После этого события запрос не будет генерировать другие.
Метод запроса в виде строки. Только для чтения. Пример 'GET' или 'DELETE'.
Строка с 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' }Заголовки запроса. Только для чтения.
HTTP trailers (если есть). Только для чтения.
Доступны тольк после наступления события 'end'.
Версия протокола HTTP в виде строки. Только чтение. Пример: '1.1', '1.0'.
Также request.httpVersionMajor содержит первое число и request.httpVersionMinor — второе.
Задаёт кодировку тела запроса. Либо 'utf8', либо 'binary'. По умолчанию
принимает значение null, что означает что в обработчик события 'data'
поступает буфер.
Прекращает генерирование событий запросом. Можно использовать для ускорения закачки файла.
Возобновляет генерирование событий запросом
Объект соединения, экземпляр net.Stream.
При поддержке HTTPS достоверность и содержимое сертификата могут быть проверены
с помощью методов verifyPeer() и getPeerCertificate()
объекта request.connection сервера.
Этот объект создаётся внутри HTTP-сервера — не пользователем. Он передаётся
вторым параметром в обработчик события 'request' и является потоком с возможностью записи.
Отправдяет клиенту сообщение 'HTTP/1.1 100 Continue', которое разрешает
отправку тела запроса. См. описанеи события checkContinue объекта http.Server.
Отправляет заголовки ответа клиенту. statusCode это три цифры кода статуса HTTP,
например 404. Последний аргумент, headers, это заголовки ответа. Также вторым
аргументом можно передать фразу reasonPhrase.
Пример:
var body = 'hello world';
response.writeHead(200, {
'Content-Length': body.length,
'Content-Type': 'text/plain' });Этот метод должен быть вызван только однажды для каждого сообщения
и должен быть вызван до response.end().
Этот метод должен вызываться после writeHead. Он отправляет часть тела ответа.
Метод может быть вызван несколько раз для отправки последующих частей тела ответа.
Аргумент chunk может быть буфером или строкой. Если chunk это строка, то
бойвторой параметр указывает в какой кодировке отправлять её в поток.
По умолчанию encoding принимает значение 'utf8'.
Замечание: Это необработанное тело HTTP-ответа и не имеет отношения к более высокоуровневым вещам вроде multi-part encoding, которые тоже могут использоваться.
После первого вызова response.write() клиенту будет отправлены заголовки
и первая часть тела сообщения. После второго вызова response.write() Node
предполагает что вы начинаете потоковую передачу данных и отправляет часть
тела отдельно. Таким образом, данные буферизуются только до первой части тела ответа.
Этот метод добавляет завершающие заголовки HTTP, следующие после тела ответа.
Эти заголовки могут быть использованы **только* в случае использование ответом
chunked encoding; в противном случае они будут проигнорированы.
Имейте в виду, что протокол HTTP требует указания заголовка Trailer
в случае использования HTTP trailers, например:
response.writeHead(200, { 'Content-Type': 'text/plain',
'Trailer': 'TraceInfo' });
response.write(fileData);
response.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});
response.end();Этот метод отправляет серверу сигнал что все заголовки и тело ответа отправлены;
сервер должен считать это сообщение законченным. Метод response.end()
ДОЛЖЕН быть вызван при каждом ответе.
Если задан аргумент data, то этот вызов эквивалентен поледовательному вызову
response.write(data, encoding) и response.end().
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.on('response', function (response) {
console.log('STATUS: ' + response.statusCode);
console.log('HEADERS: ' + JSON.stringify(response.headers));
response.setEncoding('utf8');
response.on('data', function (chunk) {
console.log('BODY: ' + chunk);
});
});Нужно иметь в виду следующие особенности реализации:
Заголовок 'Host' не добавляется Node, но обычно требуется для работы с сайтами.
Отправка заголовка 'Connection: keep-alive' сообщает Node о необходимости сохранять соединения для последующих запросов.
Отправка заголовка 'Content-length' отключит 'chunked encoding'.
Отправка заголовка 'Expect' немедленно приведёт к отправке всех заголовков.
Обычно, при отправке 'Expect: 100-continue', вы должны установить таймаут
и установить обработчик события continue.
См. RFC2616 Section 8.2.3
для дополнительной информации.
function (request, socket, head)
Генерируется каждый раз когда сервер отвечает на запрос предложением улучшить
соединение до безопасного. Если это событие не обрабатывается, клиент
при получении заголовка upgrade будет закрывать соединение.
См. описание события upgrade для http.Server.
function ()
Наступает если сервер отправляет ответ с кодом '100 Continue', обычно в случае если зщапрос включает заголовк 'Expect: 100-continue'. Это является указанием клиенту на необходимость начала отправки тела запроса.
Создаёт новый 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.
Отправляет запрос; при необходимости инициирует соединение.
Возвращает экземпляр http.ClientRequest.
method — необязательный параметр, по умолчанию принимает значение 'GET'.
request_headers необязательный параметр. Дополнительные заголовки запроса
могут быть добавлены внутри Node. Возвращает объект http.ClientRequest.
Не забудьте включить заголовок Content-Length если планируете отправить тело
запроса. Если вы хотите отправить тело запроса потоком, поставьте
Transfer-Encoding: chunked.
ВНИМАНИЕ: запрос ещё не закончен. Этот метод только отсылает заголовки серверу.
Необходимо вызвать request.end() чтобы отправить запрос целиком и получить ответ.
(Это звучит сложно, но позволяет пользователю передавать тело запроса
в потоковом режиме с помощью request.write().)
Возвращает true или false в зависимости от подлинности сертификата сервера соответственно списку доверенных сертификатов CA (переданному явно или используемому по умолчанию).
Возвращает JSON с деталями сертификата сервера, содержит поля 'subject', 'issuer', 'valid_from' и 'valid_to'.
Объект создаётся внутри Node и возвращается методом request() объекта http.Client.
Он представляет собой незаконченный запрос, заголовки которого уже отправлены.
Чтобы получить ответ, добавьте обработчик событию 'response' объекта запроса.
Событие 'response' будет сгенерировано объектом запроса при получении
заголовков ответа. Обработчик события 'response' выполняется с одним
аргументом — экземпляром http.ClientResponse.
Во время события 'response' можно добавлять обработчики к объекту ответа;
в частности, чтобы получать части тела ответа надо добавить обработчик
событию 'data'. Заметьте что обработчик события 'response' вызывается
до того, как будут получены части тела ответа, поэтому не надо беспокоиться,
что первая часть тела будет пропущена. Если обработчик 'data' добавляется
во время события 'response', то всё тело ответа будет получено наверняка.
// Good
request.on('response', function (response) {
response.on('data', function (chunk) {
console.log('BODY: ' + chunk);
});
});
// Bad - misses all or part of the body
request.on('response', function (response) {
setTimeout(function () {
response.on('data', function (chunk) {
console.log('BODY: ' + chunk);
});
}, 10);
});Это поток с возможностью записи.
Это экземпляр EventEmitter со следующими событиями:
function (response) { }
Генерируется когда на запрос приходит ответ. Это событие генерируется только
один раз. Аргументом обработчика response будет экземпляр http.ClientResponse.
Отправляет часть тела запроса. Вызывая этот метод несколько раз, пользователь
может отправлять тело ответа серверу в потоковом режиме — в таком случае
предпочтительно добавлять в заголовки ['Transfer-Encoding', 'chunked']
при создании запроса.
Аргумент chunk должен быть массивом чисел или строкой.
Аргумент encoding необязателен и имеет значение только если chunk строка.
Завершает отправку запроса. Если какие то части тела запроса ещё не были
отправлены, они отправляются. Если запрос разбит на части, будет послана
завершающая последовательность '0\r\n\r\n'.
Если задан аргумент data, то этот вызов эквивалентен поледовательному вызову
request.write(data, encoding) и request.end().
Этот объект создаётся при создании запроса с помощью http.Client.
Он передаётся обработчику события 'response' объекта запроса.
Объект ответа — поток с возможностью чтения.
function (chunk) {}
Часть тела сообщения передаётся обработчику в качестве единственного аргуметна.
Строка уже преобразована из кодировки с помощью которой осуществлялась передача.
Часть тела сообщения передаётся обработчику в виде строки. Кодировка тела
сообщения задаётся response.setBodyEncoding().
function () {}
Генерируется только однажды для каждого сообщения. Обработчик вызывается без аргументов. После этого сообщение не будет генерировать никаких событий.
Код статуса HTTP из трёх цифр, например 404.
Версия HTTP для текущего соединения. Скорее всего либо '1.1', либо '1.0'.
Также response.httpVersionMajor — первая цифра версии,
а response.httpVersionMinor — вторая.
Заголовки ответа.
См. описание выше.
Задаёт кодировку тела ответа. Может принимать значения 'utf8', 'ascii'
или 'base64'. По умолчанию используется null, что означает что в обработчик
события 'data' поступает буфер.
Приостанавливает генерацию событий ответом. Можно использовать для ускорения закачки файла.
Возобновляет генерацию событий ответом.
Ссылка на http.Client которому принадлежит ответ.
В это модуле собраны инструменты для разрешения и разбора 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' or {'query':'string'}
hash: "Якорь" URL, включая знак решётки.
Пример: '#hash'
Модуль URL предоставляет следующие методы:
Получает строку URL и возвращает объект. Передайте true вторым аргументом
чтобы одновременно разобрать строку запроса модулем querystring.
Получает объект URL и возвращает отформатированный URL в виде строки.
Получает базовый URL и относительный URL, и разрешает их как это сделал бы браузер для гиперссылки.
Этот модуль предоставляет инструменты для работы со строкой запроса.
Используйте require('querystring') чтобы получить доступ к функциям модуля.
Сериализует объект в строку запроса. Можно менять символы разделителя и присваивания.
Пример:
querystring.stringify({foo: 'bar'})
// returns
'foo=bar'
querystring.stringify({foo: 'bar', baz: 'bob'}, ';', ':')
// returns
'foo:bar;baz:bob'Десериализует строку запроса в объект. Можно менять символы разделителя и присваивания.
Пример:
querystring.parse('a=b&b=c')
// returns
{ a: 'b', b: 'c' }Функция экранирования, используемая в querystring.stringify,
предоставляется для того чтобы проще было заменить её собственной.
Функция декодирования, используемая querystring.parse,
предоставляется для того чтобы проще было заменить её собственной.
Интерактивная консоль (Read-Eval-Print-Loop, REPL) доступна как самостоятельная программа и может включаться в другие скрипты. REPL предоставляет возможность интерактивно выполнять JavaScript и сразу видеть результат. Он может использоваться для отладки, тестирования, и просто знакомства с системой.
Выполняя node без аргументов из командной строки вы попадёте прямо в REPL.
В нём есть простое редактирование строк по образцу emacs.
mjr:~$ node
Type '.help' for options.
> a = [ 1, 2, 3];
[ 1, 2, 3 ]
> 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 с prompt в качестве приглашения и потоком stream для ввода/вывода.
Параметр prompt необязателен и по умолчанию принимает значение '>'.
Параметр stream также необязателен и по умолчанию принимает значение process.stdin.
В одном экземпляре 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-сокет. Для подключения
к TCP сокетам можно использовать telnet, a socat можно использовать
для обоих типов сокетов.
Запуская REPL на сокете вместо стандартного ввода-вывода Вы можете подключаться к работающему процессу node не перезапуская его.
Внутри REPL Control+D завершает его работу. Можно вводить многострочные выражения.
Специальная переменная _ (знак подчёркивания) содержит результат последнего выражения.
> [ "a", "b", "c" ]
[ 'a', 'b', 'c' ]
> _.length
3
> _ += 1
4REPL предоставляет доступ к любым переменным глобальной области видимости.
Вы можете явно передать переменную в REPL, присвоив её объекту context,
ассоциированному с каждым экземпляром REPLServer. Например:
// repl_test.js
var repl = require("repl"),
msg = "message";
repl.start().context.m = msg;Свойства объекта context выглядят внутри REPL как локальные:
mjr:~$ node repl_test.js
> m
'message'В REPL есть несколько специальных команд:
.break - При вводе многострочного выражения иногда можно ошибиться,
либо совсем отказаться от его ввода. .break начнёт ввод заново..clear - Сбрасывает объект context в пустой и очищает введённое многострочное выражение..exit - Закрывает потоки ввода-вывода, принуждая REPL завершиться..help - Показывает список специальных команд.Node предоставляет tri-directional popen(3) в классе ChildProcess.
С дочерним потоком можно обмениваться данными через stdin, stdout и stderr
в полностью неблокирующем стиле.
Для создания дочернего процесса используйте require('child_process').spawn().
С дочерним процессом всегда ассоциированы три потока:
child.stdin, child.stdout и child.stderr.
ChildProcess — экземпляр EventEmitter.
function (code, signal) {}
Это событие генерируется при завершении дочернего процесса. Если процесс
завершён нормально, в code передаётся код завершения процесса, иначе
передаётся null. Если процесс завершился от принятия сигнала, то signal —
это строка, содержащая имя сигнала, либо null.
См. также: waitpid(2).
Поток с возможностью записи, связанный со stdin процесса дочернего.
Закрытие потока с помощью end() часто приводит к завершению процесса.
Поток с возможностью чтения, связанный со stdout дочернего процесса.
Поток с возможностью чтения, связанный со stderr дочернего процесса.
Идентификатор дочернего процесса.
Пример:
var spawn = require('child_process').spawn,
grep = spawn('grep', ['ssh']);
console.log('Spawned child pid: ' + grep.pid);
grep.stdin.end();Запускает новый процесс с указанной командой command и аргументами командной
строки args. Если аргументы пропущены, args будет пустым массивом.
Третий аргумент функции используется для задания дополнительных опций со следующими значениями по умолчанию:
{ cwd: undefined,
env: process.env,
customFds: [-1, -1, -1],
setsid: false
}cwd позволяет вам задать рабочую папку для дочернего процесса.
Используйте env для определия переменных окружения, видимых дочернему процессу.
С помощью customFds возможно связать stdin, stout и stderr дочернего процесса
с существующими потоками; -1 означает, что нужно создать новый поток.
Если setsid истинно, то процесс будет создан в новой пользовательской сессии.
Пример запуска ls -lh /usr, чтения stdout, stderr и получения кода завершения:
var util = require('util'),
spawn = require('child_process').spawn,
ls = spawn('ls', ['-lh', '/usr']);
ls.stdout.on('data', function (data) {
console.log('stdout: ' + data);
});
ls.stderr.on('data', function (data) {
console.log('stderr: ' + data);
});
ls.on('exit', function (code) {
console.log('child process exited with code ' + code);
});Пример: достаточно сложный способ выполнить 'ps ax | grep ssh'.
var util = require('util'),
spawn = require('child_process').spawn,
ps = spawn('ps', ['ax']),
grep = spawn('grep', ['ssh']);
ps.stdout.on('data', function (data) {
grep.stdin.write(data);
});
ps.stderr.on('data', function (data) {
console.log('ps stderr: ' + data);
});
ps.on('exit', function (code) {
if (code !== 0) {
console.log('ps process exited with code ' + code);
}
grep.stdin.end();
});
grep.stdout.on('data', function (data) {
console.log(data);
});
grep.stderr.on('data', function (data) {
console.log('grep stderr: ' + data);
});
grep.on('exit', function (code) {
if (code !== 0) {
console.log('grep process exited with code ' + code);
}
});Пример проверки ошибки запуска приложения:
var spawn = require('child_process').spawn,
child = spawn('bad_command');
child.stderr.on('data', function (data) {
if (/^execvp\(\)/.test(data.asciiSlice(0,data.length))) {
console.log('Failed to start child process.');
}
});См. также: child_process.exec().
Высокоуровневый способ выполнить команду в качестве дочернего процесса, сохранить весь её вывод, и передать его в callback.
var util = require('util'),
exec = require('child_process').exec,
child;
child = exec('cat *.js bad_file | wc -l',
function (error, stdout, stderr) {
console.log('stdout: ' + stdout);
console.log('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: 'SIGTERM',
cwd: null,
env: null }Если timeout больше 0, процесс будет завершён, если он выполняется дольше,
чем timeout миллисекунд. Дочерний процесс завершается с помощью сигнала
killSignal. В maxBuffer указывается максимальный объём данных, разрешённый
на stdout или stderr — если этот объём будет превышен,
то дочерний процесс будет завершён.
Отправляет сигнал дочернему процессу. Если аргументы не переданы, то процессу
будет отправлен сигнал 'SIGTERM'. См. signal(7) для списка возможных имён сигналов.
var spawn = require('child_process').spawn,
grep = spawn('grep', ['ssh']);
grep.on('exit', function (code, signal) {
console.log('child process terminated due to receipt of signal '+signal);
});
// send SIGHUP to process
grep.kill('SIGHUP');Заметьте, что хотя функция называется kill, сигнал, отправляемый дочернему процессу,
не обязательно его завершит. Метод kill просто отправляет сигналы.
См. также: kill(2).
Этот модуль используется для написания юнит-тестов для ваших приложений,
вы можете использовать его вызвав require('assert').
Проверяет что actual соответствует expected используя указанный оператор.
Проверяет что значение value равно true, то же самое что
assert.equal(true, value, message);.
Неглубокая проверка на равенство с использованием соответствующего оператора ( == ).
Неглубокая проверка на неравенство с использованием соответствующего оператора ( != ).
Глубокая проверка на равенство.
Глубокая проверка на неравенство.
Проверка на строгое равенство, с использованием соответствующего оператора ( === ).
Проверка на строгое неравенство, с использованием соответствующего оператора ( !== ).
Ожидает что блок кода block вызовет ошибку error.
error может быть конструкторов, регулярным выражением или функцией валидации.
Проверка ошибки по типу конструктора:
assert.throws(
function() {
throw new Error("Wrong value");
},
Error
);Проверка ошибки с помощью регулярного выражения:
assert.throws(
function() {
throw new Error("Wrong value");
},
/value/
);Произвольная проверка с помощью функции валидации:
assert.throws(
function() {
throw new Error("Wrong value");
},
function(err) {
if ( (err instanceof Error) && /value/.test(err) ) {
return true;
}
},
"unexpected error"
);Ожидает что блок кода block не вызовет ошибки.
См. описание параметров для assert.throws.
Проверяет что value имеет значение false, бросает исключение встретив true.
Удобно для проверки первого аргумента функций-обработчиков, error.
Используйте require('tty') чтобы получить доступ к этому модулю.
Запускает новый процесс с исполняемымы файлом указанным в переменной path в новом псевдо-терминале.
Возвращает массив [slaveFD, childProcess]. slaveFD это файловый дескриптор конца псевдотерминала, принадлежащего потомку. childProcess это объект дочернего процесса.
Возвращает true или false в зависимости от того принадлежит ли файловый дескриптор fd терминалу.
Переменная mode должна принимать значение true или false. Это задает режим работы потоков ввода-вывода текущего процесса: raw device или default.
Возвращает число столбцов в терминале текущего процесса.
Заметьте что каждый раз когда это число меняется процесс получает сигнал SIGWINCH. Поэтому можно организовать такой кеш:
var columns = tty.getColumns();
process.on('SIGWINCH', function() {
columns = tty.getColumns();
});Этот модуль содержит функции для определения параметров системы.
Используйте require('os') чтобы получить к нему доступ.
Возвращает имя компьютера в сети.
Возвращает имя операционной системы.
Возвращает версию операционной системы.
Возвращает время работы системы в секундах с последней перезагрузки.
Возвращает массив, содержащия среднюю загрузку системы за последние 1, 5 и 15 минут.
Возвращает полный объём памяти, доступной системе.
Возвращает объём свободной памяти.
Возвращает массив объектов, содержащих информацию о каждом процессоре/ядре системы: модель, частоту в мегагерцах и время в тиках, проводимое в состояниях user, nice, sys, idle и irq.
Example inspection of os.cpus:
[ { model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 252020,
nice: 0,
sys: 30340,
idle: 1070356870,
irq: 0 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 306960,
nice: 0,
sys: 26980,
idle: 1071569080,
irq: 0 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 248450,
nice: 0,
sys: 21750,
idle: 1070919370,
irq: 0 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 256880,
nice: 0,
sys: 19430,
idle: 1070905480,
irq: 20 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 511580,
nice: 20,
sys: 40900,
idle: 1070842510,
irq: 0 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 291660,
nice: 0,
sys: 34360,
idle: 1070888000,
irq: 10 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 308260,
nice: 0,
sys: 55410,
idle: 1071129970,
irq: 880 } },
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz',
speed: 2926,
times:
{ user: 266450,
nice: 1480,
sys: 34920,
idle: 1072572010,
irq: 30 } } ]Вместе с V8 идет мощный отладчик, доступный прямо в процессе выполнения через простой TCP протокол.
В Node есть встроенный клиент для этого отладчика. Чтобы его использовать, запустите Node с ключом debug; появится следующее приглашение:
% node debug myscript.js
debug>Пока myscript.js ещё не запущен. Чтобы запустить скрипт, введите команду run. Если всё в порядке, вывод будет выглядеть примерно так:
% node debug myscript.js
debug> run
debugger listening on port 5858
connecting...okОтладчик Node не поддерживает полный набор команд но выполнение и просмотр окружения вполне возможны. Добавив строку debugger; в исходный код, вы добавляете точку остановки.
Например, предположим что myscript.js выглядит так:
// myscript.js
x = 5;
setTimeout(function () {
debugger;
console.log("world");
}, 1000);
console.log("hello");При запуске в режиме отладки остановка произойдёт на четвёртой строке.
% ./node debug myscript.js
debug> run
debugger listening on port 5858
connecting...ok
hello
break in #<an Object>._onTimeout(), myscript.js:4
debugger;
^
debug> next
break in #<an Object>._onTimeout(), myscript.js:5
console.log("world");
^
debug> print x
5
debug> print 2+2
4
debug> next
world
break in #<an Object>._onTimeout() returning undefined, myscript.js:6
}, 1000);
^
debug> quit
A debugging session is active. Quit anyway? (y or n) y
%Команда print позволяет просматривать переменные. Команда next выполняет следующую строку скрипта. Кроме этого доступно ещё несколько команд, и ещё больше будут добавлены. Введите help чтобы увидеть остальные.
Отладчик V8 может быть включен и использован либо при запуске Node с ключом --debug или при передаче существующему процессу Node сигнала SIGUSR1.
Для Node есть множество модулей. Их список можно найти в вики на GitHub.
Это приложение предназначено для новичков, чтобы помочь им быстро найти качественные модули. Этот список не претендует на полноту. Мы будем рады дополнениям к этому списку.