View Source Chord.Context.Manager (Chord v0.1.4)

Orchestrates context synchronization, delta calculation, and backend interactions.

The Chord.Context.Manager module is responsible for the core operations in Chord, including context management, delta tracking, and backend interactions. It provides a flexible and efficient system for managing state and deltas, designed to work seamlessly with in-memory or external backends, offering users customizable workflows for their specific needs.

Features

  • Context Management: Handles retrieval, updates, and deletions of contexts efficiently.
  • Delta Tracking: Automatically calculates and stores deltas between context updates.
  • Synchronization: Supports syncing contexts and deltas to clients based on their known versions.
  • Exporting Contexts: Allows exporting active contexts to external storage using a configurable callback.
  • Flexible Backends: Compatible with built-in ETS or Redis backends, as well as custom backends.
  • External Context Integration: Supports fetching contexts from external storage when needed.

Use Cases

This module is designed for applications where efficient state and delta management is critical, such as:

  • Real-time collaborative applications (e.g., document editing, multiplayer games).
  • Communication platforms (e.g., chat systems, call management).
  • Systems requiring versioned state synchronization.

Developers can leverage Chord.Context.Manager to manage contexts with minimal boilerplate, while retaining the flexibility to adapt the behavior through configuration and callbacks.

Configuration

The behavior of this module is driven by the following configuration options:

config :chord,
  backend: Chord.Backend.ETS, # Backend to use for storing contexts and deltas.
  delta_threshold: 100, # Threshold for determining when to send full contexts.
  export_callback: &MyApp.ContextExporter.export/1, # Callback for exporting contexts.
  context_external_provider: &MyApp.ExternalProvider.fetch_context/1 # Function for fetching external contexts.

Summary

Functions

Deletes the context and its associated deltas.

Exports the context for a given identifier to an external storage.

Retrieves the current context for a given identifier.

Restores a context from an external provider to the current backend.

Updates the global context for a given identifier and calculates deltas.

Synchronizes the context for a specific identifier.

Partially updates the context for a given identifier and calculates deltas.

Functions

delete_context(context_id)

@spec delete_context(context_id :: any()) :: :ok | {:error, term()}

Deletes the context and its associated deltas.

Parameters

  • context_id (any): The ID of the context to delete.

Returns

  • :ok on success.
  • {:error, term()} on failure.

export_context(context_id)

@spec export_context(context_id :: any()) :: :ok | {:error, :not_found}

Exports the context for a given identifier to an external storage.

Parameters

  • context_id (any): The ID of the context to export.

Returns

  • :ok on success.
  • {:error, :not_found} if the context does not exist.

get_context(context_id)

@spec get_context(context_id :: any()) :: {:ok, map()} | {:error, term()}

Retrieves the current context for a given identifier.

Parameters

  • context_id (any): The ID of the context to be retrieved.

Returns

  • {:ok, map()} if context exists.
  • {:error, term()} if no context is available.

restore_context(context_id)

@spec restore_context(context_id :: any()) :: {:ok, map()} | {:error, :not_found}

Restores a context from an external provider to the current backend.

Parameters

  • context_id (any): The ID of the context to restore.

Returns

  • {:ok, map()} on success.
  • {:error, :not_found} if the context is missing in external storage.

set_context(context_id, new_context)

@spec set_context(context_id :: any(), new_context :: map()) ::
  {:ok, map()} | {:error, term()}

Updates the global context for a given identifier and calculates deltas.

Parameters

  • context_id (any): The ID of the context to update.
  • new_context (map): The full updated context to set.

Returns

  • {:ok, %{context: map(), delta: map()}} on success.
  • {:error, term()} on failure.

sync_context(context_id, client_version)

@spec sync_context(context_id :: any(), client_version :: integer() | nil) ::
  {:full_context, map()}
  | {:delta, map()}
  | {:no_change, integer()}
  | {:error, term()}

Synchronizes the context for a specific identifier.

Determines whether the client receives the full context, deltas, or no changes based on the client's known version.

Parameters

  • context_id (any): The ID of the context to synchronize.
  • client_version (integer | nil): The version of the context known to the client.

Returns

  • {:full_context, map()} if the client should receive the full context.
  • {:delta, map()} if the client should receive deltas.
  • {:no_change, integer()} if the client has the latest version.

update_context(context_id, changes)

@spec update_context(context_id :: any(), changes :: map()) ::
  {:ok, map()} | {:error, term()}

Partially updates the context for a given identifier and calculates deltas.

Only the provided fields in changes are updated in the existing context.

Parameters

  • context_id (any): The ID of the context to update.
  • changes (map): A map of fields to be updated.

Returns

  • {:ok, %{context: map(), delta: map()}} on success.
  • {:error, term()} on failure.