Optionalopts: ClientOptionsthe options of the client.
activate activates this client. That is, it registers itself to the server
and receives a unique ID from the server. The given ID is used to
distinguish different clients.
attach attaches the given channel to this client. The channel is
registered locally and the server is notified on the next RefreshChannel
heartbeat.
Optionalopts: AttachChannelOptionsattachChannel attaches the given channel to this client. The channel is
registered locally and the server is notified on the next RefreshChannel
heartbeat.
broadcast broadcasts the given payload to the given topic.
Optionaloptions: BroadcastOptionscreateRevision creates a new revision for the given document.
deactivate deactivates this client.
If keepalive is true, the client will request deactivation
immediately using fetch with the keepalive option enabled. This is
useful for ensuring the deactivation request completes even if the page is
being unloaded, such as in beforeunload or unload event listeners.
If synchronous is true, the server will wait for all pending operations to
complete before deactivating.
Without keepalive, if the server refuses deactivation with a 401 and
authTokenInjector rejects, the client is deactivated locally anyway
and the injector's error is thrown.
With keepalive, the response is not waited for at all: the client tears
down locally as soon as the request is sent and the returned Promise
resolves, and a late response or error is dropped. A page that freezes in
the back/forward cache never processes that response, so waiting for it
leaves the Promise pending forever in Safari.
getActorID returns the actor stamped into this client's document
changes. On a server that supports stable actors it is the stable actor
derived from the project and client key (ActivateClientResponse.actorId);
otherwise it falls back to the per-session id. This is the actor a version
vector is keyed by, so tests and callers that reason about change
authorship or GC must use this, not getID.
getCondition returns the condition of this client.
getID returns the per-session id of this client. It is the wire
clientId used for RPC routing, not the actor stamped into document
changes. Use getActorID for the change author.
getKey returns a key of client.
getRevision retrieves a specific revision by its ID with full snapshot data.
getStatus returns the status of this client.
has checks if the given resource is attached to this client.
the key of the resource.
true if the resource is attached to this client.
isActive checks if the client is active.
listRevisions lists all revisions for the given document.
peekChannel reads the current session count of a channel without
creating a session on the server. Use this when the caller only needs
to display the count (e.g. "N people writing") without contributing to
it and without receiving broadcasts.
Unlike attach({ readOnly: true }), this does not occupy a Session
entry on the server, does not generate heartbeat RPCs, and does not
subscribe to channel events. Polling is the caller's responsibility.
resync recovers a document whose local writes the server has refused
(ErrPermissionDenied from PushPull — an owner locked the document, this
member was downgraded to read-only, a share link was revoked), without
forcing the app to throw the client and the Document away.
The refused changes cannot simply be left queued: push and pull share one
RPC, so every later sync re-sends them, is denied again, and the client
stops receiving other peers' changes too. Nor can they be undone in place —
they are already applied to root and there is no server-confirmed copy to
fall back on. So recovery re-anchors on the server state:
resetForReanchor(), andDocument instance again, under the sync mode it
had, so the server snapshot arrives through the usual events, and
restart the sync loop that the denial stopped.Keeping the instance is the point: the app's subscriptions and the editor
bound to the document survive, where re-creating the client remounts them.
It also means the app can still call Document.update while steps 1–4 are
in flight, and between the discard and the re-anchor the change queue has
a clientSeq hole no new change may be minted over. So the discard
suspends minting for exactly that span: update and undo/redo throw
ErrRefused until step 3 (or the rollback below) lifts it, instead of the
edit wedging the detach with ErrInvalidClientSeq or being wiped by
resetForReanchor with nothing reported. An edit that lands before step 1
is simply part of the discarded set and reported with the rest.
Returns the discarded changes so the app can report them ("N edits were not saved"). Re-applying them is deliberately not the default — the server refused them.
Failure is accounted for rather than left half-done. If the detach is
itself refused, the queue is handed back and the document is left attached
exactly as it was, so the call can be retried. Once the detach has gone
through the changes are gone for good, so they are published as a
local-changes-dropped event at that moment — before the re-attach, which
is the one step that can still fail with the edits already discarded. An
app that only listens to that event therefore sees the loss on every path
that loses something.
sync pushes local changes of the attached documents to the server and
receives changes of the remote replica from the server then apply them to
local documents.
For Channel in manual mode, it refreshes the TTL by sending a heartbeat.
Clientis a normal client that can communicate with the server. It has documents and sends changes of the documents in local to the server to synchronize with other replicas in remote.