collab

package module
v0.26.1 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: BSD-3-Clause Imports: 27 Imported by: 4

README

go-crdt/collab

collab — the wire for collaborative editing

CI Go Reference coverage license

github.com/go-crdt/collab carries a go-crdt/crdt document between the people editing it: a gRPC service, a server that hosts documents, and a client that joins one. Pure Go, CGO=0.

The service is thin on purpose. The document is a CRDT, so the server never transforms an operation and never decides an outcome — it applies what it is sent to its own replica and hands it to everyone else. Two things follow that a server-authoritative design cannot offer: a participant may edit while disconnected and reconcile on return, and the server may be restarted or replaced without anyone losing work.

The client builds for js/wasm, so a browser tab and the server run the same code down to the merge — over either of two carriers, from one server:

carrier for browser client, gzipped
collab.WebSocket — the session's own framing anywhere, browsers included 919 KB
collab.GRPC — over gRPC native peers 4 461 KB

Everything a session carries is already bytes crdt encoded and will check on arrival, so protobuf describes fields nobody reads through it — and compiled to wasm its machinery cannot be linked away. For scale, the CRDT alone is 633 KB. Outside a browser none of that matters, which is why gRPC is still there.

From a page

The editor this was built for is TypeScript and cannot call Go, so ./wasm compiles to a binding a page uses directly. Offsets are UTF-16 code units throughout — the units a JavaScript string counts in — and an offset splitting a character is refused rather than rounded:

const session = await collab.join({ url, document: "project:default", site });

const body  = await session.text("file:main.tex");
const chat  = await session.list("chat");
const cells = await session.map("cells");

await body.insert(0, "bonjour");
await cells.set("B7", new TextEncoder().encode("42"));

await session.onChange(parts => {
  for (const part of parts) {
    if (part.kind === "text") applyEdits(part.text);   // {pos, removed, insert}
    if (part.kind === "map")  reread(part.keys);       // the keys that changed
    if (part.kind === "list") rereadWhole(part.name);  // a list says only that it moved
  }
});

Types are in wasm/collab.d.ts. A value is Uint8Array in both directions, never a string and never JSON: the CRDT does not interpret it and neither does the binding.

Keeping what people wrote

A document was saved when its last participant left, and otherwise when somebody called Flush. That is enough for a text people open and close, and not enough for what a session actually carries — the comments on it, the record of who changed what, the messages beside it. A server restarted while anybody was still connected lost everything since the document was opened, and said nothing.

store, err := collab.NewDirStore("/var/lib/loom/documents")

srv := collab.NewServer(collab.Config{
    Store:        store,
    PersistEvery: 5 * time.Second,  // bounds what a crash costs
    EvictAfter:   10 * time.Minute, // let go of what nobody is in
})
defer srv.Close(ctx)

DirStore keeps a document per file, written and renamed into place so a reader sees one whole version or the one before. The file is named after the encoding of the document name rather than the name: project:default and file:src/main.tex are not file names, and escaping them would leave the question of which characters, on which system. Documents() says what the file names cannot.

Neither runs unless it is asked for, so a server configured as before behaves as before. EvictAfter also stops a long-lived server holding every document it has ever served; reopening one costs a read from the store, not anything anybody wrote.

Using it

Server — any grpc.Server, any carrier:

srv := collab.NewServer(collab.Config{Store: myStore})
collabpb.RegisterCollabServer(grpcServer, srv)

Participant. A document holds named parts, so a caller reaches for the one it means and gets a handle that edits and publishes:

c, err := collab.Join(ctx, conn, collab.ClientConfig{Document: "notes", Site: 1})

body, _ := c.Text("file:main.tex")   // the buffer an editor binds to
chat, _ := c.List("chat")            // the messages beside it
cells, _ := c.Map("cells")           // a sheet

body.Insert(0, "hello")
chat.Append([]byte("on commence"))
cells.Set("B7", []byte("42"))
c.SetCursor(awareness.Cursor{Anchor: 5, Head: 5}, map[string]string{"name": "ada"})

for range c.Changes() {
    for _, part := range c.TakeChanges() {   // which part moved, and how
        render(part)
    }
    render(c.Peers())
}

A handle is what a caller touches rather than the replicated structure, and that is forced: editing the structure directly would produce operations nobody ever heard, so the participant would drift away from everyone else while its own screen looked right.

Coming back after a disconnection, keeping the work done offline:

c, err := collab.Join(ctx, conn, collab.ClientConfig{
    Document: "notes",
    Site:     1,
    Resume:   savedSnapshot, // from Client.Snapshot()
})

Shape of a session

One bidirectional stream per participant per document. The client opens with a Join; the server answers with a Welcome holding either the whole document or, for a participant that says what it already has, only what it missed — plus who else is present and where the server stands, so the participant can push whatever it wrote while away. After that, operations and presence flow both ways.

What it guarantees

  • Convergence, proven end to end. The acceptance test runs three replicas across two runtimes — one native, two compiled to WebAssembly and executed by Node through a real WebSocket — editing concurrently and converging on the same text.
  • Offline work is never stranded. A resuming participant pushes what the server lacks and is sent what it missed. Both directions are tested.
  • Nobody stalls the document. A participant that stops reading is disconnected with ResourceExhausted and caught up when it rejoins, rather than holding everyone up or being served state that is quietly out of date.
  • Nothing is trusted. Malformed operations, presence, version vectors and snapshots are each refused with InvalidArgument, on both sides of the wire.
  • One replica identity per participant. Two participants sharing a site is silent data loss rather than a conflict — both mint the same operation identities for different characters — so the arriving session takes the identity and the one already holding it is disconnected with Aborted. Site zero, the server's own replica, is refused outright.
  • Documents outlive sessions. The last participant out writes the document; Server.Flush writes it without waiting. A write that fails is retried rather than forgotten.

What a binding needs

An editor cannot be handed the whole text on every keystroke somebody else makes: that throws away the selection, the scroll position and every decoration. Changes says something happened, TakeChanges says what — the edits, in the order they have to be made.

c.TakeChanges()      // []crdt.Change: remove this many here, put this there
c.Anchor(pos)        // a handle on a character, for a comment or a stored selection
c.Position(anchor)   // where it is now, or where it was if it has gone
c.AuthorRuns()       // the text split by who wrote each stretch
c.InsertUTF16(pos, text)  // offsets in the units a browser counts

