Native Addons: C++ расширения

Когда Slack переписал критичный участок кода с JavaScript на C++, latency обработки сообщений упала с 300ms до 50ms. Когда Discord интегрировал Rust-библиотеку через native addon, пропускная способность voice кодирования выросла в 10 раз. Native addons - это выход за пределы возможностей чистого JavaScript, прямой доступ к железу, существующим C/C++ библиотекам и системным API. Это last resort для критичных по производительности задач, но когда он нужен - разница в скорости измеряется порядками величины.

• **bcrypt** - каждый проект с аутентификацией использует native addon для хеширования паролей. Pure-JS реализация была бы в 100 раз медленнее, делая bcrypt бесполезным для защиты от brute-force атак.
• **sharp** - обработка изображений на серверах (resize, crop, optimize). Используется в Medium, Unsplash, 500px для генерации thumbnails. Обрабатывает 1000 изображений/сек благодаря libvips (C++ библиотека с SIMD оптимизациями).
• **sqlite3** - встраиваемая БД для локальных данных, логов, кеша. Используется в Electron приложениях (VS Code, Slack, Discord) для хранения настроек и истории. Native биндинги позволяют использовать production-grade SQLite прямо в Node.js.
• **serialport** - управление Arduino, Raspberry Pi, USB-устройствами из Node.js. Используется в IoT проектах, домашней автоматизации, робототехнике. Без native addon доступ к serial ports невозможен из JavaScript.

Intro

Аналогия - гоночный автомобиль. JavaScript - это комфортный салон с автопилотом (garbage collection, event loop, высокоуровневые API). Но иногда нужно открыть капот и настроить двигатель вручную - получить прямой доступ к железу, системным библиотекам или существующему C/C++ коду. **Native Addons** - это мост между миром JavaScript и миром нативного кода.

**Native Addon** - это динамическая библиотека (`.node` файл, на самом деле `.so`/`.dylib`/`.dll`), написанная на C/C++, которую можно подключить в Node.js через `require()` как обычный модуль. Внутри аддон имеет прямой доступ к V8 API, libuv, OpenSSL и всему, что доступно C++ программе. Это позволяет использовать существующие C/C++ библиотеки (image processing, cryptography, machine learning), писать критичные по производительности участки кода или интегрироваться с системными API.

**Реальные примеры native addons в production:** `bcrypt` (хеширование паролей), `node-sass` (компиляция SASS через libsass), `sharp` (image processing через libvips), `sqlite3` (биндинги к SQLite), `robotjs` (управление мышью/клавиатурой), `canvas` (рендеринг графики через Cairo). Без native addons эти библиотеки были бы в десятки раз медленнее или вообще невозможны в Node.js.

**Опасности native addons:** 1. **Segmentation fault = крэш всего процесса Node.js**. В JavaScript ошибка в коде = exception. В C++ ошибка = undefined behavior, который может убить сервер. 2. **Memory leaks не детектируются V8 GC**. Если разработчик выделил память через `malloc()` и не освободил - утечка навсегда. 3. **Блокировка Event Loop**. Если C++ функция работает 1 секунду синхронно - Event Loop заблокирован. Нужны async workers. 4. **ABI compatibility**. Compiled аддон привязан к версии Node.js/V8. Обновление Node.js = пересборка всех аддонов. 5. **Сложность разработки**. C++ требует понимания указателей, управления памятью, многопоточности. Одна ошибка = production outage.

N-API

**N-API (Node-API)** - это стабильный C API для создания native addons, гарантирующий ABI (Application Binary Interface) совместимость между версиями Node.js. Это решение главной проблемы старых аддонов: раньше при обновлении Node.js/V8 нужно было пересобирать все аддоны, потому что внутренний API V8 постоянно менялся. N-API - это прослойка, которая изолирует аддон от изменений V8.

Аналогия - USB-разъём. До N-API каждая версия Node.js имела свой уникальный разъём (V8 API). После обновления Node.js все устройства (аддоны) переставали работать, требовалась пересборка. N-API - это стандартизированный USB-C: один раз скомпилированный аддон работает на Node.js 10, 12, 14, 16, 18, 20... без пересборки. Это **революция** для экосистемы native addons.

