HQQ: Изоляция C Libraries от Go через Cache-Line Shared Memory

gosuda.org/hqq — это среда выполнения межпроцессного взаимодействия без использования cgo и инструментальная цепочка генерации кода для Go и C11. Она изолирует нативные библиотеки C в отдельных рабочих процессах операционной системы и подключает их к вызывающим компонентам на Go через кольцевые буферы разделяемой памяти, отображаемые на память и выровненные по границам строк кэша. Проект объединяет два транспортных уровня (StandardLink для выделенных сеансов с одним производителем и одним потребителем и Advanced для многопоточной диспетчеризации MPMC), компилятор IDL hqq-bindgen и супервизор процессов с верификацией целостности (secureexec и launch).

1go get gosuda.org/hqq

Цена разделения адресного пространства с C

Каждый системный инженер, работающий с Go, рано или поздно сталкивается с одной и той же развилкой. Вы создаете службу на Go, которая компилируется за секунды с параметром CGO_ENABLED=0, поставляется в виде единого статического бинарного файла, кросс-компилируется с ноутбука под целевые платформы Linux или Windows без использования системного корневого каталога (sysroot) и работает внутри безопасной для памяти кучи с автоматическим управлением сборкой мусора. Затем вам требуется зрелая библиотека C: SQLite для встроенного реляционного хранения, Zstandard (libzstd) для компрессии словарей или библиотека работы с мультимедиа или криптографией с аппаратным ускорением.

Включение cgo для компоновки этой библиотеки C в процесс Go решает непосредственную проблему связи, порождая при этом три структурных обязательства:

Связывание инструментальной цепочки и кросс-компиляции: CGO_ENABLED=1 требует наличия компилятора C, целевых заголовочных файлов libc и компоновщика платформы для каждой целевой операционной системы и архитектуры. Сборка артефактов linux/arm64 или windows/arm64 с рабочей станции darwin/arm64 превращает единственную команду go build в матрицу кросс-компиляторов и системных корневых каталогов.
Накладные расходы планирования выполнения: Каждый вызов cgo пересекает границу среды выполнения Go, переключается из стека горутины с возможностью роста в системный стек и закрепляет поток ОС (M). Для мелкозернистых вызовов издержки перехода (~50–150 нс на вызов) и состязание за планировщик быстро накапливаются.
Крах домена сбоев: Код на C выполняется в том же виртуальном адресном пространстве, что и среда выполнения Go. Единая запись за пределами выделенного буфера, использование памяти после ее освобождения, переполнение стека или вызов abort() внутри функции C повреждают метаданные кучи Go или немедленно завершают весь процесс сервера, обходя механизм recover() и уничтожая каждый обрабатываемый в данный момент HTTP- или RPC-запрос.

Когда команды пытаются избежать использования cgo, распространенные альтернативные решения вынуждают идти на другой компромисс. Механические переводы кодовых баз C на чистый Go сохраняют значение CGO_ENABLED=0, однако часто отстают от актуальных версий вышестоящих репозиториев C, несут в себе эмулируемый уровень виртуальной памяти и активно выделяют память под нагрузкой. Перемещение библиотеки C в вспомогательный процесс по протоколу loopback TCP или доменным сокетам Unix восстанавливает изоляцию сбоев, но каждый вызов оплачивает два переключения контекста ядра, копирования буферов сокетов и сериализацию данных.

Мы создали HQQ, задав прямой вопрос: что, если библиотека C будет размещаться в отдельном процессе операционной системы с собственным виртуальным адресным пространством, в то время как Go и C обмениваются фреймами напрямую через разделяемые строки кэша процессора без входа в ядро на быстром пути?

