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 WithFollows ¶ added in v2.6.0
WithFollows says who may open a person's agent feed (docs/adr/0018): the engine's MayFollow.
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
func (s *Server) AnnounceAgent(ctx context.Context, docID, actor, name, focus string, agent map[string]any)
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.
focus is the field it last changed, so people see where; agent is what it did (the presence schema's agent), so a person can follow it.
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