native_ipc/

memory.rs

//! Common lifecycle and policy interface for the best native shared-memory backend.

use core::fmt;
use core::sync::atomic::{Ordering, compiler_fence};

/// Native backend selected for the compilation target.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum NativePlatform {
    /// Linux sealed anonymous `memfd` mappings.
    Linux,
    /// macOS Mach VM memory-entry mappings.
    MacOs,
    /// Windows unnamed paging-file section mappings.
    Windows,
}

/// Processor architecture selected for the native backend.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum NativeArchitecture {
    /// 64-bit Arm (Rust `aarch64`) architecture.
    Arm64,
    /// 64-bit x86 (Rust `x86_64`) architecture.
    Amd64,
}

/// Kernel mechanism that freezes shared-memory authority before transfer.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum AuthorityMechanism {
    /// Linux descriptor seals plus a read-only imported mapping.
    DescriptorSeals,
    /// Mach memory-entry maximum protections.
    MaximumPortRights,
    /// Windows exact-rights duplicated section handles.
    ExactHandleRights,
}

/// Cross-platform capabilities of the selected native backend.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct NativeMemoryCapabilities {
    platform: NativePlatform,
    architecture: NativeArchitecture,
    authority: AuthorityMechanism,
}

impl NativeMemoryCapabilities {
    /// Selected operating-system backend.
    pub const fn platform(self) -> NativePlatform {
        self.platform
    }

    /// Selected processor architecture.
    pub const fn architecture(self) -> NativeArchitecture {
        self.architecture
    }

    /// Native mechanism used to freeze or attenuate authority.
    pub const fn authority_mechanism(self) -> AuthorityMechanism {
        self.authority
    }

    /// Whether a private region can grow by allocating a replacement mapping.
    pub const fn supports_replacement_growth(self) -> bool {
        true
    }

    /// Whether a shared mapping can grow in place.
    pub const fn supports_in_place_growth(self) -> bool {
        false
    }

    /// Whether permission changes are accepted after sharing.
    pub const fn supports_post_share_permission_changes(self) -> bool {
        false
    }

    /// Whether dropping all owners automatically releases the anonymous object.
    pub const fn releases_on_drop(self) -> bool {
        true
    }
}

/// Reports the native memory behavior selected for this target.
pub const fn native_memory_capabilities() -> NativeMemoryCapabilities {
    NativeMemoryCapabilities {
        platform: native_platform(),
        architecture: native_architecture(),
        authority: authority_mechanism(),
    }
}

/// Endpoint that will retain the sole writable mapping after transfer.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum WriterOwner {
    /// The process creating and transferring the region remains the writer.
    Creator,
    /// The authenticated peer becomes the sole writer.
    Peer,
}

/// Planned access for one endpoint after the sharing transition.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum MemoryAccess {
    /// Mapping may load but cannot store.
    ReadOnly,
    /// Mapping is the sole store-capable view.
    ReadWrite,
}

/// Exact creator/peer access requested for the future sharing transition.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct PermissionPlan {
    writer: WriterOwner,
}

impl PermissionPlan {
    /// Creates the only supported permission plan: one writer and one reader.
    pub const fn new(writer: WriterOwner) -> Self {
        Self { writer }
    }

    /// Endpoint selected as sole writer.
    pub const fn writer(self) -> WriterOwner {
        self.writer
    }

    /// Creator's access after authenticated transfer.
    pub const fn creator_access(self) -> MemoryAccess {
        match self.writer {
            WriterOwner::Creator => MemoryAccess::ReadWrite,
            WriterOwner::Peer => MemoryAccess::ReadOnly,
        }
    }

    /// Peer's access after authenticated transfer.
    pub const fn peer_access(self) -> MemoryAccess {
        match self.writer {
            WriterOwner::Creator => MemoryAccess::ReadOnly,
            WriterOwner::Peer => MemoryAccess::ReadWrite,
        }
    }

    /// Shared executable mappings are never permitted.
    pub const fn executable(self) -> bool {
        false
    }
}

/// Capacity policy while a region is still private and quiescent.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum GrowthPolicy {
    /// Mapping size is fixed at allocation.
    Fixed,
    /// Growth replaces the private mapping up to an inclusive logical limit.
    ReplaceBeforeShare {
        /// Maximum logical byte length.
        maximum_len: usize,
    },
}

/// Cleanup policy applied while the common wrapper still owns the region.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CleanupPolicy {
    /// Release the anonymous native object without an explicit clearing pass.
    ReleaseOnDrop,
    /// Clear the complete mapping before releasing it.
    ClearThenRelease,
}

