Documentation
¶
Overview ¶
Package syncserver is the sync socket (GET /api/v1/sync): the automerge-repo network protocol, version 1, over a WebSocket, so the stock @automerge/automerge-repo WebSocket adapter connects to the engine unchanged (docs/adr/0007). It is a driving adapter: it turns protocol messages into calls on the engine's shared-draft service and nothing more, and it keeps no state a later connection needs.
One connection is one peer (a browser tab, a terminal). Per document it holds an Automerge sync state for as long as the connection lives; across replicas it learns of changes through the fan-out port, and, because a fan-out hint may be lost, it also asks every peer it serves for heads on a timer. A lost hint costs latency, never an edit (docs/adr/0008).
Index ¶
Constants ¶
const StatusIdle = websocket.StatusCode(4000)
StatusIdle is the close code for a connection closed as idle, so an interface can tell it from a failure and wait for its person instead of reconnecting at once.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶ added in v2.1.0
type Option func(*Server)
Option configures a Server.
func WithIdle ¶ added in v2.4.0
WithIdle closes a connection that has changed no document for d, so an open but unattended window holds no replica up and a deployment can scale to zero (docs/adr/0015). Pings, the server's own rechecks and presence do not count: the server cannot tell a person from a heartbeat, and a change to a document is the one thing only a person makes. An interface reconnects when its person comes back. 0 never closes.
func WithPing ¶ added in v2.1.0
WithPing pings each peer at this interval, so a quiet connection is not closed by a load balancer's idle timeout (60 s by default behind nginx or an AWS ALB) and a dead one is noticed. 0 turns pings off.
func WithRecheck ¶ added in v2.3.0
WithRecheck sets how often a connection offers its documents again whether or not a hint arrived: the most a lost hint can delay a change.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server serves the sync socket.
func New ¶
func New(shared *engine.Shared, fan fanout.Bus, authz auth.Authorizer, log *slog.Logger, opts ...Option) *Server
New returns a server over the engine's shared drafts. authz decides, per document, whether a peer may read or write it.
func (*Server) AnnounceAgent ¶ added in v2.5.0
AnnounceAgent tells everyone on a document, on every replica, that an agent is working on it (docs/adr/0016). An agent over MCP holds no socket, so the server speaks for it: presence as a browser sends it (contract/schemas/presence.schema.json), relayed over the fan-out like any peer's. It lasts as presence does, ten seconds unless repeated, so an agent shows while it works and is gone when it stops.
func (*Server) ServeHTTP ¶
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP upgrades the request and runs one peer until it leaves.
func (*Server) Shutdown ¶ added in v2.1.0
func (s *Server) Shutdown()
Shutdown closes every connection with "going away", so each peer reconnects at once (through the load balancer, to a replica that is staying) instead of finding out from a dead socket. Nothing is lost: a peer keeps its changes and offers them again on reconnecting.
type Stats ¶ added in v2.1.0
type Stats struct {
IdleClosed int64 // connections closed for changing nothing (WithIdle)
Connections int // peers connected to this replica
Documents int // documents at least one of them has open
Received int64 // sync messages received
Sent int64 // sync messages sent
Refused int64 // messages refused: a read-only peer's change, a protocol error
}
Stats are counters for monitoring.
Source Files