statsig-go: serialize purego FFI dispatches to dodge upstream race

[nsaini-figma]

Summary

Adds a process-wide sync.Mutex on *StatsigFFI and takes it across every purego-registered call this binding dispatches. Workaround — not a root-cause fix — for a concurrent-FFI-return-value race in github.com/ebitengine/purego (v0.9.x) that has been causing intermittent labmate crashes since the cutover from the upstream binding at v0.15.1 to this fork at statsig-go/v0.19.4-figma1.

Why

The labmate FFI SIGSEGV (memmove on non-canonical pointer + glibc "double free or corruption (out)" + nil-deref at *gateJson) was narrowed end-to-end to a purego concurrency bug. Two goroutines making purego dispatches in flight at the same time can have their return pointers swapped between callers: caller A gets B's *c_char and vice versa. Once the wrong pointer lands in Go, runtime.memmove over unsafe.Slice(ptr, len) faults, and the deferred free_string(ptr) makes two callers race to free the same buffer.

Discrimination matrix (full writeup forthcoming, not committed here):

• Plain-C pthread reproducer against the same libstatsig_ffi.so: 32 threads, ~16M ops, clean. So the Rust side is exonerated.
• Upstream Rust SDK bisect 0.15.1 → 0.19.3 + this fork: every version crashes when paired with the current Go binding. So this is not a Rust-side regression.
• Minimal purego-only repro (no statsig at all, single func(uint64) *byte): 2 goroutines crash within seconds with return pointers literally swapped. So the bug is purego itself.
• A sync.Mutex around UseRustString makes the production reproducer run ~13M ops over 30s with zero crashes.

What changed

• statsig-go/statsig_ffi.go: add mu sync.Mutex to StatsigFFI with full motivation in comment. Rewrite UseRustString to hold mu across handler() + free_string.
• statsig-go/statsig.go: lock around every direct purego dispatch (NewStatsig, NewStatsigWithOptions, Initialize, Shutdown, FlushEvents, LogEvent, CheckGateWithOptions, the 4 ManuallyLog*Exposure methods, and release). The Get*Gate / Config / Experiment / Layer / ParameterStore / ClientInitResponse methods inherit protection via UseRustString.
• statsig-go/statsig_types.go: lock around Layer.logExposure and the primitive-returning ParameterStore getters (GetBool, GetNumber, GetInt). GetString / GetMap / GetSlice are already UseRustString-protected.
• statsig-go/statsig_user.go, statsig-go/statsig_options.go: lock around create + finalizer-release.
• statsig-go/data_store.go, statsig-go/observability_client.go, statsig-go/persistent_storage.go: lock around the _create constructor calls and finalizer _release calls. The Rust→Go callbacks (Get/Set/Increment/etc.) deliberately do NOT take mu — see lock-ordering note on the mu field.

Invariants worth calling out

• Lock scope is the C-side hop only. JSON marshal/unmarshal stays parallel. Per-call critical section is ~5–10 µs on the hot path.
• Callbacks must not take mu. Comment on the mu field spells this out — Rust→Go callbacks fired synchronously from inside an FFI call this binding has dispatched would self-deadlock otherwise. None of the existing callback closures touch the mutex, but anyone adding new callback wiring needs to keep this invariant.
• No .so change, no version bump. Pure Go-side patch. No statsig-go/v0.19.4-figma2 tag yet — wait for review and a labmate canary before cutting.
• 10 FFI fields without public Go wrappers (statsig_override_*, statsig_remove_*_override, statsig_identify, async statsig_shutdown/statsig_flush_events, statsig_check_gate_performance) are untouched. When wrappers are added, they'll need the same pattern.
• Upstream issue to be filed against ebitengine/purego with the minimal func(uint64) *byte repro. The mutex here is a tourniquet pending that fix.

Test plan

• go build ./statsig-go/... passes.
• Local reproducer (32 goroutines × 30s × 5 runs, ~83k ops/sec, ~11.5M total gate calls): zero crashes on patched binding. Same workload reliably crashes within seconds against unpatched v0.19.4-figma1.
• go test ./statsig-go/... once CI runs.
• Reviewer optionally re-runs the discrimination matrix locally — repro at /tmp/statsig-repro/ on devbox.
• Labmate canary deploy against a v0.19.4-figma2 build of this branch before promoting fleet-wide.

🤖 Generated with Claude Code