d-major 0.0.0

/*
 * Description: Wrap POSIX OS resources.
 * This code is largely copied from the rust compiler's sys/fs/unix.rs: https://github.com/rust-lang/rust/blob/cbfdf0b014cb04982a9cbeec1578001001167f6e/library/std/src/sys/fs/unix.rs.
 * The rust compiler is distributed under both the MIT and Apache v2 licenses.
 *
 * Copyright (C) 2025 d@nny mc² <dmc2@hypnicjerk.ai>
 * SPDX-License-Identifier: LGPL-3.0-or-later
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published
 * by the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

#![cfg(unix)]

//! Wrap POSIX OS resources.
//!
//! This code is largely copied from the rust compiler's [`sys/fs/unix.rs`](https://github.com/rust-lang/rust/blob/cbfdf0b014cb04982a9cbeec1578001001167f6e/library/std/src/sys/fs/unix.rs).

use std::{io, iter, marker::PhantomData, mem::MaybeUninit, ops, os::fd, path::Path};

use parking_lot::{Mutex, MutexGuard};

use crate::{
  libc_imports,
  null_term_str::{NullTermStr, NullTermString},
};


#[repr(transparent)]
pub struct Dir(*mut libc::DIR);

unsafe impl Send for Dir {}
unsafe impl Sync for Dir {}

impl Dir {
  pub fn opendir(path: &Path) -> io::Result<Self> {
    crate::c_string::run_path_with_cstr(path, |p| {
      let dir_ptr = unsafe { libc::opendir(p.as_ptr()) };
      if dir_ptr.is_null() {
        Err(io::Error::last_os_error())
      } else {
        Ok(Self(dir_ptr))
      }
    })
  }

  fn do_readdir(
    &mut self,
  ) -> Result<Option<(NullTermStr<'_>, libc_imports::dirent64_min)>, io::Error> {
    // As of POSIX.1-2017, readdir() is not required to be thread safe; only
    // readdir_r() is. However, readdir_r() cannot correctly handle platforms
    // with unlimited or variable NAME_MAX. Many modern platforms guarantee
    // thread safety for readdir() as long an individual DIR* is not accessed
    // concurrently, which is sufficient for Rust.

    // To distinguish between errors and end-of-directory, we had to clear
    // errno beforehand and check for an error afterwards.
    let entry_ptr: *const libc_imports::dirent64 =
      crate::errno::with_cleared_errno(|| unsafe { libc_imports::readdir64(self.0) })?;
    /* End of directory, with no io error. */
    if entry_ptr.is_null() {
      return Ok(None);
    }
    debug_assert!(crate::errno::errno_is_unset());

    // The dirent64 struct is a weird imaginary thing that isn't ever supposed
    // to be worked with by value. Its trailing d_name field is declared
    // variously as [c_char; 256] or [c_char; 1] on different systems but
    // either way that size is meaningless; only the offset of d_name is
    // meaningful. The dirent64 pointers that libc returns from readdir64 are
    // allowed to point to allocations smaller _or_ LARGER than implied by the
    // definition of the struct.
    //
    // As such, we need to be even more careful with dirent64 than if its
    // contents were "simply" partially initialized data.
    //
    // Like for uninitialized contents, converting entry_ptr to `&dirent64`
    // would not be legal. However, we can use `&raw const (*entry_ptr).d_name`
    // to refer the fields individually, because that operation is equivalent
    // to `byte_offset` and thus does not require the full extent of `*entry_ptr`
    // to be in bounds of the same allocation, only the offset of the field
    // being referenced.

    // d_name is guaranteed to be null-terminated.
    let name = unsafe { NullTermStr::from_ptr((&raw const (*entry_ptr).d_name).cast()) };

    let entry = unsafe { libc_imports::dirent64_min::new(entry_ptr) };

    Ok(Some((name, entry)))
  }
}

impl ops::Drop for Dir {
  fn drop(&mut self) {
    let r = unsafe { libc::closedir(self.0) };
    if r != 0 {
      let err = io::Error::last_os_error();
      match err.kind() {
        io::ErrorKind::Interrupted => (),
        _ => panic!("unexpected error during closedir: {:?}", err),
      }
    }
  }
}


