Jido.Storage.File (Jido v2.0.0-rc.4)

View Source

File-based storage adapter for Jido.

Provides persistent storage for agent checkpoints and thread journals using a directory-based layout. Suitable for simple production deployments.

Usage

defmodule MyApp.Jido do
  use Jido,
    otp_app: :my_app,
    storage: {Jido.Storage.File, path: "priv/jido/storage"}
end

Options

  • :path - Base directory path (required). Created if it doesn't exist.

Directory Layout

base_path/
├── checkpoints/
│   └── {key_hash}.term       # Serialized checkpoint
└── threads/
    └── {thread_id}/
        ├── meta.term          # {rev, created_at, updated_at, metadata}
        └── entries.log        # Length-prefixed binary frames

Concurrency

Uses :global.trans/3 for thread-level locking to ensure safe concurrent access.

Summary

Types

key()
opts()

Functions

append_thread(thread_id, entries, opts)

Append entries to a thread with optimistic concurrency.

delete_checkpoint(key, opts)

Delete a checkpoint.

delete_thread(thread_id, opts)

Delete a thread and all its data.

get_checkpoint(key, opts)

Retrieve a checkpoint by key.

load_thread(thread_id, opts)

Load a thread from disk.

put_checkpoint(key, data, opts)

Store a checkpoint with atomic write semantics.

Types

key()

@type key() :: term()

opts()

@type opts() :: keyword()

Functions

append_thread(thread_id, entries, opts)

@spec append_thread(String.t(), [Jido.Thread.Entry.t()], opts()) ::
  {:ok, Jido.Thread.t()} | {:error, term()}

Append entries to a thread with optimistic concurrency.

Options:

  • :expected_rev - Expected current revision. Fails with {:error, :conflict} if the current revision doesn't match.

Uses a global lock to ensure safe concurrent access.

delete_checkpoint(key, opts)

@spec delete_checkpoint(key(), opts()) :: :ok | {:error, term()}

Delete a checkpoint.

Returns :ok even if the file doesn't exist.

delete_thread(thread_id, opts)

@spec delete_thread(String.t(), opts()) :: :ok | {:error, term()}

Delete a thread and all its data.

Removes the entire thread directory.

get_checkpoint(key, opts)

@spec get_checkpoint(key(), opts()) :: {:ok, term()} | :not_found | {:error, term()}

Retrieve a checkpoint by key.

Returns {:ok, data} if found, :not_found if the file doesn't exist, or {:error, reason} on failure.

load_thread(thread_id, opts)

@spec load_thread(String.t(), opts()) ::
  {:ok, Jido.Thread.t()} | :not_found | {:error, term()}

Load a thread from disk.

Reads the meta file and entries log, reconstructing a %Jido.Thread{}. Returns :not_found if the thread directory doesn't exist.

put_checkpoint(key, data, opts)

@spec put_checkpoint(key(), term(), opts()) :: :ok | {:error, term()}

Store a checkpoint with atomic write semantics.

Writes to a temporary file first, then renames for atomicity.