**N-API стал стандартом:** С Node.js 10 N-API стабилен и рекомендован для всех новых аддонов. Популярные библиотеки мигрировали: `bcrypt`, `sqlite3`, `sharp`. Преимущества: ABI stability, forward compatibility, проще поддержка (не нужно следить за изменениями V8), меньше зависимостей в CI/CD.

**N-API vs старый V8 API:** **N-API (рекомендуется):** - ✅ ABI stable - работает на разных версиях Node.js - ✅ Forward compatible - аддон для Node.js 12 работает на 18 - ✅ Проще поддержка - не нужно следить за изменениями V8 - ❌ Чуть больше boilerplate кода - ❌ Нет доступа к низкоуровневым V8 API (isolate, context) **V8 API (legacy):** - ✅ Прямой доступ ко всем возможностям V8 - ✅ Чуть меньше overhead (но разница незначительна) - ❌ Ломается при обновлении Node.js/V8 - ❌ Нужно пересобирать под каждую версию Node.js - ❌ Deprecated для новых проектов **Вердикт:** Для новых проектов ВСЕГДА используйте N-API. Для legacy проектов - миграция на N-API окупится через полгода.

NAN (Native Abstractions for Node.js)

**NAN (Native Abstractions for Node.js)** - это C++ библиотека-прослойка, которая была создана ДО появления N-API для решения той же проблемы: изоляции аддонов от изменений V8 API. NAN предоставляет макросы и хелперы, которые компилируются в разный код в зависимости от версии Node.js. Это позволяло писать аддон один раз, но пересобирать его под каждую версию Node.js.

Аналогия - переходник для розеток. В разных странах (версиях Node.js) разные розетки (V8 API), но универсальный переходник (NAN) подходит ко всем. Он не решает проблему пересборки, но хотя бы убирает необходимость переписывать весь код под каждую версию. NAN был стандартом в 2014-2018, но с появлением N-API (2018+) стал **legacy технологией**.

**Почему NAN всё ещё встречается:** Многие старые популярные библиотеки написаны на NAN: `node-sass` (deprecated, заменён на `sass`), `canvas`, `serialport`, `node-hid`. Причины: 1. **Legacy code** - библиотека работает, нет ресурсов на миграцию 2. **V8-specific features** - NAN даёт доступ к низкоуровневым V8 API, которых нет в N-API 3. **Инерция** - старые туториалы и примеры используют NAN Но для **новых проектов** NAN использовать НЕ рекомендуется - используйте N-API (напрямую или через `node-addon-api` C++ обёртку).

**NAN deprecated для новых проектов:** - ❌ Не используйте NAN для новых аддонов - ❌ Не используйте туториалы, упоминающие NAN (устаревшие) - ✅ Используйте N-API напрямую или через `node-addon-api` (C++ обёртка) - ✅ Мигрируйте существующие NAN аддоны на N-API **Исключения:** Если нужны V8-specific features (HandleScope, Isolate, EmbedderData), которых нет в N-API - применяется прямой V8 API, но это означает готовность к breaking changes.

node-gyp: Сборка аддонов

**node-gyp** - это инструмент для компиляции native addons из C++ исходников в `.node` файл (динамическую библиотеку). Он обёртка над **GYP (Generate Your Projects)** - система сборки, разработанная Google для Chromium. node-gyp читает файл `binding.gyp` (конфигурация проекта), генерирует Makefile (Linux/macOS) или Visual Studio project (Windows), и запускает компиляцию.

Аналогия - стройка дома. C++ код - это чертежи. node-gyp - это прораб, который: 1. Читает чертежи (`binding.gyp`) 2. Находит нужные инструменты (C++ компилятор, Python, Node.js headers) 3. Организует строительство (компиляция) 4. Собирает готовый дом (`.node` файл) node-gyp - это **низкоуровневый** инструмент. Обычный разработчик не вызывает его напрямую: `npm install` автоматически запускает node-gyp для native зависимостей.

**Что происходит при `npm install` native addon:** 1. npm скачивает пакет из registry 2. Проверяет, есть ли prebuilt binary (через `node-pre-gyp` или `prebuildify`) 3. Если binary найден - распаковывает и готово 4. Если нет - запускает `node-gyp rebuild`: - Скачивает Node.js headers (нужны для компиляции) - Читает `binding.gyp` - Запускает компилятор (g++, clang, MSVC) - Линкует с Node.js/V8 библиотеками - Сохраняет результат в `build/Release/addon.node` 5. При `require('addon')` Node.js загружает скомпилированный `.node` файл Это объясняет, почему установка `bcrypt` занимает 30 секунд, а `lodash` - мгновенно.

