Jido.Signal.Bus.Snapshot (Jido v1.1.0-rc.2)
View SourceManages 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
@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: %{}}}
@spec cleanup(Jido.Signal.Bus.State.t(), (Jido.Signal.Bus.Snapshot.SnapshotRef.t() -> boolean())) :: {:ok, Jido.Signal.Bus.State.t()}
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{}}
@spec create(Jido.Signal.Bus.State.t(), String.t(), Keyword.t()) :: {:ok, Jido.Signal.Bus.Snapshot.SnapshotRef.t(), Jido.Signal.Bus.State.t()} | {:error, term()}
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{}}
@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}
@spec list(Jido.Signal.Bus.State.t()) :: [Jido.Signal.Bus.Snapshot.SnapshotRef.t()]
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)
[]
@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}