/// Mandatory authority-sealing policy for shared regions.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum SealPolicy {
    /// Seal or attenuate native authority during the consuming share transition.
    RequiredOnShare,
}

/// Immutable configuration for one native shared-memory region.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct RegionOptions {
    logical_len: usize,
    growth: GrowthPolicy,
    cleanup: CleanupPolicy,
    permissions: PermissionPlan,
    seal: SealPolicy,
}

impl RegionOptions {
    /// Creates a fixed-size region with clear-on-drop cleanup.
    pub const fn fixed(logical_len: usize, writer: WriterOwner) -> Self {
        Self {
            logical_len,
            growth: GrowthPolicy::Fixed,
            cleanup: CleanupPolicy::ClearThenRelease,
            permissions: PermissionPlan::new(writer),
            seal: SealPolicy::RequiredOnShare,
        }
    }

    /// Creates a private growable region with clear-on-drop cleanup.
    ///
    /// Growth allocates a replacement mapping. It is never available after
    /// the region is consumed for native sharing.
    pub const fn growable(logical_len: usize, maximum_len: usize, writer: WriterOwner) -> Self {
        Self {
            logical_len,
            growth: GrowthPolicy::ReplaceBeforeShare { maximum_len },
            cleanup: CleanupPolicy::ClearThenRelease,
            permissions: PermissionPlan::new(writer),
            seal: SealPolicy::RequiredOnShare,
        }
    }

    /// Overrides cleanup behavior before the native sharing transition.
    pub const fn with_cleanup(mut self, cleanup: CleanupPolicy) -> Self {
        self.cleanup = cleanup;
        self
    }

    /// Initial logical bytes requested by the caller.
    pub const fn logical_len(self) -> usize {
        self.logical_len
    }

    /// Private growth policy.
    pub const fn growth(self) -> GrowthPolicy {
        self.growth
    }

    /// Pre-transfer cleanup policy.
    pub const fn cleanup(self) -> CleanupPolicy {
        self.cleanup
    }

    /// Required one-writer permission plan.
    pub const fn permissions(self) -> PermissionPlan {
        self.permissions
    }

    /// Mandatory native authority-sealing behavior.
    pub const fn seal(self) -> SealPolicy {
        self.seal
    }

    /// Inclusive logical capacity limit.
    pub const fn maximum_len(self) -> usize {
        match self.growth {
            GrowthPolicy::Fixed => self.logical_len,
            GrowthPolicy::ReplaceBeforeShare { maximum_len } => maximum_len,
        }
    }
}

/// Current common lifecycle state.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum RegionState {
    /// Region is private, writable, unshared, and not yet authority-sealed.
    Quiescent,
}

/// Snapshot of a managed region's portable state and policy.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct RegionStatus {
    /// Current lifecycle state.
    pub state: RegionState,
    /// Logical application-visible length.
    pub logical_len: usize,
    /// Native page-rounded mapping length.
    pub mapped_len: usize,
    /// Maximum pre-share logical length.
    pub maximum_len: usize,
    /// Whether another pre-share growth operation is possible.
    pub can_grow: bool,
    /// Future creator/peer permission assignment.
    pub permissions: PermissionPlan,
    /// Cleanup behavior while managed by this wrapper.
    pub cleanup: CleanupPolicy,
    /// Mandatory seal applied by the consuming native share transition.
    pub seal: SealPolicy,
}

/// Portable allocation, policy, or lifecycle failure.
#[derive(Debug)]
pub enum MemoryError {
    /// Shared-memory regions cannot be empty.
    ZeroLength,
    /// Configured maximum is smaller than the initial logical length.
    MaximumBelowInitial {
        /// Initial requested logical length.
        initial: usize,
        /// Configured maximum logical length.
        maximum: usize,
    },
    /// Fixed-size policy rejects growth.
    FixedSize,
    /// Shrinking would silently discard user-owned bytes.
    ShrinkUnsupported {
        /// Current logical length.
        current: usize,
        /// Requested smaller logical length.
        requested: usize,
    },
    /// Requested growth exceeds the configured limit.
    MaximumExceeded {
        /// Requested logical length.
        requested: usize,
        /// Configured maximum logical length.
        maximum: usize,
    },
    /// Selected native backend rejected allocation.
    Platform(NativeMemoryPlatformError),
}

impl fmt::Display for MemoryError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "native shared-memory operation failed: {self:?}")
    }
}

