gosuda.org/zstd: Compresie DataDog/zstd de tip Drop-In cu CGO Zero și Izolare la Prăbușire

gosuda.org/zstd este o bibliotecă de compresie Go cu CGO_ENABLED=0 care rulează motorul oficial C Zstandard (libzstd 1.5.7) în cadrul unui proces de lucru izolat, prin intermediul memoriei partajate HQQ. Aceasta furnizează un API de înlocuire directă (drop-in replacement) pentru github.com/DataDog/zstd (incluzând funcții de compresie/decompresie unice (one-shot) Compress/Decompress, interfețe de flux io.Writer/io.Reader, dicționare pre-digerate și contexte reutilizabile fără alocare), menținând în același timp execuția în C complet în afara spațiului de adrese al timpului de execuție Go.

1go get gosuda.org/zstd@v0.3.10507

De ce decompresia aparține în afara Heap-ului dumneavoastră Go

În mediile de producție de tip backend, compresia și decompresia se află direct la granița intrărilor neverificate. Colectoarele de jurnale (log collectors), brokerii de mesaje, porțile de acces RPC (RPC gateways) și motoarele de stocare decomprimă gigabiți de cadre furnizate extern în fiecare minut.

Multe echipe care utilizează Go aleg github.com/DataDog/zstd deoarece se leagă direct de biblioteca upstream în C libzstd: implementarea în C oferă un debit ridicat pe un singur nucleu (single-core throughput), rate strânse de compresie cu dicționar pentru înregistrări mici și zone de memorie (arenas) C în afara heap-ului (ZSTD_CCtx și ZSTD_DCtx) care nu umflă timpii de scanare a colectării de gunoi (garbage-collection) din Go.

Totuși, legarea libzstd într-un serviciu Go prin intermediul cgo aduce două dificultăți operaționale:

1. Fricțiune la compilare și implementare: La fel ca go-sqlite3, DataDog/zstd necesită CGO_ENABLED=1 și un lanț de instrumente (toolchain) de compilare C țintă. Compilarea încrucișată a serviciilor sau construirea de binare statice pentru linux/arm64 sau windows/arm64 necesită rădăcini de sistem (sysroots) C externe.
2. Spațiu de adrese partajat pentru intrări neverificate: Decomprimarea sarcinilor utile corupte sau antagonice în același spațiu de adrese virtual ca serverul dumneavoastră Go înseamnă că orice eroare din codul C nativ sau din gestionarea personalizată a dicționarelor poate termina întregul proces Go.

gosuda.org/zstd păstrează exact motorul upstream în C libzstd 1.5.7 și API-ul familiar github.com/DataDog/zstd, dar mută execuția C într-un proces copil verificat (zstd_server) conectat la programul dumneavoastră Go prin memorie partajată la nivel de linie de cache.

Înlocuitor direct (Drop-In Replacement) pentru github.com/DataDog/zstd

Migrarea de la github.com/DataDog/zstd necesită modificarea unei singure căi de import la "gosuda.org/zstd". Nu este necesară nicio instalare de binar extern sau cod de configurare: la primul apel, gosuda.org/zstd materializează un binar încorporat zstd_server certificat SLSA pentru platforma dumneavoastră, verifică suma sa de control SHA-256 prin gosuda.org/hqq/secureexec și deschide un grup de sesiuni cu memorie partajată.

 1package main
 2
 3import (
 4	"bytes"
 5	"fmt"
 6	"io"
 7	"log"
 8
 9	"gosuda.org/zstd"
10)
11
12func main() {
13	// 1. Compresie / Decompresie unică (reflectă github.com/DataDog/zstd)
14	src := []byte("shared-memory zstd payload without cgo")
15	compressed, err := zstd.CompressLevel(nil, src, zstd.BestSpeed)
16	if err != nil {
17		log.Fatal(err)
18	}
19	plain, err := zstd.Decompress(nil, compressed)
20	if err != nil {
21		log.Fatal(err)
22	}
23	fmt.Printf("one-shot: %d bytes -> %d bytes (%s)\n", len(src), len(compressed), plain)
24
25	// 2. Writer și Reader flux cu suport pentru dicționar
26	var buf bytes.Buffer
27	w := zstd.NewWriterLevel(&buf, zstd.DefaultCompression)
28	if _, err := w.Write(src); err != nil {
29		log.Fatal(err)
30	}
31	if err := w.Close(); err != nil {
32		log.Fatal(err)
33	}
34
35	r := zstd.NewReader(&buf)
36	defer r.Close()
37	streamed, err := io.ReadAll(r)
38	if err != nil {
39		log.Fatal(err)
40	}
41	fmt.Printf("streamed: %s\n", streamed)
42}

Platforme compatibile și binare încorporate

Toate cele șase platforme țintă sunt livrate cu binare de lucru precompilate și fixate prin SHA-256, încorporate prin etichete de compilare specifice platformei (internal/embedded/embed_<goos>_<goarch>.go):

În interiorul căii de date cu memorie partajată

Pentru a menține debitul competitiv cu cgo în cadrul procesului, gosuda.org/zstd evită serializarea prin socket și alocările în heap pe calea critică (hot path).

1. Codificarea sloturilor fără alocare (zstd_ctx.go și c/zstd_hooks.c)

Atunci când utilizați un zstd.Ctx reutilizabil (sau când funcțiile de nivel de pachet Compress și Decompress împrumută un Ctx din grupul intern de sesiuni), datele circulă direct prin slotul mapat StandardLink:

1Go Caller (zstd.Ctx)                    Shared-Memory Slot                    C11 Worker (zstd_hooks.c)
2--------------------                    ------------------                    -------------------------
3src []byte  ------------------------->  Request Slot Payload  ------------->  ZSTD_compressCCtx(
4                                                                                cctx, resp_slot, src, level)
5dst []byte  <-------------------------  Response Slot Payload <-------------  Writes compressed frame directly
6                                                                              into shared response slot

1. Clientul generat hqq-bindgen copiază src direct în slotul de cerere mapat în memorie și inversează cuvântul de secvență SeqLock.
2. Lucrătorul (worker) C citește src direct din slotul de cerere și transmite pointerul sarcinii utile a slotului de răspuns direct ca tampon de destinație către ZSTD_compressCCtx sau ZSTD_decompressDCtx.
3. Clientul Go copiază felia (slice) rezultată din slotul de răspuns în felia dst furnizată de apelant. În regim permanent, ctx.CompressTo(dst, src, level) și ctx.DecompressInto(dst, src) execută 0 allocs/op.

Dicționarele pre-digerate (CDict și DDict) se află pe lucrătorul C în spatele unor elemente deハンドル (mânere / handles) pe 64 de biți verificate prin generație (handle CDict, handle DDict în zstd.idl). Crearea unui dicționar o singură dată prin ctx.NewCDict(rawDict, level) analizează tabelele dicționarului în interiorul lucrătorului C și returnează un mâner ușor care poate fi reutilizat în mii de apeluri fără a retrimite octeții dicționarului.

2. Amortizarea suprasolicitării IPC cu încadrare în bloc (Bulk Framing) (zstd_bulk.go)

Pentru sarcini utile mari (16 KiB și peste), parcursul de dus-întors în memorie partajată de ~200 ns este neglijabil în comparație cu timpul de CPU petrecut în interiorul libzstd. Cu toate acestea, pentru sarcinile de lucru care comprimă mii de mesaje mici de la 100 de octeți la 1 KiB dintr-o singură mișcare, plata a chiar și 200 ns per element se adună semnificativ.

gosuda.org/zstd furnizează CompressBulk și DecompressBulk pe BulkCtx (zstd_bulk.go) pentru a elimina parcursurile de dus-întors per element:

 1bctx, err := client.NewBulkCtx(1 << 20)
 2if err != nil {
 3	log.Fatal(err)
 4}
 5defer bctx.Close()
 6
 7items := [][]byte{
 8	[]byte(`{"event":"login","user":101}`),
 9	[]byte(`{"event":"purchase","user":101,"amount":4200}`),
10	[]byte(`{"event":"logout","user":101}`),
11}
12compressedItems, err := bctx.CompressBulk(nil, items, zstd.DefaultCompression)

CompressBulk împachetează întregul lot [][]byte într-un singur cadru de cerere precedat de lungime în memoria partajată. Lucrătorul C parcurge fiecare element în C (compress_bulk în c/zstd_hooks.c), scrie toate cadrele comprimate în mod contiguu în slotul de răspuns și returnează întregul lot printr-un singur parcurs de dus-întors în memoria partajată.

3. Supraviețuirea terminării lucrătorului fără prăbușirea apelantului

Deoarece zstd_server rulează într-un proces de sistem de operare separat, o eroare fatală în interiorul lucrătorului C nu va bloca niciodată aplicația dumneavoastră Go:

• Dacă zstd_server este oprit din exterior (de exemplu, prin SIGKILL sau un eveniment OOM), stratul de transport HQQ detectează imediat omologul întrerupt și returnează un *rt.TransportError tipizat din apelul Compress sau Decompress aflat în curs de desfășurare.
• Funcțiile de nivel de pachet (zstd.Compress, zstd.Decompress, zstd.NewWriter, zstd.NewReader) detectează automat că lucrătorul implicit partajat a dispărut, generează o instanță proaspătă și verificată zstd_server la următorul apel și reiau funcționarea normală.

Structura depozitului

Baza de cod separă fațada de înlocuire directă DataDog/zstd de elementele primitive de sesiune și în bloc de nivel inferior hqq-bindgen:

1gosuda.org/zstd
2├── autolaunch.go / hashes.go  # API de compresie/decompresie încorporat, grup de recuperare automată și hash-uri SHA-256
3├── zstd_stream.go             # Writer/Reader flux (NewWriterLevelDict, NewReaderDict)
4├── zstd_ctx.go                # Wrappere Ctx, CDict și DDict fără alocare peste hqq-bindgen
5├── zstd_bulk.go               # Încadrare CompressBulk și DecompressBulk cu un singur dus-întors
6├── zstd.go                    # Client Go hqq-bindgen generat pentru serviciul IDL zstd
7├── zstd.idl                   # Schemă HQQ IDL care definește Context, CDict, DDict și metode RPC
8├── internal/embedded/         # Binare //go:embed zstd_server etichetate pentru platformă (6 ținte OS/Arhitectură)
9└── c/                         # Implementare server C11 (zstd_server.c, zstd_hooks.c, main.c)

Noțiuni de bază

Instalați gosuda.org/zstd folosind go get și utilizați-l cu CGO_ENABLED=0:

1go get gosuda.org/zstd@v0.3.10507

• Depozitul GitHub: https://github.com/gosuda/hqq-zstd
• Arhitectură și teste de performanță (Benchmarks): docs/ARCHITECTURE.md
• Timpul de execuție principal HQQ: https://gosuda.org/hqq