sync

type AuthHandler ¶

type AuthHandler func(docName, token string) error

AuthHandler is the optional server-side callback invoked when a Conn receives a MessageAuth token from the client. Returns nil to accept (server replies with EncodeAuthAuthenticated; sync proceeds normally), or an error to deny (server replies with EncodeAuthPermissionDenied(error.Error()), then EncodeClose, and the transport tears down the connection with WS close code 4401). The DocName is the docName the WS was bound to at upgrade time; AuthHandler may use it for per-document authorization.

type AuthSubType ¶

type AuthSubType uint8

AuthSubType discriminates the inner Auth-message variant inside a MessageAuth envelope. Values match @hocuspocus/server MessageReceiver.ts MessageAuth enum.

Wire shape:

varuint(MessageAuth)       outer tag = 2
varuint(AuthSubType)       0=PermissionDenied, 1=Authenticated, 2=Token
varstring(payload)         reason | empty | token (per sub-type)

const (
	// AuthPermissionDenied is the server's "your token was
	// rejected" response. Payload is a varstring with a human-
	// readable reason.
	AuthPermissionDenied AuthSubType = 0

	// AuthAuthenticated is the server's "your token was accepted"
	// ack. Payload is an empty varstring.
	AuthAuthenticated AuthSubType = 1

	// AuthToken is the client's "here is my token" handshake.
	// Payload is a varstring with the opaque token. The server's
	// OnAuthenticate callback consumes this and returns nil
	// (accept) or an error (deny — server replies with
	// AuthPermissionDenied + MessageClose).
	AuthToken AuthSubType = 2
)

type Broadcaster ¶

type Broadcaster func(envelope []byte)

Broadcaster fans one outer-envelope frame to every connection on the same doc, including the originator. Per port-note gotcha 6, V1 updates are idempotent so skip-self is unnecessary at the network layer. The transport layer implements this against a per-doc connection set.

type Conn ¶

type Conn struct {
	// Doc is the document this connection edits. All Sync messages
	// route here. Multiple Conns sharing the same Doc form one
	// collaborative session.
	Doc *doc.Doc

	// Awareness is the presence layer multiplexed on the same WS.
	// Multiple Conns share one *Awareness per doc.
	Awareness *awareness.Awareness

	// ID identifies this connection in diagnostics and as the
	// origin tag passed to awareness.Apply. The transport layer
	// generates this (typically a random string or remote addr).
	ID string

	// DocName is the docName this connection was bound to at
	// upgrade time. Forwarded to AuthHandler / StatelessHandler.
	DocName string

	// Send writes one envelope to this connection only.
	Send Sender

	// Broadcast writes one envelope to every connection on this
	// doc, including self.
	Broadcast Broadcaster

	// OnAuthenticate, OnStateless are optional Hocuspocus-extension
	// hooks. nil = the corresponding message types are silently
	// dropped (matches the bare y-websocket subset).
	OnAuthenticate AuthHandler
	OnStateless    StatelessHandler

	// AuthFailed reports whether this conn was rejected by the
	// AuthHandler. The transport layer should check after each
	// HandleFrame call and tear down the WS with code 4401 when
	// true. The conn does not close itself — that's the transport's
	// job (the WS-close call needs access to the websocket.Conn).
	AuthFailed bool
	// contains filtered or unexported fields
}

Conn is the per-connection sync state machine. It owns no transport — Send and Broadcast are caller-supplied. The package tests exercise it with in-memory channels; the server/ package wires it to coder/websocket.

Conn is safe for sequential use from a single read goroutine. HandleFrame must not be called concurrently with itself on the same Conn; the transport's read loop serializes naturally. Send and Broadcast may be called from other goroutines (e.g. an awareness OnChange callback running on a different conn's read goroutine).

func New(d *doc.Doc, aw *awareness.Awareness, id string) *Conn

func (c *Conn) ControlledClients() []uint64

func (c *Conn) Disconnect() []uint64

func (c *Conn) HandleFrame(frame *Frame) error

func (c *Conn) SendInitialSync() error

type Frame ¶

type Frame struct {
	Type MessageType

	// SyncSub is set only when Type == MessageSync or MessageSyncReply.
	SyncSub SyncSubType

	// AuthSub is set only when Type == MessageAuth.
	AuthSub AuthSubType

	// Payload is the post-discriminator bytes:
	//   MessageSync          → the inner update or state vector bytes
	//                          (already unwrapped from varbuffer)
	//   MessageAwareness     → awareness update bytes
	//                          (already unwrapped from varbuffer)
	//   MessageQueryAwareness→ nil (no payload)
	//   MessageAuth          → token (AuthToken sub) or reason
	//                          (AuthPermissionDenied) — string bytes
	//   MessageStateless     → the stateless payload string bytes
	//   MessageBroadcastStateless → same
	//   MessageClose         → close reason string bytes
	//   MessageSyncStatus    → single byte 0x00 or 0x01
	//   MessagePing/Pong     → nil
	//   other                → the raw remaining envelope bytes,
	//                          left opaque for caller-defined handling
	Payload []byte
}