A browser counts UTF-16 code units, and an emoji is one character and two units. A session that took the browser's offsets for runes would edit in the wrong place, silently, from the first emoji onwards — so the same operations are addressed both ways, and an offset landing inside a character is refused rather than moved.

Who may open what

Config.Authorize is asked once per session, after the join arrives and before the document is touched, so a refused session neither reads the store nor reveals whether the document exists:

collab.NewServer(collab.Config{
    Authorize: func(ctx context.Context, document string, site crdt.SiteID) error {
        return myACL.Check(userFrom(ctx), document)
    },
})

It lives here rather than in a gRPC interceptor, which is where one would first look for it: an interceptor sees the method and the request metadata, and the document being joined is in neither — it arrives in the stream's first message. Authentication, being per connection rather than per document, still belongs in an interceptor; the context carries whatever it put there.

Persistence

Store is a two-method seam — Load and Save on snapshots, which are self-contained, so a document restored from one can still serve a participant that has been away. MemoryStore is the default.

collab/pgstore keeps documents in PostgreSQL, over a plain *sql.DB and with no driver of its own, so the caller picks one:

db, _ := sql.Open("pgx", os.Getenv("DATABASE_URL"))
store, _ := pgstore.New(db)
store.Migrate(ctx)
srv := collab.NewServer(collab.Config{Store: store})

It is a module of its own, so importing collab does not drag a database driver into anyone's build. Its tests run against a real PostgreSQL — CI fails the job if one is missing rather than skipping it.

collab/gitstore keeps documents in a git repository, so a document can be versioned and released the way everything else is. One commit holds both the state, which carries identities and authorship and the comments anchored to characters, and the rendered text, which is what makes the repository readable by a person. A release is a tag on a commit that already exists. It is also a federation channel: two servers sharing a repository diverge, git reports a conflict on the state file, and gitstore.Merge resolves it without anybody having to choose a side.

MultiStore writes to several stores at once and reads from all of them:

srv := collab.NewServer(collab.Config{
    Store: collab.NewMultiStore(database, repository),
})

Reading merges rather than picking, because a save that failed halfway leaves the stores holding different documents and taking the first would drop whatever only the second had — MergeSnapshots is what makes that free. Adding a store to a running server therefore backfills it. A store that cannot be read fails the load rather than serving a document quietly missing a paragraph.

Tiered is the other composition: a hot store for documents somebody is using and a cold one for documents nobody has opened in a long time.

store := collab.NewTiered(hot, archive)
srv := collab.NewServer(collab.Config{Store: store})

// On a timer, or by hand.
moved, err := store.Archive(ctx, 30*24*time.Hour)

Nothing is deleted that is not already somewhere else. Archiving reads the hot store, writes the cold one, and only then asks the hot one to release exactly what was read — so a cold store that refuses releases nothing, and a document that somebody saved while it was being copied is not released at all; it is archived on a later pass. Reading an archived document brings it back to the hot store on the way past.

A Tiered store never answers "no such document" because it could not reach the archive: nil means start a new one, and a server acts on it. An unreachable archive fails the load instead.

What counts as idle is not written for a while, which is as close to not used as a store can get — and close enough, because a server saves a document somebody is in every PersistEvery, so a busy document never looks quiet. MemoryStore and DirStore both implement Archivable; Config.EvictAfter is the same idea one level up, for the server's memory rather than the store's.

Status

Version 0.1. 100% statement coverage, race-clean, six-arch CI, and the WebAssembly end-to-end test running on every pull request — where a missing toolchain is a failure, not a skipped test.

License

BSD-3-Clause — see LICENSE. Copyright the go-crdt authors.

Documentation

Overview

Package collab carries a github.com/go-crdt/crdt document between the people editing it: a gRPC service, a server that hosts documents, and a client that joins one.

The service is thin on purpose. The document is a CRDT, so the server never transforms an operation and never decides an outcome — it applies what it is sent to its own replica and hands it to everyone else. Two consequences follow that a server-authoritative design cannot offer: a participant may edit while disconnected and reconcile later, and the server may be restarted or replaced without any client losing work.

Over what

Two carriers, and which one to use is decided by where the code runs rather than by taste. WebSocket carries a session's own framing over a plain WebSocket; [GRPC] carries it over gRPC. One server serves both at once — [Server.ServeWebSocket] beside the registered service — and a participant on each edits the same document.

The reason there are two is measured. Everything a session carries is bytes some encoder in github.com/go-crdt/crdt produced and will check on arrival, so protobuf is describing fields nobody reads through it — and compiled to wasm its reflection and registry machinery cannot be linked away. The browser test client, gzipped, is 919 KB over the framing and 4 461 KB over gRPC, against 633 KB for the CRDT alone. Outside a browser none of that matters, and gRPC brings deadlines, interceptors and the tooling built around them.

The client builds for js/wasm either way, so a browser tab and a server run the same code down to the merge. Two browsers with no server between them carry a session over a WebRTC data channel (DataChannel), and two tabs of one browser over a BroadcastChannel (JoinBroadcastChannel) with nothing to configure at all.

A document holds named parts

What an editor holds is not one structure: the text of a file, the comments anchored into it, the record of who changed what, the messages beside it, the cells of a sheet. A document here is a github.com/go-crdt/crdt.Composite, so they travel together — one snapshot, one version, one decision about who may open it, and no instant at which the set of them disagrees.

A caller reaches for a part by name and gets a handle: Client.Text, Client.List, Client.Map. A handle edits and publishes in one step, which is why it exists rather than the replicated structure itself — a caller editing that directly would produce operations nobody ever heard, and drift away from everyone else while its own screen looked right.

Shape of a session

One bidirectional stream per participant per document. The client opens with a [collabpb.Join]; the server answers with a [collabpb.Welcome] holding either the whole document or, for a participant that says what it already has, only what it missed. After that, operations and presence flow both ways until either side hangs up.

Index

Constants

View Source 
const DefaultBacklog = 256

DefaultBacklog is how many messages may be queued for one participant before the server gives up on it. See Config.

It is also, and less obviously, a capacity: a document where P participants edit in the same breath sends P-1 messages to each of them, so a backlog below P is a backlog that will be exceeded. Measured on one server with 800 participants each making one edit at once — a backlog of 256 disconnected 99% of them, 512 disconnected 32%, and 1024 disconnected none.

So 256 means "about two hundred and fifty people editing at the same instant", not "a queue that is usually long enough". A document with more than that wants a larger Config.Backlog, and the cost of one is a queue slot per participant rather than anything per document.

