Fifty artefacts were read; the twenty-four that carry the argument are below,
graded. Two tiers are empty on purpose and the reason is in the first card.
Source code
Methodology note2026-10
Why there are no blogs, talks or papers in this wall
This run's egress policy allowed GitHub, the Go module proxy, the crates index, PyPI
and apache.org, and refused every other host attempted, including the company's own
documentation site, InfoQ, USENIX, arXiv and the Wayback Machine. Rather than cite
material that could not be fetched, the guide is built only from what could be read
and re-checked.
Carry forwardA repository-only reconstruction is strong on
decisions and dates and blind to operating experience. Read this guide for the first
and go elsewhere for the second.
https://github.com/cloudwego
Source code
CloudWeGo2021-06
netpoll: the stated case for replacing the language's network package
The README gives two reasons, both architectural rather than micro-optimising: Go's
net forces "the One Conn One Goroutine design", and net.Conn
"has no API to check Alive", which makes a correct RPC connection pool hard. It also
declines the existing event-loop libraries as aimed at Redis-shaped and
HAProxy-shaped workloads.
Carry forwardThe best argument for substituting a layer is
a missing capability in its interface, not a benchmark. "No liveness check" is the
kind of reason that stays true as hardware changes.
https://github.com/cloudwego/netpoll
Source code
CloudWeGo2026-10
netpoll: the race detector is deliberately blinded
A documentation file titled "DATA RACE EXPLAIN" states that netpoll ships separate
files behind //+build race and //+build !race "to avoid DATA
RACE detection in some code", because the epoll path uses unsafe.Pointer
and that "is beyond the detection range of the race detector". The design document the
README links to alongside it contains the single line "# TODO".
Carry forwardAsk of any high-performance replacement which
of your existing tools stop working against it. The answer is rarely in the README and
is sometimes in a file called explain.md.
https://raw.githubusercontent.com/cloudwego/netpoll/main/docs/reference/explain.md
Source code
CloudWeGo2022
kitex: the escape hatch back to the standard library, kept for four years
Kitex is built on netpoll, but it also carries
pkg/remote/trans/gonet, whose package comment is "Package gonet contains
server and client implementation for go net." The alternative transport has been in
the tree since 2022 and is still there.
Carry forwardThe thing that makes a layer substitution
reversible is a maintained second implementation on the original. Budget for it from
the start; retrofitting one after the replacement has diverged is a rewrite.
https://raw.githubusercontent.com/cloudwego/kitex/develop/pkg/remote/trans/gonet/trans_server.go
Source code
CloudWeGo2025-06
kitex PR 1767: rebuilding the standard-library transport, closed unmerged
A maintainer opened a reimplementation of the gonet transport on
2025-04-23 that, per a review comment, would "use bufiox to replace netpoll" in that
path. It drew forty comments on connection-state checking and goroutine lifetime,
reached about 59% patch coverage, was marked draft on 2025-06-06 and closed on
2025-06-09 with no stated reason.
Carry forwardA closed-unmerged PR on the escape hatch is a
signal about how much the escape hatch is actually exercised. If nobody will finish
the fallback, the fallback is decorative.
https://github.com/cloudwego/kitex/pull/1767
Source code
CloudWeGo2022-08
kitex PR 585: xDS support built, milestoned, then dropped
"add xds module to manage xDS resources retrieved from control plane. Support traffic
route, timeout config and service discovery based on xDS." The PR was added to the
v0.4.0 milestone on 2022-08-19, removed from it on 2022-08-22, and closed the next day
without comment, after an approval had been dismissed as stale.
Carry forwardA company that substitutes its own layers
tends to resist the industry's shared control plane, because the shared one assumes
components it has already replaced. Watch for that pattern before standardising on a
mesh.
https://github.com/cloudwego/kitex/pull/585
Source code
ByteDance2026-10
sonic compat.go: the build tag that is also an expiry date
The fast path compiles only for amd64 from Go 1.17 and
arm64 from Go 1.20, and only below go1.28. Outside that
window compat.go sets apiKind = UseStdJSON and forwards
every call to encoding/json. The README adds that Go 1.24.0 specifically
is unsupported and suggests -ldflags="-checklinkname=0".
Carry forwardGrep your dependencies for upper version
bounds in build tags. Each one is a date on which a performance assumption quietly
stops holding, with no error to alert on.
https://github.com/bytedance/sonic/blob/main/compat.go
Source code
Go package index2026-10
sonic's published interface: the fallback is documented, the compatibility is opt-in
The package reference states "On non-sonic-supporting environment, the implementation
will fall back to encoding/json" and that "Sonic DOES NOT ensure to
support all environments, due to the difficulty of developing high-performance codes".
It also shows that ConfigDefault aims "at efficiency and safety" while a
separate ConfigStd aims "at being compatible with encoding/json".
Carry forwardRead which config of a drop-in replacement is
the compatible one. If byte-for-byte parity with the original is a non-default option,
then swapping the import is a behaviour change, not a dependency bump.
https://pkg.go.dev/github.com/bytedance/sonic
Postmortem
ByteDance / Go2024-06
sonic 660: Go 1.23 rc1 broke the link to a private standard-library symbol
The reporter hit "invalid reference to encoding/json.safeSet" and noted that "Go 1.23
no longer allows //go:linkname * runtime.* link instructioins". A second reporter
arrived through Hertz the following day. A maintainer replied "We are handling this.
Please wait for a while" and tagged it a known issue; closed three weeks later.
Carry forwardThe first warning of a seam closing is a
release-candidate build failure filed by an external packager, not by you. Test
against upstream release candidates if you depend on anything that linknames.
https://github.com/bytedance/sonic/issues/660
Postmortem
Go project2025-02
golang/go 71672: upstream restored a deleted symbol and backported it
A removed //go:linkname on runtime.lastmoduledatap broke
Go 1.24 builds. A Go maintainer observed the package had never been listed in the
hall of shame because only three packages import it directly; the sonic maintainer
answered that "sonic is dependent over 1w+ repos". The symbols were added back and the
fix was backported to the 1.24 branch at a Go maintainer's request.
Carry forwardPast some adoption threshold your
unsanctioned dependency becomes the upstream project's compatibility problem. That is
leverage, but it is leverage you only get after the breakage, which is a poor plan.
https://github.com/golang/go/issues/71672
Postmortem
ByteDance2025-02
sonic 738: the downstream half of the same break
"go 1.24 build failed: link: github.com/bytedance/sonic/loader: invalid reference to
runtime.lastmoduledatap". The body's diagnosis is a guess, "It seems Go teams removes
the //go:linkname on runtime.lastmoduledatap", and the maintainer's interim advice was
a branch plus "-ldflags=-checklinkname=0". Opened 2025-02-12, closed 2025-03-08.
Carry forwardWhen the documented workaround for a
dependency is to disable a toolchain safety check, that is the real cost of the
dependency, and it belongs in the decision record rather than the troubleshooting
page.
https://github.com/bytedance/sonic/issues/738
Postmortem
ByteDance2025-12
sonic 895: Go 1.26 removed a runtime type the library relied on
"internal/rt/stubs.go:33:22: undefined: GoMapIterator" on Go 1.26 rc1, with a
commenter adding "Same problem with 1.25 actually". After the nominal fix, the same
reporter hit further undefined symbols in loader/internal/abi and asked
"is this relevant?"; the issue was closed the next day without an answer.
Carry forwardBreakage of this class recurs on a schedule
set by somebody else's release calendar. Treat it as recurring maintenance with an
owner, not as a bug that gets fixed once.
https://github.com/bytedance/sonic/issues/895
Postmortem
ByteDance2023-02
sonic 363: a one-byte input crashed the test suite under the race detector
"checkptr: converted pointer straddles multiple allocations", raised inside the JIT's
stack-map builder during package initialisation, triggered by unmarshalling
'0' into an int under go test -race. A second
reporter confirmed on a different Go and library version and noted the tests pass
without -race.
Carry forwardRun your own test suite with the instrumented
build before adopting a JIT-based library, because the failure appears in your CI and
looks like your bug.
https://github.com/bytedance/sonic/issues/363
Decision record
Go project2024-05
golang/go 67401: the decision to close the seam, with an escape hatch
Russ Cox's proposal to "prevent new //go:linkname-based dependencies and contain
existing ones", on the Go 1.23 milestone. The requirement is that "all //go:linkname
usage must be in the Handshake form: both sides must agree", enforced by a new
-checklinkname=1 default, with -checklinkname=0 left as the
opt-out. Locked as resolved in February 2025.
Carry forwardThis is the template for closing an
unsanctioned extension point without an immediate flag day: make the strict mode the
default, keep the opt-out, and name the packages affected. Reuse it when you need to
retire an internal API other teams reached into.
https://github.com/golang/go/issues/67401
Source code
Go project2025
Go's runtime names these packages in its own source as a constraint
At the go1.25.0 tag, mallocgc carries the comment "should be an internal
detail, but widely used packages access it using linkname. Notable members of the hall
of shame include" followed by bytedance/gopkg,
bytedance/sonic and cloudwego/frugal.
memmove lists sonic and cloudwego/dynamicgo;
growslice and reflect_growslice list dynamicgo;
procPin, noescape and the sync.Pool cleanup
hook list bytedance/gopkg.
Carry forwardIf you want to know which private internals
of a platform have become load-bearing for the ecosystem, read the platform's source
comments rather than its documentation. Maintainers annotate what they can no longer
change.
https://github.com/golang/go/blob/go1.25.0/src/runtime/malloc.go
Source code
CloudWeGo2025-09
frugal releases: the JIT capped, made optional, defaulted off, deleted
Four release notes tell the whole retreat: "feat(jit): go1.23 for the last supported
version" with "new reflect impl for non-amd64 arch" (v0.2.0, 2024-08-08), "feat: add
NoJIT option" (v0.2.2, 2024-11-28), "refactor: disable JIT by default" (v0.2.4,
2025-01-09) and "refactor: rm JIT code & clear CI" (v0.3.0, 2025-09-09).
Carry forwardThis is the cleanest public example of
retiring an over-reaching optimisation: cap the supported range, add the opt-out, flip
the default, delete. Thirteen months, four releases, no flag day.
https://github.com/cloudwego/frugal/releases
Case study
CloudWeGo2026-10
frugal and shmipc: what the substitutions bought, with a crossover
Frugal reports "about 2.5x to 3.7x faster than Apache Thrift (TBinaryProtocol)" on
go1.23.6. Shmipc reports that it is slower than a Unix socket at 64 bytes (7,740
against 5,523 ns/op) and roughly twice as fast at 4 KB (660.78 against 343.44 MB/s),
reaching 2,686 MB/s at 4 MB.
Carry forwardTrust the benchmark that names the size at
which the replacement loses. Then find the equivalent crossover for your own traffic
mix before adopting, because for small-message workloads this particular substitution
is a regression.
https://github.com/cloudwego/shmipc-go
Case study
ByteDance2021-12
monoio: the same bet, remade in Rust, measured on their own network
"Our test is carried out on the ByteDance production network." Monoio reports roughly
twice Tokio's peak throughput at four cores and close to three times at sixteen, and
states where it loses: "in the case of a single core and very few connections,
Monoio's latency will be higher than Tokio". The README also concedes that the
unstable features and new I/O abstraction "may cause some compatibility problems".
Carry forwardThread-per-core wins where connection counts
are high and work is uniform, and loses on small deployments. The axis to measure is
cores times connections, not requests per second.
https://raw.githubusercontent.com/bytedance/monoio/master/docs/en/benchmark.md
Decision record
KubeWharf2026-10
KubeBrain: replacing etcd behind its own interface, consistency pending
The README names the forcing function, Kubernetes' "official stable operation scale
is limited to 5K nodes", and the design: a stateless component that "implements the
storage server interface required by the API Server" and "does not actually store the
data", with watched data held in the master node's memory and final consistency
reached through an asynchronous retry queue. Two TODO items remain unchecked:
"Guarantee consistence in critical cases" and "Jepsen Test".
Carry forwardWhen a store advertises interface
compatibility, read its consistency tests before its benchmarks. Interface
compatibility is a day-one property; the guarantee is what you need on the day of the
partition.
https://github.com/kubewharf/kubebrain
Case study
KubeWharf2026-10
KubeBrain benchmark: faster on reads and writes, slower on deletes
Three-node clusters, 70-byte keys, 512-byte values, 300 concurrent etcd clients. The
stated conclusion: "KubeBrain on TiKV can outperform etcd in read and write
performance, while deletion performance needs to be further optimized", justified on
the grounds that Kubernetes' storage load "has a low percentage of deletion
operations".
Carry forwardA replacement that is faster on the common
operation and slower on a rare one is a reasonable trade, provided you have measured
your own operation mix rather than inherited the claim.
https://raw.githubusercontent.com/kubewharf/kubebrain/main/docs/benchmark.md
Decision record
KubeWharf2026-10
KubeGateway: an API-server-shaped proxy in front of the API server
The design document's load-bearing sentence is about compatibility, not performance:
"The control plane of KubeGateway is equivalent to a complete kube-apiserver", so
"you can use client-go to make configuration changes directly without additional
SDK". The README claims it "converges the number of TCP connections on a single
kube-apiserver instance by at least an order of magnitude" for clusters of more than
1,000 nodes.
Carry forwardThe cheapest configuration interface for a
new infrastructure component is an interface your operators already have a client
for. Shaping your control plane like the system it fronts removes an entire adoption
cost.
https://raw.githubusercontent.com/kubewharf/kubegateway/main/docs/en/design.md
Source code
KubeWharf2026-10
The version floor: one published distribution, pinned to 2022
enhanced-k8s lists a single release, v1.24.6-kubewharf.0.1 on Kubernetes
v1.24.6 with go1.18.6. Katalyst requires it. Godel supports 1.21.4 to 1.24.6,
KubeAdmiral 1.16 to 1.24. The fork's own branch list shows newer bases,
sharding-1.32.3 through sharding-1.34.1, maintained into
September 2025 but never released as a distribution.
Carry forwardCheck the version floor of any platform
component before adopting it, and check it against the fork it requires rather than
the component's own release date. An actively committed repository can still be
unrunnable on a supported platform.
https://github.com/kubewharf/enhanced-k8s
Source code
CloudWeGo2025-03
prutal: the next generation is pure Go and says what it does not do
"Prutal is a pure Go alternative to protocol buffers", aiming "to minimize code
generation as much as possible". It publishes its own incompatibility list: the Opaque
API is unsupported because "field presence lives in a bitmap the runtime does not
maintain", and Clone, Merge, Equal and CheckInitialized are absent. The README states
it "is NOT yet ready for production use".
Carry forwardThe honest form of a drop-in replacement is
one that ships a list of the calls it does not implement. Demand that list; if the
project will not write it, you will discover it one call at a time.
https://github.com/cloudwego/prutal
Vendor
CloudWeGo2026-10
The company's own framing of the set
"CloudWeGo is an open-source middleware set launched by ByteDance that can be used to
quickly build enterprise-class cloud native and AI native architectures. The common
characteristics of CloudWeGo projects are high performance, high scalability, high
reliability and focusing on microservices communication and governance."
Carry forwardNote what the framing omits: no scale figure,
no service count, no adoption number. The repositories assert that these systems are
"widely used inside ByteDance" and never quantify it, so neither does this guide.
https://github.com/cloudwego/.github