**Почему node-gyp - это боль экосистемы:** 1. **Требует toolchain:** Python, C++ компилятор, make/MSBuild. На чистой Windows/macOS часто отсутствует. 2. **Долгая сборка:** Компиляция C++ может занимать минуты. Умножьте на количество native зависимостей. 3. **Fails без понятных сообщений:** `gyp ERR! stack Error` - что конкретно сломалось? 4. **Проблемы на CI/CD:** Docker образы часто не содержат build-tools. Alpine Linux особенно проблематичен (musl libc vs glibc). 5. **Сложность отладки:** Если сборка падает с C++ ошибкой, нужно знание C++ для фикса. **Решения:** - **Prebuilt binaries** - публикуйте скомпилированные версии для популярных платформ - **N-API** - уменьшает частоту пересборок - **WASM** - альтернатива native addons для некоторых сценариев (например, image processing через wasm-imagemagick) - **Pure JS alternatives** - если производительность приемлема, избегайте native dependencies

Memory Safety: Управление памятью

В JavaScript управление памятью автоматическое: после создания объекта V8 GC сам почистит его, когда он больше не нужен. В C++ мире native addons режим **ручной**: выделил память через `malloc()`/`new` - обязан освободить через `free()`/`delete`. Забыл освободить - memory leak. Освободил дважды - segfault и крэш процесса.

Более того, есть **две памяти**: JavaScript heap (управляется V8 GC) и native heap (управляется вручную в C++). N-API предоставляет механизмы для их синхронизации: когда JS объект удаляется GC, нужно освободить и связанный C++ ресурс. Это критично для работы с файлами, сокетами, GPU памятью - если не освободить, утечка будет расти до OOM.

**Почему memory safety критична в production:** JavaScript сервер с memory leak'ом в чистом JS: GC рано или поздно словит объекты (если нет циклических ссылок). Worst case - restart раз в неделю. Native addon с memory leak'ом: утечка в native heap, GC её не видит, растёт до OOM. Сервер падает через несколько часов. В production это означает: - Ночные alerts - Потерянные транзакции - Недовольные пользователи - Сложная отладка (где именно течёт?) Одна ошибка в C++ коде может убить стабильность всего сервиса.

**Инструменты для поиска memory leaks в native addons:** 1. **Valgrind (Linux):** ```bash valgrind --leak-check=full --show-leak-kinds=all node app.js ``` Показывает все утечки памяти с stack trace. 2. **AddressSanitizer (ASAN):** ```bash export ASAN_OPTIONS=detect_leaks=1 node --expose-gc app.js ``` Более быстрый и точный, чем Valgrind. 3. **Chrome DevTools Memory Profiler:** Видит только JS heap, не видит native memory. Нужен в комбинации с process.memoryUsage().external. 4. **process.memoryUsage() мониторинг:** ```javascript setInterval(() => { const mem = process.memoryUsage(); console.log({ rss: (mem.rss / 1024 / 1024).toFixe 2. + ' MB', // Total heapUsed: (mem.heapUsed / 1024 / 1024).toFixe (2), // JS heap external: (mem.external / 1024 / 1024).toFixe 2. // Native memory }); }, 5000); ``` Если `external` растёт - утечка в native addon. 5. **Linux /proc/PID/smaps:** Детальная информация о памяти процесса по регионам.

Async Workers и Best Practices

Главное правило native addons: **НЕ блокируй Event Loop**. Если C++ функция делает что-то дольше нескольких миллисекунд (image processing, криптография, парсинг больших файлов) - она ОБЯЗАТЕЛЬНО должна быть асинхронной. N-API предоставляет **AsyncWorker** паттерн для выполнения C++ кода в background thread'е, не блокируя JavaScript.

Аналогия - ресторан. Официант (Event Loop) не должен уходить на кухню и готовить блюдо сам - он заблокирует обслуживание других столов. Вместо этого он передаёт заказ повару (AsyncWorker), продолжает обслуживать клиентов, а когда блюдо готово, повар звонит в колокольчик (callback), и официант приносит блюдо. Так работают async native addons.

