//! 特定于 WASI 的 [`std::fs`] 模块中原语的扩展。
//!
//! [`std::fs`]: crate::fs

#![deny(unsafe_op_in_unsafe_fn)]
#![unstable(feature = "wasi_ext", issue = "71213")]

use crate::ffi::OsStr;
use crate::fs::{self, File, Metadata, OpenOptions};
use crate::io::{self, IoSlice, IoSliceMut};
use crate::path::{Path, PathBuf};
use crate::sys_common::{AsInner, AsInnerMut, FromInner};
// 用于文档内链接上的 `File::read`
#[allow(unused_imports)]
use io::{Read, Write};

/// 特定于 WASI 的 [`File`] 的扩展。
pub trait FileExt {
    /// 从给定的偏移量开始读取多个字节。
    ///
    /// 返回读取的字节数。
    ///
    /// 偏移量相对于文件的开始，因此独立于当前游标。
    ///
    ///
    /// 当前文件游标不受此函数影响。
    ///
    /// 请注意，类似于 [`File::read`]，短读返回不会出错。
    ///
    fn read_at(&self, buf: &mut [u8], offset: u64) -> io::Result<usize> {
        let bufs = &mut [IoSliceMut::new(buf)];
        self.read_vectored_at(bufs, offset)
    }

    /// 从给定的偏移量开始读取多个字节。
    ///
    /// 返回读取的字节数。
    ///
    /// 偏移量相对于文件的开始，因此独立于当前游标。
    ///
    ///
    /// 当前文件游标不受此函数影响。
    ///
    /// 请注意，类似于 [`File::read_vectored`]，短读返回不会出错。
    ///
    fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize>;

    /// 从给定的偏移量读取填充 `buf` 所需的确切字节数。
    ///
    /// 偏移量相对于文件的开始，因此独立于当前游标。
    ///
    /// 当前文件游标不受此函数影响。
    ///
    /// 与 [`Read::read_exact`] 相似，但使用 [`read_at`] 代替 `read`。
    ///
    /// [`read_at`]: FileExt::read_at
    ///
    /// # Errors
    ///
    /// 如果此函数遇到 [`io::ErrorKind::Interrupted`] 类型的错误，则该错误将被忽略，并且操作将继续。
    ///
    /// 如果此函数在完全填充缓冲区之前遇到 "end of file"，它将返回 [`io::ErrorKind::UnexpectedEof`] 类型的错误。
    /// 在这种情况下，`buf` 的内容未指定。
    ///
    /// 如果遇到任何其他读取错误，则此函数立即返回。在这种情况下，`buf` 的内容未指定。
    ///
    /// 如果此函数返回错误，则无法确定已读取多少字节，但读取的字节数永远不会超过完全填充缓冲区所需的字节数。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rw_exact_all_at", since = "1.33.0")]
    fn read_exact_at(&self, mut buf: &mut [u8], mut offset: u64) -> io::Result<()> {
        while !buf.is_empty() {
            match self.read_at(buf, offset) {
                Ok(0) => break,
                Ok(n) => {
                    let tmp = buf;
                    buf = &mut tmp[n..];
                    offset += n as u64;
                }
                Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {}
                Err(e) => return Err(e),
            }
        }
        if !buf.is_empty() {
            Err(io::const_io_error!(io::ErrorKind::UnexpectedEof, "failed to fill whole buffer"))
        } else {
            Ok(())
        }
    }

    /// 从给定的偏移量开始写入多个字节。
    ///
    /// 返回写入的字节数。
    ///
    /// 偏移量相对于文件的开始，因此独立于当前游标。
    ///
    /// 当前文件游标不受此函数影响。
    ///
    /// 当写入超出文件末尾时，文件被适当扩展并且中间字节被初始化为值 0.
    ///
    ///
    /// 请注意，与 [`File::write`] 相似，返回短写也不是错误。
    ///
    ///
    fn write_at(&self, buf: &[u8], offset: u64) -> io::Result<usize> {
        let bufs = &[IoSlice::new(buf)];
        self.write_vectored_at(bufs, offset)
    }

    /// 从给定的偏移量开始写入多个字节。
    ///
    /// 返回写入的字节数。
    ///
    /// 偏移量相对于文件的开始，因此独立于当前游标。
    ///
    /// 当前文件游标不受此函数影响。
    ///
    /// 当写入超出文件末尾时，文件被适当扩展并且中间字节被初始化为值 0.
    ///
    ///
    /// 请注意，与 [`File::write_vectored`] 相似，返回短写也不是错误。
    ///
    ///
    fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize>;

