yjsrelay

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 20 Imported by: 0

README

go-yjs-relay 🐹

🧭 A product-neutral Yjs relay for Go: per-room y-websocket sync, presence fan-out, debounced snapshots, and flush and freeze around a publish.

Collaborative editors built on Yjs need a server that fans updates out to every peer in a document's room. go-yjs-relay is that server as a library. It speaks the stock y-websocket protocol, so y-websocket's WebsocketProvider connects to it unchanged, and it runs no Y.Doc of its own: updates pass through verbatim and the clients converge, which is what a CRDT is for. 🔌 You bring the two parts that are yours: who may join a room, and where checkpoints go.

✨ Highlights

  • 🔄 y-websocket sync: one room per document, Sync Step-1/Step-2 and updates, with a fresh joiner pulling the newest edits from the peers already there.
  • 👥 Presence you can trust: awareness fans out to the room, and the relay rewrites every user block with the verified identity, so nobody can show up as someone else. Colours are stable per user.
  • 💾 Debounced snapshots: clients send a checkpoint frame (content plus compacted Yjs state); the room saves the newest one after a quiet period, and again when the last editor leaves.
  • 🧊 Flush and freeze: Flush forces the newest checkpoint into storage before you publish; Freeze turns the room read-only afterwards and tells every editor.
  • 📣 Outcomes reach the editor: accepted and rejected checkpoints arrive as control frames, so an edit that did not persist is never silent.
  • 🩹 Self-repairing fan-out: a client whose buffer overflows is resynced instead of drifting away for good.
  • 🧱 No product wiring: no JWT, database, broker or RPC code. Logging through go-log, error codes through go-apperr when you supply them.

📦 Install

go get github.com/Bugs5382/go-yjs-relay

🚀 Usage

