Returns a specification to start this module under a supervisor.

See Supervisor.

@spec get_filesystem(tuple()) ::
  {:ok, pid()} | {:error, :not_found | :registry_unavailable}

Get the PID of a running filesystem by scope key.

Parameters

• scope_key - Tuple identifying the filesystem scope

Returns

• {:ok, pid} - Filesystem found
• {:error, :not_found} - Filesystem not running for this scope
• {:error, :registry_unavailable} - this node's registry could not answer

The third answer is deliberately distinct from :not_found for the same reason it is in Sagents.AgentSupervisor.get_pid/1: a caller reads "not found" as "start one", and on a draining node that produces a second filesystem for a scope that already has one elsewhere. See docs/deployment.md.

Examples

{:ok, pid} = get_filesystem({:user, 123})

@spec list_filesystems() :: [{tuple(), pid()}]

List all running filesystem scopes and their PIDs.

Returns

List of {scope_key, pid} tuples.

Raises Sagents.RegistryUnavailableError when this node's registry cannot answer, rather than reporting an empty list as though it were a real result. Same reasoning as Sagents.ProcessRegistry.select/1, which it uses.

Examples

filesystems = list_filesystems()
# => [{:user, 123, #PID<0.123.0>}, {:project, 456, #PID<0.124.0>}]

@spec start_filesystem(tuple(), list(), keyword()) :: {:ok, pid()} | {:error, term()}

Start a new filesystem for the given scope.

Parameters

• scope_key - Tuple identifying the filesystem scope (e.g., {:user, 123})
• configs - List of FileSystemConfig structs for this filesystem
• opts - Additional options:
  • :supervisor - Supervisor reference (PID or registered name). Defaults to __MODULE__.
  • :pubsub - PubSub configuration as {module(), atom()} tuple (optional)

Returns

• {:ok, pid} - Successfully started filesystem
• {:error, {:already_started, pid}} - Filesystem already running for this scope
• {:error, reason} - Other error

Examples

{:ok, config} = FileSystemConfig.new(%{
  scope_key: {:user, 123},
  base_directory: "Documents",
  persistence_module: Disk,
  storage_opts: [path: "/data/users/123"]
})

{:ok, pid} = start_filesystem({:user, 123}, [config])

# With PubSub
{:ok, pid} = start_filesystem({:user, 123}, [config], pubsub: {Phoenix.PubSub, :my_pubsub})

@spec start_link(keyword()) :: Supervisor.on_start()

Start the FileSystemSupervisor.

Options

• :name - Registered name for the supervisor (optional)

Examples

{:ok, pid} = start_link(name: MyApp.FileSystemSupervisor)

@spec stop_filesystem(
  tuple(),
  keyword()
) :: :ok | {:error, :not_found}

Stop an existing filesystem.

The filesystem will be gracefully terminated, allowing it to flush any pending writes.

Parameters

• scope_key - Tuple identifying the filesystem scope
• opts - Additional options:
  • :supervisor - Supervisor reference (PID or registered name). Defaults to __MODULE__.

Returns

• :ok - Successfully stopped
• {:error, :not_found} - Filesystem not running for this scope

Examples

:ok = stop_filesystem({:user, 123})

@spec wait_for_supervisor_ready(atom() | pid(), non_neg_integer()) ::
  :ok | {:error, :supervisor_not_ready}

Wait for the FileSystemSupervisor to be ready.

This function polls for the supervisor to be available, useful in scenarios where the supervisor might be starting up asynchronously (e.g., in async tests).

Parameters

• supervisor - Supervisor reference (PID or registered name). Defaults to __MODULE__.
• timeout_ms - Maximum time to wait in milliseconds (default: 5000)

Returns

• :ok - Supervisor is ready
• {:error, :supervisor_not_ready} - Timeout waiting for supervisor

Examples

:ok = wait_for_supervisor_ready()
:ok = wait_for_supervisor_ready(__MODULE__, 10_000)