    /// 尝试从给定的偏移量开始写入整个缓冲区。
    ///
    /// 偏移量相对于文件的开始，因此独立于当前游标。
    ///
    /// 当前文件游标不受此函数影响。
    ///
    /// 此方法将不断地调用 [`write_at`]，直到没有更多数据要写入或返回非 [`io::ErrorKind::Interrupted`] 类型的错误为止。
    /// 在成功写入整个缓冲区或发生此类错误之前，此方法将不会返回。
    /// 将返回第一个不是由该方法生成的 [`io::ErrorKind::Interrupted`] 类型的错误。
    ///
    /// # Errors
    ///
    /// 该函数将返回 [`write_at`] 返回的第一个非 [`io::ErrorKind::Interrupted`] 类型的错误。
    ///
    /// [`write_at`]: FileExt::write_at
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rw_exact_all_at", since = "1.33.0")]
    fn write_all_at(&self, mut buf: &[u8], mut offset: u64) -> io::Result<()> {
        while !buf.is_empty() {
            match self.write_at(buf, offset) {
                Ok(0) => {
                    return Err(io::const_io_error!(
                        io::ErrorKind::WriteZero,
                        "failed to write whole buffer",
                    ));
                }
                Ok(n) => {
                    buf = &buf[n..];
                    offset += n as u64
                }
                Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {}
                Err(e) => return Err(e),
            }
        }
        Ok(())
    }

    /// 返回文件中的当前位置。
    ///
    /// 这对应于 `fd_tell` syscall，并且类似于 `seek`，其中您从当前位置偏移了 0 个字节。
    ///
    fn tell(&self) -> io::Result<u64>;

    /// 调整与此文件关联的标志。
    ///
    /// 这对应于 `fd_fdstat_set_flags` syscall。
    fn fdstat_set_flags(&self, flags: u16) -> io::Result<()>;

    /// 调整与此文件关联的权限。
    ///
    /// 这对应于 `fd_fdstat_set_rights` syscall。
    fn fdstat_set_rights(&self, rights: u64, inheriting: u64) -> io::Result<()>;

    /// 提供有关文件描述符的文件咨询信息。
    ///
    /// 这对应于 `fd_advise` syscall。
    fn advise(&self, offset: u64, len: u64, advice: u8) -> io::Result<()>;

    /// 强制在文件中分配空间。
    ///
    /// 这对应于 `fd_allocate` syscall。
    fn allocate(&self, offset: u64, len: u64) -> io::Result<()>;

    /// 创建一个目录。
    ///
    /// 这对应于 `path_create_directory` syscall。
    fn create_directory<P: AsRef<Path>>(&self, dir: P) -> io::Result<()>;

    /// 读取符号链接的内容。
    ///
    /// 这对应于 `path_readlink` syscall。
    fn read_link<P: AsRef<Path>>(&self, path: P) -> io::Result<PathBuf>;

    /// 返回文件或目录的属性。
    ///
    /// 这对应于 `path_filestat_get` syscall。
    fn metadata_at<P: AsRef<Path>>(&self, lookup_flags: u32, path: P) -> io::Result<Metadata>;

    /// 取消链接文件。
    ///
    /// 这对应于 `path_unlink_file` syscall。
    fn remove_file<P: AsRef<Path>>(&self, path: P) -> io::Result<()>;

    /// 删除目录。
    ///
    /// 这对应于 `path_remove_directory` syscall。
    fn remove_directory<P: AsRef<Path>>(&self, path: P) -> io::Result<()>;
}

// FIXME: 绑定 fd_fdstat_get - 需要定义一个自定义返回类型
// FIXME: 绑定 fd_readdir - 无法返回 `ReadDir`，因为我们只有条目名
// FIXME: 绑定 fd_filestat_set_times 也许？ - 在 crates.io 上用于 unix
// FIXME: 绑定 path_filestat_set_times 也许？ - 在 crates.io 上用于 unix
// FIXME: 绑定 poll_oneoff 也许？ - 可能应该等待 I/O 稳定下来
// FIXME: 绑定 random_get 也许？ - 在 crates.io 上用于 unix