View Source 
const DefaultElectionWindow = 250 * time.Millisecond

DefaultElectionWindow is how long HostOrJoin listens before concluding no tab is already hosting. It is generous next to a same-origin round trip so that two tabs opening together reliably see each other's announcements and settle the host between them by the rule in [electRole].

Variables

View Source 
var ErrBroadcastClosed = errors.New("collab: broadcast channel closed")

ErrBroadcastClosed is why a BroadcastChannel carrier's [Recv] or [Send] returned: this end was closed, or the bus it spoke over was. It is the shared-bus counterpart of the error a dropped socket reports.

View Source 
var ErrChanged = errors.New("collab: the document changed since it was read")

ErrChanged reports a document that was written since it was read, so it was not released. It is not a failure: the next pass will archive the newer one.

View Source 
var ErrClosed = errors.New("collab: session closed")

ErrClosed is why a session ended when this participant closed it, and what an edit made afterwards returns.

View Source 
var ErrHostSuperseded = errors.New("collab: another tab is hosting this room")

ErrHostSuperseded is why a host's serve loop returned: another tab with a lower identifier — the one the tie-break gives priority — announced itself as host, so this tab steps down to let that one hold the room. It is the self-healing half of the election: even if two tabs ever both reach RoleHost, exactly one keeps the document and the other yields, rather than the two drifting apart as separate documents. A caller that hosts should, on this error, re-join the room (it will now find the surviving host answering) rather than treat it as a failure.

View Source 
var ErrPipeClosed = errors.New("collab: pipe closed")

ErrPipeClosed is why a Pipe carrier's [Recv] or [Send] returned: either end was closed, or the session's context was cancelled. It is the in-process counterpart of the error a dropped socket reports.

View Source 
var ErrProtocol = errors.New("collab: unexpected message")

ErrProtocol reports a message that is not part of a session: a kind that cannot arrive at that moment — a second welcome, or a join halfway through — or bytes that are not a message at all.

View Source 
var ErrTransport = errors.New("collab: transport")

ErrTransport reports a carrier that could not be opened or that failed.

Functions

func MergeSnapshots added in v0.24.0 

func MergeSnapshots(ours, theirs []byte) ([]byte, error)

MergeSnapshots combines two snapshots of the same document into one that holds everything either of them held.

It is the operation that makes a snapshot safe to keep in more than one place. Two copies of a document that were written separately have not disagreed about anything — a snapshot is a set of operations, and the union of two sets of operations is a document, which is the whole reason this project exists. Nothing here has to choose a side, and so nothing here can lose what the other side did.

Either argument may be nil, which is how a store says it has never held the document; merging with nothing gives back the other side. Merging is symmetric to the byte, because the snapshot encoding is canonical and both results hold the same operations.

func Pipe added in v0.21.0 

func Pipe() (Transport, *PipeConn)

Pipe returns the two ends of an in-process session: a Transport to hand to Join, and a handle to hand to Server.ServePipe. Nothing leaves the process — messages are carried on Go channels rather than a socket — so it is how a peer that both serves a document and edits it locally binds its own editor to that document without opening a loopback connection to itself.

What it is for

A browser tab holding a document for others over a data channel is also a place someone is typing. Its own editor is a participant like any other, and the honest way to say so is to Join the document it is serving. Without this that means a second, real carrier looping back to the same page — a WebRTC data channel to itself, dialled, answered and encrypted, to carry bytes that never cross a wire. Pipe is that participant with the carrier taken out: the same session, the same merge, over two channels and nothing else.

The same holds for a native server that wants a replica of a document it hosts — a headless editor, a linter, an exporter — without the cost of a second server or the round trip of a real link.

Shape

The two ends are one session and share its fate: closing either, or cancelling the context Join or Server.ServePipe was given, ends both. A [Recv] blocked when that happens returns ErrPipeClosed, and a [Send] after it does the same, so neither end can be left waiting on a peer that has gone.

A participant here edits the same document as one arriving over WebSocket or [GRPC]; it is a first-class participant, not a shortcut with less to it.

Types

type Archivable added in v0.26.1 

type Archivable interface {
	Store

	// Idle returns the documents this store has not been asked to write for
	// longer than d.
	//
	// Not written is the closest thing to not used that a store can know, and
	// it is close enough for the reason that matters: a server persists a
	// document somebody is in every [Config.PersistEvery], so a document with
	// anybody in it is written constantly and never looks idle. What looks idle
	// is what nobody has opened since it was last put away.
	Idle(ctx context.Context, d time.Duration) ([]string, error)

	// Release forgets a document, but only if this store still holds exactly
	// want. It reports [ErrChanged] if it holds something else, and nil if it
	// held nothing.
	//
	// The condition is the whole of it. An archiver copies a document
	// elsewhere and then asks for it to be released, and between those two
	// moments somebody may have joined the document and saved a newer one. A
	// store that released it anyway would delete a version that is nowhere
	// else. The comparison and the removal therefore happen together, under
	// whatever the store uses to keep its own writes apart.
	Release(ctx context.Context, document string, want []byte) error
}

An Archivable store can say which of its documents have gone quiet and let one go, which is what it takes to be the hot half of a Tiered.

Both methods are here rather than in Store because most stores have no business implementing them: a store that is only ever written through is complete with Load and Save, and asking every one of them for a way to forget a document would be asking for a way to lose one.

type BroadcastSession added in v0.26.1 

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

A BroadcastSession is a zero-config same-browser endpoint that has already elected its role and is live: a host that is answering hellos, or a client that has dialled its host — both on ONE BroadcastChannel and identity, kept from the election through to serving. That is what closes the serve-gap: an elected host answers the moment it wins, so a second tab opening while the first is still wiring its Server is welcomed rather than left to elect itself a rival host.

func OpenBroadcastSession added in v0.26.1 

func OpenBroadcastSession(ctx context.Context, room string, window time.Duration) (*BroadcastSession, error)

OpenBroadcastSession opens the room's BroadcastChannel, elects host or client on it, and returns a live BroadcastSession holding that decision — the gap-free replacement for HostOrJoin followed by a fresh bus. A host is already answering hellos and beaconing; a client has already dialled its host. ctx bounds the election (and, for a client, the dial); window is the election window — pass DefaultElectionWindow.

A page that hosts builds its Server and calls BroadcastSession.Serve; a page that joins calls Join with BroadcastSession.Transport. Either way ctx is the session's lifetime — cancel it to tear down — and BroadcastSession.Close releases the channel if the role is abandoned before serving or joining.

