air_sys_types/

fd.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! Descripteurs de fichiers propriétaires et empruntés — types FD natifs d'Air.
//!
//! Ce module définit les types FD de la couche 0 sans dépendre de
//! `std::os::fd` : il n'utilise que `core` plus un appel `close(2)` en
//! assembleur inline pour le `Drop`. C'est le préalable au passage
//! `#![no_std]` de la crate (cf. ADR-048 Amendement 1) : `core::os::fd`
//! n'existe pas sur Rust stable, Air doit donc posséder ses propres types.
//!
//! # Conception — miroir de `std::os::fd`
//!
//! L'API publique est calquée sur `std::os::fd` (mêmes noms de types,
//! méthodes et traits, mêmes signatures) afin que la migration des sites
//! d'appel soit purement mécanique et que le modèle mental reste celui de
//! la bibliothèque standard :
//!
//! - [`RawFd`] : alias de `i32`, identique à `std::os::fd::RawFd`.
//! - [`OwnedFd`] : possède le FD, le ferme à `Drop` (RAII).
//! - [`BorrowedFd<'fd>`] : emprunte le FD pour la durée `'fd`, ne ferme rien.
//! - traits [`AsRawFd`], [`AsFd`], [`FromRawFd`], [`IntoRawFd`].
//!
//! # Invariant de validité `-1` et absence de niche (contrainte stable)
//!
//! `std::os::fd` réserve la valeur `-1` (sentinelle d'erreur du kernel)
//! comme **niche**, ce qui donne à `Option<OwnedFd>` la même taille qu'un
//! `OwnedFd`. La std obtient cette niche via l'attribut interne
//! `rustc_layout_scalar_valid_range_start/end`, qui exige la *feature*
//! nightly `rustc_attrs` — **indisponible sur Rust stable** (et le passage
//! stable est précisément la raison d'être d'ADR-048).
//!
//! **Cette niche ne peut pas être répliquée sur stable.** Une tentative de la
//! simuler en stockant le FD sous forme transformée (`!raw` dans un
//! `NonZeroI32`, biais `+1`, …) introduirait un bug **grave** : les types FD
//! sont incrustés *tels quels* dans des structures `#[repr(C)]` miroir du
//! kernel — au premier chef [`crate::poll::PollFd`], bit-pour-bit
//! `struct pollfd` dont le champ `fd` **est** un [`BorrowedFd`]. Le kernel lit
//! alors le motif binaire brut du champ : il **doit** valoir le FD réel. Toute
//! transformation le corromprait (le kernel polît/ferme un mauvais FD).
//!
//! Air stocke donc le FD **brut** dans un `i32` (`#[repr(transparent)]`),
//! exactement comme le motif mémoire de la std :
//!
//! - motif binaire == FD réel ⇒ incrustation `#[repr(C)]` correcte (PollFd…) ;
//! - même layout mémoire que `std::os::fd::OwnedFd`/`BorrowedFd` (transparent
//!   sur `i32`), donc le pont [`RawFd`] est exact ;
//! - **conséquence** : `size_of::<Option<OwnedFd>>() == 8` (pas de niche),
//!   contre 4 pour la std. C'est le seul écart observable, assumé et scellé
//!   comme contrat air-stable jusqu'à ce qu'un mécanisme de niche stable
//!   existe (le cas échéant, ré-ouvrir par RFC sans changer le motif binaire).
//!
//! L'invariant « `raw != -1` » reste une **précondition** documentée des
//! constructeurs `unsafe` (`from_raw_fd`/`borrow_raw`), comme dans la std ;
//! il n'est simplement plus encodé dans la représentation.

use core::marker::PhantomData;

/// Descripteur de fichier brut : l'entier signé manipulé par le kernel.
///
/// Identique à `std::os::fd::RawFd` (`i32`). Une valeur négative `-1` est la
/// sentinelle d'erreur kernel ; elle n'est jamais un FD valide et reste
/// interdite dans [`OwnedFd`] / [`BorrowedFd`].
pub type RawFd = i32;

// ─────────────────────────────────────────────────────────────────────────
// close(2) — syscall minimal en assembleur inline, par architecture.
//
// `air-sys-types` n'embarquait aucun syscall jusqu'ici ; la spec couche 0
// l'autorise pour le seul besoin du `Drop` de `OwnedFd`. Numéros de syscall
// `asm-generic` : x86_64 = 3, aarch64 = 57.
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
const SYS_CLOSE: i64 = 3;
#[cfg(target_arch = "aarch64")]
const SYS_CLOSE: i64 = 57;