Модель интеграции	`CGO_ENABLED=0`	Изоляция сбоев	Системные вызовы на быстром пути	Выделения памяти в куче на вызов	Точность исходного кода C11
Внутрипроцессная компоновка `cgo`	Нет	Отсутствует (общая куча)	0	от 0 до 1+	Точный исходный C
RPC через сокеты / каналы подпроцесса	Да	Граница процессов	от 2 до 4	Несколько (фреймирование + ввод-вывод)	Точный исходный C
Механический перевод C в Go	Да	Внутрипроцессный Go	0	Высокие на сложных вызовах	Эмулируемая среда выполнения C
IPC через разделяемую память HQQ	Да	Граница процессов	0 (адаптивное ожидание)	0 (`StandardLink`)	Точный исходный C

Архитектурный обзор: четыре слоя через границы процессов

HQQ разделяет изоляцию процессов на четыре компонуемых слоя, благодаря чему механика кольцевых буферов разделяемой памяти, типизированная генерация RPC-кода, проверка целостности двоичного файла и надзор за дочерними процессами остаются независимыми.

 1+-------------------------------------------------------------------+
 2| Go Application Process (CGO_ENABLED=0)                            |
 3|                                                                   |
 4|  +-----------------------+     +-------------------------------+  |
 5|  | Generated Go Client   |     | Process Supervisor            |  |
 6|  | (gosuda.org/hqq/      |     | (gosuda.org/hqq/launch +      |  |
 7|  |  bindgen/rt)          |     |  gosuda.org/hqq/secureexec)   |  |
 8|  +-----------+-----------+     +---------------+---------------+  |
 9|              |                                 |                  |
10|  +-----------v-----------+                     | Anonymous Pipe   |
11|  | Transport Tier        |                     | Lifeline         |
12|  | (StandardLink /       |                     | (--parent-stdin) |
13|  |  Advanced MPMC)       |                     |                  |
14+--------------+---------------------------------+------------------+
15               |                                 |
16===============|========= Shared Memory =========|===================
17               |     (mmap / CreateFileMapping)  |
18+--------------v---------------------------------v------------------+
19| C11 Worker Process (Isolated Address Space)                       |
20|                                                                   |
21|  +-----------------------+     +-------------------------------+  |
22|  | Generated C11 Server  |---->| Generation-Checked Handle     |  |
23|  | & Batch Shims         |     | Table (hqq_rpc.c)             |  |
24|  +-----------+-----------+     +---------------+---------------+  |
25|              |                                 |                  |
26|              +----------------+----------------+                  |
27|                               |                                   |
28|                     +---------v---------+                         |
29|                     | Native C Library  |                         |
30|                     | (SQLite, Zstd...) |                         |
31|                     +-------------------+                         |
32+-------------------------------------------------------------------+

1. Транспорт на основе разделяемой памяти (`gosuda.org/hqq` и `c/`)

Базовый пакет gosuda.org/hqq и его аналог для C11 в каталоге c/ реализуют два режима транспорта через разделяемую память поверх POSIX mmap (Linux и macOS) и Win32 CreateFileMappingW (Windows). Каждый разделяемый сегмент начинается с проверенного суперблока HQQ_STL3, который фиксирует версию протокола, геометрию буфера и PID конечных точек до чтения любого индекса кольцевого буфера.

Все критические управляющие слова и заголовки слотов выровнены по границам строк кэша размером 64 байта, поэтому ядра производителя и потребителя никогда не конкурируют за одну и ту же строку кэша из-за ложного совместного использования (false sharing).

1StandardLink Slot Layout (64-Byte Cache-Line Aligned)
2Byte Offset:  0x00                0x08                0x10                          0x40
3              +-------------------+-------------------+-----------------------------+
4Header Line:  | seq (u64 atomic)  | len (u32) | flags | reserved (zero-padded)      |
5              +-------------------+-------------------+-----------------------------+
6Payload Area: | payload bytes [0 .. BufferSize - 1] (directly encoded / decoded)    |
7              +---------------------------------------------------------------------+