#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub enum EagerFileType {
  File = libc::DT_REG,
  Dir = libc::DT_DIR,
  Symlink = libc::DT_LNK,
  Other(libc::c_uchar),
}

impl EagerFileType {
  pub(crate) const fn from_type(d_type: libc::c_uchar) -> Self {
    match d_type {
      libc::DT_REG => Self::File,
      libc::DT_DIR => Self::Dir,
      libc::DT_LNK => Self::Symlink,
      x => Self::Other(x),
    }
  }
}


pub mod traits {
  use std::io;

  use super::{Dir, EagerFileType};
  use crate::{
    libc_imports,
    null_term_str::{MeasuredNullTermStr, NullTermStr, NullTermString},
  };

  pub trait ReaddirErr {
    fn into_err(self) -> io::Error;
  }

  pub trait ReaddirInfo {}

  pub trait HasInode: ReaddirInfo {
    fn ino(&self) -> libc_imports::ino64_t;
  }

  pub trait HasEagerType: ReaddirInfo {
    fn eager_file_type(&self) -> EagerFileType;
  }
  pub trait HasNoEagerType: ReaddirInfo {}

  pub trait HasName: ReaddirInfo {
    fn name(&self) -> NullTermStr<'_>;
  }
  pub trait HasMeasuredName: HasName {
    fn measured_name(&self) -> MeasuredNullTermStr<'_>;
  }

  pub trait ReaddirResult<'d> {
    fn readdir(dir: &'d mut Dir) -> Self
    where Self: Sized+'d;

    type Info: ReaddirInfo;
    type Err: ReaddirErr;
    fn into_result(self) -> Result<Option<Self::Info>, Self::Err>;

    type OwnInfo: ReaddirInfo;
    fn into_owned(info: Self::Info, args: NullTermString) -> Self::OwnInfo;
  }
}


/// One particular implementation of [`traits`] which uses the most general POSIX interface.
///
/// These structs retain a reference to the [`Dir`] object, which is not necessary for platforms
/// that can use the `readdir_r()` method and impose a maximum size on filename length. The rust
/// stdlib uses this approach for several BSDs and macos.
pub mod result {
  use std::io;

  use super::{traits, Dir, EagerFileType};
  use crate::{
    libc_imports,
    null_term_str::{AsNullTermStr, MeasuredNullTermStr, NullTermStr, NullTermString},
  };

  #[repr(transparent)]
  pub struct ReaddirErr(io::Error);

  impl ReaddirErr {
    pub fn into_err(self) -> io::Error { self.0 }
  }

  impl traits::ReaddirErr for ReaddirErr {
    fn into_err(self) -> io::Error { Self::into_err(self) }
  }