/// Ferme `fd` en best-effort, **en ignorant le résultat**.
///
/// Utilisé uniquement par le `Drop` de [`OwnedFd`]. Sur Linux, le FD est
/// libéré par le kernel même lorsque `close(2)` renvoie `EINTR` : il ne faut
/// donc **jamais** ré-essayer (un retry fermerait un FD potentiellement
/// recyclé entre-temps par un autre thread). La fonction explicite [`close`]
/// de `air-sys-syscall` reste disponible quand l'appelant veut récupérer
/// l'erreur.
///
/// [`close`]: https://man7.org/linux/man-pages/man2/close.2.html
#[cfg(target_arch = "x86_64")]
#[inline]
fn close_ignoring_result(fd: RawFd) {
    // SAFETY:
    // - `SYS_CLOSE` (3) prend un unique argument entier dans `rdi` ; close(2)
    //   ne déréférence aucune mémoire utilisateur, l'appel est donc sûr pour
    //   tout entier.
    // - `fd` provient d'un `OwnedFd` valide en cours de destruction : il est
    //   ouvert et possédé, et n'est utilisé qu'ici avant oubli.
    // - clobbers `rcx`/`r11` (convention `syscall`), résultat ignoré.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") SYS_CLOSE,
            in("rdi") i64::from(fd),
            lateout("rax") _,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
}

/// Variante aarch64 de [`close_ignoring_result`].
#[cfg(target_arch = "aarch64")]
#[inline]
fn close_ignoring_result(fd: RawFd) {
    // SAFETY:
    // - `SYS_CLOSE` (57) prend un unique argument entier dans `x0` ; close(2)
    //   ne déréférence aucune mémoire utilisateur, l'appel est donc sûr pour
    //   tout entier.
    // - `fd` provient d'un `OwnedFd` valide en cours de destruction : il est
    //   ouvert et possédé, et n'est utilisé qu'ici avant oubli.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") SYS_CLOSE,
            inout("x0") i64::from(fd) => _,
            options(nostack, preserves_flags),
        );
    }
}

// ─────────────────────────────────────────────────────────────────────────
// OwnedFd
// ─────────────────────────────────────────────────────────────────────────

/// Un descripteur de fichier **possédé**, fermé automatiquement à `Drop`.
///
/// `OwnedFd` est le garant RAII de la couche 0 : tant qu'il vit, le FD est
/// garanti ouvert ; quand il est détruit, `close(2)` est appelé une seule
/// fois. Pour récupérer une éventuelle erreur de fermeture, consommer le FD
/// via `air_sys_syscall::fs::close` plutôt que de laisser jouer le `Drop`.
///
/// Représentation : `#[repr(transparent)]` sur un [`RawFd`] (`i32`) contenant
/// le FD **brut** — motif binaire identique à `std::os::fd::OwnedFd`. Pas de
/// niche sur stable (cf. doc du module) : `size_of::<Option<OwnedFd>>() == 8`.
#[repr(transparent)]
pub struct OwnedFd {
    /// FD brut possédé. Précondition d'`OwnedFd` : `!= -1` (sentinelle kernel).
    fd: RawFd,
}

impl OwnedFd {
    /// Retourne le [`RawFd`] brut détenu (usage interne).
    #[inline]
    fn raw(&self) -> RawFd {
        self.fd
    }
}

// Conformément à `std::os::fd`, les opérations publiques d'`OwnedFd`
// (`as_fd`, `into_raw_fd`, `from_raw_fd`, `as_raw_fd`) sont exposées via les
// **traits** miroir [`AsFd`], [`IntoRawFd`], [`FromRawFd`], [`AsRawFd`] (cf.
// plus bas) — et non comme méthodes inhérentes. Cela calque exactement l'API
// std : un site d'appel importe le trait (`use air_sys_types::fd::AsFd`) puis
// appelle `owned.as_fd()`, comme il importait `std::os::fd::AsFd` avant.

impl Drop for OwnedFd {
    #[inline]
    fn drop(&mut self) {
        // Best-effort : on ferme une seule fois et on ignore le résultat.
        // Linux libère le FD même sur EINTR ⇒ pas de retry (cf. ADR-021 §2).
        close_ignoring_result(self.raw());
    }
}