Frame is the decoded outer-envelope message. Type indicates which MessageType discriminator the wire bytes started with; the remaining fields populate based on Type per docs/yrs-port-notes/protocol-sync.md §2.

The decode helpers return a *Frame so callers can switch on Type without reaching back into raw bytes. Mutating fields on a Frame has no effect on the original wire bytes — the decoder copies.

func DecodeEnvelope(b []byte) (*Frame, []byte, error)

type MessageType ¶

type MessageType uint8

MessageType is the outer-envelope varuint discriminator. Values match @hocuspocus/server `MessageType` enum from packages/server/src/types.ts:56-67.

ygo v0.1 implements MessageSync, MessageAwareness, and MessageQueryAwareness. The remaining tags are decoded but dispatched to the OnUnknownMessage hook so adopters can add custom handling without recompiling.

const (
	// MessageSync wraps a y-protocols/sync sub-message (SyncStep1 /
	// SyncStep2 / SyncUpdate). Payload layout:
	//   varuint(SyncSubType) • varbuffer(payload)
	MessageSync MessageType = 0

	// MessageAwareness wraps an awareness update blob — see
	// internal/awareness for the inner wire format. Payload layout:
	//   varbuffer(awarenessUpdateBytes)
	MessageAwareness MessageType = 1

	// MessageAuth carries the Hocuspocus auth-token handshake. Not
	// implemented in v0.1; bare y-websocket does not support it.
	// Deferred per docs/tech-debt.md.
	MessageAuth MessageType = 2

	// MessageQueryAwareness is sent by a client (typically right
	// after connect) to request the full current awareness snapshot.
	// Payload is empty. Server replies with a MessageAwareness frame
	// containing every known client's state. Mandatory for
	// Hocuspocus-client interop even when nothing else from
	// Hocuspocus is implemented (port-note gotcha 1).
	MessageQueryAwareness MessageType = 3

	// MessageSyncReply mirrors MessageSync but originates from the
	// server side (used by Hocuspocus internals). Wire layout is
	// identical. We decode it but treat it as MessageSync.
	MessageSyncReply MessageType = 4

	// MessageStateless / MessageBroadcastStateless / MessageClose /
	// MessageSyncStatus / MessagePing / MessagePong are Hocuspocus
	// extensions. Decoded into typed frames; not actively handled
	// in v0.1.
	MessageStateless          MessageType = 5
	MessageBroadcastStateless MessageType = 6
	MessageClose              MessageType = 7
	MessageSyncStatus         MessageType = 8
	MessagePing               MessageType = 9
	MessagePong               MessageType = 10
)

type Sender ¶

type Sender func(envelope []byte) error

Sender writes one outer-envelope frame back to a single connection. The transport layer implements this — for WebSocket it serializes via the conn's write mutex; for in-memory tests it appends to a slice.

type StatelessHandler ¶

type StatelessHandler func(docName, payload string)

StatelessHandler is the optional callback invoked when a Conn receives a MessageStateless or MessageBroadcastStateless envelope. The broadcast variant additionally triggers a broadcast of the same envelope to other conns on the doc.

The handler runs synchronously on the read loop's goroutine — long-running work should be dispatched elsewhere.

type SyncSubType ¶

type SyncSubType uint8

SyncSubType is the inner-message varuint discriminator inside a MessageSync frame. Values match y-protocols/sync.js:37-39.

const (
	// SyncStep1 carries a state vector. The receiver replies with
	// SyncStep2 containing the diff the sender is missing.
	SyncStep1 SyncSubType = 0

	// SyncStep2 carries a V1 update — the response to a SyncStep1.
	// May carry an empty update (well-formed bytes encoding zero
	// blocks and zero delete-set ranges) when the receiver has
	// nothing the sender is missing.
	SyncStep2 SyncSubType = 1

	// SyncUpdate carries an unsolicited V1 update — a steady-state
	// edit being broadcast to peers. Wire format is identical to
	// SyncStep2; the only semantic difference is that SyncUpdate
	// is not expected to be a reply to a SyncStep1.
	SyncUpdate SyncSubType = 2
)