impl FileExt for fs::File {
    fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize> {
        self.as_inner().as_inner().pread(bufs, offset)
    }

    fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize> {
        self.as_inner().as_inner().pwrite(bufs, offset)
    }

    fn tell(&self) -> io::Result<u64> {
        self.as_inner().as_inner().tell()
    }

    fn fdstat_set_flags(&self, flags: u16) -> io::Result<()> {
        self.as_inner().as_inner().set_flags(flags)
    }

    fn fdstat_set_rights(&self, rights: u64, inheriting: u64) -> io::Result<()> {
        self.as_inner().as_inner().set_rights(rights, inheriting)
    }

    fn advise(&self, offset: u64, len: u64, advice: u8) -> io::Result<()> {
        let advice = match advice {
            a if a == wasi::ADVICE_NORMAL.raw() => wasi::ADVICE_NORMAL,
            a if a == wasi::ADVICE_SEQUENTIAL.raw() => wasi::ADVICE_SEQUENTIAL,
            a if a == wasi::ADVICE_RANDOM.raw() => wasi::ADVICE_RANDOM,
            a if a == wasi::ADVICE_WILLNEED.raw() => wasi::ADVICE_WILLNEED,
            a if a == wasi::ADVICE_DONTNEED.raw() => wasi::ADVICE_DONTNEED,
            a if a == wasi::ADVICE_NOREUSE.raw() => wasi::ADVICE_NOREUSE,
            _ => {
                return Err(io::const_io_error!(
                    io::ErrorKind::InvalidInput,
                    "invalid parameter 'advice'",
                ));
            }
        };

        self.as_inner().as_inner().advise(offset, len, advice)
    }

    fn allocate(&self, offset: u64, len: u64) -> io::Result<()> {
        self.as_inner().as_inner().allocate(offset, len)
    }

    fn create_directory<P: AsRef<Path>>(&self, dir: P) -> io::Result<()> {
        self.as_inner().as_inner().create_directory(osstr2str(dir.as_ref().as_ref())?)
    }

    fn read_link<P: AsRef<Path>>(&self, path: P) -> io::Result<PathBuf> {
        self.as_inner().read_link(path.as_ref())
    }

    fn metadata_at<P: AsRef<Path>>(&self, lookup_flags: u32, path: P) -> io::Result<Metadata> {
        let m = self.as_inner().metadata_at(lookup_flags, path.as_ref())?;
        Ok(FromInner::from_inner(m))
    }

    fn remove_file<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        self.as_inner().as_inner().unlink_file(osstr2str(path.as_ref().as_ref())?)
    }

    fn remove_directory<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        self.as_inner().as_inner().remove_directory(osstr2str(path.as_ref().as_ref())?)
    }
}

/// 特定于 WASI 的 [`fs::OpenOptions`] 的扩展。
pub trait OpenOptionsExt {
    /// 将自定义 `dirflags` 参数传递给 `path_open`。
    ///
    /// 此选项将 `dirflags` 参数配置为 `OpenOptions` 最终将调用的 `path_open` 系统调用。
    /// `dirflags` 参数配置如何查找文件，当前主要影响是否遵循符号链接。
    ///
    ///
    /// 默认情况下，此值为 `__WASI_LOOKUP_SYMLINK_FOLLOW`，否则将遵循符号链接。
    /// 您可以使用 0 调用此方法以禁用以下符号链接
    ///
    fn lookup_flags(&mut self, flags: u32) -> &mut Self;

    /// 指示 `OpenOptions` 是否必须打开目录。
    ///
    /// 此方法将配置打开文件时是否传递 `__WASI_O_DIRECTORY` 标志。
    /// 传递时，将要求打开的路径是目录。
    ///
    /// 默认情况下，此选项为 `false`
    ///
    fn directory(&mut self, dir: bool) -> &mut Self;

    /// 指示是否在 `path_open` 的 `fs_flags` 字段中传递 `__WASI_FDFLAG_DSYNC`。
    ///
    ///
    /// 默认情况下，此选项为 `false`
    fn dsync(&mut self, dsync: bool) -> &mut Self;

    /// 指示是否在 `path_open` 的 `fs_flags` 字段中传递 `__WASI_FDFLAG_NONBLOCK`。
    ///
    ///
    /// 默认情况下，此选项为 `false`
    fn nonblock(&mut self, nonblock: bool) -> &mut Self;

