Yex.Sync (y_ex v0.8.0)

View Source

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

message()

@type message() ::
  {:sync, sync_message()}
  | :query_awareness
  | {:awareness, message()}
  | {:auth, term()}

sync_message()

@type sync_message() ::
  sync_message_step1() | sync_message_step2() | sync_message_update()

sync_message_step1()

@type sync_message_step1() :: {:sync_step1, encoded_state_vector :: binary()}

sync_message_step2()

@type sync_message_step2() :: {:sync_step2, document_state :: binary()}

sync_message_update()

@type sync_message_update() :: {:sync_update, encoded_diff :: binary()}

Functions

get_sync_step1(doc)

@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.

get_sync_step2(doc, encoded_state_vector)

@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.

get_update(update)

@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}}.

message_decode(message)

@spec message_decode(binary()) :: {:ok, message()} | {:error, term()}

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>>}}}

message_decode!(message)

@spec message_decode!(binary()) :: message()

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>>}}

message_decode_v1(message)

@spec message_decode_v1(binary()) :: {:ok, message()} | {:error, term()}

message_decode_v2(message)

@spec message_decode_v2(binary()) :: {:ok, message()} | {:error, term()}

message_encode(message)

@spec message_encode(message()) :: {:ok, binary()} | {:error, term()}

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>>}

message_encode!(message)

@spec message_encode!(message()) :: binary()

Encodes a message into binary format and raises an error if encoding fails. This function is useful when error handling is managed externally.

message_encode_v1(message)

@spec message_encode_v1(message()) :: {:ok, binary()} | {:error, term()}

message_encode_v2(message)

@spec message_encode_v2(message()) :: {:ok, binary()} | {:error, term()}

read_sync_message(message, doc, transactionOrigin)

@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.

read_sync_step1(encoded_state_vector, doc)

@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.

read_sync_step2(update, doc, transactionOrigin)

@spec read_sync_step2(binary(), Yex.Doc.t(), term()) :: :ok | {:error, term()}

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.