Jido.Signal.Bus.Snapshot (Jido v1.1.0-rc.2)

View Source

Manages snapshots of the bus's signal log. A snapshot represents a filtered view of signals at a particular point in time, filtered by a path pattern.

Snapshots are immutable once created and are stored in :persistent_term for efficiency. The bus state only maintains lightweight references to the snapshots.

Usage

# Create a snapshot of all signals
{:ok, snapshot_ref, new_state} = Snapshot.create(state, "*")

# Create a snapshot of specific signal types
{:ok, snapshot_ref, new_state} = Snapshot.create(state, "user.created")

# Create a snapshot with a custom ID
{:ok, snapshot_ref, new_state} = Snapshot.create(state, "user.created", id: "my-custom-id")

# Create a snapshot with signals after a specific timestamp
timestamp = DateTime.utc_now() |> DateTime.to_unix(:millisecond)
{:ok, snapshot_ref, new_state} = Snapshot.create(state, "*", start_timestamp: timestamp)

# List all snapshots
snapshots = Snapshot.list(state)

# Read a snapshot
{:ok, snapshot_data} = Snapshot.read(state, snapshot_ref.id)

# Delete a snapshot
{:ok, new_state} = Snapshot.delete(state, snapshot_ref.id)

# Clean up all snapshots
{:ok, new_state} = Snapshot.cleanup(state)

# Clean up snapshots matching a filter
{:ok, new_state} = Snapshot.cleanup(state, fn ref -> ref.path == "user.created" end)

Summary

Functions

Cleans up all snapshots from the bus state. Returns {:ok, new_state} with all snapshots removed.

Cleans up snapshots from the bus state based on a filter function. The filter function should return true for snapshots that should be removed. Returns {:ok, new_state} with filtered snapshots removed.

Creates a new snapshot of signals matching the given path pattern. Stores the snapshot data in :persistent_term and returns a reference. Returns {:ok, snapshot_ref, new_state} on success or {:error, reason} on failure.

Deletes a snapshot by its ID. Removes both the reference from the state and the data from persistent_term. Returns {:ok, new_state} on success or {:error, :not_found} if snapshot doesn't exist.

Lists all snapshot references in the bus state, sorted by creation time (newest first). Returns a list of snapshot references.

Reads a snapshot by its ID. Returns {:ok, snapshot_data} if found or {:error, :not_found} if not found.

Functions

cleanup(state)

@spec cleanup(Jido.Signal.Bus.State.t()) :: {:ok, Jido.Signal.Bus.State.t()}

Cleans up all snapshots from the bus state. Returns {:ok, new_state} with all snapshots removed.

Examples

iex> Snapshot.cleanup(state)
{:ok, %BusState{snapshots: %{}}}

cleanup(state, filter_fn)

Cleans up snapshots from the bus state based on a filter function. The filter function should return true for snapshots that should be removed. Returns {:ok, new_state} with filtered snapshots removed.

Examples

iex> Snapshot.cleanup(state, fn ref -> ref.path == "user.created" end)
{:ok, %BusState{}}

iex> Snapshot.cleanup(state, fn ref -> DateTime.compare(ref.created_at, cutoff_time) == :lt end)
{:ok, %BusState{}}

create(state, path, opts \\ [])

Creates a new snapshot of signals matching the given path pattern. Stores the snapshot data in :persistent_term and returns a reference. Returns {:ok, snapshot_ref, new_state} on success or {:error, reason} on failure.

Options

  • :id - Custom ID for the snapshot (optional)
  • :start_timestamp - Only include signals after this timestamp in milliseconds (optional)
  • :correlation_id - Only include signals with this correlation ID (optional)
  • :batch_size - Maximum number of signals to include (optional, defaults to 1000)

Examples

iex> Snapshot.create(state, "*")
{:ok, %SnapshotRef{}, %BusState{}}

iex> Snapshot.create(state, "user.created", id: "my-snapshot")
{:ok, %SnapshotRef{id: "my-snapshot"}, %BusState{}}

iex> Snapshot.create(state, "*", start_timestamp: 1612345678000)
{:ok, %SnapshotRef{}, %BusState{}}

dbug(_, _ \\ [])

(macro)

delete(state, snapshot_id)

@spec delete(Jido.Signal.Bus.State.t(), String.t()) ::
  {:ok, Jido.Signal.Bus.State.t()} | {:error, :not_found}

Deletes a snapshot by its ID. Removes both the reference from the state and the data from persistent_term. Returns {:ok, new_state} on success or {:error, :not_found} if snapshot doesn't exist.

Examples

iex> Snapshot.delete(state, "snapshot-id")
{:ok, %BusState{}}

iex> Snapshot.delete(state, "non-existent-id")
{:error, :not_found}

error(_, _ \\ [])

(macro)

list(state)

Lists all snapshot references in the bus state, sorted by creation time (newest first). Returns a list of snapshot references.

Examples

iex> Snapshot.list(state)
[%SnapshotRef{}, %SnapshotRef{}]

iex> Snapshot.list(empty_state)
[]

read(state, snapshot_id)

@spec read(Jido.Signal.Bus.State.t(), String.t()) ::
  {:ok, Jido.Signal.Bus.Snapshot.SnapshotData.t()} | {:error, :not_found}

Reads a snapshot by its ID. Returns {:ok, snapshot_data} if found or {:error, :not_found} if not found.

Examples

iex> Snapshot.read(state, "snapshot-id")
{:ok, %SnapshotData{}}

iex> Snapshot.read(state, "non-existent-id")
{:error, :not_found}