**node-addon-api vs чистый N-API:** **node-addon-api** - это C++ обёртка над N-API, предоставляющая: - ✅ RAII (автоматическое управление ресурсами) - ✅ Исключения C++ вместо napi_status кодов - ✅ Удобные классы (AsyncWorker, ObjectWrap, Promise) - ✅ Меньше boilerplate кода **Чистый N-API** - C API: - ✅ Работает с C проектами (не только C++) - ✅ Чуть меньше overhead (но разница незначительна) - ❌ Больше кода (ручная проверка napi_status) - ❌ Нет автоматического управления ресурсами **Рекомендация:** Для C++ проектов используйте **node-addon-api** - код чище и безопаснее. Для C проектов - чистый N-API.

**Когда НЕ нужен native addon:** ❌ **Простые вычисления** - Worker Threads достаточно: ```javascript const { Worker } = require('worker_threads'); const worker = new Worker('./heavy-calc.js'); // Проще, чем писать C++ ``` ❌ **I/O операции** - async Node.js API уже оптимальны: ```javascript fs.readFile('file.txt', callback); // Использует libuv, не блокирует ``` ❌ **Парсинг JSON** - V8 оптимизирован для этого: ```javascript JSON.parse(data); // Нативная реализация в V8 ``` ✅ **Когда НУЖЕН:** - Интеграция с существующими C/C++ библиотеками (OpenCV, TensorFlow) - CPU-intensive задачи, где нужна максимальная производительность (криптография, image processing) - Доступ к системным API, недоступным из JS (USB, Bluetooth, low-level network) - Работа с GPU через CUDA/OpenCL **Правило:** Сначала профилирование, затем проверка реальности узкого места, затем Worker Threads, и только потом - native addon.

Ключевые идеи

• **N-API (Node-API) - современный стандарт:** ABI stable между версиями Node.js, один раз скомпилированный addon работает на Node.js 10-20+ без пересборки. NAN - legacy технология, не используйте для новых проектов.
• **node-gyp - боль экосистемы:** требует Python, C++ компилятор, долгая сборка. Решение - prebuilt binaries для популярных платформ (node-pre-gyp, prebuildify) и миграция на N-API для совместимости.
• **Memory safety критична:** C++ ошибка = segfault = крэш процесса. Используйте RAII (smart pointers), finalizers для C++ ресурсов (napi_wrap), Valgrind/ASAN для поиска утечек. process.memoryUsage().external для мониторинга native памяти.
• **AsyncWorker для долгих операций:** НЕ блокируйте Event Loop. Любая операция >10ms должна выполняться в AsyncWorker (отдельный поток). Execute() - C++ вычисления, OnOK() - возврат результата в JS. Увеличивайте UV_THREADPOOL_SIZE для высокой нагрузки.
• **Native addon - last resort:** Сначала профилирование, затем Worker Threads, и только для реальных CPU-bound узких мест - C++. Для I/O и бизнес-логики JavaScript эффективнее.

Связанные темы

Native Addons - это выход за пределы JavaScript runtime. Для полного понимания изучите связанные концепции:

• Worker Threads — Альтернатива native addons для CPU-intensive задач. Проще разработка (на JS), но медленнее (нет доступа к C++ библиотекам и SIMD). Worker Threads - первый выбор перед native addon.
• libuv и Event Loop — AsyncWorker использует libuv thread pool для выполнения C++ кода. Понимание Event Loop критично для правильного использования async addons.
• V8 Engine и Memory Management — Native addons работают на границе V8 (JavaScript heap) и native heap (C++ память). Понимание V8 GC объясняет, почему нужны finalizers и как работает napi_wrap.
• WebAssembly (WASM) — Современная альтернатива native addons для портирования C/C++ кода. Проще развёртывание (нет node-gyp), кроссплатформенность, но медленнее native addons (нет прямого доступа к Node.js API).

Вопросы для размышления

• API-сервер обрабатывает 10000 req/sec. Добавлен native addon для валидации JWT токенов (C++ библиотека). Latency вырос на 20%. В чём может быть проблема и как диагностировать?
• Миграция legacy C++ проекта в Node.js через native addon. Код использует глобальные переменные и static state. Какие проблемы возникнут в многопоточной среде Node.js (Worker Threads, Cluster)?
• В каких сценариях WebAssembly (WASM) предпочтительнее native addon, несмотря на меньшую производительность? Рассмотрите deployment, security, кроссплатформенность.

Связанные уроки

• arch-08-memory-hierarchy