impl std::error::Error for MemoryError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Platform(error) => Some(error),
            _ => None,
        }
    }
}

impl From<NativeMemoryPlatformError> for MemoryError {
    fn from(value: NativeMemoryPlatformError) -> Self {
        Self::Platform(value)
    }
}

/// Common owner of the best private native shared-memory object on this target.
///
/// It exposes logical initialization bytes only through a closure. Consuming
/// [`NativeRegion::prepare_for_sharing`] hands the region to the existing
/// authenticated platform transfer typestate, which applies real native seals
/// and exact permissions. Growth and arbitrary permission changes are no longer
/// possible after that transition.
pub struct NativeRegion {
    inner: Option<PlatformQuiescentRegion>,
    logical_len: usize,
    options: RegionOptions,
}

impl NativeRegion {
    /// Allocates a zeroed, anonymous, non-executable native region.
    pub fn allocate(options: RegionOptions) -> Result<Self, MemoryError> {
        validate_options(options)?;
        let inner = PlatformQuiescentRegion::new(options.logical_len())?;
        Ok(Self {
            inner: Some(inner),
            logical_len: options.logical_len(),
            options,
        })
    }

    /// Returns the immutable allocation and authority policy.
    pub const fn options(&self) -> RegionOptions {
        self.options
    }

    /// Returns a portable status snapshot.
    pub fn status(&self) -> RegionStatus {
        let maximum_len = self.options.maximum_len();
        RegionStatus {
            state: RegionState::Quiescent,
            logical_len: self.logical_len,
            mapped_len: self.inner().len(),
            maximum_len,
            can_grow: matches!(
                self.options.growth(),
                GrowthPolicy::ReplaceBeforeShare { .. }
            ) && self.logical_len < maximum_len,
            permissions: self.options.permissions(),
            cleanup: self.options.cleanup(),
            seal: self.options.seal(),
        }
    }

    /// Runs one initialization operation over logical bytes only.
    ///
    /// Page-rounded padding remains zero and inaccessible through this common
    /// method. No capability has escaped while the closure runs.
    pub fn initialize<R>(&mut self, operation: impl FnOnce(&mut [u8]) -> R) -> R {
        let logical_len = self.logical_len;
        operation(&mut self.inner_mut().as_bytes_mut()[..logical_len])
    }

    /// Clears the complete page-rounded mapping and retains it for reuse.
    ///
    /// Every byte, including native page padding, is overwritten through the
    /// live mapping before this method returns.
    pub fn clear(&mut self) {
        clear_mapping(self.inner_mut());
    }

    /// Grows by replacing the still-private mapping and preserving logical bytes.
    pub fn grow(&mut self, requested: usize) -> Result<(), MemoryError> {
        if requested == 0 {
            return Err(MemoryError::ZeroLength);
        }
        if requested < self.logical_len {
            return Err(MemoryError::ShrinkUnsupported {
                current: self.logical_len,
                requested,
            });
        }
        if requested == self.logical_len {
            return Ok(());
        }
        let maximum = match self.options.growth() {
            GrowthPolicy::Fixed => return Err(MemoryError::FixedSize),
            GrowthPolicy::ReplaceBeforeShare { maximum_len } => maximum_len,
        };
        if requested > maximum {
            return Err(MemoryError::MaximumExceeded { requested, maximum });
        }

        let mut replacement = PlatformQuiescentRegion::new(requested)?;
        replacement.as_bytes_mut()[..self.logical_len]
            .copy_from_slice(&self.inner().as_bytes()[..self.logical_len]);
        let mut previous = self
            .inner
            .replace(replacement)
            .expect("managed region always owns its mapping");
        if self.options.cleanup() == CleanupPolicy::ClearThenRelease {
            clear_mapping(&mut previous);
        }
        self.logical_len = requested;
        Ok(())
    }

    /// Explicitly clears according to policy and releases the anonymous object.
    pub fn close(mut self) {
        self.release();
    }

    /// Overwrites the complete mapping, then explicitly releases it.
    ///
    /// This ignores [`CleanupPolicy`] and always performs the clearing pass.
    /// It cannot erase copies previously made by a process, the kernel, or a
    /// device. The region must still be quiescent and exclusively owned here;
    /// shared regions are destroyed by their transferred lifecycle owner.
    pub fn destroy(mut self) {
        if let Some(inner) = self.inner.as_mut() {
            clear_mapping(inner);
        }
        drop(self.inner.take());
    }