  #[derive(Copy, Clone, Debug)]
  pub struct ReaddirInfo<'d, Info> {
    name: NullTermStr<'d>,
    info: Info,
  }

  impl<'d, Info> ReaddirInfo<'d, Info> {
    pub fn ino(&self) -> libc_imports::ino64_t
    where Info: libc_imports::HasInode {
      self.info.ino()
    }

    pub fn eager_file_type(&self) -> EagerFileType
    where Info: libc_imports::HasEagerType {
      EagerFileType::from_type(self.info.eager_file_type())
    }

    pub const fn name(&self) -> NullTermStr<'d> { self.name }

    pub fn measured_name(&self) -> MeasuredNullTermStr<'d>
    where Info: libc_imports::MeasureNameLen {
      self.info.measure_name_len(self.name())
    }
  }

  impl<Info> traits::ReaddirInfo for ReaddirInfo<'_, Info> {}

  impl<Info> traits::HasInode for ReaddirInfo<'_, Info>
  where Info: libc_imports::HasInode
  {
    fn ino(&self) -> libc_imports::ino64_t { Self::ino(self) }
  }

  impl<Info> traits::HasEagerType for ReaddirInfo<'_, Info>
  where Info: libc_imports::HasEagerType
  {
    fn eager_file_type(&self) -> EagerFileType { Self::eager_file_type(self) }
  }
  impl<Info> traits::HasNoEagerType for ReaddirInfo<'_, Info> where Info: libc_imports::HasNoEagerType {}

  impl<'d, Info> traits::HasName for ReaddirInfo<'d, Info> {
    fn name(&self) -> NullTermStr<'_> { Self::name(self) }
  }

  impl<'d, Info> traits::HasMeasuredName for ReaddirInfo<'d, Info>
  where Info: libc_imports::MeasureNameLen
  {
    fn measured_name(&self) -> MeasuredNullTermStr<'_> { Self::measured_name(self) }
  }

  pub struct OwnedInfo<Info> {
    name: NullTermString,
    info: Info,
  }

  impl<Info> OwnedInfo<Info> {
    pub fn from_info(info: ReaddirInfo<'_, Info>, mut s: NullTermString) -> Self
    where Info: libc_imports::MeasureNameLen {
      info.measured_name().clone_into(&mut s);
      Self {
        name: s,
        info: info.info,
      }
    }

    pub fn ino(&self) -> libc_imports::ino64_t
    where Info: libc_imports::HasInode {
      self.info.ino()
    }

    pub fn eager_file_type(&self) -> EagerFileType
    where Info: libc_imports::HasEagerType {
      EagerFileType::from_type(self.info.eager_file_type())
    }

    pub fn name(&self) -> NullTermStr<'_> { self.measured_name().as_unmeasured() }

    pub fn measured_name(&self) -> MeasuredNullTermStr<'_> { self.name.as_null_term_str() }
  }
  impl<Info> traits::ReaddirInfo for OwnedInfo<Info> {}
  impl<Info> traits::HasInode for OwnedInfo<Info>
  where Info: libc_imports::HasInode
  {
    fn ino(&self) -> libc_imports::ino64_t { Self::ino(self) }
  }
  impl<Info> traits::HasEagerType for OwnedInfo<Info>
  where Info: libc_imports::HasEagerType
  {
    fn eager_file_type(&self) -> EagerFileType { Self::eager_file_type(self) }
  }
  impl<Info> traits::HasNoEagerType for OwnedInfo<Info> where Info: libc_imports::HasNoEagerType {}
  impl<Info> traits::HasName for OwnedInfo<Info> {
    fn name(&self) -> NullTermStr<'_> { Self::name(self) }
  }
  impl<Info> traits::HasMeasuredName for OwnedInfo<Info> {
    fn measured_name(&self) -> MeasuredNullTermStr<'_> { Self::measured_name(self) }
  }

  #[repr(transparent)]
  pub struct ReaddirResult<'d>(
    Result<Option<(NullTermStr<'d>, libc_imports::dirent64_min)>, io::Error>,
  );

  impl<'d> ReaddirResult<'d> {
    pub fn readdir(dir: &'d mut Dir) -> Self { Self(dir.do_readdir()) }

    pub fn into_result(
      self,
    ) -> Result<Option<ReaddirInfo<'d, libc_imports::dirent64_min>>, ReaddirErr> {
      match self {
        Self(Err(e)) => Err(ReaddirErr(e)),
        Self(Ok(v)) => Ok(v.map(|(name, info)| ReaddirInfo { name, info })),
      }
    }
  }

  impl<'d> traits::ReaddirResult<'d> for ReaddirResult<'d> {
    fn readdir(dir: &'d mut Dir) -> Self
    where Self: Sized+'d {
      Self::readdir(dir)
    }

    type Info = ReaddirInfo<'d, libc_imports::dirent64_min>;
    type Err = ReaddirErr;
    fn into_result(self) -> Result<Option<Self::Info>, Self::Err> { Self::into_result(self) }

    type OwnInfo = OwnedInfo<libc_imports::dirent64_min>;
    fn into_owned(info: Self::Info, args: NullTermString) -> Self::OwnInfo {
      OwnedInfo::from_info(info, args)
    }
  }

  #[cfg(test)]
  mod test {
    use std::{fs, io};

    use tempdir::TempDir;

    use super::{super::*, *};

    #[test]
    fn read_single() -> io::Result<()> {
      let td = TempDir::new("asdf")?;
      fs::write(td.path().join("f.txt"), "asdf\n")?;

      let mut dir = Dir::opendir(td.path())?;

      let d = ReaddirResult::readdir(&mut dir)
        .into_result()
        .map_err(|e| e.into_err())?
        .unwrap();
      assert_eq!(d.measured_name().as_os_str().to_str().unwrap(), ".");

      let d = ReaddirResult::readdir(&mut dir)
        .into_result()
        .map_err(|e| e.into_err())?
        .unwrap();
      assert_eq!(d.measured_name().as_os_str().to_str().unwrap(), "..");

      let f = ReaddirResult::readdir(&mut dir)
        .into_result()
        .map_err(|e| e.into_err())?
        .unwrap();
      assert_eq!(f.measured_name().as_os_str().to_str().unwrap(), "f.txt");

      assert!(ReaddirResult::readdir(&mut dir)
        .into_result()
        .map_err(|e| e.into_err())?
        .is_none());


      Ok(())
    }
  }
}