Поле	Смещение	Размер	Семантика
`seq`	`0x00`	8 Б	Монотонный счетчик последовательности. Нечетные значения обозначают запись в процессе выполнения; четные значения публикуют зафиксированный фрейм посредством операции store-release.
`len`	`0x08`	4 Б	Длина полезной нагрузки в байтах, записанная в слот (`0 <= len <= BufferSize`).
`flags`	`0x0C`	4 Б	Биты управления фреймом (продолжение, статус ошибки или уведомление об остановке).
`payload`	`0x40`	`BufferSize`	Непрерывная область полезной нагрузки, читаемая и записываемая на месте без промежуточных копий.

Вызывающие стороны выбирают между двумя транспортными уровнями в зависимости от структуры параллелизма:

StandardLink (сеанс 1:1 SPSC): Связывает клиентскую и серверную сессию через выделенные слоты запросов и ответов, защищенные блокировкой последовательности (SeqLock). На быстром пути записывающий компонент выполняет сериализацию напрямую в отображенный слот и фиксирует ее атомарной операцией store-release; читающий компонент выполняет короткое ожидание в цикле (spin) в пространстве пользователя перед переходом к примитивам пробуждения операционной системы (futex в Linux, __ulock_wait в macOS, WaitOnAddress в Windows). Круговой обход для одного фрейма занимает около 200 нс при показателе 0 allocs/op.
Advanced (кольцо диспетчеризации MPMC): Мультиплексирует M параллельных вызывающих потоков Go среди N рабочих потоков C с использованием неблокирующего кольца отправки с множеством производителей и потребителей, общего пула слотов и индексированной таблицы завершения. Вызывающие стороны резервируют слот, публикуют индекс слота в кольце и ожидают свою запись завершения, пока рабочие потоки извлекают и завершают запросы вне порядка их поступления.

Оба уровня непрерывно отслеживают активность собеседника. Каждая конечная точка обновляет атомарную монотонную временную метку с помощью Heartbeat() и проверяет PeerAlive(timeout) во время ожидания. Если рабочий процесс аварийно завершается в середине вызова, партнер немедленно обнаруживает устаревшую временную метку или мертвый PID, прерывает заблокированные ожидания с помощью ошибки ErrPeerGone и поддерживает атомический перехват сеанса (Takeover) без оставления зависших файлов разделяемой памяти.

2. RPC без выделения памяти и дескрипторы с проверкой поколения (`gosuda.org/hqq/bindgen`)

Ручное написание фреймирования разделяемой памяти для библиотеки C с десятками функций является утомительным и подверженным ошибкам процессом. Утилита hqq-bindgen представляет собой компилятор схем, который читает файл языка определения интерфейса (.idl) (или создает его автоматически напрямую из заголовочного файла .h на языке C посредством команды hqq-bindgen init) и генерирует клиентский пакет Go без использования cgo наряду со скелетом сервера на C11.

Самая опасная ошибка в любой обертке C заключается в предоставлении сырых указателей C (sqlite3*, sqlite3_stmt*, ZSTD_CCtx*) через границу языка. Если вызывающий компонент передает указатель после его освобождения, передает указатель, принадлежащий другой сессии, или повреждает целочисленный адрес, библиотека C выполняет разыменование недействительной памяти.

Инструмент hqq-bindgen запрещает использование сырых указателей на уровне передачи данных. Вместо этого IDL моделирует ресурсоемкие состояния C как типизированные объявления дескрипторов (handle):

1service sqlite3 {
2    handle Db;
3    handle Stmt @owned_by(Db);
4
5    fn open_v2(path: string, flags: i32) -> result<Db, i32>;
6    fn prepare_one(db: Db, sql: string) -> result<Stmt, i32>;
7    fn finalize(stmt: @consume Stmt) -> result<void, i32>;
8    fn close(db: @consume Db) -> result<void, i32>;
9}

На уровне передачи данных каждый дескриптор представляет собой 64-битное целое число, упаковывающее 32-битный индекс таблицы и 32-битный ненулевой счетчик поколения: (uint64_t)generation << 32 | index. Среда выполнения C (c/src/hqq_rpc.c) поддерживает таблицу дескрипторов для каждой сессии с тремя инвариантами:

