DEV Community: Andrey Kolkov

Read and Write MATLAB .mat Files in Go Without CGO: Files That Read as Empty, and MATLAB Files We Couldn't Open

Andrey Kolkov — Sat, 07 Nov 2026 11:57:29 +0000

The previous article was about scigolib/hdf5, a pure Go HDF5 library born out of the need to read MATLAB data in Go. This is the other half of that story: scigolib/matlab, the library that actually reads the .mat files.

It reads and writes both MATLAB formats in pure Go, with no cgo:

v5 (MATLAB v5 to v7.2): the classic binary format, including the zlib-compressed elements MATLAB writes by default;
v7.3: HDF5 underneath, through scigolib/hdf5.

What works today: every numeric class, complex numbers, multi-dimensional arrays, reading char arrays, both byte orders, 32-bit targets in CI, and a fuzz-tested v5 parser. Compressed elements are capped at 100 MB each and a 1000:1 ratio, so a zip bomb fails instead of eating memory.

What doesn't yet:

structures and cell arrays are not decoded (in v5 you get the class; a v7.3 struct comes back as one variable per field);
sparse matrices;
complex numbers in v7.3 use a real/imag group, not MATLAB's compound layout;
character arrays can be read but not written;
the writer doesn't compress;
an empty v5 cell {} makes Open fail.

Most of what I want to tell here are bugs, and nearly all of them share one cause:

Our tests mostly saw files we wrote ourselves.

Files saved with MATLAB's defaults read as empty

By default, MATLAB's save writes a Version 7 MAT file with compression on: each variable is wrapped in a miCOMPRESSED element. Up to v0.3.0, the reader skipped elements it didn't handle. So for a file saved with plain save data.mat, Open returned no error and zero variables.

Reproduced on the v0.3.0 tag, with SciPy's test file inner_outer_tbl_param.mat:

v0.3.0:   0 variables, err = nil
v0.3.19: 12 variables

Our tests never caught it. They read only our own writer's output, which isn't compressed. Three compressed SciPy files were already sitting in testdata, but no test opened them until v0.3.15.

v0.3.1 added zlib decompression with the bomb limits above. The lesson was the same one as hdf5's 116 datasets that read "fine": an empty result without an error is worse than a crash.

A bug report that waited three months

Issue #21 from @EtherHelm was the first and so far only external issue the project has had. MATLAB couldn't read files the library wrote. They had already traced the v5 cause themselves.

The array flags element has two 32-bit words. The spec puts the class in bits 0–7 of the first word and the flags in bits 8–11; the second word is nzmax. Our encodeArrayFlags put them in the wrong words. And the reader had the mirror bug: it read the class from the second word.

So the writer and the reader agreed with each other, and every round-trip test passed. Same story as the compound datatypes in hdf5: a round trip through your own code proves only that your code is consistent with itself.

What that looked like from the outside, reproduced on the v0.3.14 tag: real files saved by MATLAB and SciPy read with the correct values, but every variable's DataType came back as unknown, because the class was taken from nzmax, which is 0. A second bug sat next to it: the byte-order mapping was inverted, so the default output was big-endian.

The issue was opened on June 7 and answered and fixed on September 2. The plain reason: most of my time goes to GoGPU, Born and coregex, and a notification about a new issue here can get lost. Once those reach their releases, there will be more time to go through every library regularly. Until then, a report like this one, with the cause already traced, is the fastest way to a fix.

