Documentation
¶
Overview ¶
Package server implements the y-websocket / Hocuspocus-compatible WebSocket sync server for ygo documents.
The server exposes an http.Handler that adopters mount on their own http.ServeMux at any path prefix. Per port-note §"Go translation choices" — every adopter already has an HTTP server, so we layer on top rather than impose our own runtime. A 30-line cmd/ygo-server/main.go binary wraps this for stand-alone use.
Wire format compatibility: the bare y-websocket subset of the Hocuspocus envelope (tags 0=Sync, 1=Awareness, 3=QueryAwareness). Auth (tag 2), Stateless (5/6), Close (7), SyncStatus (8) are silently ignored — see docs/tech-debt.md. The Sync subset is sufficient for full interop with y-websocket clients and the Sync+Awareness subset of Hocuspocus clients.
Per-document state lives in a map keyed by docName (the last path segment of the WS URL). Documents are loaded lazily on the first connection and evicted after the last connection closes; if a persist.Store is configured, every applied update is persisted and a final snapshot is written at eviction time.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrServerClosed = errors.New("server: closed")
ErrServerClosed is returned from operations on a Server that has been Closed. Reserved for future use; currently no method returns it.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// Store optionally persists every applied update keyed by
// docName. When set, new documents load their history on first
// connect (drain through the pending buffer if necessary).
// When nil, documents are in-memory only and lost on the last
// disconnect.
Store persist.Store
// DocNameFn extracts the docName from the WS upgrade request.
// Defaults to last-path-segment, mirroring y-websocket's
// req.url.slice(1).split('?')[0] rule (port-note §3). Override
// when mounting on a complex URL scheme.
DocNameFn func(r *http.Request) string
// OriginPatterns lists the allowed Origin headers for CORS-
// style WS upgrade rejection. Defaults to an empty list which
// rejects all browser cross-origin connections; pass "*" to
// allow any origin (development only — relaxes browser
// same-origin protection). Forwarded verbatim to coder/websocket
// AcceptOptions.
OriginPatterns []string
// OnAuthenticate is the Hocuspocus auth callback. When set,
// the server expects every client to send a MessageAuth(Token)
// envelope shortly after connecting; the callback receives the
// docName + token and returns nil to accept or error to deny.
// On denial the server emits AuthPermissionDenied + Close and
// closes the WS with code 4401 (CloseStatusUnauthorized).
//
// When nil (the bare y-websocket default), MessageAuth tokens
// are accepted silently — the server responds with
// AuthAuthenticated so Hocuspocus clients flip their internal
// "authenticated" flag and proceed.
OnAuthenticate syncpkg.AuthHandler
// OnStateless is the Hocuspocus stateless-channel callback.
// Receives docName + payload string for both MessageStateless
// and MessageBroadcastStateless envelopes. Long-running work
// should be dispatched off-thread — this runs on the conn's
// read goroutine.
//
// MessageBroadcastStateless also fans out to other conns on
// the doc regardless of whether the callback is set.
OnStateless syncpkg.StatelessHandler
}
Options configures a Server. The zero value is valid: in-memory state only, no persistence, no auth, docName extracted as the last URL path segment.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the http.Handler implementation. Construct with New and mount via Handler(). Safe for concurrent use.
func New ¶
New returns a Server with the given options. The returned Server is ready to accept WS connections; call Handler() to obtain the http.Handler that performs the upgrade.
func (*Server) Close ¶
Close evicts every in-memory document, calling Flush on the configured Store. Pending in-flight WS reads will fail with context cancellation; callers should drain via an http.Server Shutdown rather than Close in production.
Returns the first error encountered while flushing, but continues attempting eviction past errors so partial failure leaves no leaks.
Source Files