@callback access(config(), path(), modes :: [:read | :write]) :: :ok | {:error, term()}

@callback append(config(), path(), contents :: iodata(), write_opts()) ::
  :ok | {:error, term()}

@callback clear(config()) :: :ok | {:error, term()}

@callback configure(keyword()) :: {module(), config()}

@callback copy(config(), source :: path(), destination :: path(), write_opts()) ::
  :ok | {:error, term()}

@callback copy(
  source_config :: config(),
  source :: path(),
  destination_config :: config(),
  destination :: path(),
  write_opts()
) :: :ok | {:error, term()}

@callback create_directory(config(), path(), write_opts()) :: :ok | {:error, term()}

@callback delete(config(), path()) :: :ok | {:error, term()}

@callback delete_directory(config(), path(), directory_delete_opts()) ::
  :ok | {:error, term()}

@callback delete_version(config(), path(), version_id :: binary()) ::
  :ok | {:error, term()}

@callback file_exists(config(), path()) :: {:ok, :exists | :missing} | {:error, term()}

@callback get_latest_version(config(), path()) ::
  {:ok, version_id :: binary()} | {:error, term()}

@callback list_contents(config(), path()) ::
  {:ok,
   [
     %Jido.VFS.Stat.Dir{
       mtime: term(),
       name: term(),
       size: term(),
       visibility: term()
     }
     | %Jido.VFS.Stat.File{
         mtime: term(),
         name: term(),
         size: term(),
         visibility: term()
       }
   ]}
  | {:error, term()}

@callback list_versions(config(), path()) ::
  {:ok, [%{version_id: binary(), timestamp: integer()}]} | {:error, term()}

@callback move(config(), source :: path(), destination :: path(), write_opts()) ::
  :ok | {:error, term()}

@callback read(config(), path()) :: {:ok, binary()} | {:error, term()}

@callback read_stream(config(), path(), stream_opts()) ::
  {:ok, Enumerable.t()} | {:error, term()}

@callback read_version(config(), path(), version_id :: binary()) ::
  {:ok, binary()} | {:error, term()}

@callback restore_version(config(), path(), version_id :: binary()) ::
  :ok | {:error, term()}

@callback set_visibility(config(), path(), Jido.VFS.Visibility.t()) ::
  :ok | {:error, term()}

@callback starts_processes() :: boolean()

@callback stat(config(), path()) ::
  {:ok,
   %Jido.VFS.Stat.File{
     mtime: term(),
     name: term(),
     size: term(),
     visibility: term()
   }
   | %Jido.VFS.Stat.Dir{
       mtime: term(),
       name: term(),
       size: term(),
       visibility: term()
     }}
  | {:error, term()}

@callback truncate(config(), path(), new_size :: non_neg_integer()) ::
  :ok | {:error, term()}

@callback unsupported_operations() :: [atom()]

@callback utime(config(), path(), mtime :: DateTime.t()) :: :ok | {:error, term()}

@callback versioning_module() :: versioning_module() | nil

@callback visibility(config(), path()) ::
  {:ok, Jido.VFS.Visibility.t()} | {:error, term()}

@callback write(config(), path(), contents :: iodata(), write_opts()) ::
  :ok | {:error, term()}

@callback write_stream(config(), path(), stream_opts()) ::
  {:ok, Collectable.t()} | {:error, term()}

@callback write_version(config(), path(), contents :: iodata(), write_opts()) ::
  {:ok, version_id :: binary()} | {:error, term()}