func (*BroadcastSession) Close added in v0.26.1 

func (bs *BroadcastSession) Close() error

Close releases the channel for a session abandoned before it served or joined (a host that hit a setup error before BroadcastSession.Serve); once serving or joined, the session's own teardown closes it.

func (*BroadcastSession) Role added in v0.26.1 

func (bs *BroadcastSession) Role() Role

Role is whether this tab elected to host the document or to join one.

func (*BroadcastSession) Serve added in v0.26.1 

func (bs *BroadcastSession) Serve(s *Server) error

Serve holds the document for the room: it wires s into the answerer that has been welcoming and buffering tabs since the election, so those tabs' sessions begin at once, and blocks until the room is torn down (its ctx cancelled). It returns ErrHostSuperseded if another tab with priority took over the room, on which the caller should re-join rather than treat it as a failure. It is a no-op error for a client session.

func (*BroadcastSession) Transport added in v0.26.1 

func (bs *BroadcastSession) Transport() Transport

Transport hands the already-dialled host connection to Join for a client session, so joining reuses the carrier the election opened rather than dialling again. It is nil-safe to call on a host session, returning a transport whose open fails.

type Client 

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

A Client is one participant's view of a document: a replica that edits locally and is kept in step with everyone else.

It is safe for concurrent use. It builds for js/wasm, so a browser tab runs this code and the server's merge logic unchanged.

func Join 

func Join(ctx context.Context, transport Transport, cfg ClientConfig) (*Client, error)

Join opens a session over transport and returns once the document has arrived, so the client is usable the moment it is returned.

Use WebSocket unless there is a reason not to; it is what the same code compiled for a browser can afford. [GRPC] is there for a native peer that wants what gRPC brings with it.

The session lives until ctx is cancelled or Client.Close is called.

func (*Client) Changes 

func (c *Client) Changes() <-chan struct{}

Changes receives a value whenever the document or the participants changed. It coalesces: a reader that is slow sees one wake-up, not a queue of them.

func (*Client) Close 

func (c *Client) Close() error

Close ends the session. The local document is left intact, so its Client.Snapshot can resume later.

func (*Client) Document 

func (c *Client) Document() string

Document returns the name of the document joined.

func (*Client) Done 

func (c *Client) Done() <-chan struct{}

Done is closed when the session has ended, whatever the reason.

func (*Client) Err 

func (c *Client) Err() error

Err returns why the session ended, or nil while it is still running. Once Client.Done is closed it is never nil: a session that was closed deliberately reports ErrClosed rather than the transport's cancellation.

func (*Client) List added in v0.10.0 

func (c *Client) List(name string) (*List, error)

List returns a handle on the list part with this name.

func (*Client) Map added in v0.10.0 

func (c *Client) Map(name string) (*Map, error)

Map returns a handle on the map part with this name.

func (*Client) Parts added in v0.10.0 

func (c *Client) Parts() []crdt.Part

Parts returns the parts this replica holds, in the canonical order. A part that has never been written to is not among them.

func (*Client) Peers 

func (c *Client) Peers() []awareness.Peer

Peers returns the other participants and where their cursors are, ordered by site.

func (*Client) SetCursor 

func (c *Client) SetCursor(cursor awareness.Cursor, meta map[string]string) error

SetCursor publishes where this participant is. meta carries whatever the editor wants shown — a display name, a colour — and is not interpreted here.

Cursor positions are ephemeral and are never persisted.

func (*Client) Site 

func (c *Client) Site() crdt.SiteID

Site returns this participant's replica identity.

func (*Client) Snapshot 

func (c *Client) Snapshot() []byte

Snapshot returns the document in a form ClientConfig.Resume accepts, which is how a participant keeps its place across a disconnection.

func (*Client) TakeChanges added in v0.7.0 

func (c *Client) TakeChanges() []crdt.PartChange

TakeChanges returns the edits made by everyone else since it was last called, in the order a view of the text has to make them, and forgets them.

It pairs with Client.Changes: that says something happened, this says what. A view that only ever applies these holds what the document holds — see crdt.Change.

Local edits are not reported. A caller that made them already knows.

func (*Client) Text 

func (c *Client) Text(name string) (*Text, error)

Text returns a handle on the text part with this name, which is created the first time anybody writes to it. The name is arbitrary UTF-8 and is expected to carry structure — "file:src/main.tex". An empty or invalid name is refused; see crdt.Part.

func (*Client) Version 

func (c *Client) Version() crdt.CompositeVersion

Version returns what this participant holds, for ClientConfig.Resume or for diagnostics.

type ClientConfig 

type ClientConfig struct {
	// Document names the document to join. It is created if it does not exist.
	Document string

	// Site is this participant's replica identity, and must differ from every
	// other participant's in the document. See [crdt.DeriveSiteID].
	Site crdt.SiteID

	// Resume is a snapshot from an earlier session, obtained from
	// [Client.Snapshot]. When set, the participant keeps the work it did while
	// disconnected and is sent only what it missed, rather than the whole
	// document.
	Resume []byte
}

ClientConfig describes a participant joining a document.

type Config 

