Стримы и backpressure
Сервис, который читает файл целиком перед отправкой, на файле в 2 ГБ и десяти параллельных запросах займёт десятки гигабайт — задолго до того, как упрётся в лимит контейнера. Стримы решают эту задачу иначе: данные идут чанками, а буфер между производителем и потребителем ограничен. Разберём типы потоков, механизм backpressure, разницу между pipe и pipeline и то, как перейти от буферов в памяти к честной потоковой обработке.
Содержание
- Зачем нужны стримы
- Четыре типа потоков
- Readable: flowing, paused и async iteration
- Writable и backpressure
- pipe, pipeline и finished
- Ошибки, destroy и отмена
- Потоковая обработка больших файлов
- Свои Transform и object mode
- Web Streams и совместимость
- Частые ошибки
- Эксперименты
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Зачем нужны стримы
Разница между readFile и createReadStream — не в удобстве API, а в профиле памяти. readFile сначала выделяет буфер под весь файл и только потом возвращает результат. Один запрос к файлу в 2 ГБ — это 2 ГБ в arrayBuffers; десять одновременных запросов — 20 ГБ, OOM и падение сервиса. Подробнее о том, почему буферы живут вне кучи V8, — в статье «Встроенные модули Node.js».
Стрим не загружает файл целиком. Он читает очередной кусок размером порядка highWaterMark, отдаёт его потребителю и ждёт, пока тот освободит место. Пока сокет медленно отправляет данные, файловый поток приостанавливает чтение; в памяти висит одно окно, а не весь файл. Это свойство называют backpressure — обратным давлением: медленный потребитель тормозит быстрого производителя, вместо того чтобы копить данные.
Стримы — не отдельная библиотека для редких задач, а основа сетевого слоя Node: http.IncomingMessage и http.ServerResponse, fs.createReadStream, net.Socket, zlib, шифрование и child_process работают через них. Поэтому понимание потоков нужно и для HTTP-сервера, и для загрузки файлов, и для проксирования ответов.
Цена — сложность. У потока несколько состояний, ошибки приходят событиями, а не исключениями, а цепочку нужно собирать так, чтобы при сбое закрылись все ресурсы. Ниже — минимальный набор правил, который делает эту сложность управляемой.
Четыре типа потоков
Все потоки строятся на четырёх базовых классах из node:stream:
| Тип | Что делает | Типичные представители |
|---|---|---|
Readable | источник данных | fs.createReadStream(), http.IncomingMessage, process.stdin |
Writable | приёмник данных | fs.createWriteStream(), http.ServerResponse |
Duplex | и источник, и приёмник; стороны независимы | net.Socket, tls.TLSSocket |
Transform | Duplex, который преобразует вход в выход | zlib.createGzip(), crypto.createCipheriv() |
PassThrough — вырожденный Transform, который ничего не меняет: удобен, чтобы вклиниться в цепочку, наблюдать чанки или разделить поток на две ветки.
Потоки совместимы по интерфейсу: у читаемого есть pipe(), read(), события data/end, у записываемого — write(), end(), drain. Кроме событий, любой поток можно обходить асинхронным итератором for await, а Readable.from() строит читаемый поток из массива, синхронного или асинхронного генератора.
Node-стримы — наследники EventEmitter, поэтому событие error у них подчиняется тем же правилам: без слушателя процесс падает. Общая механика разобрана в статье «EventEmitter и события».
Readable: flowing, paused и async iteration
У читаемого потока три режима, и от выбранного зависит, кто управляет темпом.
| Режим | Как включается | Кто задаёт скорость |
|---|---|---|
| flowing | подписка на data или resume() | поток: выдаёт чанки, не ожидая потребителя |
| paused | read(), событие readable, pause() | потребитель: забирает данные по мере готовности |
| async iteration | for await (const chunk of stream) | потребитель: цикл ждёт обработки каждого чанка |
В flowing mode обработчик data вызывается на каждый чанк, а поток продолжает читать. Если обработчик медленный, данные не теряются, но копятся в буфере потока и входящего сокета: data не даёт обратного давления. Поэтому тяжёлая синхронная работа в data — такая же проблема, как в HTTP-обработчике: она блокирует event loop и не даёт источнику остановиться.
Paused mode — pull-модель: потребитель вызывает read(size), получает чанк или null, а событие readable сообщает, что данные появились. Так работает и асинхронный итератор, который предпочтителен в новом коде:
import { createReadStream } from 'node:fs';
const source = createReadStream('access.log', { encoding: 'utf8' });
for await (const chunk of source) {
await processChunk(chunk); // цикл ждёт обработки, поток не бежит вперёд
}
Три детали, которые легко упустить.
for await даёт backpressure. Пока тело цикла не завершилось, следующая порция не запрашивается; буфер источника заполняется до highWaterMark и чтение останавливается.
break разрушает поток. Выход из цикла по break, return или исключению вызывает destroy() — файловый дескриптор закрывается. Это удобно, но означает, что «прочитать первые десять строк» нельзя, не закрыв поток; для такого чтения лучше readline или явный read().
Не смешивайте режимы. Если на потоке уже висит обработчик data, он переводит поток в flowing, и for await начнёт конкурировать с ним за чанки. Один потребитель — один режим.
setEncoding('utf8') или опция encoding превращает буферы в строки. Внутри используется StringDecoder, который склеивает разрезанный на границе чанка многобайтовый символ, — вручную через chunk.toString() этого не получить.
Writable и backpressure
Writable принимает чанки через write() и передаёт их в реализацию _write() по одному. Пока запись не завершилась, следующие чанки лежат во внутреннем буфере. Его размер и ограничивает highWaterMark.
import { once } from 'node:events';
import { createWriteStream } from 'node:fs';
const dest = createWriteStream('out.log');
for (const chunk of chunks) {
if (!dest.write(chunk)) {
await once(dest, 'drain'); // буфер заполнен — ждём, пока он опустеет
}
}
dest.end();
write() возвращает true, пока объём буфера меньше порога, и false, когда порог достигнут или превышен. false — не ошибка, а просьба остановиться: следующий write() разрешён после события drain. Если сигнал игнорировать, буфер вырастет до размера всех данных: исключения не будет, но память и задержка будут расти, пока процесс не упадёт по OOM.
У читаемой стороны зеркальная логика: push(chunk) возвращает false, когда внутренняя очередь заполнена, и источник перестаёт вызывать _read(), пока потребитель не заберёт данные.
Размеры по умолчанию:
- с Node 22 дефолт
stream— 64 КиБ для байтовых потоков (до этого — 16 КиБ); - в object mode — 16 объектов;
- текущие значения доступны через
stream.getDefaultHighWaterMark(objectMode), изменить глобально —stream.setDefaultHighWaterMark().
highWaterMark — порог, а не лимит. Он определяет, когда поток перестаёт просить новые данные, но не запрещает принять чанк больше порога и не ограничивает сумму уже принятых чанков. Реальная память — это буфер, а не константа в конструкторе.
Порог выбирают под задачу. Слишком маленький — больше системных вызовов и переключений; слишком большой — больше памяти на каждое соединение. При 10 000 открытых сокетов разница между 16 и 64 КиБ на поток составляет сотни мегабайт потенциального буфера, поэтому в чувствительных к памяти сервисах размер задают явно.
Инспектировать состояние помогают writableLength, writableNeedDrain, writableHighWaterMark и readableLength.
pipe, pipeline и finished
readable.pipe(writable) соединяет потоки и управляет скоростью: при write() === false вызывает pause() у источника, на drain — resume(), а по завершении вызывает dest.end(). Этого достаточно для простой передачи, но не для надёжной цепочки.
Чего pipe не делает:
- не пробрасывает ошибку из одной стадии в другую;
- не разрушает источник, если приёмник упал, — файл или сокет может остаться открытым;
- не гарантирует очистку слушателей при ошибке;
- не сообщает вызывающему коду, что цепочка завершилась (нет ни промиса, ни колбэка);
- не гарантирует, что ошибка не станет необработанным событием
errorи не уронит процесс.
pipeline из node:stream/promises закрывает эти пробелы: связывает стадии, при ошибке любой из них вызывает destroy(err) на всех и отклоняет промис. Он же ждёт фактического завершения и закрытия ресурсов.
import { createReadStream, createWriteStream } from 'node:fs';
import { createGzip } from 'node:zlib';
import { pipeline } from 'node:stream/promises';
await pipeline(
createReadStream('access.log'),
createGzip(),
createWriteStream('access.log.gz'),
);
pipeline принимает не только потоки, но и асинхронные генераторы в роли источника или трансформации, поддерживает Web Streams (с Node 18.16 и 19.7) и опции:
{ signal }— отмена черезAbortSignal; стадии разрушаются с ошибкой отмены (AbortErrorилиTimeoutError);{ end: false }— не закрывать последний поток автоматически.
finished решает другую задачу — дождаться, что поток больше не читается и не пишется:
import { finished } from 'node:stream/promises';
await finished(dest);
Он отклоняется на error, но ничего не разрушает и не управляет цепочкой. Его место — ожидание конкретного потока: дописать лог перед выходом, дождаться закрытия сокета, проверить поток в тесте. Для цепочки из нескольких стадий нужен pipeline, а не набор finished.
События завершения различаются:
end— источник выдал все данные, но потребитель мог их ещё не обработать;finish— приёмник принял и сбросил всё, что ему передали;close— базовый ресурс (файл, сокет) закрыт, обычно послеdestroy().
pipeline ждёт не только finish, но и закрытия ресурсов, поэтому его промис — более сильная гарантия, чем finish на последнем потоке.
Ошибки, destroy и отмена
Ошибка в потоке приходит событием error, а не исключением в точке вызова. Без слушателя это необработанное событие: процесс завершается. Поэтому в ручной цепочке на каждый поток нужен обработчик, а в pipeline — try/catch вокруг await.
import { pipeline } from 'node:stream/promises';
try {
await pipeline(source, transform, destination);
} catch (err) {
logger.error({ err }, 'поток упал');
}
pipeline вызывает destroy(err) на всех стадиях, кроме уже завершившихся. destroy() освобождает ресурс, после чего поток эмитит error и close. С Node 14 autoDestroy включён по умолчанию: поток разрушается сам после end, finish или ошибки, поэтому повторно использовать его нельзя.
В собственной реализации Writable ошибку сообщают через колбэк, а не throw:
_write(chunk, _encoding, callback) {
save(chunk)
.then(() => callback())
.catch(callback); // ошибка уйдёт в 'error' и в pipeline
}
Отмена нужна там, где работа может длиться дольше, чем нужно: клиент закрыл соединение, истёк таймаут, сервис останавливается. Для этого есть AbortSignal:
const signal = AbortSignal.timeout(5_000);
await pipeline(source, destination, { signal });
addAbortSignal(signal, stream) делает то же для отдельного потока: при отмене разрушает его с ошибкой отмены. Для HTTP-ответа удобно связать сигнал с закрытием соединения:
const ac = new AbortController();
res.on('close', () => ac.abort());
await pipeline(createReadStream(file), res, { signal: ac.signal });
Если заголовки уже отправлены, код состояния изменить нельзя: остаётся res.destroy(err), чтобы оборвать соединение, а не пытаться вернуть JSON с ошибкой.
Потоковая обработка больших файлов
Правило одно: не собирайте данные в память, если их можно обработать по пути. Всё остальное — детали конкретного формата.
CSV. Парсер — это Transform, поэтому он встаёт в цепочку между файлом и приёмником:
import { createReadStream, createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import { parse } from 'csv-parse';
await pipeline(
createReadStream('orders.csv'),
parse({ columns: true, bom: true }),
async function* (rows) {
for await (const row of rows) {
if (row.status === 'paid') yield `${row.id}\n`;
}
},
createWriteStream('paid-ids.txt'),
);
Асинхронный генератор здесь — обычная стадия pipeline: он получает предыдущий поток и выдаёт новый, сохраняя backpressure.
Архивы. zlib.createGzip() сжимает поток на лету, tar-stream и archiver читают и собирают архивы по записям. Распаковка «в память» через readFile на архиве в несколько гигабайт сводит всю экономию на нет.
Отдача файла клиенту. Размер известен — ставят Content-Length; неизвестен — работает chunked transfer encoding. pipeline сам вызывает end() у ответа:
import { createServer } from 'node:http';
import { createReadStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
createServer(async (req, res) => {
const ac = new AbortController();
res.on('close', () => ac.abort());
try {
res.writeHead(200, { 'Content-Type': 'application/octet-stream' });
await pipeline(createReadStream('big.bin'), res, { signal: ac.signal });
} catch (err) {
if (err.name !== 'AbortError') res.destroy(err);
}
}).listen(3000);
Чего здесь нет: проверки пути (пользовательский ввод нельзя бездумно подставлять в createReadStream — см. path traversal в статье «Встроенные модули Node.js»), поддержки Range и проверки прав. Статику обычно отдают через reverse proxy или библиотеку, а не самописным обработчиком.
Загрузка файла. Тело запроса — тоже Readable, поэтому его пишут на диск потоком:
await pipeline(req, createWriteStream(target));
Стрим не ограничивает размер тела: лимит ставят на прокси или проверяют Content-Length до чтения. Обрыв соединения посреди загрузки оставит неполный файл — его удаляют или проверяют размер и хеш после записи.
Свои Transform и object mode
Transform — это Duplex, у которого вход и выход связаны: каждый чанк проходит через _transform, результат уходит в push(). Когда вход закончился, вызывается _flush — место для хвоста, который накопился в буфере.
import { Transform } from 'node:stream';
import { StringDecoder } from 'node:string_decoder';
class JsonLinesParser extends Transform {
#buffer = '';
#decoder = new StringDecoder('utf8');
constructor() {
super({ readableObjectMode: true });
}
_transform(chunk, _encoding, callback) {
this.#buffer += this.#decoder.write(chunk);
const lines = this.#buffer.split('\n');
this.#buffer = lines.pop() ?? '';
for (const line of lines) {
if (!line.trim()) continue;
try {
this.push(JSON.parse(line));
} catch (err) {
return callback(err);
}
}
callback();
}
_flush(callback) {
this.#buffer += this.#decoder.end();
if (!this.#buffer.trim()) return callback();
try {
this.push(JSON.parse(this.#buffer));
callback();
} catch (err) {
callback(err);
}
}
}
StringDecoder нужен, потому что чанк — это произвольный кусок байтов, и разрезанный посередине UTF-8 символ нельзя декодировать по отдельности. readableObjectMode: true позволяет выдавать объекты, хотя на вход приходят буферы.
Object mode переключает поток с байтов на произвольные JavaScript-значения. В нём highWaterMark считается в объектах (по умолчанию 16), потому что размер объекта заранее неизвестен. readableObjectMode и writableObjectMode включаются независимо; null в object mode — не данные, а сигнал конца потока, поэтому записать его нельзя.
import { Readable } from 'node:stream';
const rows = Readable.from([{ id: 1 }, { id: 2 }]); // objectMode включён
Object mode удобен для строк БД, результатов парсинга и сообщений очереди. Но помните: поток объектов не уменьшает память сам по себе — если каждый объект большой, буфер из 16 таких объектов может весить больше, чем килобайтное окно байтового потока.
И ещё: _transform выполняется в главном потоке. Синхронный парсинг большого JSON или сжатие внутри колбэка блокируют event loop так же, как любой другой синхронный код; для CPU-bound работы нужно выносить её в worker, а не надеяться, что «это же стрим».
Web Streams и совместимость
В Node есть два семейства потоков. Кроме классических node:stream, поддерживаются Web Streams — стандарт WHATWG с ReadableStream, WritableStream и TransformStream. Они глобальны с Node 18, доступны и из node:stream/web.
Различия принципиальные:
| Аспект | Стримы Node | Web Streams |
|---|---|---|
| Чтение | события, read(), async iterator | getReader(), read() с промисом |
| Соединение | pipe() | pipeThrough(), pipeTo() |
| Ошибки | событие error | отклонение промиса |
| Backpressure | write() === false, drain | desiredSize и controller |
| Источник | fs, http, zlib | fetch, браузерные API |
Web Streams — это то, что возвращает fetch: response.body — ReadableStream, а request.body при отправке — поток для загрузки. Обращаться с ним как с Node-стримом нельзя, но мост существует:
import { Readable } from 'node:stream';
import { createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
const upstream = await fetch(url);
await pipeline(
Readable.fromWeb(upstream.body),
createWriteStream('copy.bin'),
);
Readable.fromWeb() сохраняет backpressure: медленная запись притормозит чтение из сети. Обратное направление — Readable.toWeb(createReadStream(file)), например чтобы вернуть файл из обработчика, который умеет только Response. Аналогичные пары есть для Writable и Duplex.
С Node 18.16 pipeline принимает Web Streams напрямую, но при смешивании с Node-трансформами (zlib, crypto) проще привести поток к одному семейству. for await по ReadableStream тоже работает и при break отменяет поток.
Частые ошибки
readFile+res.end. Файл целиком в памяти на каждый запрос; под нагрузкой это OOM. Для отдачи —createReadStreamиpipeline.- Игнорирование
write() === false. Буфер растёт без сигнала ошибки; спасает только лимит памяти процесса. pipeбез обработки ошибок. Ошибка одной стадии не закрывает остальные, а необработанноеerrorроняет процесс.- Смешивание
dataиfor await. Два потребителя конкурируют за чанки; поведение зависит от порядка подписок. - Огромный
highWaterMark«для скорости». Порог — не пропускная способность: память на каждое соединение растёт, а выигрыш часто в другом. - Забытый
end(). Приёмник не эмититfinish,pipelineне завершается, соединение висит. - Отсутствие
_flush. Последняя строка без перевода строки или хвост архива теряются. - Сборка всего результата через
Buffer.concat. Данные уже были потоком, но снова сложены в память. - Синхронная CPU-работа в
_transform. Поток не спасает event loop от блокировки. - Нет реакции на обрыв клиента. Чтение файла продолжается в пустоту, дескриптор занят до конца передачи.
Эксперименты
Три запуска, которые показывают поведение, плохо заметное в документации.
1. write() возвращает false и drain
import { Writable } from 'node:stream';
const slow = new Writable({
highWaterMark: 16,
write(chunk, _encoding, callback) {
setTimeout(callback, 50);
},
});
for (let i = 1; i <= 5; i++) {
console.log(`write ${i}:`, slow.write(Buffer.alloc(8)));
}
slow.on('drain', () => console.log('drain'));
slow.end();
Первые записи вернут true, затем false: буфер заполнился, и продолжать можно только после drain. Данные при этом не теряются — они ждут во внутренней очереди.
2. Ошибка в середине цепочки
import { Readable, Writable } from 'node:stream';
import { pipeline } from 'node:stream/promises';
const source = Readable.from(async function* () {
yield 'a';
throw new Error('boom');
}());
const dest = new Writable({
write(_chunk, _encoding, callback) {
callback();
},
});
try {
await pipeline(source, dest);
} catch (err) {
console.log('pipeline упал:', err.message); // boom
}
pipeline отклоняет промис и разрушает обе стадии. С pipe та же ошибка осталась бы необработанным событием error.
3. break разрушает поток
import { Readable } from 'node:stream';
const numbers = Readable.from([1, 2, 3, 4]);
for await (const n of numbers) {
console.log(n);
if (n === 2) break;
}
console.log('destroyed:', numbers.destroyed); // true
Выход из цикла — это не «пауза», а закрытие потока. Если данные ещё нужны, поток нельзя покидать через break.
Ключевые тезисы для интервью
- Стрим ограничивает память окном
highWaterMark, а не размером данных: медленный потребитель притормаживает источник через backpressure, вместо того чтобы копить всё в буфере. write()возвращаетfalseпри заполнении буфера, и продолжать можно только послеdrain; игнорирование сигнала не даёт ошибки, но превращает буфер в неограниченную память.pipeсоединяет потоки и управляет скоростью, но не пробрасывает ошибки и не закрывает цепочку;pipelineразрушает все стадии при сбое, поддерживает промисы,AbortSignal, генераторы и Web Streams.finishedтолько ждёт завершения конкретного потока, аend,finishиcloseозначают разное: конец данных, сброс записи и закрытие ресурса.- Flowing mode (
data) не даёт backpressure, async iteration забирает чанки по одному и даёт;breakв цикле разрушает поток. Transform— этоDuplexс_transformи_flush; в object modehighWaterMarkсчитается в объектах (16 по умолчанию), аnullозначает конец потока.- Web Streams — стандарт
fetchс промисами иgetReader(); мост к Node —Readable.fromWeb()иReadable.toWeb(), при этом backpressure сохраняется.
Заключение
Стримы нужны там, где размер данных превышает разумный буфер: файлы, ответы API, архивы, загрузки, логи. Их главная идея — не «читать по кусочкам», а ограничить окно и передать управление скоростью потребителю. Отсюда три практических правила: уважайте false и drain, собирайте цепочки через pipeline, а не pipe, и всегда закрывайте ресурсы при ошибке или отмене. Если эти правила соблюдены, память сервиса перестаёт зависеть от размера файла, а поведение под нагрузкой становится предсказуемым. Дальше эти же потоковые принципы встречаются в HTTP-сервере, проксировании и фоновых задачах.
Полезные ссылки
- Stream — полный API классических потоков
- Backpressuring in Streams — официальное объяснение backpressure
- stream/promises —
pipelineиfinishedв промис-варианте - Web Streams —
ReadableStream,WritableStream,TransformStream - Streams Standard — спецификация Web Streams