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 ¶
- Constants
- Variables
- func ValidateLexicalJSON(content []byte) error
- type Codes
- type FlushError
- type FlushResult
- type Handler
- type HandlerOption
- type Hub
- type Identity
- type Join
- type Option
- type RejectError
- type RoomInfo
- type Session
- type SessionObserver
- type Snapshot
- type SnapshotSink
- type TokenVerifier
- type TokenVerifierFunc
Examples ¶
Constants ¶
const ( 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.
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 ¶
var ( // ErrRejected matches a checkpoint the sink refused. ErrRejected = errors.New("yjsrelay: snapshot rejected") // 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") )
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 ¶
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
}
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.
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 ¶
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 ¶
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 ¶
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.
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 ¶
WithCodes attaches the caller's go-apperr codes to the errors Flush and Close return.
func WithDebounce ¶
WithDebounce sets how long a room waits after the last snapshot frame before it saves. The default is DefaultDebounce.
func WithLogger ¶
WithLogger sets the logger. The default discards everything.
func WithPalette ¶
WithPalette replaces DefaultPalette. An empty palette is ignored.
func WithReadLimit ¶
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 ¶
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 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.
Source Files
¶
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. |