View Source Chord (Chord v0.1.3)

Chord: A powerful library for managing real-time contexts with efficiency and flexibility.

The Chord module serves as the entry point for the library, providing a high-level API to manage contexts, deltas, cleanup, and integrations with various storage backends. It simplifies state synchronization and lifecycle management for real-time applications.

Key Features

  • Context Management: Create, update, synchronize, and delete application contexts.
  • Delta Tracking: Efficiently track changes to minimize data transfer.
  • Flexible Backends: Support for in-memory (ETS) and distributed (Redis) storage.
  • Context Export: Easily export contexts to external storage.
  • Customizable Cleanup: Automated or manual cleanup of expired data.
  • Partial Updates: Apply updates to specific fields within a context.
  • External Context Provider: Restore contexts from external sources when needed.

Configuration

Chord is designed to be configurable via the application environment. Below are the configuration options available:

config :chord,
  backend: Chord.Backend.ETS, # Backend for storing contexts and deltas (ETS or Redis)
  context_auto_delete: true, # Automatically delete expired contexts
  context_ttl: :timer.hours(6), # Time-to-live for contexts
  delta_ttl: :timer.hours(3), # Time-to-live for deltas
  delta_threshold: 100, # Maximum number of deltas to retain per context
  delta_formatter: Chord.Delta.Formatter.Default, # Formatter for deltas
  time_provider: MyApp.TimeProvider, # Custom time provider for timestamping
  export_callback: &MyApp.ContextExporter.export/1, # Callback for exporting contexts
  context_external_provider: &MyApp.ExternalState.fetch_context/1 # Restore context from external storage

Common Options

The following options are shared across several functions in this module and related modules:

  • :context_id - The identifier for the context.
  • :version - The version number for tracking state changes.
  • :inserted_at - The timestamp when the context or delta was created.
  • :limit - The maximum number of contexts or deltas to fetch.
  • :offset - The number of entries to skip when fetching.
  • :order - The sort order for results (:asc or :desc).

Example Usage

Here's how you can use Chord in your application:

# Set a context
{:ok, %{context: updated_context, delta: delta}} =
  Chord.set_context("call:123", %{status: "active"})

# Get the current context
{:ok, %{context_id: context_id, context: context, version: version, inserted_at: inserted_at}} = Chord.get_context("call:123")

# Apply a partial update to a context
{:ok, %{context: updated_context, delta: delta}} =
  Chord.update_context("call:123", %{status: "ended"})

# Synchronize context with a client
case Chord.sync_context("call:123", client_version) do
  {:full_context, context} -> :send_full_context
  {:delta, delta} -> :send_delta
  {:no_change, version} -> :no_change
end

# Restore a context from external storage
{:ok, context_data} = Chord.restore_context("call:123")

# Export a context to external storage
:ok = Chord.export_context("call:123")

# Trigger cleanup
Chord.cleanup(limit: 10)

# Start the Cleanup.Server for periodic cleanup
{:ok, _pid} = Chord.start_cleanup_server(interval: :timer.minutes(30))

Summary

Functions

Triggers a one-time cleanup for stale contexts and deltas.

Deletes the global context, including all deltas.

Exports the active context for a given identifier to external storage using the configured export callback.

Retrieves the current global context for a given identifier.

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

Sets the global context and records deltas.

Starts the Cleanup.Server for periodic cleanup.

Stops the CleanupServer if running.

Synchronizes the context for a client based on its current version.

Updates the backend options for the cleanup server at runtime.

Updates the cleanup server's interval at runtime.

Partially updates the global context for a given identifier.

Functions

cleanup(opts \\ [])

@spec cleanup(opts :: Keyword.t()) :: :ok

Triggers a one-time cleanup for stale contexts and deltas.

Parameters

  • opts (Keyword.t): Optional parameters for filtering contexts and deltas (see "Common Options").

Returns

  • :ok on success.

delete_context(context_id)

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

Deletes the global context, including all deltas.

Parameters

  • context_id - The identifier for the context.

Returns

  • :ok on success.

export_context(context_id)

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

Exports the active context for a given identifier to external storage using the configured export callback.

Parameters

  • context_id - The identifier for the context.

Returns

  • :ok if the context is successfully exported.
  • {: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 global context for a given identifier.

Parameters

  • context_id - The identifier for the context.

Returns

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

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

Sets the global context and records deltas.

Parameters

  • context_id - The identifier for the context.
  • new_context - The new context to be stored.

Returns

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

start_cleanup_server(opts \\ [])

@spec start_cleanup_server(opts :: Keyword.t()) :: {:ok, pid()} | {:error, term()}

Starts the Cleanup.Server for periodic cleanup.

Parameters

  • opts - Options for the Cleanup.Server. Examples include:
    • :interval - The interval (in milliseconds) between cleanup executions.
    • :backend_opts - A keyword list of options passed to backend listing functions (see "Common Options").

Returns

  • {:ok, pid} on success.

stop_cleanup_server()

@spec stop_cleanup_server() :: :ok

Stops the CleanupServer if running.

Returns

  • :ok on success.

sync_context(context_id, client_version)

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

Synchronizes the context for a client based on its current version.

Parameters

  • context_id - The identifier for the context.
  • client_version - The last known version for the client.

Returns

  • {:full_context, map()} if a full context is sent.
  • {:delta, map()} if deltas are sent.
  • {:no_change, version} if no changes are needed.

update_cleanup_backend_opts(new_opts)

@spec update_cleanup_backend_opts(new_opts :: Keyword.t()) :: :ok

Updates the backend options for the cleanup server at runtime.

Parameters

  • new_opts (Keyword.t): The new backend options.

update_cleanup_interval(new_interval)

@spec update_cleanup_interval(new_interval :: integer()) :: :ok

Updates the cleanup server's interval at runtime.

Parameters

  • new_interval (integer): The new interval in milliseconds.

update_context(context_id, changes)

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

Partially updates the global context for a given identifier.

Parameters

  • context_id - The identifier for the context.
  • changes - A map of fields to be updated in the existing context.

Returns

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