impl core::fmt::Debug for OwnedFd {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("OwnedFd").field("fd", &self.raw()).finish()
    }
}

// ─────────────────────────────────────────────────────────────────────────
// BorrowedFd
// ─────────────────────────────────────────────────────────────────────────

/// Un descripteur de fichier **emprunté**, valide pour la durée `'fd`.
///
/// `BorrowedFd` n'a **pas** de `Drop` : il ne ferme jamais le FD. Sa durée de
/// vie `'fd` garantit qu'il ne survit pas au propriétaire ([`OwnedFd`] ou
/// ressource équivalente). C'est l'argument à passer à un syscall qui lit un
/// FD sans en prendre l'ownership.
///
/// Même représentation que [`OwnedFd`] : `#[repr(transparent)]` sur un
/// [`RawFd`] brut, plus un marqueur de durée de vie de taille nulle. C'est ce
/// qui permet d'incruster un `BorrowedFd` dans une structure `#[repr(C)]`
/// miroir du kernel (ex. [`crate::poll::PollFd`] = `struct pollfd`) : le champ
/// `fd` y vaut bien le FD brut attendu par le kernel.
#[repr(transparent)]
#[derive(Clone, Copy)]
pub struct BorrowedFd<'fd> {
    /// FD brut emprunté. Précondition : `!= -1`.
    fd: RawFd,
    _phantom: PhantomData<&'fd OwnedFd>,
}

impl BorrowedFd<'_> {
    /// Retourne le [`RawFd`] brut emprunté (usage interne).
    #[inline]
    fn raw(&self) -> RawFd {
        self.fd
    }

    /// Construit un `BorrowedFd` empruntant `fd` pour la durée `'fd`.
    ///
    /// # Safety
    ///
    /// - `fd` doit être un descripteur ouvert et valide pour toute la durée
    ///   `'fd` choisie par l'appelant ;
    /// - `fd` doit être **différent de `-1`** ;
    /// - aucun ownership n'est transféré : le FD ne doit pas être fermé tant
    ///   que des `BorrowedFd` de durée `'fd` peuvent encore l'utiliser.
    #[must_use]
    #[inline]
    pub unsafe fn borrow_raw<'fd>(fd: RawFd) -> BorrowedFd<'fd> {
        BorrowedFd {
            fd,
            _phantom: PhantomData,
        }
    }
}

impl core::fmt::Debug for BorrowedFd<'_> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("BorrowedFd")
            .field("fd", &self.raw())
            .finish()
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Traits miroir de `std::os::fd`
// ─────────────────────────────────────────────────────────────────────────

/// Expose le [`RawFd`] brut d'une ressource, sans transfert d'ownership.
///
/// Miroir de `std::os::fd::AsRawFd`.
pub trait AsRawFd {
    /// Retourne le FD brut sous-jacent.
    fn as_raw_fd(&self) -> RawFd;
}

/// Emprunte le FD d'une ressource sous forme de [`BorrowedFd`].
///
/// Miroir de `std::os::fd::AsFd`. À préférer à [`AsRawFd`] : la durée de vie
/// retournée empêche l'usage après fermeture.
pub trait AsFd {
    /// Emprunte le FD pour la durée de l'emprunt `&self`.
    fn as_fd(&self) -> BorrowedFd<'_>;
}

/// Construit une ressource possédant un [`RawFd`].
///
/// Miroir de `std::os::fd::FromRawFd`.
pub trait FromRawFd {
    /// Prend l'ownership de `fd`.
    ///
    /// # Safety
    ///
    /// Mêmes préconditions que [`OwnedFd::from_raw_fd`] : `fd` ouvert, valide,
    /// `!= -1`, ownership cédé.
    unsafe fn from_raw_fd(fd: RawFd) -> Self;
}

/// Consomme une ressource pour en extraire le [`RawFd`] brut possédé.
///
/// Miroir de `std::os::fd::IntoRawFd`.
pub trait IntoRawFd {
    /// Consomme `self` et restitue le FD brut **sans le fermer**.
    fn into_raw_fd(self) -> RawFd;
}

impl AsRawFd for OwnedFd {
    #[inline]
    fn as_raw_fd(&self) -> RawFd {
        self.raw()
    }
}