Implement a TokenVerifier (turns a join token into a room and a verified identity) and a SnapshotSink (loads a room's stored state, saves checkpoints), then serve the handler:

verifier := yjsrelay.TokenVerifierFunc(func(ctx context.Context, token string) (yjsrelay.Join, error) {
    claims, err := myTokens.Verify(ctx, token) // your signer, your claims
    if err != nil {
        return yjsrelay.Join{}, err
    }
    return yjsrelay.Join{
        Room:      claims.DocumentID,
        Identity:  yjsrelay.Identity{UserID: claims.UserID, DisplayName: claims.Name},
        RoomAttrs: map[string]string{"tenant": claims.Tenant},
    }, nil
})

hub := yjsrelay.New(sink, yjsrelay.WithLogger(log.NewLogger("collab")))
defer hub.Close(context.Background())

mux := http.NewServeMux()
mux.Handle("GET /rooms/{room}", yjsrelay.NewHandler(hub, verifier))

The client connects to /rooms/<doc>?token=<token> (or sends Authorization: Bearer <token>). A token is only good for the room it names. Browser Origin headers are refused unless you list them with WithAllowedOrigins; the intended setup is a server-side proxy in front of the relay.

Around a publish:

// Before: the sink must hold the newest content, or the version is cut from stale content.
if _, err := hub.Flush(ctx, docID); err != nil {
    return err // a *yjsrelay.FlushError: rejected or unavailable
}
// ... publish ...
// After: every editor drops to read-only.
hub.Freeze(ctx, docID, "v7")

💾 Snapshots and the sink

The client sends a snapshot frame (protocol.MsgSnapshot, type 100) carrying its content export (for example Lexical JSON) and its compacted Y.encodeStateAsUpdate(doc). The relay attributes it to the connection's verified identity, never to anything in the frame, and saves the newest one through your sink:

type SnapshotSink interface {
    Load(ctx context.Context, room string) ([]byte, error)
    Save(ctx context.Context, snap yjsrelay.Snapshot) error
}

🛡️ What Save returns decides what editors see:

  • nil: a snapshot.accepted control frame.
  • &yjsrelay.RejectError{Reason, Detail}: a snapshot.rejected frame carrying your reason and detail.
  • an error wrapping yjsrelay.ErrUnavailable (or a context error): rejected as unavailable, and the checkpoint is kept for the next flush.
  • any other error: rejected as sink_error, with its text kept server-side.

The room keeps the newest state in memory even when the sink refuses the content, because the peers already hold those edits. ValidateLexicalJSON is a ready-made envelope check a sink can run first. A nil sink runs a pure relay.

🏷️ Error codes

The library never picks go-apperr codes for you. Pass yours and Flush and Close attach them:

hub := yjsrelay.New(sink, yjsrelay.WithCodes(yjsrelay.Codes{Rejected: 4221, Unavailable: 5031}))

errors.Is(err, yjsrelay.ErrRejected), errors.Is(err, yjsrelay.ErrUnavailable) and errors.As(err, &flushErr) keep working either way.

🔧 Options

  • 🪵 WithLogger: a go-log logger; the default discards everything. Tokens and display names are never logged.
  • ⏱️ WithDebounce: quiet period before a save (default 5s).
  • 📏 WithReadLimit: largest inbound frame (default 2 MiB). A proxy in front must allow at least this much, or it closes the biggest snapshots first.
  • 👀 WithSessionObserver: hear every join and leave, for example for an audit trail.
  • 🎨 WithPalette: presence colours. Presence also carries colorIndex, so a client can map it onto a palette of its own.
  • 🚪 WithAllowedOrigins and WithRoomFunc: handler options for the Origin allowlist and for reading the room id from a request.

📐 Scaling

All room state lives in process memory. Two editors of one document on different instances get two rooms that never see each other. Run one instance, or route each room id to one instance (a consistent hash at the ingress).

🧩 Packages

  • yjsrelay: the hub, the handler and the two interfaces.
  • yjsrelay/protocol: the wire encoders and decoders, pinned against bytes the real JavaScript yjs/y-protocols stack produced. Use it in Go clients and tests.

🛠 Develop

task build    # go build ./...
task test     # go test ./...
task lint     # gofmt check + golangci-lint + yamllint
task license  # check MIT headers (golic)

⚖️ License

MIT (c) 2026 Shane

Documentation

Overview

Package yjsrelay is a product-neutral Yjs room relay: per-room y-websocket sync and awareness fan-out, server-authoritative presence, debounced snapshots, and flush and freeze around a publish.

The relay runs no Y.Doc. Updates fan out to peers verbatim and the clients converge on their own. Durability comes from a snapshot frame the client sends (see package protocol): the editor's content export plus its compacted Yjs state. The room debounces those and hands the newest to a SnapshotSink you supply.

You supply two things:

  • a TokenVerifier, which turns a join token into a Join: the room, the verified Identity and any room attributes;
  • a SnapshotSink, which loads a room's stored state when it opens and saves checkpoints.

Then serve the Handler and use the Hub around a publish:

hub := yjsrelay.New(sink, yjsrelay.WithLogger(logger))
mux.Handle("GET /rooms/{room}", yjsrelay.NewHandler(hub, verifier))

// before publishing: the sink must hold the newest content
if _, err := hub.Flush(ctx, docID); err != nil { ... }
// after publishing: editors drop to read-only
hub.Freeze(ctx, docID, "v7")

All state is in process memory: run one instance per document. Package protocol holds the wire encoders and decoders, for Go clients and tests.

Example
package main

/*
MIT License

Copyright (c) 2026 Shane

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"net/http/httptest"
	"strings"
	"sync"

	yjsrelay "github.com/Bugs5382/go-yjs-relay"
	"github.com/Bugs5382/go-yjs-relay/protocol"
	"github.com/gorilla/websocket"
)

// mapSink keeps checkpoints in a map. A real sink writes to a database or
// forwards the content to the service that owns it.
type mapSink struct {
	mu      sync.Mutex
	content map[string]string
}

func (s *mapSink) Load(context.Context, string) ([]byte, error) { return nil, nil }

func (s *mapSink) Save(_ context.Context, snap yjsrelay.Snapshot) error {
	if err := yjsrelay.ValidateLexicalJSON(snap.Content); err != nil {
		return &yjsrelay.RejectError{Reason: "invalid_content", Detail: err.Error()}
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	s.content[snap.Room] = string(snap.Content)
	fmt.Printf("saved %s for %s\n", snap.Room, snap.Author.UserID)
	return nil
}

func main() {
	// A verifier that trusts "room/user" tokens. Use a signed token in
	// production.
	verifier := yjsrelay.TokenVerifierFunc(func(_ context.Context, token string) (yjsrelay.Join, error) {
		room, user, ok := strings.Cut(token, "/")
		if !ok {
			return yjsrelay.Join{}, errors.New("bad token")
		}
		return yjsrelay.Join{Room: room, Identity: yjsrelay.Identity{UserID: user}}, nil
	})

	sink := &mapSink{content: map[string]string{}}
	hub := yjsrelay.New(sink)
	defer func() { _ = hub.Close(context.Background()) }()

	mux := http.NewServeMux()
	mux.Handle("GET /rooms/{room}", yjsrelay.NewHandler(hub, verifier))
	srv := httptest.NewServer(mux)
	defer srv.Close()

	// A client joins doc-1 and sends a checkpoint, the frame a browser editor
	// sends after a burst of edits.
	url := "ws" + strings.TrimPrefix(srv.URL, "http") + "/rooms/doc-1?token=doc-1/ann"
	conn, _, err := websocket.DefaultDialer.Dial(url, nil)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer func() { _ = conn.Close() }()
	_, _, _ = conn.ReadMessage() // the relay's opening Sync Step-1

	content := []byte(`{"root":{"type":"root","children":[]}}`)
	_ = conn.WriteMessage(websocket.BinaryMessage, protocol.EncodeSnapshot(content, nil))
	// A client's frames are handled in order, so once a presence frame sent
	// after the checkpoint is echoed back, the room has recorded it.
	presence := protocol.EncodeAwarenessUpdate([]protocol.AwarenessEntry{{ClientID: 1, Clock: 1, State: []byte(`{}`)}})
	_ = conn.WriteMessage(websocket.BinaryMessage, protocol.EncodeAwareness(presence))
	for {
		_, msg, _ := conn.ReadMessage()
		if t, _, _ := protocol.DecodeMessage(msg); t == protocol.MsgAwareness {
			break
		}
	}

	// Before publishing: the sink must hold the room's newest content.
	res, err := hub.Flush(context.Background(), "doc-1")
	fmt.Println("flushed:", res.ContentFlushed, "error:", err)

	// After publishing: every editor drops to read-only.
	fmt.Println("frozen:", hub.Freeze(context.Background(), "doc-1", "v1"))

}
Output:
saved doc-1 for ann
flushed: true error: <nil>
frozen: true

Index

Examples

Constants

View Source
const (
	// ReasonUnavailable marks a transient failure; the checkpoint is kept.
	ReasonUnavailable = "unavailable"
	// ReasonSinkError marks any other sink error. Its text stays server-side.
	ReasonSinkError = "sink_error"
)

Reasons the relay puts on a rejected checkpoint when the sink's error is not a *RejectError.

View Source
const (
	// DefaultDebounce is how long a room waits after the last snapshot frame
	// before it saves.
	DefaultDebounce = 5 * time.Second
	// DefaultReadLimit caps one inbound frame. It has to fit the largest
	// legitimate frame, a snapshot carrying the full content and the full
	// compacted state together. A proxy in front of the relay must allow
	// frames at least this large, or it closes big snapshots first.
	DefaultReadLimit int64 = 2 << 20
)

Variables

View Source
var (
	// ErrRejected matches a checkpoint the sink refused.
	ErrRejected = errors.New("yjsrelay: snapshot rejected")
	// ErrUnavailable matches a checkpoint the sink could not take right now.
	// A sink wraps it to mark a failure as transient.
	ErrUnavailable = errors.New("yjsrelay: snapshot sink unavailable")
	// ErrClosed is returned once the hub is closed.
	ErrClosed = errors.New("yjsrelay: hub closed")
)
View Source
var DefaultPalette = []string{
	"#D93D42",
	"#C2570C",
	"#9A6B00",
	"#2B8A3E",
	"#0B7A75",
	"#2563EB",
	"#7C3AED",
	"#C026D3",
}

DefaultPalette is the presence colours a user is assigned from. The relay picks one from the user id, so a user keeps their colour across sessions and cannot pick another user's. Presence carries the index too, so a client can map it onto a palette of its own (for example per theme).

Functions

func ValidateLexicalJSON

func ValidateLexicalJSON(content []byte) error

ValidateLexicalJSON is a cheap envelope check on a Lexical EditorState export, for a sink to run before it forwards content anywhere. It refuses empty input, malformed JSON, trailing data, a top-level value that is not an object, and a missing or non-object "root". It never looks at node types: deep validation belongs to whoever owns the content.

Types

type Codes

type Codes struct {
	Rejected    int
	Unavailable int
}

Codes are the caller's go-apperr codes for the errors Flush and Close return. A zero field leaves that error uncoded; the library never picks a code of its own.

type FlushError

type FlushError struct {
	Room   string
	Reason string
	// Detail is the RejectError's detail, empty for any other sink error.
	Detail string
	// Err is the sink's error.
	Err error
}

FlushError reports that the sink does not hold the room's newest checkpoint. It matches ErrUnavailable when the failure was transient and ErrRejected otherwise, and it unwraps to the sink's own error.

func (*FlushError) Error

func (e *FlushError) Error() string

func (*FlushError) Transient

func (e *FlushError) Transient() bool

Transient reports whether resending the same checkpoint may succeed.

func (*FlushError) Unwrap

func (e *FlushError) Unwrap() []error

Unwrap returns the matching sentinel and the sink's error.

type FlushResult

type FlushResult struct {
	// RoomFound is false when nobody is editing the document. That is not an
	// error: the sink already holds the newest content.
	RoomFound bool
	// ContentFlushed is true when the call saved a pending checkpoint.
	ContentFlushed bool
}

FlushResult reports what Flush found.

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler upgrades HTTP requests to relay sockets after the TokenVerifier accepts the join token.

func NewHandler

func NewHandler(hub *Hub, verifier TokenVerifier, opts ...HandlerOption) *Handler

NewHandler returns an http.Handler that admits clients to hub's rooms. The room id comes from the request (see WithRoomFunc), the token from a ?token= query parameter or an Authorization: Bearer header, and the token has to be for that room.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

type HandlerOption

type HandlerOption func(*handlerConfig)

HandlerOption configures a Handler.

func WithAllowedOrigins

func WithAllowedOrigins(origins ...string) HandlerOption

WithAllowedOrigins sets the browser Origin allowlist, compared case-insensitively against the whole Origin header (scheme, host and port). With none set, every request carrying an Origin header is refused with 403: the intended setup is a server-side proxy in front of the relay, which sends no Origin. A request without an Origin header is not a browser and is always allowed through to the token check.

func WithRoomFunc

func WithRoomFunc(f func(*http.Request) string) HandlerOption

WithRoomFunc sets how the handler reads the room id from a request. The default uses the {room} path value when the route has one, and the last path segment otherwise.

type Hub

type Hub struct {
	// contains filtered or unexported fields
}

Hub owns the live rooms, one per document id.

All of its state is in process memory. Two editors of one document who reach different processes get two rooms that never see each other, and both race to save. Run one replica per document: a single instance, or routing that pins a room id to one instance (a consistent hash at the ingress).

func New

func New(sink SnapshotSink, opts ...Option) *Hub

New returns a Hub that loads and saves room state through sink. A nil sink runs a pure relay: rooms start empty and checkpoints are dropped.

func (*Hub) Close

func (h *Hub) Close(ctx context.Context) error

Close saves every room's pending checkpoint, then disconnects every client and stops the rooms. New joins fail with ErrClosed. The error joins every room's flush error. Close is safe to call more than once.

func (*Hub) Flush

func (h *Hub) Flush(ctx context.Context, id string) (FlushResult, error)

Flush saves the room's pending checkpoint now and returns once the sink has answered, waiting out a debounced save already in flight. Call it before publishing a document, so the published version is never older than what the editors hold.

A non-nil error is a *FlushError: the sink does not hold the room's newest checkpoint, including a rejection no newer checkpoint has replaced yet, and the publish should not go ahead. Flush never opens a room.

func (*Hub) Freeze

func (h *Hub) Freeze(ctx context.Context, id, version string) bool

Freeze makes the room read-only, saves anything still pending, and sends every editor a room.frozen control frame carrying version, so editors stop typing into a document that can no longer change. Call it after the publish succeeded, so a failed publish never leaves a live room stuck read-only; Flush is the call that belongs before. It reports whether a room was live.

func (*Hub) Lookup

func (h *Hub) Lookup(id string) (RoomInfo, bool)

Lookup describes the live room for id. It never opens one, so "nobody is editing" stays distinguishable from "a room exists".

func (*Hub) RoomCount

func (h *Hub) RoomCount() int

RoomCount returns the number of live rooms.

type Identity

type Identity struct {
	// UserID is a stable, opaque user id. It is logged; keep personal data
	// out of it.
	UserID string
	// DisplayName is the presence label. Empty falls back to UserID. It is
	// never logged.
	DisplayName string
	// Attrs carry anything else the sink or observer needs about the user,
	// for example the admin acting on their behalf.
	Attrs map[string]string
}

Identity is a verified user. The relay is authoritative for it: presence carries it in place of anything the client asserts, and snapshots are attributed to it.

type Join

type Join struct {
	// Room is the room the token admits its holder to. Required.
	Room string
	// Identity is the verified user. Identity.UserID is required.
	Identity Identity
	// RoomAttrs describe the room (for example its tenant or the document
	// version it validates against). The first joiner's attrs are kept for
	// the room's life and handed to the sink with every snapshot.
	RoomAttrs map[string]string
}

Join is a verified join token.

type Option

type Option func(*config)

Option configures a Hub.

func WithCodes

func WithCodes(codes Codes) Option

WithCodes attaches the caller's go-apperr codes to the errors Flush and Close return.

func WithDebounce

func WithDebounce(d time.Duration) Option

WithDebounce sets how long a room waits after the last snapshot frame before it saves. The default is DefaultDebounce.

func WithLogger

func WithLogger(l log.Logger) Option

WithLogger sets the logger. The default discards everything.

func WithPalette

func WithPalette(colors []string) Option

WithPalette replaces DefaultPalette. An empty palette is ignored.

func WithReadLimit

func WithReadLimit(n int64) Option

WithReadLimit caps one inbound frame in bytes; a larger frame closes the connection. The default is DefaultReadLimit.

func WithSessionObserver

func WithSessionObserver(o SessionObserver) Option

WithSessionObserver reports every join and leave to o.

type RejectError

type RejectError struct {
	Reason string
	Detail string
}

RejectError is how a sink refuses a checkpoint with a reason the editors may see. Reason is a stable token and Detail a human-readable cause; both travel to every editor in the room in a snapshot.rejected control frame.

func (*RejectError) Error

func (e *RejectError) Error() string

func (*RejectError) Is

func (e *RejectError) Is(target error) bool

Is makes a *RejectError match ErrRejected.

type RoomInfo

type RoomInfo struct {
	ID string
	// Attrs are the first joiner's Join.RoomAttrs.
	Attrs map[string]string
	// Editors is the number of connected clients.
	Editors int
	// Frozen is true after Freeze.
	Frozen bool
}

RoomInfo describes a live room.

type Session

type Session struct {
	Room      string
	RoomAttrs map[string]string
	Identity  Identity
}

Session is one client's membership of a room.

type SessionObserver

type SessionObserver interface {
	SessionJoined(ctx context.Context, s Session)
	SessionLeft(ctx context.Context, s Session)
}

SessionObserver hears clients join and leave rooms, for example to write an audit trail. Calls run on their own goroutine, so a slow observer never stalls a room.

type Snapshot

type Snapshot struct {
	Room      string
	RoomAttrs map[string]string
	// Content is the editor's export (for example Lexical JSON). It is the
	// authoritative copy of the document; the relay passes it through
	// untouched. It may be empty when a client sent only state.
	Content []byte
	// State is the client's compacted Y.encodeStateAsUpdate(doc), stored so
	// a room can rehydrate after a restart. The relay never decodes it. It
	// may be empty when a client sent only content.
	State []byte
	// Author is the verified identity of the connection that sent it.
	Author Identity
}

Snapshot is one client checkpoint, sent by the debounce, by Flush, by Freeze, or when the last client leaves.

type SnapshotSink

type SnapshotSink interface {
	// Load returns the room's last stored state, or nil when there is none.
	// It runs once when a room opens; an error refuses the join.
	Load(ctx context.Context, room string) ([]byte, error)

	// Save stores a checkpoint. A nil error tells the editors it is durable.
	// Return a *RejectError to refuse it with a reason the editors may see,
	// or an error matching ErrUnavailable (or a context error) when the
	// failure says nothing about the content, so the relay keeps the
	// checkpoint for a retry. Any other error refuses it without showing the
	// editors its text.
	Save(ctx context.Context, snap Snapshot) error
}

SnapshotSink is where a room's checkpoints go. It is the caller's code: a database row, an object store, an upstream service that validates the content, or several of those.

type TokenVerifier

type TokenVerifier interface {
	// Verify returns who is joining which room, or an error to refuse the
	// connection with 401. Join.Room must name the room the token was issued
	// for; the handler refuses a token used against any other room.
	Verify(ctx context.Context, token string) (Join, error)
}

TokenVerifier checks the join token a client presents, as a ?token= query parameter or an Authorization: Bearer header. It is the caller's code: signed JWTs, opaque session lookups or anything else. The relay never parses the token itself and never logs it.

type TokenVerifierFunc

type TokenVerifierFunc func(ctx context.Context, token string) (Join, error)

TokenVerifierFunc adapts a function to TokenVerifier.

func (TokenVerifierFunc) Verify

func (f TokenVerifierFunc) Verify(ctx context.Context, token string) (Join, error)

Verify calls f.

Directories

Path Synopsis
internal
debounce
Package debounce coalesces a burst of calls into one delayed callback.
Package debounce coalesces a burst of calls into one delayed callback.
Package protocol encodes and decodes the y-websocket wire frames the relay speaks, plus two extension frames of its own.
Package protocol encodes and decodes the y-websocket wire frames the relay speaks, plus two extension frames of its own.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL