air_sys_syscall/

net.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/.

//! Wrappers de la famille `net` — sockets synchrones.
//!
//! Cf. `docs/specs/layer-0/family-net.md`.
//!
//! Toutes les opérations de cette famille sont synchrones. Les variantes
//! io_uring seront ajoutées au Temps 2b (ADR-022), en réutilisant les
//! mêmes types.

#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
compile_error!("air-sys-syscall::net supporte uniquement x86_64 et aarch64 (ADR-014).");

use air_sys_types::fd::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd};
use alloc::ffi::CString;
use alloc::vec::Vec;
use core::ffi::CStr;
use core::num::NonZeroI32;

use air_sys_types::net::{
    AcceptFlags, AcceptResult, IoSlice, IoSliceMut, IpMembershipV4, IpMembershipV6, Ipv4SocketAddr,
    Ipv6SocketAddr, LingerOption, MessageFlags, ReceiveMessageRequest, ReceiveMessageResult,
    SendMessageRequest, SendMessageResult, ShutdownMode, SocketAddr, SocketDomain, SocketType,
    UnixCredentials, UnixSocketAddr,
};
use air_sys_types::process::Pid;
use air_sys_types::{Errno, OwnedFd as AirOwnedFd, Timeval};

// ─────────────────────────────────────────────────────────────────────────
// Helper commun : conversion d'une valeur de retour syscall négative en Errno.
// ─────────────────────────────────────────────────────────────────────────

fn errno_from_negative_syscall_ret(ret: i64) -> Errno {
    debug_assert!(ret < 0 && ret > -4096);
    #[allow(clippy::cast_possible_truncation)]
    let raw = ret.wrapping_neg() as i32;
    let nz = NonZeroI32::new(raw).expect("errno strictement positif par construction");
    Errno::from_nonzero(nz)
}

// ─────────────────────────────────────────────────────────────────────────
// Constantes socket
// ─────────────────────────────────────────────────────────────────────────

/// `SOCK_CLOEXEC` : ajouté systématiquement par les wrappers socket/socketpair/accept4.
const SOCK_CLOEXEC: i32 = 0x0008_0000;

/// `MSG_NOSIGNAL` : activé par défaut sur send/sendmsg.
const MSG_NOSIGNAL: i32 = 0x4000;

// ─────────────────────────────────────────────────────────────────────────
// Constantes sockopt
// ─────────────────────────────────────────────────────────────────────────

const SOL_SOCKET: i32 = 1;
const SO_KEEPALIVE: i32 = 9;
const SO_REUSEADDR: i32 = 2;
const SO_REUSEPORT: i32 = 15;
const SO_SNDBUF: i32 = 7;
const SO_RCVBUF: i32 = 8;
const SO_ERROR: i32 = 4;
const SO_LINGER: i32 = 13;
const SO_PEERCRED: i32 = 17;
const SO_BINDTODEVICE: i32 = 25;
// Options à `timeval` : sur LP64 (x86_64/aarch64, cibles Air), `SO_RCVTIMEO`/
// `SO_SNDTIMEO` valent les constantes « OLD » (le `time_t` y est déjà 64-bit),
// avec un `struct timeval` de 16 octets. Cf. `Timeval` (air-sys-types).
const SO_RCVTIMEO: i32 = 20;
const SO_SNDTIMEO: i32 = 21;

const IPPROTO_TCP: i32 = 6;
const TCP_NODELAY: i32 = 1;
const TCP_KEEPIDLE: i32 = 4;
const TCP_KEEPINTVL: i32 = 5;
const TCP_KEEPCNT: i32 = 6;

const IPPROTO_IP: i32 = 0;
const IP_TTL: i32 = 2;
const IP_ADD_MEMBERSHIP: i32 = 35;
const IP_DROP_MEMBERSHIP: i32 = 36;

const IPPROTO_IPV6: i32 = 41;
const IPV6_V6ONLY: i32 = 26;
// `IPV6_JOIN_GROUP` / `IPV6_LEAVE_GROUP` (alias `IPV6_ADD/DROP_MEMBERSHIP`).
const IPV6_ADD_MEMBERSHIP: i32 = 20;
const IPV6_DROP_MEMBERSHIP: i32 = 21;

/// Taille de `struct timeval` sur LP64 (deux `long` de 8 octets).
const TIMEVAL_LEN: u32 = 16;
/// Taille de `struct ip_mreq` (deux `struct in_addr`).
const IP_MREQ_LEN: u32 = 8;
/// Taille de `struct ipv6_mreq` (`in6_addr` + `int ifindex`).
const IPV6_MREQ_LEN: u32 = 20;

// Les tailles ABI ci-dessus sont **verrouillées** sur le layout `#[repr(C)]` des
// types couche 0 : un dérapage casserait la compilation (assertions const).
const _: () = assert!(core::mem::size_of::<Timeval>() == TIMEVAL_LEN as usize);
const _: () = assert!(core::mem::size_of::<IpMembershipV4>() == IP_MREQ_LEN as usize);
const _: () = assert!(core::mem::size_of::<IpMembershipV6>() == IPV6_MREQ_LEN as usize);

// ─────────────────────────────────────────────────────────────────────────
// Taille maximale de sockaddr (ss_maxsize POSIX)
// ─────────────────────────────────────────────────────────────────────────

pub(crate) const MAX_SOCKADDR_LEN: usize = 128;

/// Buffer de stockage sockaddr brut aligné sur u64.
#[repr(C, align(8))]
#[derive(Debug)]
pub(crate) struct RawSockaddrStorage {
    pub(crate) bytes: [u8; MAX_SOCKADDR_LEN],
}

/// Convertit un `SocketAddr` Air en représentation kernel brute.
/// Retourne `(buffer, longueur_effective)`.
pub(crate) fn socket_addr_to_raw(address: &SocketAddr) -> (RawSockaddrStorage, u32) {
    let mut storage = RawSockaddrStorage {
        bytes: [0u8; MAX_SOCKADDR_LEN],
    };
    match address {
        SocketAddr::Unix(unix) => {
            // sa_family = AF_UNIX = 1 (LE)
            storage.bytes[0..2].copy_from_slice(&1u16.to_ne_bytes());
            match unix {
                UnixSocketAddr::Path(path) => {
                    let bytes = path.as_bytes();
                    let length = bytes.len().min(107);
                    storage.bytes[2..2_usize.saturating_add(length)]
                        .copy_from_slice(&bytes[..length]);
                    storage.bytes[2_usize.saturating_add(length)] = 0; // NUL terminateur
                    // addrlen = sizeof(sa_family) + length + NUL
                    #[allow(clippy::cast_possible_truncation)]
                    let addrlen = (2_usize.saturating_add(length).saturating_add(1)) as u32;
                    (storage, addrlen)
                }
                UnixSocketAddr::Abstract(name) => {
                    // Premier octet = '\0' (marqueur abstrait), puis le nom
                    storage.bytes[2] = 0;
                    let length = name.len().min(107);
                    storage.bytes[3..3_usize.saturating_add(length)]
                        .copy_from_slice(&name[..length]);
                    // addrlen = sizeof(sa_family) + 1 (NUL) + length
                    #[allow(clippy::cast_possible_truncation)]
                    let addrlen = (2_usize.saturating_add(1).saturating_add(length)) as u32;
                    (storage, addrlen)
                }
                UnixSocketAddr::Unnamed => (storage, 2),
            }
        }
        SocketAddr::Ipv4(ipv4) => {
            // sa_family = AF_INET = 2
            storage.bytes[0..2].copy_from_slice(&2u16.to_ne_bytes());
            // port en big-endian
            let port_be = ipv4.port.to_be();
            storage.bytes[2..4].copy_from_slice(&port_be.to_ne_bytes());
            storage.bytes[4..8].copy_from_slice(&ipv4.address);
            // sin_zero reste à 0 (déjà initialisé)
            (storage, 16)
        }
        SocketAddr::Ipv6(ipv6) => {
            // sa_family = AF_INET6 = 10
            storage.bytes[0..2].copy_from_slice(&10u16.to_ne_bytes());
            let port_be = ipv6.port.to_be();
            storage.bytes[2..4].copy_from_slice(&port_be.to_ne_bytes());
            storage.bytes[4..8].copy_from_slice(&ipv6.flowinfo.to_ne_bytes());
            storage.bytes[8..24].copy_from_slice(&ipv6.address);
            storage.bytes[24..28].copy_from_slice(&ipv6.scope_id.to_ne_bytes());
            (storage, 28)
        }
    }
}

/// Convertit un buffer sockaddr brut en `SocketAddr` Air.
/// Retourne `None` si le buffer est trop court ou la famille inconnue.
pub(crate) fn raw_to_socket_addr(buffer: &[u8], length: u32) -> Option<SocketAddr> {
    if length < 2 {
        return None;
    }
    let len_usize = length as usize;
    if buffer.len() < len_usize {
        return None;
    }
    let family = u16::from_ne_bytes([buffer[0], buffer[1]]);
    match family {
        1 => {
            // AF_UNIX
            if length == 2 {
                return Some(SocketAddr::Unix(UnixSocketAddr::Unnamed));
            }
            if length < 3 {
                return None;
            }
            let path_bytes = buffer.get(2..len_usize)?;
            if path_bytes.first() == Some(&0) {
                // Abstract : le premier octet est '\0', suivi du nom
                let name = path_bytes.get(1..).unwrap_or(&[]).to_vec();
                Some(SocketAddr::Unix(UnixSocketAddr::Abstract(name)))
            } else {
                // Path : NUL-terminé
                let nul = path_bytes
                    .iter()
                    .position(|&b| b == 0)
                    .unwrap_or(path_bytes.len());
                let cstr = CString::new(&path_bytes[..nul]).ok()?;
                Some(SocketAddr::Unix(UnixSocketAddr::Path(cstr)))
            }
        }
        2 => {
            // AF_INET
            if length < 16 {
                return None;
            }
            let port = u16::from_be_bytes([buffer[2], buffer[3]]);
            let address = [buffer[4], buffer[5], buffer[6], buffer[7]];
            Some(SocketAddr::Ipv4(Ipv4SocketAddr { address, port }))
        }
        10 => {
            // AF_INET6
            if length < 28 {
                return None;
            }
            let port = u16::from_be_bytes([buffer[2], buffer[3]]);
            let flowinfo = u32::from_ne_bytes([buffer[4], buffer[5], buffer[6], buffer[7]]);
            let mut address = [0u8; 16];
            address.copy_from_slice(buffer.get(8..24)?);
            let scope_id = u32::from_ne_bytes([buffer[24], buffer[25], buffer[26], buffer[27]]);
            Some(SocketAddr::Ipv6(Ipv6SocketAddr {
                address,
                port,
                flowinfo,
                scope_id,
            }))
        }
        _ => None,
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Codec sockaddr PUBLIC pour la face libc (ADR-070, descellement additif couche 0
// — cadre ADR-051). Fines expositions des codecs internes ci-dessus : une seule
// autorité de layout sockaddr (kernel=bible), zéro duplication côté libc.
// ─────────────────────────────────────────────────────────────────────────

/// **Décode** un `sockaddr` kernel brut (octets + `socklen_t`) en [`SocketAddr`] typé.
/// Exposition publique de [`raw_to_socket_addr`] pour la face **libc** : `bytes` est le
/// buffer présenté par le C, `length` la longueur associée. Rend `None` si la famille
/// est inconnue ou la longueur insuffisante — aucune présomption sur les octets
/// (Principe 3), aucun `unsafe`.
#[must_use]
pub fn socket_addr_from_bytes(bytes: &[u8], length: u32) -> Option<SocketAddr> {
    raw_to_socket_addr(bytes, length)
}

/// **Encode** un [`SocketAddr`] typé en `sockaddr` kernel brut dans `out`, rendant la
/// **longueur effective** (`socklen_t`) écrite, ou `None` si `out` est trop court.
/// Exposition publique de [`socket_addr_to_raw`] pour la face libc **sans** fuiter le
/// type de stockage interne (copie bornée dans le buffer de l'appelant).
#[must_use]
pub fn socket_addr_to_bytes(address: &SocketAddr, out: &mut [u8]) -> Option<u32> {
    let (storage, length) = socket_addr_to_raw(address);
    let length_usize = usize::try_from(length).ok()?;
    let source = storage.bytes.get(..length_usize)?;
    let target = out.get_mut(..length_usize)?;
    target.copy_from_slice(source);
    Some(length)
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers cmsg (ancillaires SCM_RIGHTS)
// ─────────────────────────────────────────────────────────────────────────

/// Construit un buffer `cmsghdr` + données FDs pour `SCM_RIGHTS` (LP64).
///
/// Structure `cmsghdr` sur LP64 :
/// - cmsg_len  : u64 (8 octets) — taille incluant le header
/// - cmsg_level: i32 (4 octets) = SOL_SOCKET = 1
/// - cmsg_type : i32 (4 octets) = SCM_RIGHTS = 1
/// - données   : i32 * nfds
pub(crate) fn build_scm_rights_cmsg(fds: &[BorrowedFd<'_>]) -> Vec<u8> {
    if fds.is_empty() {
        return Vec::new();
    }
    let data_len = fds.len().saturating_mul(4); // chaque fd = i32
    let cmsg_len = 16_usize.saturating_add(data_len); // header 16 + data
    let total = cmsg_len.saturating_add(7) & !7_usize; // alignement 8
    let mut buffer = vec![0u8; total];
    // cmsg_len en u64 (LP64)
    #[allow(clippy::cast_possible_truncation)]
    buffer[0..8].copy_from_slice(&(cmsg_len as u64).to_ne_bytes());
    // cmsg_level = SOL_SOCKET = 1
    buffer[8..12].copy_from_slice(&1i32.to_ne_bytes());
    // cmsg_type = SCM_RIGHTS = 1
    buffer[12..16].copy_from_slice(&1i32.to_ne_bytes());
    // FDs
    for (i, fd) in fds.iter().enumerate() {
        let raw = fd.as_raw_fd();
        let offset = 16_usize.saturating_add(i.saturating_mul(4));
        buffer[offset..offset.saturating_add(4)].copy_from_slice(&raw.to_ne_bytes());
    }
    buffer
}

/// Parse un buffer cmsg et extrait les `OwnedFd` reçus via `SCM_RIGHTS`.
pub(crate) fn parse_scm_rights(cmsg_buf: &[u8], cmsg_len: usize) -> Vec<OwnedFd> {
    let mut fds = Vec::new();
    let mut offset = 0_usize;
    while offset.saturating_add(16) <= cmsg_len && offset.saturating_add(16) <= cmsg_buf.len() {
        let len_bytes: [u8; 8] = match cmsg_buf[offset..offset.saturating_add(8)].try_into() {
            Ok(b) => b,
            Err(_) => break,
        };
        // MAX_SOCKADDR_LEN = 128 < usize::MAX sur toutes les cibles supportées (LP64).
        // La troncature de u64 à usize est intentionnelle : les tailles cmsg sont
        // bornées à quelques centaines d'octets en pratique.
        #[allow(clippy::cast_possible_truncation)]
        let length = u64::from_ne_bytes(len_bytes) as usize;
        let level_bytes: [u8; 4] =
            match cmsg_buf[offset.saturating_add(8)..offset.saturating_add(12)].try_into() {
                Ok(b) => b,
                Err(_) => break,
            };
        let level = i32::from_ne_bytes(level_bytes);
        let ty_bytes: [u8; 4] =
            match cmsg_buf[offset.saturating_add(12)..offset.saturating_add(16)].try_into() {
                Ok(b) => b,
                Err(_) => break,
            };
        let ty = i32::from_ne_bytes(ty_bytes);

        // SOL_SOCKET=1, SCM_RIGHTS=1
        if level == 1 && ty == 1 && length >= 16 {
            let mut fd_off = offset.saturating_add(16);
            let end = offset.saturating_add(length);
            while fd_off.saturating_add(4) <= end && fd_off.saturating_add(4) <= cmsg_buf.len() {
                let raw_bytes: [u8; 4] = match cmsg_buf[fd_off..fd_off.saturating_add(4)].try_into()
                {
                    Ok(b) => b,
                    Err(_) => break,
                };
                let raw = i32::from_ne_bytes(raw_bytes);
                // SAFETY: Le kernel a retourné des FDs valides dans le cmsg SCM_RIGHTS.
                // Ces FDs nous appartiennent maintenant (le kernel en transfère l'ownership).
                fds.push(unsafe { OwnedFd::from_raw_fd(raw) });
                fd_off = fd_off.saturating_add(4);
            }
        }
        let aligned = length.saturating_add(7) & !7_usize;
        if aligned == 0 {
            break;
        }
        offset = offset.saturating_add(aligned);
    }
    fds
}

// ─────────────────────────────────────────────────────────────────────────
// Structure KernelMsghdr (LP64)
// ─────────────────────────────────────────────────────────────────────────

/// Représentation kernel de `struct msghdr` en mode LP64 (Linux x86_64/aarch64).
///
/// Les champs `size_t` font 8 octets ; on insère un padding explicite entre
/// `msg_namelen` (u32) et `msg_iov` (u64) pour respecter l'alignement LP64.
#[repr(C)]
struct KernelMsghdr {
    msg_name: u64,       // *mut void = u64 (NULL si pas d'adresse)
    msg_namelen: u32,    // longueur de l'adresse
    _pad: u32,           // alignement LP64
    msg_iov: u64,        // *mut iovec
    msg_iovlen: u64,     // size_t
    msg_control: u64,    // *mut void (cmsg)
    msg_controllen: u64, // size_t
    msg_flags: i32,      // drapeaux retournés
    _pad2: u32,
}

// ─────────────────────────────────────────────────────────────────────────
// Helper getsockopt/setsockopt bas-niveau
// ─────────────────────────────────────────────────────────────────────────

/// Lit une option socket en entier (`i32`).
fn getsockopt_i32(sock: BorrowedFd<'_>, level: i32, optname: i32) -> Result<i32, Errno> {
    let mut val: i32 = 0;
    let mut length: u32 = 4;
    let val_ptr: *mut i32 = &mut val;
    let len_ptr: *mut u32 = &mut length;
    // SAFETY:
    // - getsockopt(2) écrit `*length` octets (au maximum `*len_ptr`) dans `*val_ptr`.
    // - val et length sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_getsockopt(
            sock.as_raw_fd(),
            level,
            optname,
            val_ptr as u64,
            len_ptr as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(val)
}

/// Définit une option socket en entier (`i32`).
fn setsockopt_i32(sock: BorrowedFd<'_>, level: i32, optname: i32, val: i32) -> Result<(), Errno> {
    let val_ref: &i32 = &val;
    let val_ptr: *const i32 = val_ref;
    let length: u32 = 4;
    // SAFETY:
    // - setsockopt(2) lit `length` octets depuis `*val_ptr`.
    // - val est local, valide pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret =
        unsafe { raw_syscall_setsockopt(sock.as_raw_fd(), level, optname, val_ptr as u64, length) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// setsockopt/getsockopt PUBLICS à valeur entière pour la face libc (ADR-071,
// descellement additif couche 0 — cadre ADR-051). La quasi-totalité des options
// (SO_REUSEADDR/TCP_NODELAY/SO_KEEPALIVE/SO_ERROR/IP_TOS/…) sont des `int`.
// ─────────────────────────────────────────────────────────────────────────

/// **Définit** une option socket à valeur **entière** (`setsockopt` avec `optlen == 4`).
/// Exposition publique de [`setsockopt_i32`] pour la face libc : `level`/`optname` sont
/// les entiers bruts fournis par le C (validés par le kernel).
///
/// # Errors
/// L'`errno` de `setsockopt(2)` (`EBADF`/`ENOPROTOOPT`/`EINVAL`…), propagé.
pub fn set_socket_option_int(
    sock: BorrowedFd<'_>,
    level: i32,
    optname: i32,
    value: i32,
) -> Result<(), Errno> {
    setsockopt_i32(sock, level, optname, value)
}

/// **Lit** une option socket à valeur **entière** (`getsockopt`). Exposition publique
/// de [`getsockopt_i32`] pour la face libc.
///
/// # Errors
/// L'`errno` de `getsockopt(2)`, propagé.
pub fn get_socket_option_int(sock: BorrowedFd<'_>, level: i32, optname: i32) -> Result<i32, Errno> {
    getsockopt_i32(sock, level, optname)
}

// ─────────────────────────────────────────────────────────────────────────
// Setup des sockets
// ─────────────────────────────────────────────────────────────────────────

/// Crée un socket.
///
/// Wrappeur de `socket(2)`. `SOCK_CLOEXEC` est ajouté automatiquement
/// par le wrapper pour garantir que le FD ne fuit pas vers les processus
/// fils via `exec`.
///
/// # Parameters
///
/// - `domain` : famille de protocole ([`SocketDomain::Unix`] pour l'IPC
///   Air via Conduit).
/// - `ty` : type de socket ([`SocketType::Stream`] pour TCP/Unix stream).
/// - `protocol` : protocole (0 = défaut pour le type).
///
/// # Errors
///
/// - `EAFNOSUPPORT` : famille de protocole non supportée.
/// - `EPROTONOSUPPORT` : protocole non supporté pour ce type.
/// - `EMFILE` : quota de FD du processus atteint.
/// - `ENFILE` : quota de FD système atteint.
/// - `ENOMEM` : mémoire kernel insuffisante.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::socket;
/// use air_sys_types::net::{SocketDomain, SocketType};
///
/// let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket");
/// ```
pub fn socket(domain: SocketDomain, ty: SocketType, protocol: i32) -> Result<AirOwnedFd, Errno> {
    let domain_raw = domain as i32;
    let ty_raw = (ty as i32) | SOCK_CLOEXEC;
    // SAFETY:
    // - socket(2) ne touche à aucune mémoire utilisateur (args entiers).
    // - En cas de succès, retourne un FD valide >= 0 ; en cas d'erreur, ret < 0.
    // - SOCK_CLOEXEC est setté atomiquement par le kernel.
    let ret = unsafe { raw_syscall_socket(domain_raw, ty_raw, protocol) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation)]
    let raw_fd = ret as i32;
    // SAFETY: Le kernel a retourné un FD valide >= 0.
    Ok(unsafe { AirOwnedFd::from_raw_fd(raw_fd) })
}

/// Lie un socket à une adresse locale.
///
/// Wrappeur de `bind(2)`. Pour les sockets Unix path-based, supprimer
/// le chemin existant avec `unlinkat` (en ignorant `ENOENT`) avant
/// d'appeler `bind` est la convention recommandée.
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `address` : adresse locale à lier.
///
/// # Errors
///
/// - `EADDRINUSE` : adresse déjà utilisée.
/// - `EADDRNOTAVAIL` : adresse non disponible sur cet hôte.
/// - `EINVAL` : socket déjà lié ou adresse invalide.
/// - `EACCES` : permission refusée (ex. bind sur un port < 1024 sans
///   privilèges).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::{socket, bind};
/// use air_sys_types::net::{SocketAddr, SocketDomain, SocketType, UnixSocketAddr};
/// use air_sys_types::fd::AsFd;
///
/// let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket");
/// bind(fd.as_fd(), &SocketAddr::Unix(UnixSocketAddr::Path(
///     std::ffi::CString::new("/tmp/air.sock").expect("cstring"),
/// ))).expect("bind");
/// ```
pub fn bind(sock: BorrowedFd<'_>, address: &SocketAddr) -> Result<(), Errno> {
    let (raw, addrlen) = socket_addr_to_raw(address);
    let addr_ptr: *const u8 = raw.bytes.as_ptr();
    // SAFETY:
    // - bind(2) lit `addrlen` octets depuis `addr_ptr` (la sockaddr).
    // - `raw` est local, valide pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe { raw_syscall_bind(sock.as_raw_fd(), addr_ptr as u64, addrlen) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Met un socket en mode écoute.
///
/// Wrappeur de `listen(2)`.
///
/// # Parameters
///
/// - `sock` : FD du socket déjà lié avec [`bind`].
/// - `backlog` : taille de la file des connexions en attente d'`accept`.
///
/// # Errors
///
/// - `EADDRINUSE` : adresse déjà utilisée.
/// - `EOPNOTSUPP` : type de socket ne supporte pas `listen`.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::listen;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// listen(fd, 128).expect("listen");
/// # }
/// ```
pub fn listen(sock: BorrowedFd<'_>, backlog: u32) -> Result<(), Errno> {
    // backlog est passé comme i32 au kernel ; saturer à i32::MAX si trop grand.
    #[allow(clippy::cast_possible_truncation)]
    let backlog_i32 = if backlog > i32::MAX as u32 {
        i32::MAX
    } else {
        backlog as i32
    };
    // SAFETY:
    // - listen(2) ne touche à aucune mémoire utilisateur.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe { raw_syscall_listen(sock.as_raw_fd(), backlog_i32) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Opérations connectées synchrones
// ─────────────────────────────────────────────────────────────────────────

/// Initie une connexion vers un pair.
///
/// Wrappeur de `connect(2)`. Pour les sockets non-bloquants, retourne
/// immédiatement `EINPROGRESS` ; la connexion est terminée quand le
/// socket devient writable (via `poll`/`epoll`/io_uring).
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `address` : adresse du pair.
///
/// # Errors
///
/// - `ECONNREFUSED` : le pair refuse la connexion (Unix : socket absent).
/// - `EINPROGRESS` : connexion en cours (socket non-bloquant).
/// - `EALREADY` : connexion déjà en cours.
/// - `EISCONN` : socket déjà connecté.
/// - `ETIMEDOUT` : expiration du délai de connexion.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::{socket, connect};
/// use air_sys_types::net::{SocketAddr, SocketDomain, SocketType, UnixSocketAddr};
/// use air_sys_types::fd::AsFd;
///
/// let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket");
/// connect(fd.as_fd(), &SocketAddr::Unix(UnixSocketAddr::Path(
///     std::ffi::CString::new("/run/conduit.sock").expect("cstring"),
/// ))).expect("connect");
/// ```
pub fn connect(sock: BorrowedFd<'_>, address: &SocketAddr) -> Result<(), Errno> {
    let (raw, addrlen) = socket_addr_to_raw(address);
    let addr_ptr: *const u8 = raw.bytes.as_ptr();
    // SAFETY:
    // - connect(2) lit `addrlen` octets depuis `addr_ptr`.
    // - `raw` est local, valide pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe { raw_syscall_connect(sock.as_raw_fd(), addr_ptr as u64, addrlen) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Accepte une connexion entrante.
///
/// Wrappeur de `accept4(2)` (préféré à `accept` car CLOEXEC atomique).
/// Le wrapper active `AcceptFlags::CLOEXEC` par défaut.
///
/// # Parameters
///
/// - `listener` : FD du socket en écoute.
/// - `flags` : [`AcceptFlags`] (CLOEXEC implicite).
///
/// # Errors
///
/// - `EAGAIN` / `EWOULDBLOCK` : pas de connexion disponible (non-bloquant).
/// - `EINTR` : interrompu par un signal (ADR-021 convention 2).
/// - `ECONNABORTED` : connexion abandonnée avant l'accept.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::accept4;
/// use air_sys_types::net::AcceptFlags;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(listener: BorrowedFd<'_>) {
/// let result = accept4(listener, AcceptFlags::CLOEXEC).expect("accept4");
/// let _client_fd = result.fd;
/// # }
/// ```
pub fn accept4(listener: BorrowedFd<'_>, flags: AcceptFlags) -> Result<AcceptResult, Errno> {
    let mut addr_buf = RawSockaddrStorage {
        bytes: [0u8; MAX_SOCKADDR_LEN],
    };
    // MAX_SOCKADDR_LEN = 128, valeur connue < u32::MAX : la troncature n'est pas possible.
    #[allow(clippy::cast_possible_truncation)]
    let mut addrlen: u32 = MAX_SOCKADDR_LEN as u32;
    let addr_ptr: *mut u8 = addr_buf.bytes.as_mut_ptr();
    let addrlen_ptr: *mut u32 = &mut addrlen;
    // Forcer CLOEXEC même si l'appelant l'a oublié
    let effective_flags = (flags | AcceptFlags::CLOEXEC).bits();
    // SAFETY:
    // - accept4(2) écrit l'adresse du pair dans `addr_ptr` (au plus `addrlen` octets)
    //   et met à jour `*addrlen_ptr` avec la longueur réelle.
    // - addr_buf et addrlen sont locaux, valides pour la durée du syscall.
    // - En cas de succès, retourne un nouveau FD valide >= 0.
    // - listener est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_accept4(
            listener.as_raw_fd(),
            addr_ptr as u64,
            addrlen_ptr as u64,
            effective_flags,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation)]
    let raw_fd = ret as i32;
    // SAFETY: Le kernel a retourné un FD valide.
    let fd = unsafe { AirOwnedFd::from_raw_fd(raw_fd) };
    let address = raw_to_socket_addr(&addr_buf.bytes, addrlen);
    Ok(AcceptResult { fd, address })
}

/// Envoie des données sur un socket connecté.
///
/// Wrappeur de `send(2)`. `MessageFlags::NOSIGNAL` est activé automatiquement
/// pour éviter `SIGPIPE` sur les connexions fermées.
///
/// # Parameters
///
/// - `sock` : FD du socket connecté.
/// - `buffer` : données à envoyer.
/// - `flags` : drapeaux [`MessageFlags`].
///
/// # Errors
///
/// - `EAGAIN` : socket non-bloquant et buffer kernel plein.
/// - `EINTR` : interrompu par un signal.
/// - `EPIPE` / `ECONNRESET` : connexion fermée par le pair.
/// - `EMSGSIZE` : message trop grand pour ce type de socket.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::send;
/// use air_sys_types::net::MessageFlags;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let n = send(fd, b"hello", MessageFlags::empty()).expect("send");
/// # }
/// ```
pub fn send(sock: BorrowedFd<'_>, buffer: &[u8], flags: MessageFlags) -> Result<usize, Errno> {
    let buf_ptr: *const u8 = buffer.as_ptr();
    // MSG_NOSIGNAL ajouté automatiquement
    #[allow(clippy::cast_sign_loss)]
    let effective_flags = (flags.bits() | MSG_NOSIGNAL) as u64;
    // SAFETY:
    // - sendto(2) lit `buffer.len()` octets depuis `buf_ptr` (immutable borrow garanti).
    // - Les args address/addrlen sont NULL/0 pour un socket connecté.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_sendto(
            sock.as_raw_fd(),
            buf_ptr as u64,
            buffer.len(),
            effective_flags,
            0,
            0,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(ret as usize)
}

/// Reçoit des données d'un socket connecté.
///
/// Wrappeur de `recv(2)`. Retourne 0 si le pair a fermé la connexion
/// proprement (EOF).
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `buffer` : buffer de destination.
/// - `flags` : drapeaux [`MessageFlags`].
///
/// # Errors
///
/// - `EAGAIN` : pas de données disponibles (non-bloquant).
/// - `EINTR` : interrompu par un signal.
/// - `ECONNRESET` : connexion réinitialisée par le pair.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::recv;
/// use air_sys_types::net::MessageFlags;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let mut buffer = [0u8; 1024];
/// let n = recv(fd, &mut buffer, MessageFlags::empty()).expect("recv");
/// # }
/// ```
pub fn recv(sock: BorrowedFd<'_>, buffer: &mut [u8], flags: MessageFlags) -> Result<usize, Errno> {
    let buf_ptr: *mut u8 = buffer.as_mut_ptr();
    #[allow(clippy::cast_sign_loss)]
    let flags_u64 = flags.bits() as u64;
    // SAFETY:
    // - recvfrom(2) écrit au plus `buffer.len()` octets dans `buf_ptr`.
    // - buffer est local (mutable borrow exclusif), valide pour la durée du syscall.
    // - Les args address/addrlen sont NULL/0 : on n'a pas besoin de l'adresse source.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_recvfrom(
            sock.as_raw_fd(),
            buf_ptr as u64,
            buffer.len(),
            flags_u64,
            0,
            0,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(ret as usize)
}

/// Envoie un message avec données de contrôle (ancillaires).
///
/// Wrappeur de `sendmsg(2)`. Supporte l'envoi multi-buffer et le
/// passage de FDs via `SCM_RIGHTS`. `NOSIGNAL` est activé par défaut.
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `request` : description du message à envoyer.
///
/// # Errors
///
/// Voir [`send`]. De plus :
/// - `EINVAL` : nombre de FDs dans `request.fds` dépasse `SCM_MAX_FD`.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::sendmsg;
/// use air_sys_types::net::{IoSlice, MessageFlags, SendMessageRequest};
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let data = b"hello";
/// let iov = [IoSlice::new(data)];
/// let req = SendMessageRequest {
///     iov: &iov,
///     address: None,
///     fds: &[],
///     flags: MessageFlags::empty(),
/// };
/// sendmsg(fd, &req).expect("sendmsg");
/// # }
/// ```
pub fn sendmsg(
    sock: BorrowedFd<'_>,
    request: &SendMessageRequest<'_>,
) -> Result<SendMessageResult, Errno> {
    // Convertir l'adresse optionnelle
    let (addr_storage, addr_storage_len) = if let Some(address) = request.address {
        let (s, l) = socket_addr_to_raw(address);
        (Some(s), l)
    } else {
        (None, 0u32)
    };

    // Construire le buffer cmsg (SCM_RIGHTS) si des FDs sont présents
    let cmsg_buf = build_scm_rights_cmsg(request.fds);

    let iov_ptr: *const IoSlice<'_> = request.iov.as_ptr();

    let (name_ptr, name_len) = if let Some(ref s) = addr_storage {
        (s.bytes.as_ptr() as u64, addr_storage_len)
    } else {
        (0u64, 0u32)
    };

    let (ctrl_ptr, ctrl_len) = if cmsg_buf.is_empty() {
        (0u64, 0u64)
    } else {
        (cmsg_buf.as_ptr() as u64, cmsg_buf.len() as u64)
    };

    let mut msghdr = KernelMsghdr {
        msg_name: name_ptr,
        msg_namelen: name_len,
        _pad: 0,
        msg_iov: iov_ptr as u64,
        msg_iovlen: request.iov.len() as u64,
        msg_control: ctrl_ptr,
        msg_controllen: ctrl_len,
        msg_flags: 0,
        _pad2: 0,
    };

    #[allow(clippy::cast_sign_loss)]
    let effective_flags = (request.flags.bits() | MSG_NOSIGNAL) as u64;
    let hdr_ptr: *mut KernelMsghdr = &mut msghdr;

    // SAFETY:
    // - sendmsg(2) lit la structure msghdr pointée par hdr_ptr et les buffers iov.
    // - Tous les pointeurs (iov, cmsg, address) sont valides pour la durée du syscall,
    //   garantis par les lifetimes de SendMessageRequest.
    // - IoSlice est #[repr(C)] compatible avec struct iovec.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe { raw_syscall_sendmsg(sock.as_raw_fd(), hdr_ptr as u64, effective_flags) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(SendMessageResult {
        bytes_sent: ret as usize,
    })
}

/// Reçoit un message avec données de contrôle (ancillaires).
///
/// Wrappeur de `recvmsg(2)`. Les FDs reçus via `SCM_RIGHTS` sont
/// automatiquement encapsulés dans des [`OwnedFd`] avec `CLOEXEC`
/// si [`MessageFlags::CMSG_CLOEXEC`] est dans `request.flags`.
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `request` : buffers de destination et flags.
///
/// # Errors
///
/// Voir [`recv`].
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::recvmsg;
/// use air_sys_types::net::{IoSliceMut, MessageFlags, ReceiveMessageRequest};
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let mut buffer = [0u8; 1024];
/// let mut iov = [IoSliceMut::new(&mut buffer)];
/// let mut req = ReceiveMessageRequest {
///     iov: &mut iov,
///     flags: MessageFlags::CMSG_CLOEXEC,
/// };
/// let result = recvmsg(fd, &mut req).expect("recvmsg");
/// // result.fds contient les OwnedFd reçus via SCM_RIGHTS
/// # }
/// ```
pub fn recvmsg(
    sock: BorrowedFd<'_>,
    request: &mut ReceiveMessageRequest<'_>,
) -> Result<ReceiveMessageResult, Errno> {
    // Buffer cmsg de 1 KiO pour recevoir les données de contrôle (FDs, creds…)
    let mut cmsg_buf = [0u8; 1024];
    let mut addr_buf = RawSockaddrStorage {
        bytes: [0u8; MAX_SOCKADDR_LEN],
    };
    // MAX_SOCKADDR_LEN = 128, valeur connue < u32::MAX : la troncature n'est pas possible.
    #[allow(clippy::cast_possible_truncation)]
    let mut addrlen: u32 = MAX_SOCKADDR_LEN as u32;

    let iov_ptr: *mut IoSliceMut<'_> = request.iov.as_mut_ptr();
    let addr_ptr: *mut u8 = addr_buf.bytes.as_mut_ptr();
    let addrlen_ptr: *mut u32 = &mut addrlen;
    let cmsg_ptr: *mut u8 = cmsg_buf.as_mut_ptr();

    let mut msghdr = KernelMsghdr {
        msg_name: addr_ptr as u64,
        msg_namelen: addrlen,
        _pad: 0,
        msg_iov: iov_ptr as u64,
        msg_iovlen: request.iov.len() as u64,
        msg_control: cmsg_ptr as u64,
        msg_controllen: cmsg_buf.len() as u64,
        msg_flags: 0,
        _pad2: 0,
    };

    #[allow(clippy::cast_sign_loss)]
    let flags_u64 = request.flags.bits() as u64;
    let hdr_ptr: *mut KernelMsghdr = &mut msghdr;

    // SAFETY:
    // - recvmsg(2) écrit dans les buffers iov et cmsg, et met à jour msghdr.
    // - Tous les buffers (iov, cmsg, address) sont locaux valides pour la durée du syscall.
    // - IoSliceMut est #[repr(C)] compatible avec struct iovec.
    // - Le kernel met à jour msg_namelen avec la longueur réelle de l'adresse.
    // - sock est garanti ouvert par BorrowedFd.
    // Note : on passe également addrlen_ptr mais en réalité le kernel met à jour
    // msg_namelen dans la structure msghdr ; on le récupère après l'appel.
    let ret = unsafe { raw_syscall_recvmsg(sock.as_raw_fd(), hdr_ptr as u64, flags_u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    // Lire msg_namelen mis à jour par le kernel
    let returned_addrlen = msghdr.msg_namelen;
    // Lire msg_controllen mis à jour par le kernel
    #[allow(clippy::cast_possible_truncation)]
    let returned_cmsg_len = msghdr.msg_controllen as usize;
    // Lire msg_flags mis à jour par le kernel
    let returned_flags_bits = msghdr.msg_flags;

    let _ = addrlen_ptr; // addr_len mis à jour via msghdr.msg_namelen

    let address = raw_to_socket_addr(&addr_buf.bytes, returned_addrlen);
    let fds = parse_scm_rights(&cmsg_buf, returned_cmsg_len);

    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    let bytes_received = ret as usize;

    let flags = MessageFlags::from_bits_truncate(returned_flags_bits);

    Ok(ReceiveMessageResult {
        bytes_received,
        address,
        fds,
        flags,
    })
}

/// Ferme partiellement ou totalement un socket connecté.
///
/// Wrappeur de `shutdown(2)`. Différent de `close` : `shutdown` termine
/// la connexion de façon propre sans fermer le FD.
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `mode` : direction(s) à fermer.
///
/// # Errors
///
/// - `ENOTCONN` : socket non connecté.
/// - `ENOTSOCK` : FD n'est pas un socket.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::shutdown;
/// use air_sys_types::net::ShutdownMode;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// shutdown(fd, ShutdownMode::Write).expect("shutdown");
/// # }
/// ```
pub fn shutdown(sock: BorrowedFd<'_>, mode: ShutdownMode) -> Result<(), Errno> {
    let how = mode as i32;
    // SAFETY:
    // - shutdown(2) ne touche à aucune mémoire utilisateur.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe { raw_syscall_shutdown(sock.as_raw_fd(), how) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Opérations utilitaires
// ─────────────────────────────────────────────────────────────────────────

/// Retourne l'adresse locale du socket.
///
/// # Errors
///
/// - `ENOTSOCK` : FD n'est pas un socket.
/// - `ENOBUFS` : mémoire système insuffisante.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::getsockname;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let address = getsockname(fd).expect("getsockname");
/// # }
/// ```
pub fn getsockname(sock: BorrowedFd<'_>) -> Result<SocketAddr, Errno> {
    let mut addr_buf = RawSockaddrStorage {
        bytes: [0u8; MAX_SOCKADDR_LEN],
    };
    // MAX_SOCKADDR_LEN = 128, valeur connue < u32::MAX : la troncature n'est pas possible.
    #[allow(clippy::cast_possible_truncation)]
    let mut addrlen: u32 = MAX_SOCKADDR_LEN as u32;
    let addr_ptr: *mut u8 = addr_buf.bytes.as_mut_ptr();
    let addrlen_ptr: *mut u32 = &mut addrlen;
    // SAFETY:
    // - getsockname(2) écrit l'adresse locale dans addr_ptr (au plus *addrlen_ptr octets)
    //   et met à jour *addrlen_ptr avec la longueur réelle.
    // - addr_buf et addrlen sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret =
        unsafe { raw_syscall_getsockname(sock.as_raw_fd(), addr_ptr as u64, addrlen_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    raw_to_socket_addr(&addr_buf.bytes, addrlen).ok_or_else(|| {
        // Famille inconnue ou buffer trop court : errno EAFNOSUPPORT
        #[allow(clippy::unwrap_used)]
        Errno::from_nonzero(NonZeroI32::new(97).unwrap()) // EAFNOSUPPORT = 97
    })
}

/// Retourne l'adresse du pair connecté.
///
/// # Errors
///
/// - `ENOTCONN` : socket non connecté.
/// - `ENOTSOCK` : FD n'est pas un socket.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::getpeername;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let address = getpeername(fd).expect("getpeername");
/// # }
/// ```
pub fn getpeername(sock: BorrowedFd<'_>) -> Result<SocketAddr, Errno> {
    let mut addr_buf = RawSockaddrStorage {
        bytes: [0u8; MAX_SOCKADDR_LEN],
    };
    // MAX_SOCKADDR_LEN = 128, valeur connue < u32::MAX : la troncature n'est pas possible.
    #[allow(clippy::cast_possible_truncation)]
    let mut addrlen: u32 = MAX_SOCKADDR_LEN as u32;
    let addr_ptr: *mut u8 = addr_buf.bytes.as_mut_ptr();
    let addrlen_ptr: *mut u32 = &mut addrlen;
    // SAFETY:
    // - getpeername(2) écrit l'adresse du pair dans addr_ptr et met à jour *addrlen_ptr.
    // - addr_buf et addrlen sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret =
        unsafe { raw_syscall_getpeername(sock.as_raw_fd(), addr_ptr as u64, addrlen_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // COUVERTURE (ADR-035, STRUCTURAL — cf. docs/COVERAGE-EXCEPTIONS.md, section
    // `net`). La closure `None` (`EAFNOSUPPORT`) est inatteignable par
    // construction : `getpeername(2)` réussit sur un socket créé via l'API safe,
    // dont le domaine ∈ {Unix(1), Ipv4(2), Ipv6(10)} (`SocketDomain`) — les trois
    // familles que `raw_to_socket_addr` décode toujours en `Some`. Les gardes de
    // troncature internes (`len < 16`/`< 28`) sont testées séparément.
    raw_to_socket_addr(&addr_buf.bytes, addrlen).ok_or_else(|| {
        #[allow(clippy::unwrap_used)]
        Errno::from_nonzero(NonZeroI32::new(97).unwrap()) // EAFNOSUPPORT
    })
}

/// Crée une paire de sockets connectés.
///
/// Wrappeur de `socketpair(2)`. Équivalent à créer un pipe mais
/// pour les sockets Unix. Les deux FDs retournés sont symétriques.
///
/// Seuls les sockets Unix (`AF_UNIX`) supportent `socketpair` sur Linux.
/// `SOCK_CLOEXEC` est ajouté automatiquement.
///
/// # Parameters
///
/// - `domain` : doit être [`SocketDomain::Unix`] sur Linux.
/// - `ty` : type de socket.
/// - `protocol` : 0 = défaut.
///
/// # Errors
///
/// - `EAFNOSUPPORT` : domaine non supporté (non-Unix).
/// - `EMFILE`/`ENFILE` : quotas FD atteints.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::socketpair;
/// use air_sys_types::net::{SocketDomain, SocketType};
///
/// let (fd_a, fd_b) = socketpair(SocketDomain::Unix, SocketType::Stream, 0)
///     .expect("socketpair");
/// ```
pub fn socketpair(
    domain: SocketDomain,
    ty: SocketType,
    protocol: i32,
) -> Result<(AirOwnedFd, AirOwnedFd), Errno> {
    let mut sv = [0i32; 2];
    let sv_ptr: *mut i32 = sv.as_mut_ptr();
    let domain_raw = domain as i32;
    let ty_raw = (ty as i32) | SOCK_CLOEXEC;
    // SAFETY:
    // - socketpair(2) écrit deux FDs dans sv[0..2].
    // - sv est local, valide pour la durée du syscall.
    // - En cas de succès, sv[0] et sv[1] sont des FDs valides >= 0.
    let ret = unsafe { raw_syscall_socketpair(domain_raw, ty_raw, protocol, sv_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // SAFETY: Le kernel a retourné deux FDs valides dans sv.
    let fd_a = unsafe { AirOwnedFd::from_raw_fd(sv[0]) };
    let fd_b = unsafe { AirOwnedFd::from_raw_fd(sv[1]) };
    Ok((fd_a, fd_b))
}

// ─────────────────────────────────────────────────────────────────────────
// Options de socket (typées par option — ADR-021 convention 3)
// ─────────────────────────────────────────────────────────────────────────

/// Lit l'option `SO_KEEPALIVE`.
pub fn get_so_keepalive(sock: BorrowedFd<'_>) -> Result<bool, Errno> {
    getsockopt_i32(sock, SOL_SOCKET, SO_KEEPALIVE).map(|v| v != 0)
}

/// Définit l'option `SO_KEEPALIVE`.
pub fn set_so_keepalive(sock: BorrowedFd<'_>, enable: bool) -> Result<(), Errno> {
    setsockopt_i32(sock, SOL_SOCKET, SO_KEEPALIVE, i32::from(enable))
}

/// Lit l'option `SO_REUSEADDR`.
pub fn get_so_reuseaddr(sock: BorrowedFd<'_>) -> Result<bool, Errno> {
    getsockopt_i32(sock, SOL_SOCKET, SO_REUSEADDR).map(|v| v != 0)
}

/// Définit l'option `SO_REUSEADDR`.
pub fn set_so_reuseaddr(sock: BorrowedFd<'_>, enable: bool) -> Result<(), Errno> {
    setsockopt_i32(sock, SOL_SOCKET, SO_REUSEADDR, i32::from(enable))
}

/// Lit l'option `SO_REUSEPORT`.
pub fn get_so_reuseport(sock: BorrowedFd<'_>) -> Result<bool, Errno> {
    getsockopt_i32(sock, SOL_SOCKET, SO_REUSEPORT).map(|v| v != 0)
}

/// Définit l'option `SO_REUSEPORT`.
pub fn set_so_reuseport(sock: BorrowedFd<'_>, enable: bool) -> Result<(), Errno> {
    setsockopt_i32(sock, SOL_SOCKET, SO_REUSEPORT, i32::from(enable))
}

/// Lit l'option `TCP_NODELAY` (désactivation de l'algorithme Nagle).
pub fn get_tcp_nodelay(sock: BorrowedFd<'_>) -> Result<bool, Errno> {
    getsockopt_i32(sock, IPPROTO_TCP, TCP_NODELAY).map(|v| v != 0)
}

/// Définit l'option `TCP_NODELAY`.
pub fn set_tcp_nodelay(sock: BorrowedFd<'_>, enable: bool) -> Result<(), Errno> {
    setsockopt_i32(sock, IPPROTO_TCP, TCP_NODELAY, i32::from(enable))
}

/// Lit la taille du buffer de réception (`SO_RCVBUF`).
pub fn get_so_rcvbuf(sock: BorrowedFd<'_>) -> Result<u32, Errno> {
    getsockopt_i32(sock, SOL_SOCKET, SO_RCVBUF).map(|v| {
        // Le kernel peut retourner une valeur positive ; on la traite comme u32.
        #[allow(clippy::cast_sign_loss)]
        let u = v as u32;
        u
    })
}

/// Définit la taille du buffer de réception.
pub fn set_so_rcvbuf(sock: BorrowedFd<'_>, size: u32) -> Result<(), Errno> {
    // Le kernel interprète la valeur comme i32 ; saturer à i32::MAX si trop grand.
    #[allow(clippy::cast_possible_truncation)]
    let val = if size > i32::MAX as u32 {
        i32::MAX
    } else {
        size as i32
    };
    setsockopt_i32(sock, SOL_SOCKET, SO_RCVBUF, val)
}

/// Lit la taille du buffer d'envoi (`SO_SNDBUF`).
pub fn get_so_sndbuf(sock: BorrowedFd<'_>) -> Result<u32, Errno> {
    getsockopt_i32(sock, SOL_SOCKET, SO_SNDBUF).map(|v| {
        #[allow(clippy::cast_sign_loss)]
        let u = v as u32;
        u
    })
}

/// Définit la taille du buffer d'envoi.
pub fn set_so_sndbuf(sock: BorrowedFd<'_>, size: u32) -> Result<(), Errno> {
    #[allow(clippy::cast_possible_truncation)]
    let val = if size > i32::MAX as u32 {
        i32::MAX
    } else {
        size as i32
    };
    setsockopt_i32(sock, SOL_SOCKET, SO_SNDBUF, val)
}

/// Lit l'erreur socket en attente (`SO_ERROR`) et l'efface.
///
/// Retourne `None` si aucune erreur n'est en attente.
pub fn get_so_error(sock: BorrowedFd<'_>) -> Result<Option<Errno>, Errno> {
    let val = getsockopt_i32(sock, SOL_SOCKET, SO_ERROR)?;
    if val == 0 {
        Ok(None)
    } else {
        let nz = NonZeroI32::new(val).ok_or_else(|| {
            // Ne se produit pas : val != 0 ici
            #[allow(clippy::unwrap_used)]
            Errno::from_nonzero(NonZeroI32::new(22).unwrap()) // EINVAL
        })?;
        Ok(Some(Errno::from_nonzero(nz)))
    }
}

/// Lit les credentials du pair Unix (`SO_PEERCRED`).
///
/// Uniquement sur les sockets Unix (domain `AF_UNIX`).
pub fn get_so_peercred(sock: BorrowedFd<'_>) -> Result<UnixCredentials, Errno> {
    // struct ucred { pid_t pid; uid_t uid; gid_t gid; } = 3 * i32 = 12 octets
    let mut cred = [0i32; 3];
    let mut length: u32 = 12;
    let cred_ptr: *mut i32 = cred.as_mut_ptr();
    let len_ptr: *mut u32 = &mut length;
    // SAFETY:
    // - getsockopt(2) écrit la structure ucred (12 octets) dans cred.
    // - cred et length sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_getsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            SO_PEERCRED,
            cred_ptr as u64,
            len_ptr as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // cred[0] = pid (i32), cred[1] = uid (u32), cred[2] = gid (u32)
    let pid_raw = cred[0];
    #[allow(clippy::cast_sign_loss)]
    let uid = cred[1] as u32;
    #[allow(clippy::cast_sign_loss)]
    let gid = cred[2] as u32;
    let nz = NonZeroI32::new(pid_raw).ok_or_else(|| {
        #[allow(clippy::unwrap_used)]
        Errno::from_nonzero(NonZeroI32::new(22).unwrap()) // EINVAL : pid=0 inattendu
    })?;
    Ok(UnixCredentials {
        pid: Pid::from_nonzero(nz),
        uid,
        gid,
    })
}

/// Lit l'option `SO_LINGER`.
pub fn get_so_linger(sock: BorrowedFd<'_>) -> Result<LingerOption, Errno> {
    // struct linger { int l_onoff; int l_linger; } = 8 octets
    let mut linger = [0i32; 2];
    let mut length: u32 = 8;
    let linger_ptr: *mut i32 = linger.as_mut_ptr();
    let len_ptr: *mut u32 = &mut length;
    // SAFETY:
    // - getsockopt(2) écrit la structure linger (8 octets) dans linger.
    // - linger et length sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_getsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            SO_LINGER,
            linger_ptr as u64,
            len_ptr as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    if linger[0] == 0 {
        Ok(LingerOption::Disabled)
    } else {
        #[allow(clippy::cast_sign_loss)]
        let secs = linger[1] as u64;
        Ok(LingerOption::Enabled(core::time::Duration::from_secs(secs)))
    }
}

/// Définit l'option `SO_LINGER`.
pub fn set_so_linger(sock: BorrowedFd<'_>, linger: LingerOption) -> Result<(), Errno> {
    let (l_onoff, l_linger): (i32, i32) = match linger {
        LingerOption::Disabled => (0, 0),
        LingerOption::Enabled(d) => {
            // Saturer à i32::MAX secondes (≈ 68 ans)
            let secs = d.as_secs();
            #[allow(clippy::cast_possible_truncation)]
            let secs_i32 = if secs > i32::MAX as u64 {
                i32::MAX
            } else {
                secs as i32
            };
            (1, secs_i32)
        }
    };
    let buffer = [l_onoff, l_linger];
    let buf_ptr: *const i32 = buffer.as_ptr();
    let length: u32 = 8;
    // SAFETY:
    // - setsockopt(2) lit 8 octets depuis buf_ptr (struct linger).
    // - buffer est local, valide pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_setsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            SO_LINGER,
            buf_ptr as u64,
            length,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lie le socket à une interface réseau (`SO_BINDTODEVICE`).
pub fn set_so_bindtodevice(sock: BorrowedFd<'_>, ifname: &CStr) -> Result<(), Errno> {
    let bytes = ifname.to_bytes_with_nul();
    let ptr: *const u8 = bytes.as_ptr();
    #[allow(clippy::cast_possible_truncation)]
    let length = bytes.len() as u32;
    // SAFETY:
    // - setsockopt(2) lit `length` octets depuis `ptr` (le nom d'interface NUL-terminé).
    // - Le CStr garantit la validité du pointeur et la présence du NUL terminateur.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_setsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            SO_BINDTODEVICE,
            ptr as u64,
            length,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit l'interface liée au socket.
pub fn get_so_bindtodevice(sock: BorrowedFd<'_>) -> Result<CString, Errno> {
    // IFNAMSIZ = 16 octets suffisent pour un nom d'interface Linux
    let mut buffer = [0u8; 16];
    let mut length: u32 = 16;
    let buf_ptr: *mut u8 = buffer.as_mut_ptr();
    let len_ptr: *mut u32 = &mut length;
    // SAFETY:
    // - getsockopt(2) écrit le nom de l'interface (NUL-terminé) dans buffer.
    // - buffer et length sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_getsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            SO_BINDTODEVICE,
            buf_ptr as u64,
            len_ptr as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // Trouver le NUL terminateur pour construire le CString
    let nul_pos = buffer
        .iter()
        .position(|&b| b == 0)
        .unwrap_or(length as usize);
    // COUVERTURE (ADR-035, STRUCTURAL — cf. docs/COVERAGE-EXCEPTIONS.md, section
    // `net`). La closure `map_err` (`EINVAL`) est inatteignable par construction :
    // `nul_pos` est la position du **premier** `NUL` (ou `length` à défaut), donc
    // `buffer[..nul_pos]` ne contient aucun `NUL` interne → `CString::new`
    // retourne toujours `Ok`.
    CString::new(&buffer[..nul_pos]).map_err(|_| {
        #[allow(clippy::unwrap_used)]
        Errno::from_nonzero(NonZeroI32::new(22).unwrap()) // EINVAL
    })
}

/// Définit le délai `TCP_KEEPIDLE` (secondes d'inactivité avant premier keepalive).
pub fn set_tcp_keepidle(sock: BorrowedFd<'_>, seconds: u32) -> Result<(), Errno> {
    #[allow(clippy::cast_possible_truncation)]
    let val = if seconds > i32::MAX as u32 {
        i32::MAX
    } else {
        seconds as i32
    };
    setsockopt_i32(sock, IPPROTO_TCP, TCP_KEEPIDLE, val)
}

/// Définit le délai `TCP_KEEPINTVL` (secondes entre deux keepalives).
pub fn set_tcp_keepintvl(sock: BorrowedFd<'_>, seconds: u32) -> Result<(), Errno> {
    #[allow(clippy::cast_possible_truncation)]
    let val = if seconds > i32::MAX as u32 {
        i32::MAX
    } else {
        seconds as i32
    };
    setsockopt_i32(sock, IPPROTO_TCP, TCP_KEEPINTVL, val)
}

/// Définit le nombre max de keepalives sans réponse (`TCP_KEEPCNT`).
pub fn set_tcp_keepcnt(sock: BorrowedFd<'_>, count: u32) -> Result<(), Errno> {
    #[allow(clippy::cast_possible_truncation)]
    let val = if count > i32::MAX as u32 {
        i32::MAX
    } else {
        count as i32
    };
    setsockopt_i32(sock, IPPROTO_TCP, TCP_KEEPCNT, val)
}

/// Définit le TTL IP (`IP_TTL`).
pub fn set_ip_ttl(sock: BorrowedFd<'_>, ttl: u8) -> Result<(), Errno> {
    setsockopt_i32(sock, IPPROTO_IP, IP_TTL, i32::from(ttl))
}

/// Restreint les sockets IPv6 aux connexions IPv6-only (`IPV6_V6ONLY`).
pub fn set_ipv6_v6only(sock: BorrowedFd<'_>, v6only: bool) -> Result<(), Errno> {
    setsockopt_i32(sock, IPPROTO_IPV6, IPV6_V6ONLY, i32::from(v6only))
}

// ─────────────────────────────────────────────────────────────────────────
// Options à structure `timeval` — délais de réception / d'envoi
// (`SO_RCVTIMEO` / `SO_SNDTIMEO`). Options **structurées** (16 octets) : la
// couche 0 pose/lit un `Timeval` typé (jamais un `setsockopt` générique).
// ─────────────────────────────────────────────────────────────────────────

/// Décode un `timeval` **rendu par `getsockopt`** en délai optionnel.
///
/// Fonction **pure** (aucun syscall) : le kernel écrit une structure `timeval`
/// que NOUS relisons ensuite. Un `timeval` nul (`{0, 0}`) signifie « aucun délai
/// armé » (le socket bloque indéfiniment) → `None` ; toute autre valeur →
/// `Some(timeval)`. Isolé pour être **property-testé** (cf. exigence fuzz du
/// décodage `getsockopt`).
fn decode_timeout(tv: Timeval) -> Option<Timeval> {
    if tv.tv_sec == 0 && tv.tv_usec == 0 {
        None
    } else {
        Some(tv)
    }
}

/// Pose un délai (`SO_RCVTIMEO` / `SO_SNDTIMEO`) via un `timeval` de 16 octets.
///
/// `None` ⇒ `timeval` nul = « pas de délai » (sémantique kernel : blocage sans
/// limite). Helper **interne** paramétré par `optname` (les points d'entrée
/// publics restent dédiés, ADR-021 conv. 3).
fn set_socket_timeout(
    sock: BorrowedFd<'_>,
    optname: i32,
    timeout: Option<Timeval>,
) -> Result<(), Errno> {
    let tv = timeout.unwrap_or(Timeval {
        tv_sec: 0,
        tv_usec: 0,
    });
    let tv_ptr: *const Timeval = &tv;
    // SAFETY:
    // - setsockopt(2) lit `TIMEVAL_LEN` (16) octets depuis tv_ptr (struct timeval).
    // - tv est local, valide pour la durée du syscall ; layout #[repr(C)] fidèle
    //   (assertion const `size_of::<Timeval>() == 16`).
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_setsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            optname,
            tv_ptr as u64,
            TIMEVAL_LEN,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit un délai (`SO_RCVTIMEO` / `SO_SNDTIMEO`). Helper **interne** paramétré par
/// `optname`.
fn get_socket_timeout(sock: BorrowedFd<'_>, optname: i32) -> Result<Option<Timeval>, Errno> {
    let mut tv = Timeval {
        tv_sec: 0,
        tv_usec: 0,
    };
    let mut length: u32 = TIMEVAL_LEN;
    let tv_ptr: *mut Timeval = &mut tv;
    let len_ptr: *mut u32 = &mut length;
    // SAFETY:
    // - getsockopt(2) écrit au plus `length` (16) octets dans tv (struct timeval).
    // - tv et length sont locaux, valides pour la durée du syscall ; layout
    //   #[repr(C)] fidèle (assertion const `size_of::<Timeval>() == 16`).
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_getsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            optname,
            tv_ptr as u64,
            len_ptr as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(decode_timeout(tv))
}

/// Définit le délai de **réception** (`SO_RCVTIMEO`). `None` désarme le délai.
pub fn set_receive_timeout(sock: BorrowedFd<'_>, timeout: Option<Timeval>) -> Result<(), Errno> {
    set_socket_timeout(sock, SO_RCVTIMEO, timeout)
}

/// Lit le délai de **réception** (`SO_RCVTIMEO`). `None` = aucun délai armé.
pub fn receive_timeout(sock: BorrowedFd<'_>) -> Result<Option<Timeval>, Errno> {
    get_socket_timeout(sock, SO_RCVTIMEO)
}

/// Définit le délai d'**envoi** (`SO_SNDTIMEO`). `None` désarme le délai.
pub fn set_send_timeout(sock: BorrowedFd<'_>, timeout: Option<Timeval>) -> Result<(), Errno> {
    set_socket_timeout(sock, SO_SNDTIMEO, timeout)
}

/// Lit le délai d'**envoi** (`SO_SNDTIMEO`). `None` = aucun délai armé.
pub fn send_timeout(sock: BorrowedFd<'_>) -> Result<Option<Timeval>, Errno> {
    get_socket_timeout(sock, SO_SNDTIMEO)
}

// ─────────────────────────────────────────────────────────────────────────
// Appartenance à un groupe multicast — options **structurées**
// `ip_mreq` (v4) / `ipv6_mreq` (v6). Fonctions dédiées typées (ADR-021).
// ─────────────────────────────────────────────────────────────────────────

/// Pose une option d'appartenance multicast **IPv4** (`ip_mreq`, 8 octets).
/// Helper **interne** paramétré par `optname` (`IP_ADD`/`IP_DROP_MEMBERSHIP`).
fn set_ip_membership_v4(
    sock: BorrowedFd<'_>,
    optname: i32,
    membership: &IpMembershipV4,
) -> Result<(), Errno> {
    let ptr: *const IpMembershipV4 = membership;
    // SAFETY:
    // - setsockopt(2) lit `IP_MREQ_LEN` (8) octets depuis ptr (struct ip_mreq).
    // - `membership` est valide pour la durée de l'appel (référence empruntée) ;
    //   layout #[repr(C)] fidèle (assertion const `size_of == 8`).
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_setsockopt(
            sock.as_raw_fd(),
            IPPROTO_IP,
            optname,
            ptr as u64,
            IP_MREQ_LEN,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Pose une option d'appartenance multicast **IPv6** (`ipv6_mreq`, 20 octets).
/// Helper **interne** paramétré par `optname` (`IPV6_ADD`/`IPV6_DROP_MEMBERSHIP`).
fn set_ip_membership_v6(
    sock: BorrowedFd<'_>,
    optname: i32,
    membership: &IpMembershipV6,
) -> Result<(), Errno> {
    let ptr: *const IpMembershipV6 = membership;
    // SAFETY:
    // - setsockopt(2) lit `IPV6_MREQ_LEN` (20) octets depuis ptr (struct ipv6_mreq).
    // - `membership` est valide pour la durée de l'appel (référence empruntée) ;
    //   layout #[repr(C)] fidèle (assertion const `size_of == 20`).
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_setsockopt(
            sock.as_raw_fd(),
            IPPROTO_IPV6,
            optname,
            ptr as u64,
            IPV6_MREQ_LEN,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// **Rejoint** un groupe multicast IPv4 (`IP_ADD_MEMBERSHIP`, `struct ip_mreq`).
pub fn join_multicast_v4(sock: BorrowedFd<'_>, membership: &IpMembershipV4) -> Result<(), Errno> {
    set_ip_membership_v4(sock, IP_ADD_MEMBERSHIP, membership)
}

/// **Quitte** un groupe multicast IPv4 (`IP_DROP_MEMBERSHIP`, `struct ip_mreq`).
pub fn leave_multicast_v4(sock: BorrowedFd<'_>, membership: &IpMembershipV4) -> Result<(), Errno> {
    set_ip_membership_v4(sock, IP_DROP_MEMBERSHIP, membership)
}

/// **Rejoint** un groupe multicast IPv6 (`IPV6_ADD_MEMBERSHIP`, `struct ipv6_mreq`).
pub fn join_multicast_v6(sock: BorrowedFd<'_>, membership: &IpMembershipV6) -> Result<(), Errno> {
    set_ip_membership_v6(sock, IPV6_ADD_MEMBERSHIP, membership)
}

/// **Quitte** un groupe multicast IPv6 (`IPV6_DROP_MEMBERSHIP`, `struct ipv6_mreq`).
pub fn leave_multicast_v6(sock: BorrowedFd<'_>, membership: &IpMembershipV6) -> Result<(), Errno> {
    set_ip_membership_v6(sock, IPV6_DROP_MEMBERSHIP, membership)
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — x86_64
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_socket(domain: i32, ty: i32, protocol: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_socket (x86_64 = 41). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 41_i64,
            in("rdi") i64::from(domain),
            in("rsi") i64::from(ty),
            in("rdx") i64::from(protocol),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_bind(fd: i32, address: u64, addrlen: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_bind (x86_64 = 49). Le kernel lit `addrlen` octets depuis `address`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 49_i64,
            in("rdi") i64::from(fd),
            in("rsi") address,
            in("rdx") i64::from(addrlen),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_listen(fd: i32, backlog: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_listen (x86_64 = 50). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 50_i64,
            in("rdi") i64::from(fd),
            in("rsi") i64::from(backlog),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_connect(fd: i32, address: u64, addrlen: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_connect (x86_64 = 42). Le kernel lit `addrlen` octets depuis `address`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 42_i64,
            in("rdi") i64::from(fd),
            in("rsi") address,
            in("rdx") i64::from(addrlen),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_accept4(fd: i32, address: u64, addrlen: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_accept4 (x86_64 = 288). Le kernel écrit l'adresse du pair dans address.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 288_i64,
            in("rdi") i64::from(fd),
            in("rsi") address,
            in("rdx") addrlen,
            in("r10") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_sendto(
    fd: i32,
    buffer: u64,
    length: usize,
    flags: u64,
    address: u64,
    addrlen: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sendto (x86_64 = 44). Le kernel lit `length` octets depuis `buffer`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 44_i64,
            in("rdi") i64::from(fd),
            in("rsi") buffer,
            in("rdx") length,
            in("r10") flags,
            in("r8") address,
            in("r9") i64::from(addrlen),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_recvfrom(
    fd: i32,
    buffer: u64,
    length: usize,
    flags: u64,
    address: u64,
    addrlen: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_recvfrom (x86_64 = 45). Le kernel écrit au plus `length` octets dans `buffer`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 45_i64,
            in("rdi") i64::from(fd),
            in("rsi") buffer,
            in("rdx") length,
            in("r10") flags,
            in("r8") address,
            in("r9") addrlen,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_sendmsg(fd: i32, msghdr: u64, flags: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sendmsg (x86_64 = 46). Le kernel lit la msghdr et les buffers associés.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 46_i64,
            in("rdi") i64::from(fd),
            in("rsi") msghdr,
            in("rdx") flags,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_recvmsg(fd: i32, msghdr: u64, flags: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_recvmsg (x86_64 = 47). Le kernel écrit dans les buffers iov et cmsg.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 47_i64,
            in("rdi") i64::from(fd),
            in("rsi") msghdr,
            in("rdx") flags,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_shutdown(fd: i32, how: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_shutdown (x86_64 = 48). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 48_i64,
            in("rdi") i64::from(fd),
            in("rsi") i64::from(how),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getsockname(fd: i32, address: u64, addrlen: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getsockname (x86_64 = 51). Le kernel écrit l'adresse et met à jour addrlen.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 51_i64,
            in("rdi") i64::from(fd),
            in("rsi") address,
            in("rdx") addrlen,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getpeername(fd: i32, address: u64, addrlen: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getpeername (x86_64 = 52). Le kernel écrit l'adresse et met à jour addrlen.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 52_i64,
            in("rdi") i64::from(fd),
            in("rsi") address,
            in("rdx") addrlen,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_socketpair(domain: i32, ty: i32, protocol: i32, sv: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_socketpair (x86_64 = 53). Le kernel écrit deux FDs dans sv[0..2].
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 53_i64,
            in("rdi") i64::from(domain),
            in("rsi") i64::from(ty),
            in("rdx") i64::from(protocol),
            in("r10") sv,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getsockopt(
    fd: i32,
    level: i32,
    optname: i32,
    optval: u64,
    optlen: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getsockopt (x86_64 = 55). Le kernel écrit *optlen octets dans optval.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 55_i64,
            in("rdi") i64::from(fd),
            in("rsi") i64::from(level),
            in("rdx") i64::from(optname),
            in("r10") optval,
            in("r8") optlen,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_setsockopt(
    fd: i32,
    level: i32,
    optname: i32,
    optval: u64,
    optlen: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setsockopt (x86_64 = 54). Le kernel lit optlen octets depuis optval.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 54_i64,
            in("rdi") i64::from(fd),
            in("rsi") i64::from(level),
            in("rdx") i64::from(optname),
            in("r10") optval,
            in("r8") i64::from(optlen),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — aarch64
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_socket(domain: i32, ty: i32, protocol: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_socket (aarch64 = 198). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 198_i64,
            inout("x0") i64::from(domain) => ret,
            in("x1") i64::from(ty),
            in("x2") i64::from(protocol),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_bind(fd: i32, address: u64, addrlen: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_bind (aarch64 = 200). Le kernel lit `addrlen` octets depuis `address`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 200_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") address,
            in("x2") i64::from(addrlen),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_listen(fd: i32, backlog: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_listen (aarch64 = 201). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 201_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") i64::from(backlog),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_connect(fd: i32, address: u64, addrlen: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_connect (aarch64 = 203). Le kernel lit `addrlen` octets depuis `address`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 203_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") address,
            in("x2") i64::from(addrlen),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_accept4(fd: i32, address: u64, addrlen: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_accept4 (aarch64 = 242). Le kernel écrit l'adresse du pair dans address.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 242_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") address,
            in("x2") addrlen,
            in("x3") i64::from(flags),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_sendto(
    fd: i32,
    buffer: u64,
    length: usize,
    flags: u64,
    address: u64,
    addrlen: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sendto (aarch64 = 206). Le kernel lit `length` octets depuis `buffer`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 206_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") buffer,
            in("x2") length,
            in("x3") flags,
            in("x4") address,
            in("x5") i64::from(addrlen),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_recvfrom(
    fd: i32,
    buffer: u64,
    length: usize,
    flags: u64,
    address: u64,
    addrlen: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_recvfrom (aarch64 = 207). Le kernel écrit au plus `length` octets dans `buffer`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 207_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") buffer,
            in("x2") length,
            in("x3") flags,
            in("x4") address,
            in("x5") addrlen,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_sendmsg(fd: i32, msghdr: u64, flags: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sendmsg (aarch64 = 211). Le kernel lit la msghdr et les buffers associés.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 211_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") msghdr,
            in("x2") flags,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_recvmsg(fd: i32, msghdr: u64, flags: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_recvmsg (aarch64 = 212). Le kernel écrit dans les buffers iov et cmsg.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 212_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") msghdr,
            in("x2") flags,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_shutdown(fd: i32, how: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_shutdown (aarch64 = 210). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 210_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") i64::from(how),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getsockname(fd: i32, address: u64, addrlen: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getsockname (aarch64 = 204). Le kernel écrit l'adresse et met à jour addrlen.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 204_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") address,
            in("x2") addrlen,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getpeername(fd: i32, address: u64, addrlen: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getpeername (aarch64 = 205). Le kernel écrit l'adresse et met à jour addrlen.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 205_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") address,
            in("x2") addrlen,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_socketpair(domain: i32, ty: i32, protocol: i32, sv: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_socketpair (aarch64 = 199). Le kernel écrit deux FDs dans sv[0..2].
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 199_i64,
            inout("x0") i64::from(domain) => ret,
            in("x1") i64::from(ty),
            in("x2") i64::from(protocol),
            in("x3") sv,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getsockopt(
    fd: i32,
    level: i32,
    optname: i32,
    optval: u64,
    optlen: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getsockopt (aarch64 = 209). Le kernel écrit *optlen octets dans optval.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 209_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") i64::from(level),
            in("x2") i64::from(optname),
            in("x3") optval,
            in("x4") optlen,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_setsockopt(
    fd: i32,
    level: i32,
    optname: i32,
    optval: u64,
    optlen: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setsockopt (aarch64 = 208). Le kernel lit optlen octets depuis optval.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 208_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") i64::from(level),
            in("x2") i64::from(optname),
            in("x3") optval,
            in("x4") i64::from(optlen),
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Tests
// ─────────────────────────────────────────────────────────────────────────

#[cfg(all(test, target_os = "linux"))]
mod tests {
    use super::*;
    use air_sys_types::fd::AsFd;

    // errno standard non exposés par l'API publique (gelée). Valeurs
    // asm-generic/errno.h, identiques sur x86_64 et aarch64.
    const EADDRINUSE: Errno = Errno::try_from_raw(98).unwrap();
    const ECONNREFUSED: Errno = Errno::try_from_raw(111).unwrap();
    const ENOTCONN: Errno = Errno::try_from_raw(107).unwrap();
    const ESOCKTNOSUPPORT: Errno = Errno::try_from_raw(94).unwrap();

    /// Un `BorrowedFd` jamais valide, pour provoquer `EBADF` de façon
    /// déterministe. `i32::MAX` dépasse toute limite de fd ouvrable : le
    /// kernel rejette systématiquement, sans course de réutilisation
    /// (contrairement à un fd réel fermé). `-1` est exclu car c'est la
    /// valeur-niche de `BorrowedFd` (`borrow_raw(-1)` panique `fd != -1`).
    fn invalid_fd() -> BorrowedFd<'static> {
        // SAFETY: aucune ressource n'est lue/écrite via ce fd ; il n'est
        // transmis au kernel que pour être rejeté avec `EBADF`.
        unsafe { BorrowedFd::borrow_raw(i32::MAX) }
    }

    /// `socket` crée un FD valide.
    #[test]
    fn socket_creates_valid_fd() {
        let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket Unix stream");
        // On vérifie que le FD est valide en récupérant une vue empruntée.
        let _borrowed = fd.as_fd();
    }

    /// `socketpair` crée deux FDs distincts et symétriques.
    #[test]
    fn socketpair_creates_two_valid_fds() {
        let (fd_a, fd_b) =
            socketpair(SocketDomain::Unix, SocketType::Stream, 0).expect("socketpair");
        let raw_a = fd_a.as_raw_fd();
        let raw_b = fd_b.as_raw_fd();
        assert_ne!(raw_a, raw_b, "les deux FDs doivent être distincts");
    }

    /// `send` + `recv` via socketpair : roundtrip simple.
    #[test]
    fn socketpair_send_recv_roundtrip() {
        let (fd_a, fd_b) =
            socketpair(SocketDomain::Unix, SocketType::Stream, 0).expect("socketpair");

        let data = b"bonjour";
        let n = send(fd_a.as_fd(), data, MessageFlags::empty()).expect("send");
        assert_eq!(n, data.len(), "send doit envoyer tous les octets");

        let mut buffer = [0u8; 16];
        let m = recv(fd_b.as_fd(), &mut buffer, MessageFlags::empty()).expect("recv");
        assert_eq!(
            m,
            data.len(),
            "recv doit recevoir autant d'octets qu'envoyés"
        );
        assert_eq!(
            &buffer[..m],
            data,
            "les données reçues doivent être identiques"
        );
    }

    /// `sendmsg` + `recvmsg` : roundtrip vectoriel.
    #[test]
    fn socketpair_sendmsg_recvmsg_roundtrip() {
        let (fd_a, fd_b) =
            socketpair(SocketDomain::Unix, SocketType::Stream, 0).expect("socketpair");

        let data1 = b"hello";
        let data2 = b" world";
        let iov_send = [IoSlice::new(data1), IoSlice::new(data2)];
        let req_send = SendMessageRequest {
            iov: &iov_send,
            address: None,
            fds: &[],
            flags: MessageFlags::empty(),
        };
        let result = sendmsg(fd_a.as_fd(), &req_send).expect("sendmsg");
        assert_eq!(
            result.bytes_sent,
            data1.len() + data2.len(),
            "sendmsg doit envoyer 11 octets"
        );

        let mut buffer = [0u8; 32];
        let mut iov_recv = [IoSliceMut::new(&mut buffer)];
        let mut req_recv = ReceiveMessageRequest {
            iov: &mut iov_recv,
            flags: MessageFlags::empty(),
        };
        let result_recv = recvmsg(fd_b.as_fd(), &mut req_recv).expect("recvmsg");
        assert_eq!(
            result_recv.bytes_received,
            data1.len() + data2.len(),
            "recvmsg doit recevoir 11 octets"
        );
        assert_eq!(&buffer[..result_recv.bytes_received], b"hello world");
    }

    /// `bind` + `listen` + `connect` + `accept4` sur socket Unix path-based.
    #[test]
    fn unix_bind_listen_connect_accept4() {
        // Utiliser un chemin temporaire unique
        let path = format!("/tmp/air-net-test-{}.sock", std::process::id());
        let cpath = CString::new(path.as_str()).expect("CString");

        // Supprimer un éventuel fichier résiduel
        let _ = std::fs::remove_file(&path);

        let server = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket serveur");
        bind(
            server.as_fd(),
            &SocketAddr::Unix(UnixSocketAddr::Path(cpath.clone())),
        )
        .expect("bind");
        listen(server.as_fd(), 4).expect("listen");

        let client = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket client");
        connect(
            client.as_fd(),
            &SocketAddr::Unix(UnixSocketAddr::Path(cpath.clone())),
        )
        .expect("connect");

        let accepted = accept4(server.as_fd(), AcceptFlags::CLOEXEC).expect("accept4");
        // Le FD accepté doit être valide
        let _borrowed = accepted.fd.as_fd();

        // Nettoyage
        let _ = std::fs::remove_file(&path);
    }

    /// `getsockname` sur socket Unix lié retourne l'adresse correcte.
    #[test]
    fn getsockname_unix_path() {
        let path = format!("/tmp/air-net-gsn-{}.sock", std::process::id());
        let cpath = CString::new(path.as_str()).expect("CString");
        let _ = std::fs::remove_file(&path);

        let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket");
        bind(
            fd.as_fd(),
            &SocketAddr::Unix(UnixSocketAddr::Path(cpath.clone())),
        )
        .expect("bind");

        let address = getsockname(fd.as_fd()).expect("getsockname");
        match address {
            SocketAddr::Unix(UnixSocketAddr::Path(returned)) => {
                assert_eq!(returned, cpath, "getsockname doit retourner le chemin lié");
            }
            other => panic!("adresse inattendue : {other:?}"),
        }

        let _ = std::fs::remove_file(&path);
    }

    /// `getpeername` sur une paire de sockets connectés.
    #[test]
    fn getpeername_unix_abstract() {
        // Un socket abstract permet de tester getpeername sans fichier temporaire.
        let path = format!("/tmp/air-net-gpn-{}.sock", std::process::id());
        let cpath = CString::new(path.as_str()).expect("CString");
        let _ = std::fs::remove_file(&path);

        let server = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket serveur");
        bind(
            server.as_fd(),
            &SocketAddr::Unix(UnixSocketAddr::Path(cpath.clone())),
        )
        .expect("bind");
        listen(server.as_fd(), 4).expect("listen");

        let client = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket client");
        connect(
            client.as_fd(),
            &SocketAddr::Unix(UnixSocketAddr::Path(cpath.clone())),
        )
        .expect("connect");

        let accepted = accept4(server.as_fd(), AcceptFlags::CLOEXEC).expect("accept4");

        // getpeername sur le FD accepté doit retourner l'adresse du serveur
        let peer = getpeername(client.as_fd()).expect("getpeername");
        match peer {
            SocketAddr::Unix(_) => { /* OK */ }
            other => panic!("adresse inattendue : {other:?}"),
        }

        drop(accepted);
        let _ = std::fs::remove_file(&path);
    }

    /// `shutdown` ne retourne pas d'erreur sur un socket connecté.
    #[test]
    fn shutdown_on_connected_socket() {
        let (fd_a, _fd_b) =
            socketpair(SocketDomain::Unix, SocketType::Stream, 0).expect("socketpair");
        shutdown(fd_a.as_fd(), ShutdownMode::Write).expect("shutdown write");
    }

    /// `set_so_reuseaddr` / `get_so_reuseaddr` : roundtrip.
    #[test]
    fn sockopt_reuseaddr_roundtrip() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket IPv4");
        set_so_reuseaddr(fd.as_fd(), true).expect("set_so_reuseaddr(true)");
        let val = get_so_reuseaddr(fd.as_fd()).expect("get_so_reuseaddr");
        assert!(val, "SO_REUSEADDR doit être activé");

        set_so_reuseaddr(fd.as_fd(), false).expect("set_so_reuseaddr(false)");
        let val2 = get_so_reuseaddr(fd.as_fd()).expect("get_so_reuseaddr");
        assert!(!val2, "SO_REUSEADDR doit être désactivé");
    }

    /// `set_so_keepalive` / `get_so_keepalive` : roundtrip.
    #[test]
    fn sockopt_keepalive_roundtrip() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket IPv4");
        set_so_keepalive(fd.as_fd(), true).expect("set_so_keepalive");
        let val = get_so_keepalive(fd.as_fd()).expect("get_so_keepalive");
        assert!(val, "SO_KEEPALIVE doit être activé");
    }

    /// `get_so_error` retourne `None` sur un socket sain.
    #[test]
    fn get_so_error_none_on_healthy_socket() {
        let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket");
        let err = get_so_error(fd.as_fd()).expect("get_so_error");
        assert!(err.is_none(), "SO_ERROR doit être None sur un socket sain");
    }

    /// Erreur socket **asynchrone réelle** : un `connect` non bloquant vers un
    /// port loopback **fermé** (réservé puis libéré, donc sans listener) dépose
    /// `ECONNREFUSED` dans `SO_ERROR` → `get_so_error` rend `Some(...)` (couvre le
    /// bras `val != 0`, jadis exempté faute d'outillage `poll`). Déterministe :
    /// boucle **bornée** sur la disponibilité de l'erreur (RST loopback quasi
    /// immédiat), sans `sleep`.
    #[test]
    #[cfg_attr(miri, ignore = "sockets non supportés par Miri")]
    fn get_so_error_some_on_refused_nonblocking_connect() {
        use air_sys_types::net::Ipv4SocketAddr;

        // Réserve un port loopback puis le **ferme** → port garanti sans listener.
        let probe = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket probe");
        bind(
            probe.as_fd(),
            &SocketAddr::Ipv4(Ipv4SocketAddr {
                address: [127, 0, 0, 1],
                port: 0,
            }),
        )
        .expect("bind probe");
        let port = match getsockname(probe.as_fd()).expect("getsockname") {
            SocketAddr::Ipv4(v4) => v4.port,
            other => panic!("adresse IPv4 attendue : {other:?}"),
        };
        drop(probe); // libère/ferme le port

        let sock = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket");
        // Bascule en non-bloquant (fcntl F_SETFL + O_NONBLOCK = 0x800).
        // SAFETY: `fcntl(F_SETFL, O_NONBLOCK)` sur un fd valide ; aucune mémoire
        // utilisateur lue/écrite.
        let ret = unsafe { raw_fcntl_setfl(sock.as_raw_fd(), 4, 0x800) };
        assert!(ret >= 0, "fcntl F_SETFL O_NONBLOCK");
        let target = SocketAddr::Ipv4(Ipv4SocketAddr {
            address: [127, 0, 0, 1],
            port,
        });
        // `connect` non bloquant : `EINPROGRESS` (ou `ECONNREFUSED` synchrone) —
        // dans les deux cas l'erreur se matérialise dans `SO_ERROR`.
        let _ = connect(sock.as_fd(), &target);

        // ── CIBLE : `get_so_error` rend `Some(erreur)` (bras `val != 0`). ──
        let mut observed = None;
        for _ in 0..2_000_000 {
            if let Some(error) = get_so_error(sock.as_fd()).expect("get_so_error") {
                observed = Some(error);
                break;
            }
        }
        let error = observed.expect("SO_ERROR doit devenir disponible (connexion refusée)");
        assert_eq!(
            error, ECONNREFUSED,
            "port fermé → ECONNREFUSED via SO_ERROR"
        );
        // Idempotence : `SO_ERROR` est effacé après lecture → `None` ensuite.
        assert!(
            get_so_error(sock.as_fd())
                .expect("get_so_error 2")
                .is_none(),
            "SO_ERROR effacé après lecture"
        );
    }

    /// `set_so_linger` / `get_so_linger` : roundtrip Disabled.
    #[test]
    fn sockopt_linger_disabled_roundtrip() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket IPv4");
        set_so_linger(fd.as_fd(), LingerOption::Disabled).expect("set_so_linger(Disabled)");
        let val = get_so_linger(fd.as_fd()).expect("get_so_linger");
        assert_eq!(val, LingerOption::Disabled);
    }

    /// `set_so_linger` / `get_so_linger` : roundtrip Enabled.
    #[test]
    fn sockopt_linger_enabled_roundtrip() {
        use core::time::Duration;
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket IPv4");
        let linger = LingerOption::Enabled(Duration::from_secs(5));
        set_so_linger(fd.as_fd(), linger).expect("set_so_linger(Enabled(5s))");
        let val = get_so_linger(fd.as_fd()).expect("get_so_linger");
        assert_eq!(val, LingerOption::Enabled(Duration::from_secs(5)));
    }

    /// `get_so_peercred` sur une `socketpair` Unix : le pair est le processus
    /// courant, donc les credentials retournés sont nos propres PID/UID/GID.
    /// (Ce n'était PAS une vraie « non-testabilité » : socketpair suffit.)
    #[test]
    fn sockopt_peercred_on_socketpair_is_self() {
        let (a, _b) = socketpair(SocketDomain::Unix, SocketType::Stream, 0).expect("socketpair");
        let creds = get_so_peercred(a.as_fd()).expect("get_so_peercred");
        // Le pair (l'autre extrémité) appartient au même processus.
        assert_eq!(creds.pid.as_raw(), crate::process::getpid().as_raw());
    }

    /// `get_so_peercred` sur un socket Unix **non connecté** : le kernel renvoie
    /// `SO_PEERCRED` avec `pid == 0` (aucun pair établi). `NonZeroI32::new(0)`
    /// vaut alors `None` → la closure d'erreur `EINVAL` (`net.rs` l.1251) est
    /// prise. Couvre ce bras défensif par un chemin déterministe et sans
    /// privilège (création de socket Unix seule, aucune connexion).
    #[test]
    fn sockopt_peercred_einval_on_unconnected_unix_socket() {
        let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket Unix");
        assert_eq!(
            get_so_peercred(fd.as_fd()).unwrap_err(),
            Errno::EINVAL,
            "un socket Unix non connecté rapporte pid=0 → EINVAL"
        );
    }

    /// `set_ip_ttl` sur un socket IPv4 réel (UDP) : aucune privilège requis.
    #[test]
    fn sockopt_ip_ttl_set_on_ipv4_socket() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Datagram, 0).expect("socket IPv4 UDP");
        set_ip_ttl(fd.as_fd(), 64).expect("set_ip_ttl(64)");
    }

    /// `set_ipv6_v6only` sur un socket IPv6 réel : aucune privilège requis.
    /// Skippe proprement si IPv6 est désactivé sur l'hôte (`EAFNOSUPPORT`).
    #[test]
    fn sockopt_ipv6_v6only_set_on_ipv6_socket() {
        // IPv6 indisponible sur l'hôte (`Err`) : pas un bug du wrapper → skip.
        if let Ok(fd) = socket(SocketDomain::Ipv6, SocketType::Stream, 0) {
            set_ipv6_v6only(fd.as_fd(), true).expect("set_ipv6_v6only(true)");
        }
    }

    // ── Délais SO_RCVTIMEO / SO_SNDTIMEO (options `timeval` — couche-0-v1.13) ──

    /// `set_receive_timeout(Some)` puis `receive_timeout()` : roundtrip exact
    /// (couvre le bras `Some` de `decode_timeout` et le `unwrap_or` côté `Some`).
    #[test]
    fn sockopt_receive_timeout_some_roundtrip() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket IPv4");
        let tv = Timeval {
            tv_sec: 0,
            tv_usec: 200_000,
        };
        set_receive_timeout(fd.as_fd(), Some(tv)).expect("set_receive_timeout(Some)");
        assert_eq!(
            receive_timeout(fd.as_fd()).expect("receive_timeout"),
            Some(tv)
        );
    }

    /// `set_receive_timeout(None)` désarme le délai → `receive_timeout()` rend
    /// `None` (couvre le bras `None` de `decode_timeout` et le `unwrap_or` défaut).
    #[test]
    fn sockopt_receive_timeout_none_clears() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket IPv4");
        set_receive_timeout(
            fd.as_fd(),
            Some(Timeval {
                tv_sec: 1,
                tv_usec: 0,
            }),
        )
        .expect("armer d'abord");
        set_receive_timeout(fd.as_fd(), None).expect("set_receive_timeout(None)");
        assert_eq!(receive_timeout(fd.as_fd()).expect("receive_timeout"), None);
    }

    /// `set_send_timeout` / `send_timeout` : roundtrip (exerce l'`optname`
    /// `SO_SNDTIMEO` du helper partagé).
    #[test]
    fn sockopt_send_timeout_roundtrip() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket IPv4");
        let tv = Timeval {
            tv_sec: 2,
            tv_usec: 500_000,
        };
        set_send_timeout(fd.as_fd(), Some(tv)).expect("set_send_timeout");
        assert_eq!(send_timeout(fd.as_fd()).expect("send_timeout"), Some(tv));
    }

    /// Bras d'erreur `if ret < 0` des délais via fd invalide → `EBADF`.
    #[test]
    fn sockopt_timeout_ebadf_on_invalid_fd() {
        let tv = Timeval {
            tv_sec: 0,
            tv_usec: 1,
        };
        assert_eq!(
            set_receive_timeout(invalid_fd(), Some(tv)).unwrap_err(),
            Errno::EBADF
        );
        assert_eq!(receive_timeout(invalid_fd()).unwrap_err(), Errno::EBADF);
        assert_eq!(
            set_send_timeout(invalid_fd(), Some(tv)).unwrap_err(),
            Errno::EBADF
        );
        assert_eq!(send_timeout(invalid_fd()).unwrap_err(), Errno::EBADF);
    }

    // ── Appartenance multicast v4/v6 (options `ip_mreq`/`ipv6_mreq`) ──
    //
    // Tests **déterministes sur loopback** (aucune dépendance réseau externe) :
    // rejoindre `224.0.0.1` via l'interface `127.0.0.1`, et `ff02::1` via l'index
    // de `lo` (toujours `1` sur Linux), réussissent sans privilège — vérifié.

    /// `join_multicast_v4` puis `leave_multicast_v4` sur loopback : succès
    /// (couvre le bras `Ok` de `set_ip_membership_v4` pour ADD **et** DROP).
    #[test]
    fn sockopt_multicast_v4_join_leave_on_loopback() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Datagram, 0).expect("socket IPv4 UDP");
        let membership = IpMembershipV4 {
            multiaddr: [224, 0, 0, 1],
            interface: [127, 0, 0, 1],
        };
        join_multicast_v4(fd.as_fd(), &membership).expect("join_multicast_v4(224.0.0.1@lo)");
        leave_multicast_v4(fd.as_fd(), &membership).expect("leave_multicast_v4");
    }

    /// `join_multicast_v6` puis `leave_multicast_v6` sur loopback (`ff02::1`,
    /// ifindex 1) : succès (couvre `set_ip_membership_v6` ADD **et** DROP).
    #[test]
    fn sockopt_multicast_v6_join_leave_on_loopback() {
        let fd = socket(SocketDomain::Ipv6, SocketType::Datagram, 0).expect("socket IPv6 UDP");
        let membership = IpMembershipV6 {
            multiaddr: [0xff, 0x02, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
            interface: 1, // `lo` — index invariant sur Linux
        };
        join_multicast_v6(fd.as_fd(), &membership).expect("join_multicast_v6(ff02::1@lo)");
        leave_multicast_v6(fd.as_fd(), &membership).expect("leave_multicast_v6");
    }

    /// Bras d'erreur `if ret < 0` du multicast via fd invalide → `EBADF`.
    #[test]
    fn sockopt_multicast_ebadf_on_invalid_fd() {
        let v4 = IpMembershipV4 {
            multiaddr: [224, 0, 0, 1],
            interface: [0, 0, 0, 0],
        };
        let v6 = IpMembershipV6 {
            multiaddr: [0xff, 0x02, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
            interface: 0,
        };
        assert_eq!(
            join_multicast_v4(invalid_fd(), &v4).unwrap_err(),
            Errno::EBADF
        );
        assert_eq!(
            leave_multicast_v4(invalid_fd(), &v4).unwrap_err(),
            Errno::EBADF
        );
        assert_eq!(
            join_multicast_v6(invalid_fd(), &v6).unwrap_err(),
            Errno::EBADF
        );
        assert_eq!(
            leave_multicast_v6(invalid_fd(), &v6).unwrap_err(),
            Errno::EBADF
        );
    }

    proptest::proptest! {
        /// Property (décodage `getsockopt` — structure **rendue par le kernel**) :
        /// `decode_timeout` rend `None` **si et seulement si** le `timeval` est nul,
        /// et **préserve** exactement la valeur sinon. Couvre le décodage de la
        /// structure lue depuis le kernel (exigence fuzz/property de la mission).
        #[test]
        fn decode_timeout_is_none_iff_zero(sec in i64::MIN..=i64::MAX, usec in i64::MIN..=i64::MAX) {
            let tv = Timeval { tv_sec: sec, tv_usec: usec };
            let decoded = decode_timeout(tv);
            if sec == 0 && usec == 0 {
                proptest::prop_assert_eq!(decoded, None);
            } else {
                proptest::prop_assert_eq!(decoded, Some(tv));
            }
        }
    }

    /// `set_so_reuseport` / `get_so_reuseport` : roundtrip.
    #[test]
    fn sockopt_reuseport_roundtrip() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket IPv4");
        set_so_reuseport(fd.as_fd(), true).expect("set_so_reuseport(true)");
        assert!(get_so_reuseport(fd.as_fd()).expect("get_so_reuseport"));
    }

    /// `set_tcp_nodelay` / `get_tcp_nodelay` : roundtrip sur un socket TCP.
    #[test]
    fn sockopt_tcp_nodelay_roundtrip() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket TCP");
        set_tcp_nodelay(fd.as_fd(), true).expect("set_tcp_nodelay(true)");
        assert!(get_tcp_nodelay(fd.as_fd()).expect("get_tcp_nodelay"));
    }

    /// Buffers `SO_RCVBUF` / `SO_SNDBUF` : set puis get (le kernel double la
    /// valeur demandée, on vérifie seulement qu'elle est non nulle).
    #[test]
    fn sockopt_rcvbuf_sndbuf_roundtrip() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket IPv4");
        set_so_rcvbuf(fd.as_fd(), 8192).expect("set_so_rcvbuf");
        assert!(get_so_rcvbuf(fd.as_fd()).expect("get_so_rcvbuf") > 0);
        set_so_sndbuf(fd.as_fd(), 8192).expect("set_so_sndbuf");
        assert!(get_so_sndbuf(fd.as_fd()).expect("get_so_sndbuf") > 0);
    }

    /// `set_tcp_keepidle`/`keepintvl`/`keepcnt` sur un socket TCP réel.
    #[test]
    fn sockopt_tcp_keepalive_params() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket TCP");
        set_tcp_keepidle(fd.as_fd(), 60).expect("keepidle");
        set_tcp_keepintvl(fd.as_fd(), 10).expect("keepintvl");
        set_tcp_keepcnt(fd.as_fd(), 5).expect("keepcnt");
    }

    // ── bind/getsockname avec IPv4 (branche Ipv4 de socket_addr_to_raw) ──

    #[test]
    fn bind_ipv4_loopback_and_getsockname() {
        use air_sys_types::net::Ipv4SocketAddr;
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket IPv4");
        set_so_reuseaddr(fd.as_fd(), true).expect("reuseaddr");
        let address = SocketAddr::Ipv4(Ipv4SocketAddr {
            address: [127, 0, 0, 1],
            port: 0, // port 0 = attribution automatique
        });
        bind(fd.as_fd(), &address).expect("bind IPv4 loopback");
        let name = getsockname(fd.as_fd()).expect("getsockname IPv4");
        if let SocketAddr::Ipv4(v4) = name {
            assert_eq!(v4.address, [127, 0, 0, 1]);
            assert!(v4.port > 0, "port assigné doit être > 0");
        } else {
            panic!("getsockname doit retourner IPv4, got {name:?}");
        }
    }

    // ── bind/getsockname avec IPv6 (branche Ipv6 de socket_addr_to_raw) ──

    #[test]
    fn bind_ipv6_loopback_and_getsockname() {
        use air_sys_types::net::Ipv6SocketAddr;
        let fd = socket(SocketDomain::Ipv6, SocketType::Stream, 0).expect("socket IPv6");
        set_so_reuseaddr(fd.as_fd(), true).expect("reuseaddr");
        let address = SocketAddr::Ipv6(Ipv6SocketAddr {
            address: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1], // ::1
            port: 0,
            flowinfo: 0,
            scope_id: 0,
        });
        bind(fd.as_fd(), &address).expect("bind IPv6 loopback");
        let name = getsockname(fd.as_fd()).expect("getsockname IPv6");
        if let SocketAddr::Ipv6(v6) = name {
            assert_eq!(v6.address, [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]);
        } else {
            panic!("getsockname doit retourner IPv6, got {name:?}");
        }
    }

    // ── Unix socket abstrait (branche Abstract dans parse_sockaddr_from_raw) ─

    #[test]
    fn bind_unix_abstract_and_getsockname() {
        use air_sys_types::net::UnixSocketAddr;
        let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket Unix");
        // UnixSocketAddr::Abstract prend le nom sans le '\0' initial.
        let address = SocketAddr::Unix(UnixSocketAddr::Abstract(b"air_test_abstract_42".to_vec()));
        bind(fd.as_fd(), &address).expect("bind Unix abstrait");
        let name = getsockname(fd.as_fd()).expect("getsockname abstrait");
        if let SocketAddr::Unix(UnixSocketAddr::Abstract(_)) = name {
            // OK : l'adresse abstraite a été retournée.
        } else {
            panic!("getsockname doit retourner Unix abstrait, got {name:?}");
        }
    }

    // ── socket sans nom → Unnamed dans getsockname ────────────────────────

    #[test]
    fn getsockname_unbound_unix_returns_unnamed_or_empty() {
        let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket Unix");
        // Un socket Unix non bindé retourne une adresse sans nom.
        match getsockname(fd.as_fd()) {
            Ok(SocketAddr::Unix(_)) => {}
            Ok(other) => panic!("attendu Unix, got {other:?}"),
            Err(_) => {} // certains kernels retournent une erreur pour un socket non bindé
        }
    }

    // ── bind EADDRINUSE ────────────────────────────────────────────────────

    #[test]
    fn bind_ipv4_eaddrinuse() {
        use air_sys_types::net::Ipv4SocketAddr;
        let fd1 = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket 1");
        let fd2 = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket 2");
        set_so_reuseaddr(fd1.as_fd(), true).expect("reuseaddr 1");
        let address = SocketAddr::Ipv4(Ipv4SocketAddr {
            address: [127, 0, 0, 1],
            port: 0,
        });
        bind(fd1.as_fd(), &address).expect("bind 1");
        // Obtient le port assigné.
        let name = getsockname(fd1.as_fd()).expect("getsockname 1");
        let port = if let SocketAddr::Ipv4(v4) = name {
            v4.port
        } else {
            panic!()
        };
        // Tente de binder le même port depuis fd2 : EADDRINUSE attendu.
        let addr2 = SocketAddr::Ipv4(Ipv4SocketAddr {
            address: [127, 0, 0, 1],
            port,
        });
        let err = bind(fd2.as_fd(), &addr2).unwrap_err();
        assert_eq!(err, EADDRINUSE);
    }

    // ── connect ECONNREFUSED ───────────────────────────────────────────────

    #[test]
    fn connect_ipv4_econnrefused() {
        use air_sys_types::net::Ipv4SocketAddr;
        // On se connecte sur un port probablement fermé (1).
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket TCP");
        let address = SocketAddr::Ipv4(Ipv4SocketAddr {
            address: [127, 0, 0, 1],
            port: 1, // port 1 est rarement en écoute
        });
        let err = connect(fd.as_fd(), &address).unwrap_err();
        assert!(
            err == ECONNREFUSED || err == Errno::EACCES,
            "attendu ECONNREFUSED ou EACCES, got {err:?}"
        );
    }

    // ── send / recv error paths ────────────────────────────────────────────

    #[test]
    fn send_ebadf() {
        let invalid = invalid_fd();
        let err = send(invalid, b"data", MessageFlags::empty()).unwrap_err();
        assert_eq!(err, Errno::EBADF);
    }

    #[test]
    fn recv_ebadf() {
        let invalid = invalid_fd();
        let mut buffer = [0u8; 4];
        let err = recv(invalid, &mut buffer, MessageFlags::empty()).unwrap_err();
        assert_eq!(err, Errno::EBADF);
    }

    // ── get_so_bindtodevice / set_so_bindtodevice ─────────────────────────

    #[test]
    fn get_so_bindtodevice_unbound_returns_empty() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket");
        let device = get_so_bindtodevice(fd.as_fd()).expect("get_so_bindtodevice");
        assert!(
            device.to_bytes().is_empty(),
            "socket non bindé à un device doit retourner vide"
        );
    }

    #[test]
    fn set_so_bindtodevice_lo_or_eperm() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket");
        // SO_BINDTODEVICE requiert CAP_NET_RAW ; on accepte EPERM.
        match set_so_bindtodevice(fd.as_fd(), c"lo") {
            Ok(()) => {
                // Succès : on peut vérifier que get renvoie "lo".
                let dev = get_so_bindtodevice(fd.as_fd()).expect("get après set");
                assert_eq!(dev.to_bytes(), b"lo");
            }
            Err(Errno::EPERM) | Err(Errno::ENODEV) => {
                // Pas root ou "lo" non existant : acceptable.
            }
            Err(e) => panic!("set_so_bindtodevice erreur inattendue : {e:?}"),
        }
    }

    // ── socket : chemin d'erreur ────────────────────────────────────────────

    #[test]
    fn socket_esocktnosupport_on_unsupported_type() {
        // AF_INET ne supporte pas SOCK_SEQPACKET : le kernel rejette la
        // combinaison avec ESOCKTNOSUPPORT. Couvre la branche d'erreur de
        // `socket` via une combinaison déterministe (pas de privilège requis).
        let err = socket(SocketDomain::Ipv4, SocketType::SeqPacket, 0).unwrap_err();
        assert_eq!(err, ESOCKTNOSUPPORT);
    }

    // ── accept4 EAGAIN sur socket non-bloquant ──────────────────────────

    #[test]
    fn accept4_eagain_on_nonblocking_without_connections() {
        use air_sys_types::net::UnixSocketAddr;
        let listener = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket");
        let path = c"/tmp/air_net_accept4_eagain_42.sock";
        let _ = std::fs::remove_file("/tmp/air_net_accept4_eagain_42.sock");
        bind(
            listener.as_fd(),
            &SocketAddr::Unix(UnixSocketAddr::Path(path.to_owned())),
        )
        .expect("bind");
        listen(listener.as_fd(), 1).expect("listen");
        // Bascule le socket en mode non-bloquant via fcntl F_SETFL + O_NONBLOCK.
        // O_NONBLOCK = 0x800 sur Linux x86_64/aarch64.
        let o_nonblock: u64 = 0x800;
        // SAFETY: `fcntl(F_SETFL)` ne prend que des scalaires (fd, cmd, flags) et ne
        // déréférence aucun pointeur utilisateur — appel sûr sur un FD valide.
        let ret = unsafe { raw_fcntl_setfl(listener.as_raw_fd(), 4, o_nonblock) };
        if ret < 0 {
            // fcntl non disponible : skip
            let _ = std::fs::remove_file("/tmp/air_net_accept4_eagain_42.sock");
            return;
        }
        let err = accept4(listener.as_fd(), AcceptFlags::CLOEXEC).unwrap_err();
        // Sur Linux, EWOULDBLOCK == EAGAIN == 11.
        assert_eq!(
            err,
            Errno::EAGAIN,
            "attendu EAGAIN sur socket non-bloquant vide"
        );
        let _ = std::fs::remove_file("/tmp/air_net_accept4_eagain_42.sock");
    }

    #[cfg(target_arch = "x86_64")]
    unsafe fn raw_fcntl_setfl(fd: i32, cmd: i64, flags: u64) -> i64 {
        let ret: i64;
        // SAFETY: fcntl (x86_64 = 72). Ne prend que des scalaires (fd, cmd, flags)
        // et ne touche à aucune mémoire utilisateur.
        unsafe {
            core::arch::asm!(
                "syscall",
                in("rax") 72_i64, // fcntl
                in("rdi") i64::from(fd),
                in("rsi") cmd,
                in("rdx") flags,
                lateout("rax") ret,
                lateout("rcx") _,
                lateout("r11") _,
                options(nostack, preserves_flags),
            );
        }
        ret
    }

    #[cfg(target_arch = "aarch64")]
    unsafe fn raw_fcntl_setfl(fd: i32, cmd: i64, flags: u64) -> i64 {
        let ret: i64;
        // SAFETY: fcntl (aarch64 = 25). Ne prend que des scalaires (fd, cmd, flags)
        // et ne touche à aucune mémoire utilisateur.
        unsafe {
            core::arch::asm!(
                "svc 0",
                in("x8") 25_i64, // fcntl
                inout("x0") i64::from(fd) => ret,
                in("x1") cmd,
                in("x2") flags,
                options(nostack, preserves_flags),
            );
        }
        ret
    }

    // ── shutdown error path ────────────────────────────────────────────────

    #[test]
    fn shutdown_enotconn_on_unconnected() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket");
        let err = shutdown(fd.as_fd(), ShutdownMode::Both).unwrap_err();
        assert_eq!(err, ENOTCONN);
    }

    // ───────── debug_assert errno helper ─────────

    // Couvrent les deux opérandes du `debug_assert!(ret < 0 && ret > -4096)`.
    #[test]
    #[should_panic(expected = "ret < 0 && ret > -4096")]
    fn errno_from_negative_syscall_ret_panics_on_non_negative() {
        let _ = errno_from_negative_syscall_ret(0);
    }

    #[test]
    #[should_panic(expected = "ret < 0 && ret > -4096")]
    fn errno_from_negative_syscall_ret_panics_below_errno_range() {
        let _ = errno_from_negative_syscall_ret(-5000);
    }

    // ───────── branches d'erreur `if ret < 0` via fd invalide → EBADF ─────────

    #[test]
    fn listen_ebadf_on_invalid_fd() {
        assert_eq!(listen(invalid_fd(), 1).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn getsockname_ebadf_on_invalid_fd() {
        assert_eq!(getsockname(invalid_fd()).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn getpeername_ebadf_on_invalid_fd() {
        assert_eq!(getpeername(invalid_fd()).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn get_so_peercred_ebadf_on_invalid_fd() {
        assert_eq!(get_so_peercred(invalid_fd()).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn get_so_linger_ebadf_on_invalid_fd() {
        assert_eq!(get_so_linger(invalid_fd()).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn set_so_linger_ebadf_on_invalid_fd() {
        use core::time::Duration;
        let err =
            set_so_linger(invalid_fd(), LingerOption::Enabled(Duration::from_secs(1))).unwrap_err();
        assert_eq!(err, Errno::EBADF);
    }

    #[test]
    fn set_so_bindtodevice_ebadf_on_invalid_fd() {
        assert_eq!(
            set_so_bindtodevice(invalid_fd(), c"lo").unwrap_err(),
            Errno::EBADF
        );
    }

    #[test]
    fn get_so_bindtodevice_ebadf_on_invalid_fd() {
        assert_eq!(get_so_bindtodevice(invalid_fd()).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn sendmsg_ebadf_on_invalid_fd() {
        let data = *b"x";
        let iov = [IoSlice::new(&data)];
        let req = SendMessageRequest {
            iov: &iov,
            address: None,
            fds: &[],
            flags: MessageFlags::empty(),
        };
        assert_eq!(sendmsg(invalid_fd(), &req).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn recvmsg_ebadf_on_invalid_fd() {
        let mut buffer = [0u8; 8];
        let mut iov = [IoSliceMut::new(&mut buffer)];
        let mut req = ReceiveMessageRequest {
            iov: &mut iov,
            flags: MessageFlags::empty(),
        };
        assert_eq!(recvmsg(invalid_fd(), &mut req).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn socketpair_eopnotsupp_on_inet_domain() {
        // `socketpair(2)` n'est supporté que pour `AF_UNIX` → EOPNOTSUPP sur
        // un domaine inet (couvre la branche `if ret < 0` de `socketpair`).
        let eopnotsupp = Errno::try_from_raw(95).unwrap();
        let err = socketpair(SocketDomain::Ipv4, SocketType::Stream, 0).unwrap_err();
        assert_eq!(err, eopnotsupp);
    }

    // ───────── clamps `if val > i32::MAX` (sur socket valide) ─────────

    #[test]
    fn set_so_rcvbuf_clamps_oversized() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket");
        set_so_rcvbuf(fd.as_fd(), 0x8000_0000).expect("set_so_rcvbuf clamp");
    }

    #[test]
    fn set_so_sndbuf_clamps_oversized() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket");
        set_so_sndbuf(fd.as_fd(), 0x8000_0000).expect("set_so_sndbuf clamp");
    }

    #[test]
    fn set_so_linger_clamps_oversized_secs() {
        use core::time::Duration;
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket");
        // Durée en secondes > i32::MAX → clampée avant le syscall (le résultat
        // du syscall importe peu : la branche de clamp est exercée).
        let _ = set_so_linger(
            fd.as_fd(),
            LingerOption::Enabled(Duration::from_secs(u64::from(u32::MAX))),
        );
    }

    #[test]
    fn set_tcp_keepalive_params_clamp_oversized() {
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket TCP");
        // Valeurs > i32::MAX → clampées avant le syscall.
        let _ = set_tcp_keepidle(fd.as_fd(), 0x8000_0000);
        let _ = set_tcp_keepintvl(fd.as_fd(), 0x8000_0000);
        let _ = set_tcp_keepcnt(fd.as_fd(), 0x8000_0000);
    }

    // ───────── parseur `raw_to_socket_addr` : buffers tronqués → None ─────────

    #[test]
    fn raw_to_socket_addr_rejects_buffer_shorter_than_len() {
        // `buffer.len() < length` → None (couvre la garde l.154).
        assert!(raw_to_socket_addr(&[2, 0], 16).is_none());
    }

    #[test]
    fn raw_to_socket_addr_rejects_truncated_ipv4() {
        // famille AF_INET (2) mais `length < 16` → None (l.184).
        let mut buffer = [0u8; 16];
        buffer[0..2].copy_from_slice(&2u16.to_ne_bytes());
        assert!(raw_to_socket_addr(&buffer, 10).is_none());
    }

    #[test]
    fn raw_to_socket_addr_rejects_truncated_ipv6() {
        // famille AF_INET6 (10) mais `length < 28` → None (l.193).
        let mut buffer = [0u8; 28];
        buffer[0..2].copy_from_slice(&10u16.to_ne_bytes());
        assert!(raw_to_socket_addr(&buffer, 20).is_none());
    }

    // ───────── codec sockaddr PUBLIC (ADR-070) : round-trip + gardes ─────────

    #[test]
    fn socket_addr_bytes_round_trip_ipv4() {
        let address = SocketAddr::Ipv4(Ipv4SocketAddr {
            address: [127, 0, 0, 1],
            port: 443,
        });
        let mut buffer = [0u8; 128];
        let length = socket_addr_to_bytes(&address, &mut buffer).expect("encode IPv4");
        assert_eq!(length, 16);
        assert_eq!(socket_addr_from_bytes(&buffer, length), Some(address));
    }

    #[test]
    fn socket_addr_bytes_round_trip_ipv6() {
        let address = SocketAddr::Ipv6(Ipv6SocketAddr {
            address: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
            port: 443,
            flowinfo: 0,
            scope_id: 0,
        });
        let mut buffer = [0u8; 128];
        let length = socket_addr_to_bytes(&address, &mut buffer).expect("encode IPv6");
        assert_eq!(length, 28);
        assert_eq!(socket_addr_from_bytes(&buffer, length), Some(address));
    }

    #[test]
    fn socket_addr_to_bytes_reports_none_when_out_too_small() {
        let address = SocketAddr::Ipv4(Ipv4SocketAddr {
            address: [10, 0, 0, 1],
            port: 22,
        });
        // `out` plus court que les 16 octets d'un sockaddr_in ⇒ None (garde `out`).
        let mut tiny = [0u8; 8];
        assert_eq!(socket_addr_to_bytes(&address, &mut tiny), None);
    }

    #[test]
    fn socket_option_int_public_wrappers_round_trip() {
        // Exposition publique (ADR-071) : set SO_REUSEADDR puis get SO_TYPE.
        let sock = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket");
        // SOL_SOCKET = 1, SO_REUSEADDR = 2, SO_TYPE = 3.
        set_socket_option_int(sock.as_fd(), 1, 2, 1).expect("set SO_REUSEADDR");
        let kind = get_socket_option_int(sock.as_fd(), 1, 3).expect("get SO_TYPE");
        assert_eq!(kind, 1); // SOCK_STREAM
    }

    #[test]
    fn socket_option_int_reports_error_on_bad_option() {
        // optname invalide => ENOPROTOOPT propage (chemin d'erreur).
        let sock = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket");
        assert!(get_socket_option_int(sock.as_fd(), 1, 99_999).is_err());
    }

    #[test]
    fn socket_addr_from_bytes_rejects_unknown_family() {
        // Délègue à `raw_to_socket_addr` : une famille inconnue rend `None`.
        assert!(socket_addr_from_bytes(&[99, 0, 0, 0, 0, 0, 0, 0], 8).is_none());
    }

    // ───────── SCM_RIGHTS : passage de FD sur socketpair Unix ─────────

    #[test]
    fn scm_rights_fd_passing_roundtrip() {
        // Couvre `build_scm_rights_cmsg` (ctrl non vide), le bras `fds` de
        // `sendmsg`, et `parse_scm_rights` (boucle cmsg + extraction des FDs).
        let (fd_a, fd_b) =
            socketpair(SocketDomain::Unix, SocketType::Stream, 0).expect("socketpair");
        let passed =
            crate::mem::memfd_create(c"air-scm-rights", air_sys_types::mem::MemfdFlags::empty())
                .expect("memfd");
        let data = *b"fd!";
        let iov = [IoSlice::new(&data)];
        let fds = [passed.as_fd()];
        let req = SendMessageRequest {
            iov: &iov,
            address: None,
            fds: &fds,
            flags: MessageFlags::empty(),
        };
        sendmsg(fd_a.as_fd(), &req).expect("sendmsg with fd");

        let mut buffer = [0u8; 8];
        let mut iov_r = [IoSliceMut::new(&mut buffer)];
        let mut req_r = ReceiveMessageRequest {
            iov: &mut iov_r,
            flags: MessageFlags::empty(),
        };
        let res = recvmsg(fd_b.as_fd(), &mut req_r).expect("recvmsg with fd");
        assert_eq!(&buffer[..res.bytes_received], b"fd!");
        assert_eq!(res.fds.len(), 1, "un FD doit être reçu via SCM_RIGHTS");
    }

    #[test]
    fn socket_eprotonosupport_on_mismatched_protocol() {
        // Type STREAM avec le protocole UDP (17) → EPROTONOSUPPORT (couvre la
        // branche `if ret < 0` de `socket`).
        let eprotonosupport = Errno::try_from_raw(93).unwrap();
        let err = socket(SocketDomain::Ipv4, SocketType::Stream, 17).unwrap_err();
        assert_eq!(err, eprotonosupport);
    }

    #[test]
    fn listen_clamps_oversized_backlog() {
        // `backlog > i32::MAX` → clampé avant le syscall (couvre la branche de
        // clamp l.489). Le résultat du syscall importe peu.
        let fd = socket(SocketDomain::Ipv4, SocketType::Stream, 0).expect("socket");
        let _ = listen(fd.as_fd(), 0x8000_0000);
    }

    // ───────── parse_scm_rights : buffers cmsg dégénérés ─────────

    #[test]
    fn parse_scm_rights_ignores_non_scm_rights_cmsg() {
        // Un cmsg de niveau/type ≠ SOL_SOCKET/SCM_RIGHTS ne produit aucun FD
        // (couvre les côtés faux de `level == 1 && ty == 1 && length >= 16`).
        let mut buffer = vec![0u8; 16];
        buffer[0..8].copy_from_slice(&16u64.to_ne_bytes()); // cmsg_len = 16
        buffer[8..12].copy_from_slice(&0i32.to_ne_bytes()); // level ≠ SOL_SOCKET
        buffer[12..16].copy_from_slice(&0i32.to_ne_bytes()); // type ≠ SCM_RIGHTS
        let fds = parse_scm_rights(&buffer, 16);
        assert!(fds.is_empty());
    }

    #[test]
    fn parse_scm_rights_ignores_too_short_payload() {
        // level/type = SCM_RIGHTS mais `length < 16` → pas de FD (couvre le côté
        // faux de `length >= 16`).
        let mut buffer = vec![0u8; 16];
        buffer[0..8].copy_from_slice(&8u64.to_ne_bytes()); // cmsg interne length = 8 (< 16)
        buffer[8..12].copy_from_slice(&1i32.to_ne_bytes()); // SOL_SOCKET
        buffer[12..16].copy_from_slice(&1i32.to_ne_bytes()); // SCM_RIGHTS
        let fds = parse_scm_rights(&buffer, 16);
        assert!(fds.is_empty());
    }

    #[test]
    fn parse_scm_rights_stops_when_cmsg_len_exceeds_buffer() {
        // `cmsg_len` annoncé plus grand que le buffer réel → la 2ᵉ borne du
        // `while` (`<= cmsg_buf.len()`) arrête la boucle (couvre l.251).
        let buffer = vec![0u8; 8]; // trop court pour un header de 16 octets
        let fds = parse_scm_rights(&buffer, 1000);
        assert!(fds.is_empty());
    }

    #[test]
    fn parse_scm_rights_ignores_wrong_cmsg_type() {
        // level = SOL_SOCKET mais type ≠ SCM_RIGHTS → côté faux de `ty == 1`.
        let mut buffer = vec![0u8; 16];
        buffer[0..8].copy_from_slice(&16u64.to_ne_bytes());
        buffer[8..12].copy_from_slice(&1i32.to_ne_bytes()); // SOL_SOCKET
        buffer[12..16].copy_from_slice(&2i32.to_ne_bytes()); // type ≠ SCM_RIGHTS
        assert!(parse_scm_rights(&buffer, 16).is_empty());
    }

    #[test]
    fn parse_scm_rights_breaks_on_zero_len_entry() {
        // Un cmsg de longueur interne 0 → `aligned == 0` → `break` (l.292),
        // évite une boucle infinie.
        let mut buffer = vec![0u8; 16];
        buffer[0..8].copy_from_slice(&0u64.to_ne_bytes()); // length interne = 0
        buffer[8..12].copy_from_slice(&1i32.to_ne_bytes());
        buffer[12..16].copy_from_slice(&1i32.to_ne_bytes());
        assert!(parse_scm_rights(&buffer, 16).is_empty());
    }

    #[test]
    fn get_so_rcvbuf_ebadf_on_invalid_fd() {
        // Couvre la branche d'erreur du helper partagé `getsockopt_i32` (l.344).
        assert_eq!(get_so_rcvbuf(invalid_fd()).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn sendmsg_with_explicit_addr_on_udp() {
        // `sendmsg` avec `address = Some` (sendto-style) couvre les branches
        // `address`/`name_ptr` (l.756, 768).
        let fd = socket(SocketDomain::Ipv4, SocketType::Datagram, 0).expect("socket UDP");
        let dest = SocketAddr::Ipv4(Ipv4SocketAddr {
            address: [127, 0, 0, 1],
            port: 9,
        });
        let data = *b"udp";
        let iov = [IoSlice::new(&data)];
        let req = SendMessageRequest {
            iov: &iov,
            address: Some(&dest),
            fds: &[],
            flags: MessageFlags::empty(),
        };
        let _ = sendmsg(fd.as_fd(), &req);
    }
}