FFI: вызов готовой разделяемой библиотеки из JS через koffi — и кто владеет памятью

Что такое FFI — и чем он отличается от нативного аддона

За десять минут ты поймёшь, почему SIGSEGV из хука случился именно там, как FFI работает на уровне ABI, и три правила владения памятью, отделяющие безопасную интеграцию от бомбы замедленного действия.

Прошлые уроки строили нативный аддон: ты пишешь C/C++-обвязку под Node-API, компилируешь её в .node-бинарь и делаешь require. FFI (Foreign Function Interface, интерфейс вызова внешних функций) обходится без обвязки вовсе. Ты берёшь уже скомпилированную разделяемую библиотеку — libfoo.so на Linux, .dylib на macOS, .dll на Windows, — объявляешь прототип нужной функции на JavaScript, и библиотека маршалит вызов в рантайме. Ни своего C-кода, ни компилятора на установке, ни .node для сборки: просто открой библиотеку и опиши сигнатуру.

import koffi from 'koffi';

const libm = koffi.load('libm.so.6');             // dlopen разделяемой библиотеки
const pow  = libm.func('double pow(double, double)'); // объявляем C-прототип

pow(2, 10); // 1024 — libffi пакует double'ы по ABI, вызывает, читает результат

Та строка libm.func('double pow(double, double)') — и есть вся идея: строка, которая и есть C-сигнатура. Нет компилятора, сверяющего её с настоящим pow из libm. Объявление — контракт, который обеспечиваешь только ты, и это центральный размен против нативного аддона, где C-компилятор типизирует твою обвязку. FFI покупает тебе «никакого тулчейна, обернуть существующую библиотеку за минуты» ценой «ошибёшься в одном типе — и сказать об этом будет некому».

libffi: построение кадра вызова в рантайме

Под каждым FFI-биндингом сидит libffi (библиотека, динамически строящая кадры вызовов по соглашениям платформенного ABI). У обычного скомпилированного вызова раскладка аргументов вшита на этапе компиляции — компилятор знает положить первое целое в rdi, первый float в xmm0 и так далее по соглашению о вызовах платформы (System V AMD64 на Linux/macOS, Microsoft x64 ABI на Windows). У FFI такой роскоши нет: он узнаёт сигнатуру лишь в рантайме, из твоего объявления. Поэтому libffi строит кадр вызова динамически — читает объявленные типы, кладёт каждый аргумент в нужный регистр или слот стека под ABI, прыгает через трамплин в функцию библиотеки и читает возвращаемое значение из регистра возврата.

Цена — этот динамический шаг. Каждый FFI-вызов платит трамплин плюс помаршаливание каждого аргумента — порядка десятков наносекунд поверх собственной работы C-функции. Для горстки крупных вызовов на запрос это незаметно. Для горячего цикла с миллионами мелких вызовов это доминирует, и скомпилированный Node-API-аддон — чьи вызовы прямые, без построения кадра в рантайме — выигрывает решительно. Ниша FFI — крупнозернистые вызовы в существующую библиотеку, а не болтливый внутренний цикл.

koffi против ffi-napi: бери поддерживаемый

В Node две линии FFI, и выбор в 2025-м неравный.

Классический стек — ffi-napi + ref-napi — потомки node-ffi. Его фатальное свойство — то самое из хука: он сам нативный аддон. Установка компилирует C, так что ты наследуешь всю матрицу node-gyp/prebuild/ABI из прошлого урока — ровно ту боль сборки, которую FFI должен был устранить, — плюс поломки на каждом сдвиге ABI в мажоре Node. Сейчас он практически не поддерживается. Не начинай на нём новую работу.

koffi — современный ответ. Он поставляет prebuilt-бинари под распространённые платформы (никакого node-gyp на установке), активно поддерживается, работает заметно быстрее и имеет первоклассную поддержку структур, указателей, выходных параметров, колбэков и disposable-типов. Для новой FFI-работы koffi — senior-дефолт; относись к ffi-napi как к легаси, с которого мигрируют.

Владение памятью: граница, которую GC не пересекает

Здесь FFI кусается, и это стоит сформулировать жёстким правилом: сборщик мусора JavaScript не видит нативную память, а C не видит JS-кучу. Это два отдельных мира без общего учёта. Три следствия, которыми управляешь руками:

• C-аллокации освобождаешь ты. Если функция возвращает malloc-нутый указатель (char*-строку, структуру), GC никогда его не вернёт — нужно самому вызвать парную функцию освобождения библиотеки. Забудешь — получишь классическую утечку C-памяти, в Node-процессе, которую не объяснит ни один heap snapshot, потому что она вне кучи.
• Буферы, что ты передаёшь, должны пережить вызов. Когда ты отдаёшь C указатель в JS Buffer или типизированный массив, эта память безопасна лишь пока JS-объект жив и не сдвинут. Если C хранит указатель и использует его после возврата (async-колбэк, удержанный хэндл), нужно держать живую JS-ссылку, чтобы GC не собрал и не переместил буфер — иначе C разыменует освобождённую память.
• Выходным параметрам нужна явная аллокация. Многие C-функции заполняют переданный вызывающим буфер (int read(fd, void* buf, size_t n)). Ты аллоцируешь его (koffi.alloc), передаёшь указатель, затем декодируешь, что C записал.

// C: char* make_greeting(const char* name);  // возвращает malloc-нутую строку
//    void  free_greeting(char* p);            // вызывающий обязан освободить
const make = lib.func('char* make_greeting(const char*)');
const free = lib.func('void free_greeting(char*)');

const ptr = make('Ada');                 // C это malloc-нул — GC не в курсе
const text = koffi.decode(ptr, 'char*'); // копируем байты в JS-строку
free(ptr);                               // освобождаешь ТЫ, иначе течёт вечно

Структуры, колбэки и цена неверного типа

Ещё три места, где контракт обязан быть точным:

Структуры. Ты объявляешь раскладку (koffi.struct({ x: 'int', y: 'double' })), и порядок полей, типы и выравнивание/паддинг должны совпадать с C-определением байт в байт. Ошибёшься в паддинге — и каждое поле после него читается с неверного смещения: мусор, не крах, что отлаживать хуже.

Колбэки. Чтобы дать C вызвать обратно в JS (компаратор, обработчик события), ты регистрируешь JS-функцию как C-указатель на функцию. Две опасности: JS-функция должна оставаться живой, пока C держит указатель (потеряешь ссылку — GC соберёт её под ногами у C), и если библиотека вызывает твой колбэк на не-JS-потоке, заход в V8 оттуда роняет процесс — нужна async/registered-обработка колбэков koffi, а не сырой синхронный.

Неверные скалярные типы. Баг из хука обобщается: объявишь 'int' там, где C возвращает 64-битный size_t, long или указатель, — значение обрезается; объявишь знаковый тип для беззнакового — большие значения переворачиваются в отрицательные. Ничего из этого не проверяется. Объявление — единственный источник истины, и его правильность на тебе.