HQQ: Изолиране на C библиотеки от Go чрез споделена памет, подравнена по кеш линия

gosuda.org/hqq е времево-нулева (zero-cgo) среда за междупроцесна комуникация и инструментариум за генериране на код за Go и C11. Тя изолира нативни C библиотеки в отделни работни процеси на операционната система и ги свързва с Go извикващите през споделени пръстени в паметта, подредени по граници на кеш линии и картирани чрез mmap. Проектът съчетава два транспортни слоя (StandardLink за изолирани сесии от тип SPSC с един производител и един консуматор и 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 в матрица от кросскомпилатори и sysroot среди.
Режийни разходи за планиране на изпълнението: Всяко извикване на cgo преминава границата на Go средата на изпълнение, превключва от разширяем стек на горутина към системен стек и закрепва нишка на операционната система (M). При фино гранулирани извиквания разходът за преход (~50 до 150 ns на извикване) и конкуренцията за планировчика бързо се натрупват.
Колапс на домейна на грешките: C кодът работи в същото виртуално адресно пространство като Go средата на изпълнение. Единствен запис извън границите, използване след освобождаване, препълване на стека или abort() във функция на C повреждат метаданните на Go купчината или незабавно прекратяват целия сървърен процес, заобикаляйки recover() и повличайки след себе си всяка заявка по HTTP или RPC, която е в ход.

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

Създадохме HQQ, след като си зададохме директен въпрос: какво ще стане, ако C библиотеката живее в отделен процес на операционната система със собствено виртуално адресно пространство, а Go и C обменят кадри директно през споделени кеш линии на процесора, без да навлизат в ядрото по бързия път?

Модел на интеграция	`CGO_ENABLED=0`	Изолация на грешки	Системни извиквания на бързия път	Динамични алокации на паметта за извикване	Вярност спрямо upstream C11
`cgo` вграждане в процеса	Не	Няма (споделена купчина)	0	0 до 1+	Точно upstream C
Подпроцесен RPC през сокет/тръба	Да	Граница на процеса	2 до 4	Множество (рамкиране + I/O)	Точно upstream C
Механичен превод от C към Go	Да	Go в процеса	0	Високо при сложни извиквания	Емулирана C среда
HQQ споделена памет за IPC	Да	Граница на процеса	0 (адаптивно въртене)	0 (`StandardLink`)	Точно upstream 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 байта (кеш линия), така че производителите и консументите на ядра никога да не конкурират за една и съща кеш линия поради фалшиво споделяне.

1Оформление на слот в StandardLink (подравнен по кеш линия от 64 байта)
2Отместване в байтове:  0x00              0x08              0x10                          0x40
3              +-------------------+-------------------+-----------------------------+
4Линия на заглавката: | seq (u64 atomic)  | len (u32) | flags | reserved (zero-padded)      |
5              +-------------------+-------------------+-----------------------------+
6Област на полезния товар: | payload bytes [0 .. BufferSize - 1] (directly encoded / decoded)    |
7              +---------------------------------------------------------------------+

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

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

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

И двата слоя проследяват непрекъснато жизнеspособността на партньора. Всяка крайна точка актуализира атомарна монотонна времева марка чрез Heartbeat() и проверява PeerAlive(timeout) по време на чакане. Ако работен процес се срине по средата на извикване, партньорът незабавно открива остарялия сърдечен ритъм или мъртвия PID, прекратява блокираните чакания с ErrPeerGone и поддържа атомарно Takeover на сесията, без да оставя заклещени файлове в споделената памет.

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

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

Най-опасната грешка при всяко C свързване е излагането на сурови C указатели (sqlite3*, sqlite3_stmt*, ZSTD_CCtx*) през езиковата граница. Ако извикващият подаде указател след освобождаването му, подаде указател, принадлежащ на друга сесия, или повреди целочислен адрес, C библиотеката дereferencира невалидна памет.

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, притежавани от този Db, и изпълнява техните деструктори в обратен ред на алокацията (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 или убиецът при липса на памет), ядрото незабавно затваря записващия дескриптор. 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	// Създаване на контекст с време на изчакване от 5 секунди
16	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
17	defer cancel()
18
19	hash, err := secureexec.ParseHash("7649b1b45dacd934cde8149f35f4fcc3937f6486fbac23ce976466719b3752bb")
20	if err != nil {
21		log.Fatal(err)
22	}
23
24	listener, err := launch.NewListenerName("demo")
25	if err != nil {
26		log.Fatal(err)
27	}
28
29	srv, err := launch.Start(ctx, launch.Config{
30		Binary:   "/path/to/verified-worker",
31		SHA256:   hash,
32		Listener: listener,
33		Args:     []string{listener},
34	})
35	if err != nil {
36		log.Fatal(err)
37	}
38	defer srv.Close()
39
40	fmt.Printf("worker running on shared-memory listener %s (opts=%+v)\n", listener, rt.SessionOptions{})
41}

Структура на хранилището

Всяка подсистема в gosuda.org/hqq е организирана в тематични пакети с ясни граници:

 1gosuda.org/hqq
 2├── standard.go / ring.go      # StandardLink (SPSC) и примитиви за пръстен в споделена памет от ниско ниво
 3├── advanced.go / slotpool.go  # Advanced (MPMC) диспечер, пул от слотове и таблица за завършване
 4├── shm_*.go / wait_*.go       # Специфични за ОС mmap/CreateFileMapping и futex/ulock/WaitOnAddress
 5├── c/                         # C11 транспортна библиотека (hqq.c) и RPC сървърна среда за изпълнение (hqq_rpc.c)
 6├── bindgen/                   # Анализатор на IDL за hqq-bindgen, верификатор (V1-V41) и генератор на код за Go/C11
 7│   └── rt/                    # Клиентска среда за Go без алокации за генерирани услуги
 8├── secureexec/                # Проверка с SHA-256 / манифест с Ed25519 и изпълнение със запечатана memfd
 9├── launch/                    # Надзорник на работни процеси с управление на родителската връзка --parent-stdin
10├── cmd/hqq-manifest/          # CLI инструмент за генериране и подписване на манифести на двоични издания
11└── spec/                      # Изпълними спецификации на протокола и златни тестови вектори (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)

4. Надзор на процесите чрез родителска връзка (gosuda.org/hqq/launch)