    /// 指示是否在 `path_open` 的 `fs_flags` 字段中传递 `__WASI_FDFLAG_RSYNC`。
    ///
    ///
    /// 默认情况下，此选项为 `false`
    fn rsync(&mut self, rsync: bool) -> &mut Self;

    /// 指示是否在 `path_open` 的 `fs_flags` 字段中传递 `__WASI_FDFLAG_SYNC`。
    ///
    ///
    /// 默认情况下，此选项为 `false`
    fn sync(&mut self, sync: bool) -> &mut Self;

    /// 指示应为 `path_open` 的 `fs_rights_base` 参数传递的值。
    ///
    /// 默认情况下，此选项基于此 `OpenOptions` 构建器的 `read` 和 `write` 配置。
    /// 但是，如果调用此方法，则将使用传入的确切掩码。
    ///
    ///
    fn fs_rights_base(&mut self, rights: u64) -> &mut Self;

    /// 指示应为 `path_open` 的 `fs_rights_inheriting` 参数传递的值。
    ///
    /// 此选项的默认值与将为 `fs_rights_base` 参数传递的值相同，但是如果调用此方法，则将使用指定的值代替。
    ///
    ///
    ///
    fn fs_rights_inheriting(&mut self, rights: u64) -> &mut Self;

    /// 打开文件或目录。
    ///
    /// 这对应于 `path_open` syscall。
    fn open_at<P: AsRef<Path>>(&self, file: &File, path: P) -> io::Result<File>;
}

impl OpenOptionsExt for OpenOptions {
    fn lookup_flags(&mut self, flags: u32) -> &mut OpenOptions {
        self.as_inner_mut().lookup_flags(flags);
        self
    }

    fn directory(&mut self, dir: bool) -> &mut OpenOptions {
        self.as_inner_mut().directory(dir);
        self
    }

    fn dsync(&mut self, enabled: bool) -> &mut OpenOptions {
        self.as_inner_mut().dsync(enabled);
        self
    }

    fn nonblock(&mut self, enabled: bool) -> &mut OpenOptions {
        self.as_inner_mut().nonblock(enabled);
        self
    }

    fn rsync(&mut self, enabled: bool) -> &mut OpenOptions {
        self.as_inner_mut().rsync(enabled);
        self
    }

    fn sync(&mut self, enabled: bool) -> &mut OpenOptions {
        self.as_inner_mut().sync(enabled);
        self
    }

    fn fs_rights_base(&mut self, rights: u64) -> &mut OpenOptions {
        self.as_inner_mut().fs_rights_base(rights);
        self
    }

    fn fs_rights_inheriting(&mut self, rights: u64) -> &mut OpenOptions {
        self.as_inner_mut().fs_rights_inheriting(rights);
        self
    }

    fn open_at<P: AsRef<Path>>(&self, file: &File, path: P) -> io::Result<File> {
        let inner = file.as_inner().open_at(path.as_ref(), self.as_inner())?;
        Ok(File::from_inner(inner))
    }
}

/// 特定于 WASI 的 [`fs::Metadata`] 的扩展。
pub trait MetadataExt {
    /// 返回内部 `filestat_t` 的 `st_dev` 字段
    fn dev(&self) -> u64;
    /// 返回内部 `filestat_t` 的 `st_ino` 字段
    fn ino(&self) -> u64;
    /// 返回内部 `filestat_t` 的 `st_nlink` 字段
    fn nlink(&self) -> u64;
    /// 返回内部 `filestat_t` 的 `st_size` 字段
    fn size(&self) -> u64;
    /// 返回内部 `filestat_t` 的 `st_atim` 字段
    fn atim(&self) -> u64;
    /// 返回内部 `filestat_t` 的 `st_mtim` 字段
    fn mtim(&self) -> u64;
    /// 返回内部 `filestat_t` 的 `st_ctim` 字段
    fn ctim(&self) -> u64;
}

impl MetadataExt for fs::Metadata {
    fn dev(&self) -> u64 {
        self.as_inner().as_wasi().dev
    }
    fn ino(&self) -> u64 {
        self.as_inner().as_wasi().ino
    }
    fn nlink(&self) -> u64 {
        self.as_inner().as_wasi().nlink
    }
    fn size(&self) -> u64 {
        self.as_inner().as_wasi().size
    }
    fn atim(&self) -> u64 {
        self.as_inner().as_wasi().atim
    }
    fn mtim(&self) -> u64 {
        self.as_inner().as_wasi().mtim
    }
    fn ctim(&self) -> u64 {
        self.as_inner().as_wasi().ctim
    }
}