The fix (PR #23) put the spec layout on both sides and added two kinds of tests nobody can satisfy by agreeing with themselves:

reading SciPy's reference .mat files;
golden-byte tests that compare our output with the spec, byte by byte.

One more honest note. The v0.1.1-beta CHANGELOG said "Files now fully compatible with MATLAB/Octave". No test in the repository has ever run MATLAB or Octave. @EtherHelm's report was the first real check, and it failed.

A 136-byte file that could ask for 2 GiB

The same class of bug as hdf5's GHSA-8p88-h28q-w6m9: the v5 parser allocated each element at the size its tag claimed, before reading a byte of it, up to a 2 GiB cap. A 136-byte input that claimed 64 MiB allocated 64 MiB, then failed.

The rest turned up while bumping the hdf5 dependency:

an untyped 2^31 constant used as an int broke the build on linux/386, linux/arm and windows/386;
a claimed size of exactly 2 GiB slipped past the cap and panicked inside make on 386.

v0.3.16 validates every size against the bytes actually present, in one place, the tag reader. When the input length is unknown, it accumulates instead of allocating up front. A CI job now builds for linux/386, linux/arm and windows/386 and runs the tests on linux/386.

The fix that broke `bytes.Buffer`

The release review of v0.3.17 found that the v0.3.16 fix had broken something else.

The bound measured how much input was left after reading the 128-byte header. A bytes.Buffer reports only its unread part, so the bound came out 128 bytes short, and every valid v5 file opened from a bytes.Buffer was rejected: tag size beyond end of file.

No test had passed a bytes.Buffer to Open. Now one test opens every test file through os.File, bytes.Reader, bytes.Buffer and a reader that hides its size.

The same release also caught a stream cut off inside a skipped element being accepted, because io.CopyN errors were dropped. The review added that a file cut short gave a different error depending on whether its length was known. Every path now returns io.ErrUnexpectedEOF.

MATLAB's own v7.3 files didn't open

This bug came to light during the fact-checking for this article, and it affected every v7.3 file MATLAB writes.

MATLAB writes a v7.3 file as HDF5 behind a 512-byte user block. The first 128 bytes of that block are the usual MAT header, with version 0x0200; the HDF5 signature starts at byte 512. Our Open looked for HDF5 only at offset 0, didn't find it, and handed the file to the v5 parser:

tag size beyond end of file: 169478669 bytes at offset 512

All our v7.3 test files came from our own writer, which writes no user block. Same blind spot, third time.

There was no MATLAB-written v7.3 file at hand, so the layout was built from the references: matio (Mat_Open reads the version at bytes 124–125 and opens 0x0200 through HDF5; Mat_Create73 sets a 512-byte user block), SciPy's _get_matfile_version, and the HDF5 C library's signature search, which looks at offset 0 and then at every power of two from 512. h5jam -u produced a test file byte-identical to "block + file", and h5dump opens it. v0.3.18 detects the format by the header version, as matio and SciPy do.

The other direction took one more release. Our own v7.3 output had no MAT header either, and #21 had mentioned v7.3 too, so this may well have been that half of it. Writing the header needed user-block support in hdf5, the equivalent of the C library's H5Pset_userblock. hdf5 v0.15.0 added it, and v0.3.19 writes the header the way matio's Mat_Create73 does. h5dump opens the files. Whether MATLAB loads them, nobody has confirmed yet.

Test data and docs that claimed too much

Two smaller ones, in the same spirit.

The 8 v7.3 test files were written in November 2025 by an early hdf5 version, and h5dump can't open them; the hdf5 article tells that story from its side. They are regenerated now, and a test fails on any hdf5 warning. One old file stays in testdata/legacy to prove such files still read.

The README listed structures, cell arrays and sparse matrices as supported, and complex numbers as "proper MATLAB format for both v5 and v7.3". The reader decoded none of the three, and the v7.3 half of the complex claim wasn't true. It now says what the code does, with a Known Limitations list.

What I'd do differently

1. Your own files are not compatibility tests. Compressed files, the flags layout, the user block: each time, the tests saw little beyond what our writer produced. Test against files written by the other implementations from the start.

2. A silent empty result is worse than an error. Zero variables and nil looked like success.

3. Measure the input before you consume it, and test every kind of reader your API accepts.

4. Don't rely on email alone for issues. #21 waited three months because the notification went unseen. With many projects, look at each one's open issues directly from time to time.

What's next

MATLAB's compound layout for complex numbers, read and write;
structures, cell arrays, sparse matrices, empty cells;
writing character arrays.

If you have MATLAB or Octave, I'd like your help. Write a v5 and a v7.3 file with v0.3.19, load them there, and tell me what happens in an issue. Nobody has verified our v7.3 output in MATLAB itself, and a short report from a real MATLAB session is worth more than any test written without one.

Thanks to @EtherHelm for #21, and for doing half the work in it.

matlab: github.com/scigolib/matlab · pkg.go.dev

go get github.com/scigolib/matlab@v0.3.19

f, err := os.Open("data.mat")
if err != nil {
    log.Fatal(err)
}
defer f.Close()

mat, err := matlab.Open(f) // v5 or v7.3, detected from the header
if err != nil {
    log.Fatal(err)
}
for _, v := range mat.Variables {
    fmt.Println(v.Name, v.DataType, v.Dimensions)
}

HDF5 in Pure Go, No CGO: a 5 KB File That Allocated 40 GB, and Round-Trip Tests That Lied

Andrey Kolkov — Sat, 07 Nov 2026 02:01:30 +0000

Update, 2026-11-07: v0.15.0 is out, and it is the version to use: go get github.com/scigolib/hdf5@v0.15.0.

Upgrade from v0.14.3. A group that switched to dense link storage while being written (at its ninth link, for example in a group that also holds an external link) could leave a file the C library rejects as truncated: end-of-file address N is beyond the file size M. v0.15.0 fixes it. An affected file is repaired by zero-extending it to N (on Linux and macOS: truncate -s N file.h5).

New: user blocks (WithUserBlock, FileWriter.WriteUserBlock, the equivalent of H5Pset_userblock). That is where a MATLAB v7.3 file keeps its MAT header.

Behaviour change: FileWriter.Delete on a non-empty group now deletes the group and everything only it links to, as H5Ldelete does. Code that relied on the old refusal should check that the group is empty first.

The follow-up article, about the .mat reader and writer built on this library: Read and Write MATLAB .mat Files in Go Without CGO.

In June 2025 I was porting SURD, a causal-discovery method from a Nature Communications paper, from its Python reference to Go (causalgo). The reference data came as MATLAB .mat files. In Python that's one scipy.io.loadmat call. In Go I found nothing I could rely on.

Those files happened to be the older v5 format. But a v7.3 .mat file, the format MATLAB needs for any variable of 2 GB or more, is an HDF5 file, so a Go reader that only handled v5 would fail on the first large dataset. And HDF5 itself is how a large part of science stores its data: climate models, telescopes, particle physics. In Go there were cgo bindings to the C library and a few pure-Go attempts, abandoned years ago and far from complete.

If I was going to write these libraries at all, it made sense to make them universal from the start. So four days later I started two repositories instead of one narrow reader: scigolib/matlab and scigolib/hdf5, a full HDF5 library, read and write, in pure Go with no cgo. It has been public for a year now, with 34 releases, and this is the first time I write about it.

Only later did I understand why the earlier attempts stopped. HDF5 is a scientific binary format with decades of history and a nuance in every structure: several versions of each header and message, variable-width fields set per file, half a dozen chunk index types, a filter pipeline, shared messages, and edge cases that only the C library's own test files show you.

What's in it today:

superblock v0, v2 and v3; object headers v1 and v2; compact and dense attributes and links;
contiguous, chunked and compact layouts; GZIP, shuffle and Fletcher32 (LZF and BZIP2 on read);
compound, array, enum, variable-length, reference and opaque types;
chunk indexes of every format version, including the ones HDF5 1.10+ writes (fixed and extensible array, B-tree v2, single chunk, implicit);
reading tested against the HDF5 C library's own test files: 379 of the 383 valid ones read;
files written by the library are checked with h5dump in CI.

One thing goes beyond the C library: when the version 2 B-trees behind dense attributes rebalance after deletions. C merges and redistributes their nodes on every delete (its older version 1 B-trees are never rebalanced). Here you choose: immediately, in batches, in a background goroutine, a strategy picked from the workload, or not at all for append-only files.

What isn't there yet. Each of these fails with an explicit error, not wrong data:

virtual datasets;
the N-bit, scale-offset and SZIP filters;
the shared-message heap.

Not everything is done, but it's close.

scigolib/matlab reads and writes .mat files from v5 to v7.3, the v7.3 ones on top of it.

Then v0.14.3 happened. It started with one report:

One changed byte in a 5,656-byte file made the library try to allocate 40.9 GB.

A 5 KB file, a 40 GB allocation

Issue #75 from @TuSKan. Take a valid file, change the datatype size in the dataset's metadata, and ask for 12 values:

vals, err := ds.ReadSlice([]uint64{0}, []uint64{12})
// v0.14.2: tries to allocate 40,873,492,480 bytes, the process dies

v0.14.2 had just shipped a fix for this class of bug, with a security advisory (GHSA-8p88-h28q-w6m9). Whole-dataset reads were bounded. The hyperslab readers weren't: they parsed the dataset metadata again on their own and skipped the check.

That is the real bug. The fix for one path didn't reach the other paths, because each path had its own copy of the parsing.

The C library doesn't work like that. When it opens a dataset, it validates the storage once (H5D__contig_check, H5D__compact_init, H5D__chunk_set_sizes), and everything after works from that. v0.14.3 does the same:

one validated dataset descriptor, built once per dataset;
every reader takes its sizes from it;
every result buffer is sized through one helper;
a guard test fails if any allocation sized from file metadata appears outside that helper.

With that in place, the review found four more paths of the same class: the B-tree walk, filter output, variable-length amplification and the compound result size. All four are closed.

One case can't be bounded by the file size. A chunked dataset may legally be larger than the file, because unwritten chunks read as the fill value. Those reads get a per-file limit: File.SetReadLimit, 4 GiB by default.

Round-trip tests that lied

Issue #65 from @kf-domeng. A compound dataset written by the library opened fine in the library. h5py and H5Web refused it: invalid number of members: 0.

My round-trip tests were green the whole time. The writer and the reader had the same misunderstanding of the compound datatype message, so they agreed with each other. A round trip through your own code proves only that your code is consistent with itself.

The fix was to stop having two opinions about the format:

one datatype codec for every class, mirroring the C library's encoder and decoder;
the test: decode and re-encode all 1554 datatype messages in the official test files and compare with C's bytes.

They match. The one deliberate difference is 8 old v1 compounds with array members, which get upgraded exactly the way C upgrades them.

Compounds were not the worst case. Dense attribute storage, which HDF5 uses once an object has many attributes, had never been C-compatible at all:

the attribute info message was written and read as message type 15, which in C is the shared-message table (the attribute info message is 21);
the attribute name index was built with link records instead of attribute records, and C checks the record type;
fractal heap objects were addressed from the end of the block header instead of the block start, so C answered "invalid fractal heap offset" for every object we wrote.

All of it passed our tests, because our reader made the same mistakes. Run against the C suite, the reader found 0 of the 9 attributes in tattr4_be.h5, and returned no error. Old files written that way still read, and their storage is moved to the C layout the first time their attributes change.

Compound types also got a public API, validated the way H5Tinsert validates members:

ct, err := hdf5.NewCompoundType(16, []hdf5.CompoundMember{
    {Name: "id", Offset: 0, Type: hdf5.Int32},
    {Name: "energy", Offset: 8, Type: hdf5.Float64},
})
if err != nil {
    return err
}
dw, err := fw.CreateCompound("/events", ct, []uint64{2})
if err != nil {
    return err
}
err = dw.Write([]map[string]any{
    {"id": int32(1), "energy": 13.6},
    {"id": int32(2), "energy": 27.2},
})

116 datasets that read "fine"

This one I found myself, and it bothered me more than the crash.

HDF5 has optional filters the library doesn't implement: N-bit, scale-offset, SZIP, blosc and others. The old code skipped an unknown filter and returned the stored bytes as if they were the values. In the C test suite, 116 datasets read without an error and returned garbage.

A crash you notice. Wrong numbers in a science pipeline you may never notice.

Now an unsupported filter returns ErrNotSupported, as the C library's filter pipeline does. Three smaller ones of the same kind were fixed along the way:

unwritten chunks read as the fill value, not as zero;
unsigned compound members above 2^31 no longer come back negative;
Fletcher32 checksums are verified on read; they used to be stripped unchecked.

Errors you can act on

All the failures above now come back as errors you can tell apart with errors.Is:

f, err := hdf5.Open("data.h5")
if err != nil {
    return err
}
defer f.Close()
f.SetReadLimit(1 << 30) // reads of data the file itself doesn't bound: at most 1 GiB

vals, err := ds.ReadSlice(start, count)
switch {
case errors.Is(err, hdf5.ErrCorrupt):      // the file contradicts itself
case errors.Is(err, hdf5.ErrLimit):        // a read above the limit
case errors.Is(err, hdf5.ErrNotSupported): // e.g. an SZIP-compressed dataset
case errors.Is(err, hdf5.ErrNoData):       // nothing stored, no fill value
}

@skyqvn asked in #67 for structured metadata instead of parsing Info() strings. Datasets now have Shape, MaxShape, Datatype and Layout.

The writer moved closer to C as well. In more places it now writes exactly what the C library writes: the fill value message, filter flags, pipeline v2, dataspace v2 and message order. Tests compare its output with C-written files.

It also got faster. Against v0.14.2, opening and walking a file takes half the time with a tenth of the memory, reading many small slices of a chunked dataset takes 58–72% less time, and across the benchmarks the geometric mean is 44% less time and 64% less memory. (benchstat, six runs of each benchmark in release_bench_test.go, run against both versions on the same laptop.) Most of it came from one fix: object headers are now read with one read per chunk instead of two per message.

Our own old files

The hardest question in this release came from our own sibling project. scigolib/matlab ran its tests against the new, stricter superblock check, and 8 of its .mat test files were rejected. They had been written by this library in November 2025.

The library was right to reject them. Versions up to v0.13.4 wrote a CRC32 checksum where HDF5 requires Jenkins lookup3, and h5dump can't open those files either. Later versions had their own gaps: v2 object headers with no checksum at all, an end-of-file address not updated on close. Files from those versions are not valid HDF5, even though our own reader always opened them.

So what do you do with files your own library wrote wrong?

"Be liberal in what you accept" has a bad record: RFC 9413 describes how silent tolerance entrenches bugs. But a targeted workaround for one known buggy writer is standard practice: Apache Parquet ignores the min/max statistics written by old parquet-mr versions, which it identifies by created_by, instead of rejecting the files. A checksum on metadata guards integrity, not authenticity, so accepting one exact legacy value costs nothing in security.

The policy in v0.14.3:

old files still read, and every deviation is reported through File.Warnings() with a typed code. A file written by the C library or by the current version produces no warnings;
everything the library writes must be valid HDF5. What can be repaired in place is repaired; what can't is refused with a clear error;
go.mod retracts v0.13.9 and older, the versions that wrote files no HDF5 tool can open, so go get no longer picks them and go list -m -u tells users why;
planned: a repack function to convert old files, and from v1.0 a strict default with one explicit legacy option.

Read old files, but never write a new broken one, and tell people so nobody keeps producing them.

How I check it now

The C library is the oracle. Every format check cites the C source it follows, file and line. Where the format spec defines a value, the spec decides, not the C code.
Every fix starts with a test that fails on the old code. Corruption tests claim megabytes against kilobyte inputs. Crafted-input runs work under a 4 GB memory cap, so a missed bound fails the test instead of the machine.
Two reviews. Every change gets an adversarial review. Once per release, a second, independent model reviews the final security diff. I started that after the v0.14.2 advisory turned out to be incomplete. I use AI tools for this work openly. They are fast at finding the fifth path of a bug class once you've found the first, and they never replace the test that proves it.

What I'd do differently

1. Validate once, at the boundary. Every reader that re-parses the metadata is a reader that can forget a check. One validated descriptor turned "fix it in N places" into "fix it once".

2. Never trust a round trip alone. Reading your own output proves only consistency. Test against the other implementation: h5dump, h5py, the C library's bytes.

3. Unknown means error, not "skip". A filter you don't understand is a reason to stop, not to hand back bytes.

4. Your own old files are part of the format. Users keep what you wrote. Decide what you will read, what you will warn about and what you will write before the strict check ships.

5. A security fix covers a class, not a path. After the first path, look for every other path that sizes memory from file metadata. In #75 there were five.

What's next

Users drive much of this work: the crash, the h5py failure and the metadata API all started as issues from people I'd never met. Thank you, @TuSKan, @kf-domeng and @skyqvn, and @rhaist and @chiliec for merged PRs.

scigolib is meant to be a home for scientific libraries in Go. The longer plan is Go counterparts of the Python libraries people reach for, visualization included. My own main focus is GPU graphics (GoGPU) and ML (Born). So if scientific Go is your thing, I'd be glad of help: issues, PRs, or bringing your own library into scigolib. A co-maintainer for hdf5 would be welcome.

hdf5: github.com/scigolib/hdf5 · pkg.go.dev

go get github.com/scigolib/hdf5@latest

A Shader Loop That Never Ran: What GPU Readback Found in gogpu/naga, a Go WGSL Compiler

Andrey Kolkov — Tue, 03 Nov 2026 17:07:23 +0000

Here's a WGSL loop:

for (var j = 0u; j < 4u; j++) {
    result[j] = j + 1u;
}

Until v0.20.3 in October, naga, our shader compiler written in Go, turned it into DXIL that never ran the loop. Microsoft's validator looked at the module and said it was valid. On an Intel and an NVIDIA GPU the loop body didn't execute once.

The validator wasn't wrong. That's the interesting part.

What the validator saw

This is the DXIL that naga v0.20.2 writes for that loop, trimmed to the lines that matter, with my comments on the right:

  %2 = alloca i32, align 4           ; var j
  br label %3
  ...
  %5 = load i32, i32* %2, align 4    ; read j for "j < 4"
  %6 = icmp ult i32 %5, 4
  br i1 %6, label %11, label %12

The variable j gets memory, and the very first thing the loop does is read it. Nothing ever stored the 0. Reading uninitialized memory is legal in LLVM IR, so every instruction here is well formed, the types match, the control flow is structured. IDxcValidator checks exactly those things and reports VALID (S_OK).

What it doesn't check is whether the module computes what the source says. No static validator does, not DXC's and not spirv-val. They answer "can a driver run this?", and the answer was yes. The driver ran it, j started as whatever was in that memory, and the loop exited before its first iteration.

naga v0.20.3 fixed three bugs of this kind in the DXIL backend:

The shader	What the DXIL did
`for (var j = 0u; j < 4u; j++)`	never stored the initializer; the loop didn't run
`for (var j = i; j < n; j++)`	an optimization pass deleted the initial store, then noticed the loop also writes `j`; the loop started from an uninitialized `j`
`v[i] = v[i] + 1u` on a local vector	a run-time index always picked `v.x`

For this article I compiled all three shaders with v0.20.2 again. All three come back VALID (S_OK).

Our own tests missed them too. We compare naga's text output with Rust naga's and its DXIL with DXC's, and none of that asks what the shader computes. What found them was a one-off experiment: run the shaders on real GPUs through Direct3D 12 and read the buffers back.

What naga is

naga reads WGSL, the WebGPU shading language, and writes SPIR-V for Vulkan, MSL for Metal, GLSL for OpenGL, HLSL for Direct3D, and DXIL for Direct3D 12. The DXIL is emitted directly, without DXC or LLVM. It's plain Go with no CGO, so it cross-compiles like any other Go package.

package main

import (
    "fmt"
    "log"

    "github.com/gogpu/naga/dxil"
    "github.com/gogpu/naga/hlsl"
    "github.com/gogpu/naga/msl"
    "github.com/gogpu/naga/spirv"
    "github.com/gogpu/naga/valid"
    "github.com/gogpu/naga/wgsl"
)

const source = `
@group(0) @binding(0) var<storage, read_write> result: array<u32>;

@compute @workgroup_size(1)
fn main() {
    for (var j = 0u; j < 4u; j++) {
        result[j] = j + 1u;
    }
}
`

func main() {
    module, _, err := wgsl.Parse(source, wgsl.ParseOptions{})
    check(err)
    _, err = valid.Validate(module, valid.Options{})
    check(err)

    spv := must(spirv.Compile(module, spirv.Options{}))   // Vulkan
    metal := must(msl.Compile(module, msl.Options{}))     // Metal
    hlslSrc := must(hlsl.Compile(module, hlsl.Options{})) // Direct3D, through FXC or DXC
    blob := must(dxil.Compile(module, dxil.Options{}))    // Direct3D 12, no DXC needed

    fmt.Printf("SPIR-V %d bytes, MSL %d bytes, HLSL %d bytes, DXIL %d bytes\n",
        len(spv), len(metal), len(hlslSrc), len(blob))
    fmt.Println(metal)
}

// must returns a backend's output and stops on its error.
func must[T, I any](out T, _ I, err error) T {
    check(err)
    return out
}

func check(err error) {
    if err != nil {
        log.Fatal(err)
    }
}

With naga v0.21.2 it prints SPIR-V 1240 bytes, MSL 917 bytes, HLSL 667 bytes, DXIL 2960 bytes, then the Metal source. The zero value of every options struct is the safe choice: bounds checks are on and workgroup memory is zeroed. The SPIR-V, MSL and HLSL writers also give every loop an iteration limit, because a loop the driver's compiler can prove never ends is undefined behavior, and the compiler is then free to delete it, bounds checks included. Two of those show up in the Metal output:

while(true) {
    if (metal::all(loop_bound == uint2(0u))) { break; }
    ...
    result[metal::min(unsigned(_e6), (_buffer_sizes.size0 - 0 - 4) / 4)] = _e8 + 1u;
}

Keep an eye on that metal::min. It's a fix from this month, and it comes back later.

naga takes its IR and much of its design from Rust naga, the shader compiler of Rust wgpu, which is the core of WebGPU in Firefox, Servo and Deno. We run Rust naga's 172-shader WGSL test corpus, compare our output with Rust's wherever Rust writes the same format (SPIR-V only structurally so far), and record every difference with its reason. Rust naga has no DXIL backend, so for DXIL the references are DXC and Mesa. naga's main user is gogpu/wgpu, a WebGPU implementation in Go, which compiles its WGSL shaders with naga in its default pure-Go build.

Running the output instead

After v0.20.3 we turned that experiment into a permanent test corpus: small compute shaders, each paired with the exact values a GPU has to write when it runs them. It lives in testdata/readback and has 55 cases today, mostly loops, function calls and local variables. Each case is a .wgsl file and a .json file:

{
  "format": 1,
  "desc": "for-loop counter declared in the loop header writes 1..4; the sentinel after them stays",
  "entry": "main",
  "workgroups": [1, 1, 1],
  "bindings": [
    {"binding": 0, "kind": "storage-rw", "len": 5, "fill": "0xDEADBEEF",
     "expect": [[1, 2, 3, 4, "fill"]]}
  ]
}

Three habits made the corpus useful:

Sentinels. Every output buffer starts filled with 0xDEADBEEF, and the expected values say where it has to survive. A loop that runs one time too many, or a store through the wrong index, shows up as a missing sentinel.

Inputs from buffers. Most cases read their inputs from a storage buffer, so the compiler can't fold the work away at compile time, and a few, like collatz-lit.wgsl and collatz-rt.wgsl, test the same computation both ways. The WebGPU conformance test suite uses the same trick.

Known failures with a card. A case can list a backend it currently fails on, with the issue that tracks it. The run stays readable while the bug is open, and the entry goes away with the fix.

naga can't drive a GPU itself, so the work is split. naga checks that every case is well formed and compiles on every backend, and runs spirv-val, glslangValidator, dxc and IDxcValidator on the output where they're installed. wgpu runs the corpus on its GPUs before naga releases that touch a backend, with a Go workspace (go.work) pointing at the naga candidate, so a change runs on real hardware before it's tagged. That runner still lives outside the wgpu repository; moving it in is planned, and then anyone can run the corpus on their own GPU.

For v0.21.1 the corpus ran on eight backend and adapter pairs:

Backend	Adapters
Vulkan	Intel Iris Xe, NVIDIA CMP 30HX
Direct3D 12, HLSL through FXC	Intel Iris Xe, NVIDIA GTX 1660 SUPER
Direct3D 12, naga's DXIL	Intel Iris Xe, NVIDIA GTX 1660 SUPER
OpenGL ES	Intel Iris Xe
wgpu's software backend	CPU

There's no Mac in that list. Metal is covered by wgpu's own tests on a macOS CI runner, which is where the third bug below turned up.

What it caught

Local arrays that forgot their initializers. wgpu found this one with a vertex shader that picks its corners from local arrays. The same shape, cut down:

@vertex
fn vs(@builtin(vertex_index) v: u32) -> @builtin(position) vec4f {
    var xs = array<f32, 6>(-1.0, 1.0, -1.0, -1.0, 1.0, 1.0);
    var ys = array<f32, 6>(-1.0, -1.0, 1.0, 1.0, -1.0, 1.0);
    return vec4f(xs[v % 6u], ys[v % 6u], 0.0, 1.0);
}

On naga v0.21.0 the DXIL for this has two alloca instructions and not a single store, so every index reads uninitialized memory, and the validator again says VALID (S_OK). wgpu's shader drew nothing on Intel. The bug was there since at least v0.17.16. Since v0.21.1 naga stores the initializers: 12 stores for this shader, checked on v0.21.2.

A loop-carried variable read as if the loop ran once. naga's DXIL backend turns local variables into SSA values where it can. When every access to a variable sat in one block inside a loop, and that block read the variable before writing it, the pass treated the block as running only once:

var x: u32;
for (var i = 0u; i < n; i++) {
    x += i + 1u;
    dst[i] = x;   // want 1, 3, 6, 10. DXIL wrote 1, 2, 3, 4.
}

Every iteration saw the value from before the loop. This one shipped in every release since v0.17.4. The corpus case for it also checks shapes the old code got right, such as variables read after the loop or updated only in branches, so the fix can't quietly break those.

The v0.21.1 run compared every result with the same run on v0.21.0. 54 of the 55 cases ran on each of the eight pairs (one needs shader-f16, which the runner skipped), 432 results in all. Seven changed, all on DXIL, all from fail to pass:

Backend and adapter	v0.21.0	v0.21.1
Direct3D 12 + naga's DXIL, Intel Iris Xe	50 of 54 pass	54 of 54
Direct3D 12 + naga's DXIL, GTX 1660 SUPER	51 of 54 pass	54 of 54
the other six pairs	unchanged	unchanged

Not everything in that run was green, and both versions failed the same cases: two workgroup-memory cases on the CMP 30HX under Vulkan (not diagnosed yet; Intel passes them), one known OpenGL ES failure, and 15 of the 54 in wgpu's software backend (11 failures, 4 already known). For a release gate that's the point: nothing got worse.

An out-of-bounds write on Metal. wgpu has hand-written readback tests too. One of them, TestStorageBufferOutOfBoundsContained, writes past the end of a storage binding and then checks that the binding next to it is untouched. WGSL allows an implementation to clamp such an access, and wgpu's Metal backend asks naga to clamp every index into a buffer.

On the macOS CI runner the test failed. For a plain var<storage> a: array<u32>, naga's MSL used the index as it was, and the write landed in the next binding. Only a runtime-sized array at the end of a struct got clamped. v0.21.2 clamps every index into a runtime-sized array; that's the metal::min from the output above. The unclamped MSL was perfectly valid MSL.

When Rust naga and the spec disagree

While fixing the Metal bug I noticed that our bound was computed from the array's stride and Rust naga's from the element's size. I switched to Rust's form and called ours a defect.

It wasn't. WGSL defines how many elements a runtime-sized array has, and calls it NRuntime: the buffer binding's size minus the array's offset, divided by the stride, rounded down. arrayLength must return exactly that.

The two forms differ when an element is smaller than its stride and the binding ends partway through the last stride. Take array<vec3<f32>>: each element is 12 bytes and the stride is 16. On a 28-byte binding the spec says there is truncate(28 / 16) = 1 element. Rust naga's MSL computes 1 + (28 - 12) / 16 = 2, because a second vec3 would fit in bytes 16 to 27. That's true about memory and wrong about WGSL.

The correction came from the wgpu side, and wgpu's vec3 test now pins it: its comment quotes the spec's NRuntime and requires arrayLength to follow it. v0.21.2 uses the spec's count for both the clamp and arrayLength, which is what naga's HLSL, DXIL, GLSL and SPIR-V output already did. On the macOS CI runner, a 28-byte array<vec3<u32>> binding now reads arrayLength back as 1 (run result). The difference from Rust is written down in the code, in the tests that pin the bound, and in the CHANGELOG.

So this is how we decide now. Where the spec defines a value or an error, the spec decides. Rust naga decides what the spec leaves open, like the shape of the IR or the wording of an error message. When we differ from Rust, we assume the bug is ours until we've read the spec. After that it might be theirs.

What I'd do differently

Run the output from the first day of a backend. We had validators, golden files and Rust parity long before we had a GPU in the loop. All three check that the output looks right. Only running it checks that it is right.

Read a green validator as "legal", not "correct". It's a gate worth having, and it says nothing about values.

Make the expected values hard to fake. Sentinels in every slot that shouldn't change, inputs from buffers, and several shapes per bug, including the ones the old code already handled.

What's next

DXIL is opt-in in wgpu (GOGPU_DX12_DXIL=1). The default Direct3D 12 path is HLSL through FXC, so DX12 users on that path were never affected by the DXIL bugs above.

Before we call DXIL stable, the shaders of gg, our 2D graphics library, have to pass the validator, readback has to be green on Intel and NVIDIA, and no silent bug may be known. Two are known and open right now:

more shapes of the local-initializer bug: indexed vectors, arrays of arrays, zero-initialized arrays of vectors, and struct or array variables of a helper function called inside a loop;
primitive_index reads wrong in fragment shaders on Intel, probably because the DXIL doesn't mark fragment system values as non-interpolated.

If naga compiles one of your shaders wrong, the corpus format is documented. A WGSL file plus the values it should produce is the most useful bug report we can get.

naga: github.com/gogpu/naga · pkg.go.dev

The Go gopher was designed by Renée French and is licensed under CC BY 4.0.

go get github.com/gogpu/naga@v0.21.2
go install github.com/gogpu/naga/cmd/nagac@latest
nagac -o shader.spv shader.wgsl

Go regexp too slow? I built coregex, a drop-in replacement. An audit found 16 bugs — here's what broke

Andrey Kolkov — Fri, 09 Oct 2026 08:25:58 +0000

Six months ago I published "Go's Regexp is Slow. So I Built My Own". The project grew, got contributors, beat Rust on several patterns. Tested on Go 1.27, go.mod requires 1.27+.

Then I commissioned an independent code review — a full differential fuzz against stdlib plus manual audit of the engine internals.

6% of random pattern/input pairs gave wrong answers.

Not edge cases. Not theoretical. (?i)привет didn't match "привет" — its own literal. \pL+ on a 50KB file returned no matches while MatchString returned true. A 15-character pattern OOM'd the process at compile time.

This is the story of what broke, why 65,000 lines of tests missed it, and what it took to fix.

The bug that would have broken every HTTP router

Issue #166 from @vmihailenco — sat open for six weeks because I missed the notification buried in email noise, and only caught it reviewing the repo:

coregex.MustCompile(`^x(a|bc)`).MatchString("xbc") // false

That's a false on a pattern that obviously matches. When I dug in, it wasn't one bug — it was an entire strategy producing wrong answers:

^x(a|bc)              "xbc"        → false   (prefix ignored)
^HTTP/(1\.0|1\.1|2)   "HTTP/2"     → false   (every HTTP version check)
^/api/(users|posts)   "/api/users" → false   (every API router)
^(GET|POST) /         "GET x"      → true    (false positive!)

The BranchDispatch optimization dispatched by first byte, then verified the match with a simple matcher that couldn't handle real AST shapes. It was a mini-engine — one that said "yes" without being a real engine.

Lesson: An optimization that answers "yes" independently must be a full engine. Otherwise it's a bug generator. Safe optimizations only say "no" quickly (prefilters, first-byte reject) and delegate "yes" to the real engine. Rust regex doesn't need branch dispatch — the lazy DFA transition table already is a dispatch table at every state.

Solution: deleted the entire strategy. -1077 lines. Anchored alternations now go through BoundedBacktracker with O(1) first-byte reject. 13 ns → 66 ns on short strings — still 1.5× faster than stdlib. The speed gap is a known issue; once the capture path is fixed (#177), anchored one-pass patterns can route through it.

Case-insensitive Cyrillic didn't match its own literal

The NFA compiler had this:

if foldCase && isASCIILetter(r) {
    // create alternation: upper + lower
}

Non-ASCII runes with case-insensitive flag were compiled as exact uppercase match. syntax.Parse uppercases Cyrillic (к → К), so the NFA only matched К, never к.

But here's the weird part: (?i)кот (3 Cyrillic runes) worked fine. (?i)привет (6 runes) didn't. Same code path — how?

Two different engines, one hiding the bug. For 2-4 rune patterns, the cross-product of case variants fit within the Teddy prefilter's literal limit. Teddy matched all variants by exact bytes, bypassing the broken NFA entirely. For 1 rune and 5+ runes, the cross-product exceeded the limit → fell back to NFA → bug.

The test suite had (?i)кот — green. The real-world (?i)привет — broken. A test that passes on a specific length doesn't test the code path you think it tests.

Fix: unicode.SimpleFold orbit for every rune, compiled as a split tree:

func foldOrbit(r rune) []rune {
    orbit := []rune{r}
    for f := unicode.SimpleFold(r); f != r; f = unicode.SimpleFold(f) {
        orbit = append(orbit, f)
    }
    return orbit
}
// Σ → [Σ, σ, ς]  (Greek sigma, three forms)
// K → [K, k, K]  (ASCII K, ASCII k, Kelvin sign)

Silent wrong results on large input

\pL+ (match Unicode letters) on a 50KB file: MatchString returned true, but FindAllStringIndex returned zero or one match instead of thousands.

Root cause: \pL compiles to 5842 NFA states (stdlib uses 3 instructions). On input over ~10KB, the BoundedBacktracker's visited table overflows and falls back to bidirectional DFA search. The forward DFA found the match end correctly, but the reverse DFA overflowed too — and its fallback ran the reverse NFA's PikeVM forward on forward data. Reverse NFA expects reversed UTF-8 byte sequences; running it forward produces no matches.

Fix: when the reverse DFA fails, fall back to the forward PikeVM's SearchBetween instead. Correct on all input sizes now.

The cost: \pL+ on large inputs uses PikeVM fallback at ~50 μs/byte (8.4s on 120KB vs stdlib's 9ms). Correct, but impractical. The real fix is DFA cache clear-and-continue (as Rust does) plus compact UTF-8 range-trie compilation for Unicode classes. Both are tracked.

Empty matches that produced invalid UTF-8

re := coregex.MustCompile(`a*`)
result := re.ReplaceAllString("日", "-")
// Expected: "-日-"
// Got: invalid UTF-8 — rune sliced at byte boundaries

After an empty match, the position advanced by one byte instead of one rune. "日" is 3 bytes (E6 97 A5), so instead of two empty matches (before and after the rune), we got four — one at each byte boundary, slicing the rune apart.

26 call sites across 9 functions. One helper fixed them all:

func advanceAfterEmpty(b []byte, pos int) int {
    if pos < len(b) {
        _, w := utf8.DecodeRune(b[pos:])
        return pos + w
    }
    return pos + 1
}

The 15-character DoS

coregex.Compile(`.(?:ac*d|ac)xy*`)
// 15 characters → >3 GB heap, >15 seconds, OOM kill
// stdlib: ~7 μs

cloneRegexp in the literal extractor cloned both Sub and Sub0 arrays. In syntax.Regexp, Sub usually aliases Sub0[:1] — so every node with one child got cloned twice. Size grew as 2^depth.

Fix: delete the Sub0 loop. One loop removed, compile time back to microseconds.

For a library that claims "no ReDoS" — any service compiling user-supplied patterns was vulnerable to a 15-character denial of service.

What the fuzz found (and didn't)

The test suite had hasUTF8CodepointDifference — a whitelist function that skipped exactly the patterns where bugs lived. The fuzz harness compared each API against stdlib but filtered out multibyte input. We were testing the correct code paths and skipping the broken ones.

After fixes, differential fuzz against stdlib: 6.0% → 0.75% divergence on random pattern/input pairs. The remaining 0.75% decomposes into three classes, each with its own issue:

Class	Example	Issue
Negated classes match bytes	`\S{2}` on `"К"` → false positive	#174
Lazy quantifiers = greedy	`\d+?` on `"11"` → `[0 2]`	#175
Leftmost priority divergence	`FindAllIndex` ≠ `FindAllSubmatchIndex`	#176

The benchmarks after fixes

All 16 bugs from the audit are fixed; three pre-existing classes are tracked in #178. No benchmark regressions — verified on AMD EPYC via regex-bench CI (Go stdlib, coregex, and Rust regex on identical 6 MB workloads):

Pattern	vs stdlib	vs Rust
`.keyword.` (inner literal)	527×	27× faster
`.*\.txt` (suffix)	143×	7.3× faster
IPv4 octet alternation	236×	5.6× faster
`[\w]+` (char class)	11×	1.2× faster
`(?m)^/.*\.php` (multiline)	154×	~same

What I'd do differently

1. Fuzz first, optimize second. I had 65K lines of tests. A ~150-line differential harness found most of the bugs — random pattern × random input × compare with stdlib. Should have been day one.

2. Never whitelist what you can't explain. hasUTF8CodepointDifference was a flag that said "we know this is different." It should have been a bug count that said "we have N bugs to fix."

3. Optimizations that say "yes" are engines. Prefilters, rejectors, first-byte checks — they say "no" quickly. Safe. The moment your optimization says "yes, this matches" without delegating to the real engine, you've built a second engine with half the test coverage.

4. Real users find real bugs. vmihailenco's one-line repro exposed a class of bugs that 65K lines of tests missed. Every regex library should have a "give me your pattern, I'll diff it against stdlib" command.

What's next

Three correctness classes to close before v1.0 (#178). FindSubmatch is 3-10× slower than stdlib with 6-9 allocations per call — that's the primary API for log parsing and the most user-visible gap.

The strategy architecture is sound; the bugs were in the NFA compiler's Unicode handling and in shortcuts around the engines.

Contributions welcome. Especially on negated character classes — it's the biggest remaining divergence from stdlib, and the fix follows a pattern we've already applied for ..

coregex: github.com/coregx/coregex

go get github.com/coregx/coregex@v0.12.27

import regexp "github.com/coregx/coregex"

re := regexp.MustCompile(`(?i)привет`)
re.MatchString("Привет") // true (fixed in v0.12.26)

Go 1.27 HTTP Router with Generic Methods and Zero-Alloc Routing: FURSY — What an Independent Audit Found at 94% Coverage

Andrey Kolkov — Thu, 08 Oct 2026 01:01:54 +0000

We shipped FURSY v0.5.4 thinking it was production-ready. Ninety-four percent test coverage. Thirty-five findings from our internal audit, all fixed. Twelve CI checks across three operating systems. Zero-alloc routing under 100 ns/op.

Then we handed the codebase to an independent auditor. They found the CORS middleware echoing back unfiltered headers to browsers. The SECURITY.md teaching six APIs that don't exist. Error responses claiming RFC 9457 compliance while returning text/plain. A path parser that panics on Google's most widely used REST convention.

This is the story of what went wrong, how we fixed it, and what fursy actually is after the cleanup.

What Is Fursy

FURSY (Fast Universal Routing SYstem) is an HTTP router for Go 1.27+ with three properties that don't usually come together:

Generic methods on the router -- router.POST("/users", handler) where handler receives a typed *Box[CreateReq, UserRes]. Go 1.27 enabled this; to our knowledge, FURSY is the first Go router to ship generic methods on the router type.
Zero-allocation routing -- sub-100 ns/op for static routes, 0 B/op, 0 allocs/op. The radix tree reuses a caller-provided param buffer from sync.Pool.
RFC 9457 Problem Details as the default -- every auto-generated error (404, 405, 401, 429, 500) returns application/problem+json. Not opt-in. Not "if you use our error type." Every response.

We built it as the successor to ozzo-routing, Qiang Xue's router from the Yii framework ecosystem. When Xue handed over the go-ozzo organization in mid-2026, FURSY was already running in our internal services.

The Generic Methods Story

Before Go 1.27, if you wanted type-safe handlers in Go, your options were ugly:

// Package-level functions -- verbose, no type inference
fursy.POST[CreateUserReq, UserRes](router, "/users", handler)

// Or abandon type safety -- manual binding, no compile-time guarantees
router.Handle("POST", "/users", func(c *Context) error {
    var req CreateUserReq
    // manual JSON decode, manual validation, manual error handling...
})

Go 1.27 allows methods on concrete types to declare their own type parameters. This changes everything:

router.POST("/users", func(c *fursy.Box[CreateUserReq, UserRes]) error {
    // c.ReqBody is *CreateUserReq -- already validated, already bound
    user := createUser(c.ReqBody)
    return c.Created("/users/"+user.ID, UserRes{ID: user.ID, Name: user.Name})
})

No explicit type parameters at the call site. The compiler infers [CreateUserReq, UserRes] from the handler signature. Binding happens automatically before your handler runs -- if the JSON is malformed, the client gets a 400 before your code executes.

This sounds minor until you have 200 endpoints. The reduction in ceremony is significant.

What the Audit Found: CORS Was Echoing Everything

The most dangerous finding was in the CORS middleware. When a browser sends a preflight OPTIONS request, it includes Access-Control-Request-Headers listing which headers the JavaScript wants to use. The server should respond with only the headers it actually allows.

Our code:

// cors.go -- BEFORE the fix
func (cfg *CORSConfig) setPreflightHeaders(origin, method, reqHeaders string, headers http.Header) {
    allowed, allowedHeaders := cfg.isPreflightAllowed(origin, method, reqHeaders)
    if !allowed {
        return
    }
    // ...
    if allowedHeaders != "" {
        headers.Set("Access-Control-Allow-Headers", reqHeaders)  // BUG
    }
}

See it? isPreflightAllowed returns allowedHeaders (the filtered list), but line 225 writes reqHeaders (the raw request value). The browser sends Content-Type, X-Evil-Header, we configured the server to only allow Content-Type, and the response says "sure, X-Evil-Header is fine too."

The fix was one word:

headers.Set("Access-Control-Allow-Headers", allowedHeaders)  // FIXED

One word. Ninety-four percent test coverage didn't catch it because every test requested only headers that were in the allowlist. The regression test we added:

func TestCORS_PreflightFilteredHeaders(t *testing.T) {
    r := fursy.New()
    r.Use(CORSWithConfig(CORSConfig{
        AllowOrigins: "https://example.com",
        AllowMethods: "GET,POST",
        AllowHeaders: "Content-Type,Authorization",
    }))
    // ... setup ...

    req := httptest.NewRequest("OPTIONS", "/api", http.NoBody)
    req.Header.Set("Access-Control-Request-Headers", "Content-Type, X-Evil-Header")
    // ...

    got := w.Header().Get("Access-Control-Allow-Headers")
    if strings.Contains(got, "X-Evil-Header") {
        t.Errorf("preflight echoed disallowed header: got %q", got)
    }
}

Lesson: test the negative case. Every CORS test we had sent only valid headers.

The Documentation Was Lying

The auditor checked whether our docs matched the actual API. They didn't.

Document said	Reality
`router.Run(":8080")`	Method doesn't exist. Never did.
`fursy.CSRF(fursy.CSRFConfig{...})`	No CSRF middleware
`fursy.Timeout(30 * time.Second)`	Doesn't exist
`fursy.BodyLimit(10 * 1024 * 1024)`	Doesn't exist. Body limit is `router.SetMaxBodySize()`
`fursy.HTTPSRedirect()`	Doesn't exist
`fursy.RateLimit(100, time.Minute)`	Actual signature: `middleware.RateLimit(float64, int)`. This wouldn't even compile.
`import "encoding/json/v2"`	Code uses `encoding/json`. Go 1.27 made v2 the default behind this import.
SECURITY.md: supported versions 0.1.x, 0.2.x	Current version: 0.5.4

Six non-existent APIs documented as if they were real. An LLM coding assistant reading our llms.txt would confidently generate code that doesn't compile. A developer copying from SECURITY.md would get build errors.

How did this happen? The docs were written during the design phase and never reconciled with what was actually implemented. Classic drift -- the code evolves, the prose doesn't.

We cleaned out the worst offenders. Full documentation parity is still in progress -- doc drift is a hydra, and every time we grep for one stale reference, two more surface. The rule going forward: if the API doesn't exist in the source tree, it doesn't exist in the docs.

RFC 9457: Claiming It vs. Being It

Fursy's README said "Native RFC 9457 Problem Details." The auditor checked what GET /nonexistent actually returned:

HTTP/1.1 404 Not Found
Content-Type: text/plain; charset=utf-8

Not Found

Plain text. Not JSON. Not RFC 9457. The "native" Problem Details only activated when a handler explicitly returned a fursy.Problem. Every auto-generated error -- 404, 405, 413, 415, 400, 500, and all middleware rejections -- was text/plain.

We fixed this across all paths:

// BEFORE -- text/plain
terminalHandler = func(ctx *Context) error {
    return ctx.String(http.StatusNotFound, "Not Found")
}

// AFTER -- RFC 9457
terminalHandler = func(ctx *Context) error {
    return ctx.Problem(NewProblem(http.StatusNotFound, "Not Found", ""))
}

Same change in JWT (401), BasicAuth (401), RateLimit (429), CircuitBreaker (503), Recovery (500). Every error response is now:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404
}

With Content-Type: application/problem+json. This is a breaking change -- clients parsing text/plain error bodies will break. We shipped it in v0.6.0 because the project is pre-1.0 and the previous behavior was a lie.

The Colon That Broke Google's API Convention

A developer migrating from ozzo-routing reported that route registration panics:

router.GET("/clients:getOrganization/:id", handler1)
router.GET("/clients:getAddress/:id", handler2)
// panic: conflicting wildcard names: getOrganization vs getAddress

The : in clients:getOrganization was being parsed as a wildcard param marker. But this is a Google AIP-136 custom method -- the most widely adopted enterprise REST convention for non-CRUD operations. Google Firestore alone has 20+ endpoints using this pattern: /documents:commit, /documents:batchGet, /documents:rollback.

RFC 3986 Section 3.3 lists : as a legal path character. It doesn't need escaping. The :param convention is a Sinatra invention from 2007, not an RFC.

The fix: colons are wildcards only at segment start (after / or position 0):

// BEFORE
func findWildcardIndex(path string) int {
    for i := 0; i < len(path); i++ {
        if path[i] == ':' || path[i] == '*' {
            return i  // any position
        }
    }
    return -1
}

// AFTER
func findWildcardIndex(path string) int {
    for i := 0; i < len(path); i++ {
        if (path[i] == ':' || path[i] == '*') && (i == 0 || path[i-1] == '/') {
            return i  // segment start only
        }
    }
    return -1
}

For context: Gin fixed this in v1.11.0 after six years of open issues. Echo needed three separate PRs. httprouter never fixed it. Express.js has had it open since 2019.

Form Binding Errors: 500 Instead of 400

Submitting age=abc where age is an int field returned 500 Internal Server Error. The strconv parse error wasn't wrapped in our DecodeError type, so the error handler fell through to the catch-all:

// BEFORE -- raw error, caught by nothing
if err := setField(field, values[0]); err != nil {
    return fmt.Errorf("set field %s error: %w", structField.Name, err)
}

// AFTER -- wrapped, caught as 400
if err := setField(field, values[0]); err != nil {
    return &DecodeError{Err: fmt.Errorf("field %s: %w", structField.Name, err)}
}

A user sending ?age=abc now gets 400 Bad Request with a Problem Details body explaining which field failed. Not a 500 that makes your monitoring think the server is crashing.

This fix covers setField type mismatches. Errors from ParseForm/ParseMultipartForm itself (malformed percent-encoding, corrupt multipart boundaries) were also wrapped in v0.6.2.

What Fursy Doesn't Do

No ORM -- use Relica or GORM or raw database/sql
No migrations -- use goose or atlas
No template rendering -- this is an API router, not a web framework
No WebSocket/SSE built-in -- SSE works via the stream plugin; WebSocket upgrade requires the base responseWriter (no middleware wrappers in the chain) until stream adopts http.NewResponseController
No process management -- use daemon if you need it
No CSRF middleware -- we removed the docs that claimed it existed. If you need CSRF, use gorilla/csrf or write your own. We'll add it when we have a design we're confident in, not before.

Fursy vs. Other Go Routers (2026)

Router	Go Version	Type Safety	Allocs/op	Error Format	Colon Literal	Dependencies
Go 1.22+ stdlib	1.22+	`{param}` only	~3	text/plain	Yes (`{param}`)	0
chi v5	1.22+	`{param}` only	~2	text/plain	Yes (`{param}`)	0
Gin	1.18+	No generics	0	custom JSON	Yes (v1.11+)	8
Echo	1.18+	No generics	1	custom JSON	Yes (escaped)	4
Fiber	1.21+	No generics	0	text/plain	No	fasthttp
fursy	1.27+	Generic methods	0 (plain) / 2 (generic)	RFC 9457	Yes (v0.6.2)	2 (JWT, rate)

Fursy requires Go 1.27. That's a hard requirement. If you're on 1.22 or earlier, use chi or the stdlib mux. If you want zero dependencies, use the stdlib. If you need the fastest raw throughput, Fiber on fasthttp wins.

Fursy is for teams that want type-safe handlers, zero-alloc routing, and RFC-compliant error responses in a single package, and can target Go 1.27+.

Numbers

Metric	Value
Core library	~8,200 lines
Test code	~16,000 lines (2:1 ratio)
Test functions	510+ (core + plugins)
Benchmarks	21
Coverage	93.8% core, 96.5% middleware
Static route lookup	<100 ns/op, 0 alloc
Parametric route lookup	<140 ns/op, 0 alloc
Production dependencies	2 (golang-jwt, x/time)
Plugin dependencies	Isolated per plugin
CI checks	12 (3 OS, lint, format, vuln, 4 plugins, examples, codecov)
External audit findings	45 claims checked, 33 confirmed, all fixed in v0.6.0-v0.6.2

Gotchas

router.GET Is a Generic Method Now

After v0.5.0, router.GET expects Handler[Req, Res] (a function taking *Box[Req, Res]), not HandlerFunc (taking *Context). For plain handlers without type-safe binding:

// This does NOT compile:
router.GET("/health", func(c *fursy.Context) error { ... })

// Use Handle for plain handlers:
router.Handle("GET", "/health", func(c *fursy.Context) error { ... })

// Or use the generic form with Empty types:
router.GET("/health", func(c *fursy.Box[fursy.Empty, fursy.Empty]) error { ... })

Plugins Have Their Own go.mod

Each plugin (plugins/opentelemetry, plugins/database, plugins/stream, plugins/validator) is a separate Go module. When upgrading fursy, update the plugin's go.mod too:

cd plugins/stream
go get github.com/coregx/fursy@v0.6.2
go mod tidy

CORS Must Be Global

CORS middleware must be registered at the router level (router.Use()), not on a group. Preflight OPTIONS requests hit the global middleware chain before route matching. Group-level CORS will miss them. This matches Gin, Echo, and Chi behavior.

The Second Pass

The first audit found the CORS echo, the phantom docs, and the text/plain lie. We fixed those in v0.6.0. Then we sent the fix branch back for re-validation. The second pass found 11 more: an open redirect in the trailing-slash handler, WebSocket hijack broken by our own response wrapper, the circuit breaker counting 404s as backend failures, and the OpenAPI generator not knowing about the colon fix it shipped alongside. All fixed in v0.6.2.

The pattern is humbling: every fix creates a surface for the next bug. The CORS allowlist fix shipped next to a default that had been blocking JSON POST preflights all along -- no test ever sent one. The colon fix in the radix tree didn't propagate to the OpenAPI converter. The response wrapper that tracked written didn't implement Hijack. Ninety-four percent coverage catches syntax, not semantics.

Try It

go get github.com/coregx/fursy@v0.6.2

The project is at v0.6.2. The API is not frozen -- we're pre-1.0 and will break things when the design demands it. The llms.txt documents every API pattern for both developers and AI coding assistants.

coregx/fursy -- Type-safe HTTP router for Go 1.27+. RFC 9457 errors. Zero-alloc routing. MIT license.

Go SQL Query Builder Without Dependencies: Relica, the ozzo-dbx Successor — What Broke on PostgreSQL and SQLite

Andrey Kolkov — Sat, 03 Oct 2026 09:05:52 +0000

Relica is a zero-dependency SQL query builder for Go (PostgreSQL, MySQL, SQLite), the successor to ozzo-dbx. I wrote it from scratch, keeping the API design of ozzo-dbx — the query builder by Qiang Xue, creator of Yii framework. Qiang hadn't maintained it for years, and when he handed me the go-ozzo organization in mid-2026, Relica was already in production.

We run Relica in production across multiple services on PostgreSQL, MySQL and SQLite, and an external code auditor recently found six critical bugs in one session. This article is about those bugs, how they got there, and the patterns that prevent them.

The Bug That Would Have Woken Me at 3 AM

An external auditor ran our codebase on Go 1.27.1 (we support 1.25+) with the race detector and custom reproducing tests. One finding hit hard: One() was checking rows.Next() and returning ErrNotFound without ever calling rows.Err().

What this means in production: when PostgreSQL drops a connection mid-query — context cancellation, network blip, anything — rows.Next() returns false, and you get "not found" instead of "database unreachable." Your monitoring shows a spike in 404s. Your dashboards look fine. Users intermittently can't find their own profiles.

// Before v0.17.2 (broken):
if !rows.Next() {
    return ErrNotFound  // masks real errors!
}

// After v0.17.2:
if !rows.Next() {
    if rowErr := rows.Err(); rowErr != nil {
        return rowErr  // context.Canceled, connection reset, etc.
    }
    return ErrNotFound  // genuinely no rows
}

The fix was three lines. The lesson: ErrNotFound is a business outcome, not an infrastructure failure. Test for it explicitly in your handlers:

var user User
user.ID = requestedID
err := db.Select().Model(&user)

switch {
case errors.Is(err, relica.ErrNotFound):
    return nil, ErrUserNotFound
case err != nil:
    return nil, fmt.Errorf("fetch user: %w", err) // real DB error
}

PostgreSQL `$N` Placeholder Collision in Subqueries (`bind message supplies N parameters`)

If you've ever seen bind message supplies 3 parameters, but prepared statement requires 2 on PostgreSQL — this might be why.

Before v0.17.2, Relica built SQL in multiple passes. Each subquery numbered its own placeholders from $1. When a subquery was embedded inside an outer query, the numbers collided:

-- What Relica generated (broken):
WHERE active = $1 AND "id" IN (SELECT "user_id" FROM "orders" WHERE status = $1 AND total > $2)
-- args: [true, "done", 100]
-- $1 used for both 'true' and 'done'!

-- What it should be:
WHERE active = $1 AND "id" IN (SELECT "user_id" FROM "orders" WHERE status = $2 AND total > $3)

The fix required rearchitecting the builder. We split buildSQL into two methods: renderSQL assembles the entire query with ? placeholders, then buildSQL does a single replacePlaceholders pass to number them sequentially. One lexer, one pass, no collisions.

The same fix caught two more bugs we hadn't noticed: GroupByExpr and OrderByExpr with parameters weren't being renumbered on PostgreSQL at all — the ? stayed in the output SQL verbatim.

Squirrel hit the same bug class in 2019 (#203) — closed with a workaround. The maintainer called it a design issue that can't be fixed without breaking compatibility. Our renderSQL approach solves it cleanly.

Statement Cache: The Race Nobody Tested

Our statement cache used Get() and Set() — standard LRU. Two goroutines prepare the same query simultaneously:

Goroutine A: Get("SELECT...") → miss
Goroutine B: Get("SELECT...") → miss (A hasn't Set yet)
A: Prepare() → stmt1, Set("SELECT...", stmt1)
B: Prepare() → stmt2, Set("SELECT...", stmt2) → closes stmt1
A: stmt1.Query() → sql: statement is closed

The auditor reproduced this under concurrent load — hundreds of sql: statement is closed errors on cold start. The fix: GetOrSet() — an atomic cache-or-insert. The loser of the race closes its own statement (which nobody else has seen) and uses the cached one.

cached, inserted := cache.GetOrSet(sql, stmt)
if !inserted {
    _ = stmt.Close() // lost the race — ours is unobserved
    return cached, nil
}
return stmt, nil

Patterns That Actually Work

Model() for CRUD, Builder for Everything Else

The first version of Relica only had the fluent builder — that's what ozzo-dbx had. After months of production use, I added Model() for the most common case:

// Quick PK lookup — one line
var user User
db.Model(&user).Find(42)

// Need column selection or filters — full builder chain
user = User{ID: 42}
db.Select("name", "email").
    Where(relica.IsNull("deleted_at")).
    Model(&user)

Model() reads the primary key from struct fields, figures out the table name, and scans the result. The builder is for everything else.

Expression API Over String Conditions

// Portable across PostgreSQL, MySQL, SQLite:
query = query.Where(relica.Eq("status", filter.Status))
query = query.Where(relica.GreaterOrEqual("age", filter.MinAge))
query = query.Where(relica.IsNull("deleted_at"))

// Instead of:
query = query.Where("status = ?", filter.Status)  // works, but less explicit

The Expression API handles identifier quoting and placeholder numbering internally. It also catches more errors at build time — Eq("status", nil) generates IS NULL, not a broken = NULL.

ForUpdate Inside Transactions

err := db.Transactional(ctx, func(tx *relica.Tx) error {
    var account Account
    account.ID = accountID
    err := tx.Select().ForUpdate().Model(&account)
    if err != nil {
        return err
    }
    if account.Balance < amount {
        return ErrInsufficientFunds
    }
    account.Balance -= amount
    return tx.Model(&account).Update("balance")
})

ForUpdate() outside a transaction is pointless — the lock releases immediately. On SQLite, it's silently ignored because SQLite uses database-level locking. Your code stays portable.

QueryHook for Everything Observable

db, _ := relica.Open("postgres", dsn,
    relica.WithQueryHook(func(ctx context.Context, e relica.QueryEvent) {
        queryDuration.WithLabelValues(e.Operation).Observe(e.Duration.Seconds())
        if e.Duration > 100*time.Millisecond {
            slog.WarnContext(ctx, "slow query",
                "sql", e.SQL, "duration_ms", e.Duration.Milliseconds())
        }
    }),
)

One hook replaced our logger, metrics middleware, and slow-query detector. Zero overhead when not configured — it's a nil check.

Subqueries Need .AsExpression()

The public *SelectQuery doesn't implement Expression directly. This compiles but treats the query object as a bind parameter value:

// Wrong — compiles, generates garbage SQL:
db.Select().From("users").Where(relica.In("id", sub)).All(&users)

// Correct:
db.Select().From("users").Where(relica.In("id", sub.AsExpression())).All(&users)

Same for Exists(). The .AsExpression() call is the explicit conversion from query object to SQL fragment.

What We Didn't Build

Migrations. Use goose or atlas.
Relations / eager loading. Write JOINs explicitly — that's the point of a query builder.
Compile-time type safety. If you want that, sqlc or jet are better tools.
Schema management. We build queries, not manage databases.

Relica vs Squirrel vs sqlx vs GORM vs sqlc (2026)

If you're choosing between Go SQL libraries in 2026:

Tool	Style	When to pick it
go-jet	Code generation	Large schemas, compile-time type safety, IDE autocompletion
sqlc	Code generation	Static queries only, strongest type guarantees
goqu	Fluent builder	Mature, battle-tested, complex dynamic filters
sq	Generics/callback	Zero-reflection scanning, generics-first API
GORM	Full ORM	Relations, migrations, hooks — if you want the full stack
Relica	Fluent + Model API	Zero deps, transparent SQL, built-in LRU cache, Stripe-like IDs
Squirrel	Fluent builder	Maintenance mode since 2024. Known subquery placeholder limitation (#203)
sqlx	Scanning layer	Last release v1.4.0 (2024). A community fork exists

If you need compile-time typed SQL — go-jet or sqlc are better tools. If you want a fluent builder without external deps that shows you exactly what SQL it generates — that's Relica.

Numbers


Library code	14,101 lines
Test code	37,902 lines (2.7:1 ratio)
Test functions	1,136
Coverage	85%+
Production dependencies	0
CI	Unit: Linux, macOS, Windows. Integration: PostgreSQL, MySQL, SQLite
Releases	37
External audit bugs found	6 (all fixed in v0.17.2)

The Gotchas

Always implement TableName(). Default inference adds s and lowercases — Category → categorys, not categories. I'm not a fan of plural table names, and even if you are, naive pluralization won't work:

func (Category) TableName() string { return "category" }

Select("n.*") was broken until v0.17.1. The wildcard was quoted as "n"."*" — valid identifier syntax, invalid wildcard. If you're on an older version, use explicit column names.

Zero-dependency means zero-dependency. go.mod has no require block. Test and benchmark modules are separate. I've had people not believe this until they check.

Relica is at v0.17.3. The AGENTS.md has every API pattern — it's written for both humans and AI coding assistants.

Found a bug? Open an issue. Have a pattern that works well? Tell us in discussions.

Go Daemon for MCP Servers: Shared Background Processes Without systemd or Other Supervisors

Andrey Kolkov — Wed, 23 Sep 2026 18:28:10 +0000

My team builds GoGPU — a pure-Go GPU ecosystem (1.25M+ LOC, 21 repositories) gogpu/ui — a GPU-accelerated UI framework, and Born ML — a machine learning framework on top of it. Working on codebases this size with AI agents requires serious tooling: you can't just grep and hope. So we built GLIDE — a headless Go IDE written in Go, with 65 MCP tools, a knowledge graph, and full gopls integration, designed to give AI coding agents — Claude Code, Cursor, Copilot — semantic understanding of Go code. It's an internal tool we're preparing for open source, still in progress.

Here's where it gets expensive. GLIDE runs as an MCP server, and each AI agent spawns its own instance. Each instance starts a gopls language server. gopls eats about 1–2 GB of RAM per workspace. Run six agents on GoGPU — congrats, you just burned 12 GB on identical type-checking of the same modules.

The obvious fix: share one gopls across all agents. Run GLIDE as a background daemon, let agents connect on demand.

The non-obvious part: making that daemon reliable on three operating systems, under concurrent access from processes that die without warning, without adding a single dependency to the binary.

This is the story of grpmsoft/daemon — a pure-Go library for on-demand background process lifecycle. We extracted it from GLIDE because the problem is universal: any CLI tool that needs a shared background server faces the same dance of PID files, health checks, and process identity. No CGO, no vendored C, no x/sys. Stdlib only.

The Problem Is Not "How to Fork"

Go can't fork(). The runtime has threads, and forking a multi-threaded process is asking for deadlocks. The typical workaround is re-executing the binary with an environment variable marker. sevlyar/go-daemon does exactly this. kardianos/service takes a different approach — it wraps your binary to run under a system service manager (systemd, launchd, Windows SCM) and can install unit files via an explicit Install() call.

Neither solves our problem. We don't want a system service that lives forever. We want a process that:

Starts when the first agent needs it.
Shares itself with every subsequent agent.
Dies when the last agent leaves.

The owner of the process lifetime is demand, not an init system.

EnsureRunning: The Core Abstraction

The entire library exists so you can write this:

port, err := daemon.EnsureRunning(ctx, daemon.Config{
    Name:    "myapp",
    DataDir: ".myapp",
    Args:    []string{"serve"},
})

If the daemon is already running, you get the port. If not, the library spawns it, waits for the health check, and gives you the port. If two agents call EnsureRunning at the exact same millisecond, one wins the startup race and the other gets the same port. No duplicate daemons. Ever.

The trick is a startup lock file — flock on Unix, LockFileEx on Windows — that serializes all startup attempts across processes. The winner spawns the child, passes the PID file lock via ExtraFiles (so the child inherits ownership with zero gap), and the loser polls until the PID file contains a port.

This required more thought than I expected.

The PID File Is the Lock

Most daemon libraries use the PID file as a data file: write the PID, read it later, check if the process is alive with kill(pid, 0). This has a classic race: process dies, PID gets recycled to an unrelated process, your library kills someone's database.

We took a different approach. The PID file is opened with an exclusive flock (or Windows share-mode lock), and the lock is held for the entire lifetime of the daemon. When the daemon dies — cleanly, via SIGKILL, via OOM — the kernel releases the lock. No timers, no polling, no PID reuse bugs. Identity is a kernel lock, not a number.

lock, err := pidlock.TryLock(pidPath)  // flock(LOCK_EX|LOCK_NB)
// ... write PID data through the lock (Seek+Write+Truncate) ...
// ... pass lock.File() to child via ExtraFiles ...
// child inherits the lock — zero window where it's released

On Unix, ExtraFiles passes the locked fd to the child — the lock is never released between parent and child. On Windows, ExtraFiles is not supported (Go issue #26182), so the parent releases the lock under the startup lock, and the child re-acquires it in Serve with a retry loop. The startup lock serializes this — no window for a third process to steal it.

The lock file is never deleted. Deleting a flock'd file while another process waits on flock() causes the inode-reuse race — both processes end up locking different inodes at the same path. We learned this the hard way.

Counting Connections Was Wrong

v0.1.0 had connect/disconnect endpoints. Proxy starts, POSTs /daemon/connect, counter goes up. Proxy stops, POSTs /daemon/disconnect, counter goes down. When the counter hits zero and IdleTimeout fires, the daemon exits.

Sounds clean. Here's what actually happens: a proxy gets SIGKILL'd. A terminal closes. An OOM killer strikes. The disconnect POST never fires. The counter stays at 1 forever. A daemon with IdleTimeout: 5 * time.Minute sits there consuming RAM until someone manually kills it.

We patched the counter twice — clamping to prevent negative counts from stray disconnects, and CAS loops for concurrent disconnect races. Both fixed real bugs, but neither touches the actual problem: counting requires both endpoints to fire, and one of them is called by a dead process. The positive count leak is inherent to the model.

Leases: Let the Kernel Count

The fix landed in v0.3.1. Instead of POST/POST, the proxy opens a GET /daemon/attach request and holds the TCP connection open for its entire lifetime:

Proxy               Daemon
  │                    │
  ├── GET /daemon/attach ──► ct.Connect()
  │         │          │
  │    TCP alive       │  count > 0, idle timer blocked
  │         │          │
  ╳ SIGKILL            │
  │                    │
kernel closes socket ──► ct.Disconnect()
                        │
                   count drops to 0 → idle shutdown

The TCP connection is the lease. When the proxy dies — for any reason — the kernel closes the socket, the HTTP handler's r.Context() gets cancelled, the deferred ct.Disconnect() fires, and the count drops. No heartbeats. No watchdogs. No stale counts.

A v0.3.1+ proxy against an older daemon without /daemon/attach detects 404 and falls back to the old connect/disconnect pair. The reverse (old proxy, new daemon) gets 401 because the token is missing — upgrade the proxy.

Bearer Token from the PID File

The daemon listens on 127.0.0.1 with a random port, so you might think it's safe. DNS rebinding is a real threat — a malicious page can resolve a domain to 127.0.0.1 and attempt requests. The Host header check (loopbackGuard, added in v0.1.1) stops this: browsers cannot forge the Host header, so the rebinding attack fails at the middleware.

The token protects against a different threat: other local processes that can already reach the port, or any non-browser client. The daemon generates a random token at startup (crypto/rand) and writes it to the PID file, which has 0600 permissions on Unix (on Windows, the DataDir ACL is the boundary). Every /daemon/* control-plane endpoint requires Authorization: Bearer <token>. The proxy reads the token from the PID file and sends it automatically. Your application handler (/mcp, custom routes) is open by default for curl debugging — set Config.RequireToken = true to lock it down too.

// In Serve():
token := rand.Text()  // crypto/rand, Go 1.24+
pidData.Token = token
lock.WriteData(marshal(pidData))

// Middleware:
func authGuard(next http.Handler, token string) http.Handler {
    // /daemon/* → require Bearer, constant-time compare
    // /health → pass through (external probes)
}

What We Didn't Build

No process supervision. If you need your daemon to restart after a crash, use systemd with Restart=on-failure. Our library complements kardianos/service — it doesn't replace it. Mixing Restart=always with idle auto-shutdown creates two supervisors that fight each other.

No remote access. Localhost only. If you need remote dev, that's your application's job, not the daemon library's.

No log rotation. We write to a log file. When it gets big, you rotate it. If this bothers enough people, we'll add it.

No heartbeats. The lease model eliminates the need. Heartbeats are the wrong abstraction when the kernel already tells you the connection is dead.

There is a school of thought that says daemonization is an anti-pattern and every background process should be an OS service. That is right when the requirement is supervision — boot-time presence, automatic restart, root-installed units. Our requirement is the opposite: a process that exists only while agents need it, spawned by tools that cannot sudo. The two are complementary, which is why this library does not replace kardianos/service.

Numbers

2,651 lines of library code. ~5.4K lines of tests. 160+ test functions. 2:1 test-to-code ratio.
Zero dependencies. go.mod has no require block.
Three platforms. CI runs build + test + lint + race detector on Linux, macOS, and Windows.
80%+ code coverage (85% root package). Every lifecycle feature has an integration test using the helper-process pattern (no external binaries).
No marginal binary cost if your binary already imports net/http (most MCP/CLI tools do). Otherwise you pay for net/http, not for this library — there are no transitive dependencies.

Try It

go get github.com/grpmsoft/daemon

The README has complete examples for all three modes — client, server, proxy. The library is at v0.3.3, pre-1.0. The API evolves fast — we break things when the design demands it, not on a schedule.

If you're building a CLI tool that needs a shared background server — an MCP server, a language server proxy, a build daemon, a local API cache — this might save you from reinventing the same PID-file-plus-health-check dance that every Go CLI eventually writes.

grpmsoft/daemon — Pure-Go on-demand process lifecycle for shared background services. MIT license.

gogpu/ui v0.1.54: We Built Flutter's Gesture System in Pure Go — Arena, Recognizers, and All

Andrey Kolkov — Thu, 13 Aug 2026 16:33:34 +0000

Series: Building Go's GPU Ecosystem

Recent articles:

Enterprise Render Pipeline — Layer Tree, Damage Tracking, 0% GPU Idle

Extracting a GPU Compositor — Patterns from Flutter and Chromium

Pure Go 3D Renderer Embedded Inside a GUI Widget

Google Says Go Is Ideal for AI-Assisted Engineering

The Problem: Every Widget Reinvented Click Detection

Our GUI toolkit has 27 widgets — buttons, checkboxes, sliders, text fields, dropdowns, dialogs, tab views, tree views, data tables, docking panels, and more — and each one implemented its own click/drag/selection logic from scratch. Button tracked pressed state. Slider tracked dragging. TextField had its own MouseDrag handler. No code was shared. No disambiguation existed.

When we wanted to add text selection to TextField (drag to select, double-click to select word, triple-click to select all), we realized the ad-hoc approach couldn't scale. What happens when a TextField is inside a ScrollView? Both want drag events. Who wins?

Flutter solved this problem in 2017 with the GestureArena. We decided to port the same architecture to Go.

What We Built

The Gesture Arena

The arena is the core disambiguation mechanism. When a pointer goes down, all widgets under the pointer register their gesture recognizers in the arena. The recognizers compete:

First to accept wins. If a recognizer is confident it detected its gesture (e.g., drag exceeded the slop threshold), it accepts and all others are rejected.
Last to not reject wins. If everyone else rejects (e.g., no movement for drag), the remaining recognizer wins by default.
Sweep after pointer up. If no one accepted, the first member wins as a last resort.

// Widget implements gesture.GestureAware
func (w *Widget) GestureHitTest(pos geometry.Point) []gesture.Recognizer {
    return []gesture.Recognizer{w.clickRec}
}

Four Recognizers + VelocityTracker

Recognizer	What it detects	Used by
ClickRecognizer	Single/double/triple click with timing	Button, Checkbox, Radio
DragRecognizer	Pan, horizontal, vertical drag with velocity	Slider, SplitView
LongPressRecognizer	Press-and-hold (500ms, frame-based)	Future: context menu
TapAndDragRecognizer	Click counting + drag in one recognizer	TextField
VelocityTracker	Least-squares velocity for fling detection	ScrollView momentum

Per-Device Thresholds

Mouse and touch have different precision. A 1px movement on a mouse is intentional; on a touchscreen it's noise. We use the same constants Flutter validated against millions of users:

Parameter	Mouse	Touch
Drag threshold (slop)	1px	18px
Double-click timeout	300ms	300ms
Double-click distance	4px (Chromium)	100px
Anti-bounce minimum	40ms	40ms

Unified Pointer Pipeline

We replaced the legacy mouse callback path with a single PointerEvent-based pipeline:

Platform → PointerEvent → HandlePointerEvent
    ├── Gesture Arena (recognizer dispatch for GestureAware widgets)
    └── Derived MouseEvent (existing widgets continue working unchanged)

Every pointer event flows through this single path. No dual dispatch. Existing widgets receive MouseEvent as before — derived from the same PointerEvent that feeds the arena.

Container Widget Hit-Testing

The hardest bug we hit: a Collapsible widget (parent) and a Checkbox (child) both had ClickRecognizers. The parent won the arena and silently dropped clicks meant for the child.

The fix: GestureHitTest(pos geometry.Point) receives widget-local coordinates. Container widgets only return recognizers when the pointer is in their interactive region:

// Collapsible returns recognizer ONLY for header clicks
func (w *Widget) GestureHitTest(pos geometry.Point) []gesture.Recognizer {
    headerRect := geometry.NewRect(0, 0, w.Bounds().Width(), w.headerHeight)
    if !headerRect.Contains(pos) {
        return nil // Content-area click → child widgets handle it
    }
    return []gesture.Recognizer{w.clickRec}
}

TextField: The Full Story

TextField was our proof-of-concept. Before v0.1.54, it could place a cursor on click. That's it. No selection, no word selection, no clipboard.

Now:

Click to place cursor (with Shift+Click for range extension)
Drag to select text character-by-character
Double-click to select word (uses wordBoundsAt() with Unicode word boundaries)
Triple-click to select all text
Double-click + drag for word-by-word selection
Ctrl+C/V/X for OS clipboard (Win32, macOS, Linux)

All of this through one TapAndDragRecognizer that provides consecutiveTapCount on every callback — exactly how Flutter's TextSelectionGestureDetector works.

OS Clipboard

We added widget.ClipboardProvider — a DI interface (same pattern as our SoundPlayer) that bridges widget clipboard requests to the platform:

// In widget package — no platform imports
widget.ClipboardWrite("copied text")
text := widget.ClipboardRead()

// Desktop layer registers the platform implementation
widget.RegisterClipboardProvider(gogpuApp) // Win32/macOS/Linux

Ctrl+C copies to system clipboard. Ctrl+V pastes from it. Works across applications.

Signals Integration

Gesture state is exposed as opt-in reactive signals:

dragRecognizer := gesture.NewDragRecognizer(gesture.DragConfig{
    OnDragStart: handleStart,
}, gesture.WithDraggingSignal(isDragging))

// Widget binds to signal for reactive redraw
state.BindToScheduler(isDragging, widget, scheduler)

Bool signals suppress no-op notifications. Point signals fire on every change. Frame-based timers (no goroutines) for long press.

Numbers

~8,300 LOC added (gesture/ package + widget migrations + clipboard + tests)
124 gesture tests, 96% coverage
20 widgets implement GestureAware with GestureHitTest
0 goroutines in the entire gesture system — single-threaded by design
5 enterprise references studied: Flutter (source code verified), Chromium, GTK4, Qt6, Android

What's Next

The gesture system is designed for multi-touch from day one. PointerEvent carries PointerID and PointerType (mouse/touch/pen). When Android support lands (@besmpl is working on it), pinch-to-zoom and multi-finger gestures will plug into the same arena.

Context menu (right-click) is the next visible feature. The gesture infrastructure supports any button — ClickRecognizer just needs a ButtonRight config.

gogpu/ui is an enterprise GUI toolkit for Go with GPU-accelerated rendering. Zero CGO, 220K+ LOC, 70 packages, 7,800+ tests.

Help Us Build Go's GUI Future

The gesture system is the kind of infrastructure that needs real-world validation. We tested with our gallery and examples, but the edge cases live in your applications.

Try it. Clone the repo, run the gallery, drag-select some text, double-click a word. If something feels wrong — file an issue. If it feels right — even better. Tell us.

git clone https://github.com/gogpu/ui.git && cd ui
GOGPU_GRAPHICS_API=vulkan go run ./examples/gallery/

Star the repo. It sounds small, but GitHub stars are how Go developers discover projects. We're listed in awesome-go — every star helps us stay there.

Spread the word. A mention in your team's Slack, a retweet, a discussion with a colleague who's frustrated with GUI options in Go. Most Go developers don't know a pure Go GUI toolkit with GPU rendering exists.

Contribute. The gesture system is designed for extensibility. Build a custom recognizer, add a new widget, improve accessibility, test on your hardware. Check CONTRIBUTING.md. @besmpl contributed 20+ PRs across the ecosystem including Android arm64 support — contributors make this project better.

Support the project. If gogpu saves you from CGO hell or fills a gap in Go's ecosystem, consider supporting on Open Collective. Open source is free to use but not free to build.

The gogpu ecosystem is 1.25M+ lines of pure Go with zero CGO. gogpu/ui alone: 220K+ LOC, 70 packages, 7,800+ tests. Five GPU backends. Three platforms. One goal: make Go the best language for building desktop applications.

GitHub · Discussions · Release v0.1.54 · awesome-go

Google Says Go Is Ideal for AI-Assisted Engineering. We've Been Proving It for a Year.

Andrey Kolkov — Wed, 12 Aug 2026 08:02:47 +0000

Yesterday Google published "Why Go is an Ideal Language for AI-Assisted Software Engineering" — arguing that AI shifted the bottleneck from writing code to reviewing it, and Go's integrated platform provides the guardrails AI teammates need.

We read it and thought: yes, we know.

Since fall 2025 we've been building Pure Go infrastructure that Go was missing — starting with HDF5 and Born ML (GPU-accelerated machine learning), then launching GoGPU in December 2025. Today it's 1.25 million lines of code. 15 repositories. Shader compiler, WebGPU implementation, 2D/3D graphics, GUI toolkit, audio engine, multi-process compositor. Zero CGO. All built using Smart Coding — our methodology where humans own architecture, specification, and review (70%), while AI handles mechanical implementation (30%), with cumulative knowledge transfer between sessions.

Here's what Google got right, what we learned the hard way, and what the article doesn't mention.

What Google Got Right

"The bottleneck shifted from writing to reviewing"

This is the central thesis, and it's correct. When AI generates hundreds of lines per session, the limiting factor becomes: can you verify this is correct?

In our workflow, every PR gets claim-by-claim validation. When a contributor submits "fix: correct PDF y-axis transform," we don't just read the diff — we verify the math:

Transform.Then applies the receiver first.
Translate(0,h).Then(Scale(1,-1)) → y' = -(y+h) ← WRONG
Scale(1,-1).Then(Translate(0,h)) → y' = h-y     ← CORRECT

We write the proof in a temp file, run it, confirm the output, then approve. AI generates the fix. Humans verify the math. Google's thesis in action.

"Go's integrated platform enables AI self-correction loops"

Google argues that gofmt, go test, go vet, and the compiler form a feedback loop where AI can iteratively fix its own output. True — and we run this loop on every change:

gofmt -w .                    # format
go build ./...                # compile (catches type errors, hallucinated APIs)
go vet ./...                  # static analysis
golangci-lint run --timeout=5m # 30+ linters
go test ./...                 # behavioral verification

Across 1.25M LOC, this catches most AI mistakes before a human ever looks at the code. The compiler is the first reviewer.

"Static types = safety net for agentic code"

Google: "If an AI agent attempts to use a non-existent method, pass an incorrect type, or leave a variable uninitialized, the code simply will not compile."

We cross-compile for three platforms on every PR:

GOOS=windows go build ./...
GOOS=linux   go build ./...
GOOS=darwin  go build ./...

This catches platform-specific hallucinations that single-platform builds miss — an AI might generate a Windows syscall in a Linux file, or reference a macOS framework in cross-platform code.

"Single static binary, zero system dependencies"

Our ecosystem proves this at scale. go build produces a binary that includes a WebGPU implementation (Vulkan/DX12/Metal/GLES/Software backends), a shader compiler (WGSL → SPIR-V/MSL/GLSL/HLSL/DXIL), a 2D graphics engine, and a GUI toolkit. No DLLs, no shared libraries, no runtime dependencies. No C compiler required.

This is what "batteries-included" means when taken seriously.

What Google Didn't Do — and We Did

Google created Go in 2009. They wrote the article about Go being ideal for AI in 2026. In between — 17 years — Go lacked three things every serious platform needs: professional graphics, GPU access, and an ML ecosystem.

No GPU graphics. No GPU-accelerated 2D library. No shader compiler. No WebGPU implementation. No GUI toolkit with native rendering. Java had Swing, then JavaFX. .NET had WPF, then MAUI. Rust got wgpu, then Bevy. Go got Fyne (CGO + OpenGL) and Ebiten (game engine, not a platform).

No GPU compute. Python has PyTorch, CUDA, TensorFlow. Rust has wgpu-rs for compute shaders and Burn for ML. Go had... os/exec to shell out to Python. A language "ideal for AI-assisted engineering" that couldn't run a GPU kernel without calling C. The irony: Google co-created the WebGPU standard (W3C) and built Dawn — the reference WebGPU implementation for Chrome. But they never gave Go access to their own standard. We built the third native WebGPU implementation in the world — and the only one in Go.

No ML ecosystem. Google writes the article about Go and AI, then builds TensorFlow in Python/C++, JAX in Python, and Gemini in... not Go. The language they praise as ideal for AI couldn't train a model.

Google builds Flutter (Dart), Android UI (Kotlin), Chrome (C++), TensorFlow (Python/C++). They never invested in making Go a first-class platform for graphics, GPU compute, or machine learning.

We're fixing all three:

Graphics: Shader compiler ahead of Rust naga on some features (DXIL generator — Rust hasn't shipped theirs). WebGPU implementation — the third in the world after Chrome's Dawn and Firefox's wgpu, and the only one in Go. GUI toolkit listed in awesome-go.
GPU compute: Born ML — a production ML framework fully migrated to our Pure Go GPU stack. Trains models on GPU. No Python, no CUDA, no CGO.
The full stack: 1.25M lines of Pure Go. From shader compilation to neural network training to GUI rendering — one language, one toolchain, go build.

Google's article validates why Go is the right language. GoGPU and Born ML prove what's possible when someone actually builds the missing pieces.

What We Learned That Google Didn't Mention

AI-generated code needs claim-by-claim validation, not just compilation

Google focuses on the compiler as the safety net. The compiler catches syntax and type errors. It does not catch:

Wrong algorithm — code compiles but produces incorrect output
Wrong architecture — code works but cements the wrong design
Wrong numbers — "renderer.go: ~720 → ~400 LOC" when the actual delta is 2,174 → 1,892

In our dev.to articles, we validate every factual claim against code before publishing. "Flutter's flow/ has ~15K LOC" — we count: actual is ~22K total lines. "ssa.Func has 30+ fields" — we count: actual is 41. "UI has 24 widgets" — we check README: actual is 27.

The compiler can't do this. Humans must.

Enterprise references prevent AI from reinventing wheels badly

Google mentions "cleaner training data" from Go's standardized ecosystem. But they don't address a deeper problem: AI confidently generates plausible-looking architecture that violates well-established patterns.

When we needed a GPU compositor, AI would happily generate a god-struct with 200 fields and bidirectional dependencies. Instead, we researched how Flutter (flow/), Chromium (cc/), and GTK4 (GSK) handle compositors. The answer was consistent: unidirectional deps, concrete structs, minimal callback interfaces. Research before code.

We formalized this as a rule: every GPU/HAL/sync/barrier change starts with enterprise reference research. AI proposes, references validate.

But references aren't always available. When you're building the third WebGPU implementation in the world, or the first Pure Go DXIL generator, there's no "how Flutter does it" to consult. You're the pioneer. AI can't help here either — it will confidently generate plausible architecture that has never been tested at scale. This is where human judgment, deep domain knowledge, and the willingness to read GPU specs directly become irreplaceable. Google's article assumes references exist. In practice, sometimes you are the reference.

Multi-agent architecture, not one AI editing everything

Google's article implies a single AI agent working on a single codebase. At our scale (15 repos), the architecture is fundamentally different.

Each repository has its own specialized agent with domain-specific sub-agents — a shader compiler agent that knows SPIR-V opcodes, a HAL backend agent that understands Vulkan barrier semantics, a GUI toolkit agent that knows widget lifecycle patterns. These agents are tuned for the specific library they serve, with their own project-level instructions, enterprise references, and research protocols.

The ecosystem-level agent only coordinates — it tracks cascade releases, manages cross-repo issues, and communicates via GitHub. It does NOT implement features in other repos. When it makes a claim ("this API should change in wgpu"), the repo-level agent independently validates that claim through its own deep research. They agree, or they push back with evidence. Very often, the first architectural instinct turns out to be fundamentally wrong — the repo agent catches it because it knows the domain deeply.

Cross-repo code changes by the coordination agent are rare exceptions, limited to thin interface seams (a new method on gpucontext.DeviceProvider, a version bump in go.mod). The real work happens inside each repo's agent session.

This isn't a preference — it's a technical necessity. No single AI agent can load 1.25M lines of code into its context window. Each repo is 96K-324K lines — already pushing context limits for a single session. The only way to work at ecosystem scale is specialized agents that deeply understand their domain, coordinated by a lightweight orchestrator that trusts but verifies.

go.work plays a different but critical role: when all repos are in a shared workspace, any agent in any repo always builds and tests against the current local state of every ecosystem dependency — not the last published version. An agent working on gg sees unpublished wgpu changes. An agent fixing a naga shader bug can immediately verify the fix compiles against the latest wgpu consumer code. No publish-wait-update cycles. When it's time for a PR or release, the code goes through multi-stage validation: each repo's agent runs its own pre-flight checks (build, test, lint across platforms, feature completeness audit, dependency freshness, documentation scan). The ecosystem agent validates cross-repo consistency. Agents check each other's claims — stubs, incomplete implementations, architectural shortcuts are caught before they reach production. And at the end, the human reviews and approves before anything is published. No release ships without explicit human sign-off.

The entire process is backed by persistent knowledge artifacts. Every deep investigation produces a research document with enterprise references and source-verified findings. Before implementation, an Architecture Decision Record (ADR) is written — documenting the decision, alternatives rejected, and enterprise patterns adopted. Kanban tasks break the work into trackable units with clear acceptance criteria.

When it's time to implement, specialized agents receive the full context — the research doc, the ADR, the task description, the relevant enterprise references. They write the code. Then the main repo agent reviews everything they produced — validates claims against code, checks for stubs, verifies test coverage, confirms the implementation matches the ADR. Only after confirming the code meets acceptance criteria does the agent approve the commit and public documentation update. If it doesn't meet the bar, the implementation iterates until it does. This is not a one-shot process — it's a quality ratchet that only moves forward.

But it's the multi-agent architecture, not go.work, that makes 15-repo AI-assisted development possible at all.

CI lint versions drift — and AI can't predict it

A practical problem Google's article doesn't address: golangci-lint latest in CI means the rules change under you. We've had PRs that pass locally (v2.12.2 on Windows, Go 1.25.5) but fail in CI (same v2.12.2, but Go 1.25.12 on Linux) because staticcheck behavior differs between Go toolchain versions.

AI generates code that passes your lint. CI runs different lint. The fix is pinning versions — but latest is the default in most GitHub Actions, including golangci-lint's own action.

The Numbers

What	Scale
Total Pure Go code	1.25M LOC
Repositories	15
GitHub stars	1,200+
Development period	~1 year (HDF5 + Born ML fall 2025, GoGPU from Dec 2025)
CGO required	Zero
External C/Rust dependencies	Zero
GPU backends	5 (Vulkan, DX12, Metal, GLES, Software)
Shader targets	5 (SPIR-V, MSL, GLSL, HLSL, DXIL)
Platforms	Windows, macOS, Linux, Browser
Contributors	8+

All built using Smart Coding — human architecture + AI implementation + cumulative knowledge — with exactly the Go guardrails Google describes.

The Ecosystem

Project	LOC	What it does
naga	324K	Shader compiler
gg	312K	2D graphics
wgpu	254K	WebGPU implementation
ui	211K	GUI toolkit (27 widgets)
gogpu	96K	App framework
+ 10 more repos	~53K	3D, audio, composition, system tray, types

Google's article is the theory. GoGPU is the proof. If you're considering Go for an AI-assisted project — we can confirm: the guardrails work. The compiler catches the easy bugs. The toolchain catches the medium bugs. Humans catch the hard bugs. And Go makes all three layers practical at scale.

But guardrails alone aren't enough. You also need a methodology — Smart Coding — where humans own the architecture, AI handles implementation, and cumulative knowledge files ensure each session builds on the last. Go provides the platform. Smart Coding provides the process.

Star us on GitHub: github.com/gogpu/gogpu ⭐

Support continued development: opencollective.com/gogpu

GoGPU: Extracting a GPU Compositor in Pure Go — Patterns from Flutter and Chromium

Andrey Kolkov — Tue, 11 Aug 2026 15:12:05 +0000

We had a suspicion the compositor was in the wrong package. But it worked, there was only one consumer, and refactoring a GPU compositor is genuinely hard. So we shipped it and moved on.

Then the 3D renderer arrived. Then the overlays broke. Suspicion turned into certainty — at the worst possible time.

This is the story of that migration, and what we learned from Flutter, Go stdlib, and Chromium along the way.

The Setup: a Compositor Hidden Inside a Drawing Library

GoGPU is a Pure Go GPU ecosystem — 1.25M lines of code, zero CGO. The architecture has three layers:

gogpu    — app framework (windowing, events, lifecycle)
gg       — 2D graphics (paths, text, GPU SDF, rasterizer)
wgpu     — WebGPU implementation (Vulkan/DX12/Metal/GLES/Software)

When we first built GPU-accelerated rendering for gg, the compositor logic naturally ended up inside gg. It was the only consumer. It owned the render target, the blit pipeline, the MSAA resolve, the damage tracking. It decided when to clear vs preserve content.

This is an ownership inversion. In every enterprise graphics stack — Chromium, Flutter, GTK4 — the compositor owns the render target and content cache. The drawing library just records draw commands into whatever surface it's given:

Framework	Drawing library	Compositor	Who owns the surface?
Chromium	Skia	cc/ (tile manager)	Compositor
GTK4	Render nodes	GSK	Compositor
Flutter	Dart Canvas	flow/	Compositor
GoGPU (before)	gg	gogpu	gg ← wrong

We suspected this wasn't right. But gg was the only renderer, it worked, and the refactoring would be complex. So we shipped it.

The Breaking Point: Three Problems, One Root Cause

Problem 1: Damage rects were single-source

Damage tracking already lived in gogpu — but as a simple passthrough. gg called SetDamageRects() with its dirty regions, gogpu forwarded them to the platform compositor via VkPresentRegionsKHR. One source, one consumer, worked fine.

Then g3d arrived. A 3D scene rotating at 60fps sends full-viewport damage. But SetDamageRects only accepted one set of rects — from gg. When gg rendered a HUD overlay on top of a g3d scene, only the HUD's damage was reported. The g3d viewport outside the HUD? Stale frames on Wayland compositors. Confirmed by @porjo on Asahi Linux (g3d#22) — visible mosaic artifacts because Mesa's wl_surface_damage_buffer only updated the HUD area.

So we redesigned the damage system from scratch. SetDamageRects (single source, simple passthrough) was replaced with RegisterDamageSource — each renderer registers as a named source, reports its own damage per frame, and gogpu unions all sources at present time. Chromium's DamageTracker uses the same union pattern. That was ADR-065 — not a refactor, a reimplementation.

Problem 2: Two overlays, two libraries

We had two independent debug overlay implementations:

gg had a damage overlay (damage_debug.go) — green flash-and-fade on dirty regions (GOGPU_DEBUG_DAMAGE)
ui had a dirty widget overlay (debug_dirty.go) — cyan rectangles on repainted widgets (GOGPU_DEBUG_DIRTY)

Both worked fine in isolation. Each had its own env var, its own rendering logic, its own fade effects. And neither knew about the other. A g3d-only app had zero debug overlays — no damage visualization, no FPS counter, nothing.

The fix: move overlays to the compositor level. A g3d-only app without gg still needs overlays. A multi-renderer app (gg + g3d) needs a unified overlay that sees damage from all sources. That was ADR-066 — a pluggable DebugOverlay system at the compositor level, with built-in damage and FPS overlays.

Problem 3: The move that broke everything

ADR-065 and ADR-066 shipped together in v0.51.0. Damage sources worked. Overlays worked — until the content was idle and the overlay had a 400ms fade animation.

1. Overlay fade: NeedsAnimationFrame() → RequestRedraw()
2. Next frame: gg says "nothing dirty" → no GPU commands
3. gg owns the render target → no commands = frame skipped
4. Overlay never draws → animation freezes

The compositor (gogpu) couldn't render overlays independently because gg owned the surface. Without gg's cooperation, the compositor couldn't even decide whether to clear or preserve the render target. The Vulkan spec says acquired swapchain images have UNDEFINED content — so without gg drawing, the overlay rendered on garbage.

Three problems, one root cause: gg owned what the compositor should own. The shortcut that "worked fine" for one consumer became a blocking architectural problem when the second and third consumers appeared. Every enterprise reference confirmed what we'd only suspected — the compositor must own the render target, not the drawing library.

Delaying further would have meant building workarounds. Each workaround would cement the wrong architecture deeper. So we stopped delaying.

Phase 1: Moving the Compositor Out of gg (ADR-067)

The first step was getting the compositor code out of gg and into gogpu where it belongs.

We introduced a compositor-owned composition texture:

Before:
  swapchain acquired → gg renders directly → present
  (gg decides Clear/Load, gg owns MSAA resolve)

After:
  swapchain acquired → gogpu clears composition texture
  → gg/g3d render INTO composition texture (they don't know)
  → gogpu draws overlays on top
  → gogpu blits composition texture → swapchain → present

Key insight: content renderers don't need to know about the compositor. Context.SurfaceView() returns the composition texture view instead of the swapchain view. From gg's perspective, nothing changed — it renders to a TextureView, same as before.

Overlay-only frames became first-class. When content is idle but an overlay is animating, the compositor uses LoadOpLoad (preserve) instead of LoadOpClear, draws the overlay on the preserved content, and presents. No cooperation from gg needed.

Phase 2: Extracting internal/compositor/ (ADR-069)

After moving compositor logic into gogpu, we had ~2,500 LOC of compositor code mixed with ~4,000 LOC of application framework in the same package. Time for the second step: extract it into internal/compositor/.

Research first

Before writing extraction code, we studied three references:

Flutter's flow/ (~22K lines) — concrete structs, unidirectional deps (shell/ → flow/, never reverse), GPU resources borrowed per frame through a callback. Closest to our situation.

Go stdlib ssa.Func (41 fields) — the largest internal/ split in Go. Struct ownership + Frontend callback interface. Parent creates the struct, calls methods. Internal package calls back through a minimal interface when it needs the parent.

Chromium cc/ (~190K lines) — interface-heavy dependency injection with *Client/*Delegate abstract classes everywhere. A C++ necessity, over-engineered for Go internal/.

What we actually built

The compositor isn't a single god-struct. It's a set of focused types that the root package composes:

gogpu/ (root package, renderer.go)
│
├── RenderTarget {
│     damageSources  []*compositor.DamageSource
│     blitPipeline    compositor.BlitPipeline
│     compositeState  compositor.CompositeState
│   }
│
└── internal/compositor/
    ├── blit.go            — BlitResources, BlitDrawRecorder interface
    ├── blit_pipeline.go   — BlitPipeline, CompositeState
    ├── damage_source.go   — DamageSource, per-renderer damage tracking
    ├── damage_scissor.go  — pure geometry: rect union, scissor clipping
    ├── damage_overlay.go  — DamageDebugOverlay (damage rect visualization)
    ├── fps_overlay.go     — FPSDebugOverlay (frame rate counter)
    ├── overlay_pipeline.go — shared GPU pipeline for overlays
    └── shader.go          — WGSL shader sources

Content renderers (gg, g3d) implement one interface:

type BlitDrawRecorder interface {
    RecordBlitDraws(pass *wgpu.RenderPassEncoder)
}

The compositor owns the render pass lifecycle. Renderers just record their draws.

The numbers

renderer.go: 2,174 → 1,892 lines (-282 LOC of compositor logic removed)
internal/compositor/: 2,357 LOC (self-contained subsystem)
Root package wiring: 194 LOC (thin delegation)

Zero public API change. All App, Context, RenderTarget types stayed in the root package. RegisterDamageSource() return type narrowed to gpucontext.DamageReporter interface — which external consumers already used. No breaking change.

Rules That Emerged

These are now enforced in CI:

1. No type aliases for migrated types. type X = internal.X is for transitional migration only. We changed return types to interfaces instead.

2. Call internal directly. No unexported wrapper functions around internal/ calls. At call sites: r.blitPipeline.Init(device, format, shader), not an unexported initBlitPipeline() wrapper.

3. Unidirectional deps, enforced in CI:

- name: Compositor dependency direction
  run: |
    if grep -r '"github.com/gogpu/gogpu"' internal/compositor/; then
      echo "compositor must not import root package"
      exit 1
    fi

4. Performance is not a reason to avoid extraction. We benchmarked interface calls: ~1.4-3.0ns vs ~1.3ns for direct calls. At 10 calls/frame × 60fps = ~60ns per frame vs ~16.7ms budget. 0.0005% overhead. Go 1.20+ devirtualizes most of these anyway.

What We Learned

"We'll fix it later" has a deadline you don't control. We suspected the compositor was in the wrong place for months. The deadline to fix it wasn't set by us — it was set by the overlay freeze bug and the 3D renderer needing damage tracking. Under pressure, every refactoring is harder.

Enterprise references agree on ownership. We checked Chromium, Flutter, and GTK4. In all three, the compositor owns the surface and content cache. The drawing library just draws. This isn't a coincidence — it's the architecture that survives multi-renderer apps.

Not everything needs a god struct. The Go stdlib ssa.Func pattern (single struct, 40+ fields, callback interface) is powerful but not universal. Our compositor worked better as a set of focused types (3-8 fields each) that the root package composes. Each type has a clear responsibility.

internal/ is underrated. Most Go projects either put everything in one package or create deep hierarchies. internal/ gives you encapsulation without the API commitment. The compositor is free to change its struct layout without breaking external consumers.

The Ecosystem

GoGPU is 1.25M lines of Pure Go — a full GPU ecosystem, not just one library:

Project	LOC	What it does
naga	324K	Shader compiler (WGSL → SPIR-V/MSL/GLSL/HLSL/DXIL)
gg	312K	2D graphics (Skia-class rasterizer, GPU SDF, ClearType)
wgpu	254K	WebGPU (Vulkan/DX12/Metal/GLES/Software/Browser)
ui	211K	GUI toolkit (27 widgets, 4 design systems)
gogpu	96K	App framework + compositor
g3d	14K	3D rendering (scene graph, PBR, forward renderer)
compose	10K	Multi-process composition (Unix socket, LZ4, hot-plug)
systray	8K	System tray (Win32/macOS/Linux, zero CGO)
audio	3.5K	Audio engine (WASAPI, WAV, Mixer)

Zero CGO. go build and it works. Windows, macOS, Linux, Browser.

1,200+ GitHub stars. Listed in awesome-go. Used by Born ML for GPU compute, ironwail-go for Quake 1 rendering.

The compositor migration landed across three releases: v0.51.0 (ADR-065 + ADR-066, damage source reimplementation + pluggable overlays), v0.52.0 (ADR-067, compositor-owned render target), and v0.52.1 (ADR-069, package extraction).

If your drawing library owns compositor state and you only have one consumer — fix it now. The second consumer always arrives sooner than you expect.

Try It, Break It, Tell Us

GoGPU is pre-v1.0 — this is the best time to influence the API before it freezes. We need your help:

Test on your hardware. We develop on Intel Iris Xe (Windows) and Mesa llvmpipe (Linux). AMD, NVIDIA, Apple Silicon, Adreno — every GPU we haven't tested is a bug we haven't found. Run the examples, file issues.
Contribute. PRs welcome — from typo fixes to new backends. We review everything. Check good first issues across the org.
Write about it. Tutorials, reviews, comparisons — in any language. Pavel Tišnovský wrote three parts on root.cz (Czech), covering gg 2D graphics and gogpu windowing with 12 interactive examples. If you write something, let us know — we'll link it.
Spread the word. Star us, mention us in your talks, recommend us when someone asks "how do I do GPU in Go?"

Support the Project

GoGPU is built by a small team in their spare time. If you find it useful, consider supporting continued development:

Support GoGPU on Open Collective — every contribution helps us spend more time on the ecosystem instead of client work.

Star us on GitHub: github.com/gogpu/gogpu ⭐

We Built a Pure Go 3D Renderer — Then Embedded It Inside a GUI Widget

Andrey Kolkov — Sun, 02 Aug 2026 21:33:11 +0000

Go has had a 2D graphics story for a while now. But 3D? The options have been either CGO wrappers around OpenGL, abandoned projects from 2019, or "use Ebiten and write your own engine."

We decided to build the missing piece: g3d — a Pure Go 3D rendering library with scene graph, PBR materials, and forward rendering pipeline. Zero CGO, all five GPU backends (Vulkan, Metal, DX12, GLES, Software), 374 tests, built on our WebGPU implementation.

But a 3D renderer that only works standalone is half the story. The real question is: how does it compose with UI?

This post covers the two integration patterns we shipped in v0.1.4 — patterns that every enterprise 3D application uses, from Unity to Blender to CAD tools. And how we filed eight cross-repo issues across five repositories to make it work.

The 20-Line Rotating Cube

Before we get to integration — here's what g3d looks like standalone:

scene := g3d.NewScene()
scene.SetBackground(g3d.RGB(0.1, 0.1, 0.15))

sun := g3d.NewDirectionalLight(
    g3d.WithLightColor(g3d.White),
    g3d.WithLightIntensity(1.0),
)
scene.Add(sun.LightNode())

cube := g3d.NewMesh(
    g3d.NewBoxGeometry(1, 1, 1),
    g3d.NewStandardMaterial(
        g3d.WithColor(g3d.RGB(0.4, 0.7, 1.0)),
        g3d.WithRoughness(0.6),
    ),
)
scene.Add(cube.MeshNode())

camera := g3d.NewPerspectiveCamera(75, 800.0/600.0, 0.1, 1000)
camera.CameraNode().SetPosition(g3d.Vec3{X: 0, Y: 0.5, Z: 3})

Scene graph, PBR materials, directional lighting — all CPU data structures. No GPU device needed until you render. The API is inspired by Three.js, but idiomatic Go: interfaces + functional options, not OOP inheritance chains.

The renderer creates itself lazily on first frame:

app.OnDraw(func(dc *gogpu.Context) {
    if renderer == nil {
        renderer, _ = g3d.NewRenderer(app.GPUContextProvider())
    }
    renderer.Render(scene, camera, dc.SurfaceView())
})

That's it. Rotating PBR cube on Vulkan. Single binary, zero CGO, go build && ./app.

The Real Challenge: 3D + UI

A standalone 3D window is a demo. A 3D viewport inside a GUI application — that's a product. Think about what real 3D applications look like:

Game: fullscreen 3D world with health bar, minimap, crosshair overlaid
CAD tool: 3D model viewer with toolbar, property panel, status bar around it
IDE: 3D preview panel embedded alongside code editor and file tree

These are two fundamentally different composition patterns:

Pattern	3D Renders To	UI Renders To	Who Owns the Surface
Fullscreen overlay	Swapchain directly	Same swapchain (on top)	Both, sequentially
Embedded widget	Offscreen texture	Swapchain (compositor)	UI framework

We implemented both. And both required solving problems that no Go project had solved before.

Pattern 1: Fullscreen 3D + 2D Overlay

This is the game/CAD pattern. g3d renders the 3D scene to fill the entire window, then gg (our 2D graphics library) draws HUD elements on top: title, FPS counter, crosshair, status bar.

The enterprise pattern is well-established — we researched seven engines:

Engine	How They Do It
Bevy + egui	Separate render pass, `LoadOp::Load`, `depth_stencil: None`
Dear ImGui	Separate render pass, `DepthEnable=false`, alpha blending
Unity	Screen Space Overlay canvas, rendered after everything
Godot	CanvasLayer, separate from 3D viewport
Three.js	`clearDepth()` between 3D and HUD render calls

The universal answer: two render passes on the same surface. First pass clears and renders 3D with depth testing. Second pass loads the existing content and renders 2D with alpha blending, no depth.

In g3d + gogpu + gg, this looks like:

app.OnDraw(func(dc *gogpu.Context) {
    // Pass 1: g3d renders 3D scene (LoadOp::Clear + depth)
    renderer.Render(scene, camera, dc.SurfaceView())

    // Bridge: tell gogpu the surface has content
    dc.MarkExternalContent()

    // Pass 2: gg renders 2D HUD (LoadOp::Load + alpha blend)
    canvas.Draw(func(cc *gg.Context) {
        drawHUD(cc, width, height, fps)
    })
    canvas.Render(dc.RenderTarget())
})

MarkExternalContent() is the key API. It tells the gogpu framework: "someone already rendered to this surface — don't clear it." Without this call, gg's render pass would wipe the 3D scene with LoadOp::Clear. With it, gg uses LoadOp::Load and draws transparently on top.

This is the same concept as Qt's beginExternal()/endExternal(), Flutter's InlinePassContext, and Unity's Camera.DontClear.

The Result

A rotating PBR cube at 60 FPS with a full HUD overlay — title, live FPS counter, animated crosshair, status bar with backend info. All Pure Go, all on the same swapchain, zero copies.

GOGPU_GRAPHICS_API=vulkan go run ./examples/fullscreen-overlay/

Pattern 2: 3D Inside a GUI Widget

This is the CAD/IDE pattern. The 3D viewport is one widget among many — surrounded by buttons, text, panels. The UI framework owns the window; g3d renders into an offscreen GPU texture; the compositor blits it into the widget tree.

This is how Qt's QRhiWidget, Unity's RenderTexture, and Godot's SubViewport work.

In g3d + gogpu/ui:

vp := gpuview.New(
    gpuview.Size(600, 400),
    gpuview.Continuous(true),
    gpuview.OnRender(func(view gpucontext.TextureView) {
        wgpuView := (*wgpu.TextureView)(view.Pointer())
        renderer.Render(scene, camera, wgpuView)
    }),
)

The gpuview.Widget (formerly Viewport3D, renamed for universality) handles the GPU texture lifecycle. It creates an offscreen texture, passes it to your OnRender callback, and hands the result to the Layer Tree compositor for blitting into the final frame.

Your 3D renderer doesn't know or care that it's inside a widget. It receives a TextureView and renders to it — same API as fullscreen rendering.

The UI layout is standard gogpu/ui:

uiApp.SetRoot(primitives.Box(
    primitives.Text("g3d GPUView").FontSize(22).Bold(),
    vp, // 3D viewport widget
    button.New(
        button.TextOpt("Pause / Resume"),
        button.OnClick(func() { paused = !paused }),
    ),
).Padding(28).Gap(14).Rounded(12).ShadowLevel(2))

Material 3 themed card with a 3D viewport, title, and control buttons. The 3D content renders at GPU speed inside the widget while the rest of the UI renders through the standard compositor pipeline.

go run ./examples/viewport3d/

Eight Issues Across Five Repos

Getting both patterns working wasn't just API design — it was a debugging marathon across five repositories (g3d, gg, gogpu, ui, wgpu) and eight issues. Here are the three hardest:

Bug 1: MSAA Resolve Overwrites External Content

When gg renders its 2D overlay, it uses 4x MSAA for antialiased edges. The MSAA render pass writes to an intermediate texture, then resolves to the swapchain. The resolve is a full overwrite — it doesn't care what was on the swapchain before.

So even with LoadOp::Load, the MSAA intermediate texture was empty (it never contained the 3D scene), and the resolve wrote empty + HUD to the swapchain. 3D content gone.

Fix: gg v0.50.9 implemented Strategy C from Skia's playbook — render the overlay into a separate offscreen MSAA texture, resolve to a 1x intermediate with alpha, then alpha-blend composite onto the swapchain via textured quad. The 3D content survives because the swapchain is never a resolve target.

Bug 2: GPU Buffer Use-After-Free

g3d's renderer created uniform buffers per frame with MappedAtCreation, used them in a render pass, submitted the command buffer, and immediately released them via defer. But queue.Submit() is asynchronous — the GPU was still reading the buffers when Go freed them.

command buffer at index 0 references released buffer "g3d_frame_uniforms"

Fix: Replaced per-frame allocation with persistent uniform buffers updated via queue.WriteBuffer(). Geometry buffers cached by identity. Bind groups deferred-released at the start of the next frame. This is the same pattern gg uses internally — zero allocations in the hot path.

Bug 3: Layer Tree Missing External Texture Node

The gpuview widget created its texture, fired OnRender, and g3d rendered into it correctly. But the widget was invisible. The Layer Tree compositor had ExternalTextureLayer support in its rendering code — but nobody created those nodes.

buildBoundaryLayer() only created PictureLayer nodes. Widgets with external GPU textures needed a parallel ExternalTextureLayer node so the compositor would blit their content.

Fix: ui v0.1.49 added externalTextureWidget interface detection in the Layer Tree builder. Widgets that provide Texture() and ViewportSize() automatically get an ExternalTextureLayer alongside their PictureLayer.

Shared Command Encoder: The Third Way

Sometimes you don't want two separate queue.Submit() calls. g3d v0.1.3 added RenderTo() — record g3d render passes into a caller-owned command encoder:

encoder, _ := device.CreateCommandEncoder(nil)

// g3d records its render pass
renderer.RenderTo(encoder, scene, camera, targetView)

// Other renderers record their passes
overlayRenderer.RecordTo(encoder, ...)

// One submit for the entire frame
commands, _ := encoder.Finish()
queue.Submit(commands)

This eliminates the multi-submit overhead and gives you precise control over render pass ordering. It's the pattern gogpu v0.48.4 uses internally via dc.CommandEncoder().

The Architecture

Here's how g3d fits into the gogpu ecosystem:

Your Application
    ├── gogpu (window + GPU device)
    ├── g3d  (3D scene → render passes)
    ├── gg   (2D graphics → render passes)
    └── ui   (widget tree → compositor → render passes)
              └── gpuview widget ← g3d renders here

g3d depends down only — on wgpu and gpucontext. Never on gogpu, gg, or ui. This means you can use g3d in any context: with gogpu, with your own windowing, or headless for testing.

The shared GPU device comes through gpucontext.DeviceProvider — the same database/sql-style interface pattern that gg, ui, and Born ML use. One device, shared across all renderers, zero-copy resource sharing.

The Ecosystem Is Accelerating

g3d doesn't exist in isolation. The gogpu ecosystem is growing in directions that directly benefit 3D applications:

Zero-CGO Android. @besmpl proved that CGO_ENABLED=0 -buildmode=c-shared works on Android arm64 via //go:nativeexport — a Go toolchain patch that eliminates the last CGO dependency for mobile GPU apps. The prototype runs on API 30 emulator. Once upstream, g3d will run on Android with the same go build simplicity as desktop.

Pure Go Race Detector. The GoGPU ecosystem can't use go test -race today because GPU backends require CGO_ENABLED=0. We're contributing to a Pure Go race detector that achieves read-path parity with TSAN (0.985x on Apple M1). @besmpl delivered 20 optimization commits in 5 days. When merged, every GPU-accelerated Go project gets race detection for free.

Browser/WASM. wgpu's triple-backend architecture (ADR-038) means g3d will run in the browser via WebGPU — same Go code, GOOS=js GOARCH=wasm go build. The browser backend is already shipping in wgpu for 2D; 3D follows the same path.

Composition library. gogpu/compose enables multi-process GPU composition — think VS Code's renderer process architecture, but for Go. A g3d viewport in one process, a 2D editor in another, composited via Unix socket + LZ4.

Community tutorials. Pavel Tišnovský (2,185+ articles on root.cz, Czech Republic) published 88 minutes of tutorial content covering the ecosystem with 54 working examples — the first serious European press coverage of Go GPU graphics.

Games are happening. @kivutar built Goro — a Ragnarok Online client using gogpu/ui in Pure Go (no CGO), with working UI, mercenaries, and gameplay. @darkliquid's Quake 1 port runs on our Vulkan stack. The Go game dev community is real — and it needs a 3D library that doesn't require CGO.

By the Numbers

Metric	Value
g3d LOC	~11,700
Tests	374
GPU backends	5 (Vulkan, Metal, DX12, GLES, Software)
Examples	3 (hello-cube, fullscreen-overlay, viewport3d)
Cross-repo bugs found	8
Cross-repo bugs fixed	8
Releases	3 (v0.1.2 → v0.1.4, Jul 26 – Aug 2)
Ecosystem total	1.2M+ LOC Pure Go

Try It

# Standalone 3D
go run github.com/gogpu/g3d/examples/hello-cube@latest

# Fullscreen 3D + 2D overlay
go run github.com/gogpu/g3d/examples/fullscreen-overlay@latest

# 3D inside UI widget
go run github.com/gogpu/g3d/examples/viewport3d@latest

Select your GPU backend:

GOGPU_GRAPHICS_API=vulkan   go run ./examples/hello-cube/
GOGPU_GRAPHICS_API=dx12     go run ./examples/hello-cube/
GOGPU_GRAPHICS_API=software go run ./examples/hello-cube/

What's Next

g3d v0.1.4 has the foundation: scene graph, PBR materials, forward renderer, and two production-ready integration patterns. Here's what's coming:

Phase 2 — Real Materials. Cook-Torrance BRDF replaces Blinn-Phong. Shadow mapping (directional + point). Normal maps, metallic/roughness textures, emissive maps. This is where g3d goes from "demo-ready" to "product-ready."

Phase 3 — GLTF 2.0. Binary .glb and JSON .gltf loading with PBR materials, skeletal animation, and morph targets. GLTF is the "JPEG of 3D" — every modeling tool exports it, every engine imports it. g3d will too.

Phase 4 — Scale. Instance batching for thousands of objects. Environment maps for reflections. Post-processing pipeline (bloom, tone mapping, FXAA). Skybox.

Phase 5 — Performance. BVH-accelerated frustum culling, LOD (level of detail), SIMD math via Go 1.25+ goexperiment.simd. The GoMLX PackGEMM team proved 14x speedup with Pure Go AVX-512 — same approach applies to matrix math.

The rendering library was the last missing piece in Go's graphics ecosystem. 2D graphics, GUI toolkit, shader compiler, audio engine, system tray — all Pure Go, all shipping. Now 3D joins them.

How You Can Help

This project grows through real-world usage. Every bug report from a different GPU, every feature request from a real application, every "it works on my AMD/NVIDIA/Apple M4" — that's data we can't generate alone.

Test it on your hardware. We develop on Intel Iris Xe. AMD, NVIDIA, Apple Silicon, Adreno — we need your GPU. A simple go run ./examples/hello-cube/ and a one-line issue "works on RTX 4080 / Vulkan" is genuinely valuable.

Build something with it. A 3D file viewer. A data visualizer. A game prototype. A CAD preview panel. The API is designed to be embedded — g3d doesn't own your application, you own g3d. The integration patterns in this article work today.

Report what's missing. We're tracking Phase 2–5 features, but priority depends on what people actually need. Shadows? GLTF? Instance batching? Textures? Tell us.

Spread the word. Star the repos, share the examples, write about your experience. Go's graphics ecosystem has been invisible for 17 years because nobody knew it existed. That changes when the community talks about it.

Contribute code. The CONTRIBUTING.md has everything you need. Good first issues are labeled. We review PRs within 24 hours. Every contributor gets credit in the CHANGELOG and release notes.

Support the project. We accept donations via Open Collective to fund development, testing on diverse GPU hardware, and CI infrastructure. Every contribution helps us test on more platforms and ship faster.

The ecosystem is 1.2M+ lines of Pure Go — but the codebase isn't what makes it real. Users make it real. Applications make it real. The more people building on g3d, the faster it reaches the quality bar that Go deserves.

Go's sql.Null[T] Will Never Get JSON Support. Here's What We Built Instead.

Andrey Kolkov — Sat, 04 Jul 2026 18:52:37 +0000

Go 1.22 gave us sql.Null[T] — a generic nullable type for SQL. Problem solved?

No. Try marshaling it to JSON:

{"V":"Alice","Valid":true}

That's not "Alice". That's not null. That's a broken API response.

And it will never be fixed. Issue #68375 — proposal to add MarshalJSON to sql.Null[T] — was closed as infeasible. Go's policy forbids adding marshal methods to types that already have a "reasonable" default marshaling. The struct marshaling {"V":...,"Valid":...} counts as "reasonable."

This is a permanent gap in Go's standard library.

The Three Bad Options (Before opt)

1. `sql.Null[T]` — SQL works, JSON broken

type User struct {
    Name sql.Null[string] `json:"name"`
}
// Marshals to: {"name":{"V":"Alice","Valid":true}}
// You wanted:  {"name":"Alice"}

2. `*string` — JSON works, everything else is awkward

type User struct {
    Name *string `json:"name"`
}
// Pointer allocation overhead on every value
// Can't distinguish "field absent" from "field is null"
// user.Name == nil — is this "not set" or "set to null"?

3. `guregu/null` — Works, but carries 10 years of legacy

guregu/null (2,070 stars) is the de facto standard. It works. But:

v1→v6 legacy — API evolved over 10 years, backward compatibility constraints
No three-state — can't distinguish "field absent" from "field null" (critical for PATCH APIs)
No Map/FlatMap — no functional composition
No OrNull constructors — every project writes the same boilerplate helpers
Generic Value[T] has MarshalText and Equal commented out — couldn't make them work generically

opt: Option<T> for Go

coregx/opt — designed from scratch for Go 1.24+. No legacy, no compromises.

import "github.com/coregx/opt"

type User struct {
    Name  opt.String `json:"name"`
    Email opt.String `json:"email,omitzero"`
    Age   opt.Int    `json:"age"`
}

user := User{
    Name: opt.StringFrom("Alice"),
    Age:  opt.IntOrNull(0),  // 0 means "not set" → null
}

data, _ := json.Marshal(user)
// {"name":"Alice","age":null}
// Email omitted (omitzero) — not null, just absent

JSON works. SQL works. No pointer overhead. No boilerplate.

What Makes opt Different

1. Three-State `Field[T]` — The PATCH API Killer Feature

Every REST API with PATCH endpoints has this problem: how do you distinguish "the client didn't send this field" from "the client explicitly set it to null"?

type PatchUser struct {
    Name  opt.Field[string] `json:"name,omitzero"`
    Email opt.Field[string] `json:"email,omitzero"`
    Age   opt.Field[int]    `json:"age,omitzero"`
}

// Client sends: {"name":"John","email":null}
var patch PatchUser
json.Unmarshal(input, &patch)

patch.Name.IsValue()   // true  → set name to "John"
patch.Email.IsNull()   // true  → set email to NULL in DB
patch.Age.IsAbsent()   // true  → don't touch age

Three states: absent (don't touch), null (set to NULL), value (set to value).

Rust does this with Option<Option<T>>. Kotlin with nullable + optional. In Go, no library properly solves this — guregu/null doesn't distinguish absent from null, and pointer-based approaches (**T) are impractical. coregx/opt's Field[T] is the first clean solution with concrete typed constructors, OrNull, FlatMap, and a zero/ subpackage.

2. `OrNull` Constructors — No More Boilerplate

Every project using nullable types with a database writes the same helpers:

// This is in EVERY Go project with nullable DB fields
func optStr(s string) opt.String {
    return opt.NewString(s, s != "")
}
func optInt(n int64) opt.Int {
    if n == 0 { return opt.Int{} }
    return opt.IntFrom(n)
}

With opt, this is built in:

row := CompanyRow{
    City: opt.StringOrNull(company.City()),     // "" → null
    OGRN: opt.StringOrNull(reg.OGRN()),         // "" → null
    Count: opt.IntOrNull(company.EmployeeCount()), // 0 → null
}

One function per type. Zero boilerplate. Available for all 8 concrete types including BoolOrNull.

3. Functional API — Map, FlatMap, Equal

Inspired by Rust's Option<T>:

// Transform if valid, propagate null
name := opt.From("  Alice  ")
trimmed := opt.Map(name, strings.TrimSpace)    // opt.Option[string]{"Alice", true}
length := opt.Map(trimmed, func(s string) int { return len(s) })  // opt.Option[int]{5, true}

// Chain operations that may produce null
parsed := opt.FlatMap(input, func(s string) opt.Option[int] {
    n, err := strconv.Atoi(s)
    if err != nil { return opt.New(0, false) }
    return opt.From(n)
})

// Nil-safe comparison
opt.Equal(opt.From(42), opt.From(42))  // true
opt.Equal(opt.From(42), opt.New(0, false))  // false

guregu/null has ValueOr. That's it. No Map, no FlatMap, no OrElse.

4. Generic `Option[T]` That Actually Works

guregu's generic Value[T] has MarshalText and Equal commented out in the source code — they couldn't make them work generically.

opt's Option[T] is fully functional:

// Works with ANY type
v := opt.From(MyCustomStruct{Name: "test"})
data, _ := json.Marshal(v)  // {"Name":"test"}

null := opt.New(MyCustomStruct{}, false)
data, _ = json.Marshal(null)  // null

5. `zero/` Subpackage — Alternative Semantics

Sometimes you want zero values to be null, and null to marshal as zero (not null):

import "github.com/coregx/opt/zero"

s := zero.StringFrom("")   // Invalid — empty = null
data, _ := json.Marshal(s) // "" (not "null")

i := zero.IntFrom(0)       // Invalid — 0 = null
data, _ = json.Marshal(i)  // 0 (not "null")

Package	`From("")`	Marshal null
`opt`	Valid (empty string)	`null`
`opt/zero`	Invalid (null)	`""`

Comparison

Feature	coregx/opt	guregu/null	`*T`	`sql.Null[T]`
Generic nullable	`Option[T]`	Partial	N/A	No JSON
Three-state (PATCH)	`Field[T]`	No	No	No
Concrete types (String, Int...)	8 types	8 types	N/A	N/A
`OrNull` constructors	Yes	No	No	No
`FieldFromOption`	Yes	No	No	No
Map / FlatMap	Yes	No	No	No
OrElse (lazy)	Yes	No	No	No
Equal	Yes	Yes	N/A	No
JSON marshal	Yes	Yes	Yes	Broken
SQL Scanner/Valuer	Yes	Yes	Yes	Yes
omitzero (Go 1.24+)	Yes	Yes	No	No
zero-is-null subpackage	`zero/`	`zero/`	No	No
json/v2 compatible	Yes	Yes	Yes	No
Legacy code	None	v1→v6	N/A	N/A

Performance

Zero-allocation unmarshal. Bool operations under 2 nanoseconds:

BenchmarkBoolMarshalJSON     0.85 ns/op    0 allocs
BenchmarkBoolUnmarshalJSON   2.1 ns/op     0 allocs
BenchmarkIntUnmarshalJSON    193 ns/op     1 alloc
BenchmarkStringUnmarshalJSON 137 ns/op     0 allocs
BenchmarkStructMarshalJSON   876 ns/op     9 allocs

Why New Projects Should Start with opt

sql.Null[T] will never get JSON support — this is official Go team position (#68375)
*T can't do three-state — nil means both "absent" and "null"
guregu/null works but carries v1→v6 legacy and has no PATCH support
opt starts clean — Go 1.24+, generics-first, no backward compatibility burden
Field[T] is unique — no other Go library properly solves the PATCH three-state problem
Zero dependencies — only Go stdlib
json/v2 ready — works today, optimizable when json/v2 goes stable

Getting Started

go get github.com/coregx/opt@v0.3.0

import "github.com/coregx/opt"

// Always valid
name := opt.StringFrom("Alice")

// Zero means "not set"
age := opt.IntOrNull(0)  // null

// From pointer (nil → null)
email := opt.StringFromPtr(emailPtr)

// Three-state for PATCH
type PatchRequest struct {
    Bio opt.Field[string] `json:"bio,omitzero"`
}

Full API and examples: github.com/coregx/opt

Help Us Get to v1.0.0

opt is in active development. We're heading toward a stable v1.0.0 and need your help:

Try it in your project — replace *string or guregu/null and tell us how it goes
Report issues — edge cases, driver compatibility, unexpected behavior
Suggest features — what nullable types should do that no library does yet
Send PRs — new types, better tests, documentation improvements
Share — if opt solved a problem for you, tell your team or write about it

Every bug report, feature idea, and PR brings us closer to a stable API.

GitHub | Issues | pkg.go.dev

opt is part of the coregx ecosystem — high-performance Go libraries for production applications.

DEV Community: Andrey Kolkov

Read and Write MATLAB .mat Files in Go Without CGO: Files That Read as Empty, and MATLAB Files We Couldn't Open

Files saved with MATLAB's defaults read as empty

A bug report that waited three months

A 136-byte file that could ask for 2 GiB

The fix that broke bytes.Buffer

MATLAB's own v7.3 files didn't open

Test data and docs that claimed too much

What I'd do differently

What's next

HDF5 in Pure Go, No CGO: a 5 KB File That Allocated 40 GB, and Round-Trip Tests That Lied

A 5 KB file, a 40 GB allocation

Round-trip tests that lied

116 datasets that read "fine"

Errors you can act on

Our own old files

How I check it now

What I'd do differently

What's next

A Shader Loop That Never Ran: What GPU Readback Found in gogpu/naga, a Go WGSL Compiler

What the validator saw

What naga is

Running the output instead

What it caught

When Rust naga and the spec disagree

What I'd do differently

What's next

Go regexp too slow? I built coregex, a drop-in replacement. An audit found 16 bugs — here's what broke

The bug that would have broken every HTTP router

Case-insensitive Cyrillic didn't match its own literal

Silent wrong results on large input

Empty matches that produced invalid UTF-8

The 15-character DoS

What the fuzz found (and didn't)

The benchmarks after fixes

What I'd do differently

What's next

Go 1.27 HTTP Router with Generic Methods and Zero-Alloc Routing: FURSY — What an Independent Audit Found at 94% Coverage

What Is Fursy

The Generic Methods Story

What the Audit Found: CORS Was Echoing Everything

The Documentation Was Lying

RFC 9457: Claiming It vs. Being It

The Colon That Broke Google's API Convention

Form Binding Errors: 500 Instead of 400

What Fursy Doesn't Do

Fursy vs. Other Go Routers (2026)

Numbers

Gotchas

router.GET Is a Generic Method Now

Plugins Have Their Own go.mod

CORS Must Be Global

The Second Pass

Try It

Go SQL Query Builder Without Dependencies: Relica, the ozzo-dbx Successor — What Broke on PostgreSQL and SQLite

The Bug That Would Have Woken Me at 3 AM

PostgreSQL $N Placeholder Collision in Subqueries (bind message supplies N parameters)

Statement Cache: The Race Nobody Tested

Patterns That Actually Work

Model() for CRUD, Builder for Everything Else

Expression API Over String Conditions

ForUpdate Inside Transactions

QueryHook for Everything Observable

Subqueries Need .AsExpression()

What We Didn't Build

Relica vs Squirrel vs sqlx vs GORM vs sqlc (2026)

Numbers

The Gotchas

Go Daemon for MCP Servers: Shared Background Processes Without systemd or Other Supervisors

The Problem Is Not "How to Fork"

EnsureRunning: The Core Abstraction

The PID File Is the Lock

Counting Connections Was Wrong

Leases: Let the Kernel Count

Bearer Token from the PID File

What We Didn't Build

Numbers

Try It

gogpu/ui v0.1.54: We Built Flutter's Gesture System in Pure Go — Arena, Recognizers, and All

The Problem: Every Widget Reinvented Click Detection

The fix that broke `bytes.Buffer`

PostgreSQL `$N` Placeholder Collision in Subqueries (`bind message supplies N parameters`)

1. `sql.Null[T]` — SQL works, JSON broken

2. `*string` — JSON works, everything else is awkward

3. `guregu/null` — Works, but carries 10 years of legacy

1. Three-State `Field[T]` — The PATCH API Killer Feature

2. `OrNull` Constructors — No More Boilerplate