pub struct DirCollector<R> {
  dir: Dir,
  _ph: PhantomData<R>,
  done: bool,
}

impl<R> DirCollector<R> {
  pub const fn new(dir: Dir) -> Self {
    Self {
      dir,
      _ph: PhantomData,
      done: false,
    }
  }

  pub const fn is_done(&self) -> bool { self.done }
}

impl<R> Iterator for DirCollector<R>
where
  for<'e> R: traits::ReaddirResult<'e>,
  for<'e> <R as traits::ReaddirResult<'e>>::Info: traits::HasName,
{
  type Item = Result<<R as traits::ReaddirResult<'static>>::OwnInfo, io::Error>;

  fn next(&mut self) -> Option<Self::Item> {
    if self.done {
      return None;
    }

    loop {
      use traits::{HasName, ReaddirErr};

      let Some(result) = R::readdir(&mut self.dir).into_result().transpose() else {
        self.done = true;
        return None;
      };
      return Some(match result {
        Err(e) => Err(e.into_err()),
        Ok(info) => {
          /* If it matches '.' or '..', pretend it's not there. */
          if info.name().match_dir_entries_unmeasured() {
            continue;
          }
          /* TODO: pool allocations for strings? */
          let owned = R::into_owned(info, NullTermString::new());
          Ok(owned)
        },
      });
    }
  }
}

impl<R> iter::FusedIterator for DirCollector<R>
where
  for<'e> R: traits::ReaddirResult<'e>,
  for<'e> <R as traits::ReaddirResult<'e>>::Info: traits::HasName,
{
}


/// Pair a [`Dir`] struct with a file descriptor, usable for dir-relative operations like
/// [`Self::openat()`] and [`Self::fstatat()`].
///
/// # Lifetimes and Mutability
/// We want to achieve several things at once here:
/// 1. The [`DirCollector`] (with a **mutable** handle to the [`Dir`] struct) can be iterated *in
///    parallel* with the `OwnInfo` entries it has already spawned.
/// 2. Each entry has a handle to the file descriptor, which can be sent to another thread and
///    operated upon indepdendently of the `readdir()` iteration.
/// 3. This [`DirFd`] struct (and the internal [`Dir`] instance it owns) is not dropped until all
///    entries have been processed.
/// 4. We want to be able to implement some form of backpressure in order to limit the number of
///    open file handles across the crawl.
///
/// This likely involves some dependency on the end-user API in [`crate::crawl`], as the user will
/// define when the handle should be dropped, especially given (4) (limiting open file handles).
///
/// In [`crate::crawl`], we define an "end-user API", but which we ourselves will be using in order
/// to limit open file handles. We would *like* to avoid explicitly sending entries to threads yet,
/// but this may be a false hope--if we want to implement resource management like limiting open
/// file handles, and we *also* need to e.g. invoke [`Self::fstatat()`] for platforms which do not
/// provide [`EagerFileType`], we will probably need to architect resource management and then
/// expose a separate external end-user API from [`crate::crawl`].
///
/// I *think* we can use an [`UnsafeCell`](std::cell::UnsafeCell) for this, but we will need to be
/// very careful to demarcate iteration vs dereferencing the fd. We would *like* to use
/// [`Weak`](std::sync::Weak) pointers, but we do actually need each entry to keep this [`DirFd`]
/// alive until all have been processed.
///
/// ## Proposal: Global Registry
/// I think this implies that [`DirFd`] instances should be kept within some global registry, and
/// explicitly dropped when we are *positive* all their entries have been processed.
pub struct DirFd<R> {
  dir: Mutex<DirCollector<R>>,
  fd: fd::RawFd,
}