    /// Freezes common initialization/growth and creates a native share request.
    ///
    /// The request retains the permission and mandatory seal policy alongside
    /// the native region. Its platform parts must be consumed by the matching
    /// authenticated prepare/transfer operation.
    pub fn prepare_for_sharing(mut self) -> NativeShareRequest {
        NativeShareRequest {
            inner: self.inner.take(),
            permissions: self.options.permissions(),
            seal: self.options.seal(),
            cleanup: self.options.cleanup(),
        }
    }

    fn inner(&self) -> &PlatformQuiescentRegion {
        self.inner
            .as_ref()
            .expect("managed region always owns its mapping")
    }

    fn inner_mut(&mut self) -> &mut PlatformQuiescentRegion {
        self.inner
            .as_mut()
            .expect("managed region always owns its mapping")
    }

    fn release(&mut self) {
        if let Some(inner) = self.inner.as_mut()
            && self.options.cleanup() == CleanupPolicy::ClearThenRelease
        {
            clear_mapping(inner);
        }
        drop(self.inner.take());
    }
}

/// Consuming boundary between common memory management and native transfer.
///
/// This type exposes no bytes and supports no growth. It keeps the requested
/// one-writer permission plan attached until the caller enters the existing
/// platform-specific authenticated transfer typestate.
pub struct NativeShareRequest {
    inner: Option<PlatformQuiescentRegion>,
    permissions: PermissionPlan,
    seal: SealPolicy,
    cleanup: CleanupPolicy,
}

impl NativeShareRequest {
    /// Required creator/peer access assignment.
    pub const fn permissions(&self) -> PermissionPlan {
        self.permissions
    }

    /// Mandatory native authority-sealing policy.
    pub const fn seal_policy(&self) -> SealPolicy {
        self.seal
    }

    /// Complete native page-rounded mapping length.
    pub fn mapped_len(&self) -> usize {
        self.inner
            .as_ref()
            .expect("share request always owns its mapping")
            .len()
    }

    /// Enters the platform authenticated transfer layer.
    ///
    /// The returned permission plan must select the matching creator-writer or
    /// peer-writer consuming transition. Native code applies the actual seal or
    /// maximum-rights attenuation; safe code cannot disable the seal policy.
    pub fn into_platform_parts(mut self) -> (PlatformQuiescentRegion, PermissionPlan) {
        let region = self
            .inner
            .take()
            .expect("share request always owns its mapping");
        (region, self.permissions)
    }

    /// Clears and releases a prepared request without sharing it.
    pub fn destroy(mut self) {
        if let Some(inner) = self.inner.as_mut() {
            clear_mapping(inner);
        }
        drop(self.inner.take());
    }

    fn release(&mut self) {
        if let Some(inner) = self.inner.as_mut()
            && self.cleanup == CleanupPolicy::ClearThenRelease
        {
            clear_mapping(inner);
        }
        drop(self.inner.take());
    }
}

impl Drop for NativeShareRequest {
    fn drop(&mut self) {
        self.release();
    }
}

fn clear_mapping(region: &mut PlatformQuiescentRegion) {
    for byte in region.as_bytes_mut() {
        // SAFETY: the quiescent typestate uniquely owns the complete live
        // mapping, and each byte pointer is valid for one volatile store.
        unsafe { core::ptr::write_volatile(byte, 0) };
    }
    compiler_fence(Ordering::SeqCst);
}

impl Drop for NativeRegion {
    fn drop(&mut self) {
        self.release();
    }
}

fn validate_options(options: RegionOptions) -> Result<(), MemoryError> {
    if options.logical_len() == 0 {
        return Err(MemoryError::ZeroLength);
    }
    let maximum = options.maximum_len();
    if maximum < options.logical_len() {
        return Err(MemoryError::MaximumBelowInitial {
            initial: options.logical_len(),
            maximum,
        });
    }
    Ok(())
}

#[cfg(target_os = "linux")]
/// Native quiescent region selected on Linux.
pub type PlatformQuiescentRegion = native_ipc_platform::linux::QuiescentRegion;
#[cfg(target_os = "linux")]
/// Native allocation error selected on Linux.
pub type NativeMemoryPlatformError = native_ipc_platform::linux::LinuxError;

#[cfg(target_os = "macos")]
/// Native quiescent region selected on macOS.
pub type PlatformQuiescentRegion = native_ipc_platform::macos::QuiescentRegion;
#[cfg(target_os = "macos")]
/// Native allocation error selected on macOS.
pub type NativeMemoryPlatformError = native_ipc_platform::macos::MachError;

#[cfg(target_os = "windows")]
/// Native quiescent region selected on Windows.
pub type PlatformQuiescentRegion = native_ipc_platform::windows::QuiescentRegion;
#[cfg(target_os = "windows")]
/// Native allocation error selected on Windows.
pub type NativeMemoryPlatformError = native_ipc_platform::windows::WindowsError;

#[cfg(target_os = "linux")]
const fn native_platform() -> NativePlatform {
    NativePlatform::Linux
}
#[cfg(target_os = "macos")]
const fn native_platform() -> NativePlatform {
    NativePlatform::MacOs
}
#[cfg(target_os = "windows")]
const fn native_platform() -> NativePlatform {
    NativePlatform::Windows
}

#[cfg(target_arch = "aarch64")]
const fn native_architecture() -> NativeArchitecture {
    NativeArchitecture::Arm64
}

#[cfg(target_arch = "x86_64")]
const fn native_architecture() -> NativeArchitecture {
    NativeArchitecture::Amd64
}

#[cfg(target_os = "linux")]
const fn authority_mechanism() -> AuthorityMechanism {
    AuthorityMechanism::DescriptorSeals
}
#[cfg(target_os = "macos")]
const fn authority_mechanism() -> AuthorityMechanism {
    AuthorityMechanism::MaximumPortRights
}
#[cfg(target_os = "windows")]
const fn authority_mechanism() -> AuthorityMechanism {
    AuthorityMechanism::ExactHandleRights
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn capabilities_report_the_compilation_architecture() {
        let capabilities = native_memory_capabilities();

        #[cfg(target_arch = "aarch64")]
        assert_eq!(capabilities.architecture(), NativeArchitecture::Arm64);
        #[cfg(target_arch = "x86_64")]
        assert_eq!(capabilities.architecture(), NativeArchitecture::Amd64);
    }

    #[test]
    fn growable_region_preserves_bytes_and_reports_policy() {
        let options = RegionOptions::growable(32, 128, WriterOwner::Creator);
        let mut region = NativeRegion::allocate(options).unwrap();
        region.initialize(|bytes| bytes[..4].copy_from_slice(b"NIPC"));
        region.grow(96).unwrap();

        let status = region.status();
        assert_eq!(status.logical_len, 96);
        assert_eq!(status.maximum_len, 128);
        assert!(status.can_grow);
        assert_eq!(status.permissions.creator_access(), MemoryAccess::ReadWrite);
        assert_eq!(status.permissions.peer_access(), MemoryAccess::ReadOnly);
        region.initialize(|bytes| assert_eq!(&bytes[..4], b"NIPC"));
    }

    #[test]
    fn fixed_and_bounded_growth_fail_closed() {
        let mut fixed =
            NativeRegion::allocate(RegionOptions::fixed(32, WriterOwner::Peer)).unwrap();
        assert!(matches!(fixed.grow(64), Err(MemoryError::FixedSize)));

        let mut bounded =
            NativeRegion::allocate(RegionOptions::growable(32, 64, WriterOwner::Peer)).unwrap();
        assert!(matches!(
            bounded.grow(65),
            Err(MemoryError::MaximumExceeded {
                requested: 65,
                maximum: 64
            })
        ));
        assert!(matches!(
            bounded.grow(16),
            Err(MemoryError::ShrinkUnsupported {
                current: 32,
                requested: 16
            })
        ));
    }

    #[test]
    fn clear_covers_logical_bytes() {
        let mut region =
            NativeRegion::allocate(RegionOptions::fixed(32, WriterOwner::Creator)).unwrap();
        region.initialize(|bytes| bytes.fill(0xaa));
        region.clear();
        region.initialize(|bytes| assert!(bytes.iter().all(|byte| *byte == 0)));
        region.initialize(|bytes| bytes[..4].copy_from_slice(b"REUS"));
        region.initialize(|bytes| assert_eq!(&bytes[..4], b"REUS"));
        region.destroy();
    }

    #[test]
    fn share_request_preserves_permissions_and_removes_byte_access() {
        let region = NativeRegion::allocate(RegionOptions::fixed(32, WriterOwner::Peer)).unwrap();
        let request = region.prepare_for_sharing();
        assert_eq!(request.seal_policy(), SealPolicy::RequiredOnShare);
        assert_eq!(
            request.permissions().creator_access(),
            MemoryAccess::ReadOnly
        );
        assert_eq!(request.permissions().peer_access(), MemoryAccess::ReadWrite);
        assert!(request.mapped_len() >= 32);
        request.destroy();
    }
}