Проверка поколения: Каждый поиск проверяет, что слот занят, его сохраненное поколение совпадает с верхними 32 битами дескриптора, а тег типа дескриптора соответствует типу параметра (Db или Stmt). Повторное использование закрытого дескриптора немедленно завершается ошибкой HQQRPC_E_BAD_HANDLE до вызова библиотеки C.
Иерархическое владение (@owned_by): Поскольку Stmt помечен аннотацией @owned_by(Db), закрытие дескриптора Db автоматически обходит все активные дочерние дескрипторы Stmt, принадлежащие этой базе данных, и выполняет их деструкторы в обратном порядке выделения (sqlite3_finalize перед sqlite3_close_v2).
Очистка при завершении сеанса: Если клиент Go отключается или завершается аварийно без закрытия своих дескрипторов, деструктор сеанса сервера C сканирует всю таблицу дескрипторов сеанса в обратном порядке, гарантируя отсутствие утечек выделенной памяти C после перезапусков клиента.

Перед тем как сеанс обработает свой первый RPC-вызов, клиент и сервер обмениваются 32-байтовым дайджестом интерфейса SHA-256, вычисленным по канонизированному IDL (с префиксом HQQ-BINDGEN-IDL-V1\n). Если клиент Go и рабочий процесс C были скомпилированы из несовместимых схем IDL, рукопожатие отклоняет соединение на этапе загрузки.

3. Защищенное от манипуляций выполнение двоичных файлов (`gosuda.org/hqq/secureexec`)

Перемещение кода C в рабочий исполняемый файл поднимает вопрос цепочки поставок: как процесс Go узнает, что рабочий файл на диске не был изменен или заменен между проверкой и выполнением?

Вызов crypto/sha256 для пути к файлу с последующим os/exec.Command(path).Start() оставляет окно уязвимости между проверкой и использованием (TOCTOU), в течение которого другой процесс может перезаписать или подменить файл до того, как ядро выполнит его. Пакет gosuda.org/hqq/secureexec закрывает это окно:

В ОС Linux модуль secureexec открывает бинарный файл, передает его содержимое в дескриптор анонимной файловой памяти, созданный с помощью memfd_create(MFD_CLOEXEC | MFD_ALLOW_SEALING), одновременно вычисляя его хэш SHA-256, сверяет хэш с зафиксированным 32-байтовым дайджестом или подписанным Ed25519 манифестом релиза (cmd/hqq-manifest), применяет fcntl(F_ADD_SEALS, F_SEAL_SEAL | F_SEAL_SHRINK | F_SEAL_GROW | F_SEAL_WRITE), чтобы ни один процесс в системе не мог изменить страницы памяти, и порождает дочерний процесс из запечатанного дескриптора.
В macOS и Windows модуль secureexec материализует проверенные двоичные файлы в защищенных от изменения правами доступа кэш-директориях, индексируемых по дайджесту SHA-256, и проверяет размер файла и целостность дайджеста перед запуском.

4. Надзор за процессами через спасательный круг родителя (`gosuda.org/hqq/launch`)

Когда приложение Go порождает фоновый рабочий процесс C, рабочий процесс никогда не должен переживать своего родителя в качестве осиротевшего процесса, даже если родительский процесс Go завершается сигналом SIGKILL (kill -9) и не может выполнить обработчики очистки defer.

Модуль gosuda.org/hqq/launch принудительно обеспечивает связывание жизненного цикла с помощью анонимного канала операционной системы, переданного на стандартный ввод рабочего процесса с флагом --parent-stdin. Родительский процесс Go удерживает записывающий конец канала и никогда в него не пишет; рабочий процесс C следит за читающим концом в выделенном потоке спасательного круга. Если процесс Go завершается нормально, вызывает панику или уничтожается ядром ОС (сигналом SIGKILL или OOM-киллером), ядро немедленно закрывает дескриптор записи. Рабочий процесс C получает EOF в канале в течение микросекунд, прерывает любые активные вызовы, запускает деструкторы дескрипторов сеанса, удаляет файлы разделяемой памяти и чисто завершает работу.

Быстрый старт: вызов сгенерированного сервиса

С использованием hqq-bindgen и launch вызов изолированного рабочего процесса C из Go выглядит как работа с обычным типизированным клиентом Go при сохранении параметра CGO_ENABLED=0:

 1package main
 2
 3import (
 4	"context"
 5	"fmt"
 6	"log"
 7	"time"
 8
 9	"gosuda.org/hqq/bindgen/rt"
10	"gosuda.org/hqq/launch"
11	"gosuda.org/hqq/secureexec"
12)
13
14func main() {
15	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
16	defer cancel()
17
18	hash, err := secureexec.ParseHash("7649b1b45dacd934cde8149f35f4fcc3937f6486fbac23ce976466719b3752bb")
19	if err != nil {
20		log.Fatal(err)
21	}
22
23	listener, err := launch.NewListenerName("demo")
24	if err != nil {
25		log.Fatal(err)
26	}
27
28	srv, err := launch.Start(ctx, launch.Config{
29		Binary:   "/path/to/verified-worker",
30		SHA256:   hash,
31		Listener: listener,
32		Args:     []string{listener},
33	})
34	if err != nil {
35		log.Fatal(err)
36	}
37	defer srv.Close()
38
39	fmt.Printf("worker running on shared-memory listener %s (opts=%+v)\n", listener, rt.SessionOptions{})
40}

Структура репозитория

Каждая подсистема в gosuda.org/hqq организована в виде специализированных пакетов с явными границами:

 1gosuda.org/hqq
 2├── standard.go / ring.go      # StandardLink (SPSC) and low-level shared-memory ring primitives
 3├── advanced.go / slotpool.go  # Advanced (MPMC) dispatcher, slot pool, and completion table
 4├── shm_*.go / wait_*.go       # OS-specific mmap/CreateFileMapping and futex/ulock/WaitOnAddress
 5├── c/                         # C11 transport library (hqq.c) and RPC server runtime (hqq_rpc.c)
 6├── bindgen/                   # hqq-bindgen IDL parser, verifier (V1-V41), and Go/C11 code generator
 7│   └── rt/                    # Zero-allocation Go client runtime for generated services
 8├── secureexec/                # SHA-256 / Ed25519 manifest verification and memfd-sealed execution
 9├── launch/                    # Worker process supervisor with --parent-stdin lifeline management
10├── cmd/hqq-manifest/          # CLI tool for generating and signing release binary manifests
11└── spec/                      # Executable wire specifications and golden test vectors (BINDGEN.md)

Чтобы увидеть, как HQQ обеспечивает готовую замену для промышленного использования для двух наиболее широко используемых библиотек cgo в экосистеме Go, ознакомьтесь со вспомогательными пакетами, созданными на базе этого стека:

gosuda.org/sqlite3: Готовый драйвер database/sql, совместимый с github.com/mattn/go-sqlite3, выполняющий нативный код C SQLite 3.54.1 поверх разделяемой памяти с конвейерной пакетной предварительной выборкой.
gosuda.org/zstd: Готовая замена для github.com/DataDog/zstd, исполняющая нативный код C libzstd 1.5.7 в изолированном рабочем процессе с разделяемой памятью без выделения памяти в куче и с пакетной обработкой блоков.
Репозиторий на GitHub: https://github.com/gosuda/HQQ

Цена разделения адресного пространства с C

Архитектурный обзор: четыре слоя через границы процессов

1. Транспорт на основе разделяемой памяти (gosuda.org/hqq и c/)

2. RPC без выделения памяти и дескрипторы с проверкой поколения (gosuda.org/hqq/bindgen)

3. Защищенное от манипуляций выполнение двоичных файлов (gosuda.org/hqq/secureexec)