type Config struct {
	// Store keeps documents between sessions. Defaults to a [MemoryStore].
	Store Store

	// Backlog is how many messages may be queued for one participant.
	// A participant that falls further behind than this is disconnected with
	// ResourceExhausted rather than served stale state or allowed to stall
	// everyone else; it rejoins and is caught up from its version vector.
	// Defaults to [DefaultBacklog].
	//
	// Size it against the number of participants who may edit at once, not
	// against how fast one of them types: one edit by each of P participants is
	// P-1 messages into every queue, so a burst on a busy document reaches the
	// limit in an instant however well everyone is keeping up. See
	// [DefaultBacklog] for what that costs, measured.
	//
	// Note what "it rejoins" asks of a caller. Nothing here rejoins: the
	// material is there — [Client.Snapshot] and [ClientConfig.Resume] — and the
	// loop belongs to whoever is holding the session, the same way it does for
	// [Server.Follow] and for the same reason. A caller that does not write one
	// turns a burst into a disconnection nobody recovers from.
	Backlog int

	// PersistEvery, when set, saves every document that has changed at this
	// interval, whoever is connected. Without it a document is saved when its
	// last participant leaves and when [Server.Flush] is called, so a server
	// restarted while anybody was still editing loses everything since the
	// document was opened.
	//
	// It bounds what a crash costs to this interval, which is a number an
	// operator can choose. A server that sets it must be closed with
	// [Server.Close], which stops the housekeeping and saves what is left.
	PersistEvery time.Duration

	// EvictAfter, when set, persists a document nobody has been in for this long
	// and lets go of it. Without it a long-lived server holds every document it
	// has ever served.
	//
	// A document is reloaded from the store the next time somebody joins it, so
	// evicting costs a read rather than anything anybody wrote.
	EvictAfter time.Duration

	// OnEvictError, when set, is told about a document that could not be saved
	// as it was evicted. There is nobody left to return an error to, and the
	// document cannot be kept — a session may already have opened a fresh
	// replica of it — so this is the only place that failure can be seen.
	OnEvictError func(document string, err error)

	// OnPersistError, when set, is called for every document whose periodic
	// save failed, with the error the store gave.
	//
	// Without it a server that cannot write is silent about it. The saves go on
	// being attempted and go on failing, participants go on editing and are
	// told nothing, and the work is there until the process stops and then is
	// not. A disk that filled up, a name a filesystem will not take, a
	// credential that expired: all of them look exactly like a server that is
	// working, which is the worst way for durability to fail.
	//
	// It is called from the housekeeping goroutine, once per document per pass,
	// so an implementation that blocks delays the next pass. Counting or
	// logging is what it is for; recovery is the operator's.
	//
	// [Server.Flush] does not call it — a caller that asks for a flush is given
	// the error to handle.
	OnPersistError func(document string, err error)

	// Clock is what [Config.EvictAfter] measures with. It defaults to time.Now,
	// and exists because a caller that wants a monotonic source, or a test that
	// wants to reach an hour of idleness without waiting an hour, has nowhere
	// else to say so. It is read from more than one goroutine, so it must be
	// safe for concurrent use and must be given here rather than set afterwards.
	Clock func() time.Time

	// Authorize, when set, decides whether a participant may open a document.
	// It is asked once per session, after the join arrives and before the
	// document is touched, so a refused session neither reads the store nor
	// reveals whether the document exists.
	//
	// This belongs here rather than in a gRPC interceptor, which is where one
	// would first look for it: an interceptor sees the method and the request
	// metadata, and the document being joined is in neither — it arrives in the
	// stream's first message. Anything deciding per document has to run after
	// that message, which means here. Authentication, which is per connection
	// rather than per document, still belongs in an interceptor; ctx carries
	// whatever it put there.
	//
	// Returning a gRPC status error passes that status to the participant
	// unchanged; any other error is reported as PermissionDenied.
	Authorize func(ctx context.Context, document string, site crdt.SiteID) error

	// AuthorizeOperations, if set, is asked about every batch a session sends,
	// and refusing ends the session.
	//
	// Authorize runs once, when somebody joins, and decides whether that site
	// may be in this document. That is the whole story for a participant: a
	// participant speaks for itself, and the site it joined as is the site its
	// operations carry.
	//
	// It is not the whole story for a link. [Server.Follow] joins as one site
	// and then relays the work of everyone on the server it follows, so what
	// arrives on a link names sites this server never authorised — thousands of
	// them, belonging to an institution rather than to a person. Inside one
	// deployment that is exactly right and there is nothing to decide. Between
	// two, it is the decision: whether this link may speak for those sites.
	//
	// from is the site the session joined as. batches carry the operations it
	// is asking to add, each naming the site that made it, so a policy can be
	// written about the relationship between the two — "this link may carry
	// operations for sites derived within lyon.ac.example" — which is what an
	// interfederation has scopes for.
	//
	// It runs after the operations have been decoded and before any of them is
	// applied, so a refused batch changes nothing. Returning a gRPC status
	// error passes that status on unchanged, as Authorize does.
	AuthorizeOperations func(ctx context.Context, document string, from crdt.SiteID, batches []crdt.PartOps) error
}

Config configures a Server.

type ICEServerAuth added in v0.20.0 

type ICEServerAuth struct {
	URLs       []string
	Username   string
	Credential string
}

ICEServerAuth is one STUN/TURN server with long-term credentials. URLs holds one or more server URLs that share the same Username and Credential — the form a TURN relay needs. It is the credentialed counterpart of a bare ICEServers URL, mirroring one { urls, username, credential } entry of an RTCPeerConnection's iceServers.

type List added in v0.10.0 

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

A List is a handle on one list part — comments, a change log, the messages beside a document.

func (*List) Append added in v0.10.0 

func (l *List) Append(values ...[]byte) error

Append adds values after the last one, which is what a chat or a log does.

func (*List) Delete added in v0.10.0 

func (l *List) Delete(pos, count int) error

Delete removes count values from index pos.

func (*List) Get added in v0.10.0 

func (l *List) Get(pos int) ([]byte, error)

Get returns a copy of the value at index pos.

func (*List) Insert added in v0.10.0 

func (l *List) Insert(pos int, values ...[]byte) error

Insert adds values at index pos, locally and then everywhere.

func (*List) Len added in v0.10.0 

func (l *List) Len() int

Len returns how many values are present.

func (*List) Name added in v0.10.0 

func (l *List) Name() string

Name returns the part's name.

func (*List) Part added in v0.10.0 

func (l *List) Part() crdt.Part

Part names this handle's part.

func (*List) Values added in v0.10.0 

func (l *List) Values() [][]byte

Values returns copies of every value present, in order. It is what a view of a list reads when it is told the list changed; see crdt.PartChange.

type Map added in v0.10.0 

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

A Map is a handle on one map part, such as the cells of a sheet.

func (*Map) Delete added in v0.10.0 

func (m *Map) Delete(key string) error

Delete removes key, locally and then everywhere. It writes a tombstone whether or not this replica holds the key; see crdt.Map.

func (*Map) Get added in v0.10.0 

func (m *Map) Get(key string) ([]byte, bool)

Get returns a copy of the value at key, and whether the key is present. It is what a view reads for each key a crdt.PartChange names.

func (*Map) Keys added in v0.10.0 

func (m *Map) Keys() []string

Keys returns the keys present, ascending.

func (*Map) Len added in v0.10.0 

func (m *Map) Len() int

Len returns how many keys are present, not counting deleted ones.

func (*Map) Name added in v0.10.0 

func (m *Map) Name() string

Name returns the part's name.

func (*Map) Part added in v0.10.0 

func (m *Map) Part() crdt.Part

Part names this handle's part.

