ygo is a pure-Go implementation of the Yjs CRDT (Conflict-free Replicated Data Type) library, enabling real-time collaborative applications in Go backends without CGO or embedded runtimes.
It is binary-compatible with the JavaScript Yjs reference implementation — updates produced by ygo can be applied by Yjs clients, and vice versa.
This library is production-ready. All planned phases are complete, the test suite passes, and the B4 benchmark targets are met. See the CHANGELOG for recent security hardening.
| Component | Status |
|---|---|
encoding/ |
✅ Complete |
crdt/ core |
✅ Complete |
crdt/types/ |
✅ Complete |
| Update encoding V1 | ✅ Complete |
| Update encoding V2 | ✅ Complete |
| Sync protocol | ✅ Complete |
| Awareness | ✅ Complete |
| WebSocket handler | ✅ Complete |
| HTTP handler | ✅ Complete |
| Snapshots / GC | ✅ Complete |
- Pure Go — no CGO, no V8, no embedded JavaScript engine
- Binary-compatible — interoperates with JS Yjs, Yrs (Rust), and any compliant Yjs client
- Full type support — YText, YArray, YMap, YXmlFragment, YXmlElement, YXmlText
- Both update formats — UpdateV1 and UpdateV2 (with V1↔V2 conversion)
- Sync protocol — implements y-protocols SyncStep1/2 and incremental updates
- Awareness — presence, cursor sharing, and ephemeral state
- Snapshots — point-in-time document history and restore
- Transport-agnostic — core logic has no transport dependency; WebSocket and HTTP handlers are addons
- Idiomatic API — designed for Go developers, not a transliteration of the JS API
- Go 1.23 or later
go get github.com/reearth/ygopackage main
import (
"fmt"
"github.com/reearth/ygo/crdt"
)
func main() {
// Create two peers
alice := crdt.New()
bob := crdt.New()
// Obtain the shared type before entering a transaction —
// GetText and Transact both acquire the document mutex.
text := alice.GetText("content")
// Alice makes edits
alice.Transact(func(txn *crdt.Transaction) {
text.Insert(txn, 0, "Hello, world!", nil)
})
// Encode Alice's state and send to Bob
update := alice.EncodeStateAsUpdate()
// Bob applies the update — both docs now converge
if err := crdt.ApplyUpdateV1(bob, update, nil); err != nil {
panic(err)
}
fmt.Println(bob.GetText("content").ToString()) // "Hello, world!"
}The examples/ directory contains four runnable programs with detailed inline comments:
| Example | What it shows |
|---|---|
examples/peer-sync |
In-process two-peer sync via the y-protocols handshake — no network needed |
examples/http-sync |
Pull/push sync over HTTP with incremental state-vector diffs |
examples/collab-editor |
Real-time multi-tab collaborative editor with a browser client |
examples/snapshot-history |
Document versioning — capture, store, and restore past states |
Run any example from the repository root:
go run ./examples/peer-sync
go run ./examples/http-sync
go run ./examples/snapshot-history
go run ./examples/collab-editor/server # then open http://localhost:8080package main
import (
"net/http"
"github.com/reearth/ygo/provider/websocket"
)
func main() {
server := websocket.NewServer()
http.Handle("/yjs/{room}", server)
http.ListenAndServe(":8080", nil)
}Backend services — AI agents, HTTP handlers, content pipelines — can push
changes into a live room without simulating a WebSocket peer. Three APIs
are available on *websocket.Server.
Fans a pre-encoded V1 update out to all peers currently connected to a
room. Does not apply the update to the server's doc — callers who
want the server's state to reflect the broadcast must call
crdt.ApplyUpdateV1 first (or use Apply below).
doc := server.GetDoc("my-room")
if err := crdt.ApplyUpdateV1(doc, update, nil); err != nil {
return err
}
if err := server.BroadcastUpdate(ctx, "my-room", update); err != nil {
return err
}Skipping ApplyUpdateV1 creates divergence. Live peers see the
update, but peers joining afterwards receive the server's stale state
via sync step 2.
Applies a callback to the doc and broadcasts the resulting delta atomically.
Auto-creates the room if needed. Persistence runs via the existing
OnUpdate hook — callers do not need to persist separately.
err := server.Apply(ctx, "my-room",
func(doc *crdt.Doc, transact func(func(*crdt.Transaction))) {
frag := doc.GetXmlFragment("content") // OUTSIDE transact — see note
transact(func(txn *crdt.Transaction) {
elem := crdt.NewYXmlElement("p")
frag.InsertElement(txn, 0, elem)
})
},
)Important: calls to doc.GetXmlFragment, doc.GetText, doc.GetMap,
and the other root-type accessors must happen outside the transact
callback. These methods acquire the doc's write lock, which transact
already holds — calling them inside deadlocks.
fn should be fast. It runs inside the doc's write lock and blocks all
peer reads and writes to the room for the duration.
On ErrUpdateTooLarge, the mutation sticks. The size check runs
after fn's transaction commits and after persistence has enqueued the
update, so the server's doc reflects fn's changes and the update IS
persisted — but peers do NOT see it. Size-bound fn's effects
explicitly or reconcile peers via a sync step 1/2 exchange.
Explicit teardown for rooms created by Apply that never accumulated
peer connections. Without CloseRoom, such rooms linger until process
exit.
if err := server.CloseRoom("my-room", false); err != nil { /* ... */ }
// force=true closes connected peers first.An optional hook gates all server-side writes:
server.OnInject = func(ctx context.Context, info websocket.InjectInfo) error {
tenant, _ := ctx.Value(tenantKey{}).(string)
if !allowed(tenant, info.Room) {
return fmt.Errorf("tenant %q may not write to %q", tenant, info.Room)
}
if info.Op == websocket.OpBroadcastUpdate && info.UpdateSize > 1<<20 {
return errors.New("update too large for this tenant")
}
return nil
}info.Op is OpBroadcastUpdate or OpApply. info.UpdateSize is the
length of the update bytes for BroadcastUpdate; zero for Apply (the
delta has not yet been produced — size capping for Apply is handled
by MaxUpdateBytes, post-hoc).
Refusals are returned wrapped with ErrInjectRefused, so callers can
match either the sentinel or the hook's own error via errors.Is.
Server.MaxUpdateBytes— per-update size cap, default 64 MiB (matches the peer frame limit).Server.MaxRooms— total-room cap applied uniformly to peer upgrades (HTTP 503) andApply(ErrTooManyRooms). Default unlimited.
Server.Apply and Server.BroadcastUpdate grant total write authority
on the document. Treat the *Server handle with the same care as a
database connection — do not expose it directly to untrusted code.
OnInject is defense-in-depth, not a substitute for caller-side
authorization. A caller who can reach either API can craft updates that
spoof any client ID, which is equivalent to the authority already
granted by GetDoc + ApplyUpdateV1.
# Run all benchmarks with memory allocation stats
go test ./... -run='^$' -bench='^Benchmark' -benchmem
# Run a specific package only
go test ./crdt/ -run='^$' -bench='^Benchmark' -benchmem
# Run with more iterations for tighter confidence intervals
go test ./... -run='^$' -bench='^Benchmark' -benchmem -benchtime=5s -count=3To compare two branches (e.g. before and after an optimization), install benchstat:
go install golang.org/x/perf/cmd/benchstat@latest
# Capture baseline
git checkout main
go test ./... -run='^$' -bench='^Benchmark' -benchmem -count=5 | tee old.txt
# Capture candidate
git checkout my-branch
go test ./... -run='^$' -bench='^Benchmark' -benchmem -count=5 | tee new.txt
# Compare
benchstat old.txt new.txtThe CI benchmark workflow (.github/workflows/benchmark.yml) runs this comparison automatically on every pull request.
Measured on Apple M4 Max (arm64, Go 1.23). Your numbers will vary by hardware.
Encoding (encoding/) — the codec runs on every item; these are sub-10 ns, zero-alloc:
| Benchmark | ns/op | Allocs |
|---|---|---|
| ReadVarUint (1 byte) | 1.0 | 0 |
| WriteVarUint (1 byte) | 1.7 | 0 |
| WriteVarString (1000 chars) | 15 | 0 |
| ReadVarString (1000 chars) | 89 | 1 (string copy) |
Encoder reuse (Reset) vs new |
7.7 vs 12.4 | 0 vs 1 |
CRDT core (crdt/) — realistic document operations:
| Benchmark | ns/op | Notes |
|---|---|---|
YText_InsertBulk (1000 chars) |
2 006 | Single transaction — fast path |
YText_Insert (1000 × 1 char) |
344 048 | ~344 ns per keystroke |
YText_Delete (1000 × 1 char) |
891 456 | ~891 ns per delete |
EncodeStateAsUpdateV1 (1000 items) |
21 360 | ~21 µs to serialise a document |
ApplyUpdateV1 (1000 items) |
109 806 | ~110 µs to integrate a full state |
EncodeStateAsUpdateV2 |
33 029 | V2 is ~1.5× larger to encode… |
ApplyUpdateV2 |
679 207 | …and ~6× slower to decode |
TwoPeerConvergence |
16 284 | Encode + apply incremental sync |
YMap_Set (100 keys) |
19 557 | |
YArray_Push (100 elements) |
59 209 |
Sync protocol (sync/) — message framing overhead is negligible:
| Benchmark | ns/op |
|---|---|
EncodeSyncStep1 |
179 |
ApplySyncMessage_Step1 |
631 |
ApplySyncMessage_Update (1000-item doc) |
1 404 |
FullHandshake |
1 303 |
Awareness (awareness/) — per-peer ephemeral state:
| Benchmark | ns/op |
|---|---|
SetLocalState |
65 |
EncodeUpdate (1 client) |
226 |
EncodeUpdate (50 clients) |
12 901 |
ApplyUpdate (50 clients) |
19 801 |
See docs/ARCHITECTURE.md for a detailed explanation of the CRDT algorithm, data model, and package design.
ygo targets compatibility with:
- Yjs v13.x (JavaScript reference implementation)
- y-protocols sync and awareness protocol
- lib0 binary encoding format
Compatibility is verified by golden-file tests that compare binary output byte-for-byte with Yjs-generated fixtures.
Transact acquires the document write lock for the duration of its callback.
Calling any of the read methods (Get, ToSlice, Keys, Entries, ToString,
ToDelta) or registering/unregistering observers (Observe, ObserveDeep) from
inside a Transact callback will deadlock because those operations try to
acquire the same lock.
// ✗ WRONG — deadlocks
doc.Transact(func(txn *crdt.Transaction) {
arr.Get(0) // tries to RLock — deadlock
arr.Observe(fn) // tries to Lock — deadlock
})
// ✓ CORRECT — acquire references and register observers before Transact
arr.Observe(func(e crdt.YArrayEvent) { /* ... */ })
doc.Transact(func(txn *crdt.Transaction) {
arr.Push(txn, []any{"value"})
})
fmt.Println(arr.ToSlice()) // read after Transact returnsThis constraint applies to YArray, YText, YMap, YXmlFragment, and
YXmlElement. UndoManager callbacks (OnStackItemAdded) also run outside
the lock and are safe to use normally.
Use crdt.WithClientID(id) at construction time. Changing the ID after the
document has started accepting operations will corrupt the item store.
Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.
For significant changes, open an issue first to discuss what you'd like to change.
Please report security vulnerabilities by following the process in SECURITY.md. Do not open public issues for security problems.
MIT License — see LICENSE.
This project is not affiliated with the Yjs authors. Yjs is developed by Kevin Jahns and contributors.