View Source Yex.Sync (y_ex v0.7.2)
Yex.Sync provides functions to handle the synchronization protocol for Yex documents.
This module defines a set of message types and encoding/decoding functions to manage document state synchronization. The messages follow the protocol described in the Yjs Sync Protocol Documentation. Each message type corresponds to a step in the sync process or an update to the document state.
Summary
Functions
Generates a sync_step1
message for initiating document synchronization. This message
contains the current encoded state vector of the document.
Creates a sync_step2
message to continue synchronization using a given encoded state vector.
This message contains the current state of the document to be synchronized.
Generates a sync_update
message based on a provided update binary. This is typically
used to apply incremental changes to the document state.
Decodes a binary message into a recognized protocol format, returning {:ok, message}
if decoding is successful, or {:error, reason}
otherwise.
Decodes a binary message, raising an error if decoding fails. Useful for cases where error handling is managed at a higher level.
Encodes a message into binary format, returning {:ok, binary}
if encoding
succeeds or {:error, reason}
on failure.
Encodes a message into binary format and raises an error if encoding fails. This function is useful when error handling is managed externally.
Reads and applies a synchronization message to the document, based on the message type.
Supports sync_step1
, sync_step2
, and sync_update
messages, with each type invoking
the appropriate handler.
Processes a sync_step1
message to produce a sync_step2
response, used to
synchronize document state.
Processes a sync_step2
or sync_update
message by applying the update to the document.
The update is applied within a transaction to ensure document consistency.
Types
@type message() :: {:sync, sync_message()} | :query_awareness | {:awareness, message()} | {:auth, term()}
@type sync_message() :: sync_message_step1() | sync_message_step2() | sync_message_update()
@type sync_message_step1() :: {:sync_step1, encoded_state_vector :: binary()}
@type sync_message_step2() :: {:sync_step2, document_state :: binary()}
@type sync_message_update() :: {:sync_update, encoded_diff :: binary()}
Functions
@spec get_sync_step1(Yex.Doc.t()) :: {:ok, sync_message_step1()} | {:error, term()}
Generates a sync_step1
message for initiating document synchronization. This message
contains the current encoded state vector of the document.
Returns {:ok, {:sync_step1, encoded_state_vector}}
if successful, otherwise an error.
@spec get_sync_step2(Yex.Doc.t(), binary()) :: {:ok, sync_message_step2()} | {:error, term()}
Creates a sync_step2
message to continue synchronization using a given encoded state vector.
This message contains the current state of the document to be synchronized.
Returns {:ok, {:sync_step2, document_state}}
if successful, otherwise an error.
@spec get_update(binary()) :: {:ok, sync_message_update()} | {:error, term()}
Generates a sync_update
message based on a provided update binary. This is typically
used to apply incremental changes to the document state.
Returns {:ok, {:sync_update, update}}
.
Decodes a binary message into a recognized protocol format, returning {:ok, message}
if decoding is successful, or {:error, reason}
otherwise.
Examples
iex> Yex.Sync.message_decode(<<0, 0, 1, 0>>)
{:ok, {:sync, {:sync_step1, <<0>>}}}
Decodes a binary message, raising an error if decoding fails. Useful for cases where error handling is managed at a higher level.
Examples
iex> Yex.Sync.message_decode!(<<0, 0, 1, 0>>)
{:sync, {:sync_step1, <<0>>}}
Encodes a message into binary format, returning {:ok, binary}
if encoding
succeeds or {:error, reason}
on failure.
Examples
iex> Yex.Sync.message_encode({:sync, {:sync_step1, <<0>>}})
{:ok, <<0, 0, 1, 0>>}
Encodes a message into binary format and raises an error if encoding fails. This function is useful when error handling is managed externally.
@spec read_sync_message( sync_message(), Yex.Doc.t(), term() ) :: {:ok, sync_message_step2()} | :ok | {:error, :unknown_message} | {:error, term()}
Reads and applies a synchronization message to the document, based on the message type.
Supports sync_step1
, sync_step2
, and sync_update
messages, with each type invoking
the appropriate handler.
Returns {:ok, response}
on success or {:error, :unknown_message}
if the message type is invalid.
@spec read_sync_step1(binary(), Yex.Doc.t()) :: {:ok, sync_message_step2()} | {:error, term()}
Processes a sync_step1
message to produce a sync_step2
response, used to
synchronize document state.
Returns {:ok, {:sync_step2, document_state}}
if successful.
Processes a sync_step2
or sync_update
message by applying the update to the document.
The update is applied within a transaction to ensure document consistency.
Returns :ok
on success, or {:error, reason}
on failure.