impl AsFd for OwnedFd {
    #[inline]
    fn as_fd(&self) -> BorrowedFd<'_> {
        // Aucun transfert d'ownership : l'emprunt est borné par `&self`, donc
        // ne peut survivre au `OwnedFd`.
        // SAFETY: `self.raw()` provient d'un `OwnedFd` valide (ouvert, != -1).
        unsafe { BorrowedFd::borrow_raw(self.raw()) }
    }
}

impl FromRawFd for OwnedFd {
    /// # Safety
    ///
    /// - `fd` doit être un descripteur ouvert et valide ;
    /// - `fd` doit être **différent de `-1`** (sentinelle kernel interdite) ;
    /// - l'appelant cède l'ownership : `fd` ne doit plus être fermé ailleurs,
    ///   sous peine de double-`close` (faille de sécurité classique).
    #[inline]
    unsafe fn from_raw_fd(fd: RawFd) -> Self {
        // Validité/ownership et `fd != -1` garantis par l'appelant (contrat
        // `unsafe`) ; on stocke le FD brut tel quel (motif binaire = FD réel).
        Self { fd }
    }
}

impl IntoRawFd for OwnedFd {
    #[inline]
    fn into_raw_fd(self) -> RawFd {
        let raw = self.raw();
        // Ne pas fermer : on transfère l'ownership du FD à l'appelant.
        core::mem::forget(self);
        raw
    }
}

impl AsRawFd for BorrowedFd<'_> {
    #[inline]
    fn as_raw_fd(&self) -> RawFd {
        self.raw()
    }
}

impl AsFd for BorrowedFd<'_> {
    #[inline]
    fn as_fd(&self) -> BorrowedFd<'_> {
        *self
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Interop `std::os::fd` — TRANSITOIRE
//
// Ponts `From` entre les types FD d'Air et ceux de la std, pour les crates
// couche 1+ qui doivent encore franchir la frontière std (`std::fs::File`,
// `std::net`, …). La conversion passe toujours par le [`RawFd`] brut (i32
// identique), jamais par `transmute` (les représentations internes diffèrent,
// cf. doc du module). Gardés derrière `#[cfg(any(feature = "std", test))]` : la
// crate est `#![no_std]`, ces impls sont la seule partie du module qui référence
// `std`. Activer la feature `std` (off par défaut) pour franchir la frontière.
// ─────────────────────────────────────────────────────────────────────────

#[cfg(any(feature = "std", test))]
impl From<OwnedFd> for std::os::fd::OwnedFd {
    #[inline]
    fn from(owned: OwnedFd) -> Self {
        // SAFETY: `into_raw_fd` cède un FD ouvert valide (!= -1) ; la std en
        // prend l'ownership exclusif.
        unsafe { std::os::fd::FromRawFd::from_raw_fd(owned.into_raw_fd()) }
    }
}

#[cfg(any(feature = "std", test))]
impl From<std::os::fd::OwnedFd> for OwnedFd {
    #[inline]
    fn from(owned: std::os::fd::OwnedFd) -> Self {
        use std::os::fd::IntoRawFd;
        // SAFETY: idem, sens inverse — la std cède un FD ouvert valide (!= -1).
        unsafe { Self::from_raw_fd(owned.into_raw_fd()) }
    }
}

#[cfg(any(feature = "std", test))]
impl<'fd> From<BorrowedFd<'fd>> for std::os::fd::BorrowedFd<'fd> {
    #[inline]
    fn from(borrowed: BorrowedFd<'fd>) -> Self {
        // SAFETY: même FD emprunté, même durée de vie `'fd` ; `!= -1` garanti
        // par l'invariant de `BorrowedFd`.
        unsafe { std::os::fd::BorrowedFd::borrow_raw(borrowed.raw()) }
    }
}

#[cfg(any(feature = "std", test))]
impl<'fd> From<std::os::fd::BorrowedFd<'fd>> for BorrowedFd<'fd> {
    #[inline]
    fn from(borrowed: std::os::fd::BorrowedFd<'fd>) -> Self {
        use std::os::fd::AsRawFd;
        // SAFETY: même FD emprunté, même durée de vie `'fd` ; `!= -1` garanti
        // par l'invariant du `BorrowedFd` std.
        unsafe { Self::borrow_raw(borrowed.as_raw_fd()) }
    }
}

#[cfg(test)]
mod tests;