/// 特定于 WASI 的 [`fs::FileType`] 的扩展。
///
/// 增加了对特殊 WASI 文件类型的支持，例如 block/character 设备，管道和套接字。
///
pub trait FileTypeExt {
    /// 如果此文件类型是块设备，则返回 `true`。
    fn is_block_device(&self) -> bool;
    /// 如果此文件类型是字符设备，则返回 `true`。
    fn is_char_device(&self) -> bool;
    /// 如果此文件类型是套接字数据报，则返回 `true`。
    fn is_socket_dgram(&self) -> bool;
    /// 如果此文件类型是套接字流，则返回 `true`。
    fn is_socket_stream(&self) -> bool;
    /// 如果此文件类型是任何类型的套接字，则返回 `true`。
    fn is_socket(&self) -> bool {
        self.is_socket_stream() || self.is_socket_dgram()
    }
}

impl FileTypeExt for fs::FileType {
    fn is_block_device(&self) -> bool {
        self.as_inner().bits() == wasi::FILETYPE_BLOCK_DEVICE
    }
    fn is_char_device(&self) -> bool {
        self.as_inner().bits() == wasi::FILETYPE_CHARACTER_DEVICE
    }
    fn is_socket_dgram(&self) -> bool {
        self.as_inner().bits() == wasi::FILETYPE_SOCKET_DGRAM
    }
    fn is_socket_stream(&self) -> bool {
        self.as_inner().bits() == wasi::FILETYPE_SOCKET_STREAM
    }
}

/// 特定于 WASI 的 [`fs::DirEntry`] 的扩展方法。
pub trait DirEntryExt {
    /// 返回 `dirent_t` 的底层 `d_ino` 字段
    fn ino(&self) -> u64;
}

impl DirEntryExt for fs::DirEntry {
    fn ino(&self) -> u64 {
        self.as_inner().ino()
    }
}

/// 创建一个硬链接。
///
/// 这对应于 `path_link` syscall。
pub fn link<P: AsRef<Path>, U: AsRef<Path>>(
    old_fd: &File,
    old_flags: u32,
    old_path: P,
    new_fd: &File,
    new_path: U,
) -> io::Result<()> {
    old_fd.as_inner().as_inner().link(
        old_flags,
        osstr2str(old_path.as_ref().as_ref())?,
        new_fd.as_inner().as_inner(),
        osstr2str(new_path.as_ref().as_ref())?,
    )
}

/// 重命名文件或目录。
///
/// 这对应于 `path_rename` syscall。
pub fn rename<P: AsRef<Path>, U: AsRef<Path>>(
    old_fd: &File,
    old_path: P,
    new_fd: &File,
    new_path: U,
) -> io::Result<()> {
    old_fd.as_inner().as_inner().rename(
        osstr2str(old_path.as_ref().as_ref())?,
        new_fd.as_inner().as_inner(),
        osstr2str(new_path.as_ref().as_ref())?,
    )
}

/// 创建一个符号链接。
///
/// 这对应于 `path_symlink` syscall。
pub fn symlink<P: AsRef<Path>, U: AsRef<Path>>(
    old_path: P,
    fd: &File,
    new_path: U,
) -> io::Result<()> {
    fd.as_inner()
        .as_inner()
        .symlink(osstr2str(old_path.as_ref().as_ref())?, osstr2str(new_path.as_ref().as_ref())?)
}

/// 创建一个符号链接。
///
/// 这是一种便捷的 API，类似于 `std::os::unix::fs::symlink`，`std::os::windows::fs::symlink_file` 和 `std::os::windows::fs::symlink_dir`。
///
pub fn symlink_path<P: AsRef<Path>, U: AsRef<Path>>(old_path: P, new_path: U) -> io::Result<()> {
    crate::sys::fs::symlink(old_path.as_ref(), new_path.as_ref())
}

fn osstr2str(f: &OsStr) -> io::Result<&str> {
    f.to_str()
        .ok_or_else(|| io::const_io_error!(io::ErrorKind::Uncategorized, "input must be utf-8"))
}