func (*Map) Set added in v0.10.0 

func (m *Map) Set(key string, value []byte) error

Set stores value at key, locally and then everywhere.

type MemoryStore 

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

MemoryStore keeps documents in memory. It is the default, it is what the tests use, and it is enough for a single process that does not need to survive a restart. Anything else — Postgres, object storage — implements Store.

func NewMemoryStore 

func NewMemoryStore() *MemoryStore

NewMemoryStore returns an empty store.

func (*MemoryStore) Documents 

func (s *MemoryStore) Documents() []string

Documents returns the names of the documents held, which is what a caller needs to inspect or migrate a store.

func (*MemoryStore) Idle added in v0.26.1 

func (s *MemoryStore) Idle(_ context.Context, d time.Duration) ([]string, error)

Idle returns the documents this store has not been asked to write for longer than d, which is a MemoryStore's half of Archivable.

func (*MemoryStore) Load 

func (s *MemoryStore) Load(_ context.Context, document string) ([]byte, error)

Load returns a copy of the stored snapshot, or nil if the document is new.

func (*MemoryStore) Release added in v0.26.1 

func (s *MemoryStore) Release(_ context.Context, document string, want []byte) error

Release forgets a document if this store still holds exactly want.

The comparison and the removal are one step under the same lock, so a save that lands while a document is being archived cannot be deleted by the release that follows it.

func (*MemoryStore) Save 

func (s *MemoryStore) Save(_ context.Context, document string, snapshot []byte) error

Save records a copy of the snapshot.

type MultiStore added in v0.24.0 

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

A MultiStore keeps every document in several stores at once.

What it is for

The stores in this project answer different questions. A database answers "what is the document now", quickly, which is what a server restarting needs. A git repository answers "what did it say last Tuesday, and who wrote this sentence", which is what a person needs. Neither answers the other's question, and an operator who wants both has until now had to choose.

The alternative already in use is worse than choosing: writing to one store from the server and to the other from somewhere else — a browser, a sync job — which is two sources of truth held together by whichever of them happens to run last.

Reading merges rather than picking

[Load] reads every store and merges what they return. The obvious design is to read the first store that has the document and stop, and it is wrong here for a reason particular to this problem: a save that failed halfway leaves the stores holding different documents, and reading only the first would quietly drop whatever only the second had. Merging is the only answer that loses nothing, and a CRDT is what makes it available.

It has a consequence worth having on purpose: adding a store to a running server backfills it. The new store returns nothing, the merge is the other store's document unchanged, and the next save writes it across.

The cost is that opening a document reads every store instead of one, and merges when more than one has content. That is paid once per document, when it is opened, and not per edit.

A store that cannot be read makes the document unavailable

If any store fails to read, [Load] fails. It does not fall back to the stores that answered, because what came back would be a document that is missing whatever the unreadable store alone held — and the next save would then write that shortened document over the store that was merely unreachable. Serving a document that is quietly missing a paragraph is worse than serving none: an error stops at one document and an operator can fix it, while silent loss is discovered by the person who wrote the paragraph.

Writing tries every store, and fails if any refused

[Save] writes to all of them even after one has failed, so that a store being down does not stop the others from being written, and then reports every failure together. It returns an error if any store refused, because a caller that gets nil back has to be able to believe the document is durable in all of them.

They are written one after another rather than at the same time because there are two of them, not two hundred.

func NewMultiStore added in v0.24.0 

func NewMultiStore(stores ...Store) *MultiStore

NewMultiStore returns a store that writes to all of the given stores and reads from all of them.

It panics if given none: a store that silently keeps nothing would look like it was working, and there is no configuration in which that is what somebody meant. One is allowed, and behaves as that store does.

func (*MultiStore) Load added in v0.24.0 

func (m *MultiStore) Load(ctx context.Context, document string) ([]byte, error)

Load returns the merge of what every store holds, or nil if none of them has the document yet.

func (*MultiStore) Save added in v0.24.0 

func (m *MultiStore) Save(ctx context.Context, document string, snapshot []byte) error

Save writes the snapshot to every store, and reports every store that refused it.

type Peer added in v0.19.0 

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

A Peer is one browser's side of a WebRTC connection, from before a channel exists until it is open. It wraps the native RTCPeerConnection and is used once, by one goroutine: offer or answer, then take the channel, then close.

func NewPeer added in v0.19.0 

func NewPeer(cfg PeerConfig) (*Peer, error)

NewPeer creates a Peer over a fresh RTCPeerConnection. It fails only where there is no RTCPeerConnection to create — outside a browser, or in one old enough not to have it — which a page can report before it offers to connect.

func (*Peer) AcceptAnswer added in v0.19.0 

func (p *Peer) AcceptAnswer(blob string) error

AcceptAnswer takes the answer the other browser pasted back and completes the offerer's side of the exchange. Only an offerer accepts an answer; a peer that has not offered has nothing for the answer to complete.

func (*Peer) Answer added in v0.19.0 

func (p *Peer) Answer(ctx context.Context, remoteOffer string) (string, error)

Answer plays the browser that joins: it takes the offerer's pasted offer, sets it, makes an answer, and returns the local description once every address has been gathered. Hand the returned blob back to the offerer. The data channel is not made here — it arrives on the connection, and Peer.DataChannel hands it over once it is open.

func (*Peer) Close added in v0.19.0 

func (p *Peer) Close() error

Close ends the connection and gives every callback back. It is safe to call more than once, and safe to call on a handshake that never finished.

func (*Peer) DataChannel added in v0.19.0 

func (p *Peer) DataChannel(ctx context.Context) (js.Value, error)

DataChannel returns the open channel, for handing to DataChannel or Server.ServeDataChannel. It waits: for the answerer, until the channel has arrived on the connection; for either side, until its readyState is "open". Call it after the exchange — after Peer.AcceptAnswer on the offerer, after Peer.Answer on the answerer — since a channel opens only once both descriptions are set.

func (*Peer) Offer added in v0.19.0 

func (p *Peer) Offer(ctx context.Context, label string) (string, error)

Offer plays the holder of the document: it creates the data channel, makes an offer, and returns the local description once every address has been gathered. Hand the returned blob to the other browser, then give its answer back through Peer.AcceptAnswer.

The channel is created here, before the offer, so that it is part of what the offer describes and is ordered — a document that arrived out of order would not be the document.

type PeerConfig added in v0.19.0 

