Sagents.FileSystem.FileSystemConfig (Sagents v0.4.2)

Configuration for a filesystem persistence backend.

A FileSystemConfig defines how files in a specific virtual directory are persisted. Multiple configs can be registered with a FileSystemServer, allowing different directories to use different persistence backends with different settings.

Fields

:base_directory - Virtual directory path this config applies to (e.g., "user_memories", "S3")
:persistence_module - Module implementing the Persistence behaviour
:debounce_ms - Milliseconds of inactivity before auto-persist (default: 5000)
:readonly - Whether files in this directory are read-only (default: false)
:default - When true, this config acts as a fallback for any file that doesn't match a specific base_directory config (default: false). When default: true, base_directory is optional — if omitted, the sentinel value "__default__" is used internally as an identifier.
:storage_opts - Backend-specific options passed to persistence module

Examples

# Writable user files with disk persistence
{:ok, config} = FileSystemConfig.new(%{
  base_directory: "user_files",
  persistence_module: Sagents.FileSystem.Persistence.Disk,
  debounce_ms: 5000,
  storage_opts: [path: "/data/users"]
})

# Read-only account files from database
{:ok, config} = FileSystemConfig.new(%{
  base_directory: "account_files",
  persistence_module: MyApp.DBPersistence,
  readonly: true,
  storage_opts: [repo: MyApp.Repo, table: "account_files"]
})

# Read-only S3 files
{:ok, config} = FileSystemConfig.new(%{
  base_directory: "S3",
  persistence_module: MyApp.S3Persistence,
  readonly: true,
  debounce_ms: 30000,
  storage_opts: [bucket: "shared-assets", region: "us-east-1"]
})

# Default catch-all config (no base_directory needed)
{:ok, config} = FileSystemConfig.new(%{
  default: true,
  persistence_module: MyApp.DBPersistence,
  storage_opts: [repo: MyApp.Repo]
})

Summary

Types

t()

Functions

build_storage_opts(config, scope_key)

Builds storage options for this config, including scope_key.

changeset(config \\ %FileSystemConfig{}, attrs)

Creates a changeset for a FileSystemConfig.

matches_path?(file_system_config, path)

Checks if a given path matches this config's base directory.

new(attrs)

Creates a new FileSystemConfig.

new!(attrs)

Creates a new FileSystemConfig, raising on error.

Types

t()

@type t() :: %Sagents.FileSystem.FileSystemConfig{
  base_directory: String.t(),
  debounce_ms: non_neg_integer(),
  default: boolean(),
  persistence_module: module(),
  readonly: boolean(),
  storage_opts: keyword()
}

Functions

build_storage_opts(config, scope_key)

@spec build_storage_opts(t(), tuple()) :: keyword()

Builds storage options for this config, including scope_key.

Examples

iex> config = FileSystemConfig.new!(%{
...>   base_directory: "user_files",
...>   persistence_module: SomeMod,
...>   storage_opts: [path: "/data"]
...> })
iex> FileSystemConfig.build_storage_opts(config, {:user, 123})
[path: "/data", scope_key: {:user, 123}, base_directory: "user_files"]

iex> FileSystemConfig.build_storage_opts(config, {:agent, "agent-123"})
[path: "/data", scope_key: {:agent, "agent-123"}, base_directory: "user_files"]

changeset(config \\ %FileSystemConfig{}, attrs)

Creates a changeset for a FileSystemConfig.

matches_path?(file_system_config, path)

@spec matches_path?(t(), String.t()) :: boolean()

Checks if a given path matches this config's base directory.

Examples

iex> config = FileSystemConfig.new!(%{
...>   base_directory: "user_files",
...>   persistence_module: SomeMod
...> })
iex> FileSystemConfig.matches_path?(config, "/user_files/data.txt")
true
iex> FileSystemConfig.matches_path?(config, "/other/file.txt")
false

new(attrs)

@spec new(map() | keyword()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}

Creates a new FileSystemConfig.

Parameters

attrs - Map or keyword list with config fields

Required Fields

:base_directory - Virtual directory path (without leading/trailing slashes). Optional when default: true — if omitted, the sentinel "__default__" is used internally.
:persistence_module - Module implementing Persistence behaviour

Optional Fields

:debounce_ms - Auto-persist delay in milliseconds (default: 5000)
:readonly - Read-only flag (default: false)
:default - When true, acts as a catch-all for unmatched paths (default: false)
:storage_opts - Backend-specific options (default: [])

Returns

{:ok, config} on success
{:error, changeset} on validation failure

Examples

iex> FileSystemConfig.new(%{
...>   base_directory: "user_files",
...>   persistence_module: MyApp.Persistence.Disk,
...>   debounce_ms: 3000,
...>   storage_opts: [path: "/data"]
...> })
{:ok, %FileSystemConfig{}}

iex> FileSystemConfig.new(%{base_directory: ""})
{:error, %Ecto.Changeset{}}

new!(attrs)

@spec new!(map() | keyword()) :: t()

Creates a new FileSystemConfig, raising on error.

Same as new/1 but raises on validation errors.