impl<R> DirFd<R> {
  const fn new(dir: Dir, fd: fd::RawFd) -> Self {
    Self {
      dir: Mutex::new(DirCollector::new(dir)),
      fd,
    }
  }

  #[allow(clippy::self_named_constructors)]
  pub fn dirfd(dir: Dir) -> io::Result<Self> {
    let fd = unsafe { libc::dirfd(dir.0) };
    if fd == -1 {
      Err(io::Error::last_os_error())
    } else {
      Ok(Self::new(dir, fd))
    }
  }

  pub fn fdopendir(fd: fd::RawFd) -> io::Result<Self> {
    let dir_ptr = unsafe { libc::fdopendir(fd) };
    if dir_ptr.is_null() {
      Err(io::Error::last_os_error())
    } else {
      let dir = Dir(dir_ptr);
      Ok(Self::new(dir, fd))
    }
  }

  fn lock_dir(&self) -> MutexGuard<'_, DirCollector<R>> { self.dir.lock() }

  pub fn dir(
    &self,
  ) -> impl ops::DerefMut<
    Target=impl Iterator<Item=Result<<R as traits::ReaddirResult<'static>>::OwnInfo, io::Error>>+iter::FusedIterator,
  >
  where
    for<'e> R: traits::ReaddirResult<'e>,
    for<'e> <R as traits::ReaddirResult<'e>>::Info: traits::HasName,
  {
    self.lock_dir()
  }

  pub const fn fd(&self) -> fd::RawFd { self.fd }

  pub fn openat(&self, name: NullTermStr<'_>) -> io::Result<fd::RawFd> {
    debug_assert!(
      !name.match_dir_entries_unmeasured(),
      "can't open dir entries '.' or '..'"
    );
    /* FIXME: allow the user to do whatever they want with the file, not just open read-only! */
    /* FIXME: open directories separately from files! */
    /* FIXME: determine whether to follow symlinks! */
    let fd = unsafe { libc_imports::openat64(self.fd, name.as_ptr(), libc::O_RDONLY) };
    if fd == -1 {
      Err(io::Error::last_os_error())
    } else {
      Ok(fd)
    }
  }

  pub fn fstatat(&self, name: NullTermStr<'_>) -> io::Result<libc_imports::stat64> {
    debug_assert!(
      !name.match_dir_entries_unmeasured(),
      "can't stat dir entries '.' or '..'"
    );
    let mut stat = MaybeUninit::<libc_imports::stat64>::uninit();
    let rc = unsafe {
      libc_imports::fstatat64(
        self.fd,
        name.as_ptr(),
        stat.as_mut_ptr(),
        /* FIXME: determine whether to follow symlinks! */
        libc::AT_SYMLINK_NOFOLLOW,
      )
    };
    if rc == -1 {
      Err(io::Error::last_os_error())
    } else {
      debug_assert_eq!(rc, 0);
      let stat = unsafe { stat.assume_init() };
      Ok(stat)
    }
  }
}

/// Check if a file descriptor is not open.
///
/// Many IO syscalls can't be fully trusted about EBADF error codes because those
/// might get bubbled up from a remote FUSE server rather than the file descriptor
/// in the current process being invalid.
///
/// So we check file flags instead which live on the file descriptor and not the underlying file.
/// The downside is that it costs an extra syscall, so we only do it for debug.
#[inline]
fn fd_is_invalid(fd: fd::RawFd) -> bool {
  (unsafe { libc::fcntl(fd, libc::F_GETFD) } == -1) && crate::errno::errno() == libc::EBADF
}

impl<R> ops::Drop for DirFd<R> {
  fn drop(&mut self) {
    debug_assert!(!fd_is_invalid(self.fd));
  }
}