type PeerConfig struct {
	ICEServers []string
	// ICEServersAuth adds STUN/TURN servers that carry long-term credentials —
	// what a TURN relay needs to authenticate and what the plain ICEServers URL
	// list cannot express. Both lists are used together, ICEServers first.
	ICEServersAuth []ICEServerAuth
}

PeerConfig configures a Peer. ICEServers is a list of STUN or TURN URLs, each the "urls" of one entry in the RTCPeerConnection configuration — for example "stun:stun.l.google.com:19302". Empty is a working configuration for two browsers on the same network, where no server is needed to discover an address that both can reach.

type PipeConn added in v0.21.0 

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

PipeConn is the server end of a Pipe, the side Server.ServePipe serves. It is an opaque handle: the session is spoken through it, not by the caller.

type Role added in v0.26.0 

type Role int

A Role is which side of the protocol a tab took, decided by [electRole]. 

const (
	// RoleClient is a tab that joins a document another tab is holding.
	RoleClient Role = iota + 1
	// RoleHost is the tab holding the document and answering the others.
	RoleHost
)

func HostOrJoin added in v0.26.0 

func HostOrJoin(ctx context.Context, room string, window time.Duration) (Role, error)

HostOrJoin decides whether this tab should hold the document for the room or join one another tab already holds, so a page offering "collaborate in this browser" need not know which tab it is. It returns RoleHost or RoleClient; the page then calls Server.ServeBroadcastChannel or JoinBroadcastChannel on the same room accordingly. window bounds the decision — pass DefaultElectionWindow unless there is a reason not to. See [electRole] for the rule that keeps two tabs opening together from both hosting.

Prefer OpenBroadcastSession, which keeps the elected bus and identity and so leaves no window between electing and serving where an elected host is deaf. This two-call shape reopens the bus to serve, which is exactly that window; it is kept for a page that already knows its role.

type Server 

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

A Server hosts documents. Register it with [collabpb.RegisterCollabServer] on any grpc.Server — over github.com/grpc-transports/websocket for browsers, over plain TCP for anything else.

Documents stay in memory once opened, so a long-lived server holds every document it has served. Call Server.Flush to persist them.

func NewServer 

func NewServer(cfg Config) *Server

NewServer returns a server ready to register.

func (*Server) Close added in v0.18.0 

func (s *Server) Close(ctx context.Context) error

Close stops the housekeeping Config.PersistEvery and Config.EvictAfter ask for, and saves everything that has changed. It does not end the sessions in progress: those belong to whatever is serving them, and stopping that is the caller's to do first.

Calling it twice is harmless. A server that asked for neither still has one, so a caller need not know which kind it configured.

func (*Server) Flush 

func (s *Server) Flush(ctx context.Context) error

Flush persists every document that has changed since it was last written. A server that wants durability without waiting for participants to leave calls this on a timer, or before shutting down.

func (*Server) ServeBroadcastChannel added in v0.26.0 

func (s *Server) ServeBroadcastChannel(ctx context.Context, room string) error

ServeBroadcastChannel runs sessions over the BroadcastChannel named room, with this browser tab holding the document, for as many other tabs as join. It returns when ctx is cancelled.

It is the counterpart of Server.ServeDataChannel for a shared bus rather than a point-to-point channel: there is no request to upgrade and no origin to check, because a BroadcastChannel is already scoped to this origin and every tab on it is this browser.

func (*Server) ServeDataChannel added in v0.18.0 

func (s *Server) ServeDataChannel(ctx context.Context, ch js.Value) error

ServeDataChannel runs one session over a data channel, with this browser holding the document. It returns when the session ends.

It is the counterpart of [Server.ServeWebSocket], for a page rather than a listener: there is no request to upgrade and no origin to check, because the page decided who it was talking to when it swapped connection descriptions with them.

func (*Server) ServePipe added in v0.21.0 

func (s *Server) ServePipe(ctx context.Context, sc *PipeConn) error

ServePipe runs one session over the server end of a Pipe, with this server holding the document. It returns when the session ends — because the client end closed, because ctx was cancelled, or because the session itself failed.

It is the in-process counterpart of [Server.ServeWebSocket] and, in a browser, Server.ServeDataChannel: there is no request to upgrade and no origin to check, because there is no boundary to cross. Give it the PipeConn that Pipe returned beside the Transport the local editor joined over.

type Store 

type Store interface {
	// Load returns the snapshot for a document, or nil if there is none yet.
	// Returning nil is how a store says "new document", and is not an error.
	Load(ctx context.Context, document string) ([]byte, error)

	// Save records the current snapshot, replacing any previous one.
	Save(ctx context.Context, document string, snapshot []byte) error
}

A Store keeps documents between sessions. It holds snapshots, which are self-contained: a document restored from one can still serve a participant that has been away, because the snapshot carries the whole history.

Implementations must be safe for concurrent use.

type Text added in v0.10.0 

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

A Text is a handle on one text part: the buffer of a file, and what an editor binds to.

func (*Text) Anchor added in v0.10.0 

func (t *Text) Anchor(pos int) (crdt.ID, error)

Anchor returns the identity of the character at rune offset pos, which keeps naming that character however the text moves around it. It is what a comment or a stored selection should hold; see crdt.Doc.Anchor.

func (*Text) AnchorUTF16 added in v0.12.0 

func (t *Text) AnchorUTF16(pos int) (crdt.ID, error)

AnchorUTF16 is Text.Anchor with pos counted in UTF-16 code units, the units a page counts in. An offset falling between the two units of one character is refused rather than rounded; see crdt.ErrSurrogateBoundary.

func (*Text) AuthorRuns added in v0.10.0 

func (t *Text) AuthorRuns() []crdt.AuthorRun

AuthorRuns splits the visible text into stretches by who wrote them, which is what colouring a document by author needs.

func (*Text) AuthorRunsUTF16 added in v0.12.0 

func (t *Text) AuthorRunsUTF16() []crdt.AuthorRun

AuthorRunsUTF16 is Text.AuthorRuns with every offset and length counted in UTF-16 code units, so that a page can colour the string it holds without converting anything by hand.

func (*Text) Delete added in v0.10.0 

func (t *Text) Delete(pos, length int) error

Delete removes length runes at rune offset pos, locally and then everywhere.

func (*Text) DeleteUTF16 added in v0.10.0 

func (t *Text) DeleteUTF16(pos, length int) error

DeleteUTF16 removes length code units at an offset counted in the same units.

func (*Text) Insert added in v0.10.0 

func (t *Text) Insert(pos int, text string) error

Insert adds text at rune offset pos, locally and then everywhere.

func (*Text) InsertUTF16 added in v0.10.0 

func (t *Text) InsertUTF16(pos int, text string) error

InsertUTF16 adds text at an offset counted in UTF-16 code units.

func (*Text) Len added in v0.10.0 

func (t *Text) Len() int

Len returns the number of characters, counted in runes.

func (*Text) LenUTF16 added in v0.10.0 

func (t *Text) LenUTF16() int

LenUTF16 returns the length a browser would report, counting UTF-16 code units. Its companions InsertUTF16 and DeleteUTF16 take offsets in the same units, so a caller in the browser never converts by hand; see crdt.Doc.

func (*Text) Name added in v0.10.0 

func (t *Text) Name() string

Name returns the part's name.

func (*Text) Part added in v0.10.0 

func (t *Text) Part() crdt.Part

Part names this handle's part, which is what a crdt.PartChange from Client.TakeChanges carries.

func (*Text) Position added in v0.10.0 

func (t *Text) Position(anchor crdt.ID) (int, bool)

Position returns where the character an anchor names sits now — or where it was, if it has been deleted. See crdt.Doc.Position.

func (*Text) PositionUTF16 added in v0.12.0 

func (t *Text) PositionUTF16(anchor crdt.ID) (pos int, ok bool)

PositionUTF16 is Text.Position with the offset reported in UTF-16 code units. ok is false for an anchor this replica has never seen, exactly as it is there — which is not the same question as whether the character is still in the text; that one is Text.Visible.

func (*Text) String added in v0.10.0 

func (t *Text) String() string

String returns the text as it stands here.

func (*Text) Visible added in v0.10.0 

func (t *Text) Visible(anchor crdt.ID) bool

Visible reports whether the character an anchor names is still in the text.

type Tiered added in v0.26.1 

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

A Tiered store keeps documents somebody is using in one store and documents nobody has opened for a long time in another.

What it is for

A server holds every document it has ever served until it is told to let go — see Config.EvictAfter — and a store holds every document it has ever been given, with nothing to let go of it at all. A year of a busy service is a directory of documents that were opened once, and there has been no way to move them anywhere cheaper without deleting them.

Nothing is deleted that is not already somewhere else

Archiving is three steps in one order: read the hot store, write the cold one, then ask the hot one to release exactly what was read. Every way it can fail leaves the document somewhere. A cold store that will not take it releases nothing. A document that was written between the read and the release is not released, because Archivable.Release compares before it removes; it is archived on a later pass, when it has gone quiet again.

An archived document is not a missing one

Store.Load returning nil means "there is no such document, start a new one", and a server acts on it: it opens an empty document and, at its next save, writes it over whatever was there. So a Tiered store never answers nil for a document the cold store has, and never answers nil because it could not reach the cold store — it fails instead. A document that is unreachable is not a document that does not exist, and confusing the two is how a store loses what it was given.

Reading an archived document brings it back: it is written to the hot store on the way past, so the next read does not go looking again and the next save has somewhere to land.

func NewTiered added in v0.26.1 

func NewTiered(hot Archivable, cold Store) *Tiered

NewTiered returns a store that writes to hot and falls back to cold.

It panics if either is nil, which is a mistake in the call rather than a state anything could recover from.

func (*Tiered) Archive added in v0.26.1 

func (t *Tiered) Archive(ctx context.Context, idleFor time.Duration) (int, error)

Archive moves every document the hot store has not been asked to write for idleFor into the cold store, and returns how many it moved.

It is a method rather than a timer of its own because a server already has housekeeping running on a schedule an operator chose, and a store that starts goroutines is a store that has to be closed.

A document that could not be archived does not stop the ones after it: the errors are returned together, and what was moved is reported whatever else happened.

func (*Tiered) Load added in v0.26.1 

func (t *Tiered) Load(ctx context.Context, document string) ([]byte, error)

Load returns the document from the hot store, or from the cold one, bringing it back to the hot store on the way.

func (*Tiered) Save added in v0.26.1 

func (t *Tiered) Save(ctx context.Context, document string, snapshot []byte) error

Save writes to the hot store, which is where a document being edited belongs.

type Transport added in v0.11.0 

type Transport interface {
	// contains filtered or unexported methods
}

A Transport is how a participant reaches a server. WebSocket works anywhere, a browser included; [GRPC] works outside one.

There are two because of what they cost where they run. Outside a browser a carrier costs nothing anybody notices, and gRPC brings deadlines, interceptors and everything already built around them. Inside one it is paid for on every load: protobuf alone is six times the size of the whole CRDT compiled to wasm — see wire.go for the measurements — so the browser gets a framing of four message kinds over a plain WebSocket instead.

Both carry the same session, byte for byte in the fields that matter, because every field in these messages is something github.com/go-crdt/crdt encoded and will check on arrival. A participant on one and a participant on the other can edit the same document.

func DataChannel added in v0.18.0 

func DataChannel(ch js.Value) Transport

DataChannel returns a transport over an RTCDataChannel the page has already opened. The channel must be open — its readyState "open" — because a participant that joins before the connection exists has nothing to join.

func JoinBroadcastChannel added in v0.26.0 

func JoinBroadcastChannel(room string) Transport

JoinBroadcastChannel returns a transport that joins a document another tab of this browser is holding, over the BroadcastChannel named room. It is the side that joins; Server.ServeBroadcastChannel is the side that holds. Like WebSocket and DataChannel, it opens nothing until Join does — the bus is created, and the host dialled, when the session starts.

Use it directly when the page already knows it is joining; use HostOrJoin when it should discover whether to host or join.

func WebSocket added in v0.11.0 

func WebSocket(url string, opts ...WebSocketOption) Transport

WebSocket returns a transport that opens sessions at url, which is "ws://" or "wss://" and the path the server's handler is mounted at.

This is the transport a browser uses, and the one to reach for by default: it is what the same code compiled to wasm can afford. See Transport.

type WebSocketOption added in v0.11.0 

type WebSocketOption func(*wsTransport)

A WebSocketOption configures WebSocket.

Source Files

View all Source files

Directories

Path Synopsis
Command browsertest is the real-browser half of the WebRTC proof.
 Command browsertest is the real-browser half of the WebRTC proof.
gitstore module
migrate module
pgstore module
Command wasmtest is the browser half of the end-to-end proof.
 Command wasmtest is the browser half of the end-to-end proof.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.